Design-system schema

A design system is a folder of CSS, tokens and previews under .design/system/<name>/. The schema is the short list of names every system agrees on. Because a canvas asks for --accent, --bg-1 or .btn and every system answers to those names, the canvas can move from one system to another without anyone mapping tokens by hand.

The schema checks structure only: that a name exists, that it has the right kind of value, that colours exist in both themes. It never judges how a value looks. A system with an unusual palette is still a valid system.

Three tiers

A canvas may also declare --c-* for colours that belong to that canvas alone.

Core roles

An asterisk marks a colour role, which must exist in every theme the system declares. A system that declares Light and Dark defines each asterisked name in both. A theme block counts when it is a top-level rule, a rule in a layer, a :root rule (for the default theme) or a light-dark() value (for both).

The three presence names count only when the system turns the presence family on. The first 68 names come from the original design-system contract; the other 27 (the functional roles such as --accent-on-soft, --status-*-text, --focus-ring, --scrim) were added so that components do not need a private colour for every state.

Value types

Each role has a type, and the checker tests the form of the value, not the value itself.

A --focus-ring written as a box-shadow, for example, is a type error.

Slots

Slots are optional families. They matter at switch time: a canvas that uses --palette-4 keeps working on a system with only two palette entries, because the switch writes a pairing for the missing indexes.

"Handed to AI" means the switch's restyle pass sees the canvas's use of that slot and decides; nothing is invented silently.

Own names

Any other custom property that is neither core, a slot nor --x-* is reported as unprefixed-own. It still works; it is simply not portable, and a switch cannot know what it means.

Aliases and collisions

Many systems predate the schema and use their own spellings, for example --w-semibold for --weight-semibold, --accent-muted for --accent-soft or --ease-spring for --ease-signature-1. The registry carries 69 aliases. An alias is accepted, flagged, and fixed mechanically: the system declares the schema name and keeps the old name as var(--schema-name).

A collision is a name that exists but means something else. The checker finds the ones it can by form:

and notes the ones only a person can judge (--status-*-fg as text colour, --bg-4 as pressed or elevated, --space-N as multiples of 4px, an overshoot --ease-out). Judgement collisions never change a level; they go to the Bring-up step as notes.

Components

A system ships components.json (schema version 1) next to its CSS. It names the component classes, their variants and sizes, the type-role classes, the icon map and any slots or ext.* components. The class contract is what lets a canvas write <Button variant="secondary"> and have any conformant system draw it.

Core components have variants and sizes: Button has primary secondary ghost danger and sm lg; Badge has success warn error info accent; Card has raised interactive flat; Callout has info success warn error. A variant a system lacks is written as null with a fallback naming the variant drawn instead.

State selectors are fixed: :hover, :active, :focus-visible, :disabled, [aria-pressed="true"], [aria-busy="true"], [aria-invalid="true"], [aria-checked="true"] or :checked, :indeterminate, [aria-selected="true"], [open] and [data-side].

Type roles. Eleven classes carry text styles, and ten are required: t-title, t-heading, t-subheading, t-body, t-body-sm, t-caption, t-label, t-eyebrow, t-code, t-num. t-display-N follows the display slot.

Icons. Forty names make up the shared vocabulary: home, search, add, close, check, chevron-up, chevron-down, chevron-left, chevron-right, arrow-up, arrow-down, arrow-left, arrow-right, more, settings, user, users, bell, share, link, trash, edit, copy, download, upload, lock, info, warning, error, success, star, heart, calendar, clock, image, file, folder, play, pause, external. The system’s icon map says which of its own icons answers each name.

Scope and themes. A system's tokens live under the scope class ds (or the system's own root class), and the theme is the data-theme attribute on a wrapper. Canvases use the <DSRoot> wrapper instead of writing either by hand.

Levels and exit codes

maude design ds-check <name> gives a system one of three levels.

Reasons behind the level (an excerpt):

Other exit codes: 12 when canvas mode finds a blocking finding, 13 when a write flag is refused and nothing is written, 1 for an error and 2 for a usage mistake. A single-theme system is never colour-inverted for you: that would be a visual guess, so it is reported and left alone.

Fallbacks

A level below Conformant does not break a canvas. For each system, Maude injects only the roles and classes that system never declares, in a CSS layer (@layer maude.fallback) placed before the tokens. The layer is the lowest in the cascade, so it can never shadow a value the system sets. Colours in it derive from the system's own tokens (--accent-on-soft falls back to --accent-text), weights are numeric, tracking is 0, and nothing adds a look the system did not have.

What a canvas is checked for

maude design ds-check <name> --canvases runs nine rules on each canvas's .tsx and the stylesheets it imports.

Each canvas lands in one of four states, first match wins:

Pins are computed on every run; only dsPinned is stored.

Commands

maude design ds-check <name>                    # a system's level; read-only
maude design ds-check --all --json              # every system, machine-readable
maude design ds-check <name> --canvases         # plus every canvas's state and findings
maude design ds-check <name> --emit             # (re)write system/<name>/tokens.json from the CSS
maude design ds-check --canvas "ui/home.tsx" --fix=mechanical --dry-run
maude design ds-check --cheatsheet <name>       # the role cheat-sheet the AI gets
maude design ds-upgrade <name> --analyse        # start Bring-up (never writes the system)

ds-check runs without a prompt in Claude Code: without a write flag it is read-only, and --emit and --fix only write inside the project. In a project shared through a team server, --emit and --fix ask first when the chat has read a file that someone who can see the target canvas is not allowed to see. Autofix is limited to three byte-minimal changes on canvases: an alias becomes its schema name, a system's own CSS import is removed, and a hand-written wrapper becomes ds. System files change only through Bring-up.

Related

• Multi-DS: several systems in one project and per-canvas attribution.
• Bootstrap: creating a system with /design:setup-ds.
• /design:system: opening a system's canvas.