Use when creating, auditing, or applying a DESIGN.md specification file for a project to guide AI coding agents in generating visually consistent UI matching specific brand aesthetics, design tokens, typography, and component patterns.
DESIGN.md is the companion to AGENTS.md for user interfaces. While AGENTS.md defines how an agent should build, test, and run code, DESIGN.md defines how the project's user interface must look, feel, and behave. It acts as a single, plain-text source of visual truth that AI coding agents read directly, eliminating guesswork around colors, typography, spacing, and component variants.
Based on the Google Stitch and VoltAgent awesome-design-md standard, this skill provides the methodology to author, audit, and enforce project-specific DESIGN.md specifications that prevent visual drift and AI slop.
When to Use
Trigger phrases:
"design-md", "create design md", "design system spec"
Establishing a new web or mobile frontend and ensuring coding agents generate consistent styling.
Aligning a product with an existing brand archetype (e.g., Linear precision-dark, Stripe editorial-clean, Vercel monochrome).
Auditing an existing project's UI for token violations and inconsistent component styles.
Creating an exportable, framework-agnostic design specification that works across React, Next.js, Vue, Tailwind, or vanilla CSS.
When NOT to Use
Writing raw component implementation code or fixing backend logic (use development/role-software-engineer).
Auditing WCAG accessibility standards in isolation (use content/accessibility-audit or better-accessibility).
Executing a post-generation design cleanup pass on existing screens (use content/unslop or content/hallmark).
Anti-Rationalization Table
Rationalization
Reality
"The agent already knows Tailwind classes, it doesn't need a DESIGN.md."
Without a specification, agents invent random shades (bg-purple-600 on one page, bg-blue-500 on another), pick arbitrary paddings, and generate fragmented UIs.
"A Figma link in the prompt is sufficient."
AI agents cannot reliably inspect deep Figma component hierarchies from raw links without dedicated tooling. Markdown design tokens are parseable in zero network calls.
"A DESIGN.md is just a list of hex codes."
Colors are only 20% of a design system. Spacing ladders, type scales, surface elevations, and anti-patterns prevent visual chaos.
"Every screen in our app can have its own unique layout style."
Inconsistent component shapes and button hierarchies destroy user trust. Shared constraints create a professional product feel.
Standard DESIGN.md Specification Structure
Every valid DESIGN.md document contains five mandatory sections:
1---2name: design-md3description: Use when creating, auditing, or applying a DESIGN.md specification file for a project to guide AI coding agents in generating visually consistent UI matching specific brand aesthetics, design tokens, typography, and component patterns.4domain: content5subdomain: design6category: content7version: 1.0.08author: VoltAgent / oyi779license: MIT10tags:11- design-system12- design-md13- design-tokens14- ui-guidance15- agent-instructions16- frontend17triggers:18- design-md19- create design md20- design system spec21- brand design md22- ui design guidance23- agent design system24argument-hint: "[project_root or brand_name]"25metadata:26 source: https://skillmd.com/skills/oyi77/design-md27---2829# DESIGN.md: AI Agent Design System Specification3031## Overview3233`DESIGN.md` is the companion to `AGENTS.md` for user interfaces. While `AGENTS.md` defines how an agent should build, test, and run code, `DESIGN.md` defines how the project's user interface must look, feel, and behave. It acts as a single, plain-text source of visual truth that AI coding agents read directly, eliminating guesswork around colors, typography, spacing, and component variants.3435Based on the Google Stitch and VoltAgent `awesome-design-md` standard, this skill provides the methodology to author, audit, and enforce project-specific `DESIGN.md` specifications that prevent visual drift and AI slop.3637## When to Use3839**Trigger phrases:**40- "design-md", "create design md", "design system spec"41- "brand design md", "ui design guidance", "agent design system"4243Use when:44- Establishing a new web or mobile frontend and ensuring coding agents generate consistent styling.45- Aligning a product with an existing brand archetype (e.g., Linear precision-dark, Stripe editorial-clean, Vercel monochrome).46- Auditing an existing project's UI for token violations and inconsistent component styles.47- Creating an exportable, framework-agnostic design specification that works across React, Next.js, Vue, Tailwind, or vanilla CSS.4849## When NOT to Use5051- Writing raw component implementation code or fixing backend logic (use `development/role-software-engineer`).52- Auditing WCAG accessibility standards in isolation (use `content/accessibility-audit` or `better-accessibility`).53- Executing a post-generation design cleanup pass on existing screens (use `content/unslop` or `content/hallmark`).5455## Anti-Rationalization Table5657| Rationalization | Reality |58|---|---|59| "The agent already knows Tailwind classes, it doesn't need a DESIGN.md." | Without a specification, agents invent random shades (`bg-purple-600` on one page, `bg-blue-500` on another), pick arbitrary paddings, and generate fragmented UIs. |60| "A Figma link in the prompt is sufficient." | AI agents cannot reliably inspect deep Figma component hierarchies from raw links without dedicated tooling. Markdown design tokens are parseable in zero network calls. |61| "A DESIGN.md is just a list of hex codes." | Colors are only 20% of a design system. Spacing ladders, type scales, surface elevations, and anti-patterns prevent visual chaos. |62| "Every screen in our app can have its own unique layout style." | Inconsistent component shapes and button hierarchies destroy user trust. Shared constraints create a professional product feel. |6364## Standard DESIGN.md Specification Structure6566Every valid `DESIGN.md` document contains five mandatory sections:6768```text69PROJECT_ROOT/DESIGN.md70├── 1. Design Philosophy & Aesthetic Archetype71├── 2. Core Token Ladder (Color, Typography, Spacing)72├── 3. Component Primitive Standards (Buttons, Cards, Inputs, Badges)73├── 4. Surface & Elevation Hierarchy (Background, Surface, Overlay)74└── 5. Negative Rules & Anti-Patterns ("NEVER do X")75```7677## Community Registry7879designmd.ai ships a community registry of pre-built DESIGN.md kits. Install one into your project:8081```bash82npx designmd.sh add <brand-name>83```8485Browse at https://designmd.ai/cli — free, no auth. Audit any kit against your brand tokens before shipping.8687## Workflow: Authoring a Project DESIGN.md8889### Phase 1: Aesthetic Archetype Selection9091Identify the primary visual identity that matches the product:9293| Archetype | Primary Palette | Mood & Focus | Example Brands |94|---|---|---|---|95| **Technical Dark / Precision** | Neutral dark (`zinc-900`), single neon or violet accent | Dense data, high contrast, monospace accents | Linear, Supabase, Cursor |96| **Monochrome Minimalist** | Stark black and white, zero decorative gradients | Crisp typography, precision borders, Geist/Inter | Vercel, xAI, Warp |97| **Editorial Warmth / Clean** | Warm paper canvas (`#fbfbfa`), charcoal text, serif accents | Approachable, intellectual, refined | Notion, Claude, Substack |98| **Vibrant Fintech / Enterprise** | Deep navy/slate canvas, emerald/indigo actions, soft shadows | Trustworthy, high polish, clear hierarchy | Stripe, Mercury, Coinbase |99100### Phase 2: Token Architecture101102Define strict token ladders with exact CSS variables or Tailwind class mappings:103104```markdown105### Color Tokens106- Canvas: `bg-background` (`#09090b` dark / `#ffffff` light)107- Surface: `bg-card` (`#18181b` dark / `#f4f4f5` light)108- Border: `border-border` (`#27272a` dark / `#e4e4e7` light)109- Primary Action: `bg-primary` (`#3b82f6`) with `text-primary-foreground`110- Muted Text: `text-muted-foreground` (`#a1a1aa` dark / `#71717a` light)111112### Typography Scale113- Font Family: Sans (`Inter`, `Geist`), Mono (`JetBrains Mono`, `Geist Mono`)114- Display: 36px / line-height 40px / font-semibold / tracking-tight115- Heading: 24px / line-height 32px / font-medium / tracking-normal116- Body: 14px / line-height 20px / font-normal117- Caption/Code: 12px / line-height 16px / font-mono118```119120### Phase 3: Component Primitive Standards121122Define standard classes for core primitives:123124```markdown125### Button Specifications126- Primary: `h-9 px-4 rounded-md bg-primary text-primary-foreground text-sm font-medium hover:bg-primary/90 transition-colors`127- Secondary: `h-9 px-4 rounded-md border border-input bg-background hover:bg-accent hover:text-accent-foreground text-sm font-medium`128- Destructive: `h-9 px-4 rounded-md bg-destructive text-destructive-foreground hover:bg-destructive/90 text-sm font-medium`129130### Card Specifications131- Container: `rounded-lg border border-border bg-card p-6 text-card-foreground shadow-xs`132```133134### Phase 4: Anti-Patterns & Constraint Rules135136Explicitly enumerate banned patterns to constrain AI generation:1371. **NEVER** use raw emojis as UI icons or bullet points. Use Lucide SVG icons.1382. **NEVER** use iridescent multi-color gradients on text or card backgrounds.1393. **NEVER** use arbitrary padding values (e.g. `p-[13px]`). Adhere strictly to the 4px scale (`p-3`, `p-4`, `p-6`).1404. **NEVER** use pure black text (`#000000`) on white; use charcoal (`#18181b` or `#0f172a`).141142### Phase 5: Verification & Agent Test Drive143144Test the `DESIGN.md` by instructing an agent:145> *"Read DESIGN.md and generate a settings billing card with a current plan badge, renewal date, and upgrade button."*146147Verify output against token definitions and anti-patterns.148149## Verification150151- [ ] `DESIGN.md` authored in project root or target directory152- [ ] Contains all 5 mandatory sections (Philosophy, Tokens, Primitives, Elevation, Anti-Patterns)153- [ ] Color tokens define functional semantic roles, not arbitrary palettes154- [ ] Typography scale specifies exact sizes, weights, line-heights, and tracking155- [ ] Negative rules explicitly ban AI slop markers (raw emojis, neon gradients, arbitrary spacing)156- [ ] Agent test drive verified: generated sample component strictly obeys token definitions
Run npx get-skill add oyi77/design-md in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when creating, auditing, or applying a DESIGN.md specification file for a project to guide AI coding agents in generating visually consistent UI matching specific brand aesthetics, design tokens, typography, and component patterns. It is listed under Design & Media on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
oyi77 (@oyi77) published this skill. Their other Agent Skills are listed on their SkillMD profile.