Design System Extractor (md-generator)
Captures a live website's real, measured CSS into a publication-quality DESIGN.md — a v3 Style Reference.
It is a named, role-driven, ship-ready design-system handoff: named colour tokens, semantic type scale, named components, Surfaces, Elevation, Agent Prompt Guide, Similar Brands, and copy-paste Quick Start CSS + Tailwind.
AI agents build against it without hallucinating colors, fonts, spacing, or shadows.
It runs a three-phase pipeline (extract, write, validate) through an embedded Playwright crawler that samples five viewports and emits verbatim tokens.json.
Deep operational detail lives in references/.
Boundary. This skill is the extraction and format-fidelity engine for design references. It captures what already exists.
It does not decide values for a surface that does not exist yet. That work belongs to sk-code-frontend, which the sk-code hub bundles for visual decisions.
The transport mcp-figma moves design data. This skill produces the authoritative measured reference that transport and downstream implementers (sk-code) consume.
When both apply to the same surface, this reference outranks sk-code-frontend's defaults. Where no measurement exists, sk-code-frontend decides.
1. WHEN TO USE
Activation Triggers
Use when the user wants to:
- Extract a live website's real CSS into a machine-readable
DESIGN.md v3 Style Reference, with every hex, pixel, font-weight, radius, and shadow copied verbatim from the running page.
- Produce a hallucination-proof design document for an AI agent to code against —
DESIGN.md replaces guesses with measured ground truth.
- Capture colors (including dark-mode palette if detected), typography stacks, shadows, border-radii, spacing scales, CSS custom properties, framework markers, icon-system hints, motion tokens, and a11y data across five responsive viewports.
- Validate a generated
DESIGN.md against its source tokens.json to confirm hex accuracy and section completeness.
- Generate visual validation reports (HTML preview, diff report) from a
DESIGN.md + tokens.json pair.
- Re-extract a site after a redesign to update the design-system reference.
Keyword Triggers: "extract design system", "generate DESIGN.md", "capture website css", "design tokens from url", "create design reference", "style reference", "tokens.json", "validate DESIGN.md", "anti-hallucination design doc", "design-to-markdown", "extract design tokens".
Use Cases
Full extraction — URL to DESIGN.md. The canonical workflow: crawl a live URL, produce tokens.json, write DESIGN.md output conforming to the v3 Style Reference format, then validate hex accuracy, section completeness, and Quick-Start fidelity. This is the primary path.
Validation-only. The user already has a DESIGN.md + tokens.json pair (from a prior extraction or hand-edited) and wants to confirm fidelity. Run the validator without re-extracting.
Visual report generation. Given a DESIGN.md + tokens.json pair, render an HTML preview and a visual-diff report to confirm the written doc matches the extracted tokens.
Example study. The user wants to understand how a gold-standard site (stripe, vercel, linear, supabase — included in references/examples/) structures its DESIGN.md output, to inform a new extraction or to learn the format conventions.
When NOT to Use
Skip this skill when:
- The task is inventing a new design direction (palette, type scale, the anti-default critique). That is out of scope — this skill captures measured reality, it does not create new direction.
- The task is authoring a Style Reference from a brief alone with no live site to measure. That is forward-authoring and OUT OF SCOPE for this mode.
This mode reports what is measurably there.
A brief-only request that does not name this mode's artifact uses a different contract. Route it to
sk-code-frontend through the sk-code hub, and never loosen fidelity here to satisfy it.
references/authoring-boundary.md draws the line between measured values and a brief's stated intent.
- The target is a Figma file, not a live website. Use
mcp-figma to extract from Figma Desktop.
- The user only wants a screenshot or visual preview of a page. Use
mcp-chrome-devtools.
- The website cannot be reached (requires a live, renderable URL with JavaScript execution).
2. SMART ROUTING
The sk-design hub's sk-design-md-generator signal selects this packet, so its SKILL.md loads first.
A request selects it by naming DESIGN.md, tokens.json, a style reference, CSS capture, validation or a report measured from a live site or an existing pair.
A brief-only request naming DESIGN.md still lands here for its authoring-boundary refusal.
Load references/design-md-format.md first, then the resources the detected phase names.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
The Three-Phase Pipeline
Every extraction runs as a sequential pipeline. No phase can be skipped in a full run, though VALIDATE and REPORT can be invoked standalone on an existing DESIGN.md + tokens.json pair.
Process Flow: EXTRACT (Phase 1) → WRITE (Phase 2) → VALIDATE (Phase 3) → REPORT (Phase 4, optional)
- EXTRACT — Playwright crawls 5 viewports, collecting computed CSS (colors, typography, shadows, radii, spacing, CSS variables), measured image-edge outlines, nested/concentric radii, root font smoothing, and hit-target affordances when present, plus dark-mode/framework/icon/motion/a11y signals. Every token is tagged with a stability class (L1–L4, see below). Output:
tokens.json.
- WRITE — Run
build-write-prompt.ts first. It pre-renders the value tables (Tokens — Colors, Spacing & Shapes, Surfaces, Quick Start) and a FACTS block deterministically from tokens via formatters-v3.ts (doc-as-view, no AI on the value tables).
Paste those sections unchanged. Write prose only: intro, Typography role prose, Components, Do's/Don'ts, Elevation, Imagery, Layout, Agent Prompt Guide, and Similar Brands. Follow the voice in references/writing-style-guide.md.
Elevation renders FLAT when there are 0 shadow tokens. Output: DESIGN.md.
- VALIDATE —
validate.ts checks hex accuracy, v3 section completeness, Quick-Start fidelity, and prose provenance (see "What validate.ts traces" below). Output: pass/fail with a dual score and per-finding messages.
- REPORT (optional) —
report-gen.ts and preview-gen.ts render visual artifacts (HTML report, preview) for human review.
Full phase-by-phase actions and handoff: references/extraction-workflow.md.
Procedure Card Selection
After the hub selects the public md-generator mode, choose the private procedures/design-system-extraction.md card when a request involves any of these:
- Measured extraction, token capture, CSS capture,
DESIGN.md generation, source design systems, screenshots, brand references, gaps, inconsistencies, or grounding future work in an existing surface.
Cite that card by relative path in the plan or proof line.
It supports this mode but is not a public route.
If the card does not match, state Procedure applied: none - baseline md-generator pipeline and continue with phase detection (EXTRACT_WRITE, VALIDATE, REPORT, STUDY) plus the existing resource router.
Backend Boundary Preservation
Procedure support does not replace or generalize the extraction backend.
design-md-generator remains the only mutating sk-design mode. It has backendKind: playwright-extract, Write/Edit/Bash permission, and the embedded TypeScript pipeline under backend/scripts/.
The protected entrypoints are extract.ts, build-write-prompt.ts, validate.ts, report-gen.ts, preview-gen.ts, and proof.ts.
Package-level verification remains npm run typecheck, npm run build, and npm test from backend/ when operator policy allows those commands.
The procedure card can shape planning and proof, but it must not flatten this skill into read-only guidance or alter its owned extract-write-validate write boundary.
Context, Proof, And Direct Fallback
Before extraction or validation, record the context basis:
- Public mode
md-generator, selected procedure card or no-procedure fallback, pipeline phase, source type, target URL or artifact, output paths, tool-readiness state, loaded references, and value-origin risks.
Before any completion claim, include proof naming:
- The selected procedure card, backend entrypoint used,
tokens.json/DESIGN.md provenance, validation result, and unresolved gaps.
If subagents are unavailable or disallowed, execute directly in the current session using this mode's normal backend boundary. Direct fallback does not weaken the pipeline: full extraction still requires extract, write, and validate; validation-only and report-only paths still use their dedicated backend entrypoints.
Cardinal Fidelity Rule
Every hex code, pixel value, font weight, box shadow, border radius, and spacing value in DESIGN.md MUST be copied verbatim from tokens.json. No estimation, no rounding, no invention, no "close enough" substitution. This is the single non-negotiable contract of the skill — it is what makes DESIGN.md a hallucination-proof reference.
- Hex codes must use 6-digit lowercase format (e.g.,
#1a1a2e, never #1A1A2E or #1a1a2).
- Stability gates: only L1 (permanent/brand-level) and L2 (system/component-level) tokens belong in the main DESIGN.md sections. L3 (campaign-level, e.g., a seasonal accent color) may appear with an explicit "Subject to change" annotation. L4 (content-level, e.g., a hero image's dominant color) is excluded.
- Dark mode: include a dark-mode section ONLY when the extractor detected a dark-mode palette. Do not fabricate a dark palette from the light one.
- What
validate.ts traces:
- Validation hard-checks hex codes against
tokens.colorTokens and Quick Start values. Every Quick Start hex traces to a token; --page-max-width matches tokens.spacingSystem.maxContentWidth.
- Non-hex values (pixel sizes, font weights, shadows, radii) are NOT re-traced by the validator.
- Their fidelity is guaranteed upstream. The WRITE phase pre-renders the value tables from
formatters-v3.ts and supplies the typography/component numbers verbatim in the FACTS block, so the AI never types them.
- The cardinal rule binds those values even though validation does not re-check each one.
Authoring Boundary
The cardinal rule stays enforceable by inspection because every value has a legible origin.
A value is:
- measured (read off the page and present in
tokens.json)
- brief-provided (supplied by the user, not the page)
- inferred (a grounded characterization of a measured value)
- absent (never captured)
Only measured values enter the token tables, unlabeled. An unlabeled value is a promise it was measured.
Brief-provided values stay in prose as a stated intent and never sit in a value table.
Inferred claims carry [INFERRED] and cite the measured token they rest on. Absent values are stamped or omitted, not backfilled.
This boundary adds no capability and relaxes the fidelity contract by not one digit.
When a value's origin is unclear, or a request asks to author from a brief with no live site, load references/authoring-boundary.md for the full line and assets/source-of-truth-router-card.md to sort each value before writing.
Authoring from a brief alone is forward-authoring and stays out of scope (Section 1, When NOT to Use).
Invocation
Working directory. One-time setup runs from backend/. Every pipeline script runs from the repo root with the full script path — extract.ts refuses any --output that resolves inside the skill, so a relative specs/... path only resolves correctly from there. Full phase-by-phase actions: references/extraction-workflow.md. Complete flag reference: backend/README.md.
# One-time setup
cd .skilled/skills/sk-design/sk-design-md-generator/backend && npm install && npx playwright install chromium
# Phase 1 — extract (writes tokens.json to --output)
npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/extract.ts <url> --fast --output specs/<track>/<packet>/output
# Phase 2 — pre-render value tables + FACTS block, then write DESIGN.md prose
npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/build-write-prompt.ts specs/<track>/<packet>/output/tokens.json
# Phase 3 — validate (DESIGN.md first, tokens.json second)
npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/validate.ts <DESIGN.md> specs/<track>/<packet>/output/tokens.json
Optional Phase 4 (from the repo root, tokens.json first): proof.ts <url> <tokens.json>, report-gen.ts <tokens.json> <dir> <DESIGN.md>, preview-gen.ts <tokens.json> <dir>. Interaction capture is default-on; opt out with --no-interaction or --fast-no-interaction.
Token Stability Classes (L1–L4)
The deterministic classifier in backend/scripts/cluster.ts classifies each token from L1 (Permanent/infrastructure) through L4 (Content/content).
L1+L2 populate the main DESIGN.md sections. L3 gets a "Subject to change" annotation; L4 is excluded entirely.
Boundary tokens take the higher (more restrictive) class.
See references/extraction-workflow.md (Section 3) for the full class table, emitted stability.layer string mapping, and coverage-election pre-gate.
4. RULES
✅ ALWAYS
- ALWAYS read
references/design-md-format.md and references/writing-style-guide.md before writing DESIGN.md. These define the v3 Style Reference section specification and the voice/tone rules. No DESIGN.md is conformant without them.
- ALWAYS copy every numeric CSS value verbatim from
tokens.json. Hex colors, pixel sizes, font weights, box shadows, border radii, spacing values — every number must match tokens.json exactly. This is the cardinal fidelity rule.
- ALWAYS use 6-digit lowercase hex for every color in DESIGN.md (e.g.,
#1a1a2e, never #1A1A2E, #333, rgb(), or hsl()).
- ALWAYS apply stability gates: L1 and L2 colours in the main token table; L3 colours in the "Current Campaign Colors (Subject to change)" sub-table; L4 tokens excluded entirely.
- ALWAYS run
validate.ts before claiming completion of any extraction or DESIGN.md edit.
Validation checks hex accuracy against tokens.json, v3 Style Reference section completeness, Quick-Start fidelity, and prose provenance.
Every Quick Start hex traces to a token, and --page-max-width matches tokens.json.
The gate passes only with zero hard failures in the target, schema, and provenance categories.
valuesScore and claimsScore print as information.
- ALWAYS include a dark-mode section ONLY when
tokens.json contains a detected dark-mode palette. Never infer, derive, or fabricate a dark palette from the light tokens.
- ALWAYS include an accessibility section drawn from the
tokens.json a11y data (contrast ratios, focus ring styles, minimum touch-target sizes). If the extractor captured no a11y data, note the absence rather than inventing values.
- ALWAYS confirm tool readiness before any extract/validate/report invocation:
cd backend && npm install && npx playwright install chromium. The embedded tool requires Node.js and a Playwright Chromium binary.
- ALWAYS cite
procedures/design-system-extraction.md or the no-procedure fallback before substantial extraction planning, generation, validation, or report output.
- ALWAYS, on a brief-only request with no live URL, STOP before producing any Style Reference content.
The entire response is text only. Choose either:
- Request the live URL to crawl.
- Explicitly state that brief-only authoring is out of scope for this mode, cite
references/authoring-boundary.md by path, and name sk-code-frontend through the sk-code hub as the route.
Cite both references/authoring-boundary.md and assets/source-of-truth-router-card.md by file path in the response text. Reading them with a tool call does not replace naming them for the user.
NEVER produce a partial or full DESIGN.md artifact as a byproduct of this decision — no Tokens table, no Surfaces, no Quick Start, even with a disclaimer sentence attached or brief values Origin-labeled.
A labeled or disclaimed artifact is still forward-authoring. The boundary forbids the artifact itself, not just unlabeled values inside it.
There is no third option or "boundary exception" framing that produces output anyway.
⛔ NEVER
- NEVER estimate, round, or invent a hex, pixel, font-weight, shadow, or radius value in DESIGN.md. Every value must trace back to a token in
tokens.json. Even trivial-looking values like 1px borders or 0.25rem spacing must be confirmed.
- NEVER include L4 (content) tokens in DESIGN.md. These are image-derived or one-off values that do not represent the design system.
- NEVER replace the v3 Style Reference format with a freeform structure.
The named sections are part of the contract that downstream consumers —
sk-code and AI coding agents — depend on:
- Tokens — Colors/Typography/Spacing & Shapes
- Components
- Do's and Don'ts
- Surfaces
- Elevation
- Layout
- Agent Prompt Guide
- Similar Brands
- Quick Start
Never assert a false system (gradient-as-depth, focus-consistent) that the tokens contradict.
- NEVER skip validation before claiming a DESIGN.md is complete. An unvalidated DESIGN.md is a draft. Validation errors must be resolved before completion.
- NEVER write DESIGN.md without reading
tokens.json first. The markdown exists only as a faithful rendering of the token data; writing without the source data guarantees hallucination.
- NEVER produce any Tokens table (Colors, Typography, Spacing & Shapes, Border Radius, or any other) when the request is brief-only with no live URL to crawl.
This applies even with an Origin/brief-provided label or a disclaimer sentence attached.
For that condition, the correct response contains zero token tables: request a URL or state that authoring is out of scope per ALWAYS rule #10.
Outside that specific no-live-URL condition, a brief-provided value must never appear inside an actual Tokens table row, even when a separate Provenance/source-of-truth table exists elsewhere in the response.
A separate labeling table does not cure an unlabeled value in the real Tokens table. Brief-provided values stay in prose only, per
references/authoring-boundary.md's measured/brief-provided/inferred/absent line (Section 3, "Only measured values enter the token tables, and they enter unlabeled").
⚠️ ESCALATE IF
- ESCALATE IF the extract fails (Playwright cannot reach the URL, JavaScript rendering times out, or the page emits no measurable CSS). Report the specific error, the URL, and whether the site requires authentication or blocks automated crawlers. Do not retry in a loop.
- ESCALATE IF dark-mode detection is ambiguous — the extractor found a
prefers-color-scheme media query but could not capture the dark palette values. Ask whether to proceed with light-only output or to investigate a manual dark-mode toggle on the site.
- ESCALATE IF a token straddles the L2/L3 boundary and the classifier cannot disambiguate. Surface the token and its context and ask which class to assign.
- ESCALATE IF validation reports hex mismatches that appear to be extractor bugs rather than write-phase errors (e.g.,
tokens.json itself contains #1A1A2E — invalid case — where the live CSS was #1a1a2e). Ask whether to correct tokens.json before re-validating.
- ESCALATE IF the user wants to edit DESIGN.md by hand after extraction and remove or alter token-derived values. The DESIGN.md is a fidelity artifact; manual edits that deviate from
tokens.json break validation. Offer to re-run extraction with different parameters instead.
5. REFERENCES
Core References (Format & Style)
- design-md-format.md — The authoritative v3 Style Reference section specification: named colour tokens, semantic type scale, named components, Surfaces/Elevation, Agent Prompt Guide, Similar Brands, and copy-paste Quick Start, with heading conventions and token-to-section mapping.
- writing-style-guide.md — Voice, tone, tense, and section-composition rules for DESIGN.md prose.
- color-role-taxonomy.md — Color role naming conventions and the classification hierarchy (brand, semantic, surface, border, text, interactive).
- component-taxonomy.md — Component naming, hierarchy patterns, and the component-to-section mapping rules.
- anti-patterns.md — Common DESIGN.md authoring mistakes: invented values, missing sections, wrong hex case, L4 leaks, and dark-mode fabrication.
- quality-checklist.md — Pre-validate self-check list: hex format, section presence, stability-class compliance, dark-mode gate, a11y section presence.
Gold-Standard Examples
- references/examples/stripe/ — DESIGN.md + tokens.json + writing-notes.md for Stripe.
- references/examples/vercel/ — DESIGN.md + tokens.json + writing-notes.md for Vercel.
- references/examples/linear/ — DESIGN.md + tokens.json + writing-notes.md for Linear.
- references/examples/supabase/ — DESIGN.md + tokens.json + writing-notes.md for Supabase.
- references/examples/editorial-exemplar.md - Non-SaaS study guide for editorial, culture, hospitality or ecommerce extraction shape. Illustrative only, never a preset.
Skill-Owned References
- references/extraction-workflow.md — The three-phase workflow as it runs in this framework: invocations, output paths, stability classes, and handoff.
- references/troubleshooting.md — Failure modes and fixes (Chromium, crawl blocks, dark-mode gaps, validation mismatches).
- references/authoring-boundary.md — The line between measured, brief-provided, inferred and absent values, plus the source-of-truth labels that protect the cardinal fidelity rule. States that forward-authoring from a brief with no live site is out of scope and routes to
sk-code-frontend through the sk-code hub.
- references/guided-run.md - Guided wrapper contract and behavior for readiness checks, phase orchestration, smoke runs, stop conditions and operator handoff, without auto-authoring
DESIGN.md.
- references/creation-contract.md - Lifecycle, context, grounding, proof, authority and handoff contract for the
/design:extract command.
- references/sk-code-handoff.md - Envelope for handing an accepted Style Reference from extraction to
sk-code implementation.
- procedures/design-system-extraction.md - Private measured-extraction procedure support for source evidence, gaps, inconsistencies, and next steps inside this existing mode.
Design Knowledge
- references/design-knowledge/README.md — Condensed general design-knowledge layer: the Brand-vs-Product operating register (and its six dials), anti-slop principles, cognitive and numeric design laws, token vocabulary, and a design-principles digest.
It lets this skill read design intent off a surface, not only CSS.
This mode records the extracted surface's register so a captured Style Reference carries the posture forward; it does not author a register from a brief.
Assets
- assets/design-md-prompt-template.md — Copy-paste WRITE-phase prompt that encodes the cardinal rules and the v3 Style Reference contract.
- assets/cardinal-rules-card.md — One-page fidelity checklist for a pre-validate self-check.
- assets/source-of-truth-router-card.md — Fill-in card that sorts each value into measured, brief-provided, inferred or absent before writing, so no value is fabricated or backfilled.
Reference Loading Notes
references/design-md-format.md is the baseline (always loaded). Load writing-style-guide.md alongside it for any write-phase work.
- Load the taxonomy docs (
color-role-taxonomy.md, component-taxonomy.md) and anti-patterns.md only when the intent is EXTRACT_WRITE.
- Load
quality-checklist.md before any validation or completion claim.
- Load
references/authoring-boundary.md and assets/source-of-truth-router-card.md when a value's origin is unclear (brief versus measured) or when a request asks to author from a brief with no live site. The boundary doc keeps the cardinal rule enforceable and routes forward-authoring out of scope.
- Load one example site at a time from
references/examples/ when in STUDY intent; compare the DESIGN.md against the tokens.json to understand format conventions.
- Load
references/guided-run.md for wrapper, smoke lane, preflight, readiness, or guided run requests.
- Keep
ROUTER.md as the single routing authority for all resource loads.
6. SUCCESS CRITERIA
Extraction complete when:
Validation-only complete when:
Report complete when:
7. INTEGRATION POINTS
- New visual direction (palette, type, anti-default critique) is out of scope; this skill supplies the measured ground truth such work would build on.
sk-code implements against DESIGN.md as the hallucination-proof source of truth for colors, fonts, spacing, shadows, and radii.
mcp-figma is the Figma-file alternative to a live-URL extraction.
system-spec-kit applies when the extraction is part of a larger spec-tracked feature and packet documentation is required.
- Requires Playwright (Apache 2.0, via
npx playwright install chromium) and Node.js 20+ (backend/package.json pins engines.node to >=20); ts-node executes the embedded TypeScript modules directly.
8. REFERENCES AND RELATED RESOURCES
- Manual validation scenarios:
manual-testing-playbook/manual-testing-playbook.md.
- Release notes:
changelog/; the latest is changelog/v1.1.11.0.md.
- Tool setup:
INSTALL-GUIDE.md.
- The embedded
backend/scripts/ pipeline (28 TypeScript modules) is documented operationally in references/extraction-workflow.md.
1---2name: sk-design-md-generator3description: "Extracts a live website's real CSS into a v3 Style Reference DESIGN.md via an embedded extract-write-validate pipeline."4allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]5version: 1.1.12.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-design-md-generator8---910# Design System Extractor (md-generator)1112Captures a live website's **real, measured CSS** into a publication-quality `DESIGN.md` — a v3 **Style Reference**.13It is a named, role-driven, ship-ready design-system handoff: named colour tokens, semantic type scale, named components, Surfaces, Elevation, Agent Prompt Guide, Similar Brands, and copy-paste Quick Start CSS + Tailwind.14AI agents build against it without hallucinating colors, fonts, spacing, or shadows.15It runs a three-phase pipeline (extract, write, validate) through an embedded Playwright crawler that samples five viewports and emits verbatim `tokens.json`.16Deep operational detail lives in [`references/`](references/).1718> **Boundary.** This skill is the **extraction and format-fidelity engine** for design references. It captures what already exists.19>20> It does not decide values for a surface that does not exist yet. That work belongs to `sk-code-frontend`, which the `sk-code` hub bundles for visual decisions.21>22> The transport `mcp-figma` moves design data. This skill produces the authoritative measured reference that transport and downstream implementers (`sk-code`) consume.23>24> When both apply to the same surface, this reference outranks `sk-code-frontend`'s defaults. Where no measurement exists, `sk-code-frontend` decides.2526---2728## 1. WHEN TO USE2930### Activation Triggers3132**Use when** the user wants to:33- Extract a live website's real CSS into a machine-readable `DESIGN.md` v3 Style Reference, with every hex, pixel, font-weight, radius, and shadow copied verbatim from the running page.34- Produce a hallucination-proof design document for an AI agent to code against — `DESIGN.md` replaces guesses with measured ground truth.35- Capture colors (including dark-mode palette if detected), typography stacks, shadows, border-radii, spacing scales, CSS custom properties, framework markers, icon-system hints, motion tokens, and a11y data across five responsive viewports.36- Validate a generated `DESIGN.md` against its source `tokens.json` to confirm hex accuracy and section completeness.37- Generate visual validation reports (HTML preview, diff report) from a `DESIGN.md` + `tokens.json` pair.38- Re-extract a site after a redesign to update the design-system reference.3940**Keyword Triggers**: "extract design system", "generate DESIGN.md", "capture website css", "design tokens from url", "create design reference", "style reference", "tokens.json", "validate DESIGN.md", "anti-hallucination design doc", "design-to-markdown", "extract design tokens".4142### Use Cases4344**Full extraction — URL to DESIGN.md.** The canonical workflow: crawl a live URL, produce `tokens.json`, write `DESIGN.md` output conforming to the v3 Style Reference format, then validate hex accuracy, section completeness, and Quick-Start fidelity. This is the primary path.4546**Validation-only.** The user already has a `DESIGN.md` + `tokens.json` pair (from a prior extraction or hand-edited) and wants to confirm fidelity. Run the validator without re-extracting.4748**Visual report generation.** Given a `DESIGN.md` + `tokens.json` pair, render an HTML preview and a visual-diff report to confirm the written doc matches the extracted tokens.4950**Example study.** The user wants to understand how a gold-standard site (stripe, vercel, linear, supabase — included in `references/examples/`) structures its DESIGN.md output, to inform a new extraction or to learn the format conventions.5152### When NOT to Use5354**Skip this skill when:**55- The task is **inventing a new design direction** (palette, type scale, the anti-default critique). That is out of scope — this skill captures measured reality, it does not create new direction.56- The task is **authoring a Style Reference from a brief alone** with no live site to measure. That is forward-authoring and OUT OF SCOPE for this mode.57 This mode reports what is measurably there.58 A brief-only request that does not name this mode's artifact uses a different contract. Route it to `sk-code-frontend` through the `sk-code` hub, and never loosen fidelity here to satisfy it.59 `references/authoring-boundary.md` draws the line between measured values and a brief's stated intent.60- The target is a **Figma file**, not a live website. Use `mcp-figma` to extract from Figma Desktop.61- The user only wants a **screenshot or visual preview** of a page. Use `mcp-chrome-devtools`.62- The website cannot be reached (requires a live, renderable URL with JavaScript execution).6364---6566## 2. SMART ROUTING6768The `sk-design` hub's `sk-design-md-generator` signal selects this packet, so its `SKILL.md` loads first.69A request selects it by naming `DESIGN.md`, `tokens.json`, a style reference, CSS capture, validation or a report measured from a live site or an existing pair.70A brief-only request naming `DESIGN.md` still lands here for its authoring-boundary refusal.71Load `references/design-md-format.md` first, then the resources the detected phase names.72Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.7374---7576## 3. HOW IT WORKS7778### The Three-Phase Pipeline7980Every extraction runs as a sequential pipeline. No phase can be skipped in a full run, though VALIDATE and REPORT can be invoked standalone on an existing `DESIGN.md` + `tokens.json` pair.8182**Process Flow:** `EXTRACT (Phase 1)` → `WRITE (Phase 2)` → `VALIDATE (Phase 3)` → `REPORT (Phase 4, optional)`8384- **EXTRACT** — Playwright crawls 5 viewports, collecting computed CSS (colors, typography, shadows, radii, spacing, CSS variables), measured image-edge outlines, nested/concentric radii, root font smoothing, and hit-target affordances when present, plus dark-mode/framework/icon/motion/a11y signals. Every token is tagged with a stability class (L1–L4, see below). Output: `tokens.json`.85- **WRITE** — Run `build-write-prompt.ts` first. It pre-renders the value tables (Tokens — Colors, Spacing & Shapes, Surfaces, Quick Start) and a FACTS block deterministically from tokens via `formatters-v3.ts` (doc-as-view, no AI on the value tables).86 Paste those sections unchanged. Write prose only: intro, Typography role prose, Components, Do's/Don'ts, Elevation, Imagery, Layout, Agent Prompt Guide, and Similar Brands. Follow the voice in `references/writing-style-guide.md`.87 Elevation renders FLAT when there are 0 shadow tokens. Output: `DESIGN.md`.88- **VALIDATE** — `validate.ts` checks hex accuracy, v3 section completeness, Quick-Start fidelity, and prose provenance (see "What `validate.ts` traces" below). Output: pass/fail with a dual score and per-finding messages.89- **REPORT** (optional) — `report-gen.ts` and `preview-gen.ts` render visual artifacts (HTML report, preview) for human review.9091Full phase-by-phase actions and handoff: `references/extraction-workflow.md`.9293### Procedure Card Selection9495After the hub selects the public `md-generator` mode, choose the private `procedures/design-system-extraction.md` card when a request involves any of these:96- Measured extraction, token capture, CSS capture, `DESIGN.md` generation, source design systems, screenshots, brand references, gaps, inconsistencies, or grounding future work in an existing surface.97 Cite that card by relative path in the plan or proof line.98 It supports this mode but is not a public route.99100If the card does not match, state `Procedure applied: none - baseline md-generator pipeline` and continue with phase detection (`EXTRACT_WRITE`, `VALIDATE`, `REPORT`, `STUDY`) plus the existing resource router.101102### Backend Boundary Preservation103104Procedure support does not replace or generalize the extraction backend.105`design-md-generator` remains the only mutating `sk-design` mode. It has `backendKind: playwright-extract`, Write/Edit/Bash permission, and the embedded TypeScript pipeline under `backend/scripts/`.106The protected entrypoints are `extract.ts`, `build-write-prompt.ts`, `validate.ts`, `report-gen.ts`, `preview-gen.ts`, and `proof.ts`.107Package-level verification remains `npm run typecheck`, `npm run build`, and `npm test` from `backend/` when operator policy allows those commands.108109The procedure card can shape planning and proof, but it must not flatten this skill into read-only guidance or alter its owned extract-write-validate write boundary.110111### Context, Proof, And Direct Fallback112113Before extraction or validation, record the context basis:114- Public mode `md-generator`, selected procedure card or no-procedure fallback, pipeline phase, source type, target URL or artifact, output paths, tool-readiness state, loaded references, and value-origin risks.115116Before any completion claim, include proof naming:117- The selected procedure card, backend entrypoint used, `tokens.json`/`DESIGN.md` provenance, validation result, and unresolved gaps.118119If subagents are unavailable or disallowed, execute directly in the current session using this mode's normal backend boundary. Direct fallback does not weaken the pipeline: full extraction still requires extract, write, and validate; validation-only and report-only paths still use their dedicated backend entrypoints.120### Cardinal Fidelity Rule121122**Every hex code, pixel value, font weight, box shadow, border radius, and spacing value in `DESIGN.md` MUST be copied verbatim from `tokens.json`.** No estimation, no rounding, no invention, no "close enough" substitution. This is the single non-negotiable contract of the skill — it is what makes `DESIGN.md` a hallucination-proof reference.123124- **Hex codes** must use **6-digit lowercase** format (e.g., `#1a1a2e`, never `#1A1A2E` or `#1a1a2`).125- **Stability gates**: only L1 (permanent/brand-level) and L2 (system/component-level) tokens belong in the main DESIGN.md sections. L3 (campaign-level, e.g., a seasonal accent color) may appear with an explicit "Subject to change" annotation. L4 (content-level, e.g., a hero image's dominant color) is excluded.126- **Dark mode**: include a dark-mode section ONLY when the extractor detected a dark-mode palette. Do not fabricate a dark palette from the light one.127- **What `validate.ts` traces**:128 - Validation hard-checks hex codes against `tokens.colorTokens` and Quick Start values. Every Quick Start hex traces to a token; `--page-max-width` matches `tokens.spacingSystem.maxContentWidth`.129 - Non-hex values (pixel sizes, font weights, shadows, radii) are NOT re-traced by the validator.130 - Their fidelity is guaranteed upstream. The WRITE phase pre-renders the value tables from `formatters-v3.ts` and supplies the typography/component numbers verbatim in the FACTS block, so the AI never types them.131 - The cardinal rule binds those values even though validation does not re-check each one.132133### Authoring Boundary134135The cardinal rule stays enforceable by inspection because every value has a legible origin.136A value is:137- **measured** (read off the page and present in `tokens.json`)138- **brief-provided** (supplied by the user, not the page)139- **inferred** (a grounded characterization of a measured value)140- **absent** (never captured)141142Only measured values enter the token tables, unlabeled. An unlabeled value is a promise it was measured.143Brief-provided values stay in prose as a stated intent and never sit in a value table.144Inferred claims carry `[INFERRED]` and cite the measured token they rest on. Absent values are stamped or omitted, not backfilled.145This boundary adds no capability and relaxes the fidelity contract by not one digit.146When a value's origin is unclear, or a request asks to author from a brief with no live site, load `references/authoring-boundary.md` for the full line and `assets/source-of-truth-router-card.md` to sort each value before writing.147Authoring from a brief alone is forward-authoring and stays out of scope (Section 1, When NOT to Use).148149### Invocation150151> **Working directory.** One-time setup runs from `backend/`. Every pipeline script runs from the **repo root** with the full script path — `extract.ts` refuses any `--output` that resolves inside the skill, so a relative `specs/...` path only resolves correctly from there. Full phase-by-phase actions: `references/extraction-workflow.md`. Complete flag reference: `backend/README.md`.152153```bash154# One-time setup155cd .skilled/skills/sk-design/sk-design-md-generator/backend && npm install && npx playwright install chromium156157# Phase 1 — extract (writes tokens.json to --output)158npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/extract.ts <url> --fast --output specs/<track>/<packet>/output159160# Phase 2 — pre-render value tables + FACTS block, then write DESIGN.md prose161npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/build-write-prompt.ts specs/<track>/<packet>/output/tokens.json162163# Phase 3 — validate (DESIGN.md first, tokens.json second)164npx ts-node .skilled/skills/sk-design/sk-design-md-generator/backend/scripts/validate.ts <DESIGN.md> specs/<track>/<packet>/output/tokens.json165```166167Optional Phase 4 (from the repo root, tokens.json first): `proof.ts <url> <tokens.json>`, `report-gen.ts <tokens.json> <dir> <DESIGN.md>`, `preview-gen.ts <tokens.json> <dir>`. Interaction capture is **default-on**; opt out with `--no-interaction` or `--fast-no-interaction`.168169### Token Stability Classes (L1–L4)170171The deterministic classifier in `backend/scripts/cluster.ts` classifies each token from L1 (Permanent/`infrastructure`) through L4 (Content/`content`).172L1+L2 populate the main `DESIGN.md` sections. L3 gets a "Subject to change" annotation; L4 is excluded entirely.173Boundary tokens take the higher (more restrictive) class.174See `references/extraction-workflow.md` (Section 3) for the full class table, emitted `stability.layer` string mapping, and coverage-election pre-gate.175176---177178## 4. RULES179180### ✅ ALWAYS1811821. **ALWAYS read `references/design-md-format.md` and `references/writing-style-guide.md` before writing DESIGN.md.** These define the v3 Style Reference section specification and the voice/tone rules. No DESIGN.md is conformant without them.1832. **ALWAYS copy every numeric CSS value verbatim from `tokens.json`.** Hex colors, pixel sizes, font weights, box shadows, border radii, spacing values — every number must match `tokens.json` exactly. This is the cardinal fidelity rule.1843. **ALWAYS use 6-digit lowercase hex** for every color in DESIGN.md (e.g., `#1a1a2e`, never `#1A1A2E`, `#333`, `rgb()`, or `hsl()`).1854. **ALWAYS apply stability gates:** L1 and L2 colours in the main token table; L3 colours in the "Current Campaign Colors (Subject to change)" sub-table; L4 tokens excluded entirely.1865. **ALWAYS run `validate.ts` before claiming completion** of any extraction or DESIGN.md edit.187 Validation checks hex accuracy against `tokens.json`, v3 Style Reference section completeness, Quick-Start fidelity, and prose provenance.188 Every Quick Start hex traces to a token, and `--page-max-width` matches `tokens.json`.189 The gate passes only with zero hard failures in the `target`, `schema`, and `provenance` categories.190 `valuesScore` and `claimsScore` print as information.1916. **ALWAYS include a dark-mode section ONLY when `tokens.json` contains a detected dark-mode palette.** Never infer, derive, or fabricate a dark palette from the light tokens.1927. **ALWAYS include an accessibility section** drawn from the `tokens.json` a11y data (contrast ratios, focus ring styles, minimum touch-target sizes). If the extractor captured no a11y data, note the absence rather than inventing values.1938. **ALWAYS confirm tool readiness** before any extract/validate/report invocation: `cd backend && npm install && npx playwright install chromium`. The embedded tool requires Node.js and a Playwright Chromium binary.1949. **ALWAYS cite `procedures/design-system-extraction.md` or the no-procedure fallback** before substantial extraction planning, generation, validation, or report output.19510. **ALWAYS, on a brief-only request with no live URL, STOP before producing any Style Reference content.**196 The entire response is text only. Choose either:197 - Request the live URL to crawl.198 - Explicitly state that brief-only authoring is out of scope for this mode, cite `references/authoring-boundary.md` by path, and name `sk-code-frontend` through the `sk-code` hub as the route.199 Cite both `references/authoring-boundary.md` and `assets/source-of-truth-router-card.md` by file path in the response text. Reading them with a tool call does not replace naming them for the user.200 **NEVER produce a partial or full DESIGN.md artifact as a byproduct of this decision** — no Tokens table, no Surfaces, no Quick Start, even with a disclaimer sentence attached or brief values Origin-labeled.201 A labeled or disclaimed artifact is still forward-authoring. The boundary forbids the artifact itself, not just unlabeled values inside it.202 There is no third option or "boundary exception" framing that produces output anyway.203204### ⛔ NEVER2052061. **NEVER estimate, round, or invent a hex, pixel, font-weight, shadow, or radius value in DESIGN.md.** Every value must trace back to a token in `tokens.json`. Even trivial-looking values like `1px` borders or `0.25rem` spacing must be confirmed.2072. **NEVER include L4 (content) tokens in DESIGN.md.** These are image-derived or one-off values that do not represent the design system.2083. **NEVER replace the v3 Style Reference format with a freeform structure.**209 The named sections are part of the contract that downstream consumers — `sk-code` and AI coding agents — depend on:210 - Tokens — Colors/Typography/Spacing & Shapes211 - Components212 - Do's and Don'ts213 - Surfaces214 - Elevation215 - Layout216 - Agent Prompt Guide217 - Similar Brands218 - Quick Start219 Never assert a false system (gradient-as-depth, focus-consistent) that the tokens contradict.2204. **NEVER skip validation before claiming a DESIGN.md is complete.** An unvalidated DESIGN.md is a draft. Validation errors must be resolved before completion.2215. **NEVER write DESIGN.md without reading `tokens.json` first.** The markdown exists only as a faithful rendering of the token data; writing without the source data guarantees hallucination.2226. **NEVER produce any Tokens table (Colors, Typography, Spacing & Shapes, Border Radius, or any other) when the request is brief-only with no live URL to crawl.**223 This applies even with an Origin/brief-provided label or a disclaimer sentence attached.224 For that condition, the correct response contains zero token tables: request a URL or state that authoring is out of scope per ALWAYS rule #10.225 Outside that specific no-live-URL condition, a brief-provided value must never appear inside an actual Tokens table row, even when a separate Provenance/source-of-truth table exists elsewhere in the response.226 A separate labeling table does not cure an unlabeled value in the real Tokens table. Brief-provided values stay in prose only, per `references/authoring-boundary.md`'s measured/brief-provided/inferred/absent line (Section 3, "Only measured values enter the token tables, and they enter unlabeled").227228### ⚠️ ESCALATE IF2292301. **ESCALATE IF the extract fails** (Playwright cannot reach the URL, JavaScript rendering times out, or the page emits no measurable CSS). Report the specific error, the URL, and whether the site requires authentication or blocks automated crawlers. Do not retry in a loop.2312. **ESCALATE IF dark-mode detection is ambiguous** — the extractor found a `prefers-color-scheme` media query but could not capture the dark palette values. Ask whether to proceed with light-only output or to investigate a manual dark-mode toggle on the site.2323. **ESCALATE IF a token straddles the L2/L3 boundary** and the classifier cannot disambiguate. Surface the token and its context and ask which class to assign.2334. **ESCALATE IF validation reports hex mismatches** that appear to be extractor bugs rather than write-phase errors (e.g., `tokens.json` itself contains `#1A1A2E` — invalid case — where the live CSS was `#1a1a2e`). Ask whether to correct `tokens.json` before re-validating.2345. **ESCALATE IF the user wants to edit DESIGN.md by hand after extraction** and remove or alter token-derived values. The DESIGN.md is a fidelity artifact; manual edits that deviate from `tokens.json` break validation. Offer to re-run extraction with different parameters instead.235236---237238## 5. REFERENCES239240### Core References (Format & Style)241242- [design-md-format.md](references/design-md-format.md) — The authoritative v3 Style Reference section specification: named colour tokens, semantic type scale, named components, Surfaces/Elevation, Agent Prompt Guide, Similar Brands, and copy-paste Quick Start, with heading conventions and token-to-section mapping.243- [writing-style-guide.md](references/writing-style-guide.md) — Voice, tone, tense, and section-composition rules for DESIGN.md prose.244- [color-role-taxonomy.md](references/color-role-taxonomy.md) — Color role naming conventions and the classification hierarchy (brand, semantic, surface, border, text, interactive).245- [component-taxonomy.md](references/component-taxonomy.md) — Component naming, hierarchy patterns, and the component-to-section mapping rules.246- [anti-patterns.md](references/anti-patterns.md) — Common DESIGN.md authoring mistakes: invented values, missing sections, wrong hex case, L4 leaks, and dark-mode fabrication.247- [quality-checklist.md](references/quality-checklist.md) — Pre-validate self-check list: hex format, section presence, stability-class compliance, dark-mode gate, a11y section presence.248249### Gold-Standard Examples250251- [references/examples/stripe/](references/examples/stripe/) — DESIGN.md + tokens.json + writing-notes.md for Stripe.252- [references/examples/vercel/](references/examples/vercel/) — DESIGN.md + tokens.json + writing-notes.md for Vercel.253- [references/examples/linear/](references/examples/linear/) — DESIGN.md + tokens.json + writing-notes.md for Linear.254- [references/examples/supabase/](references/examples/supabase/) — DESIGN.md + tokens.json + writing-notes.md for Supabase.255- [references/examples/editorial-exemplar.md](references/examples/editorial-exemplar.md) - Non-SaaS study guide for editorial, culture, hospitality or ecommerce extraction shape. Illustrative only, never a preset.256257### Skill-Owned References258259- [references/extraction-workflow.md](references/extraction-workflow.md) — The three-phase workflow as it runs in this framework: invocations, output paths, stability classes, and handoff.260- [references/troubleshooting.md](references/troubleshooting.md) — Failure modes and fixes (Chromium, crawl blocks, dark-mode gaps, validation mismatches).261- [references/authoring-boundary.md](references/authoring-boundary.md) — The line between measured, brief-provided, inferred and absent values, plus the source-of-truth labels that protect the cardinal fidelity rule. States that forward-authoring from a brief with no live site is out of scope and routes to `sk-code-frontend` through the `sk-code` hub.262- [references/guided-run.md](references/guided-run.md) - Guided wrapper contract and behavior for readiness checks, phase orchestration, smoke runs, stop conditions and operator handoff, without auto-authoring `DESIGN.md`.263- [references/creation-contract.md](references/creation-contract.md) - Lifecycle, context, grounding, proof, authority and handoff contract for the `/design:extract` command.264- [references/sk-code-handoff.md](references/sk-code-handoff.md) - Envelope for handing an accepted Style Reference from extraction to `sk-code` implementation.265- [procedures/design-system-extraction.md](procedures/design-system-extraction.md) - Private measured-extraction procedure support for source evidence, gaps, inconsistencies, and next steps inside this existing mode.266267### Design Knowledge268269- [references/design-knowledge/README.md](references/design-knowledge/README.md) — Condensed general design-knowledge layer: the Brand-vs-Product operating register (and its six dials), anti-slop principles, cognitive and numeric design laws, token vocabulary, and a design-principles digest.270 It lets this skill read design intent off a surface, not only CSS.271 This mode records the extracted surface's register so a captured Style Reference carries the posture forward; it does not author a register from a brief.272273### Assets274275- [assets/design-md-prompt-template.md](assets/design-md-prompt-template.md) — Copy-paste WRITE-phase prompt that encodes the cardinal rules and the v3 Style Reference contract.276- [assets/cardinal-rules-card.md](assets/cardinal-rules-card.md) — One-page fidelity checklist for a pre-validate self-check.277- [assets/source-of-truth-router-card.md](assets/source-of-truth-router-card.md) — Fill-in card that sorts each value into measured, brief-provided, inferred or absent before writing, so no value is fabricated or backfilled.278279### Reference Loading Notes280281- `references/design-md-format.md` is the baseline (always loaded). Load `writing-style-guide.md` alongside it for any write-phase work.282- Load the taxonomy docs (`color-role-taxonomy.md`, `component-taxonomy.md`) and `anti-patterns.md` only when the intent is EXTRACT_WRITE.283- Load `quality-checklist.md` before any validation or completion claim.284- Load `references/authoring-boundary.md` and `assets/source-of-truth-router-card.md` when a value's origin is unclear (brief versus measured) or when a request asks to author from a brief with no live site. The boundary doc keeps the cardinal rule enforceable and routes forward-authoring out of scope.285- Load one example site at a time from `references/examples/` when in STUDY intent; compare the DESIGN.md against the tokens.json to understand format conventions.286- Load `references/guided-run.md` for wrapper, smoke lane, preflight, readiness, or guided run requests.287- Keep [`ROUTER.md`](./ROUTER.md) as the single routing authority for all resource loads.288289---290291## 6. SUCCESS CRITERIA292293**Extraction complete when:**294- [ ] `tokens.json` was written by `extract.ts` with no fatal errors, and the file is valid JSON with non-empty token arrays.295- [ ] `DESIGN.md` was written conforming to the v3 Style Reference format in `references/design-md-format.md`.296- [ ] Every hex, pixel, font-weight, shadow, and radius in DESIGN.md matches `tokens.json` verbatim.297- [ ] All hex codes use 6-digit lowercase format.298- [ ] L1 + L2 colours populate the main token table; L3 colours appear in the "Current Campaign Colors (Subject to change)" sub-table; L4 tokens are absent.299- [ ] Elevation renders FLAT when there are 0 shadow tokens (states how depth is achieved instead); no false systems asserted.300- [ ] The Quick Start CSS + Tailwind blocks are present and every value traces to a token.301- [ ] `validate.ts` passes with zero hex mismatches, zero missing required sections, Quick-Start fidelity intact and zero hard failures in the `target`, `schema` and `provenance` categories.302- [ ] The selected private procedure card is cited by relative path, or the no-procedure fallback is explicitly stated.303- [ ] The mutating backend entrypoint and validation evidence are named; procedure support does not replace the extract-write-validate boundary.304305**Validation-only complete when:**306- [ ] `validate.ts` was run against the DESIGN.md + tokens.json pair.307- [ ] All reported errors are resolved or escalated per Section 4 (ESCALATE IF).308309**Report complete when:**310- [ ] `report-gen.ts` and `preview-gen.ts` produced artifacts at the specified output paths with no errors.311312---313314## 7. INTEGRATION POINTS315316- New visual direction (palette, type, anti-default critique) is out of scope; this skill supplies the measured ground truth such work would build on.317- `sk-code` implements against `DESIGN.md` as the hallucination-proof source of truth for colors, fonts, spacing, shadows, and radii.318- `mcp-figma` is the Figma-file alternative to a live-URL extraction.319- `system-spec-kit` applies when the extraction is part of a larger spec-tracked feature and packet documentation is required.320- Requires Playwright (Apache 2.0, via `npx playwright install chromium`) and Node.js 20+ (`backend/package.json` pins `engines.node` to `>=20`); `ts-node` executes the embedded TypeScript modules directly.321322---323324## 8. REFERENCES AND RELATED RESOURCES325326- Manual validation scenarios: `manual-testing-playbook/manual-testing-playbook.md`.327- Release notes: `changelog/`; the latest is `changelog/v1.1.11.0.md`.328- Tool setup: `INSTALL-GUIDE.md`.329- The embedded `backend/scripts/` pipeline (28 TypeScript modules) is documented operationally in `references/extraction-workflow.md`.