spec-to-prototype

name	spec-to-prototype
description	Use when the user has a spec document, design system reference, component library doc, wireframe description, or similar specification and wants a visual HTML/CSS dummy prototype built from it. Triggers on "build a prototype", "create a mockup from this spec", "prototype this design", "make a visual demo". Also use when converting technical documentation into stakeholder-ready visual demos. Do NOT use for production frontend implementation — this produces visual HTML/CSS dummies only, not shippable code.
effort	high
allowed-tools	Read, Write, Edit, Glob, Grep, Bash(python:*), Agent, Skill, AskUserQuestion

Spec-to-Prototype Builder

Build self-contained HTML/CSS visual prototypes from specification documents. Produces shareable single-file demos with realistic data and navigation — no backend, no build tools, no framework dependencies.

When to Use

• User has a spec, reference doc, design system doc, or component description
• Goal is a visual demo, not a functional application
• Stakeholder presentations, design validation, or vision casting
• User says "prototype", "mockup", "dummy UI", "visual demo"

Not for: Production apps, functional forms, real data integration, or creative/original UI design (use frontend-design skill directly for those).

Process

digraph prototype_flow {
  rankdir=TB;
  node [shape=box, style=rounded];

  read [label="1. Read & analyze spec"];
  identify [label="2. Identify prototypable views"];
  ask [label="3. Ask clarifying questions\n(batched, one AskUserQuestion call)"];
  design [label="4. Invoke frontend-design skill"];
  build [label="5. Build single HTML file"];
  test [label="6. Test in browser"];
  fix [label="7. Fix issues found"];
  done [label="Deliver"];

  read -> identify -> ask -> design -> build -> test;
  test -> fix [label="issues"];
  fix -> test;
  test -> done [label="clean"];
}

Step 1 — Read the Spec

Read the full spec document. Extract:

• Components/elements described (with names, anatomy, behaviors)
• Layout structure (shells, sidebars, content areas, navigation)
• Visual language (colors, typography, spacing, icons mentioned)
• Data model (what entities exist, what fields they have)
• Interaction patterns (what opens what, navigation flows)

Step 2 — Identify Prototypable Views

Determine what can be shown as static views. Propose 2-3 options to the user:

• Which views/scenarios best showcase the spec?
• Which combination hits the most components?
• What's the minimum set of views for maximum stakeholder impact?

Step 3 — Ask Clarifying Questions

Ask the four essential questions in one AskUserQuestion call — this is a short scoping exchange before a build, not an interview, and batching costs the user one interaction instead of four:

1. Which scenario/views to show? Options derived from the Step 2 analysis; recommend the one covering the most components.
2. Visual fidelity? Pixel-accurate recreation of the existing system / recognizably accurate but not pixel-perfect (recommend) / wireframe-blueprint style.
3. Data source? User-supplied sample data (CSV, JSON) / derive realistic data from the spec (recommend when no data was mentioned).
4. Single page or multi-page? Single self-contained HTML file (recommend, for shareability) / multiple views via CSS class toggling with minimal JS.

Each gets a header of ≤12 chars, multiSelect: false, and 2–4 real options with the recommended one first. Do not add a "let me type my own" option — the Other box is always there.

Persona, branding, or scenario context (agent name, company, use case) is free-form, not multiple choice: ask it as prose in the same turn, or skip it when the spec already supplies one. Stop when you have enough to build.

Step 4 — Design Direction

Invoke the frontend-design skill. The design direction depends on the spec type:

• Existing system recreation (e.g., ServiceNow, Salesforce): Match the platform's visual language — colors, fonts, spacing, component patterns. The goal is recognition, not originality. Use Google Fonts for the platform's typeface family.
• New design from requirements: Follow the frontend-design skill's creative direction process fully.
• Wireframe/blueprint: Gray boxes with labels, structural layout only.

Step 5 — Build Rules

Single file, self-contained:

• One .html file with all CSS embedded in <style> tags
• External dependencies limited to Google Fonts (typography + Material Symbols for icons)
• All data hardcoded inline — no fetch calls, no external JSON
• File should be sharable via email, Slack, or USB stick with zero setup

Minimize JavaScript:

• CSS-only for all visual states (hover, focus, active, badges, colors)
• JS permitted ONLY for view switching between multiple views in the same file
• View switching pattern: CSS classes toggled by ~10-line inline <script> at the bottom
• No frameworks, no libraries, no npm

CSS architecture:

• CSS custom properties (variables) for all colors, spacing, and sizing
• Logical grouping: shell, header, content, components, utilities
• Mobile-responsive only if requested — default to desktop viewport

Data realism:

• If user provided a data file, derive prototype content from real entries
• Generate 10-15 rows for list/table views (enough to feel real, not overwhelming)
• Use realistic names, dates, statuses, IDs — never "Lorem ipsum" or "Test 123"
• Vary data values (mix of priorities, statuses, time ranges)

Multi-view navigation:

• Default view visible on load, others hidden with display: none
• Both the hidden and visible views need explicit CSS rules for both states
• Clicking a list item opens a detail view; clicking back/tabs returns
• Session tabs persist in header when switching views (match workspace UX)
• Close (X) buttons on tabs remove the tab and return to default view

Step 6 — Test in Browser

If browser automation tools are available:

1. Start a local HTTP server (python -m http.server --directory [path] [port])
2. Navigate browser to the prototype
3. Screenshot each view
4. Test all navigation paths (click through, switch tabs, close tabs)
5. Check: icons render, badges colored correctly, layout not broken, all views accessible

Step 7 — Fix Issues

Common bugs to watch for:

• View toggle CSS: Both views need explicit display rules. A view without a display: none rule in its non-active state will bleed through.
• Close button scope: Tab close buttons should stopPropagation() to avoid triggering the tab's click handler, then hide both the view AND the tab element.
• Icon font loading: Material Symbols requires the Google Fonts link. If icons show as text, the font isn't loading.
• Overflow: Long content in fixed-height layouts needs overflow-y: auto on scrollable containers.

Output Structure

prototype/
  [name]-prototype.html    # Single self-contained file

Filename should reflect what it prototypes (e.g., agent-workspace-prototype.html, dashboard-prototype.html).

Common Mistakes

Mistake	Fix
Multiple HTML files	Combine into one with view toggling
External CSS file	Embed in <style> tags
Lorem ipsum data	Use realistic data from spec or user's data source
Heavy JS for interactivity	CSS-only states; JS only for view switching
Forgetting display:none for hidden views	Both active and inactive states need explicit CSS
Generic design when recreating existing system	Match the target platform's visual language

Error Handling

• No spec/reference document provided: ask the user for one before proceeding (see When to Use).
• No sample data file available for a data-heavy prototype: derive realistic data from the spec instead of using placeholder text (see Step 3, Q3), and never fall back to "Lorem ipsum" or "Test 123" (see Common Mistakes).
• Browser automation tools are unavailable for Step 6: skip in-browser testing, note the skip to the user, and rely on a careful manual review against the Step 7 common bugs instead of skipping verification entirely.
• Clarifying-question answers still leave visual fidelity or view scope ambiguous after 5 questions: pick the safer default (option B fidelity, single self-contained file) and state the assumption rather than asking indefinitely.
• Icons render as raw text during the Step 6 test: the Google Fonts / Material Symbols link isn't loading — fix per the Step 7 "Icon font loading" entry before delivering.