How to Extract Design Tokens and Style Guides from Stitch HTML

Stitch Design Skills provide a two-step workflow that captures a self-contained HTML snapshot using Puppeteer, then parses Tailwind classes, CSS variables, and theme configurations to generate a semantic DESIGN.md style guide.

The google-labs-code/stitch-skills repository provides specialized Design Skills that convert live web pages into structured design systems. By combining the Extract Static HTML skill with the Design MD utility, you can extract design tokens and style guides from Stitch HTML without manual documentation. This workflow captures the exact visual state of your application and transforms it into a canonical style guide that designers and developers can share.

Step 1: Capture Static HTML with Extract Static HTML

The first phase uses the Extract Static HTML skill to create a portable, self-contained snapshot of your running application. This skill crawls the target URL using Puppeteer (or a browser sub-agent) and inlines every stylesheet, image, and CSS variable into a single .html file.

The snapshot.ts Script Implementation

The core logic resides in plugins/stitch-design/skills/extract-static-html/SKILL.md, which orchestrates the snapshot.ts script. This script accepts flags for the target URL, output path, and wait time to ensure dynamic content renders before capture.

# Capture a static HTML snapshot using Puppeteer

npx tsx plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts \
  --url http://localhost:3000/profile \
  --output .stitch/profile.html \
  --wait 2000

The --wait parameter specifies milliseconds to delay after page load, ensuring JavaScript-rendered content appears in the final snapshot.

Step 2: Generate Design Tokens with Design MD

Once you have the static HTML file, the Design MD skill parses the markup to extract semantic design tokens and assemble a comprehensive style guide. According to the implementation in plugins/stitch-utilities/skills/design-md/SKILL.md, this skill processes the HTML to identify visual patterns and map them to human-readable descriptions.

Parsing Tailwind and Theme Configurations

The Design MD skill analyzes the snapshot to extract Tailwind classes, custom CSS variables, and theme configuration files (such as theme.ts, tokens.ts, or SASS maps). It identifies color palettes, typography scales, spacing systems, and component-specific styles embedded in the markup.

Creating the DESIGN.md Style Guide

The skill assembles these technical tokens into a structured DESIGN.md file containing color swatches, typography rules, component style notes, and layout principles. This output serves as the canonical style guide for your project.

# Add the Stitch skills and generate the style guide

npx skills add google-labs-code/stitch-skills
stitch::design-md \
  --html .stitch/profile.html \
  --project-id 1234567890 \
  --output .stitch/DESIGN.md

Alternative Workflows and Source Code Parsing

If you already possess a static HTML file, you can skip the snapshot step and invoke stitch::design-md directly with the --html flag. For projects where you need to parse source code directly rather than compiled HTML, the Extract Design MD skill (located at plugins/stitch-design/skills/extract-design-md/SKILL.md) analyzes TypeScript, JavaScript, and Tailwind configuration files to collect tokens before compilation.

Key Source Files and Implementation Details

The following files contain the core implementation logic for the design token extraction workflow:

• plugins/stitch-design/skills/extract-static-html/SKILL.md – Defines the Puppeteer-based crawling logic and the snapshot.ts script parameters for creating self-contained HTML files.
• plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts – The executable script that performs the actual page capture, inlining resources and handling the --wait delay.
• plugins/stitch-utilities/skills/design-md/SKILL.md – Contains the parsing logic that transforms HTML snapshots into semantic DESIGN.md style guides, including Tailwind class extraction and CSS variable mapping.
• plugins/stitch-design/skills/extract-design-md/SKILL.md – Provides source-code parsing capabilities for extracting tokens directly from TypeScript, SASS maps, and configuration files.

Summary

• Extract Static HTML uses Puppeteer via snapshot.ts to create portable, inlined HTML snapshots that capture the exact visual state of your application.
• Design MD processes these snapshots to extract Tailwind classes, CSS variables, and theme configurations, outputting a semantic DESIGN.md style guide.
• The workflow supports both crawled snapshots and existing HTML files, with source-code parsing available as an alternative through Extract Design MD.
• All implementation details are documented in the respective SKILL.md files within the google-labs-code/stitch-skills repository.

Frequently Asked Questions

What is the difference between Extract Design MD and Design MD skills?

Extract Design MD parses source code files—including TypeScript, JavaScript, Tailwind configs, and SASS maps—to extract design tokens before compilation. Design MD processes compiled HTML snapshots to extract visual tokens and generate the final style guide. Use Extract Design MD when working with source repositories; use Design MD when extracting from rendered HTML.

Can I extract design tokens from an existing HTML file without crawling?

Yes. If you already have a static HTML file, skip the snapshot.ts step and pass the file directly to the stitch::design-md command using the --html flag. The skill will parse the existing file and generate the DESIGN.md output without requiring a live URL or Puppeteer instance.

What types of design tokens are captured from Stitch HTML?

The Design MD skill captures Tailwind utility classes, custom CSS variables (such as those defined in theme.ts or tokens.ts), color palettes, typography scales, spacing systems, component style notes, and layout principles embedded in the markup or computed styles.

How does the snapshot script handle dynamic or delayed content?

The snapshot.ts script accepts a --wait parameter that specifies the number of milliseconds to wait after the initial page load before capturing the HTML. This ensures that JavaScript-rendered content, lazy-loaded images, and dynamically injected stylesheets are fully rendered in the final snapshot.

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