---
type: howto
title: "Design Mode Workflow"
summary: Run the design-mode iterative design replication workflow to extract a design system from an existing site and use it as a constraint for building new UIs. Produces three foundation artifacts — reference HTML, style guide, and Tailwind config.
tags:
  - type/howto
  - tool/tailwind
  - domain/design
  - domain/dev
  - project/design-mode
scope: project
last_updated: 2026-06-27
---

# Design Mode Workflow

Use this when you want to replicate an existing design's visual language and encode it as reusable tokens for building new UIs. The workflow runs inside the `design-mode` project. Suitable for any project where you've identified a target design to draw from.

## Prerequisites

- [ ] `design-mode` project cloned and accessible
- [ ] Target site accessible in browser (for CSS extraction)
- [ ] Screenshot of target design saved locally
- [ ] Local dev server available (`python -m http.server` or VS Code Live Server) — needed for Tailwind dynamic imports in Phase 1

## The Flow

```
Target Design (inspiration)
     ↓
[1] Extract CSS  ──→  Raw styles to assets/raw-styles.txt
     ↓
[2] /design-to-html  ──→  Produces 3 foundation artifacts:
     │                     • reference.html (validation)
     │                     • style-guide.md (for humans)
     │                     • tailwind.config.js (for machines)
     ↓
[3] Iterate  ──→  2-3 rounds until reference matches target
     ↓
[4] /design  ──→  Uses config + style guide for creative freedom
```

## Steps

### Step 1: Create project folder

```bash
mkdir -p projects/[name]/assets
```

**Expected result:** Per-project directory ready to hold all artifacts for this design.

### Step 2: Extract CSS from target site

Open the target site in browser DevTools. Use VisBug or the Computed Styles panel to capture design token values (colors, spacing, fonts, border radii). Save the raw dump:

```
projects/[name]/assets/raw-styles.txt
```

Optionally compress the raw output first:

```bash
python tools/compress-styles.py
```

**Expected result:** A condensed CSS values file that `/design-to-html` can parse efficiently.

### Step 3: Run /design-to-html

Provide the command with:
- Screenshot of the target design
- Path to the extracted CSS file

The command produces three artifacts in the project folder:

| Artifact | Purpose |
|----------|---------|
| `reference.html` | Pixel-accurate validation page — compare side-by-side with screenshot |
| `style-guide.md` | Human-readable intent and patterns — when/why to use each token |
| `tailwind.config.js` | Machine-readable theme tokens — single source of truth for all design values |

**Expected result:** Three files written to `projects/[name]/`.

### Step 4: Iterate until reference matches target

Compare `reference.html` side-by-side with your target screenshot. Run `/design-to-html` again with corrections until the match is satisfying — typically 2–3 rounds. Each iteration refines all three artifacts in sync.

**Expected result:** `reference.html` visually matches the target close enough that differences are not visible at a glance.

### Step 5: Build new UIs with /design

Once the foundation artifacts are stable, use `/design` for new UI work:

```
/design [description of the UI you want to build]
```

The command uses `tailwind.config.js` (tokens) + `style-guide.md` (usage intent) as constraints, giving creative freedom within the established design language.

**Expected result:** New UI output that looks consistent with the extracted design system without manually specifying colors or spacing.

## Validation Checkpoints

| Step | Checkpoint |
|------|------------|
| `reference.html` | Side-by-side with target: can you spot differences? |
| `style-guide.md` | Generate content WITHOUT reference in context — does it match? |
| `tailwind.config.js` | Drop into a project; do components render correctly? |
| Styled components | Look right with theme tokens applied? |
| Final build | Resize browser — is responsive behavior correct? |

## Tailwind Config: Two-Phase Approach

**Phase 1 — Design iteration (dynamic import):** HTML files import the config at runtime via ES modules. No build step; config changes apply instantly to all HTML files.

```html
<script src="https://cdn.tailwindcss.com"></script>
<script type="module">
  const { default: config } = await import('./tailwind.config.js');
  window.tailwind.config = config;
</script>
```

Requires a local dev server (browser module imports don't work over `file://`).

**Phase 2 — Production (CLI build):** When ready to ship, compile to static CSS:

```bash
npx tailwindcss -c tailwind.config.js -o dist/styles.css --minify
```

Replace the CDN script tags with `<link rel="stylesheet" href="dist/styles.css">`. Default to Phase 1 during design; switch to Phase 2 only at production handoff.

## Commands Reference

| Command | Purpose |
|---------|---------|
| `/design-to-html` | Screenshot + CSS → three foundation artifacts |
| `/design` | Description + theme → new UI (uses config + style guide) |
| `python tools/compress-styles.py` | Compress raw CSS before passing to design-to-html |

## Tips

- **Config is palette, style guide is instructor** — config says *what* values exist; style guide says *when and why* to use them
- **One viewport at a time** — get desktop tokens right first, then handle responsive
- **Test without reference** — if the style guide can't reproduce the look when used alone (without reference.html in context), it's incomplete
- **Tokens are viewport-agnostic** — colors/fonts/spacing don't change at breakpoints; layout does
- **Avoid over-fitting** — the goal is theme inspiration, not pixel-perfect cloning of every element

## Related

- [[vault-conventions]] — frontmatter and tag taxonomy for this vault
