# Designsystem

> Design system architecture. design tokens, theme systems, Figma to code, component API, Storybook, light/dark, versioning.

- Skill: `arbazkhan971/designsystem` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arbazkhan971/designsystem`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arbazkhan971/designsystem/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: arbazkhan971 (https://skillmd.com/u/arbazkhan971)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arbazkhan971/designsystem

---


# Design System — Design System Architecture

## Activate When
- User invokes `/godmode:designsystem`
- User says "design system," "design tokens," "theme architecture," "Figma to code"
- Creating a shared component library or establishing token architecture
- Building theme support (light/dark, multi-brand) or Figma-to-code pipeline
- Versioning/distributing a design system package or auditing for consistency

## Workflow

### Step 1: Assess Current State
```
DESIGN SYSTEM ASSESSMENT:
Project: <name>  Framework: <React/Vue/Angular/Svelte/Web Components>
Existing system: <none/partial/mature>
Token coverage: Colors/Spacing/Typography/Shadows/Borders/Motion — <defined/partial/none> each
Theme support: <none/light-dark/multi-brand>
Component count: <N>  Storybook: <yes/no>  Figma integration: <yes/no>
Maturity: NONE | STARTER | GROWING | MATURE
```

### Step 2: Token Architecture
Three-tier architecture is mandatory:

```
TIER 1: PRIMITIVES (raw values)      --primitive-blue-500: #3b82f6;
TIER 2: SEMANTIC (meaning)           --color-primary: var(--primitive-blue-500);
TIER 3: COMPONENT (specific)         --button-bg: var(--color-primary);
```

**Colors:** Neutral scale (50-950), brand scale, feedback (red/green/amber). Semantic: bg, surface, text-primary/secondary/tertiary, primary/hover/active, error/success/warning, border/border-strong/border-focus.

**Spacing:** 4px base unit scale: 0, px, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24 (in rem).

**Typography:** Font families (sans, mono), sizes (xs-5xl modular 1.25 scale), weights (400-700), line heights (tight/normal/relaxed).

**Shadows:** xs through 2xl + inner + focus ring.

### Step 3: Component API Standards
```
STANDARDS:
- variant: "primary"|"secondary"|"ghost"|"danger"  size: "sm"|"md"|"lg"
- Extend native HTML element props. Export all prop types.
- forwardRef on every component wrapping native elements. Set displayName.
- Compound components: <Card><Card.Header/><Card.Body/></Card>
- Defaults: variant="primary", size="md"
- on<Event> convention. Support controlled and uncontrolled modes.
- className always accepted as escape hatch.
```

### Step 4: Theme System
Light/dark via CSS custom properties on `[data-theme]`. ThemeProvider with system preference detection,
localStorage persistence, flash-free SSR. Multi-brand via `[data-brand]` overriding primitive tokens.

### Step 5: Design-to-Code Pipeline
Figma Variables/Tokens Studio -> tokens.json (W3C format) -> Style Dictionary -> outputs (CSS variables,
TypeScript constants, Tailwind config). CI automation: Figma webhook -> generate -> PR -> visual regression
test.

### Step 6: Versioning & Distribution
Semantic versioning: MAJOR (remove token/component, rename, change defaults), MINOR (add
component/token/variant), PATCH (fix values/bugs). Package structure: dist/css/, dist/js/, dist/tokens/.
Release: version bump -> build -> changelog -> publish -> deploy Storybook.

### Step 7: Storybook Documentation
Initialize with essential addons (a11y, viewport, docs, designs). Structure: Introduction > Foundations
(Colors, Typography, Spacing, Shadows) > Components (Atoms, Molecules, Organisms) > Patterns > Theming.

### Step 8: Audit Report
```
DESIGN SYSTEM AUDIT:
  Token Coverage: Colors/Spacing/Typography/Shadows — <N>/<N> used, <N> hardcoded
  Component API Compliance: <N>/<N> standards-compliant
  Theme System: Light/Dark/System preference/Persistence/Flash-free
  Pipeline: Figma sync automated/manual/none
  Documentation: Storybook coverage <X>%
  Score: <N>/100  Maturity: NONE | STARTER | GROWING | MATURE
