design-systems-architecture
Skill10 starsChanged 4 months agoMITView on GitHub
Build scalable, maintainable design systems that grow with your product. Use this skill for design system foundations, component architecture, token strategies, governance decisions, scaling patterns, documentation standards, versioning, and cross-team collaboration. Triggers include: design system audits, component library structure, design token organization, system governance questions, scaling decisions, component versioning, breaking changes, documentation strategy, multi-brand support, and system health metrics. Essential for anyone architecting or maintaining a design system serving multiple teams or products.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- phazurlabs/sumitheir own version, first seen Oct 24, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- phazurlabs/sumi★ 58same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- anti-ai-design-patternsSkill
- component-library-masterySkill
- css-styling-pixel-perfectSkill
- deployment-devops-workflowSkill
- design-fundamentalsSkill
- design-to-code-workflowSkill
- design-tokens-systemSkill
- figma-expert-workflowsSkill
- frontend-framework-guideSkill
- inclusive-design-patternsSkill
- qa-testing-visual-regressionSkill
- responsive-universal-designSkill
- web-accessibility-a11ySkill
- web-performance-optimizationSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 44
Search box (input + icon + button)
- Very specific: line 210
Use a hierarchical structure: category-semantic-variant
- Distinctive: line 249
Every component needs clear documentation.
- Distinctive: line 347
Don't remove features abruptly.
- Distinctive: line 362
Before introducing breaking changes:
- Distinctive: line 474
Fix: Every component needs a README.
- Distinctive: line 482
Fix: Create contribution guidelines.
- Distinctive: line 486
Fix: Treat it as a product. Have a product owner, roadmap, user research (talk to teams using it), and quarterly reviews.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.mdDesign 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)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

