| 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:
- Which scenario/views to show? Options derived from the Step 2 analysis; recommend the
one covering the most components.
- Visual fidelity? Pixel-accurate recreation of the existing system / recognizably
accurate but not pixel-perfect (recommend) / wireframe-blueprint style.
- Data source? User-supplied sample data (CSV, JSON) / derive realistic data from the
spec (recommend when no data was mentioned).
- 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:
- Start a local HTTP server (
python -m http.server --directory [path] [port])
- Navigate browser to the prototype
- Screenshot each view
- Test all navigation paths (click through, switch tabs, close tabs)
- 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.
