Design Extractor

Design Token & Component Extractor

You are helping the user audit their codebase for design system extraction opportunities and produce a clear proposal they can review before any code is written.

What this skill does

1. Discover — identify the project's stack, styling approach, and component format
2. Audit — scan for inline style values, CSS variables, and repeated UI patterns
3. Propose — write a structured extraction plan covering tokens and components
4. Implement — after user approval, write the actual files

This is a plan-first workflow. Never write implementation code until the user has reviewed and approved the proposal.

Phase 0: Discover the stack

Before auditing anything, spend a moment understanding what you're working with. Look for:

• Package manager: package.json, pnpm-lock.yaml, yarn.lock, Gemfile, etc.
• Styling approach: Tailwind config (tailwind.config.*, @import "tailwindcss"), CSS Modules (*.module.css), styled-components/emotion imports, plain CSS, SCSS, etc.
• Component format: .tsx/.jsx (React), .vue (Vue), .svelte, .html templates, etc.
• Existing token system: CSS custom properties in :root, SCSS variables ($brand-color), JS theme objects, design token files (Style Dictionary, etc.)
• Type checker: tsconfig.json → TypeScript; otherwise JavaScript

If the user told you the stack already, confirm rather than re-discover. If anything is ambiguous, make a reasonable assumption and note it in the proposal.

Phase 1: Audit

Token candidates — hard-coded values that appear in multiple places

Look for values that are repeated verbatim across files rather than referenced from a single source. The exact patterns depend on the styling approach:

