design-system-builder
Build cohesive, scalable design systems with design tokens, component libraries, documentation, and governance. Use when creating company-wide design systems, style guides, or component libraries for
SKILL.mdplugins/loxihart-design/skills/design-system-builder/SKILL.md
GitHub<essential_principles>
1. Tokens → Components → Docs → Governance
Every design system follows this build order. Tokens are the foundation — components consume tokens — docs make components discoverable — governance keeps it alive. Skipping steps creates tech debt.
2. Accessible by Default
WCAG 2.2 AA minimum. Keyboard navigation, screen reader support, focus management, and color contrast are non-negotiable in every component. Not bolted on later.
3. API Consistency Across Components
All components share the same prop conventions: variant, size, disabled, className escape hatch, ...rest spread. Consumers learn one pattern and apply it everywhere.
4. Tree-Shakeable from Day One
Use sideEffects: false, per-component exports, and zero-runtime CSS (Tailwind + CVA recommended). Target under 100KB gzipped for the entire system.
5. Design-Engineering Parity
Tokens in code must match Figma tokens exactly. Style Dictionary transforms a single source of truth into platform-specific outputs (CSS, iOS, Android). No manual syncing.
</essential_principles> <intake>Identify starting point from the user's request:
| User Says | Route To |
|---|---|
| "New design system" / "start from scratch" / "set up our system" | workflows/new-system.md |
| "Add a component" / "build a button/card/modal" / "component API" | workflows/add-component.md |
| "Document our system" / "Storybook" / "component docs" | workflows/document-system.md |
| "Design tokens" / "token architecture" / "Style Dictionary" | references/token-architecture.md |
| "CVA" / "component patterns" / "testing components" / "bundle size" | references/component-patterns.md |
| "Governance" / "contribution workflow" / "versioning" / "release" | references/governance.md |
| "What tech stack?" / "Tailwind vs Styled Components" | references/tech-stack-comparison.md |
If ambiguous, ask: "Are you starting a new design system, adding components to an existing one, or documenting what you already have?"
</intake> <routing>| Workflow | Purpose | When to Read |
|---|---|---|
workflows/new-system.md |
Full setup: charter → tokens → structure → first components | Starting from zero |
workflows/add-component.md |
Design API → implement → test → document a single component | Adding to existing system |
workflows/document-system.md |
Storybook, component docs, getting-started guides | System exists, needs docs |
| Reference | Purpose | When to Read |
|---|---|---|
references/token-architecture.md |
3-tier token system, JSON format, Style Dictionary config | Setting up or modifying tokens |
references/component-patterns.md |
CVA variants, file structure, testing strategy, bundle optimization | Building or reviewing components |
references/governance.md |
Contribution flow, versioning, release automation, quality gates | Establishing team processes |
references/tech-stack-comparison.md |
CSS/JS framework tradeoffs (Tailwind+CVA, Styled Components, CSS Modules, Vanilla Extract) | Choosing or evaluating tech stack |
| Script | Purpose | When to Run |
|---|---|---|
scripts/build-tokens.js |
Transform token JSON into CSS/JS/iOS/Android outputs via Style Dictionary | After creating or modifying token files |
scripts/generate-component.js |
Scaffold a new component with implementation, tests, stories, and barrel export | Adding a new component to the library |
| Asset | Purpose | When to Use |
|---|---|---|
assets/starter-tokens.json |
Complete starter token file with colors, spacing, typography, shadows, radii | Bootstrapping a new token system |
assets/style-dictionary.config.json |
Ready-to-use Style Dictionary config for CSS + JS output | Setting up token build pipeline |
assets/storybook-theme.js |
Branded Storybook theme matching design system tokens | Configuring Storybook appearance |
After reading the relevant workflow/reference, follow it exactly.
</routing> <quick_reference>Recommended stack: Tailwind + CVA (class-variance-authority) for new systems
Component file pattern:
ComponentName/
├── ComponentName.tsx (implementation)
├── ComponentName.test.tsx (tests)
├── ComponentName.stories.tsx (Storybook)
└── index.ts (barrel export)
Atomic design hierarchy:
primitives/— atoms (Button, Input, Text, Icon)components/— molecules (Card, FormField, SearchInput)patterns/— organisms (Navigation, Modal, DataTable)layouts/— templates (AppShell, Dashboard)
Token tiers:
- Tier 1: Primitive (raw values —
blue-500: #3b82f6orblue-500: oklch(60% 0.19 261)) - Tier 2: Semantic (contextual —
color-primary: {blue-500}) - Tier 3: Component (specific —
button-bg: {color-primary})
Color space note: Define primitive tokens in OKLCH for new systems — perceptually uniform lightness produces consistent palette steps and smooth gradients. Keep hex fallbacks for browser compatibility. Existing locked brand profiles (FlashFusion v3, Loxihart) stay in hex — OKLCH is for new token authoring only.
Quality gates for v1.0:
- 20+ components documented
- WCAG 2.2 AA accessibility audited
- 80%+ test coverage
- Bundle size under 100KB gzipped
- Storybook deployed to public URL
- 2+ consuming products using the system
- Visual regression baseline established (
npx vizzly tddor Chromatic)
CLAIMS
- [SOURCED] Three-tier token architecture (primitive → semantic → component) is the industry standard approach — documented in Style Dictionary, Theo, and Figma Variables
- [GENERATED]
sideEffects: falsein package.json is required for tree-shaking to work in webpack/Rollup — without it, all components are included even if only one is imported - [GENERATED] CVA (class-variance-authority) over hand-rolled variant strings because it provides TypeScript inference on variant props at zero runtime cost beyond Tailwind itself
GAPS / BLINDSPOTS / UNKNOWN-UNKNOWNS
- RSC (React Server Components) compatibility is a growing constraint on component library architecture — client/server component boundaries affect which hooks are safe
- CSS-only component approaches (no JS) are not covered — valid for static sites and performance-critical contexts
- Design system governance tooling (Chromatic, Zeroheight, Supernova) is mentioned but not evaluated