# How to Extract DESIGN.md from Existing Frontend Source Code

> Extract DESIGN.md from frontend source code automatically. This skill reverse-engineers your design system from manifests, stylesheets, and configs, generating a structured DESIGN.md without build or runtime.

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

---

**The `stitch::extract-design-md` skill reverse-engineers a complete design system by scanning package manifests, style sheets, and configuration files to generate a structured DESIGN.md document without requiring a build or runtime.**

The `stitch::extract-design-md` skill in the `google-labs-code/stitch-skills` repository provides a systematic approach to extracting DESIGN.md from existing frontend source code. It operates in four distinct phases to analyze your codebase and produce a canonical design system document that Stitch can consume.

## The Four-Phase Extraction Process

The extraction workflow is defined in [`plugins/stitch-design/skills/extract-design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/SKILL.md) and proceeds through project discovery, deep extraction, file generation, and optional integration.

### Phase 1: Project Discovery

The skill begins by mapping your source tree and detecting the underlying framework. It scans [`package.json`](https://github.com/google-labs-code/stitch-skills/blob/main/package.json) to identify whether you are using React, Vue, Svelte, Angular, or plain CSS architectures.

Key detection targets include:

- **Configuration files**: `tailwind.config.*`, `postcss.config.*`, and theme files
- **Directory structures**: `src/components`, `src/styles`, `src/theme`
- **CSS methodologies**: Tailwind, PostCSS, CSS-in-JS libraries, and design-token files

### Phase 2: Deep Extraction

Once the framework is identified, the skill harvests specific design tokens and patterns. According to the framework-specific reference files in `plugins/stitch-design/skills/extract-design-md/references/`, this phase captures:

- **Visual Theme & Atmosphere**: Inferred mood from root backgrounds, spacing scales, and density settings
- **Color Palette**: Harvested from CSS custom properties, Tailwind config, theme files, and component styles; deduplicated and assigned functional roles
- **Typography**: Font families, size/weight hierarchies, line-height, and letter-spacing definitions
- **Component Stylings**: Descriptions of buttons, cards, navigation, inputs, and domain-specific UI primitives
- **Layout Principles**: Grid systems, breakpoints, whitespace strategies, and responsive behavior patterns

Reference implementations vary by framework:

- **React/Tailwind**: [`references/react-tailwind.md`](https://github.com/google-labs-code/stitch-skills/blob/main/references/react-tailwind.md)
- **Vue**: [`references/vue.md`](https://github.com/google-labs-code/stitch-skills/blob/main/references/vue.md)
- **Svelte**: [`references/svelte.md`](https://github.com/google-labs-code/stitch-skills/blob/main/references/svelte.md)
- **Angular**: [`references/angular.md`](https://github.com/google-labs-code/stitch-skills/blob/main/references/angular.md)
- **Plain CSS**: [`references/plain-css.md`](https://github.com/google-labs-code/stitch-skills/blob/main/references/plain-css.md)

### Phase 3: Writing the DESIGN.md File

The skill assembles the extracted data into [`.stitch/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/DESIGN.md) at your project root, creating the `.stitch/` directory if it does not exist. The output must include the required YAML front-matter (containing `name`, `colors` mappings, and other metadata) followed by markdown sections that match the canonical template.

You can view the expected format in [`plugins/stitch-utilities/skills/design-md/examples/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/examples/DESIGN.md), which demonstrates the complete structure including the mandatory YAML header and section ordering.

### Phase 4: Integration with Stitch (Optional)

To upload the generated design system to Stitch automatically, invoke the `stitch::manage-design-system` skill and pass the newly created [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) as input. The integration logic is documented in [`plugins/stitch-design/skills/manage-design-system/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/manage-design-system/SKILL.md).

## Automation Examples

You can automate the extraction process using either CLI wrappers or the Stitch SDK.

### Bash Wrapper

