Skip to main content
skill CX Codex

design-md · shuaimxu — Claude Code skill: managing design documentation

The design-md skill for Claude Code generates a DESIGN.md file, acting as a living design-language contract. It audits your codebase to define UI rules for AI agents and developers.

MIT ★ 529 updated 2026-11-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ShuaiMXu/happyhands --skill design-md -a claude-code
Open on GitHub

What design-md does

This skill classifies your repository to determine whether to extract an existing style, merge it with current documentation, or propose a new visual direction. When proposing a design for greenfield projects, the agent drafts a proposal and requires user approval before proceeding.

It produces a central DESIGN.md file containing token, font, component, and motion specifications, alongside a portable frontend-design craft skill. The agent adheres strictly to the existing codebase, citing specific files for every claim, and ensures that it never restyles UI elements without an explicit instruction from the user.

What it helps with

  • generate design documentation from codebase
  • sync design docs with actual implementation
  • standardize UI rules for AI agents
  • prepare project for design scaling

Example prompts for the agent

  • /plugin:design-md add a DESIGN.md
  • /plugin:design-md document our design language
  • /plugin:design-md bootstrap design

How to install design-md

1Skills CLI (Vercel)

npx skills add ShuaiMXu/happyhands --skill design-md -a claude-code

2Manually: put the files in place

~/.claude/skills/design-md/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-md/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about design-md

How to install design-md in Claude Code?

Run npx skills add ShuaiMXu/happyhands --skill design-md -a claude-code. The skill will be installed at ~/.claude/skills/design-md/SKILL.md.

What does design-md do?

It creates a living DESIGN.md contract that provides AI agents and humans with clear instructions on how the project's UI is built based on existing evidence.

What is required to use design-md?

No specific API keys are needed, but the project must have an existing UI codebase so the agent can perform an audit of your design patterns.

Source text

SKILL.md · MIT
---
name: design-md
description: Create or update a repo's DESIGN.md — a living design-language contract for AI agents and humans — plus a portable frontend-design skill. Classifies the repo first (document an existing design language, merge with existing design docs, or propose a new direction with user approval) so it never overwrites a project's current design. Use when setting up design docs for a frontend project. Triggers on "add a DESIGN.md", "document our design language", "set up design docs", "create a design system doc", "bootstrap design".
license: MIT
metadata:
  version: "1.0.0"
---

# Design Language Doc (DESIGN.md)

You are creating this repository's design-language contract: a root `DESIGN.md` that tells agents and humans exactly how UI is built here, plus a portable `frontend-design` craft skill. The doc is **downstream of the code** — you describe the design language that exists, or propose one with user approval. You never invent a design language and present it as fact, and you never restyle existing UI to match a doc.

## Goal

1. Root `DESIGN.md` — the repo's design language, written from evidence, citing real files and tokens
2. `.agents/skills/frontend-design/SKILL.md` — portable craft doctrine (typography, surfaces, motion) that applies to any repo
3. A link from `AGENTS.md` so agents find the design language within one hop

## Reference templates

| File | Used for |
|------|----------|
| `references/design-md-template.md` | `DESIGN.md` skeleton, filled from evidence |
| `references/skill-frontend-design.md` | `.agents/skills/frontend-design/SKILL.md` (create verbatim) |

## Phase 0: Audit, then classify (before writing anything)

Gather evidence. Every claim in `DESIGN.md` must trace back to something you saw here:

- [ ] `package.json`: framework, UI libraries (react/vue/svelte, tailwind, shadcn, radix/base-ui, motion/framer-motion, lucide, fonts packages)
- [ ] Token layer: `globals.css` / `tailwind.config.*` / theme files — CSS variables, `@theme` blocks, custom utilities (shadows, radii, animations)
- [ ] Fonts: how they're loaded (`next/font`, `@font-face`, link tags), which families, which roles
- [ ] Component system: `components/ui/`, shared primitives, variant patterns (cva, variants props)
- [ ] Motion: keyframes, transition utilities, motion-library usage, `prefers-reduced-motion` handling
- [ ] The 3–5 most polished surfaces in the app — these define the *actual* design language, whatever the tokens claim
- [ ] Existing design docs: `DESIGN.md`, `docs/design*`, brand guidelines, Figma links in READMEs, design-related Cursor rules or agent docs

