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

> Easily extract design systems from your codebase into DESIGN.md. Our tool scans source files to compile colors, typography, components, and layout rules automatically.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file without requiring build steps or runtime dependencies.**

The `extract-design-md` skill in the [google-labs-code/stitch-skills](https://github.com/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/extract-design-md/SKILL.md), the skill examines [`package.json`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file. As defined in [`examples/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/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:

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

```

### Programmatic Integration

Call the skill programmatically from Node.js applications:

```javascript
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:

```yaml
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`](https://github.com/google-labs-code/stitch-skills/blob/main/references/react-tailwind.md)
- **Vue and Nuxt**: Patterns defined in [`references/vue.md`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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.