DESIGN.md Extractor

Tailkits DESIGN.md

Turn what a product already looks like into a DESIGN.md an agent can follow: exact tokens in YAML front matter, rules in prose, valid against the official linter.

When to use

• “Write a DESIGN.md for this repo” or “from https://example.com”.
• “Extract our design system”, “make the agent stay on brand”, “capture these colours and fonts”.
• “Lint my DESIGN.md”, “turn my DESIGN.md into a Tailwind / shadcn theme”.
• “Restyle these sections with our DESIGN.md”.

Not for: designing a new brand from nothing. For that, use the free DESIGN.md Studio at https://tailkits.com/design-md/ or the MCP tool designmd_create.

The MCP (optional, free, no account)

Steps 3 to 5 call the Tailkits MCP when it is connected. Check whether tools named designmd_lint, designmd_to_theme and designmd_apply are available. If they are not, say once that the user can add them with:

claude mcp add --transport http tailkits https://tailkits.com/mcp

(Other agents: https://tailkits.com/mcp.) Then continue with the fallbacks; never stop because the MCP is missing.

Workflow

<skill-dir> below is the folder that contains this SKILL.md (for example ~/.claude/skills/tailkits-design-md).

1. Extract

Pick the source the user means. When unclear, ask once: “From the code in this repo, or from the live site?”

# From the repository (CSS variables, Tailwind config, shadcn theme, fonts, and a built page if there is one)
node <skill-dir>/scripts/extract.mjs . --out DESIGN.md --report design-extract.json

# From a URL (the page and its stylesheets; colours weighted by how many elements use them)
node <skill-dir>/scripts/extract.mjs https://example.com --out DESIGN.md --report design-extract.json

# From a local build or a running dev server
node <skill-dir>/scripts/extract.mjs dist/index.html --out DESIGN.md
node <skill-dir>/scripts/extract.mjs http://localhost:3000 --out DESIGN.md

Add --name "Brand" to set the name. Add --render for pages that render in the browser (it uses Playwright only if the project already has it).

The script has no dependencies and never executes project code: it reads the Tailwind config by pattern.

2. Review the report

Open design-extract.json. For every colour it records where the value came from (--primary in app/globals.css, the most used button background, derived).

• Anything in guessed was derived, not found. Confirm it with the user or with the code.
• contrastBelowAA lists real text/background pairs below 4.5:1. Report them; do not silently change brand colours.
• Monochrome sites (black buttons) get primary equal to the text colour. That is correct; do not invent a brand colour.
• Then rewrite the ## Overview and ## Do's and Don'ts prose from what you see in the product (tone, density, imagery). Keep the token values.

See references/reading-tokens.md for how each token is chosen and how to correct it by hand.

3. Lint

• MCP: call designmd_lint with content set to the file’s text.
• Fallback: npx -y @google/design.md lint DESIGN.md (prints JSON; summary.errors must be 0).

Fix every error. Warnings about contrast are real findings about the product: report them and let the user decide.

4. Export a theme

• MCP: designmd_to_theme with target = tailwind-v4, shadcn or css-vars. tailwind-v4 also includes the Tailkits UI derived tokens and motion.
• Fallback: npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css (or css-vars, json-tailwind for Tailwind v3).

Put the CSS where the project keeps its global styles and import it once.

5. Apply to sections (optional, MCP only)

When the user wants new UI in this style, call designmd_apply with content and up to 10 section_ids (for example ["hero-3", "pricing-2"]; find IDs with ui_search_sections or let the user pick at https://tailkits.com/pick/). It returns each section’s HTML restyled with the tokens, plus the theme CSS. Free sections return code anonymously; Pro sections return a preview and a note, which is not an error.

6. Hand off

Commit DESIGN.md at the repository root and add one line to CLAUDE.md, AGENTS.md or the editor’s rules file:

Follow DESIGN.md for every UI change and use only its tokens.

Delete design-extract.json unless the user wants to keep it.

Output format

Google Labs DESIGN.md, version alpha: front matter with colors, typography, rounded, spacing and components, then ## sections in the official order (Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts). Colour names follow shadcn/ui (background, foreground, primary, muted-foreground, …), so the file is also a shadcn theme and drives Tailkits UI sections. references/design-md-format.md has a short annotated example.

Troubleshooting

• “The page has only N elements”: the site renders client-side. Use --render, extract from the repo, or from the built HTML.
• Wrong primary: pass the repo instead of the URL (semantic variables beat usage counts), or edit the value and re-run step 3.
• Fonts show as aliases (for example Source): the site self-hosts under a short name. Replace it with the real family.
• npx is blocked: lint with the MCP, or paste the file into https://tailkits.com/design-md/ (Import tab).