# How to Extract Design Tokens and Style Guides from Stitch HTML

> Extract design tokens and style guides from Stitch HTML with a two-step workflow. This method generates a semantic DESIGN.md style guide by parsing Tailwind CSS and theme configurations.

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

---

**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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-static-html/SKILL.md), which orchestrates the [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) script. This script accepts flags for the target URL, output path, and wait time to ensure dynamic content renders before capture.

```bash

# 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/theme.ts), [`tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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.

```bash

# 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/extract-static-html/SKILL.md)** – Defines the Puppeteer-based crawling logic and the [`snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/snapshot.ts) script parameters for creating self-contained HTML files.
- **[`plugins/stitch-design/skills/extract-static-html/scripts/snapshot.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/SKILL.md)** – Contains the parsing logic that transforms HTML snapshots into semantic [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) style guides, including Tailwind class extraction and CSS variable mapping.
- **[`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)** – 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/theme.ts) or [`tokens.ts`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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.