Cheatsheet — Design Systems
Atomic Design Stage Decision Table
| Stage | Question to ask | Example |
|---|
| Atom | Can this be broken down further without losing function? If no → atom. | Button, input, color token |
| Molecule | Is this a small group of atoms with exactly one clear purpose? | Labeled search input |
| Organism | Is this a distinct, complex interface section (may repeat a molecule)? | Header, product grid |
| Template | Is this a full-page layout with placeholder content? | Article page skeleton |
| Page | Is this a template populated with real, representative content? | The actual article page |
If a component's job needs "and" to describe ("shows X and lets user edit Y"), it's probably not a molecule — split it or promote it to organism.
Token Layer Decision Rule
| Situation | Use |
|---|
| Defining a raw brand value | Primitive token (blue-500) |
| Referencing a value from inside a component | Semantic token (color.action.primary) |
| Need per-theme values (light/dark, multi-brand) | Semantic token that re-points per theme; primitives stay theme-agnostic |
Never reference a primitive token directly from component code — always go through the semantic layer.
Component API Prop Vocabulary (adopt one, don't mix)
| Concern | Common prop name | Values |
|---|
| Visual style | variant | primary / secondary / ghost / outline |
| Size | size | sm / md / lg |
| Semantic intent/color | tone or color | neutral / danger / warning / success |
| State control | value + onChange (controlled) or defaultValue (uncontrolled) | — |
Governance Model Trade-offs
| Model | Best for | Risk |
|---|
| Centralized (one core team owns everything) | Small orgs, early-stage systems | Bottleneck as org grows |
| Federated (feature teams contribute under review) | Large orgs with many product teams | Quality drift without strong review criteria |
| Hybrid (core owns primitives, teams own product patterns) | Most mid-to-large orgs | Requires clear ownership boundary to avoid overlap disputes |
Versioning Quick Rules
- Patch: bug fix, no API/visual contract change.
- Minor: new prop/component, backward compatible.
- Major: breaking prop rename/removal, or a visual change that breaks a consumer's layout assumptions.
- Always pair a deprecation with a concrete removal version — never leave it open-ended.
Accessibility Testing Layers (do all three, in this order)
- Automated (axe-core / Storybook a11y addon) — fast, catches a meaningful but partial subset (contrast, missing labels, invalid ARIA).
- Keyboard-only pass — tab through every interactive flow with no mouse; check focus order and visibility.
- Screen reader pass (VoiceOver/NVDA/JAWS) — the only layer that validates actual usability for assistive-technology users.
When to Reach for This Skill vs. an Implementation Skill
| Question | Skill |
|---|
| "How should I structure/name/govern my design system?" | design-systems (this skill) |
| "What props does Radix Dialog accept?" | radix-primitives-docs |
| "What props does Base UI Dialog accept?" | base-ui-docs |
| "How do I style with Tailwind utility classes?" | tailwind-docs |
| "What pre-styled shadcn components exist?" | shadcn-ui-docs |