How to Extract DESIGN.md from Existing Frontend Source Code

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 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 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
• Vue: references/vue.md
• Svelte: references/svelte.md
• Angular: references/angular.md
• Plain CSS: references/plain-css.md

Phase 3: Writing the DESIGN.md File

The skill assembles the extracted data into .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, 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 as input. The integration logic is documented in 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

#!/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

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	Core workflow definition, discovery checklist, and quality rubric
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	Vue framework extraction guidelines
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	Angular component style extraction
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	Canonical example of the required output format
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 using the format specified in 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 and adapts its extraction strategy based on the framework identified in 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 inside it. You can verify the exact path by checking for .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 for specific token harvesting strategies.

How do I integrate the extracted design system with Stitch?

After generating .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, this handles the automatic upload and synchronization with the Stitch API, eliminating manual file transfers.

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