# Spec To Prototype

> 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.

- Skill: `davistroy/spec-to-prototype` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davistroy/spec-to-prototype`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davistroy/spec-to-prototype/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: davistroy (https://skillmd.com/u/davistroy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davistroy/spec-to-prototype

---


# 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

```dot
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

```text
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.