🎨 designscope — Design System Extraction & Design Documentation

Point at any visual source — a screenshot, a live URL, a Figma link — and extract its design system into structured artifacts: a design.md brief with a responsive CSS Grid/Flexbox layout tree another AI (or human) can build from, a W3C DTCG design-tokens.json for design tooling, and an optional WCAG accessibility report. Element mode zooms into one component and outputs either a rebuild spec or a token-grounded image prompt. Outputs serve directly as briefs for AI builders and as client brand documentation.

Modes

Every invocation resolves to exactly one mode. Load only the matched reference:

When to Use

Triggers:

• "Extract the design system from this site/screenshot/Figma file".
• "Deconstruct this page into a component layout tree / layout hierarchy".
• "Extract the responsive CSS Grid / Flexbox structure from this screenshot".
• "Help me recreate this website design (structure + tokens)".
• "What palette does this site use?", "what font is this?", "document the style of Y".
• "Convert this image into tokens", "help me replicate this design".
• Element-scoped: "copy this navbar", "just the pricing card", "recreate this illustration", "give me a prompt to regenerate this graphic".
• Agency workflow: producing a brand/design brief to feed AI builders (Cursor, v0, Lovable) or to document a client's visual system.
• Auditing whether a production site implements what a Figma design defined.

Anti-triggers:

• Building UI from scratch with no reference source — use your normal frontend workflow.
• Generating new designs or inventing a brand identity from nothing — this skill documents what exists; it does not create.
• Copying verbatim brand-identifying artwork (logos, mascots) for reuse outside analysis/documentation.

Quick Reference

Procedure

Always follow this order, no skipping steps.

Step 1 — Identify source and objective

Confirm two things (only if unclear from the message):

1. Which source is it? Image / URL / Figma / combination.
2. What's the emphasis?
   • Reconstruction → to feed an AI builder (requires full Component Layout Tree in Section 4.5)
   • Mood/reference → to document style, branding, inspiration
   • Design system → to extract tokens and components as a system

If the user doesn't clarify, assume reconstruction + design system as the default combo. The design.md covers all three anyway — what changes is the depth.

Also determine mode: full analysis vs element copy. Element-mode signals: a definite article + single component ("the navbar", "that button"), an element-scoped verb ("copy", "extract just", "recreate"), or any request for an image-generation prompt. When genuinely ambiguous, default to full mode and offer element mode as the follow-up.

Step 2 — Capture the material

Execute the flow for the source type. Read references/capture-flows.md when you start this step.

• Image: view it directly. Skip to Step 3.
• URL: web-fetch the HTML first. If it has real content, work with it and also extract CSS custom properties (python scripts/extract_css_vars.py <URL>). If the HTML comes back empty (SPA without SSR), capture viewports or elements using your agent's native browser/screenshot tooling instead.
• Figma: Figma MCP tools in order — get_metadata, get_variable_defs, get_design_context, get_screenshot.

If something fails (URL down, no Figma access, broken image), tell the user clearly and propose alternatives instead of inventing content.

Step 3 — Layered analysis + Art Direction QA pass

Analyze the material in 6 layers, general to specific. Read references/analysis-framework.md when you start this step.

After Layers 1-6, run the Art Direction Patterns QA pass at the end of references/analysis-framework.md. It surfaces patterns shallow analysis routinely misses. The QA pass is non-negotiable.

For token rigor ("green-500 = #16A34A", not "green"), consult references/token-extraction.md. For accessibility checks on extracted color pairs, run python scripts/check_contrast.py --pair "#111827,#FFFFFF".

Step 3.1 — Responsive Component Layout Tree Extraction

When extracting layout structure (Layer 4), decompose the visual interface into an actionable responsive component layout tree (consult references/layout-tree-extraction.md):

1. Deconstruct into Container Blocks:
   • Header / Nav: flex row, sticky/fixed, justify-between, items-center.
   • Hero Section: flex col (centered) or 2-col CSS Grid (split text/preview), min-h bounds.
   • Feature & Bento Grids: CSS Grid (repeat(12, 1fr) or auto-fit), column/row spans.
   • Alternating Bands: flex col on mobile $\rightarrow$ alternating flex row/reverse on desktop.
   • Footer Matrix: multi-column link grid with top divider and bottom legal bar.
