build-lab

Lab

A lab is a durable experiment surface inside a website the user runs: a page where a design idea gets built against real production components, tuned with live controls, and retained as an instrument to revisit and as design history. The /lab section is the wing of the site that holds them, with a sidebar to move between labs.

Everything in this skill is a working default. Freely reshape its structure, tools, appearance, exposure, and lifecycle around the user's needs and the host codebase. Labs are optimized for retention, so keep them by default and record settled decisions in outcome metadata; remove them when the user or host lifecycle calls for it.

This skill is for setup: it installs the shell and teaches the host repo the vocabulary. Day-to-day lab authoring is then driven by the section it writes into the project's agents file — after setup, "make me a lab for X" needs no skill at all. If the project has no app-style routing or the user wants a standalone playground, the host can be a bare app whose only content is /lab.

The conventions

Canonical statement of the pattern. The agents-file template restates these for the host repo so it stands alone — an edit to either must be mirrored in the other.

• Folder = lab. A new folder with a page inside the lab directory appears in the sidebar automatically. No registration step, ever.
• File split: a thin server/route wrapper (page) plus a client component holding the experiment and its controls (lab).
• Optional metadata: a lab may carry a small meta module — title, description, date, outcome (a short note on what the lab decided, written once when accepted values go back to production; its absence just means the lab hasn't decided anything). Absent metadata falls back to the folder slug. Metadata is never required — there is deliberately no status field to keep fresh.
• Defaults flow from production. A tuning lab imports its starting values from the production module it tunes, so the lab can never drift from what ships. Accepted values travel back by copying the control panel's output and applying it to the production source — so whatever control-panel library is chosen must export its current values in copyable form.
• Harmonize with the destination. For changes to an existing page, section, or component, use its surrounding content, layout, hierarchy, and interface patterns as the starting point. Depart when that is part of the experiment.
• The control surface is an interface. Order controls in the sequence someone tunes the result, group them by concept, keep high-leverage choices visible, and collapse secondary calibration. Use clear labels, useful ranges, intentional defaults, and a placement that preserves the experiment's canvas. Its appearance follows the lab by default; an independent appearance is a deliberate experiment choice.
• The dependency points one way. The shell reads labs' metadata; labs stay independent of shell components, so swapping shells touches zero labs.
• Labs own their canvas. The shell stays background-free edge to edge; an opaque shell layer silently covers labs that paint fixed or negative-z backdrops.
• Exposure follows the host. Public labs default to direct access, noindex, and omission from the sitemap and main navigation. Protected labs reuse the host's route protection or deployment infrastructure at the /lab boundary; noindex is metadata, not access control. Read references/access-control.md when protection is selected or already exists.
• Variants inside a lab use a ?v=<name> search param, each named for the axis it diverges on (layout, density, personality, motion). Retain unadopted variants by default for later comparison; the outcome note names the one that was accepted. Follow the user's or host's cleanup preference when it differs. Read references/variant-comparison.md when one lab needs rapid comparison between structural or interaction directions; parameter snapshots stay in the control panel.