Studio Code: pick the look first and save it as DESIGN.md, then pick the layout in that look

[youknowriad]

Related issues

• Related to Studio Code: let the user pick a design from four drawn pairs, with rendered sneak peeks in the app #4813 (follow-up to the design pick with rendered sneak peeks)

How AI was used in this PR

Designed and built with Claude Code (Opus 5) in a working session with me: design discussion, implementation, a simplification pass, and verification. I reviewed the changes and the live runs.

Verified with lint, typecheck, and unit tests; the single-page build eval (passes, including a new check that DESIGN.md is written with its design tokens); a live studio ui run through both picks; and rendered sample boards. The last live app run happened before the final simplification pass, which is covered by unit tests, sample renders, and the eval.

Worth a close look: the board renderer (renderDesignBoard), the pick_design contract change, and the skill wording.

Proposed Changes

• Two picks instead of one. Today the site design is one question mixing two choices, a layout and a look, so users who like one option's colors and another's layout can't say so. The pick is now two steps: the look first, then the layout, previewed in that look.
• The look is saved as DESIGN.md at the site root, in the open DESIGN.md format (design tokens in YAML front matter, then sections covering colors, typography, components, imagery, motion, and voice). Later Studio Code sessions on that site are told the file exists and follow it for design and content work; other coding agents find it through the site's AGENTS.md.
• Look options are all picked by the agent (four directions suited to the brief, no random draw). Each is shown as a design board drawn from its DESIGN.md draft — palette swatches, type, buttons on the palette, the site name, and the option's image — so the user picks exactly what gets saved.
• Layout options stay two agent picks plus two random, each previewed as a first-screen sneak peek in the picked look.
• Zoom: each option in the agentic UI has a small zoom button that opens the preview on its own, full size.
• Cleaner agent behavior: the spec no longer searches for DESIGN.md (the active-site line already says whether one exists) or lists plugins and themes before the design is settled; DESIGN.md describes no page structure until the layout is picked; theme.json reuses DESIGN.md's color names.
• Trade-offs: when nothing is asked (surprise me, skipped questions, evals, MCP), the agent may choose its own layout instead of a random one. The avoid option of pick_design is gone. yaml becomes a direct CLI dependency (it was already in the tree).

Testing Instructions

• Run npm run cli:build:ui && node apps/cli/dist/cli/main.mjs ui --no-open and open http://localhost:8081.
• Ask for a new site, e.g. "Create a new site named Crumb Bakery and build it: a one-page site for a neighborhood bakery."
• Check that four look boards appear; pick one; DESIGN.md appears at the site root; four layout sneak peeks appear in that look; pick one; the Layout section of DESIGN.md records it; the build follows.
• Click the zoom button on an option; check it in both light and dark appearance.
• In a new chat on the same site, ask for content (e.g. "Write a short blog post announcing …"): the agent reads DESIGN.md first and writes in its voice.
• Run npm run eval -- --filter-pattern "single-page site build keeps".
• Note: when image generation is unavailable, the boards show a dot pattern instead of a photo.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing 053855d vs trunk

app-size

Metric	trunk	053855d	Diff	Change
App Size (Mac)	1458.21 MB	1458.88 MB	+0.67 MB	⚪ 0.0%

site-editor

Metric	trunk	053855d	Diff	Change
load	1164 ms	1162 ms	2 ms	⚪ 0.0%

site-startup

Metric	trunk	053855d	Diff	Change
siteCreation	7511 ms	7517 ms	+6 ms	⚪ 0.0%
siteStartup	2874 ms	3371 ms	+497 ms	🔴 17.3%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)