design-md-to-shadcn

DESIGN.md → shadcn/ui

Take an external DESIGN.md (the Google Labs design-token format, version alpha, Apache-2.0) and apply it to the project's shadcn/ui theme.

What this skill is for

The DESIGN.md format pairs machine-readable YAML front matter (design tokens) with markdown prose (rationale + guidance). It uses a Material-3-style token namespace (primary, secondary, tertiary, neutral, surface, on-surface, surface-container-*, on-primary, …) that does not map 1:1 to shadcn's fixed semantic tokens.

The official design.md export --format css-tailwind emits --color-primary etc. — single-mode, no foreground pairs — which is not usable by shadcn. This skill provides the missing mapping layer: DESIGN.md tokens → shadcn :root / .dark CSS variables, plus prose → component guidance.

• Direction: inbound only (external DESIGN.md → the project). Do not generate a DESIGN.md from the project.
• Dependencies: none. No @google/design.md CLI, no package installs. Pure parsing + the mapping table in rules/token-mapping.md.

Project target (locate, then verify before editing)

First find the project's shadcn theme CSS file and config — don't assume a path:

• Theme CSS file: the file holding shadcn tokens as CSS variables in :root (light) and .dark. Common locations: app/globals.css, src/index.css, src/app.css, resources/css/app.css, styles/globals.css. Confirm by grepping for --background, --primary, or --radius.
• components.json (repo root): read style, baseColor, cssVariables, tailwind.css (points to the theme file), and the aliases. Note whether tokens are HSL/oklch()/raw and match that convention.
• Composition rules (Card/Dialog/Tabs/etc.) and component install belong to the shadcn skill — defer to it for step 5.

Re-read the theme CSS file before editing; its token blocks are the source of truth and may differ from any assumptions.

Workflow

1. Collect the input

Get the DESIGN.md as a file path, pasted text, or URL. If a URL, fetch the raw markdown (e.g. WebFetch). Confirm it has --- front matter; if it's prose-only, extract what tokens you can and note the gaps.

2. Parse

• Front matter (between the --- fences): name, colors, typography, rounded, spacing, components.
• Body (## sections, canonical order): Overview / Colors / Typography / Layout / Elevation & Depth / Shapes / Components / Do's and Don'ts. Section aliases exist (Overview≡"Brand & Style", Layout≡"Layout & Spacing", Elevation≡"Elevation & Depth").
• Resolve token references {path.to.token} (e.g. {colors.primary}, {rounded.md}) to their values before mapping.

3. Map tokens → shadcn (the core step)

Follow rules/token-mapping.md exactly:

• Color tokens → shadcn semantic variables (with foreground pairs).
• rounded.md/DEFAULT → --radius.
• Detect light vs dark from the background's lightness; fill the matching block, derive the opposite block (flag it for review).
• Normalize every color to the theme file's existing convention (oklch(), HSL channels, or raw) — match what's already there; keep the original value in a trailing comment.

4. Apply to the theme CSS file

Edit only the variable lines inside :root and .dark. Preserve everything else: @imports, fonts, @theme {} (including any --color-* → var(--*) aliases and the --radius-* calc scale), and @layer base {}.

• Use targeted Edit calls per variable block — never overwrite the whole file.
• Present a concise summary of the changes (old → new per token) before/with the edit.
• Unmapped DESIGN.md tokens: keep them as extra custom vars with a comment, or report them — do not silently drop.

5. Component & layout guidance

Summarize the prose (Overview, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts) into concrete rules for any UI built next — e.g. "one primary action per screen", radius/elevation conventions, component variants. Then hand off actual component selection / install / composition to the shadcn skill.

Guardrails

• Never overwrite the theme CSS file wholesale — edit token lines only; keep imports/fonts/@theme/@layer base intact.
• Show the token diff before applying so the user can sanity-check.
• Color conversions (to oklch()/HSL) are approximations — recommend a visual check; do not claim exact color fidelity.
• This skill maps tokens and surfaces guidance; it does not install components (that's the shadcn skill) and does not add dependencies.
• After editing, the user must rebuild/restart the dev server to see changes — use the project's own build command (e.g. npm run build/dev, pnpm, bun, or vendor/bin/sail … for Laravel Sail setups). Check package.json scripts if unsure.