hero-design-system

Hero Design System

A "look" is a set of CSS-variable tokens + a font trio + optional signature treatments — never a structural change. This is what makes the live selector instant (swapping a theme is a class toggle). This skill produces the variants and feeds the selector.

What a theme is

A theme is a self-contained object the site can apply (see templates/content/theme.ts in the hero-site-method skill). It carries:

• Palette: paper, paperDeep, ink, inkSoft, muted, faint, line, card, accent, accentDeep, accentSoft.
• Fonts: a display, a sans, and a mono (Google Fonts names loaded via next/font).
• Treatments (booleans/values): grain overlay on/off, reveal animation, link-underline style, corner radius, max content width.

Generating distinct variants (default 3)

Run the variants as parallel subagents (the design-variant agent), each given a divergent brief so the options differ in real ways, not shades of one idea. Good default briefs:

#	Brief	Feel
1	Editorial / warm	serif display, paper + terracotta, grain, generous whitespace
2	Minimal / mono	high-contrast, mono accents, tight grid, restrained color
3	Bold / studio	oversized type, saturated accent, confident, modern

Seed brief #1 (or whichever) from the persona's default design brief in hero-site-method/presets/. Each agent should use the frontend-design skill when available to avoid generic-AI aesthetics, and return a complete theme object (no placeholders).

Regeneration: when invoked with feedback (e.g. "more colorful, less corporate"), append the feedback to every brief and produce a fresh set.

The live browser selector

The selector is the running dev app itself rendering the person's real content, re-themed live. Mechanism (templates provided in hero-site-method/templates/):

1. Variants are written into the scaffold as a themes[] array the app can switch between via a CSS-variable swap (instant, no rebuild).
2. A dev-only theme switcher UI lets the person flip between variants and click Choose.
3. Choose POSTs to a dev-only route handler (app/api/choose-theme/route.ts) that writes the selected theme to content/theme.ts.
4. Claude starts the dev server, opens the selector URL in the person's browser, then watches content/theme.ts for the write and continues the build with the theme locked.

 3 parallel design-variant agents ─▶ themes[] in scaffold
         │
         ▼
   npm run dev ─▶ open localhost selector (their real content, live re-theme)
         │ click "Choose"
         ▼
   POST /api/choose-theme ─▶ writes content/theme.ts ─▶ Claude reads it ─▶ build continues

Environment + fallback

Assumes a GUI machine with a browser (Claude Desktop / cowork). If the dev server's localhost cannot be opened or the write-back route cannot reach the filesystem in the runtime sandbox, fall back to: render each variant to a screenshot, present them, and let the person say which they pick; then write content/theme.ts manually from the chosen theme. State clearly when the fallback is in use.