Design System Architecture
Concept of the skill
A design system architecture is the discipline of turning recurring UI decisions into a governed, layered vocabulary so that building a screen becomes composition from durable parts rather than a fresh round of local choices. It has three layers and a rule layer. Raw tokens hold the literal brand values — a palette, a spacing ramp, a type scale. Semantic tokens name product meaning (surface, danger, primary-action, text-muted) and point at raw tokens, so the meaning of a token is stable while the value behind it can change per theme. Component contracts define each reusable piece — its purpose, props and slots, states, accessibility behavior, and composition rules — and consume only semantic tokens, never raw values. Over all three sits governance: forbidden local overrides, deprecation and migration paths, documentation that shows expected use and anti-use, and drift detection between code and design intent. The architecture's job is to encode decisions once and make them reusable and enforceable, so that color, spacing, state, theming, and accessibility are answered by the system instead of re-decided on every screen — and a theme change or token rename propagates through the semantic layer without rewriting components.
Coverage
Design and audit reusable UI systems. Covers token taxonomy, semantic vs raw tokens, component APIs, variants, slots, theming, accessibility contracts, responsive behavior, documentation, governance, migration, and drift detection between code and design intent.
Philosophy of the skill
A design system is a product architecture layer, not a style pile. Tokens and components should encode durable decisions so product work becomes faster and more consistent. If every screen still makes local choices for color, spacing, state, and behavior, the design system is only decorative.
Optimize for clear constraints. A system with too many escape hatches is not flexible; it is ungoverned.
Method
- Inventory tokens, components, variants, and usage hotspots.
- Separate raw tokens from semantic tokens.
- Define component contracts: purpose, props/slots, states, accessibility, and composition rules.
- Establish theming and density rules before multiplying variants.
- Mark forbidden local overrides and migration paths.
- Add docs examples that show expected use and anti-use.
- Verify real screens can be built without one-off styling.
Verification
Do NOT Use When
| Use instead |
When |
information-architecture |
You need page hierarchy, navigation, sitemap, or wayfinding. |
microcopy |
You need UI wording, labels, empty states, or error copy. |
a11y |
You need focused accessibility compliance verification. |
layout-composition |
You need page-specific responsive structure, section order, or breakpoints. |
visual-design-foundations |
You need color, typography, spacing, density, or visual craft direction. |
interaction-patterns |
You need to choose a control or interaction pattern before systemizing it. |
refactor |
You are only restructuring existing code without changing design-system contracts. |
1---2name: design-system-architecture-23description: Use when designing or auditing a design system's architecture: token taxonomy, semantic tokens, component APIs, theming, accessibility contracts, documentation, governance, and migration strategy. Do NOT use for information hierarchy and navigation (use `information-architecture`), page-specific layout (use `layout-composition`), visual craft direction (use `visual-design-foundations`), sentence-level UI copy (use `microcopy`), or accessibility-only audits (use `a11y`).4license: MIT5---6# Design System Architecture78## Concept of the skill910A design system architecture is the discipline of turning recurring UI decisions into a governed, layered vocabulary so that building a screen becomes composition from durable parts rather than a fresh round of local choices. It has three layers and a rule layer. **Raw tokens** hold the literal brand values — a palette, a spacing ramp, a type scale. **Semantic tokens** name product meaning (surface, danger, primary-action, text-muted) and point at raw tokens, so the meaning of a token is stable while the value behind it can change per theme. **Component contracts** define each reusable piece — its purpose, props and slots, states, accessibility behavior, and composition rules — and consume only semantic tokens, never raw values. Over all three sits **governance**: forbidden local overrides, deprecation and migration paths, documentation that shows expected use and anti-use, and drift detection between code and design intent. The architecture's job is to encode decisions once and make them reusable and enforceable, so that color, spacing, state, theming, and accessibility are answered by the system instead of re-decided on every screen — and a theme change or token rename propagates through the semantic layer without rewriting components.1112## Coverage1314Design and audit reusable UI systems. Covers token taxonomy, semantic vs raw tokens, component APIs, variants, slots, theming, accessibility contracts, responsive behavior, documentation, governance, migration, and drift detection between code and design intent.1516## Philosophy of the skill1718A design system is a product architecture layer, not a style pile. Tokens and components should encode durable decisions so product work becomes faster and more consistent. If every screen still makes local choices for color, spacing, state, and behavior, the design system is only decorative.1920Optimize for clear constraints. A system with too many escape hatches is not flexible; it is ungoverned.2122## Method23241. Inventory tokens, components, variants, and usage hotspots.252. Separate raw tokens from semantic tokens.263. Define component contracts: purpose, props/slots, states, accessibility, and composition rules.274. Establish theming and density rules before multiplying variants.285. Mark forbidden local overrides and migration paths.296. Add docs examples that show expected use and anti-use.307. Verify real screens can be built without one-off styling.3132## Verification3334- [ ] Semantic tokens cover product meaning without leaking palette names35- [ ] Components have clear ownership and API boundaries36- [ ] Variants map to real use cases, not visual guesses37- [ ] Accessibility behavior is part of the component contract38- [ ] Theming does not require component-level rewrites39- [ ] Deprecated tokens or components have migration paths40- [ ] Real product screens can use the system without local escape hatches4142## Do NOT Use When4344| Use instead | When |45|---|---|46| `information-architecture` | You need page hierarchy, navigation, sitemap, or wayfinding. |47| `microcopy` | You need UI wording, labels, empty states, or error copy. |48| `a11y` | You need focused accessibility compliance verification. |49| `layout-composition` | You need page-specific responsive structure, section order, or breakpoints. |50| `visual-design-foundations` | You need color, typography, spacing, density, or visual craft direction. |51| `interaction-patterns` | You need to choose a control or interaction pattern before systemizing it. |52| `refactor` | You are only restructuring existing code without changing design-system contracts. |
jacob-balslev