design-wireframe

name	design-wireframe
description	Compose real design system components into full responsive page layouts with real data points. Uses ds- components from the HTML Template design system. Triggers on 'wireframe this page', 'create layout', 'build screen', 'design the page structure'.
allowed-tools	["Read","Write","Bash","Glob","Grep","Edit","Agent","WebFetch","WebSearch","AskUserQuestion"]

Design Wireframe

Compose design system components into full-page wireframe layouts with real data. Wireframes use actual ds- components with real labels and values — the neutral token styling IS the wireframe aesthetic. Style phase later overrides CSS custom properties with zero markup changes.

1. Pre-flight

Read state.json from the project root. Extract designSystemPath and projectPath.

Read {designSystemPath}/manifest.json to load all available components, their variants, sizes, and data attributes.

Read decomposition.json from the project directory for the full list of flows, pages, templates, patterns, components, and dataFields.

Read references.json for tagged inspiration with pattern and layout recommendations.

If decomposition.json or references.json are missing, warn the designer: "I don't have decomposition/references from prior phases. Please provide a list of pages and the components each page needs, or run /design-analyze and /design-inspire first."

Create the output directory: wireframe/screens/ inside the project path.

2. Page Planning

List every page from decomposition.json and present the plan:

"You have {N} pages to wireframe: {list of page names grouped by flow}. I'll start with {first page name}."

For each page, identify:

• The flow it belongs to
• The layout type (scroll, tabs, split, grid)
• Which patterns apply (from decomposition patterns and references)
• All dataFields that need to appear

3. Per-Page Wireframing

Work through pages one at a time in an interactive loop.

Step 1 — Layout Proposal

Present 2-3 layout approaches for the page. Star the recommended one. Reference the inspiration from references.json and explain why.

Example: "For the Listing Detail page, I recommend: ★ Hero scroll — full-width image hero, sticky bottom CTA bar, content sections below. Alternative: Tab sections — image at top, tabbed content (Overview / Reviews / Location)."

Step 2 — Build the Page

Generate the complete HTML file using the template and component snippets from references/page-generation.md.

Rules:

• Use REAL data from dataFields — actual property names, prices in correct currency, plausible ratings
• Use every relevant ds- component with correct data-* attributes
• Include Phosphor icons via <i class="ph ph-{name}"> for all icon slots
• Use domain-relevant placeholder images from Unsplash (https://images.unsplash.com/photo-{id}?w=400&h=300&fit=crop) — NEVER use picsum.photos (it produces random irrelevant photos). For wireframes, use neutral/grayscale Unsplash images or simple solid-color placeholder <div>s with icon overlays.
• Apply layout patterns: sticky nav, sticky CTA, scroll rows, card grids
• Build ALL sections from the decomposition — if the decomposition lists 15 sections for a page, the wireframe must have all 15. Do not skip sections to "simplify" — missing sections will require painful iteration later.
• Keep the page functional — it must open directly in a browser and render correctly

Save to wireframe/screens/{page-name}.html.

Step 3 — Pattern Decisions

For each pattern on the page, state the chosen approach and its source:

"For the search bar, I'm using persistent with leading icon (inspired by your Airbnb reference). For the property cards, I'm using a vertical card grid with heart save button. Want alternatives for any of these?"

Step 4 — Data Point Review

List all data fields rendered on the page. Ask the designer to confirm:

"This card shows: name, location, price/night, rating, review count, thumbnail. Missing anything? Want to add or remove fields?"

Step 5 — Responsive Notes

Summarize how the page reflows:

"Mobile: single-column card stack. Tablet: 2-column grid. Desktop: 3-column grid with sidebar filters."

Step 6 — Lock or Iterate

Ask: "Happy with this wireframe? Lock it in, or want to iterate?"

• Lock: Update wireframe/wireframes.json with the screen entry (see references/wireframe-metadata.md for schema). Set status to locked. Move to next page.
• Iterate: Save as {page-name}-v{N}.html, increment version. Apply requested changes and re-present.

4. Output Generation

Each page is saved as a standalone HTML file at wireframe/screens/{page-name}.html. The file can be opened directly in any browser — no build step required.

Maintain wireframe/wireframes.json as the manifest tracking all screens, their status, versions, patterns, and data fields. Follow the schema in references/wireframe-metadata.md.

5. State Update

After each page is locked, update state.json:

• Add the screen name to phases.wireframe.screens
• Add locked screens to phases.wireframe.locked

When all screens from decomposition.json are locked:

• Set phases.wireframe.status to complete
• Announce: "All {N} wireframes locked! Ready for styling with /design-style."

Key Principles

• Real components, real data. Never use gray boxes or lorem ipsum. Every element is a ds- component with actual content.
• Design system first. Check manifest.json before inventing custom HTML. If a component exists, use it.
• Data attributes always. Every component carries data-component, data-variant, and relevant data-size/data-state.
• Browser-ready. Every HTML file works standalone — open it and see the wireframe immediately.
• Iterate fast. Present, get feedback, revise. Version files so nothing is lost.