Extract Design System

Extract Design System

Turn a codebase's actual, shipped design language into a reusable skill. The output is a new SKILL.md — a tight rules + workflow + pitfalls guide — that lets any agent restyle or build pages that look like they belong in this app. Ground everything in the real code and the rendered UI. Never invent tokens; a design system you can't point to in the tree is a guess.

This is the generator that produces a design skill. It is not frontend (which invents a new aesthetic) — here the aesthetic already exists and your job is to codify it faithfully.

Steps

1. Read the tokens — don't guess. Find where design decisions actually live:

• Config tokens: Tailwind config (theme.extend — colors, fontFamily, borderRadius,

boxShadow, spacing), CSS custom properties (:root, @theme, data-theme), SCSS/LESS variables, or a tokens.* / theme.* file.

• Typography: font loading (next/font, @font-face, ``), families, weights, the

type scale, and any display/accent face used differently from body.

• Color & theming: the palette and the semantic names layered on it (background,

surface, muted, accent, border), plus the dark-mode strategy (class vs prefers-color-scheme) and how token pairs flip.

• Scales: the real radius, spacing, shadow, and border values in use — and which size

maps to which kind of element (control vs card vs sheet).

• Components: open the base primitives (Button, Card, Input, layout shell). Note

default radii, whether surfaces use borders / shadows / tone, and the variant set.

• Motion & atmosphere: transition durations/easings, hover/active patterns,

prefers-reduced-motion handling, and any grain, gradient, glow, or background wash.

1. See it, don't just read it. Run the app (or open Storybook / existing screenshots) and

look at 2–3 real screens in both themes. Code lies — dead tokens, inline overrides, one-off styles. Trust what renders; reconcile it with the tokens.

1. Derive the rules, not the inventory. A design system is the handful of non-obvious

constraints that make pages look right — what defines a surface, what never gets a border, the radius scale, how sections are separated, the one signature move. Aim for 6–9 load-bearing rules, each citing real class/token names. A dump of every variable is not a design system.

1. Write the skill. Create skills/-design/SKILL.md following the skeleton below,

named after the product or aesthetic. Put copy-paste token values and 2–4 real code snippets from the app in a sibling REFERENCE.md if they run long; keep SKILL.md dense.

1. Validate and dogfood. Run npm run check, then apply the new skill to restyle one

small component and screenshot it in both themes — it should be indistinguishable from the source app. If it isn't, a rule is wrong or missing.

Output skeleton (the design skill you generate)

---
name: -design
description: Apply the  "" design system — . Use
  when building or restyling pages/components in , or when the user mentions
  "" or asks to make a page match .
---

#  Design System

## The N rules
1. **.** 
   … (6–9 rules)

## Workflow for a new page
1. … the order you actually build a screen in this system

## Pitfalls (each shipped as a bug once)
-  → 

## Tokens / reference

Model the density and voice on the project's own well-written docs — every line should save the next agent a lookup.

Guardrails

• Grounded only. Never document a token, class, or component you haven't found in the

tree and confirmed on screen.

• Rules over inventory. 6–9 constraints that carry the look beat a wall of variables.
• Portability. An extracted design skill is usually product-specific (brand colors,

product name, private aesthetic). Keep it local unless it's genuinely generic and meant to be shared — add skills/-design/ to .gitignore so brand-specific design skills never publish by accident. Strip any secret, internal URL, or machine-specific path from the output.

• Leave committing to the commit / ship skills.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: therapys
• Source: therapys/dotagents
• License: MIT

Install and usage instructions live in the source repository linked above.