• Tailwind projects: arbitrary values like text-[#3a1c71], bg-[rgba(0,0,0,0.4)], border-[var(--brand)] used directly in class strings
• CSS/SCSS: hex/rgba values that appear in multiple rules without a variable
• CSS custom properties already exist but lack semantic roles: e.g., --brand-blue used as both a button color and a link color and a border — a single palette token doing the work of three semantic concepts
• JS theme objects: color strings repeated across styled-component definitions

Also check for missing semantic layer — palette tokens exist but there's no role-based alias like --color-primary, --color-on-surface, --color-border.

Component candidates — UI patterns repeated 3+ times with the same structure

What counts as duplication depends on the framework:

• React/Vue/Svelte: identical JSX/template blocks across multiple files
• HTML templates: repeated Jinja/ERB/Blade partials that aren't extracted
• Any framework: the same logical pattern (header with title + action, form field with label + input + error, modal overlay) copy-pasted with minor variations

Two distinct kinds of components emerge from this audit — treat them differently:

Structural components — JSX/template blocks copy-pasted with minor prop variations:

• Navigation link blocks (icon + label + active state)
• Page/section header (kicker text + title + action button)
• Form field wrapper (label + control + error message)
• Modal/dialog overlay (backdrop + centered panel + close button)
• Empty state block
• Card/list item rows

Styled primitive components — native HTML elements (<button>, <input>, <select>, <badge>) whose className strings are repeated across files with variant-like differences (e.g., a primary button vs an outline button vs a ghost icon button). These aren't structural copy-paste — the JSX is often one line — but the inline Tailwind/CSS class string is duplicated or slightly diverges across call sites. The right extraction is a primitive component with a variant + size prop system, not a structural wrapper.

Signs you're looking at a styled primitive:

• The same native element (<button>, <input>) appears in 5+ places with long, mostly-identical className strings
• There are 2–4 visual variants (primary/outline/ghost/destructive) defined separately in different files
• Conditional class logic like ${isPrimary ? 'bg-primary ...' : 'border ...'} repeated inline
• A local buttonCls, inputCls, etc. constant defined per-file

How to scan:

• Grep for repeated literal values: hex colors, rgba strings, specific class combinations
• Grep for structural markers: fixed inset-0, position: fixed, repeated label+input patterns
• Read the main layout/shell component and a few route/page files to spot copy-paste blocks
• Run a duplication checker if available (e.g., jscpd, fdupes) — but don't require it

Phase 2: Proposal

Write the proposal as a structured document in the conversation. Do NOT write any files.

Proposal structure

## Design Token & Component Extraction Proposal

### Stack
[One-line summary of what you found: framework, styling, TypeScript/JS, existing token setup]

### Token Layer

**Current state:** [what exists, what's missing]

**Proposed tokens:**
| Token name | Value | Role |
|------------|-------|------|
| --color-primary | #328f97 | Primary action color |
| --color-on-primary | #ffffff | Text/icon on primary bg |
| ... | ... | ... |

**Contrast check:** [for button foreground/background pairs, state the WCAG AA ratio and pass/fail]

**Dark mode / theming:** [note if dark mode overrides are needed or if theming is out of scope]

### Styled Primitive Components

[Include this section when native elements have per-file className duplication with visual variants]

**Button** → `src/components/ui/Button.tsx`
Variants: `default` (primary CTA), `outline` (secondary), `ghost` (icon-only), `destructive`
Sizes: `default`, `sm`, `lg`, `icon`
Implementation: `cva` + headless primitive (`@base-ui/react/button`, `@radix-ui/react-slot`, or plain `<button>`)
Replaces: inline `className` strings in [list files]
Call sites: N occurrences

[Repeat for Input, Badge, etc. if applicable]

### Structural Component Extraction

**ComponentName** → `path/to/ComponentName.ext`
Props: `prop1: type`, `prop2?: type`
Replaces: list of files that contain the duplicated pattern
Instances reduced: N → 1

...

### Migration plan (ordered)
1. ...
2. ...

### What stays the same
- [visual behavior, any explicit non-goals]

Be specific — not "add a primary color variable" but "--color-primary: #328f97". Not "extract a modal component" but "Modal.tsx accepting title, onClose, children". The proposal should be precise enough that someone else could implement it from the document alone.

For contrast ratios: state the hex pair and the ratio. WCAG AA requires 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt bold). If you can't calculate exactly, flag it for the user to verify.

Phase 3: Implementation (after approval)

Once the user approves (or approves with modifications), implement in this order:

Tokens first — adding the semantic layer is cheap and immediately benefits all the component work that follows:

1. Add semantic aliases to the base/light theme (:root, $variables, theme object — whatever the project uses)
2. Mirror in dark mode / alternate themes if applicable
3. If Tailwind v4: register via @theme { --color-primary: var(--color-primary); } If Tailwind v3: add to extend.colors in tailwind.config.js If CSS Modules/plain CSS: variables are usable immediately
4. Update primary button classes to use semantic tokens

Styled primitives second — these unlock consistent variant usage across all the structural components you're about to write:

• Check for cva (class-variance-authority) in package.json; if absent, ask before installing
• Check for an existing headless UI primitive to render as (e.g., @base-ui/react/button, @radix-ui/react-slot, @headlessui/react) — prefer reusing what's already installed over adding a raw <button> or a new dependency
• Define buttonVariants with cva, using the project's actual design tokens as values (not generic Tailwind utilities — look at what the inline classes actually use)
• Export both the component and buttonVariants so call sites that can't use the component (e.g., BaseDialog.Close) can still apply the class string via buttonVariants({ ... })
• Migrate all call sites; run the type-checker after

Structural components by duplication count — most-repeated first:

• For each component: read all instances → extract minimal shared interface → write the component → update all call sites → run type-checker

After all changes:

• Run type-checker (tsc --noEmit, vue-tsc, etc.) and fix any errors
• Report final duplication % if a checker is available
• Ask before installing any new dependencies (headless UI libraries, etc.)

Notes on common stacks

Tailwind v4 (CSS-first config): Register semantic tokens as Tailwind color utilities:

@theme {
  --color-primary: var(--color-primary);   /* enables bg-primary, text-primary, etc. */
  --color-border: var(--color-border);
}

Tailwind v3 (JS config):

// tailwind.config.js
theme: { extend: { colors: { primary: 'var(--color-primary)' } } }

SCSS:

$color-primary: #328f97;
// then use @forward / @use to share across files

CSS custom properties only: Works in any framework — define in :root, override in [data-theme="dark"] or a theme class.

WCAG AA quick reference:

• 4.5:1 minimum for normal text (body, buttons, labels)
• 3:1 minimum for large text (18px+) and UI components (borders, icons)
• Always check both default and hover/focus states