build-prototype

Files (10)

• SKILL.md
• openai.yaml · agents/
• README.md · evals/
• evals.json · evals/
• compare.html · evals/fixtures/compare-resume/
• project.md · evals/fixtures/compare-to-prototype/
• project.md · evals/fixtures/dark-tokens/
• tokens.css · evals/fixtures/dark-tokens/
• comparison-shell.html · templates/
• shell.html · templates/

SKILL.md (first lines)

# Build Prototype

Build a disposable but finished-looking model of the whole surface so the user
can settle structure, relationships, and behavior before implementation.

Separate the product layer from the decision layer: `prototype.html` holds the
canonical product screens and flows; a temporary `compare.html` resolves the
user's current question in its specific situation. Scope the comparison by what
the decision needs, whether a component, a screen, or a short flow.

When it is unclear where the user needs to open the preview, ask once whether
they will review it only on the computer running the work or also on another
device. Use a nonblocking question when the host supports one; otherwise finish
the access-independent build before asking. Do not infer the review device from
the execution host or treat no answer as a choice. Select the execution and
hosting method from the available environment; do not prescribe a particular
platform.

For a local comparison request, go directly to **Compare one decision** and
limit building and verification to that decision. The whole-surface inventory,
review, and preservation gates apply to the prototype, not to this intermediate.

## Set the effort

Accept `effort=standard` or `effort=high`. Recommend and use `standard` when the
argument is omitted.

Pass one base completion gate at either effort: produce a finished-looking
surface, cover every requested screen and relevant state, make intended
interactions and reset paths work, exercise every relevant viewport in a
browser, correct every reproduced defect found during that inspection, and
share an address the user can open. Hold this gate fixed at `standard`.

- `standard` uses the base gate as its complete result.
- `high` passes the same base gate, then adds close visual matching to an
  inspectable current product or reference through **Review and converge**.
  When the host supports subagents, delegate the audit to one fresh reviewer
  subagent at high model
  effort and give it the reference and candidate artifact without the builder's
  findings. Otherwise separate the build and verification passes and report
  that reviewer independence or model effort was unavailable. If no reference
  can be inspected, report that visual equivalence is unverified and use the
  extra pass only to strengthen layout robustness.

## Ground the prototype

Use the request and conversation as scope. When present, read `GLOSSARY.md`,
relevant subjects from `docs/decisions/README.md`, and a work-unit spec only
when the request or a prior handoff identifies one. Do not search for a spec.

Inspect the existing product and design system as evidence. Use their canonical
terms, interface language, tokens, and components; otherwise use the user's
language and the template's finished minimal style. Include the baseline in the
review only when the user is choosing between it and the candidate. Surface
conflicts instead of resolving them silently.

Hold confirmed relationships fixed. Keep overlays, drawers, and modals attached
to their source screen unless the user is reconsidering that relationship.

## Build one canonical product surface

Present the screen inventory as a correctable draft and begin building without
waiting for approval.

Copy [templates/shell.html](./templates/shell.html) into one temporary,
self-contained HTML file and grow every product screen inside it. Preserve and
follow the template's contract comment; it owns the review chrome, product-pixel
boundary, screen and state semantics, and viewport behavior. Keep one canonical
version of each product screen in this file.

Keep one-click and transient changes as working product interactions, however
different they look. Reserve selector presets for important multi-step results,
forced data or errors, and structures that are not trivial to reach. Synchronize
the selector when interactions enter or leave a declared preset.

Copy project tokens verbatim into `:root`, or extract the existing design
language when no token file exists. When the project ships a dark palette, copy
it under `.sh-theme-dark` so the shell's theme switch appears; a project without
one leaves the prototype with no theme control rather than an invented dark
mode. Style every screen through those tokens and mark elements with the design
system's component names in `data-component`; use `new:Name` only when no
component exists.

Use realistic dummy content with real-length names, plausible copy, awkward
numbers, and only relevant edge conditions. Never use lorem ipsum. Keep out real
data, APIs, latency, production routing or state wiring, frameworks, build
steps, and network dependencies.

Use a phone frame for native app mockups and start mobile-first prototypes in
the template's narrow viewport; its classes own simulated responsive behavior.

## Review and converge

Render and inspect the artifact before presenting it. Exercise every screen,
declared state, interaction entry and reset path, and relevant viewport in a
browser. Run the finished HTML using a method supported by the current harness
and share an address the user can open. Explain differences, rationale, and
review guidance in the conversation, outside the product pixels. Present the
artifact and correctable screen draft, walk through the surface screen by
screen, and ask what to change. Do not close an open review with a completion
handoff.

For `high`, audit through two independent lenses. Compare the reference and
prototype at matching screen, state, and viewport coordinates for typography,
spacing, alignment, wrapping, overflow, and asset treatment. Separately stress
layout and interaction recovery with realistic long or awkward content. Give
each material mismatch candidate its exact coordinate, observed evidence, and
reproduction path. Have the fresh reviewer subagent reproduce candidates when
one is available, discard those that do not reproduce, and correct the verified
set until no reproduced material mismatches remain.
After a correction, re-render its coordinate and the other screens or states
that share the changed token, component, or shell behavior. Report the audited
coverage and any unverified coordinates or fidelity claims in the conversation.

## Compare one decision

For one unresolved visual or interaction decision, copy
[templates/comparison-shell.html](./templates/comparison-shell.html) into a
temporary `compare.html`. Name the concrete user situation and render up to

From toy-crane/skills, MIT.

More from toy-crane/skills