Design MD Generator v2

Overview

This skill generates a publication-quality DESIGN.md v2 from a live website URL. The v2 format produces a 17-section document (14 core + 4 optional) that exceeds what any existing AI design system tool generates.

The process has two distinct phases with a hard boundary between them:

Phase 1 -- Deterministic Extraction (scripts) Node.js scripts crawl the site, extract computed styles, capture screenshots, and produce a structured tokens.json file. This phase is mechanical. Every value it produces is ground truth.

Phase 2 -- Semantic Writing (Claude Code) You read the extraction data and screenshots, then write the DESIGN.md. Your job is semantic interpretation: assigning roles to colors, naming typography levels, describing atmosphere, writing do's/don'ts, inferring accessibility contracts, documenting content voice, and composing self-contained agent prompts.

The cardinal rule: ALL numerical values in the final DESIGN.md -- every hex code, every pixel value, every font-weight number, every shadow string, every border-radius -- MUST be copied verbatim from tokens.json or extraction output. You never estimate, round, normalize, or invent values. If a value is not in the extraction data, it does not appear in the DESIGN.md. This is the single most important constraint. Violating it produces phantom values (anti-pattern AP-01) that make the entire document unreliable.

Hex value cardinal rules:

• NEVER use 3-digit hex shortcuts (#000, #fff, #eee). ALWAYS use 6-digit lowercase (#000000, #ffffff, #eeeeee).
• Colors from CSS variables in tokens.json ARE acceptable if the variable name and value are documented in the cssVariables field.
• Before writing ANY hex value, verify it exists in either tokens.colorTokens[].hex or tokens.cssVariables[].value. If not found, do not use it.

What you DO contribute:

• Semantic role assignment (which color is "primary," which is "accent")
• Atmospheric descriptions (what the design feels like, its personality)
• Descriptive color names ("Ship Red" instead of "Red 1")
• Typography role mapping (which extracted size is "Display Hero" vs "Body")
• Named design strategies and principles
• Brand context and personality inference
• Content voice analysis from observed copy
• Accessibility contract inference from observed patterns
• State matrix construction from observed component states
• Icon system identification
• Do's and don'ts derived from observed patterns
• Self-contained agent prompts with all values inlined
• Structural observations (shadow-as-border philosophy, compression-as-identity)

What you NEVER invent:

• Hex values, px values, rem values, font-weight numbers
• Shadow strings, gradient definitions, border-radius values
• Breakpoint widths, spacing scale entries, transition durations
• Font family names, OpenType feature tags
• Button labels, copy text, or any content not observed on the site

Prerequisites

• Node.js >= 18
• Project located at the dmdg/ directory (this repo)
• Playwright with Chromium browser

Auto-install if dependencies are missing:

cd /path/to/dmdg && npm install && npx playwright install chromium

Verify readiness:

cd /path/to/dmdg && npx ts-node scripts/extract.ts --help

If ts-node is not found, install it: npm install -D ts-node typescript.

Execution Mode

FULL AUTO with PARALLEL PIPELINE. Three phases with maximum parallelism. Target: under 4 minutes for any site.

Phase 1: Fast Extract (Orchestrator)

Run extraction with speed-optimized defaults:

cd /path/to/dmdg && npx ts-node scripts/extract.ts <URL> --fast

The --fast flag sets: maxPages=5, noInteraction=true, concurrency=8. This typically completes in 60-120 seconds.

If the user needs interaction states (hover/focus/active), they can re-run later with --with-interaction --merge-with output/<domain>/tokens.json.

After extraction: read tokens.json, check boundary, review extraction report.

Phase 2: Write + Proof in Parallel

Launch ALL of these in a SINGLE message — 10 writing subagents + 1 proof task, all parallel:

10 Writing Subagents (opus model):

Each receives: tokens.json file path + cardinal rules + stability layer rules (L1+L2 only in main content)

Proof Task (run as background Bash command):

cd /path/to/dmdg && npx ts-node scripts/proof.ts <URL> output/<domain>/tokens.json output/<domain>/ &

Proof only needs tokens.json + live site — does NOT need DESIGN.md. Run it during Phase 2 to save ~40 seconds.

Subagent prompt template:

You are writing sections [X, Y, Z] of a DESIGN.md v2 for [site]. Use opus model.

CARDINAL RULES:
- ALL hex values must exist in tokens.colorTokens[].hex or cssVariables[].value — NO EXCEPTIONS
- 6-digit lowercase hex only (#ffffff not #fff)
- Numeric font weights only (400 not "regular")
- Include frequency data for colors/shadows/radius
- Use STABILITY CLASSIFICATION: only L1 (infrastructure) + L2 (system) tokens in main content.
  L3 (campaign) in notes marked "Current campaign — subject to change". L4 (content) excluded entirely.
- Include USE: lines on every component variant with real text
- Use NAMED PRINCIPLES with comparative framing
- Agent prompts must be zero-lookup (every value inlined)

tokens.json is at: [path]

Write ONLY your assigned sections. Output as markdown. Do not include sections assigned to other agents.

Phase 3: Assemble & Deliver (Orchestrator)

After all 10 subagents + proof return:

1. Assemble: Concatenate sections in order with header comment block. Fix any h1→h2 header issues.
2. Machine pre-validation: grep all hex values, verify traceable, fix 3-digit hex / uppercase / phantoms
3. Run validation: npx ts-node scripts/validate.ts — if score < 80, auto-fix and re-run
4. Generate preview: npx ts-node scripts/preview-gen.ts
5. Generate report (proof-data.json already exists from parallel proof): npx ts-node scripts/report-gen.ts
6. Open report: open output/<domain>/report.html
7. Present summary:

   ✅ Generation complete for [Site].
   Quality: [score]/100 | Fidelity: [coverage]%
   Colors: [N] (L1: [n], L2: [n], L3: [n] campaign) | Typography: [N] | Components: [N]
   DESIGN.md: [lines] lines | Time: [total]s
   📄 report.html opened in browser.
   

Fallback: Sequential Mode

If subagent launching is not available (Cursor, Codex, etc.), run Steps 5-20 sequentially within a single context. Add --with-interaction to extraction for full state capture since there's no parallel time saving to protect.

Step 1: Run Extraction

Command:

cd /path/to/dmdg && npx ts-node scripts/extract.ts <URL> --output output/<domain>/

Replace <URL> with the target website (e.g., https://vercel.com) and <domain> with the domain name (e.g., vercel).

Expected time: 30-60 seconds for a typical site. Sites with many pages or heavy Java