Design Systems Architecture

Design Systems Architecture

A practical guide to building, scaling, and maintaining design systems that serve teams and products long-term.

A design system is more than a component library—it's a shared language, a source of truth, and a scalable architecture for consistent digital experiences. This skill covers the principles, organization, and governance that make systems sustainable.

What Is a Design System?

A design system comprises:

Foundation — Design tokens (colors, typography, spacing, etc.) that define the visual language

Components — Reusable UI building blocks (buttons, cards, modals) paired with guidelines

Patterns — Common interaction and layout patterns (forms, navigation, error handling)

Documentation — Clear guidance on when/how to use each piece

Governance — Decision-making framework, versioning, deprecation policy

Tools — Platforms that host, maintain, and distribute the system (Figma, Storybook, npm, etc.)

---

Design System Principles

1. Atomic Design Methodology

Atomic Design (by Brad Frost) organizes components by complexity:

Atoms (smallest)

• Buttons, labels, inputs, icons
• Standalone; can't be broken down further
• Example: `, , `

Molecules (combination of atoms)

• Form field (label + input + error message)
• Card header (icon + title + subtitle)
• Search box (input + icon + button)
• Example: `, `

Organisms (combination of molecules + atoms)

• Contact form (multiple form fields + button)
• Header (logo + nav + search box)
• Product card (image + title + description + button)
• Example: `, `

Templates (layout + organisms, no content)

• Product listing page layout (header + sidebar + product grid)
• Article template (nav + hero + content + footer)
• Example: ``

Pages (templates + real content)

• Actual product listing page with real products
• Actual article with real text
• Example: ``

When to use: Atomic design is useful for thinking through hierarchy but shouldn't lock you into strict folder structure. Many teams flatten the hierarchy in practice.

2. Component-Based Architecture

Design systems organize around components, not pages. A component is a:

• Self-contained unit with clear inputs (props) and outputs (rendered UI)
• Reusable across different contexts and pages
• Documented with usage guidelines and examples
• Testable with a clear contract (props → output)
• Accessible by default, not as an afterthought

Characteristics of well-designed components:

✅ Single responsibility — One component, one purpose (button activates action; modal confirms decision)

✅ Composable — Can combine with other components without knowing their internals

✅ Predictable — Same props + state = same output every time

✅ Resilient — Handles edge cases (long text, many items, missing data)

✅ Documented — Clear examples, do's and don'ts, accessibility notes

3. Scalability Over Perfection

A design system evolves. Prioritize:

1. Foundation first — Tokens, typography, spacing scales are more important than perfect components
2. Coverage over perfection — Better to have 80% of components working well than 20% perfect
3. Iteration — Version early and often; don't wait for "complete"
4. User feedback — Listen to teams using the system; they know what's missing

---

Design System Organization

Layer Model: Primitives → Semantic → Components

Layer 1: Primitives

• Raw colors (hex values, RGB)
• Raw font families
• Raw spacing increments (8px, 16px, 24px, etc.)
• Raw shadows, borders, border-radius
• Example: color-red-600, font-family-sans, space-4

Layer 2: Semantic

• Colors with meaning (primary, secondary, danger, success)
• Typography scales (display, heading, body, caption)
• Semantic spacing (section-gap, component-gap, element-gap)
• Semantic shadows (sm, md, lg)
• Example: color-primary, typography-body, space-section-large

Layer 3: Components

• Composed semantic tokens into UI elements
• Buttons, cards, forms, modals
• Include styling, structure, and interaction
• Example: `, , `

Why layers matter:

• Maintenance is easier (change one primitive, all semantics and components update)
• Teams speak the same language (everyone understands "primary color")
• Flexibility (different contexts can use different semantics, same primitives)

Folder Structure Example

design-system/
├── tokens/
│   ├── primitives/
│   │   ├── colors.json
│   │   ├── typography.json
│   │   └── spacing.json
│   └── semantic/
│       ├── colors.json
│       ├── typography.json
│       └── spacing.json
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.stories.tsx
│   │   ├── Button.test.tsx
│   │   └── README.md
│   ├── Card/
│   ├── Modal/
│   └── ...
├── patterns/
│   ├── FormField.tsx
│   ├── Layout.tsx
│   └── ...
├── docs/
│   ├── Getting Started.md
│   ├── Design Tokens.md
│   ├── Component API.md
│   └── Contributing.md
└── README.md

