Design md to shadcn

Skill douinc/agent-skills/skills/design-md-to-shadcn

Agent skills for Claude Code, Copilot, Codex, and Gemini CLI — Figma icons (Iconify), logos (SVGL), Korean UX Writing, and more.

Install

npx -y skills add douinc/agent-skills --skill design-md-to-shadcn

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Applies an external DESIGN.md (Google Labs design-token format) to a project's shadcn/ui theme. Activate when the user provides or references a DESIGN.md / design.md file, a designmd.app or Stitch design system, a downloaded brand design system, or asks to 'apply a design system / theme' to a shadcn project. Translates DESIGN.md tokens into shadcn CSS variables in the project's theme CSS file and turns the prose into component guidance. Inbound-only: does not extract a DESIGN.md from the project.

SKILL.md

5.4 KB, as published. Nobody here has run it

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.