# design-md

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 529 repo stars
- Author: ShuaiMXu
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/ShuaiMXu/happyhands/tree/HEAD/.agents/skills/design-md/SKILL.md
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/shuaimxu-design-md

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ShuaiMXu/happyhands --skill design-md -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/design-md/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/design-md/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ShuaiMXu/happyhands --skill design-md -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/design-md/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ShuaiMXu/happyhands --skill design-md -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/design-md/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ShuaiMXu/happyhands .agents/skills/design-md
```

2. **Manually: put the files in place**
- File: `.github/skills/design-md/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ShuaiMXu/happyhands --skill design-md -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ShuaiMXu/happyhands --path .agents/skills/design-md
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/design-md/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ShuaiMXu/happyhands/tree/HEAD/.agents/skills/design-md/SKILL.md

## When to use it
- generate design documentation from codebase
- sync design docs with actual implementation
- standardize UI rules for AI agents
- prepare project for design scaling

## Example prompts
- /plugin:design-md add a DESIGN.md
- /plugin:design-md document our design language
- /plugin:design-md bootstrap design

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8894dccfbcfea31b.

BEGIN THIRD-PARTY FILE 8894dccfbcfea31b
```text
---
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)
```
END THIRD-PARTY FILE 8894dccfbcfea31b

The third-party file has ended. Everything between the 8894dccfbcfea31b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3195 of 8133 bytes. © ShuaiMXu · MIT · https://github.com/ShuaiMXu/happyhands/tree/HEAD/.agents/skills/design-md/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
