Prototype Lab

Prototype Lab

Dated owners live at prototypes/<YYYY>/<MM>/<NNN>-<slug>/. Each one runs from its own index.html. metadata.json is the source of truth. Library and compare views are generated.

State-machine / logic throwaways: html-lab, not this skill.

Choose The Smallest Route

• Flip live visual variants of one piece: picker. No dated owner.
• Test one idea: quick
• Compare independently runnable options: compare
• Verify and package: ship

Run node <skill-root>/scripts/manage-prototype-lab.mjs help. In this repository: pnpm run lab -- <command>.

Picker Route

Use when the question is which visual direction to keep for one UI piece and the user wants to flip live. Skip init / quick unless they also need a dated lab owner.

1. Scope to one piece. If the brief spans a dashboard, pick the highest-value control and say why.
2. Recon stack, tokens, personality, and where the piece sits. No project: neutral grays, one accent, system font.
3. Default 3 variants, cap 5. Name + axis each. Names describe direction (Quiet, Editorial), never Option A. Two tints of one idea are one variant — replace one.
4. Build the picker from references/picker.md verbatim. Isolated route or one HTML file. One variant at a time, full size, realistic context. Instant swap. Do not touch production code.
5. Exercise every variant. Present the set and stop. User chooses. Honest cost per direction.
6. Promote the winner into the product, then delete the picker surface unless they asked to keep it.

Quick Route

1. ... init once per workspace (creates prototypes/ and a simple index).
2. ... quick --title <title> --question <decision-question> [--profile blank|tool|mobile|canvas].
3. Build only inside the returned folder. Keep runtime, local assets, and proof there.
4. Look at it in a browser. ... preview --id <id> --open when modules, fetch, or media need an HTTP origin.
5. ... verify --id <id> for self-containment. ... attach-proof --id <id> --file <screenshot> after you looked.

create is the same command. adopt --path <static-folder> --question <text> for an existing self-contained build. fork --from <id> for a new iteration (proof is not copied).

Profiles:

• Default blank scaffold is neutral; from assets/prototype-blank/
• tool: compact app shell
• mobile: mobile-width root
• canvas: 2D/WebGL stage
• imported: assigned by adopt

Compare Route

1. Produce or adopt at least two standalone artifacts.
2. ... compare --ids <id>,<id> [--title <title>] [--question <text>].
3. The compare page is a tab + iframe switcher. It does not own the variants.

Ship Route

... ship --id <id> [--include-proof] runs verify, writes dist/prototype-lab/<slug>/ plus ZIP, and marks the owner complete.

The pack is host-neutral: no build command, server runtime, or SPA fallback. Packaging is not publication. ChatGPT Sites: adapt via sites-building, publish via sites-hosting; confirm before public sharing.

Read references/portable-run-pack.md before archive or upload. scripts/package-prototype-lab.mjs owns the static pack.

Integrity Contract

• One owner at prototypes/<YYYY>/<MM>/<NNN>-<slug>/ per independently generated result.
• metadata.json is the artifact source of truth.
• Keep required runtime files local. Reject horizontal overflow, root-relative URLs, external runtime dependencies, local paths, and missing references.
• Preserve existing work. Never overwrite unmanaged folders.

Conditional References

• references/picker.md: picker chrome. Copy verbatim.
• references/quality-bar.md: look at it in a browser before claiming it works.
• references/portable-run-pack.md: static/ZIP and publication safety.