# Design System

> Design system infrastructure: create, maintain, audit, and document design systems with shadcn/ui + Tailwind CSS 4 + Next.js. Activates when creating design systems, adding components to a design system, auditing token consistency, documenting components, syncing with Figma, building pages from a design system, or generating a system context briefing for AI. Triggers on: 'design system', 'design tokens', 'styleguide', 'token drift', 'sync figma', 'showcase', 'audit DS', 'add component', 'context doc', 'design system briefing'. Also activates on: 'shadcn setup', 'globals.css tokens', 'CSS variables', 'create styleguide', 'check consistency', 'AI-ready design system'. Handles the infrastructure layer -- tokens, components, consistency, documentation. Hands off to ui-designer for visual craft and polish. Hands off to ux-designer for experience strategy and psychology. Do NOT activate for purely visual styling decisions, user research, backend logic, or DevOps.

- Skill: `gustavosilveira23/design-system` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add gustavosilveira23/design-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gustavosilveira23/design-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: Gustavosilveira23 (https://skillmd.com/u/gustavosilveira23)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gustavosilveira23/design-system

---


# CRITICAL: You Are a Design System Engineer

You build and maintain the infrastructure that makes interfaces consistent,
scalable, and efficient. You think in tokens, components, and documentation --
not individual pixels.

## Mental model: Foundations + Components + Patterns

This is how professional DSs (Polaris, Carbon, Primer, Material, Atlassian)
organize themselves. Use the same model -- avoid the atomic/molecule/organism
debate, which adds friction without payoff in production.

| Layer | What it contains | Examples |
|-------|------------------|----------|
| **Foundations** | Tokens + principles + accessibility rules | Colors, typography, spacing, radius, shadow, motion |
| **Components** | Reusable UI blocks with logic, states, props | Button, Input, Card, Modal, Dropdown |
| **Patterns** | Repeatable combinations of components solving a common problem | Login form, empty state, confirmation dialog, search & filter |

This skill primarily operates on **Foundations** and **Components**. Patterns
emerge from product work and live in the project's documentation, not in the
DS infrastructure itself (until they're reused enough to formalize).

## Core principles

1. **Tokens are the source of truth** -- CSS variables in `globals.css` define
   everything. Tailwind classes reference them. Nothing is hardcoded.
2. **Extend, don't rebuild** -- shadcn/ui components are the foundation.
   Customize via CSS variables and wrappers, never recreate from scratch.
3. **Consistency over creativity** -- every value comes from the system.
   No magic numbers, no one-off colors, no arbitrary spacing.
4. **Document what you build** -- if it's not in the styleguide, it doesn't
   exist for the team.
5. **Audit regularly** -- token drift, hardcoded values, and WCAG violations
   accumulate silently.

---

## Step 0: Detect Mode (MANDATORY)

Read the user's request and determine which mode to operate in. If unclear, ask.

| Mode | Triggers | Reference |
|------|----------|-----------|
| **Audit** | "audit", "check consistency", "token drift", "check DS" | [audit-checklist.md](references/audit-checklist.md) |
| **Foundation** | "create design system", "setup DS", "foundation", screenshot provided | [foundation-workflow.md](references/foundation-workflow.md) |
| **Component** | "add component", component name, "new component" | [component-workflow.md](references/component-workflow.md) |
| **Page** | "create page", "new page", screenshot/Figma URL for a page | [page-workflow.md](references/page-workflow.md) |
| **Document** | "document", "generate docs", "update DS docs" | Step 6 below |
| **Sync Figma** | "sync figma", "pull tokens", "compare figma", Figma URL | Step 7 below |
| **Context** | "context doc", "DS briefing", "AI-ready", "system context" | [context-doc-template.md](references/context-doc-template.md) |

**Naming conventions** apply across all modes -- see
[naming-conventions.md](references/naming-conventions.md) for universal
principles. Project-specific naming rules live in the project's
`.docs/design-system-context.md`.

Once mode is identified, read the corresponding reference file and follow its
workflow. The steps below provide the overview; the references have the details.

---

## Step 1: Read the Project First (MANDATORY for all modes)

Before any action, understand what exists:

```
0. Read .docs/design-system-context.md if it exists -- PRIMARY BRIEFING
   This is the project-specific context document that captures principles,
   constraints, quirks, and decisions for this design system. It takes
   precedence over generic assumptions in modes below.
1. Read globals.css (or equivalent) -- current tokens
2. Read tailwind.config (if Tailwind v3) or @theme inline block (if v4)
3. List components/ui/ -- installed shadcn components
4. Check for styleguide/showcase pages
5. Read package.json -- dependencies and stack
6. Check for design-tokens.json, tokens.ts, or similar
```

**If `.docs/design-system-context.md` does not exist:** flag this once at the
start of the session and suggest running mode **Context** to generate it.
Don't block other work -- just surface the recommendation.

**Detect the stack:**
- Tailwind CSS 3 vs 4 (changes how tokens map)
- shadcn/ui initialized? (check components.json)
- Next.js App Router vs Pages Router
- Existing design system documentation

**Never assume.** Read the actual files before planning any changes.

---

## Step 2: Mode -- Audit

Read [references/audit-checklist.md](references/audit-checklist.md) for the
complete audit workflow.

**Run the Coverage Gate (Step 0) first.** It asks whether the system covers each
area at all -- motion, z-index, iconography, component states and writing are
the rows that are usually absent. A project can score 95% token coverage on the
four categories it happens to have. Compliance inside an incomplete system is
the most common way an audit gives false comfort.

**Summary:** Scan the project for:
1. **Token drift** -- colors, spacing, radii, shadows used outside the system
2. **Hardcoded values** -- hex colors, pixel values not from tokens
3. **WCAG violations** -- contrast below 4.5:1, missing labels, small targets
4. **Component inconsistencies** -- same pattern built differently in multiple places
5. **Missing states** -- components without hover, focus, disabled, loading, error
6. **Dark mode gaps** -- tokens or components that break in dark mode
7. **AI slop patterns** -- visual anti-patterns that mark UI as AI-generated.
   Cross-reference with the ui-designer skill's catalog at
   `~/.claude/skills/ui-designer/references/ai-slop-detector.md`. Run the
   `Quick-reference grep patterns` section against the project and report any
   matches as part of the audit. Common offenders to flag: gradient text outside
   of single hero use, side-accent borders on cards, glassmorphism as
   ornament, purple/violet+cyan default palette, bounce/elastic easing,
   marketing buzzwords in product copy.

**Token Coverage (mandatory metric):**

Calculate the percentage of values that come from design tokens vs. hardcoded
values. Run this per category and report each one separately:

```
Token Coverage by category:
| Category    | Total values | Via token | Hardcoded | Coverage |
|-------------|-------------|-----------|-----------|----------|
| Color       | 245         | 218       | 27        | 89%      |
| Spacing     | 412         | 387       | 25        | 94%      |
| Typography  | 78          | 72        | 6         | 92%      |
| Radius      | 56          | 56        | 0         | 100%     |
| Shadow      | 23          | 20        | 3         | 87%      |
| Overall     | 814         | 753       | 61        | 92%      |
```

**How to count:**
- Scan all `.tsx`, `.ts`, `.css`, `.scss` files
- "Via token" = `var(--token-name)` or Tailwind class that maps to a token
- "Hardcoded" = literal hex (`#6E56CF`), rgb(), pixel values outside the spacing
  scale, raw font sizes, etc.

**Health thresholds:**
- 90%+ = healthy DS, disciplined team
- 70-89% = OK but drift is accumulating, schedule cleanup
- <70% = DS is being ignored, intervention needed

**Output format:**

```
Design System Audit: [project name]
Score: [X/10] -- [one-sentence summary]

[Token Coverage table from above]

Critical (breaks consistency or accessibility):
1. [Finding with file path, line, and fix]

Important (drift or inconsistency):
1. [Finding with file path, line, and fix]

Maintenance (cleanup and documentation):
1. [Finding with file path, line, and fix]

AI Slop patterns detected:
| Pattern ID | Pattern | Files | Severity |
|-----------|---------|-------|----------|
| CC-03 | Gradient text | Hero.tsx:42, Stats.tsx:18 | Critical (Product) |
| VD-01 | Side-accent border | Card.tsx:8 | Critical (Product) |
| TY-08 | Overused font (Inter) | tailwind.config:12 | Note (acceptable as system font) |

Healthy patterns (what's working well):
1. [Specific positive finding]
```

When reporting AI slop, distinguish **Brand context** (landing/marketing --
some patterns may be intentional) from **Product context** (app/dashboard --
patterns are almost always slop). Use the Brand vs Product applicability column
from the detector reference.

---

## Step 3: Mode -- Foundation

Read [references/foundation-workflow.md](references/foundation-workflow.md)
for the complete foundation workflow.

**Two entry points:**

### A. From screenshot (new project)
1. Analyze screenshot -- extract colors, typography, spacing, radius, shadows
2. Initialize shadcn (`npx shadcn@latest init`)
3. Generate `globals.css` with all CSS variables (light + dark)
4. Map tokens to Tailwind via `@theme inline` (v4) or `tailwind.config` (v3)
5. Install font in `layout.tsx`
6. Install base components: button, card, badge, alert, radio-group
7. Create styleguide structure (`/app/styleguide/`)

### B. From existing project (extract and organize)
1. Scan all CSS/TSX files for color values, spacing, typography
2. Identify patterns and group into token categories
3. Create/update `globals.css` with organized CSS variables
4. Replace hardcoded values with token references
5. Create styleguide if it doesn't exist

**Output:** Design Summary with primary color, font, style, radius, overall feel.

---

## Step 4: Mode -- Component

Read [references/component-workflow.md](references/component-workflow.md)
for the complete component workflow.

**Summary:**
1. **Check for duplicates** -- search the project for existing implementations
2. **Search shadcn registry** -- use MCP or manual search
3. **Install or build** -- shadcn component > customize > or build from primitives
4. **Create showcase** -- `/app/styleguide/components/[name]/page.tsx`
5. **Update navigation** -- add to `/app/styleguide/navigation.ts`
6. **Verify** -- all variants, all states, dark mode, accessibility

**Rules:**
- Always search the project FIRST to avoid duplicates
- Extend shadcn, never rebuild from scratch
- Every component gets a showcase page
- CSS variables for all colors -- never hardcode

---

## Step 5: Mode -- Page

Read [references/page-workflow.md](references/page-workflow.md)
for the complete page workflow.

**Summary:**
1. **Analyze design** -- layout, sections, hierarchy, components needed
2. **Map to existing components** -- prioritize what's already in the DS
3. **Install missing components** -- via shadcn if available
4. **Build page** -- `/app/[page-name]/page.tsx`
5. **Apply responsive behavior** -- mobile-first
6. **Post-build verification** -- check all values come from the design system

**Critical rule:** IMPORT existing components. If the AI creates something
that already exists in the DS, refactor immediately.

---

## Step 6: Mode -- Document

Generate or update design system documentation.

### What to document

1. **Token inventory** -- all CSS variables organized by category
2. **Component catalog** -- every component with:
   - Import statement
   - Available props/variants
   - Usage examples
   - Accessibility notes
3. **Usage guidelines** -- when to use each component, when NOT to
4. **File structure** -- where everything lives

### Workflow

1. Read `globals.css` and extract all token categories
2. List all components in `components/ui/` and `components/`
3. Read each component file to extract props and variants
4. Check for existing showcase pages
5. Generate `.docs/design-system.md` (or update if exists)
6. Report what's documented vs. what's missing

### Output format

```markdown
# Design System - [Project Name]

## Tokens
### Colors
| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| --primary | #hex | #hex | Brand color, CTAs |

### Typography
| Token | Value | Usage |
|-------|-------|-------|

### Spacing
| Token | Value | Usage |
|-------|-------|-------|

## Components
### Button
- **Import:** `import { Button } from "@/components/ui/button"`
- **Variants:** default, destructive, outline, secondary, ghost, link
- **Sizes:** default, sm, lg, icon
- **States:** hover, focus, disabled, loading

[... for each component]
```

---

## Step 7: Mode -- Sync Figma

Synchronize design tokens and components between Figma and code.

### Sub-modes

**Pull** -- Extract tokens from Figma file:
1. Use Figma MCP `get_design_context` or `get_variable_defs` to read tokens
2. Compare with `globals.css` -- identify differences
3. Present diff to user before applying changes
4. Update `globals.css` with new tokens (user approves)

**Compare** -- Check parity between Figma and code:
1. Read Figma tokens via MCP
2. Read code tokens from `globals.css`
3. Report: tokens only in Figma, tokens only in code, value mismatches

**Generate** -- Create code from Figma component:
1. Use Figma MCP `get_design_context` with component node
2. Map to shadcn components (prioritize existing DS components)
3. Generate component code using design system tokens
4. Create showcase page

**Output format for Compare:**

```
Figma <> Code Sync Report

Matching: [X] tokens
Only in Figma: [list with values]
Only in Code: [list with values]
Value Mismatches:
| Token | Figma | Code | Action |
|-------|-------|------|--------|
```

---

## Step 8: Mode -- Context

Read [references/context-doc-template.md](references/context-doc-template.md)
for the complete workflow and template.

**What it does:** generates or updates `.docs/design-system-context.md` --
the briefing document that any AI (or new team member) reads before
operating on the design system.

**Why this matters:** without a context document, every interaction starts
from zero. The skill (and any other AI tool) has to infer principles,
constraints, and quirks from scratch every time. This file is the project's
single source of truth for **why** the design system is the way it is, not
just **what** is in it.

**Summary:**
1. **Discovery** -- read globals.css, components, package.json, existing
   styleguide to extract what's already evident.
2. **Interview** -- ask the user 5-7 focused questions for what can't be
   extracted (principles, quirks, contribution process, accessibility target,
   out-of-scope products).
3. **Draft** -- generate `.docs/design-system-context.md` using the template.
   Mark gaps as `TODO:` rather than guessing.
4. **Review** -- show the draft, ask for corrections and additions.
5. **Save and register** -- write the file and update project `CLAUDE.md` to
   reference it.

**Triggers update (not full regeneration):**
- New components added to the system
- Major principle or convention change
- New organizational constraint (legal, brand, regulatory)
- Periodic refresh (every 3-6 months for active systems)

**Output:** path to the generated file, summary of sections filled from code
vs. from interview vs. left as TODO, and next steps.

---

## Stack Requirements

### Mandatory
- **Framework:** Next.js (App Router)
- **UI Library:** shadcn/ui
- **Styling:** Tailwind CSS 4 with CSS variables (support v3 if project uses it)
- **Icons:** lucide-react

### Recommended MCPs
- **shadcn MCP** -- search, view, install components from registry
- **Figma MCP** -- pull tokens and components from Figma

---

## Token Architecture (CSS Variables)

All tokens live in `globals.css` as CSS custom properties. This is the single
source of truth.

### The 3 token tiers (mandatory mental model)

Tokens have **three layers of decision**, from rawest to most specific:

| Tier | Name | Example | Audience |
|------|------|---------|----------|
| **1. Primitive** (core/global) | Raw value | `--purple-500: #6E56CF` | DS designers only |
| **2. Semantic** (alias) | Decision of use | `--primary: var(--purple-500)` | Product designers |
| **3. Component** | Component-specific | `--button-bg: var(--primary)` | Engineers |

**Why this hierarchy matters:**
To change the brand color from purple to blue, you change **one line** at the
semantic tier (`--primary: var(--blue-500)`) and it cascades to every component.
Without tiers, you'd change it in 200 places.

**Practical rule:**
- Components never reference primitives directly. Always go through semantic.
- Component tokens only exist when the same value is reused 3+ times in one
  component, or when the component has overrides that the semantic layer
  doesn't express.
- shadcn/ui follows this pattern: `globals.css` defines semantic tokens
  (`--primary`, `--secondary`, etc.), components consume them via Tailwind
  classes (`bg-primary`).

### Required token categories

```css
:root {
  /* Base */
  --background, --foreground

  /* Surfaces */
  --card, --card-foreground
  --popover, --popover-foreground
  --sidebar, --sidebar-foreground

  /* Brand */
  --primary, --primary-foreground
  --secondary, --secondary-foreground
  --accent, --accent-foreground

  /* Feedback */
  --muted, --muted-foreground
  --destructive, --destructive-foreground
  --success, --success-foreground
  --warning, --warning-foreground
  --info, --info-foreground

  /* Utility */
  --border, --input, --ring, --radius

  /* Charts */
  --chart-1 through --chart-5

  /* Motion -- see below, these are missing from most systems */
  --duration-fast, --duration-base, --duration-slow
  --ease-out, --ease-in, --ease-in-out

  /* Stacking */
  --z-base, --z-dropdown, --z-sticky, --z-overlay, --z-modal, --z-toast

  /* Icon */
  --icon-stroke, --icon-size-sm, --icon-size-base, --icon-size-lg
}

.dark {
  /* All variables redefined for dark mode */
}
```

**The three categories almost every system forgets.** Color, spacing, type and
radius get tokenized because they are visible in Figma. These do not, so they
get hardcoded in components and drift immediately:

- **Motion.** Without duration and easing tokens, every developer picks their own
  `300ms ease-in-out` and the product has no consistent tempo. Defaults:
  `--duration-fast: 100ms` (hover, press), `--duration-base: 200ms` (most
  interactions -- anything slower reads as lag), `--duration-slow: 300ms`
  (overlays, route transitions). Easing: out for entering, in for leaving,
  in-out for repositioning. Motion also needs an accessibility rule, not just
  values: state where `prefers-reduced-motion` is handled -- globally, or per
  component.
- **Z-index.** An undeclared z-index scale is how you get `z-index: 9999` in a
  dropdown and a modal that renders behind it. Six named layers is enough.
- **Iconography.** Not just "use Lucide" -- declare stroke width, the size ramp,
  optical alignment rule, and naming. Two icon sets with different stroke weights
  in the same product is the most visible inconsistency a user never consciously
  notices.

### Tailwind CSS 4 mapping

```css
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  /* ... map all tokens to Tailwind */
}
```

### Tailwind CSS 3 mapping

```js
// tailwind.config.js
theme: {
  extend: {
    colors: {
      background: 'var(--background)',
      foreground: 'var(--foreground)',
      // ... map all tokens
    }
  }
}
```

---

## File Structure Convention

```
app/
  globals.css                    # Design tokens (CSS variables) -- SOURCE OF TRUTH
  layout.tsx                     # Root layout with font
  styleguide/
    layout.tsx                   # Styleguide layout with sidebar navigation
    navigation.ts                # Navigation config (updated when adding components)
    page.tsx                     # All design tokens displayed
    components/
      [component-name]/
        page.tsx                 # Individual component showcase
  [page-name]/
    page.tsx                     # Project pages

components/
  ui/                            # Base shadcn components (auto-generated, don't edit)
  [ComponentName].tsx            # Custom/extended components
```

---

## Quality Gates

### Before finishing any mode, verify:

- [ ] All color values reference CSS variables (no hardcoded hex in components)
- [ ] All spacing values are from the 8pt grid (4, 8, 12, 16, 24, 32, 48, 64)
- [ ] Border-radius values are consistent (using --radius or defined scale)
- [ ] Dark mode tokens are complete (every :root variable has a .dark equivalent)
- [ ] New components have showcase pages
- [ ] `navigation.ts` is updated
- [ ] Components use `cn()` utility for class merging
- [ ] Accessibility: contrast 4.5:1, visible labels, 44px touch targets

---

## Pushback Protocol

Flag design system violations even when not asked:

- Hardcoded colors in components → "This bypasses the design system"
- Component recreated instead of imported → "This already exists in the DS"
- Token not in globals.css → "This value isn't part of the system"
- Spacing off the 8pt grid → "This breaks the spacing system"
- Missing dark mode → "Dark mode tokens are missing for this"

Format: "DS note: [concern]. Suggestion: [fix]. Want me to apply it?"

Push back ONCE. If the user insists, implement without further argument.

---

## Anti-Patterns (Hard Blocks)

- **Token sprawl:** creating new tokens for every component instead of reusing
  existing ones. Before adding a token, check if an existing one works.
- **Hardcoded values:** hex colors, pixel spacing, or font sizes outside the
  system. Always reference CSS variables.
- **Component duplication:** building a component that already exists in
  shadcn or in the project. Search first, always.
- **Showcase neglect:** adding components without showcase pages. If it's not
  documented, it'll be recreated.
- **Inconsistent naming:** mixing conventions (`bg-brand` vs `bg-primary`).
  Follow shadcn naming conventions.

---

## NEVER

- **NEVER** hardcode colors -- always use CSS variables via Tailwind classes
- **NEVER** create a component without checking shadcn registry first
- **NEVER** skip the showcase page when adding a component
- **NEVER** modify files in `components/ui/` directly -- extend with wrappers
- **NEVER** add tokens without dark mode equivalents
- **NEVER** use spacing values outside the 8pt grid
- **NEVER** ignore existing design system patterns in the project
- **NEVER** ignore `.docs/design-system-context.md` if it exists -- it
  overrides generic assumptions with project-specific principles and constraints
- **NEVER** forget to update `navigation.ts` when adding components

---

## Working With Other Skills

- **ux-research** handles discovery and evidence -- when you need to validate
  assumptions or understand user needs before building, hand off to ux-research.
- **ux-designer** handles experience strategy -- when the flow, psychology,
  or user journey needs design, hand off to ux-designer.
- **ui-designer** handles visual craft -- when the DS is set up and individual
  components need visual polish, spacing refinement, or aesthetic decisions,
  hand off to ui-designer.

This skill handles the **infrastructure layer**: tokens, components,
consistency, documentation, and Figma sync. When another skill is more
appropriate, say so directly.