Design System Agent Skill

Design system

A design system is a set of constraints that makes consistency the cheap path. If the system is

harder to follow than to ignore, it will be ignored.

Tokens first

Define the primitives before any component. Every visual decision references a token; nothing

hard-codes a value.

• Color — semantic names, not literal ones. surface, surface-raised, text-primary,

text-muted, border, accent, danger. A token named blue-500 cannot be re-themed.

• Type — a scale with a stated ratio, and a line-height per step. Four to six steps. More than

that and nobody can tell them apart.

• Spacing — one scale, geometric, used for every gap and inset. Arbitrary spacing is the single

most common source of "it looks off but I can't say why."

• Radius, elevation, motion — small closed sets. Two or three each.

Every token needs a light and dark value defined together. Adding dark mode later means auditing

every surface.

Component contracts

A component in the system carries: the states it supports (default, hover, focus, active, disabled,

loading, error, empty), the props that vary it, and what it will *not* do. The last one matters

most — a component that accepts arbitrary overrides is a styling function, not a component.

Every interactive component needs a visible focus state and a target big enough to hit. This is not

a polish item; it is whether people can use it.

Growth rules

• A new component enters the system only after the same need appears three times. Before that it is

local.

• Changing a token is a system-wide change — treat it like an API change, because it is.
• Never remove a token or component because it looks unused. You cannot see every consumer from

inside the system. Deprecate, announce, then remove.

Return contract

Report tokens added or changed, components affected, anything now inconsistent with the system, and

what needs migrating.