plugin87 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:
<button>,<label>,<input />
Molecules (combination of atoms)
- Form field (label + input + error message)
- Card header (icon + title + subtitle)
- Search box (input + icon + button)
- Example:
<FormField>,<CardHeader>
Organisms (combination of molecules + atoms)
- Contact form (multiple form fields + button)
- Header (logo + nav + search box)
- Product card (image + title + description + button)
- Example:
<ContactForm>,<Header>
Templates (layout + organisms, no content)
- Product listing page layout (header + sidebar + product grid)
- Article template (nav + hero + content + footer)
- Example:
<ProductListingTemplate>
Pages (templates + real content)
- Actual product listing page with real products
- Actual article with real text
- Example:
<ProductListingPage>
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:
- Foundation first — Tokens, typography, spacing scales are more important than perfect components
- Coverage over perfection — Better to have 80% of components working well than 20% perfect
- Iteration — Version early and often; don't wait for "complete"
- 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:
<Button>,<Card>,<Modal>
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
<Button variant="primary">Click me</Button>
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
<a>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
<Button variant="primary">Save</Button>
Secondary Button
<Button variant="secondary">Cancel</Button>
Disabled State
<Button disabled>Disabled</Button>
With Loading
<Button loading>Processing...</Button>
### 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:
- Deprecate the old API (1–2 releases)
- Warn teams (in release notes, team meetings, Slack)
- Document migration path (before/after code examples)
- Update v1 docs to include deprecation notice
- 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: `<Button color="red">Delete</Button>`
- After: `<Button variant="danger">Delete</Button>`
- **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:
<button style={{ color: 'var(--color-primary)' }}>Click me</button>
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)