# Design System Builder

> Build your design system step by step, then export design.md, design tokens, CSS and Tailwind. Free, with no account: it runs in the browser.

People build a design system in steps (Brand, Style, Color, Typography, Spacing, Radius & borders, Layout, Icons, Elevation, Motion, Components), with a live preview, then export it. Every export comes from the same choices, so they always match:

- design.md: rules, design tokens and component specs in Markdown, written for AI coding agents. Follow its numbered rules and use only the token names it lists.
- tokens.json: W3C Design Tokens (DTCG 2025.10).
- CSS custom properties with light and dark themes, and a Tailwind CSS v4 theme.
- config.json: the raw choices, which the builder can open again.

## Apply a design system to a codebase

Systems are saved in the person's browser, not on this server, so there is no API or account to look them up by, and you can't use the builder for them. Work from what they give you.

1. **Get the system.** Ask for a link for AI tools, which they copy from the builder's Export step. It looks like `https://designsystems.page/design.md?s=…`, and fetching it returns their design.md as Markdown. A share link (`https://designsystems.page/builder#share=…`) won't work: the system is after the `#`, which browsers never send to a server, so fetching it returns the empty builder. If they have a design.md file instead, read that.
2. **Save design.md in the repo**, at the root or in `docs/`, and point to it from the project's agent instructions (AGENTS.md, CLAUDE.md, `.cursor/rules` or `.github/copilot-instructions.md`), so later sessions follow it too.
3. **Read its rules first.** design.md opens with numbered rules. Follow them, and use only the token names it lists. Don't invent colors, sizes or spacing that aren't in it.
4. **Add the tokens to the code.** Fetch the same link with `&format=` added and save the result in the project. It matches design.md exactly, so don't retype values from it. Pick the one that fits the project:
   - `&format=css`: CSS custom properties with the light and dark themes, plus `.text-*` typography classes. Import it once, globally.
   - `&format=tailwind`: a Tailwind CSS v4 theme. It replaces Tailwind's default palette, so only on-system classes exist.
   - `&format=tokens`: W3C Design Tokens (DTCG) JSON, for Style Dictionary or other token tools.
5. **Replace hard-coded values with tokens**, one component or page at a time: colors, type, spacing, radius and shadows. Put text on a color only in the pairings design.md lists; each one is contrast-checked.
6. **Check the result.** If design.md has light and dark themes, check both. Every interactive element needs its hover, pressed, focus-visible and disabled states.
7. **When the system changes, ask for a new link.** A link is a snapshot from when it was copied, and doesn't update.

If the person has no design system yet, send them to https://designsystems.page/builder. It's free, needs no account, and takes a few minutes; the Export step then gives them the link for AI tools.

A link for AI tools packs the system into the address itself; nothing is stored on the server.

These steps are also an Agent Skill: [skill.md](https://designsystems.page/skill.md). Save it in your skills folder (for example `.claude/skills/design-system-builder/SKILL.md`) to use it in later sessions.

## Example

- [Harbor design.md](https://designsystems.page/design.md?s=rZfNbts4EIBfxZi90oYsK4qjW7HAbntt0d1D4AMljiTCFCmQVBxv4HdfDGk5cpNGCdqTaZKab_5IzjyBq1rs-D9onTQaijWDDj2H4gk07xAK-MxtaSwwEOgqK3sf9sGfXHVs0VuspMMF12Lh7eD8wVjfHleLT4veGjFUfvH9y6I2dtGj6RUuDq1ZdFzzBhed0XgMX5oeLSe5bgUMHkZdYL1KVgkwGHrBPYpPHgpIkzRfrpNlcgsnBrUZtIifksqVUcbSgFcVak8jhyiggD-yOsvxhr5xWBktuD1OlxNxl223tKxx8Jar6WKe3WbbEhh4SULBDaVXSJt746SXDzjdvc75JuNRVMN_XBVVmqc5rR641VI308X65g6Tkhalrs10Jb3JNxhWOiPQQXEPSjatp7hwu4fdiYE_9qaxvG-DZbXRPjilt7I7W1vzTqojFPBFe6SYOjPYiqLcGNMoBAYHJLEEyJKE3SQJy5Nkx6DmSpW82hPZHZ3HbjlIksC1Wzq0sg46XDn3gvvW8woXf1vj0e1nsB_CdUYbKPSg1IlByR1-k_8hFOucgau4wq-UG1CsV-kNg96iwxA_z0lHQfL8UQV3XvJdSNcrflyqBhhYoyZzwIJXScLFTAYuIPOEgZIaPwdDCLkeraJFWkXv0ZIrQtSXySpJT-wFtxMf4mbb38R13ce4v2pvi1xI3Vz5-Tz3FneT_sil0M6B16-Ap45-BzjNfhd46un3gF94eg6cTKClEde5TBPPuPFyGGHrF-k0YWXvYU3dOsPKf5U19eQM60X0PsBSvER15cQw8xHLpiG7eRdu6sc53Jup-T7c1JVzuDeP4Ks4OgjheRhnnsJt_V1Lcv_5sqbZzaODImWQ0m_GgH62DFwXsZ04O7eJB_JRxRshpQFdhRsa5BmDjAZ3-enEwHIhBzcyo7yRp41GKJIISiMoi5xtxBCWZBE2YIhbD4rE393dEaA0VmCoOw5S-JYGAms-KB8KKuetIZvTULBUg_t6dsF5d8rA1HV4mlISp_jRDKF4KS3yfW_k-SUn5XK6eEm923xUMBk9sU63yYlBY6V4tjZURUOnoz-bgQITrem4bSTVfPkpipxs3b6-dUM2qOZqKzlo3EuajHuzhIzp-OO_0cx1mpB2sqLa7gmULG2oE0ANlRQ4PsZQgBk85RdE1-1xFLC6vYk5ePFG0E2c78iQE8REhQ881qlPF6Gu5cIcgEorj9pJf7yq5DozflAjqusiQQz2Iq7mjqJKSa6N7ahQTOmPU-YAxSaYiNyNhd0opLhPVilLWMLWOwYYyq_iPnmeeaSTcJ-sNjTB1rsTGVKZrjcax_C3vCdLLBW9SIpVRntr1HgQo08253OSnX2SbSlFB--jAah5qaio9HZABg_cSh4A99ODPnmFnqPRtMb52Al4O1ShtN1dInIP4Q4J95ZqYkWKj_4viUq8Dd69GvqfSnWosPIzIimkqId5cMeV-lZZROo4hDW9MAcd-gTNq33J7ayI2ASEjqU03ptuWcUAh5pUa5wREYv9STPx3BtMeohY7orYmbypT7hWLkckPG4hH7bnhMjjySy5aHBGM2eUDGVyPCc7FlussDY2Smzstq7TZmLNxYapYcHoHQNhfCRTvrdY7UvzOB9butPN_DZ3kL5q5_d5XroZV9CZs2NuYtNRiEWIStXKfubjWqrYcFWtkRUF83T6Hw): a sample system for a finance product, as a link for AI tools

## Guides

- [What is design.md? A design system guide for AI coding tools](https://designsystems.page/guides/design-md): design.md tells AI coding tools like Cursor, Claude Code and Copilot how to use your colors, type, spacing and components. See what goes in one, and make yours free.

## Optional

- [Home page](https://designsystems.page/): what the builder does and who it's for.
- [The builder](https://designsystems.page/builder): the app itself. Its pages are rendered in the browser, so there is little to read without running it.

Last updated 2026-10-22.