1. What Is DESIGN.md Extractor and Why Extract Design Systems

In modern web development, design systems are almost always proprietary, fragmented, or inaccessible: locked inside private Figma workspaces, scattered across dozens of CSS stylesheets, or residing solely in the minds of lead designers. When developers need to craft interfaces inspired by a reference site or rapidly adopt a client brand's visual language, they typically spend hours manually eyedropping hex values in DevTools and measuring button border radiuses with screen rulers.

DESIGN.md Extractor is a specialized skill for Claude Code that automates the reverse-engineering of web UI design systems. The agent inspects a live page, extracts system tokens directly from the DOM and computed CSS styles, and synthesizes a machine-readable DESIGN.md specification alongside a self-contained visual showcase, design-preview.html.

mermaid

flowchart TD A["Target URL or Brand Name<br><i>'stripe.com'</i>"] --> B["Claude Code + design-md-extractor"] B --> C["DOM & CSS Parser<br><i>(Read :root variables, compute styles)</i>"] C --> D["Extract 4 Token Dimensions<br><i>(Colors, typography, spacing, shapes)</i>"] D --> E["Generate DESIGN.md<br><i>(YAML specification + prose brief)</i>"] D --> F["Build design-preview.html<br><i>(Offline UI kit powered by raw tokens)</i>"] E & F --> G["Export to Tailwind CSS / Figma / Codebase"]

Manual Inspection vs. Automated Extraction

Phase	Manual DevTools Inspection	DESIGN.md Extractor Workflow
Color Palette Extraction	Manually copying individual `color` and `background` rules	Automated extraction of a complete token hierarchy (~35 tokens) from `:root`
Typography Analysis	Sampling `font-size` on isolated heading elements	7-level standardized scale with line-height and tracking rules
Grid & Spacing	Heuristic guesses of margins and padding	Precise mathematical base grid unit (e.g. 8px increment scale)
Output Artifact	Scattered notes or raw screenshots	Structured `DESIGN.md` file and interactive HTML UI kit
Turnaround Time	3 to 6 hours of repetitive labor	Under 60 seconds for an end-to-end extraction cycle

Note

The skill interacts with public, rendered client-side code to extract the exact CSS properties the browser uses for paint and layout operations, eliminating guesswork and human interpretation errors.

2. Architecture and Operating Principles: From URL to Design System

The extraction pipeline consists of several interconnected execution phases designed to guarantee data fidelity.

Step-by-Step Analysis Algorithm

Page Ingestion and Rendering: Claude navigates to the target URL, acquiring the complete HTML document and associated stylesheets.
Parsing Global :root Variables: The agent extracts all declared CSS custom properties (--color-primary, --font-sans, --spacing-unit, --radius-lg).
Evaluating Computed Styles: For elements lacking explicit CSS custom properties, the script samples high-signal components (buttons, headers, input fields, navigation bars) and reads actual browser computed styles.
Token Normalization and Canonicalization: Raw color values are converted to standard HEX or OKLCH, while font family definitions are mapped against Google Fonts or standard system fonts.
Artifact Generation: The agent generates the structured DESIGN.md specification and compiles the offline design-preview.html showcase.

Tip

When evaluating sites built with utility-first frameworks like Tailwind CSS, the skill identifies classes like p-4, rounded-xl, and bg-slate-900 to reconstruct the underlying Tailwind theme configuration.

3. Four Dimensions of Visual Tokens: Colors, Typography, Spacing, and Shapes

DESIGN.md Extractor organizes visual tokens across four architectural pillars, creating an integrated design language.

Color Palette (Colors)

The extractor generates an expanded functional palette of approximately 35 tokens adhering to Material Design 3 and Radix UI patterns:

Brand Accents: primary, secondary, tertiary, paired with high-contrast foreground tokens like on-primary and on-secondary.
Surfaces and Containers: background, surface, surface-variant, surface-container (representing elevation tiers from base to elevated modals).
System States: error, warning, success, info alongside corresponding accessible text tokens.
Neutrals and Dividers: outline, outline-variant, scrim, and shadow.

Typographic Hierarchy (Typography)

The typography system is formalized into seven standardized functional scales:

Token Level	Primary Usage	Standard Size	Line Height	Font Weight
`headline-xl`	Hero banners, primary H1	48px – 64px	1.1 – 1.15	Bold / ExtraBold
`headline-lg`	Section headings H2	32px – 40px	1.2	SemiBold
`title-md`	Card and widget headers H3	20px – 24px	1.3	Medium / SemiBold
`body-lg`	Lead paragraphs, intro copy	18px	1.5 – 1.6	Regular
`body-md`	Standard body copy	15px – 16px	1.5 – 1.6	Regular
`label-md`	Buttons, tabs, badges	13px – 14px	1.2 – 1.4	Medium
`label-sm`	Form hints, disclaimers	11px – 12px	1.3	Regular / Medium

