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. |
Skill Graph context
Classification
- Subject:
frontend-engineering
- Public:
true
- Domain:
design/system
- Scope: Designing and auditing a design system's architecture — token taxonomy, semantic tokens, component APIs, theming, accessibility contracts, documentation, governance, and migration strategy. Portable across any design system; principle-grounded, not repo-bound. Excludes information hierarchy and navigation (information-architecture), page-specific layout (layout-composition), visual craft direction (visual-design-foundations), sentence-level UI copy (microcopy), and accessibility-only audits (a11y).
When to use
- define semantic tokens so charts, status colors, and surfaces do not hardcode raw colors
- audit this component library for API consistency and token drift
- design the theming architecture before adding dark mode
- how should we migrate old CSS variables to canonical design-system tokens?
Not for
- organize pages, nav, sitemap, and wayfinding
- rewrite the empty-state text and tooltip labels
- add aria-labels and keyboard behavior to this component
- draft an architecture note explaining why we chose Postgres over DynamoDB
Related skills
- Verify with:
a11y, code-review, component-architecture
- Related:
component-architecture, layout-composition, visual-design-foundations, interaction-patterns, microcopy, refactor, a11y, information-architecture, semantics
Concept
- Mental model: |
- Purpose: |
- Boundary: |
- Analogy: A design system architecture is to product UI what a building code plus a kit of standardized parts is to construction — it does not draw any single floor plan (the page layout) or pick the paint colors (the visual values); it defines the load-bearing vocabulary (semantic tokens), the certified components and how they connect (component contracts), and the rules every builder must follow (governance), so any team can assemble a sound, consistent building without re-engineering the joists each time.
- Common misconception: |
Keywords
design tokens, semantic tokens, component API, theming, component library, token taxonomy, design system migration, design system audit, component library audit, token drift
1---2name: design-system-architecture3description: 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`). Do NOT use for organize pages, nav, sitemap, and wayfinding. Do NOT use for rewrite the empty-state text and tooltip labels. Do NOT use for add aria-labels and keyboard behavior to this component. Do NOT use for draft an architecture note explaining why we chose Postgres over DynamoDB.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. |5354## Skill Graph context5556<!-- skill-graph-context:start (generated — do not edit by hand) -->5758**Classification**59- Subject: `frontend-engineering`60- Public: `true`61- Domain: `design/system`62- Scope: Designing and auditing a design system's architecture — token taxonomy, semantic tokens, component APIs, theming, accessibility contracts, documentation, governance, and migration strategy. Portable across any design system; principle-grounded, not repo-bound. Excludes information hierarchy and navigation (information-architecture), page-specific layout (layout-composition), visual craft direction (visual-design-foundations), sentence-level UI copy (microcopy), and accessibility-only audits (a11y).6364**When to use**65- define semantic tokens so charts, status colors, and surfaces do not hardcode raw colors66- audit this component library for API consistency and token drift67- design the theming architecture before adding dark mode68- how should we migrate old CSS variables to canonical design-system tokens?6970**Not for**71- organize pages, nav, sitemap, and wayfinding72- rewrite the empty-state text and tooltip labels73- add aria-labels and keyboard behavior to this component74- draft an architecture note explaining why we chose Postgres over DynamoDB7576**Related skills**77- Verify with: `a11y`, `code-review`, `component-architecture`78- Related: `component-architecture`, `layout-composition`, `visual-design-foundations`, `interaction-patterns`, `microcopy`, `refactor`, `a11y`, `information-architecture`, `semantics`7980**Concept**81- Mental model: |82- Purpose: |83- Boundary: |84- Analogy: A design system architecture is to product UI what a building code plus a kit of standardized parts is to construction — it does not draw any single floor plan (the page layout) or pick the paint colors (the visual values); it defines the load-bearing vocabulary (semantic tokens), the certified components and how they connect (component contracts), and the rules every builder must follow (governance), so any team can assemble a sound, consistent building without re-engineering the joists each time.85- Common misconception: |8687**Keywords**88- `design tokens`, `semantic tokens`, `component API`, `theming`, `component library`, `token taxonomy`, `design system migration`, `design system audit`, `component library audit`, `token drift`8990<!-- skill-graph-context:end -->
jacob-balslev