---
name: design-auditor
description: Audit an existing codebase UI and produce a formal design system file. Use when asked to perform a design audit, extract design tokens and component specs, or generate a design system for a Next.js + Tailwind project (or similar React/Tailwind stacks) based on real code.
---
# Design Auditor
Create a design system document from an existing codebase by auditing real UI code. Focus on what exists; do not invent new styles or components.
## Quick start
1. Identify the UI surface area to audit.
2. Extract tokens, components, and patterns from code.
3. Write the design system to `.superdesign/design-system.md` and a concise audit summary to `docs/design-audit.md`.
## Workflow
### 1) Scope the audit
- Prefer a full UI audit unless the user specifies a particular page, feature, or app section.
- If scope is ambiguous, ask for the most important pages or flows to prioritize.
- Use the **scope hints** below to gather high-signal constraints quickly.
**Scope hints (ask these if unclear):**
- Which pages or flows are most used or most critical?
- Which parts of the UI feel inconsistent or “off” today?
- Are there any known constraints (brand colors, typography, accessibility)?
### 2) Collect sources
Read UI-relevant files only. Favor actual implementation over documentation.
Minimum sources to locate and read:
- `tailwind.config.*`
- Global styles: `globals.css` or equivalent
- App/layout wrappers (`app/layout.tsx`, layout components, nav/sidebars)
- Page components and their UI subcomponents
- Shared UI primitives (`Button`, `Card`, `Input`, `Modal`, etc.)
- Utility helpers for classes (`cn`, `clsx`, `cva` usage)
If `.superdesign/init/` exists, read all files there first (`components.md`, `layouts.md`, `routes.md`, `theme.md`, `pages.md`) to speed up discovery.
**Discovery helper (optional):** Use `scripts/discover_ui_sources.py` to generate a candidate file list and confirm coverage.
### 3) Extract design system data
Use only what is present in the codebase. Record:
- **Brand & product context**: product name, audience, key flows (from app copy and nav)
- **Colors**: Tailwind palette usage, CSS variables, semantic aliases
- **Typography**: font families, weights, sizes, line heights, letter spacing
- **Spacing & sizing**: spacing scale, container widths, grid rules
- **Elevation & borders**: shadow tokens, radii, borders
- **Layout conventions**: app shell, navigation patterns, page structure
- **Components**: inventory with variants, states, sizing, spacing, and usage notes
- **Content patterns**: tables, forms, empty states, alerts, pagination
- **Motion**: transitions/animations if present
- **Accessibility**: focus styles, contrast patterns, aria usage, keyboard affordances
**Component inventory checklist (confirm coverage):**
- Button, Link
- Input, Select, Textarea
- Checkbox, Radio, Switch
- Badge/Tag, Avatar
- Card, Table, List
- Tabs, Accordion
- Modal/Drawer, Tooltip/Popover
- Toast/Alert, Banner
- Pagination, Breadcrumb
- Skeleton/Loading, Empty state
**Evidence convention (required):** For each token/component, include the source path(s) and class names where observed.
### 4) Write outputs
Write both files using the provided templates. Keep them concise but complete.
- Do not add speculative or “ideal” tokens.
- If you find inconsistencies, call them out in an **Audit Notes** section.
- Keep the **Token Map (YAML)** short and evidence-linked (source paths and class names).
## Output templates
Use:
- `references/design-system-template.md` for `.superdesign/design-system.md`
- `references/design-audit-template.md` for `docs/design-audit.md`
## Tips
- Favor exact values over descriptions (e.g., `#0F172A`, `text-sm`, `rounded-lg`).
- For components with multiple styles, describe each variant explicitly.
- If multiple fonts are used, list where each is applied.
