--- name: ai-assist-prototype description: "Build self-contained, double-click-to-open HTML prototypes so the user can vet an interface before it gets built. One file holds several structurally different variants of a page, app screen, component, flow, or terminal/TUI layout (rendered in-browser), plus a draggable Design Deck for flipping between variants, tuning fonts, colors, spacing, shape, motion and 'feel' with live dials, trying vibe presets, checking viewport sizes and light/dark, pinning comments on elements, and an 'Export to LLM' button that copies the chosen variant and every dial value as a handoff block to paste back to the agent. Use this whenever the user wants to prototype, mock up, wireframe, explore options for, or sanity-check a UI (landing page, dashboard, settings page, onboarding, form, mobile screen, component, CLI/TUI layout), or says 'what should this look like', 'show me a few options', 'let me tweak it before we build', 'vet the design'. Also use it when the user pastes a block starting with 'AI-ASSIST PROTOTYPE HANDOFF': that is this skill's export and tells you which variant and settings they chose. Triggers on: prototype, mockup, wireframe, design options, variations, vet the UI, tweak the look, TUI mockup, design handoff." argument-hint: "[what to prototype, e.g. 'settings page, 3 variants' | or paste an AI-ASSIST PROTOTYPE HANDOFF block]" ---

# Prototype

Build a throwaway-but-polished prototype the user can open by double-clicking, explore, tune, and hand back to you with a structured export. The spine is: **brief → plan variants → build one file → verify → hand over → receive the handoff → iterate or implement.**

Three ideas make this useful rather than another mockup generator:

- **Variants explore structure, dials explore feel.** Variants differ in layout, information hierarchy and primary affordance. Colors, fonts, spacing, radius, elevation and motion are live dials that work on every variant, so never spend a variant on a recolor. - **One self-contained file.** No server, no build, no dependencies, no account. It survives being emailed to a PM or designer, who can tune it and export their decision without you in the room. - **The export closes the loop.** "Export to LLM" copies a handoff block (chosen variant, changed dials, notes, pinned comments, resolved CSS variables). The user pastes it back; you read it and either iterate or implement the real thing.

## Modes: detect from the input

| Input | Mode | |---|---| | A brief, a feature, a page, "what should this look like", "show me options" | **Build** (this is the bullseye) | | "add a variant", "make B denser", "tweak the prototype", an existing `prototypes/*.html` mentioned | **Iterate** | | A pasted block starting with `AI-ASSIST PROTOTYPE HANDOFF` or JSON with `"schema": "ai-assist-prototype/handoff@1"` | **Receive** (see "Receiving a handoff") |

## What you produce

- `prototypes/<slug>.parts.html`: the source you author. A JSON manifest plus one `<template data-variant="…">` per variant. Small, readable, diffable. - `prototypes/<slug>.html`: the deliverable, assembled by `scripts/build-prototype.mjs` from the parts file and the harness in `assets/template.html`. Never hand-copy or retype the harness; it is large and must stay intact.

Default location is `prototypes/` at the project root (create it). Put it next to the feature instead if the repo clearly organizes design artifacts elsewhere, and follow an explicit user path over either.

The built file contains the **Design Deck**, a draggable floating panel that:

- flips between variants (◀ ▶, or ← → keys), and between screens inside a variant when the variant declares them - offers vibe presets (Neutral, Calm, Bold, Editorial, Playful, Technical, Midnight, Mono, plus any you add) and ~25 dials: Feel macros (warmth, energy), Type (display/body fonts from a curated Google Fonts list, base size, scale, line height, tracking, weights), Color (light/dark, accent hue/sat/light, secondary hue shift, neutral hue/tint, surface depth, contrast), Shape (radius, border, elevation), Space (density, container width), Motion, and any custom controls the manifest adds - previews at Fit / 390 / 820 / 1280 / 1536 widths (each variant is its own document, so real media queries respond) - collects notes and click-to-pin comments on elements, saves snapshots to compare looks, and persists everything in `localStorage` per prototype - **Export to LLM** copies the handoff block; JSON copies only the JSON; View shows it for manual copy when the clipboard is blocked

TUI prototypes use the same file and deck with a terminal-specific dial set (theme, font, columns/rows, border glyphs, cursor, CRT scanlines).

## Step 1: Get the brief (fast)

Pin these down, from `$ARGUMENTS`, the conversation, and the repo, before planning:

- **Subject and audience**: what is being designed, for whom, and the one job the screen has. - **The design question**: what the prototype should settle ("table or cards?", "wizard or single form?", "does the sidebar earn its space?"). The export carries this brief, so write it as a real sentence. - **Kind**: `web` by default; `tui` when the subject is a terminal/CLI tool (ncurses, Ink, Bubble Tea, Textual, ratatui, a curses dashboard, a CLI wizard). - **Variant count**: default 3, cap 5. Fewer when the question is narrow, never more than five (they stop being different and start being noise). - **Where to save**: default `prototypes/<slug>` as above.

Look around the repo for things that make the prototype feel like *their* product rather than a generic page: a `DESIGN.md` (the `ai-assist-design-creator` output), `tailwind.config.*`, CSS custom properties, an existing nav/header, brand name, real entity names and data shapes, existing copy. Seed the manifest `defaults` and a brand preset from them and use the real content. Say what you reused.

Ask at most one or two questions, and only ones whose answer changes the work (for example, which existing page hosts this, or web vs TUI when genuinely ambiguous). If the user is not around, state your assumptions in the plan and build anyway; a prototype that exists is easy to redirect, a questionnaire is not.

## Step 2: Plan the variants

Read `references/variant-playbook.md` for archetype menus per surface type, content rules, the quality floor and the self-critique checklist. Then write a compact plan:

