prototyper

name

prototyper

description

Prototype UI flows, pages, or components as multiple live, switchable variants before implementation. Use when the user asks to prototype, explore variants, compare design options, ideate a UI flow, try a few approaches, see different ways something could work, or choose between interaction paradigms. Build a self-contained HTML artifact by default, use an inline app prototype only when real app context is necessary, include a rationale view with a recommendation, and hand off the chosen variant into production code on request.

Prototyper

Create live UI prototypes that help the user choose an interaction direction before committing to production implementation.

The deliverable is a decision tool: multiple distinct variants, realistic content, real-feeling interaction, and a rationale that explains which option is strongest and why.

Default to a self-contained HTML artifact. Use inline app prototypes only when the user explicitly wants to feel the prototype inside the real app shell, or when real auth/data/context is necessary.

Intake

Infer reasonable defaults and keep momentum. Ask only when the prototype target is genuinely unclear.

Confirm these choices in 2-3 lines, then build:

• Target: flow, page, component, or state to prototype.
• Mode: html by default; inline only when needed.
• Variant count: 3 by default. Never produce fewer than 2.
• Existing implementation: read it if relevant. If the user says to ignore it, start clean.

Use the user's brief as the source of truth. Do not turn prototyping into a requirements interview.

Ground The Prototype

Read the real product and design context before designing.

Prioritize these files when present:

File	Extract
DESIGN.md	Design principles, visual rules, component guidance, named constraints, anti-patterns.
PRODUCT.md	Product voice, audience, UX principles, anti-references, emotional register.
src/app/globals.css	Exact design tokens, especially :root, .dark, font variables, radii, shadows, and color values.

Then read feature-specific context:

• Existing components for the flow or surface.
• Feature docs for real fields, options, costs, limits, and states.
• Locale files.
• Neighboring views that show local layout, copy, and component conventions.

For inline mode, also inspect the app's UI primitives and one adjacent route before building.

Never use placeholder fields, invented pricing, generic colors, or marketing copy when real product context is available.

Design Variants

Make each variant a distinct interaction paradigm, not a visual restyle.

For every variant, write a one-sentence bet:

This variant bets that...

Examples of valid paradigms:

• Full-page stepper: one decision at a time, maximum calm.
• Centered dialog: familiar overlay, improved structure and breathing room.
• Slide-over sheet: preserve background context while configuring.
• Inline expansion: keep the user in the list or dashboard.
• Command palette: keyboard-first, fast, power-user oriented.
• Quick-start presets: optimize for the common path, expose advanced config second.
• Conversational setup: reduce anxiety through guided exchange.
• Split configure-and-preview: show consequences while choices are made.

These are just examples, you can use some of them and design different ideations as well.

Reject variants that differ only by spacing, color, copy density, or card treatment. If two options serve the same mental model, merge them and explore another axis.

Build Mode: HTML Artifact

Use this mode unless the user asks for inline.

Create one self-contained file:

artifacts/<prototype-name>-prototypes.html

The file must open directly in a browser with no build step.

Include:

• Inlined design tokens copied exactly from globals.css.
• Inter and Cairo font loading when bilingual or RTL support matters.
• html[dir="rtl"] styling that switches to Cairo and mirrors layout cleanly.
• Plain-CSS primitives that honor the app design system.
• Real product fields, options, copy, costs, modes, and states.
• A believable surrounding app context, not a blank canvas.
• A fixed variant switcher.
• A language/direction toggle when the product supports Arabic or RTL.
• Real interaction: selectable choices, step changes, cost updates, preview changes, animated conversational replies, or equivalent stateful behavior.
• Visible focus states.
• prefers-reduced-motion handling.
• Mobile-safe layout with no overflow.

Use Tailwind CDN, Lucide UMD, Google Fonts, and inline CSS/JS as needed. Do not add npm dependencies for HTML mode.

After writing the artifact, open it for the user.

Build Mode: Inline Prototype

Use this mode only when the prototype needs the real app shell or app-native feel.

Place throwaway prototype code under:

src/app/[lang]/_proto/<prototype-name>/page.tsx

Requirements:

• Use real app components, Tailwind tokens, i18n helpers, and local conventions.
• Mock data inline.
• Do not write to the database or call real mutations.
• Add a visible banner: Prototype - not wired to real data.
• Include a floating variant switcher.
• Keep the route clearly temporary.
• Remove the _proto code during hand-off.

Do not copy the HTML artifact's plain CSS into React. The HTML prototype is a spec, not production code.

Rationale View

Every prototype must include a rationale.

For HTML mode, add a switcher tab or panel named Why these?.

For each variant, include:

Field	Meaning
Name	Short variant name.
The bet	One sentence describing the user need or mental model.
When it shines	Situations where this variant is strongest.
Tradeoffs	Honest costs, risks, or weaker contexts.
Recommendation	Whether to choose it, reject it, or pair it with another option.

Mark one variant, or one pairing, as favorable. Ground the recommendation in the product principles and the user's goal. Do not hedge equally across every option.

For inline mode, include the rationale in the chat reply as a concise markdown table.

Hand-Off

When the user says implement, hand off, go with this, or chooses a variant, build the selected direction for real.

Before editing, restate:

• The chosen variant.
• The production files it will affect.
• What prototype behavior must be preserved.

Then implement using the real stack:

• Use real React/app components, not the HTML prototype's CSS copies.
• Use Tailwind tokens and established UI primitives.
• Use real i18n keys for every supported locale.
• Preserve the chosen variant's pacing, structure, copy register, and interaction model.
• Wire real mutations only where appropriate for the production feature.
• Remove inline _proto routes.
• Keep HTML artifacts as design records unless the user asks to delete them.

Verify with the project's normal checks:

npm run lint
npm test

Run only relevant tests when the suite is large. Open the real flow in a browser and sanity-check that it preserves the prototype's intent.

Quality Bar

A prototype is complete only when:

• It uses exact available design tokens, not approximations.
• It contains at least two genuinely different interaction paradigms.
• Every variant has a clear one-sentence bet.
• Copy, fields, options, and states come from real product context.
• The switcher makes comparison instant.
• The rationale view names a recommended direction.
• RTL and locale behavior work when relevant.
• Focus states are visible.
• Motion respects prefers-reduced-motion.
• The layout does not overflow on mobile.
• HTML mode opens without a build step.

Anti-Patterns

Avoid:

• Three versions of the same layout with different styling.
• Hardcoded approximate colors when tokens exist.
• Lorem ipsum, fake fields, or invented options.
• A prototype with no rationale.
• A rationale that refuses to recommend.
• Over-interviewing before making.
• Copying throwaway HTML/CSS into production React.
• Forgetting RTL or locale parity for bilingual products.