Design tokens and shared components
Name repeated design decisions and show how to use them.
Why this matters
Picture your third screen of the day: same button, slightly different blue, slightly different padding — again. A design system ends that drift. It's your reusable decisions and behaviors: tokens name visual roles, building blocks handle common interactions, examples show how they combine here.
Start from real screens. A giant token list won't fix an unclear hierarchy or a missing empty state.
What to understand
A raw value describes how something looks — a hex, a spacing step. A meaningful role describes its job — action background, muted text. When components use roles, they can adapt when the theme changes.
Keep the vocabulary small: a few shared roles for color, type, spacing, shape, and motion, picked for your people, content, density, and platform. Separate the layers — a plain Button knows nothing about invitations, InviteActions combines blocks for your product, layouts own repeated regions — so you extend the right one.
Watch for
- A token list standing in for unclear hierarchy or missing states.
- Hard-coded values bypassing a role that already exists.
- A new variant for one screen instead of a new meaning.
- Two identical-looking controls that behave differently on purpose — or two different values that are accidental drift.
- A second copy of CSS values in prose or hand-maintained JSON no tool reads.
- A confident token name like "accessible-blue" that was never checked as a pair.
Strong default
Name roles before values. Add a token or variant only from demonstrated need — who uses it, which decision it puts in one place. Show one ordinary example and one hard one: very long content, no access, still saving.
When this doesn't apply
A fixed type ratio or spacing base is a starting habit, not a law. One measured pixel in isolation doesn't automatically deserve a token. Don't add settings or roles for imaginary future users — find the consumer first.
In practice
Ask your agent: "does this style use a role, or a hard-coded value?"
:root {
--surface: #ffffff;
--text: #172033;
--action: #214fc6;
--action-text: #ffffff;
}
.primary-action {
color: var(--action-text);
background: var(--action);
}A small sketch, not a full palette. Always check real pairs, states, and supported themes. A token name doesn't make its contrast pass.
| Decision | Useful shared roles |
|---|---|
| Color | Page, surface, text, muted text, action, focus, status pairs. |
| Type | Page title, section heading, body, label, small metadata, code. |
| Spacing | Repeated inner, group, and section gaps. |
| Shape and depth | A few radii and elevations tied to layering. |
| Motion | Repeated feedback and transitions, with a reduced-motion option. |
Raw values live at the source. When a shared change touches several screens, open those screens and look — the evidence decides whether it's drift or an intentional exception. Write down where tokens live, how to import components, the variants that matter, and the rule for adding or changing them.
Verify
Real pairs on real surfaces, in every supported theme and state. Open every screen a shared change touches. Hard content — long names, empty, saving — surfaces missing roles faster than any checklist.
Related skills
Use $tokens for a foundation or extension and $system to revisit shared decisions. Continue with theming, component architecture, and AI-ready systems.
Last updated on