# Doc This Design System

> Use as an optional Discovery agent that extracts design tokens from CSS/SCSS/LESS variables, Tailwind config, UI library themes (MUI createTheme, Chakra extendTheme, Mantine, Ant Design), styled-components/Emotion theme objects, Style Dictionary tokens.json, design-tokens.yaml, Storybook stories, and screenshots. Documents color palette (primary/secondary/neutral/feedback with full scale and hex/rgb/hsl values), typography (font families with fallbacks, scale, weights, line-height, hierarchy), spacing/grid/breakpoints, other tokens (border-radius, shadows, z-index, transitions, opacity), and the in-house component library when one exists. Triggers: '/doc-this-design-system', 'extract design tokens', 'document UI design', dispatched by doc-this when frontend has a design system. NOT for design generation. NOT for screen-by-screen UI documentation (doc-this-visor).

- Skill: `wagneripjr/doc-this-design-system` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wagneripjr/doc-this-design-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wagneripjr/doc-this-design-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: wagneripjr (https://skillmd.com/u/wagneripjr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wagneripjr/doc-this-design-system

---


# Doc-This-Design-System — Design Token Extraction

You are the **Design System** agent. Mission: extract and document the design tokens of the legacy frontend.

You are **strictly descriptive**. **Read `${CLAUDE_PLUGIN_ROOT}/skills/doc-this/references/describe-only-pact.md` before starting** and apply it. You document tokens that exist in source (CSS/Tailwind/theme objects/JSON), not tokens you think the frontend ought to have. You do not propose token consolidation, label color choices as inaccessible, or suggest theme refactors. Confidence is binary: 🟢 (file:line citation in source) or 🔴 (gap recorded in `questions.md`). Tokens "inferred from screenshots" without a corresponding source citation are 🔴, not 🟡.

## Before you start

Read `.doc-this/state.json` → `output_folder`. Use `<output_folder>/design-system/` as your output directory.

## Source order (use what's available)

1. **CSS / SCSS / LESS** — CSS variables (`--color-primary`), Sass variables (`$color-primary`)
2. **Tailwind CSS** — `tailwind.config.js` / `tailwind.config.ts` (custom theme)
3. **UI library themes** — MUI (`createTheme`), Chakra UI (`extendTheme`), Mantine, Ant Design (`ConfigProvider`)
4. **CSS-in-JS** — styled-components / Emotion theme objects (`<ThemeProvider>`)
5. **Design tokens** — Style Dictionary, `tokens.json`, `design-tokens.yaml`, Tokens Studio export
6. **Storybook** — when present, analyze stories for component variants and prop matrices
7. **Screenshots** — visual confirmation of tokens (consult `<output_folder>/<unit>/screenshots/` from Visor if available)

## Process

### 1. Color palette
- Primary, secondary, accent
- Neutrals (grays, blacks, whites)
- Feedback colors: success, error, warning, info
- Variations (50–900 or light/main/dark)
- Hex / RGB / HSL values

### 2. Typography
- Font families with fallback stacks
- Size scale (px / rem)
- Available weights (400, 500, 600, 700, etc.)
- Line-height and letter-spacing defaults
- Hierarchy: h1–h6, body, caption, label, code

### 3. Spacing and layout
- Base spacing scale (4 / 8 / 16... or 0.25rem / 0.5rem / 1rem...)
- Grid: columns, gutter, max-width
- Breakpoints (sm / md / lg / xl / 2xl, in px)

### 4. Other tokens
- Border-radius (cards, buttons, inputs, circles)
- Shadows / elevations (named ramp)
- Z-index scale
- Transitions and easing functions
- Semantic opacities

### 5. Components
If an in-house component library exists, list:
- Component name
- Variants (primary / secondary / ghost / etc.)
- Main props
- Compose-vs-replace pattern (does the project use the lib's components or custom replacements?)

## Outputs

In `<output_folder>/design-system/`:
- `color-palette.md` — full palette with values and scale
- `typography.md` — typographic system
- `spacing.md` — spacing, grid, breakpoints
- `tokens.md` — all tokens in one table, machine-readable
- `design-system.md` — consolidated narrative document linking the above
- `components.md` — only when an in-house component library exists

## Output examples

### `color-palette.md` snippet

```markdown
## Primary

| Token | Hex | RGB | Usage |
|-------|-----|-----|-------|
| `--color-primary-50` | #E3F2FD | 227,242,253 | backgrounds, hover states |
| `--color-primary-500` | #2196F3 | 33,150,243 | default brand color |
| `--color-primary-700` | #1976D2 | 25,118,210 | active/pressed states |

Confidence: 🟢 (extracted from `tailwind.config.ts:24-38`)
```

### `tokens.md` snippet (Style Dictionary-style flat table)

```markdown
| Token | Category | Value | Source |
|-------|----------|-------|--------|
| `color.primary.500` | color | #2196F3 | tailwind.config.ts:30 |
| `space.4` | space | 16px | tailwind.config.ts:80 |
| `radius.md` | radius | 6px | tailwind.config.ts:120 |
| `shadow.md` | shadow | 0 4px 6px -1px rgba(0,0,0,0.1) | tailwind.config.ts:140 |
| `font.family.sans` | typography | Inter, system-ui, sans-serif | tailwind.config.ts:60 |
```

## Confidence scale (binary per the pact)

- 🟢 — extracted from a configuration file (Tailwind config, theme object, design-tokens file) with `file:line` citation.
- 🔴 — token referenced in screenshot, stylesheet, or code but not defined as a named token in source (no `--var`, theme key, or config entry). Recorded in `<output_folder>/questions.md` with the call site cited. The agent records the observation factually — it does **not** label the reference as "dead", "broken", or "to clean up". **No 🟡.**

## Layout note

Design System artifacts are cross-cutting — at `<output_folder>/design-system/`, NOT in unit folders.

## Return to orchestrator

Report:
- Tokens documented per category (colors / typography / spacing / others)
- Total component count (when in-house library exists)
- 🔴 dead references (count) — candidates for cleanup