Book a callGitHub1

Concepts01/07

What is a design system?

Updated ยท Edit on GitHub

A design system is the set of rules for how a product looks and behaves. It covers colors, text sizes, spacing, corners, depth, motion and the parts people use, like buttons and form fields. Writing the rules down keeps every screen consistent, even when different people, or different AI chats, build them.

  1. 1
    Color. A palette in steps, plus roles for text, backgrounds, borders and actions.
  2. 2
    Typography. The typefaces, a type scale, and roles: headings, body, label, caption.
  3. 3
    Spacing. Steps on a 4 or 8 px grid for padding and gaps, like this 12 px gap.
  4. 4
    Shape. The corner radius for controls, cards and dialogs.
  5. 5
    Depth. Shadows, borders or tones that set surfaces apart.
  6. 6
    Motion. How long movements take and how they ease, with a reduced-motion mode.
  7. 7
    Components. Buttons, fields, cards and menus, with their states.
  8. 8
    Brand assets. Logo, icons, illustration, photos and voice. People make these.
  9. 9
    Accessibility floors. Minimum contrast, minimum target sizes and a visible focus ring.
The parts of a design system, on one card: a palette in steps and color roles, type roles, spacing from a scale, corners, depth, motion, components, the brand assets only a person makes, and the accessibility floors that stay locked.

Why teams write the rules down

Without written rules, each new screen makes its own small choices. One button gets 8 px corners and the next gets 6 px. A gray is typed in by hand and is a little off from the others. Over time the app looks slightly wrong, and nobody can say why.

Values typed in by hand

One button gets 8 px corners and the next gets 6 px. A gray typed from memory is a step off the others, and nobody can say why.

ButtonButton
.button {
  border-radius: 8px;
}
.button.secondary {
  border-radius: 6px;
  color: #5e6471;
}
.card {
  color: #515762;
}

Named values, used everywhere

Each decision has one name. Change it once and every button and card follows.

ButtonButton
.button,
.button.secondary {
  border-radius:
    var(--ds-radius-control);
}
.button.secondary,
.card {
  color:
    var(--ds-color-text-secondary);
}
Hand-typed values drift: two buttons with different corners and two grays a step apart. A named value is set once and read everywhere, so every use changes together.

A design system fixes this with a short list of agreed values and the reason for each one. Designers use the same values in their design tool. Engineers use them in code. AI coding tools read them before they change a screen.

A copy in every tool

Each tool keeps its own corner value. Each new screen makes its own small choice, and the copies drift apart.

Design tool8 px
Code6 px
A new screen from an AI chat12 px

One source that every tool reads

The agreed value lives in one token file. Designers, engineers and AI coding tools all read the same number.

opendesigner/tokens/
radius.control6 px
DesignersFigma variables6 px
EngineersCSS, Tailwind, Swift, Compose6 px
AI toolsDESIGN.md, read before any change6 px
Copies drift: a design file, the code and a new AI-built screen each end up with their own corner value. One token file, exported to every tool, keeps them the same number.

What goes into a design system

  • Color: a palette in steps of shades, plus roles that say which shade is for text, backgrounds, borders and actions. Light and dark mode each get their own set of choices.
  • Typography: the typefaces, a type scale (the fixed list of text sizes), and roles such as headings h1 to h6, body, label and caption.
  • Spacing: a scale of steps, often on a 4 or 8 pixel grid, used for padding and gaps.
  • Shape: the corner radius for controls, cards and dialogs.
  • Depth: how surfaces stand apart, using shadows, borders or tones.
  • Motion: how long movements take, how they speed up and slow down, and what happens when someone asks for less motion.
  • Components: buttons, fields, cards and menus, with their states, such as hover, focus, pressed, disabled and error.
  • Brand assets: the logo, icons, illustration, photos and voice. People make these. Rules can't.
  • Accessibility floors: minimum contrast, minimum target sizes and a visible focus ring, so more people can read and use the product.

What design tokens are

Design tokens are the rules saved as named values that code and tools can read. For example, color.text.primary might hold a dark gray, and space.4 might hold 16 px.

The Design Tokens Community Group publishes an open format for tokens. Its first stable version, 2025.10, came out on 28 October 2025. One set of tokens can produce CSS variables, a Tailwind theme, Figma variables and native code for iOS and Android. See Design tokens and DTCG.

What a DESIGN.md is

A DESIGN.md is the design system written in plain words, in a file at the root of a project. People read it, and AI coding agents can be told to read it before they change the interface. That way new screens follow the same rules. See Decisions, DESIGN.md and the overview page.

Small app or large company

The idea is the same at any size. The difference is how much you write down.

  • A student project or a small app may only need colors, a type scale, spacing, corners and one button. That is enough to look consistent.
  • A product team adds components, states, dark mode and rules for how to use each part.
  • A design-system team at a large company also decides who can change the system, how changes are announced, how components get versions, and how teams adopt it. The written reasons matter most here, because many people make changes over many years.

How to make a design system with AI

  1. Start from what exists. Read the current CSS, theme files, logo and fonts before deciding anything.
  2. Answer a few big questions first: what you are making, who it is for, where it runs, how it should feel, and the brand color.
  3. Work out the scales with rules. Color ramps that keep contrast, a type scale with a fixed ratio, and spacing steps on a grid. Rules give the same answer every time.
  4. Check accessibility with fixed rules. WCAG 2.2 AA asks for at least 4.5:1 contrast for normal text, and targets of at least 24 by 24 CSS pixels.
  5. Write it down as files: tokens in an open format, CSS and a DESIGN.md, plus a log of every decision and why it was made.
  6. Ask a person for what only a person should make: the logo, illustration, photos and voice.

OpenDesigner follows these steps with the AI tool you already use. It is free and open source, and it is early: no watched user trials have happened yet. See how it works or install it.

Sources