5.8 KiB

Raw Permalink Blame History

type

title

summary

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

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:

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.

<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:

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

vault-conventions — frontmatter and tag taxonomy for this vault

5.8 KiB Raw Permalink Blame History Unescape Escape