Extract SaaS Design
Extract the implemented visual system of an existing SaaS dashboard, admin panel, or internal tool into structured documentation. This is forensic work: document what exists, where it comes from, and how it behaves.
Use this skill when
- The user wants the current visual system documented: tokens, component specs, layout patterns, dark mode, or dashboard-specific UI behavior.
- The user wants to recreate the current look in another codebase through documentation, not by copying source.
- The user wants scoped extraction: foundations only, named components, a navigation or data-display slice, or an evidence-based consistency audit.
Do not use this skill when
- The real task is to build, port, or generate a working UI.
- The real task is redesign, restyling, “make it better,” or speculative UX advice.
- The target is mainly a marketing or brochure site instead of a SaaS/dashboard/admin product.
- There is no implemented UI evidence to inspect.
Operating boundaries
- Document, don't rebuild. Output documentation and evidence, not production UI code.
- Honor the requested scope. Do not default to a full-system extraction unless the user asked for it.
- Work from evidence only. Read actual source files and supporting artifacts; never infer unimplemented behavior.
- Resolve aliases. Convert utilities, tokens, and variables to final values and explain their semantic role.
- Absence is evidence. If a state or mode does not exist, write
not implemented. - Separate canon from noise. Document the dominant system, then flag inconsistencies and exceptions explicitly.
Scope routing
| If the user asks for... | Example requests | Deliver |
|---|---|---|
| Full extraction / "visual DNA" / "document the design system" | "Extract the full design system", "Document the visual DNA" | system.md, foundation docs, relevant component docs, and meta-docs (INDEX.md, _summary.md) |
| Foundations / tokens / theme only | "Extract the color tokens", "Document the spacing system" | system.md plus foundation docs only; skip component docs unless requested |
| Specific components or patterns | "Document the sidebar", "Extract button specs" | Minimal foundation context plus full docs for the named components or patterns only |
| Consistency / quality / accessibility audit | "Audit the color consistency", "Check accessibility" | Evidence-based findings grounded in extracted docs; do not drift into redesign proposals |
Minimal workflow
- Frame the job
- Restate what is in scope, what is out of scope, and which artifacts count as ground truth. - Prefer the smallest extraction that satisfies the request.
- Build the evidence base
- Detect the styling stack first -- this determines everything else: - Offline snapshot / plain HTML+CSS mode: if the input is just HTML/CSS files with no package.json, no src/, and no Tailwind/shadcn markers, treat the CSS files as the token source of truth. Skip framework-specific checks and write not implemented / N/A where those systems do not exist. - Tailwind v4 uses @import "tailwindcss" in CSS and @theme blocks instead of tailwind.config.js. Check for both. - shadcn/ui: look for components/ui/ directory and @/lib/utils imports with cn(). - CSS entry point: find globals.css or app.css -- this is where tokens live. - Normalize the target root before running any routed command. Reference snippets that mention src/, app/, or package.json are common repo examples, not fixed paths. In offline snapshot mode, search the snapshot root directly. See references/extraction/target-modes.md. - Identify token sources: global CSS, theme files, Tailwind config (if v3), component source, Storybook. - Resolve representative token chains end-to-end before writing docs: Tailwind class -> CSS variable -> final value bg-primary -> var(--primary) -> oklch(0.21 0.006 285.88) Plain CSS snapshot chain.metric-card -> var(--card-bg) -> #111827 - Detect the color space: modern shadcn uses oklch(), older uses hsl(). - Check for variant systems: CVA (class-variance-authority) defines variant/size matrices. - Capture recurring values, mode switching, state styling, and composition patterns.
- Extract foundations first when needed
- Spacing, colors, typography, shadows/depth, radius, animations, and shared state conventions. - For dashboard products, explicitly check sidebar overrides, chart palettes, density zones, and tabular/monospace usage.
- Extract components and patterns in scope
- For each component, document anatomy, variants, sizes, states, state transitions, dark-mode differences, and composition. - In offline snapshot mode, treat repeated DOM fragments plus their matching selectors as the component evidence. Document only what the snapshot proves; if the capture does not expose a variant or state, call out the gap explicitly instead of inventing it. - Treat sidebars, tables, command palettes, and form layouts as mega-components that must be decomposed.
- Verify before handoff
- Use references/quality-checklist.md as your verification checklist. - Every important value should be resolved to a final computed value, not just a class name or alias. - Every relevant state should be explicit, including not implemented. - Pay special attention to disabled, focus-visible, loading, error/invalid, empty, and dark-mode behavior. - Document opacity semantics and animation composition when they carry design meaning. - If a recreator would still need to guess, the extraction is incomplete.
- Package the output
- Create all extraction artifacts in the .design-soul/ directory at the codebase root (not inside the skills repo). - "Codebase root" may be the original repo root or a writable working copy of the target UI (for example a copied fixture under a work directory). The rule is about target ownership, not about the original location on disk. - Use the .design-soul/ structure defined in references/documentation/output-format.md. - Follow the exact templates and file layout from the references instead of inventing new formats.
Guardrails: do this, not that
| Do this | Not that |
|---|---|
Resolve bg-primary, rounded-md, p-3, and similar aliases to actual values and meanings | Stop at class names or token aliases |
Write Hover: not implemented / Loading: not implemented when absent | Invent expected states or “best practice” behavior |
| Scope to the user's request | Default to documenting the entire app |
| Document composition and context | Describe components only in isolation |
| Decompose mega-components into sub-parts and modes | Flatten sidebar, table, or form layout into one vague blob |
| Flag inconsistencies with file evidence | Smooth them over into a cleaner system than the product really has |
| Keep audits evidence-based | Turn the task into redesign or subjective critique |
Recovery rules
- Evidence is incomplete: look for adjacent ground truth (global CSS, theme files, config, Storybook, screenshots). If still unresolved, document the gap explicitly.
- The codebase is too large: split into foundations plus the requested categories or components; do not widen scope silently.
- Values conflict across files: document the dominant pattern, then list exceptions with source references.
- Dark mode or a state does not exist: say so plainly; absence is part of the extraction.
- The task starts drifting toward implementation: stop generating build instructions and return to documentation deliverables.
Output contract
When you are asked to produce extraction files, keep the structure predictable:
system.mdfor foundations in scope- numbered foundation docs when doing system-level extraction
- one numbered doc per extracted component
- numbered pattern docs in
components/[app-specific]/when the scope includes dashboard-level compositions or product-unique flows INDEX.mdand_summary.mdfor multi-document or full extractions
Use the exact structure, naming, and content expectations in references/documentation/output-format.md, references/system-template.md, and references/component-template.md.
Reference routing
Start with the smallest relevant set. Only expand if the task genuinely needs more depth.
| Need | What it contains | Read |
|---|---|---|
| Target root and snapshot path handling | How to reinterpret repo-style example commands for repo-backed UIs vs copied HTML/CSS snapshots | references/extraction/target-modes.md |
| Foundation extraction method | Agent prompts for scanning tokens + grep commands + output templates | references/extraction/target-modes.md, references/foundations-agent.md, references/extraction/color-extraction.md, references/extraction/typography-extraction.md, references/extraction/spacing-extraction.md, references/system-template.md |
| Component extraction method | Agent prompt for per-component visual specs + template with all required sections | references/extraction/target-modes.md, references/components-agent.md, references/component-template.md, references/extraction/icons-and-assets.md |
| Dashboard/admin-specific patterns | Sidebar, metrics, tables, charts, cmdk, mega-component decomposition | references/extraction/target-modes.md, references/dashboard-patterns.md, references/layout/grid-and-responsive.md |
| Token translation and naming | W3C DTCG, CSS custom properties, oklch format, shadcn naming pattern | references/extraction/target-modes.md, references/tokens/token-formats.md, references/tokens/naming-conventions.md |
| Packaging the docs | .design-soul/ directory structure, INDEX.md and _summary.md templates | references/documentation/output-format.md, references/system-template.md, references/component-template.md |
| Verification and audit | Extraction completeness checklist, token/component consistency matrix, WCAG contrast checks | references/extraction/target-modes.md, references/quality-checklist.md, references/audit/consistency-checklist.md, references/audit/accessibility-review.md |
Steering Notes for Agents
These notes prevent the most common extraction failures. Read the linked references for full detail.
Tailwind v4 Detection
Grep for @import "tailwindcss" or @theme in CSS files — if found, the project uses Tailwind v4 (CSS-native config, no tailwind.config.js). If tailwind.config.ts exists with theme.extend, it uses Tailwind v3. Always check before extracting tokens. See references/foundations-agent.md for detection commands.
oklch Color Space
Modern shadcn/ui (2024+) uses oklch(L C H) instead of hsl(). L=lightness (0-1), C=chroma (0-0.4), H=hue (0-360). Grays have C < 0.01. Always note lightness to distinguish dark/light colors. See references/extraction/color-extraction.md and references/tokens/token-formats.md for reading guides.
CVA and cn() Patterns
The cva() call IS the component's visual spec — extract every variant/size key-value pair. The cn() utility merges classes via tailwind-merge where the last class wins. See references/component-template.md for the CVA extraction checklist and cn() merging guide.
Token Chain Resolution
Never stop at the Tailwind class. Resolve the full chain: bg-primary → var(--primary) → oklch(0.205...). Some tokens chain through multiple variables. Resolve ALL the way to the literal value. See references/extraction/color-extraction.md for variable chain resolution.
Final reminder
This skill should feel like an orchestrator, not a template dump. Keep the main flow tight, use references for detail, and stay anchored to the implemented UI rather than rebuilding or redesigning it.