wireframe-doc

What this skill does

The wireframe-doc skill lets you write product wireframes in plain Markdown and render them as a single deployable HTML file — no design tools, no Figma account, no multi-megabyte exports.

You write structured Markdown: ASCII frames that show what each screen looks like, a Mermaid flowchart that shows how screens connect, and bullet-note "sticky notes" that explain what's happening and what questions need answers. The render script assembles these into a polished review doc with a horizontal card strip, collapsible context sections, and a tap-to-enlarge modal for each frame.

The result is a shareable URL that works in any browser. Founders and teammates can view the flow, read the notes, and give targeted feedback by linking to specific frames via #frame-{key} anchors — no Figma view access, no Loom, no synchronous meeting required.

HTML in reviewer notes is sanitized by DOMPurify before rendering, so agent-generated content is safe to inject. CDN fallback shows raw source after 2 seconds if libraries fail to load.

When to use it

• Pre-design product reviews — founders need to see flow and intent before committing to a UI implementation. ASCII frames communicate structure without burning design time.
• Async team feedback on multi-flow user journeys — share a URL, collect comments in a chat thread. No realtime coordination needed.
• Lightweight specs that double as input to next-stage UI generation — structured frame notes and scene descriptions are clean input for a UI-generation agent.
• Replacing screenshot-heavy wireframe decks — a 1–2 MB Figma export becomes a ~50–215 KB self-contained HTML. Faster to share, faster to load, version-controllable as plain text.

When NOT to use it

• Pixel-perfect mockups — use a real design tool (Figma, Sketch, etc.). This is intentionally low-fidelity.
• Interactive prototypes — the output is static HTML. No clickable flows, no state transitions.
• Brand-styled comps — the template uses a neutral gray palette by design. It communicates intent, not aesthetics.

Lexicon

Terms the skill uses. AI agents authoring with this skill should treat these as the canonical vocabulary.

• Frame — one screen rendered with device chrome (the bezel, status strip / browser bar). Authored as a ### Frame: {Name} block with a key: line.
• Flow — a ## {Flow name} section containing one or more frames in sequence.
• Scene — optional flavor prose right after the ### Frame: line, before the ASCII block. Sets context, not content.
• Notes — the **Notes:** block alongside each frame. Full Markdown; reviewer-facing commentary, open questions, decisions.
• Device chrome — the rendered bezel + status strip (phone / tablet) or browser bar (desktop / custom). The renderer draws it; the author does not.
• Row budget — the per-device target number of ASCII rows (phone ~36–44, tablet ~44–56, desktop ~28–34). Used with the column budget to compose top → body → bottom.
• Decision-flow card — a flow block that captures decided logic (conditions, rules, branches). Complements the Mermaid screen-map; never replaces it.
• Stream → screens map — the ## Stream → screens Mermaid flowchart. Maps which frames connect, using frame keys as node IDs.
• Deep link — the per-frame URL anchor #frame-{key} used by the Copy link button. Position-independent — anchors don't change when frames are reordered.
• Kebab-case key — every frame's REQUIRED unique identifier (lowercase, hyphens). Drives Mermaid node IDs and deep-link anchors.

Non-Negotiables

Hard rules. Violating any of these breaks the visual or structural contract.

• The bezel IS the screen. Don't draw an outer ASCII box around the frame — the device chrome is the border. Internal panels and tables are fine.
• Compose top → body → bottom. Every frame has a top region, a body region, and a bottom region. Use deliberate blank lines, not invented content, to reach the row budget.
• ASCII inside ASCII; Markdown inside Notes. The screen block is verbatim monospace. Notes is full Markdown. Never mix.
• Decision-flow cards ≠ Mermaid. Mermaid maps which screens connect. Decision-flow cards capture decided logic. Use both; never substitute one for the other.
• Every frame has a kebab-case key. Required, unique per doc, lowercase-with-hyphens. Used as Mermaid node ID and deep-link anchor.

Quick start

1. Copy assets/spec-template.md to your project:

   cp ~/.claude/skills/wireframe-doc/assets/spec-template.md my-wireframes/spec.md
   

2. Fill in the YAML frontmatter (title, version, date, frame_count, deploy_url), then write your scene, open questions, flow diagram, and frames.
3. Render:

   node ~/.claude/skills/wireframe-doc/scripts/wireframe-render.mjs my-wireframes/spec.md my-wireframes/index.html
   

4. Open my-wireframes/index.html in a browser, or deploy to any static host (Vercel, Netlify, GitHub Pages, S3, file://).
5. Share the URL. Link to specific frames via #frame-{key} (e.g., your-url.com#frame-landing).

Spec syntax cheatsheet

YAML frontmatter fields:

• title — page title + header h1
• version — shown in header (e.g., v0, v1)
• date — ISO date (YYYY-MM-DD)
• frame_count — total frame count (validated against actual count — error on mismatch; use --lenient to warn)
• deploy_url — URL without https:// (shown in header + footer)
• default_device — OPTIONAL. Default device for all frames. Values: phone (default) / tablet / desktop / custom WxH.

**Devic