154 lines
5.8 KiB
Markdown
154 lines
5.8 KiB
Markdown
---
|
||
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
|