Then classify the repo into exactly one mode:

### Mode A — Document (established design language, no design doc)

The repo has consistent tokens, deliberate font choices, a component system, recurring motifs. Your job is **extraction**: write `DESIGN.md` describing what exists, citing the files that prove it. Nothing about the actual design changes. Where the codebase is internally inconsistent, document the dominant/most-recent pattern and note the deviation — do not resolve it by fiat.

### Mode B — Merge (design docs already exist)

A `DESIGN.md`, brand guide, or design-related rules already exist. **Merge, never regenerate**: preserve every unique local rule, deduplicate against the template structure, keep one source of truth, and leave pointers behind if you consolidate scattered docs. If existing docs contradict the code, flag the contradiction to the user instead of silently picking a side.

### Mode C — Propose (greenfield, no coherent design language)

No established language exists. Choosing an aesthetic direction is a **user-owned decision**, not an evidence question. Write a one-page proposal to `docs/plans/design-language.md` (or `PLAN.md` if the repo has no `docs/plans/`) covering: aesthetic direction and tone, font pairing (display + body), color approach and the accent budget, elevation strategy, motion approach. Offer 2–3 distinct directions if the product context supports them. **Stop and get user approval before writing `DESIGN.md`.** After approval, write the full doc from the approved proposal.

## Deliverables

```
DESIGN.md                              # root design-language contract (living document)
.agents/
  skills/
    frontend-design/SKILL.md           # portable craft doctrine (references/skill-frontend-design.md)
docs/
  plans/
    design-language.md                 # Mode C only: the approved proposal
```

Plus one edit: add `- [Design Language](DESIGN.md)` to the Quick Links in `AGENTS.md` (create the section if the repo has an `AGENTS.md` without it; skip if there is no `AGENTS.md`).

## Process (in order)

1. **Phase 0** audit and classification (checklist above)
2. Mode C only: write the proposal, present it, and **wait for approval**
3. Write `DESIGN.md` using `references/design-md-template.md` as structure — filled from evidence (Modes A/B) or the approved proposal (Mode C)
4. Create `.agents/skills/frontend-design/SKILL.md` verbatim from `references/skill-frontend-design.md` (stripping the template preamble), unless the repo already has an equivalent craft skill — then skip it
5. Link `DESIGN.md` from `AGENTS.md` Quick Links
6. Run the **verification pass** below
7. Report: mode chosen and why, files created, contradictions found between docs and code, rules preserved from pre-existing docs

## Writing rules for DESIGN.md

- **Cite real files.** Every token, utility, font, and component pattern named in the doc must link to the file that defines it
- **Name the budgets.** Great design languages are mostly restraint — make limits explicit ("one accent pairing per view", "at most one display-font moment per page"), because agents follow budgets better than vibes
- **Include the one-liner.** A blockquote near the top that compresses the whole language into one paragraph an agent can carry to another surface
- **End with a per-page checklist** of verifiable items, phrased so an agent can self-review against them
- **Sizes over adjectives.** "`rounded-3xl` cards, `rounded-full` CTAs" beats "generously rounded"
- Semantic tokens over hardcoded values everywhere the repo's token system reaches; name the sanctioned exceptions explicitly

## Constraints

- **Never restyle existing components to match `DESIGN.md`.** The doc describes or proposes; it does not authorize a refactor. If the user wants the UI brought in line with the doc, that is a separate, explicit task
- In Modes A and B, do not "improve" the design language while documenting it — record improvement ideas at the end under a clearly-marked "Open questions" section instead
- Do not copy another product's design language (fonts, palettes, motifs) into `DESIGN.md` unless verified in THIS repo or approved in the Mode C proposal
- Prefer an accurate short doc over an impressive long one — an agent that trusts a wrong design doc produces confidently wrong UI
- Match the repo's markdown tone and formatting

## Verification pass (required before finishing)

