---
name: html-prototype-builder
description: Use when generating, revising, debugging, validating, or freezing runnable HTML prototypes for Web admin consoles or mobile apps. Consumes analysis.md, PRD, product-fact-context.md, shared-context.md, and ui-system/ to produce versioned index.html, styles.css, app.js, data.js, and prototype-readme.md with stable IDs, interactions, mock data, states, role differences, and PRD-prototype consistency. Do not use for requirement analysis or UI system design.
---

# HTML Prototype Builder

## Purpose

Use this skill as the runnable HTML prototype engine in a Codex product-design workflow.

It turns:

- `analysis.md`
- `admin-prd.md` or `mobile-prd.md`
- `shared-context.md`
- `product-fact-context.md`
- `ui-system/`
- User revision notes or Multica feedback

Into:

- A versioned, runnable HTML prototype
- Prototype documentation
- Validation notes and revision records

This skill builds prototypes. It does not perform upstream requirement analysis, design the project UI system, maintain the product fact source, or decide development issue splitting.

## Required Inputs

Before generating or revising a prototype, require or explicitly mark missing:

- Target surface: `admin` or `mobile`
- Iteration ID and version
- Relevant PRD
- `analysis.md`
- `shared-context.md`, if cross-end or shared rules exist
- `product-fact-context.md`
- `ui-system/README.md`
- `ui-system/design-tokens.md`
- `ui-system/component-patterns.md`
- `ui-system/page-patterns.md`
- `ui-system/interaction-patterns.md`
- `ui-system/prototype-rules.md`

If `ui-system/` is missing, ask to run `product-ui-system` first or create a clearly marked draft UI system before building.

## Workflow

1. Identify target surface and version path.
2. Read relevant references only as needed:
   - Use [prototype-output-contract.md](references/prototype-output-contract.md) before creating files.
   - Use [html-implementation-rules.md](references/html-implementation-rules.md) while implementing.
   - Use [state-and-data-rules.md](references/state-and-data-rules.md) when modelling states, permissions, and mock data.
   - Use [debugging-and-validation.md](references/debugging-and-validation.md) before delivery.
   - Use [freeze-and-revision-rules.md](references/freeze-and-revision-rules.md) for frozen versions or feedback revisions.
3. Map PRD pages, actions, fields, states, and acceptance criteria to prototype elements.
4. Apply `ui-system/` tokens, components, page patterns, and interaction patterns.
5. Generate or update the prototype files.
6. Use stable IDs for pages, actions, fields, and states.
7. Implement state switching in the page UI, not only in developer tools.
8. Validate that the prototype runs and core interactions work.
9. Check PRD-prototype consistency.
10. Freeze by creating a new version directory when the prototype is ready for review.

## Output Structure

Use:

```text
prototypes/iterations/{iteration-id}/{admin|mobile}/{version}/
  index.html
  styles.css
  app.js
  data.js
  prototype-readme.md
```

Simple prototypes may start with a single `index.html`, but Multica review versions should use the standard structure unless the project explicitly chooses otherwise.

## Implementation Rules

- Admin and mobile prototypes are generated separately.
- Use relative paths for local files and navigation.
- Prefer small patches for revisions.
- Avoid whole-file rewrites for large prototypes unless intentionally regenerating a clean version.
- Do not overwrite a frozen version; create a new version directory.
- Keep business terms, field names, enum values, permissions, and states aligned with PRD and `product-fact-context.md`.
- Keep visual choices aligned with `ui-system/`; do not invent styling freely.
- Include realistic mock data that helps review normal, boundary, empty, error, and permission states.

## Stable IDs

Use stable attributes:

```html
<section data-page-id="PAGE-001">
<button data-action-id="ACT-001">
<input data-field-id="FIELD-001">
<div data-state-id="STATE-001">
```

Stable IDs must correspond to PRD IDs when the PRD provides them. If the PRD lacks IDs, create IDs and report them so the PRD can be updated.

## Done Definition

The prototype is done only when:

- The prototype can be opened locally.
- The page is nonblank and styled.
- Core navigation and interactions work.
- Required states can be viewed by a reviewer.
- Mock data matches PRD terminology and enums.
- Admin or mobile viewport has no obvious layout breakage.
- PRD pages, actions, fields, states, permissions, and acceptance criteria can be traced to prototype elements.
- `prototype-readme.md` explains run method, version, scope, implemented states, known gaps, and related PRD.