How to Extract Design Systems from Existing Codebases into DESIGN.md

The extract-design-md skill reverse-engineers design systems from frontend repositories by scanning source files and compiling colors, typography, components, and layout rules into a Stitch-compatible DESIGN.md file without requiring build steps or runtime dependencies.

The extract-design-md skill in the google-labs-code/stitch-skills repository automates the conversion of implicit design patterns into explicit documentation. Operating entirely on static source analysis, it reads configuration files, component directories, and style definitions to generate a comprehensive DESIGN.md document that captures your project's visual language and component architecture.

Framework Detection and Source Mapping

The extraction process begins by detecting your project's framework and tooling stack. According to extract-design-md/SKILL.md, the skill examines package.json and scans for framework-specific signal files to determine whether you're working with React, Vue, Svelte, Angular, Tailwind, CSS-in-JS, or plain CSS.

Once detected, the skill maps your source tree to locate design assets. It searches standard directories including src/components, src/styles, src/theme, and tailwind.config.* files to identify where colors, fonts, and component patterns reside.

Extracting Design Dimensions

The skill captures five critical design dimensions from your codebase:

Visual Theme and Atmosphere

The skill infers your project's mood and density philosophy by analyzing root background colors, whitespace characteristics, and overall visual weight found in global styles and layout files.

Color Palette and Roles

It collects every unique color from CSS variables, Tailwind configuration, theme files, and component styles. These colors are then grouped by functional roles such as primary, accent, typography, and state indicators to create a semantic color system.

Typography Rules

Font families, size scales, weight variations, letter-spacing, and line-height definitions are extracted from CSS files or Tailwind configurations to document your complete typographic system.

Component Stylings

The skill documents essential primitives—including buttons, cards, navigation elements, and inputs—capturing their shape definitions, color applications, state variations, and transition behaviors as implemented in the source.

Layout Principles

Grid configurations, responsive breakpoints, base spacing units, and layout behaviors are recorded to preserve your site's structural logic and responsive design patterns.

Synthesizing the DESIGN.md File

After extraction, the skill assembles the findings into a structured DESIGN.md file. As defined in examples/DESIGN.md, the file must begin with a YAML frontmatter block containing at least the name field and a colors mapping, followed by markdown documentation describing the extracted design system.

Running the Extraction

You can invoke the skill through multiple interfaces depending on your workflow:

Command Line Interface

Use the Stitch CLI to process a frontend project:

stitch run stitch::extract-design-md --input ./my-frontend-project --output .stitch/DESIGN.md

Programmatic Integration

Call the skill programmatically from Node.js applications:

import { runSkill } from '@stitch/sdk'

await runSkill('stitch::extract-design-md', {
  input: './my-frontend-project',
  output: '.stitch/DESIGN.md',
})

Skill Chaining

Chain the extraction with the manage-design-system skill to automatically upload the generated file to Stitch's MCP:

steps:
  - name: extract-design
    skill: stitch::extract-design-md
    input: ./src
    output: .stitch/DESIGN.md
  - name: upload
    skill: stitch::manage-design-system
    input: .stitch/DESIGN.md

Framework-Specific References

The skill relies on framework-specific reference documents to understand project structures and extraction patterns:

• React and Tailwind: Patterns defined in references/react-tailwind.md
• Vue and Nuxt: Patterns defined in references/vue.md

These references guide the extraction logic for framework-specific conventions regarding component organization, style definitions, and configuration file locations.

Summary

• The extract-design-md skill performs static analysis on frontend repositories to reverse-engineer design systems without executing code or requiring runtime dependencies.
• It detects frameworks by examining package.json and signal files, then maps standard directories like src/components and src/theme to locate design tokens.
• The extraction captures five dimensions: visual atmosphere, color palettes, typography rules, component stylings, and layout principles.
• Output follows the canonical DESIGN.md structure with YAML frontmatter containing name and colors mappings as specified in the examples.
• The skill integrates with Stitch CLI, Node.js SDK, and can chain with manage-design-system for automated design system uploads.

Frequently Asked Questions

Does the extract-design-md skill require the application to be running?

No. The skill works purely on source file analysis and does not require build steps, runtime dependencies, or a running application. It reads static files including package.json, CSS configurations, and component source code to extract design tokens without executing the codebase.

Which frontend frameworks are supported?

The skill supports React, Vue, Svelte, Angular, and vanilla projects using Tailwind, CSS-in-JS, or plain CSS. Detection logic in extract-design-md/SKILL.md maps signal files to specific framework patterns, with dedicated reference documents available for React+Tailwind and Vue implementations.

What must a generated DESIGN.md file contain?

According to the canonical example in extract-design-md/examples/DESIGN.md, the file must start with a YAML frontmatter block specifying at least the name field and a colors mapping. The remainder of the document uses markdown to describe typography, components, and layout principles extracted from the codebase.

Can the extraction process be automated in CI/CD pipelines?

Yes. Since the skill operates via CLI and requires no runtime, you can integrate it into CI/CD workflows using the stitch run stitch::extract-design-md command or Node.js SDK calls. Chain it with manage-design-system to automatically update design system documentation when code changes are pushed to your repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}