Spacing and Modular Grid (Spacing)

The skill identifies the baseline spatial increment (typically 4px or 8px) and establishes a cohesive scale:

xs (4px), sm (8px), md (16px), lg (24px), xl (32px), 2xl (48px).
In addition, macro layout constraints are captured: max container width (max-width: 1280px) and responsive gutter margins (gutter: 24px).

Shapes and Elevation (Shapes & Elevation)

Border Radiuses: A scale extending from none (0px) to full (9999px for circular badges and pill buttons).
Elevation Shadows: Layered box-shadow tokens (shadow-sm, shadow-md, shadow-xl) that model physical component elevation.

4. Anatomy of DESIGN.md: YAML Specifications and Prose Sections

A DESIGN.md file is structured as a hybrid document: the top section provides a strict YAML schema for linters, compilers, and code generators, while the bottom contains a comprehensive design brief for developers and AI agents.

Example YAML Frontmatter

yaml

--- name: "Acme Cloud Platform" extractedFrom: "https://acme.example.com" version: "1.0.0" colors: primary: "#4F46E5" on-primary: "#FFFFFF" primary-container: "#EEF2FF" secondary: "#06B6D4" background: "#0F172A" surface: "#1E293B" surface-variant: "#334155" on-surface: "#F8FAFC" outline: "#475569" typography: fontFamilySans: "'Inter', -apple-system, sans-serif" fontFamilyMono: "'JetBrains Mono', monospace" headline-xl: fontSize: "48px" lineHeight: "1.1" fontWeight: "800" letterSpacing: "-0.02em" body-md: fontSize: "16px" lineHeight: "1.5" fontWeight: "400" letterSpacing: "0em" spacing: base: "8px" sm: "8px" md: "16px" lg: "24px" xl: "32px" shapes: borderRadiusSm: "4px" borderRadiusMd: "8px" borderRadiusLg: "16px" borderRadiusFull: "9999px" ---

Seven In-Depth Prose Sections

Beneath the YAML frontmatter, the file provides seven detailed design guidelines:

Brand & Style Personality: Defines the voice and aesthetic posture (e.g. "Minimalist engineering rigor inspired by Linear" or "Warm consumer fintech aesthetic like Stripe").
Color Palette Rationale: Prescribes token usage rules and enforces WCAG AA contrast compliance.
Typography Rhythm: Establishes vertical rhythm, optical kerning, and heading hierarchy.
Layout & Spacing Philosophy: Details responsive grid breakpoints, component padding, and container behavior.
Elevation & Depth: Guidelines for backdrop blur filters, gradients, and light-source shadow modeling.
Shape & Border Language: Corner radius consistency, stroke weights, and card borders.
Component Blueprints: Ready-to-implement structural recipes for buttons, inputs, cards, and navigation items.

5. Interactive Previews: Architecture of design-preview.html

In addition to DESIGN.md, the skill compiles a standalone design-preview.html file that serves as an offline, interactive visual design showcase.

mermaid

flowchart LR subgraph design_preview_html["design-preview.html (Self-Contained Showcase)"] P["Color Swatches<br><i>(Click to copy HEX/RGB)</i>"] T["Type Specimen<br><i>(Google Fonts preview)</i>"] C["UI Sandbox<br><i>(Buttons, cards, inputs)</i>"] S["Mockup View<br><i>(Synthesized landing block)</i>"] end design_preview_html --> B["Open in Any Web Browser<br><i>(Zero dependencies, no local server required)</i>"]

Key Advantages of the Self-Contained Preview

Zero Dependencies: No Node.js runtime, npm packages, or bundlers needed. Double-click the file in Finder or File Explorer to view instantly.
Embedded Assets: All icons and graphics are embedded as inline SVG or Base64 data URIs, ensuring complete functionality without an internet connection.
One-Click Token Copy: Clicking on any color swatch immediately copies its formatted hex or CSS variable string to the clipboard.
Interactive State Validation: All interactive components include fully rendered :hover, :focus-visible, :active, and :disabled states.

6. Installation and Execution in Claude Code

The design-md-extractor skill responds to natural language commands or explicit slash invocations.

Terminal Invocation Examples

Execution Lifecycle

Claude Code launches the internal style-harvesting routines.
The agent reports progress in the terminal: parsing CSS custom properties, inspecting font weights, and computing component bounding boxes.
Upon completion, DESIGN.md and design-preview.html appear in the project root.
Claude prompts you to view the visual UI showcase via your browser (open design-preview.html).

7. Integrating Tokens into Tailwind CSS, Figma, and React

Extracted tokens can be directly integrated into production workflows without manual reformatting.

Exporting to Tailwind CSS Configuration

Extend your tailwind.config.ts using the values extracted by the skill:

typescript

