Repository boundary: advisory design guidance only

Downstream adaptation for Issue #841. This reference provides design advice, not execution authority. Current main canonical documents, CLAUDE Hard rules, existing components and their behavior, src/styles/tokens.css, i18n, security rules and the user's actual permissions take precedence. Preserve the incumbent design and authorized scope. Missing design documents do not imply a greenfield project. Do not create or replace PRODUCT.md, DESIGN.md, sidecars or other project documentation automatically. Review requests and visual selections do not authorize applying changes, installing tools, replacing dependencies, downloading fonts/assets, changing settings, or publishing. Any implementation needs its own applicable authorization. No external engine, hook, launcher, helper agent or operational fallback is enabled by these files. Generic examples illustrate design concepts; adapt their values to existing tokens and their copy to i18n. Accessibility suggestions do not waive repo tests, independent review or release gates.

Prototyping Variants

Hard Rules

1. Never touch production code during exploration. Everything lives in an isolated prototype surface (see Phase 4). A selected variant is a design preference; integration needs a separately approved change scope.
2. Variants diverge on a named axis — layout, density, personality, motion, interaction model. Before building, you must be able to state each variant's axis in a phrase. Sharing the project's tokens is not convergence; variants should feel native to the product.
3. Every variant fully works. Real interactions, real motion, realistic content — actual product-shaped copy, plausible names and numbers. No lorem ipsum, no dead buttons, no "imagine this part".
4. A picker is illustrative comparison chrome. PICKER.md illustrates anatomy and keyboard behavior. Adapt any separately authorized implementation to current tokens, fonts, components and i18n; never copy raw values into the app.
5. Cleanup is separately scoped. A visual choice does not authorize integration, deleting files or replacing components. Preserve artifacts unless cleanup is explicitly authorized.

Workflow

Phase 1 — Scope

One thing per run. If the description spans multiple components ("the dashboard"), narrow it: pick the single highest-leverage piece, say which and why, and offer the rest as follow-up runs. Restate the brief in one sentence — what the thing is, where it will live, what it must do.

Phase 2 — Recon

Before designing anything, map the ground the variants must stand on:

• Stack: framework, styling system (Tailwind, CSS modules, vanilla), motion library if any.
• Tokens: colors, radii, spacing, fonts, easing/duration variables. Variants use these — every variant should look like it could ship in this product tomorrow.
• Personality: playful consumer app or crisp dashboard? This bounds how far the boldest variant may go.
• Context: where the piece renders — against what background, beside what neighbors, at what sizes.

If there is no project (empty directory, or the user is just exploring), skip to the standalone branch in Phase 4 and choose a restrained default look: neutral grays, one accent, system font stack.

Phase 3 — Choose directions

Default 3 variants; up to 5 when the user asks or the design space is genuinely wide. More than 5 dilutes the comparison.

Before writing any code, list the set: a name and an axis for each. Names describe the direction — "Quiet", "Editorial", "Playful", "Dense" — never "Option A/B/C". If two proposed directions would differ only in accent color or copy, they are one direction; replace one with a real alternative (different layout, different interaction model, different motion story).

Completion criterion: every variant has a name and a stated axis, and no two variants share an axis position.

Phase 4 — Describe a comparison surface

When an artifact is explicitly requested, agree on its destination and boundaries first. Possible comparison surfaces are:

• In a project with a dev server — an isolated route or page (/prototypes/<slug>, or the framework's equivalent), one file per variant plus a small harness file. Nothing imports from the prototype surface into production code.
• No project / static context — a single self-contained HTML file (inline CSS/JS) the user can open directly in a browser.

Use PICKER.md as an illustrative anatomy reference. Preserve current project tokens, fonts, component conventions and i18n in any separately authorized implementation. Beyond the picker itself, the harness must render one variant at a time, full size, in realistic surrounding context — a toast needs a page behind it, a card needs siblings, a button needs a form. Side-by-side thumbnails distort spacing and scale; never judge UI at postage-stamp size. Switching is instant — flipping is a 100+/session action; by the frequency rule the variant swap gets no animation.

Phase 5 — Verify and hand off

If a comparison artifact was separately requested and implemented, use its authorized verification workflow. Confirm every variant renders, every interaction responds, and the console is clean — flip through all of them yourself before showing the user. If browser tooling is available, screenshot each variant.

Then present the set and stop — the choice belongs to the user:

#	Variant	Axis	When it's the right choice	Its cost
1	Quiet	Minimal motion, borders over shadows	The product is a daily-use tool	Least memorable
2	Editorial	Large type, generous whitespace	The moment deserves weight	Eats vertical space

Close with where the picker is running (URL or file path) and the keys to flip.

Completion criterion: every variant is reachable from the picker and behaves correctly; no console errors; the table names each variant's tradeoff honestly.

Phase 6 — Record the choice

When the user picks, record the preference and describe the corresponding proposed change. Integrate or delete artifacts only under separately scoped authorization, following existing components, tokens, i18n, tests and documentation governance. A preference alone is not Apply consent.

Advisory comparison topics

These phrases identify design preferences, not executable commands or permission to create artifacts.

Topic	Advisory response
<description>	Describe the scope, existing context and up to three alternatives; create a comparison artifact only when explicitly requested
<description> x5	Describe up to five alternatives and their tradeoffs; any artifact keeps its own requested destination and scope
riff <variant>	Describe a fresh comparison around the named direction; generating or changing artifacts requires a separate request
keep <variant>	Record the preference and propose integration and cleanup; perform either only under specific authorized scope
keep <variant>, leave the picker	Record the preference and intention to preserve comparison artifacts; propose integration only, subject to specific authorized scope

Tone

Sell each variant honestly — one line on when it wins, one on what it costs. Never pre-pick a favorite in the table; if the user asks which you'd choose, answer with a reason rooted in the product's personality and frequency of use, not aesthetics alone. If two variants converged while you built them, cut one and say so: a picker with two truly distinct directions beats one padded to three.