# How do you start a design system that coding agents will keep to?

Source: https://saer.app/guides/start-a-design-system-for-coding-agents
Updated: 2026-11-12

**Short answer.** Start small and make it real code. Choose a colour scale, type, shape and density, check every text pair for contrast in light and dark, and write the result into the project as tokens and a handful of components. Then tell your agents the system exists, in the files they already read, and check each pull request for raw values and hand-built UI. A system that only lives in a design file or a document is one an agent cannot see.

## Decide the few things that matter

- Colour: a scale per hue, with semantic roles (background, surface, text, border, primary, accent) for light and dark.
- Type: a heading and a body font and a modular scale.
- Shape and density: radius, elevation and how roomy controls are.
- Components: the handful every screen needs, such as a button, an input, a card and tabs.

Check contrast while you choose, not afterwards: the text on a solid colour, muted text and primary-coloured text should each read at 4.5:1 or better in both themes.

## Put it where agents look

Agents read your code, not your design file. Write the tokens into the stylesheet your framework uses (Tailwind v4 `@theme`, shadcn/ui variables or plain custom properties), keep the components in the repository, and add a short section to `AGENTS.md` or `CLAUDE.md` that says the system exists and how to check against it.

Write the system into a project, then connect your agents:

```
$ saer create --from saer-system.json
$ saer init
```

## Check every change

Once the system is in the code, Saer treats it like any other: a raw value equal to a token is exact drift, and hand-built UI where the component exists is flagged on the pull request. See [CI checks](https://saer.app/docs/ci).

## What Saer does about this today

- [Saer Create](https://saer.app/create) (in the beta): colour in OKLCH, semantic tokens for light and dark with every text pair checked to WCAG AA, type, shape, density and seven components, with exports for Tailwind v4, shadcn/ui, CSS and W3C design tokens.
- `saer create` (in the beta) writes that system into a project, asking before it changes a file you already have; `saer init` connects your agents.

## Not built yet

- Starting from an existing website or codebase: planned.
- Generated Storybook stories for the components: planned.