- [ ] Every file path referenced in `DESIGN.md` resolves to an existing file
- [ ] Every token, utility class, and font named in the doc exists in the codebase (grep for it)
- [ ] Modes A/B: no rule in the doc contradicts what the most polished surfaces actually do
- [ ] Mode B: every unique rule from the pre-existing docs survived the merge (diff them)
- [ ] Mode C: the doc matches the approved proposal; the proposal file exists in `docs/plans/`
- [ ] The `AGENTS.md` link resolves
- [ ] The checklist at the end of `DESIGN.md` contains only items an agent can verify from code

## Done when

- An agent building UI in this repo can answer "what fonts, what tokens, what radii, what shadows, what motion?" from `DESIGN.md` alone, one hop from `AGENTS.md`
- The user's existing design decisions are intact — nothing was overwritten, and any new direction was explicitly approved
- The portable `frontend-design` craft skill is installed
- Every doc statement is evidence-backed (or approval-backed) and the verification pass is clean

© ShuaiMXu · MIT · ShuaiMXu/happyhands

Similar skills

All skills for Agent setup: memory, context, orchestration →

design-md by other authors comes first.

design-md official google-labs-code Extracts screens and styles from Google Stitch via MCP to synthesize a semantic design system into a DESIGN.md file. CX Codex +1 67,200installs design-md nexu-io design-md is a Claude Code skill that creates and maintains DESIGN.md files for design direction, tokens, and visual rules. It activates for requests about design docs or token documentation. CX Codex +1 3,300installs design-md Hermes Agent Create and validate DESIGN.md token specs, compare revisions, and export design tokens to Tailwind or W3C DTCG formats. CX Codex +1 541installs design-system-adoption Owl-Listener design-system-adoption is a Claude Code skill that builds an adoption strategy and team enablement materials for a design system. Use it when the system exists but teams ignore it. CX Codex +1 2,400installs design-flow julianoczkowski design-flow walks you from clarifying questions to built components across six phases, confirming before each next step. CX Codex +1 5,500installs design-brief julianoczkowski Interviews you about a feature, scans the codebase, and saves a design brief as markdown. Useful before you start building a page. CX Codex +1 5,500installs design-handoff official anthropics design-handoff turns a Figma file or a written design description into a developer handoff spec: measurements, tokens, states, breakpoints, edge cases. CX Codex +1 4,000installs frontend-design mager frontend-design — a skill that gives the agent a specific design stance: type, palette, tactile states. Useful when building a UI from scratch or restyling an existing one. CX Codex +1 1,700installs awesome-design-md wearescientist awesome-design-md picks a matching DESIGN.md style from a bundled library and applies it to frontend work: layout, color, type, spacing. CX Codex +1 1,100installs

From the same set34

The whole set →
component-state-auditor The component-state-auditor skill for Claude Code compares documented component states against a versioned rubric in rubric.json. It identifies missing states during UI development and review. CX Codex +1 ★ 529repo stars visual-hierarchy-reviewer visual-hierarchy-reviewer is a Claude Code skill that reviews task hierarchy and design language from screenshots. It runs on interface reviews, including requests to reduce an AI-made look while keeping the product’s brand. CX Codex +1 ★ 529repo stars review-video review-video is a Claude Code skill that inspects and repairs product or promotional videos using original assets, before/after evidence, and timeline reviews. Runs during video audits and defect fixes. CX Codex +1 ★ 529repo stars happyhands happyhands is a Claude Code skill that investigates a specific UI or product-experience issue and guides a repair. Explicit requests for product or promotional video work go through a separate timestamped workflow. CX Codex +1 ★ 529repo stars frontend-design The frontend-design skill for Claude Code enforces interface styling and typography standards. It runs during the creation or review of web UI components. CX Codex +1 ★ 529repo stars review-product review-product is a Claude Code skill that examines one important user task in an existing app. It identifies a possible UX change and checks the result against the original state. CX Codex +1 ★ 529repo stars happyhands-ui happyhands-ui is a Claude Code skill for applying HappyHands rules to UI copy, color, typography, and interactions. It runs during implementation or review of HappyHands interfaces and projects that have adopted the profile. CX Codex +1 ★ 529repo stars experience-remediation The experience-remediation skill for Claude Code executes UI and UX repairs. It runs to fix layout flaws and interaction issues based on project-specific rules. CX Codex +1 ★ 529repo stars

Project sponsors

Companies that keep this analytics open