# Design Md To App > Generate or customize a frontend app from a DESIGN.md (Google design.md spec): reads its tokens and produces a working React app pre-styled to match. Next.js 16 + App Router only; pre-16 refused. Four UI libraries — shadcn/ui, Base UI, MUI, Coss/UI (via `coss-ui`) — and TanStack Form + Zod (default) or react-hook-form. Bumps phase to `scaffolded`. Use when the user has a DESIGN.md and wants to scaffold an app, set up a theme, or customize shadcn / Base UI / MUI from its tokens: "use this DESIGN.md to start an app", "DESIGN.md → app", "scaffold from design.md", "applica il DESIGN.md a shadcn / Base UI / MUI", "crea l'app dal DESIGN.md", "init shadcn con questo DESIGN.md". Not for: mobile apps (use rn-bootstrap), writing PRDs (use prd-from-idea), or generating pages after the scaffold exists (use screenshot-to-page). - Skill: `lukedj78/design-md-to-app` (Agent Skill, multi-file: 33 files) - Install (CLI): `npx skillmds@latest add lukedj78/design-md-to-app` - Raw SKILL.md: https://api.skillmd.com/api/skills/lukedj78/design-md-to-app/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: lukedj78 (https://skillmd.com/u/lukedj78) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lukedj78/design-md-to-app --- ## Dev-flow contract This skill participates in the **dev-flow** workflow. When invoked on a project that has a `.workflow/` folder at its root: - **Input** is `/.workflow/DESIGN.md` (mandatory) and `/.workflow/meta.json#stack` (preferred — if `framework` and `ui` are set, use them; if not, ask the user once and persist). - **Output** is the codebase scaffold at `/`, **alongside** the existing `.workflow/` directory (NOT nested inside it). The framework's standard layout — `package.json`, `app/`, `components/`, `lib/`, etc. — sits at the top so `cd && pnpm dev` works the way every developer expects. - **State** is updated by setting `meta.json#phase = "scaffolded"`, refreshing `updated_at`, and appending an entry to `meta.json#history` describing the run (skill name, inputs, outputs, phase delta). - **Standalone mode** (no `.workflow/` present) is still supported — fall back to the original "ask the user where to scaffold" behavior. The contract is opt-in. The canonical contract spec is in `references/contracts.md`. Read it if any of the rules above are unclear. # DESIGN.md → App Take a `DESIGN.md` (Google design.md spec — see `references/spec.md`) and produce a working React app where shadcn/ui or MUI components are already themed and ready to compose into the actual product. The user picks the library; this skill turns design tokens into theme code, customizes component variants according to the `components` block, and leaves the user with a runnable scaffold plus a `/showcase` page they can visually verify. ## When this skill applies Trigger on any of: - A `DESIGN.md` (or `design.md`) file path or content provided by the user. - Explicit requests: "fai partire l'app dal DESIGN.md", "scaffold from design.md", "customize shadcn/MUI from this DESIGN.md", "apply these tokens to shadcn/MUI". - A user describing wanting to start a project where the design system is already specified in `DESIGN.md` form. If the user has a `DESIGN.md` but only mentions shadcn/MUI without referencing the file, still trigger — they likely want their tokens applied. ## What you produce A scaffolded (or augmented) **React + TypeScript** project where: 1. The chosen UI library (shadcn/ui or MUI) is installed and configured. 2. **Design tokens** from the YAML frontmatter are wired into the theme: - `colors` → CSS variables (shadcn) or `palette` (MUI). **Always two modes**: dark + light, with the source DESIGN.md driving the canonical mode and the other auto-derived (see §Dark + light below). - `typography` → typography scale (Tailwind theme extension or `theme.typography`). - `rounded` → radius scale (`borderRadius` extension or `theme.shape`). - `spacing` → spacing scale (Tailwind extension or `theme.spacing` overrides). 3. **Components** from the `components` block are reflected in: - shadcn: variant overrides on the corresponding component (e.g. `button-primary` → `Button` `default` variant in `components/ui/button.tsx`). All shadcn primitives are installed (`shadcn add --all`) so the app comes out of the box ready to compose. - MUI: `theme.components.MuiXxx.styleOverrides` and/or `defaultProps`. 4. A `/showcase` page renders every styled primitive so the user can verify the result. 5. Fonts referenced in `typography.fontFamily` are loaded — via `next/font/google` when on Next, via direct `` for Vite/Remix when the font is on Google Fonts, otherwise self-hosted from a local `public/fonts/` (see §Font loading). 6. A `_design-md-mapping.json` is written at the project root showing exactly how each DESIGN.md token resolved to library values — useful for debugging and for the user to verify the mapping at a glance. 7. The markdown body's qualitative rules (gradients, glow, glassmorphism, "do's and don'ts") are encoded as utility classes / theme effects where they translate to CSS, and otherwise summarized in a `STYLE_NOTES.md` so the user — and future agents — can apply them consistently. **Never invent the spec.** When in doubt about a token shape, valid units, references like `{colors.primary}`, or canonical section ordering, read `references/spec.md` first. ## Workflow ### Step 1 — Locate and parse the DESIGN.md - **Preferred (dev-flow mode):** if a `.workflow/meta.json` exists at the project root, the DESIGN.md is at `.workflow/DESIGN.md`. Don't search further. - **Fallback:** if the user gave a file path, use it. Otherwise look for `DESIGN.md` in the project root (case-insensitive). If multiple are found, ask which one. - Run `python scripts/parse_design_md.py ` to get a normalized JSON dump of `{ frontmatter, body_sections, resolved_components }` where token references like `{colors.primary}` are resolved to literal values. - If parsing fails (malformed YAML, duplicate sections), surface the error and stop. The user must fix the source. **A third shape exists, and it is not an input.** `design.md` now names two unrelated artefacts. Ours is the Google spec below: token blocks in the frontmatter. The other is an **Agent Skill** — frontmatter of exactly `name` + `description`, body in prose, zero tokens. [`https://vercel.com/design.md`](https://vercel.com/design.md) is one: Vercel's brand guidance for agents writing report pages, served as `text/markdown` so any agent can load it. Fed one of those, the parser used to exit `0` with empty tokens — which shape 2 below reads as "body-only, extract from prose", and every value in the app ends up invented. It now **exits `2` and says so**. If a user hands you a URL or a file that turns out to be a skill, the answer is not to parse it: it carries no design system. **Two valid input shapes — handle both:** 1. **Frontmatter + body** (the canonical Google design.md spec). The parser returns a populated `frontmatter` dict; `resolved_components` is non-empty. This is the easy path — token values are already structured for you. 2. **Body-only / prose-only** (no `---` fences, the spec written entirely as markdown). The parser returns `frontmatter: {}` and everything goes into `body_sections`. This is now common in the wild — many DESIGN.md files written for AI agents are pure prose with section headings like `## 2. Color Palette`, `## 3. Typography Rules`, etc. When `frontmatter` is empty, **don't stop and ask for YAML**. Extract tokens directly from the body sections. Map sections to token categories by their heading (case-insensitive partial match): - "Color" / "Palette" / "Colors" → colors - "Typography" / "Type" / "Fonts" → typography levels + font families - "Component" / "Components" / "Cards" / "Buttons" → component variants - "Layout" / "Spacing" / "Grid" → spacing scale, container widths - "Radius" / "Shapes" / "Border" → radius scale - "Depth" / "Elevation" / "Shadow" → shadow utilities - "Do's and Don'ts" / "Notes" / "Known Gaps" → STYLE_NOTES.md content + mode/font opt-outs Read each section as the source of truth for its category — extract hex values from prose, copy typography tables, lift component prose specs verbatim. Document this extraction path explicitly in `_design-md-mapping.json` under a top-level `extraction_method` field so a reviewer can see what came from prose inference vs. from a structured field. ### Step 2 — Pick the library Ask the user once: **shadcn/ui, Base UI, MUI, or Coss/UI?** Offer a recommendation based on `references/library-choice.md`. Common heuristics: - Highly custom visual identity (glassmorphism, brutalist, editorial, distinctive shapes) + user wants to edit source → **shadcn**. - Same custom-Tailwind philosophy as shadcn but the user prefers a library they can `pnpm update` (no CLI / `components.json` overhead) → **Base UI**. - Material-leaning, dashboard, enterprise CRUD, lots of data tables / dialogs out of the box → **MUI**. - Tailwind already in use, or the user wants utility-first → **shadcn** or **Base UI** (toss-up; Base UI for less source-maintenance, shadcn for max control). - Heavy Material Icons / Material Design heritage → **MUI**. - Best accessibility track record without Material visuals → **Base UI** (same MUI team, headless). **If they pick shadcn, ask the follow-up: which primitive base — Base UI, Radix, or React Aria?** (`shadcn create --base base|radix|aria`). shadcn CLI v4 builds on any of them, with the same component API and blocks across variants. **Default Base UI** (shadcn's default for new projects since 2026-07; full component + block coverage, MUI-team a11y). Pick **Radix** (the long-standing base, still fully supported) or **React Aria** (`--base aria`, Adobe's a11y-first primitives, first-class since 2026-07) explicitly. Record as `stack.ui_base`. This is distinct from picking standalone Base UI (`stack.ui = "base-ui"`, no shadcn CLI) — see `references/library-choice.md`. **Hybrid asking** (per dev-flow): also ask `icon_library` (lucide default), and `rtl` only when the project is multilingual/RTL. **Don't** ask base color / theme — the DESIGN.md tokens own the visual layer; `css_variables` stays `true`. - Wants the **Cal.com design system** / an AI-first, MCP-friendly copy-paste kit on Base UI, and Tailwind v4 is acceptable → **Coss/UI** (`stack.ui = "coss"`) — hand off to the `coss-ui` skill. Mapping skill choice → `meta.json#stack.ui` → `references/-mapping.md`: - "shadcn" → `references/shadcn-mapping.md` (+ `stack.ui_base` = base|radix|aria) - "base-ui" → `references/base-ui-mapping.md` (standalone Base UI, no shadcn CLI) - "mui" → `references/mui-mapping.md` - "coss" → **hand off to `coss-ui/SKILL.md`** (Coss/UI — Cal.com DS on Base UI via the shadcn `@coss/*` registry; `ui_base = "base"`; requires **Tailwind v4**; mixed **MIT/AGPLv3** license). Coss's tokens are shadcn CSS vars, so DESIGN.md overrides apply as in the shadcn path. State the suggestion with a one-line rationale ("Suggerisco Base UI perché vuoi l'aesthetics flessibile di shadcn ma senza la source-maintenance del CLI"), then accept whatever the user picks. After picking, load the matching `-mapping.md` and follow it for installation, theming, and component wiring. ### Step 3 — Pick the project target, framework, and scope Ask the user **two** things in this step: **3a. Project target** - **Dev-flow mode** (`.workflow/meta.json` exists): scaffold the codebase **at `/` alongside `.workflow/`** (e.g., `pnpm create next-app .` from the project root). Do NOT create a sub-directory like `app/` or `code/` to nest the codebase. The framework comes from `meta.json#stack.framework` if set, otherwise ask. The user does **not** pick the path — the contract pins it. - **New project (standalone)** → ask which framework: **Next.js (App Router)** [default], **Vite + React**, or **Remix**. Then scaffold in a folder of the user's choice with TS + the chosen UI library wired in (see the relevant mapping reference for exact init commands). - **Existing project?** → ask for the project root, then detect the framework by inspecting `package.json` and the file layout: - Next.js → `next` in deps + `app/` or `pages/`. - Vite + React → `vite` + `@vitejs/plugin-react` in deps. - Remix → `@remix-run/*` in deps. - Anything else → tell the user what you found and ask how to proceed (most often: "write the theme files anyway and I'll wire them up"). The mapping references describe the framework-specific glue (font loading, root layout/provider wiring, where to put `theme.ts` / `globals.css`). Don't assume Next.js paths — branch on the detected framework. **3b. Scope: full scaffold vs. theme-only** Ask: **"Vuoi lo scaffold completo (showcase + STYLE_NOTES + provider wiring) o solo le patch al tema?"** Two modes: - **Full scaffold** (default for new projects): everything described in §What you produce — theme files + component overrides + `/showcase` route + `STYLE_NOTES.md` + `_design-md-mapping.json` + provider wiring. **Golden rule 2 — wire i18n now** (follow the doc-grounded how-to in `references/i18n-next-intl.md`, don't improvise the setup): install **next-intl** (`stack.i18n`), scaffold `messages/en.json` + `messages/it.json` (minimum `stack.locales = ["en","it"]`, default `en`), the `[locale]` routing (`routing.ts`/`navigation.ts`/`proxy.ts`/`request.ts`) with `setRequestLocale` + `generateStaticParams`, and `` in the root layout. All scaffolded copy uses `useTranslations` keys — never hardcoded strings (the `forms` skill already assumes this). Adding i18n later touches every page, so it's part of the initial scaffold, not deferred. - **Theme-only patch** (recommended for mature existing projects): write *only* the design-token files as a reviewable diff: - shadcn: `globals.css` (Tailwind v4 is CSS-first — tokens live in `@theme` inside `globals.css`; only touch `tailwind.config.ts` if the project still uses a v3 JS config), the `cva` blocks of components named in DESIGN.md. - MUI: `lib/theme.ts` only (or wherever the theme already lives). - **Plus** `_design-md-mapping.json` and `STYLE_NOTES.md` because they're cheap to add and useful for the reviewer. In theme-only mode, **don't** create `/showcase`, **don't** install new dependencies, **don't** touch the root layout/provider unless the user explicitly asks. The goal is a diff a senior reviewer can read in five minutes. Default the choice based on context: existing project with extensive code → suggest theme-only; new project or empty repo → full scaffold. State the suggestion in one line, accept whatever the user picks. If overwriting any existing theme/config (`globals.css`, `tailwind.config.*`, `theme.ts`), show a diff of what will change and confirm before writing. ### Step 4 — Apply the chosen mapping **Confirmation gate (BLOCKING — do this before scaffolding).** Before running any `shadcn create` / install command, print a recap of the **full resolved configuration** and **wait for the user to confirm or adjust**. Do not scaffold until they say go. Show every value that will be passed to the CLI, including the ones derived from DESIGN.md (so the user sees them even though they weren't prompted): ``` Sto per scaffoldare con shadcn create. Configurazione: • framework : next (App Router) ← stack.framework • base (primitivi): base (Base UI) ← stack.ui_base • base color : neutral ← stack.base_color (poi sovrascritto dai token DESIGN.md) • theme : (dai token DESIGN.md) ← stack.ui_theme • icone : lucide ← stack.icon_library • css variables : on ← stack.css_variables • rtl : no ← stack.rtl • monorepo : no ← stack.framework Confermi, o vuoi cambiare qualcosa? ``` Resolve each value from `meta.json#stack` (with the documented defaults). On "cambia X", update `meta.json#stack` and re-print the recap. Only after explicit confirmation, proceed. For MUI / standalone Base UI, print the equivalent lighter recap (library, framework, base color source) and confirm the same way. **Never scaffold on assumed config.** When `stack.shadcn_preset` is set, run `pnpm dlx shadcn@latest preset decode ` and show the decoded config in the recap (so the user confirms what the preset carries). Read the relevant mapping reference and follow it: - Any conversational surface or rendered markdown → `references/chat-and-typeset.md` (shadcn chat components + typeset + streamdown, the standard — never hand-roll chat or render model markdown as plain text). - shadcn → `references/shadcn-mapping.md`. **Monorepo first:** if `meta.json#stack.framework == "monorepo"` and the monorepo is web-centric (no NativeWind/mobile side — e.g. web-only or web + agent), follow that reference's **"Monorepo (shared `packages/ui`)"** section: scaffold with `shadcn init --monorepo` so primitives land in a shared `packages/ui` (`@workspace/ui`), NOT in `apps/web/components/ui/`. The single-app flow below (and `--no-monorepo`) is for non-monorepo projects (or the web+mobile case where components stay app-local). **Two visual-config paths — they are mutually exclusive:** - **A) Preset path** (when `stack.shadcn_preset` is set): the preset owns the visual layer. Scaffold with `pnpm dlx shadcn@latest init --preset ${stack.shadcn_preset} --template ${framework} --base ${stack.ui_base ?? "base"} --yes`, then `pnpm dlx shadcn@latest add --all --yes`. **Skip `build_registry.py` / the `registry.json` token install** — the preset already encodes colors/theme/fonts/icons/radius. (Helpers: `preset decode` to inspect, `preset url`/`preset open` to view in browser.) - **B) DESIGN.md-first path** (default, no preset): the recommended **token-first install via `registry.json`** (see the dedicated section in that reference). Three steps: scaffold framework → emit `registry.json` from DESIGN.md tokens (use `scripts/build_registry.py`) → run `pnpm dlx shadcn@latest init ./registry.json --yes` followed by `pnpm dlx shadcn@latest add --all --yes`. **`add --all` stays** — every primitive lands in `components/ui/*` and gets customized in the next step per the DESIGN.md `components` block (`cva` edits). - **Pass the create parameters from `meta.json#stack`** (shadcn CLI v4): `--base ${stack.ui_base ?? "base"}` (Base UI / Radix / React Aria primitives), `--base-color ${stack.base_color ?? "neutral"}`, `${stack.css_variables === false ? "--no-css-variables" : "--css-variables"}`, and `--rtl` when `stack.rtl`. The DESIGN.md tokens (via `registry.json`) override base color / theme / fonts, so those flags are only the starting scaffold. **`--base` is NOT overridden by DESIGN.md** — it picks the primitive engine, so honor `stack.ui_base` exactly. If `stack.ui_base` is unset, ask before scaffolding (don't silently pick a base on a fresh project). - Every shadcn block/component exists in both Radix and Base UI variants; once `--base` is set, `shadcn add` pulls the matching variant automatically. - MUI → `references/mui-mapping.md` Each reference describes: - the exact files to write per framework (Next.js / Vite / Remix), - how each token category maps, - which components to install/override (shadcn: `add --all` so the user has the full kit pre-themed; MUI: theme overrides cover all primitives by default), - how to encode the qualitative rules from the markdown body that **can** be expressed in code (e.g. radial background gradients, glass surfaces with backdrop-filter, ambient glow as a custom utility), - what to put in `STYLE_NOTES.md` for the rest (e.g. "Use radial gradients for hero backgrounds — see DESIGN.md §Layout"). The asset templates in `assets/shadcn/` and `assets/mui/` are starting points — read them, fill the placeholders with resolved tokens, write to disk. Do not paste them verbatim if the DESIGN.md doesn't define a value; fall back to library defaults rather than invent. After writing the theme files, also write `_design-md-mapping.json` at the project root. This is a debug artifact: a JSON dump of `{ token_path → resolved_value → library_target }` for every color/typography/component that was mapped, plus the list of fallbacks that were used because the DESIGN.md didn't define a value. Add `_design-md-mapping.json` to `.gitignore` if the user wants to keep it local-only — by default leave it tracked since it's useful for reviewers. ### Step 4.3 — Library primitive priority (mandatory, supersedes custom components) **Rule**: when the chosen UI library (shadcn or MUI) ships a primitive for the pattern, **use it**. Don't roll custom. This is the single most-violated rule in scaffolders. The skill installs `shadcn add --all` (or MUI's full theme), giving the project access to dozens of pre-built, accessible, mobile-aware, theme-integrated primitives — and then the skill writes a custom 100-line `` from scratch using `