import type { Config } from 'tailwindcss'; const config: Config = { content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'], theme: { extend: { colors: { brand: { primary: '#4F46E5', 'on-primary': '#FFFFFF', surface: '#1E293B', background: '#0F172A', }, }, borderRadius: { sm: '4px', md: '8px', lg: '16px', }, fontFamily: { sans: ['Inter', 'sans-serif'], }, }, }, plugins: [], }; export default config;

Binding to CSS Custom Properties

Alternatively, import the extracted tokens into globals.css:

css

:root { --color-primary: #4f46e5; --color-on-primary: #ffffff; --color-surface: #1e293b; --radius-md: 8px; --spacing-base: 8px; }

Syncing with Figma via Tokens Studio

Convert the YAML frontmatter into standard JSON (tokens.json) to import directly into the Tokens Studio for Figma plugin, automatically synchronizing Figma Variables with your codebase.

8. Practical Business Scenarios and Real-World Use Cases

The design extractor provides tangible acceleration across product engineering and visual analytics.

Four Primary Use Cases

Competitor Benchmarking & Design Audits: Deconstruct visual systems from industry benchmark products (Linear, Vercel, Apple, Stripe) before writing a single line of custom CSS.
Client Project Onboarding: Instead of waiting weeks for brand books or outdated design guidelines, extract live design tokens from the client's production web application in minutes.
Rapid MVP Development Without a Dedicated Designer: Founders and solo engineers can adopt the harmonious proportions and palettes of refined products, adjusting accent colors to launch high-polish MVPs quickly.
Context Injection for Autonomous AI Agents: The DESIGN.md file serves as system context for downstream coding agents, guaranteeing that generated components follow strict design tokens.

9. Hands-on Workshop: Extracting a Design System and Building a Component

Follow this hands-on workflow to extract tokens and construct a production-ready React component.

Step 1. Trigger the Extraction Workflow

From your terminal, run the following prompt inside Claude Code:

text

Extract design system from https://news.ycombinator.com or your preferred inspiration website

Claude gathers live DOM styles and outputs DESIGN.md.

Step 2. Inspect the Generated Visual Showcase

Open the preview file in your web browser:

bash

open design-preview.html

Confirm that typography sizes, color contrasts, and component elevations accurately mirror the source product.

Step 3. Generate a React Component from DESIGN.md

Instruct Claude Code to build a component adhering to the generated specification:

text

Using the tokens and component rules defined in DESIGN.md, create a responsive PricingCard component in src/components/PricingCard.tsx with primary and secondary CTA buttons.

Claude references the exact radiuses, shadows, and colors from DESIGN.md to produce a production component:

typescript

import React from 'react'; interface PricingCardProps { title: string; price: string; features: string[]; isPopular?: boolean; } export const PricingCard: React.FC<PricingCardProps> = ({ title, price, features, isPopular }) => { return ( <div className={`p-6 rounded-[16px] border ${isPopular ? 'border-[#4F46E5] bg-[#1E293B]' : 'border-[#475569] bg-[#0F172A]'} text-[#F8FAFC]`}> <h3 className="text-xl font-semibold mb-2">{title}</h3> <div className="text-4xl font-extrabold mb-4">{price}</div> <ul className="space-y-3 mb-6"> {features.map((feat, idx) => ( <li key={idx} className="text-sm text-[#94A3B8] flex items-center gap-2"> ✓ {feat} </li> ))} </ul> <button className="w-full py-3 rounded-[8px] bg-[#4F46E5] hover:bg-[#4338CA] text-white font-medium transition-colors"> Get Started </button> </div> ); };

10. Self-Assessment and Production Checklist

Test your comprehension of the design system extraction workflow.

Review Questions

Tip

1. Where does DESIGN.md Extractor source its exact color and typography parameters?

Answer: The skill queries live CSS custom properties (:root) and computed styles directly from the rendered browser DOM, avoiding approximation or arbitrary guesswork.

Tip

2. Which two primary artifacts are generated upon completing an extraction?

Answer: A machine-readable DESIGN.md document (featuring YAML frontmatter and seven descriptive prose sections) and an offline visual UI preview in design-preview.html.

Tip

3. How does DESIGN.md accelerate other Claude AI coding workflows?

Answer: It acts as an authoritative design system context. AI coding agents read tokens directly from DESIGN.md, ensuring all newly generated UI components strictly match your chosen visual tokens.

Production Readiness Checklist

DESIGN.md contains valid YAML frontmatter specifying core color, font, and spacing tokens.
All seven descriptive prose sections document the target brand's specific aesthetic without generic boilerplate.
design-preview.html opens cleanly in local browsers without script or console errors.
Verified that primary brand colors meet WCAG AA contrast ratios for accessible text display.
Extracted design tokens are mapped into tailwind.config.ts or globals.css.
Initial synthesized components have been validated against the target grid system.