---

Design Tokens

Design tokens are the atomic units of a design system—the decisions that power everything else.

Token Categories

Color tokens:

{
  "color": {
    "primary": "#2563eb",
    "primary-hover": "#1d4ed8",
    "success": "#10b981",
    "warning": "#f59e0b",
    "error": "#ef4444"
  }
}

Typography tokens:

{
  "typography": {
    "display": { "size": "32px", "weight": "700", "lineHeight": "1.2" },
    "heading": { "size": "24px", "weight": "600", "lineHeight": "1.3" },
    "body": { "size": "16px", "weight": "400", "lineHeight": "1.5" },
    "caption": { "size": "12px", "weight": "400", "lineHeight": "1.4" }
  }
}

Spacing tokens:

{
  "spacing": {
    "xs": "4px",
    "sm": "8px",
    "md": "16px",
    "lg": "24px",
    "xl": "32px",
    "2xl": "48px"
  }
}

Token Naming Convention

Use a hierarchical structure: category-semantic-variant

✅ color-primary ✅ color-primary-hover ✅ spacing-section-gap ✅ typography-body-large

❌ blue-600 (too specific; doesn't convey meaning) ❌ p1 (too cryptic) ❌ LargeSpacing (inconsistent casing)

DTCG (Design Tokens Community Group) Standard

The W3C-backed DTCG format enables token sharing across tools:

{
  "$schema": "https://tokens.figma.com/schema.json",
  "color": {
    "primary": {
      "$value": "#2563eb",
      "$type": "color",
      "$description": "Primary action color"
    },
    "primary-hover": {
      "$value": "{color.primary}",
      "$type": "color",
      "$description": "Primary hover state (darker)"
    }
  }
}

Benefits: Tools (Figma, Storybook, design token generators) can read this standard format and generate code automatically.

---

Component Documentation

Every component needs clear documentation.

Component README Template

# Button

Primary call-to-action element.

## Usage

```jsx
Click me

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | variant | enum | "primary" | "primary" \| "secondary" \| "ghost" | | size | enum | "md" | "sm" \| "md" \| "lg" | | disabled | boolean | false | Disables button | | onClick | function | — | Click handler | | children | node | — | Button text or content |

Guidelines

✅ Do

• Use primary variant for main actions
• Pair with descriptive text ("Save changes" not "OK")
• Provide loading state for async actions

❌ Don't

• Use as link (use `` or Link component)
• Stack multiple primary buttons
• Remove focus outline

Accessibility

• Has visible focus indicator (outlined, 2px)
• Keyboard accessible (Enter, Space to activate)
• Disabled buttons have reduced opacity (50%), not gray
• No aria-label needed if text is clear

Examples

Primary Button

Save

Secondary Button

Cancel

Disabled State

Disabled

With Loading

Processing...

### What Good Documentation Includes

✅ Purpose — What is this component for?
✅ Usage — Code example (copy-paste ready)
✅ Props — What can be configured?
✅ Guidelines — When to use, when not to use
✅ Accessibility — a11y considerations
✅ Examples — Multiple real-world variants
✅ Changelog — What changed in recent versions

---

## Governance & Versioning

### Semantic Versioning

Use `MAJOR.MINOR.PATCH`:

- **MAJOR** — Breaking changes (e.g., removed prop, changed API)
- **MINOR** — New features, backward compatible
- **PATCH** — Bug fixes, backward compatible

Example: `Button` component moves from `1.2.0` → `2.0.0` if a prop changes.

**Release strategy:**
- Patch releases frequently (as needed)
- Minor releases quarterly (or as features land)
- Major releases annually or when necessary (communicate deprecations 2+ releases ahead)

### Deprecation Policy

Don't remove features abruptly. Follow this pattern:

**v1.5.0** — Deprecate (add warning in console)
```js
console.warn('`size` prop is deprecated in Button v1.5.0. Use `variant` instead.');

v1.6.0–v1.9.0 — Keep deprecated prop, warn (Give teams 2–3 releases to migrate)

v2.0.0 — Remove deprecated prop (Major version bump, documented migration guide)

Breaking Change Policy

Before introducing breaking changes:

1. Deprecate the old API (1–2 releases)
2. Warn teams (in release notes, team meetings, Slack)
3. Document migration path (before/after code examples)
4. Update v1 docs to include deprecation notice
5. Release as major version bump (v1.x → v2.0)

Example breaking change changelog:

## v2.0.0 (2025-01-15)

### Breaking Changes
- **Button**: Removed `color` prop. Use `variant` instead.
  - Before: `Delete`
  - After: `Delete`
- **Modal**: Renamed `isOpen` to `open`. Use `onClose` instead of `onDismiss`.

### Migration Guide
See MIGRATION.md for detailed upgrade instructions.

---

Scaling: Single Brand → Multi-Brand

Phase 1: Single Brand

• One set of tokens (colors, typography, spacing)
• Components inherit brand tokens
• Simpler, but limited

Phase 2: Multi-Brand Tokens

• Multiple token sets (e.g., light-mode, dark-mode, brand-a, brand-b)
• Components use CSS variables or token overrides
• Allows brand variation without duplicating components

Example:

/* theme-light.css */
:root {
  --color-primary: #2563eb;
  --color-success: #10b981;
}

/* theme-dark.css */
:root {
  --color-primary: #60a5fa;
  --color-success: #6ee7b7;
}

Components stay the same; tokens change:

Click me

Phase 3: Multi-Product Architecture

• Shared foundation (core tokens, base components)
• Product-specific layers (custom components, extended tokens)
• Reduces duplication, maintains coherence

Example structure:

design-system-monorepo/
├── @ds/core/              # Shared tokens, base components
│   ├── tokens/
│   ├── Button/
│   └── ...
├── @ds/mobile/            # Mobile-specific extensions
│   ├── tokens/            # Mobile overrides
│   └── MobileMenu/
└── @ds/web/               # Web-specific extensions
    ├── tokens/            # Web overrides
    └── Sidebar/

---

System Health Metrics

Monitor your design system's adoption and health:

Adoption metrics:

• % of components used in products
• % of teams using design system tokens
• Reduction in custom CSS (goal: <10% custom styles)

Quality metrics:

• Component test coverage (goal: ≥80%)
• Accessibility audit pass rate (goal: 100% WCAG AA)
• Documentation completeness (goal: 100% of components)

Velocity metrics:

• Time to add new component (goal: <1 sprint)
• Time to release new version (goal: <2 weeks)
• Upgrade adoption (% of teams on latest version)

Maintenance metrics:

• GitHub issues resolved/month
• Feature requests backlog (prioritize high-impact items)
• Deprecation migration completion (track teams still on old versions)

---

Common Mistakes & How to Fix Them

Too Many Tokens

Problem: 50+ color tokens, teams confused about which to use. Fix: Reduce to semantic tokens (primary, secondary, danger, success). Document use cases for each.

Components Without Documentation

Problem: Team doesn't know how to use Button component; creates 3 duplicate versions. Fix: Every component needs a README. Include examples, props, and dos/don'ts.

No Versioning Strategy

Problem: Breaking changes shipped without warning; teams' builds break. Fix: Implement semantic versioning. Deprecate → warn → remove (over 2+ releases).

Governance Vacuum

Problem: Anyone can add components; no standards. System becomes bloated and inconsistent. Fix: Create contribution guidelines. Require design review, accessibility audit, documentation before merge.

Treating It Like a Repository, Not a System

Problem: Design system is just a code repo; no one thinks about the ecosystem. Fix: Treat it as a product. Have a product owner, roadmap, user research (talk to teams using it), and quarterly reviews.

---

Reference Files & Further Reading

Bundled resources:

• atomic-design-to-code.md — Translating Atomic Design principles into folder structure and components
• component-api-patterns.md — Designing component props, composition patterns, slot-based architecture
• governance-scaling-guide.md — Governance models, versioning strategies, team structure

---

When to Use This Skill

✅ Do use for:

• Design system architecture and organization decisions
• Component structure and naming strategy
• Design token strategy and organization
• Versioning and governance decisions
• Documentation standards and templates
• Scaling strategies (single → multi-brand)
• System health metrics and KPIs
• Deprecation and migration planning
• Atomic Design application

❌ Don't use for:

• Specific tool setup (Figma, Storybook, npm config — see tool-specific skills)
• Component implementation details (CSS, React hooks, framework code)
• Design language decisions (colors, typography — see design-fundamentals)
• Accessibility patterns (see web-accessibility-a11y)
• Performance optimization (see web-performance-optimization)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: plugin87
• Source: plugin87/full-stack-design-skills
• License: MIT

Install and usage instructions live in the source repository linked above.