```

### Step 9: Remediation Plan
Priority 1 (Critical): blocks adoption. Priority 2 (High): degrades consistency. Priority 3 (Medium): improves
DX. Priority 4 (Low): polish.

### Step 10: Commit
```
Commit per area: "designsystem: <tokens|theme|pipeline|storybook> — <description>"
Transition: Run /godmode:ui for component audit, /godmode:a11y for accessibility
```

## Key Behaviors
1. **Tokens are the single source of truth.** Every visual decision is a token.
2. **Three-tier architecture is mandatory.** Primitives -> Semantic -> Component.
3. **Keep component APIs predictable.** Same prop naming, composition, typing everywhere.
4. **Theming is infrastructure.** Dark mode requires complete semantic token layer.
5. **Automate the pipeline.** Manual sync guarantees drift.
6. **Version like a product.** Semver, changelogs, migration guides.
7. **Storybook is the documentation.** If not in Storybook, it does not exist.

## Flags & Options

| Flag | Description |
|--|--|
| `--audit` | Audit existing design system maturity |
| `--tokens` | Token architecture only |
| `--theme` | Theme system setup |
| `--pipeline` | Figma-to-code pipeline setup |
| `--storybook` | Storybook documentation setup |
| `--init` | Initialize complete design system from scratch |

```bash
# Build and test design system
npx storybook build --ci
npx chromatic --exit-zero-on-changes
npx style-dictionary build
```

IF token coverage < 90%: audit for hardcoded values.
WHEN Storybook build fails: fix imports, check addon compatibility.
IF visual regression detected: review diff, update baseline if intentional.

## HARD RULES
- NEVER use raw hex/rgb in component code — always reference semantic tokens
- NEVER skip the semantic token layer
- NEVER create a component without a Storybook story
- NEVER publish without a CHANGELOG entry
- NEVER modify token values affecting layout without MAJOR version bump
- ALL components MUST forward refs and accept className

## Auto-Detection
```
1. Scan for tailwind.config, CSS :root/[data-theme], tokens.json, style-dictionary config, .storybook/
2. Detect component library: shadcn/ui, radix, chakra, mantine, MUI
3. Check for Figma integration: .figma*, figma-tokens.json
4. Determine maturity: NONE (>10 hardcoded) | STARTER (<50% coverage) | GROWING | MATURE
```

## Multi-Agent Dispatch
```
Agent 1 (tokens): Build/audit token architecture — primitives, semantics, themes
Agent 2 (components): Audit component API compliance — ref forwarding, prop naming
Agent 3 (pipeline): Configure Figma-to-code pipeline — Style Dictionary, CI
Agent 4 (docs): Set up Storybook — foundation stories, component stories
MERGE: All -> visual regression test -> unified report
```

## TSV Logging
Log to `.godmode/designsystem-results.tsv`:
`timestamp\tskill\ttarget\taction\ttokens_count\tcomponents_count\tcoverage_pct\tstatus`

## Success Criteria
1. All tokens in single source (Style Dictionary/Figma Tokens)
2. Semantic layer between primitives and components
3. Every component references only semantic tokens
4. Light + dark themes work by swapping tokens only
5. Every component has Storybook story with all variants
6. Token pipeline generates CSS custom properties
7. Token coverage >= 90%

<!-- tier-3 -->

## Error Recovery
- **Tokens out of sync with Figma:** Re-export, rebuild, diff, update only if changed.
- **Theme switching breaks:** Check semantic token usage, verify data-theme attribute, inspect computed styles.
- **Storybook fails:** Check imports, addon compatibility, clear cache.
- **Visual regression false positives:** Font rendering diffs, update baselines, use threshold tolerance.

## Platform Fallback
Run sequentially if `Agent()` or `EnterWorktree` unavailable. Branch per task: `git checkout -b
godmode-designsystem-{task}`. See `adapters/shared/sequential-dispatch.md`.

## Output Format
Print: `DesignSystem: {tokens} tokens, {components} components. Theme: {light_dark|single}. Storybook:
{passing|failing}. Status: {DONE|PARTIAL}.`

## Keep/Discard Discipline
```
After EACH design system change:
  KEEP if: all components use semantic tokens AND Storybook builds AND visual regression passes
  DISCARD if: primitive token used directly OR Storybook breaks OR visual regression detected
  On discard: revert. Fix token mapping before retrying.
```

## Stop Conditions
```
Loop until target or budget. Never ask to continue — loop autonomously.
Measure before/after. Guard: test_cmd && lint_cmd.
On failure: git reset --hard HEAD~1.

STOP when ALL of:
  - All components reference semantic tokens only
  - Storybook builds and deploys successfully
  - Theme switching works (light/dark) without layout breaks
  - Visual regression baseline established
```