```bash
#!/usr/bin/env bash
set -e

PROJECT_ROOT=$(pwd)

# Execute the extraction skill

stitch run stitch::extract-design-md --path "$PROJECT_ROOT"

# Verify output

if [[ -f "$PROJECT_ROOT/.stitch/DESIGN.md" ]]; then
  echo "✅ DESIGN.md generated at $PROJECT_ROOT/.stitch/DESIGN.md"
else
  echo "❌ DESIGN.md not found – check skill logs"
  exit 1
fi

```

### Node.js Implementation

```javascript
import { runSkill } from '@stitch/sdk';
import fs from 'fs';

async function extractDesignMd(projectPath) {
  await runSkill('stitch::extract-design-md', { path: projectPath });

  const designMd = await fs.promises.readFile(
    `${projectPath}/.stitch/DESIGN.md`,
    'utf8'
  );

  console.log('✅ DESIGN.md content:');
  console.log(designMd);
}

extractDesignMd(process.cwd()).catch(console.error);

```

## Key Implementation Files

Understanding the source structure helps when debugging or extending the extraction process:

| File | Purpose |
|------|---------|
| [`plugins/stitch-design/skills/extract-design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/SKILL.md) | Core workflow definition, discovery checklist, and quality rubric |
| [`plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md) | React and Tailwind-specific extraction patterns |
| [`plugins/stitch-design/skills/extract-design-md/references/vue.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/vue.md) | Vue framework extraction guidelines |
| [`plugins/stitch-design/skills/extract-design-md/references/svelte.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/svelte.md) | Svelte-specific design token harvesting |
| [`plugins/stitch-design/skills/extract-design-md/references/angular.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/angular.md) | Angular component style extraction |
| [`plugins/stitch-design/skills/extract-design-md/references/plain-css.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/plain-css.md) | Vanilla CSS and CSS Module patterns |
| [`plugins/stitch-utilities/skills/design-md/examples/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/examples/DESIGN.md) | Canonical example of the required output format |
| [`plugins/stitch-design/skills/manage-design-system/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/manage-design-system/SKILL.md) | Optional integration skill for Stitch API uploads |

## Summary

- **The `stitch::extract-design-md` skill** extracts DESIGN.md from existing frontend source code without requiring a build step or runtime environment.
- **Four-phase process**: Project Discovery (framework detection), Deep Extraction (token harvesting), File Generation (YAML + markdown), and optional Integration (Stitch API upload).
- **Output location**: The skill writes to [`.stitch/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/DESIGN.md) using the format specified in [`plugins/stitch-utilities/skills/design-md/examples/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/examples/DESIGN.md).
- **Framework support**: Dedicated reference files handle React/Tailwind, Vue, Svelte, Angular, and plain CSS architectures.
- **Automation ready**: Both CLI and programmatic SDK interfaces are available for CI/CD integration.

## Frequently Asked Questions

### What file formats does the extraction skill support?

The skill supports any frontend codebase that uses standard web technologies. It specifically detects Tailwind configurations, PostCSS setups, CSS-in-JS libraries, and plain CSS/SCSS files. The detection logic resides in [`plugins/stitch-design/skills/extract-design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/SKILL.md) and adapts its extraction strategy based on the framework identified in [`package.json`](https://github.com/google-labs-code/stitch-skills/blob/main/package.json).

### Where is the generated DESIGN.md file stored?

By default, the skill creates a `.stitch/` directory in your project root and writes [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) inside it. You can verify the exact path by checking for [`.stitch/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/DESIGN.md) relative to the `--path` argument you passed to the skill.

### Can I use this with CSS-in-JS solutions like Styled Components?

Yes. The skill recognizes CSS-in-JS patterns during the Project Discovery phase and applies the appropriate extraction logic defined in the framework reference files. For React projects using CSS-in-JS, consult [`plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-design-md/references/react-tailwind.md) for specific token harvesting strategies.

### How do I integrate the extracted design system with Stitch?

After generating [`.stitch/DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/DESIGN.md), run the `stitch::manage-design-system` skill and pass the file path as input. According to [`plugins/stitch-design/skills/manage-design-system/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/manage-design-system/SKILL.md), this handles the automatic upload and synchronization with the Stitch API, eliminating manual file transfers.