| id | name | thesis (what this variant bets on) | structure in one line | |---|---|---|---| | `ledger` | Ledger | Power users scan; a dense table beats cards | top nav, KPI strip, full-width table, detail screen | | `beds` | Garden beds | Spatial grouping mirrors the real garden | sidebar of beds, card grid, detail screen | | `journal` | Journal | One thing at a time, phone-first | single column feed, sticky primary action |

Hold the set to a structural-diversity test: if two variants would look alike with the same preset applied, one of them is a recolor, so redo it with an explicit structural constraint ("no card grid", "no sidebar", "list + detail"). Decide up front which screens a variant needs (usually a main screen and one drill-in), which custom controls earn a dial (sidebar width, density of a specific table, a chart style: things a dial can express and the user will actually want to tune), and one or two brand presets.

Show the plan in chat in a few lines and proceed. If the user is present they can redirect before you build; do not block on approval.

## Step 3: Build the parts file and assemble

Read `references/token-contract.md` before writing any CSS. It lists the manifest schema, every dial, every `--pt-*` variable the dials drive, the helper classes, screens, and the `PT` bridge API. For `kind: "tui"` also read `references/tui-prototypes.md`.

Author `prototypes/<slug>.parts.html`:

```html <script type="application/json" id="pt-manifest"> { "schema": "ai-assist-prototype/manifest@1", "id": "garden-dashboard", "name": "Garden Companion · dashboard", "kind": "web", "brief": "Home screen for a garden planner. Hobby gardeners on laptop and phone. Table-first, sidebar cards, or journal feed?", "controls": "web", "defaults": { "accentHue": 140, "fontDisplay": "Fraunces" }, "extraControls": [ { "id": "sidebarWidth", "label": "Sidebar width", "group": "Layout", "type": "range", "min": 200, "max": 340, "step": 10, "default": 260, "unit": "px", "var": "--x-sidebar-w" } ], "presets": { "Garden": { "accentHue": 140, "neutralHue": 90, "radius": 12 } }, "variants": [ { "id": "ledger", "name": "Ledger", "thesis": "Dense table for scanning", "screens": [{ "id": "home", "name": "Today" }, { "id": "plant", "name": "Plant" }] }, { "id": "beds", "name": "Garden beds", "thesis": "Sidebar of beds, cards per plant", "tokens": { "radius": 16 } } ] } </script>

<template data-variant="ledger"> <style> .hero h1 { font-size: var(--pt-t-3xl); } .card { background: var(--pt-surface); border: var(--pt-border) solid var(--pt-border-color); border-radius: var(--pt-radius); padding: var(--pt-s-5); box-shadow: var(--pt-shadow-sm); } @media (max-width: 720px) { .kpis { grid-template-columns: 1fr 1fr; } } </style> <section data-screen="home" data-screen-name="Today"> … </section> <section data-screen="plant" data-screen-name="Plant" hidden> … </section> <script> PT.root.addEventListener('click', e => { const g = e.target.closest('[data-go]'); if (g) PT.go(g.dataset.go); }); </script> </template> ```

Authoring rules that make the dials and the export work:

- **Consume tokens, never hardcode the look.** Colors via `--pt-bg / --pt-surface / --pt-surface-2 / --pt-text / --pt-text-muted / --pt-border-color / --pt-accent / --pt-accent-soft / --pt-accent-2`, type via `--pt-font-display / --pt-font-body` and `--pt-t-xs … --pt-t-5xl`, spacing via `--pt-s-1 … --pt-s-9`, shape via `--pt-radius*`, `--pt-border`, `--pt-shadow-sm/md/lg`, motion via `--pt-dur-*`. Decorative illustration (a gradient thumbnail) may use accent-derived vars; the validator warns on anything else. - **Each variant is its own document.** Plain selectors are safe, `@media` queries work, the Deck's viewport buttons resize the document. Base styles and optional helpers (`.pt-container`, `.pt-card`, `.pt-btn`, `.pt-btn-primary`, `.pt-input`, `.pt-badge`, `.pt-muted`, `.pt-eyebrow`) are present; use them or style your own structure. - **Real content.** The product's words, entities and realistic quantities. No lorem ipsum, no "Item 1". Placeholder art is CSS gradients or inline SVG, never remote images. - **Light interactivity is welcome** (tabs, hover, open a detail screen, toggle a state) with in-memory data, no network, no persistence. Inline `<script>` in a template runs when that variant mounts; `PT.root` is its document, `PT.go(id)` switches screens, `PT.tokens()` / `PT.on('tokens', fn)` react to dials. - **Quality floor**: responsive at 390 / 820 / 1280, visible focus, reduced motion honored (the base styles do this), readable in both modes, no horizontal overflow (`minmax(0, 1fr)` in sidebar grids).

Assemble and validate in one command (`<skill-dir>` is the folder containing this SKILL.md):

```bash node <skill-dir>/scripts/build-prototype.mjs --parts prototypes/<slug>.parts.html --out prototypes/<slug>.html ```

The build splices your parts into the harness, sets the page title, and runs `scripts/validate-prototype.mjs` (manifest shape, every variant has a template and vice versa, self-contained, token usage lint). Fix errors; treat warnings as review notes and clear the ones that are not deliberate.

## Step 4: Verify like a design lead

1. Open it. Windows: `start "" "prototypes\<slug>.html"`; macOS: `open prototypes/<slug>.html`; Linux: `xdg-open prototypes/<slug>.html`. The file works from `file://`. 2. If you have browser automation, drive it instead of guessing: load the file (or serve the folder locally if your tool refuses `file://`), then use `window.__PT__`: `await __PT