2. Generate Responsive Box-Model Specifications:
   • Detail display (grid vs flex), flex direction, alignment (justify-*, items-*), and grid templates (grid-template-columns, gap).
   • Define breakpoint transition rules across Mobile (<640px/768px), Tablet (768px–1024px), Desktop (1024px–1280px), and Wide (>1280px).
3. Map Visual Hierarchy Directly to Design Tokens:
   • Bind typography scale ({typography.display}, {typography.h1}, {typography.body}).
   • Bind spacing rhythm ({spacing.4}, {spacing.6}, {spacing.12}), radii, borders, and surface elevation tiers.
   • Output the complete structural hierarchy in Section 4.5 of design.md.

Step 4 — Generate the output artifacts

Use the template in references/output-template.md as the output contract (read it when you reach this step). For element mode, follow references/element-copy.md instead.

Non-negotiable honesty rules:

1. Honesty over confidence. Every important inference carries a confidence level (✅ high / ⚠️ medium / ❓ low). Inventing tokens is worse than saying "not enough info".
2. Real hex codes, not literary approximations. No "sky blue" — #3B82F6 with its semantic role.
3. Mandatory "Open Questions" section. What you couldn't determine and what needs human input. If none, justify why.
4. Mandatory "Do's and Don'ts" section. Brand-specific usage rules grounded in observation. If you can't generate at least 3 of each, say so explicitly — never pad with generic UX advice.
5. Dual output when applicable. Besides design.md, generate design-tokens.json in W3C DTCG format ($value/$type) — only if you extracted concrete tokens.
6. Accessibility report (optional). With at least two color pairs, generate a brief design-a11y.md with WCAG ratios via scripts/check_contrast.py.

Step 5 — Lint gate, then deliver

ALWAYS run the lint script before delivering any design.md:

python scripts/lint_design_md.py <generated-design.md>

Fix every reported failure before delivering (unresolved token refs, missing mandatory sections, empty Do's/Don'ts without abstain justification).

Then present the generated files and offer next steps based on the Step 1 emphasis:

1. Refine the analysis if something felt weak or the user sees something you didn't.
2. Convert the design.md into a build prompt for any AI code agent (Cursor, opencode, Copilot, v0, Lovable).
3. Analyze another source to compare.

Don't close with "anything else?". Proactively suggest the logical next step.

Pitfalls

• ❌ Never invent tokens you didn't observe. A short honest system beats a long invented one.
• ❌ Never write "modern and clean design" without concrete observations backing it. Every claim traces to something seen.
• ✅ Prefer extracted CSS variables over inferred values — they carry ✅ high confidence by default. Inference is the fallback, not the default.
• ❌ Don't assume a framework without class evidence. No bg-blue-500 classes → don't say "this is Tailwind".
• ❌ Don't invent variants. Saw one button → "1 variant observed", not "primary, secondary, tertiary".
• ❌ Don't fabricate responsive behavior from desktop-only material — flag it in Open Questions and recommend multi-viewport captures.
• ❌ Don't skip the Art Direction QA pass, layout tree decomposition, or lint gate.
• ❌ Don't generate images in element mode. Deliver the prompt; rendering is the user's step.
• ❌ Don't analyze in a vacuum. If the user gave context ("this is for X brand"), the analysis must connect with that hint.

Audit routing

designscope produces design systems (tokens, components, palettes). For deeper audits of the output:

• UI/component audit → refactor-ui audit mode (scored UI report, WCAG 2.2 contrast)
• Design-token audit → refactor-ui tokens mode (extract-and-centralize)
• Content-quality audit → content audit mode (anti-slop scan, fact verification)

Cross-link: skills/references/audit-mode-guidance.md for canonical severity + routing.

Verification

Before declaring the task complete:

1. Lint gate passes: python scripts/lint_design_md.py <output> reports zero failures.
2. Hex format check: every color token is a real hex code (#[0-9A-Fa-f]{6}), not a prose approximation.
3. DTCG validity: design-tokens.json parses as JSON, uses $value/$type, and every $extensions.designscope.confidence marker matches the confidence stated in design.md.
4. Grep-audit your own output for invented tokens: pick 3 random tokens from the output and confirm each traces to something in the captured material (HTML, screenshot, Figma data). If one doesn't trace, remove it or downgrade to ❓ low with justification.
5. Mandatory sections present: Open Questions and Do's/Don'ts exist — or carry explicit justifications for their absence.
6. Layout Tree Present: Section 4.5 Component Layout Tree exists in design.md with container blocks, CSS Grid/Flexbox specifications, and token-grounded hierarchy.