skills/ui-variations/SKILL.md

name, description, compatibility

name	description	compatibility
ui-variations	Create 3-5 materially different UI variations inside a web app, present them on a single preview page with a bottom-centered floating switcher, and after the user chooses a winner, fully integrate it and clean up the temporary variants.	opencode

UI Variations

Use this skill when the user wants help exploring UI directions for a new or existing web UI surface and wants real code, not static mockups.

This skill is optimized for browser-based apps first. Favor in-app previews that reuse the real design system, routing, and data flow. Fall back to an isolated preview page only when the target repo makes in-situ previewing awkward or risky.

Default Behavior

• Ask at most one short clarification if the target page, component, or feature area is unclear.
• Inspect the repository before editing. Look for design philosophy docs, design-system conventions, router structure, and existing component primitives.
• Only create variations of the UI surface the user asked for. Keep the rest of the page and surrounding experience stable unless the user explicitly asks for broader exploration.
• Generate 3-5 materially different variations.
• Present one variation at a time on a single preview surface.
• Add a floating bottom-centered variant switcher so the user can compare directions quickly.
• Make each variation look production-ready. Do not present wireframes, placeholder framing, or experiment-looking chrome unless the user explicitly asks for that level of fidelity.
• Keep rationale out of the UI itself. Do not render explanatory labels, design notes, or variation descriptions inside the previewed interface.
• If the agent-browser skill is available and the app can run locally, use it to visually inspect the rendered variants and refine obvious issues before asking the user to choose.
• Stop at the preview phase by default.
• If the user later picks a winner, fully integrate that choice and remove the preview-only artifacts.

Inputs

The skill can usually infer most of these from the repo. Only ask when a missing answer would block safe progress.

Input	Default	Ask only if needed
Target UI surface	Infer from user request and repo structure	Yes
Number of variations	4	No
Preview surface	In-situ when practical, isolated when necessary	No
Device emphasis	Existing repo defaults	No
Promotion behavior	Wait for user selection	No

Workflow

The work has two modes: preview mode and promotion mode.

Preview Mode

1. Discover the local UI language

Read the minimum necessary files to understand the app before editing:

• project docs such as README*, docs/**, CONTRIBUTING*, or design notes
• router and layout entry points
• component primitives, shared wrappers, and design tokens
• styling setup such as Tailwind config, CSS variables, theme providers, or UI libraries
• existing patterns for feature previews, internal-only routes, or story/demo pages

Use references/discovery-checklist.md as the discovery checklist.

2. Choose the preview surface

Prefer the smallest correct surface:

• Best: preview the ideas inside the real feature/page so spacing, layout, and surrounding context stay honest.
• Acceptable: add a preview route or internal page that still uses the app's real shell.
• Fallback: add an isolated sandbox page if the app architecture makes in-situ previewing expensive.

If you add a dedicated preview route, follow local router conventions and use a clearly temporary path such as /_ui/..., /internal/..., or the repo's existing preview pattern.

3. Build the variations

Create 3-5 variations that differ in meaningful ways, not just color or copy tweaks.

Only vary the requested surface. Do not add extra sections, side quests, marketing panels, helper callouts, or new feature ideas unless they are already part of the requested UI or the user explicitly asks for broader exploration.

Aim to vary things like:

• information hierarchy
• density and spacing
• framing and container treatment
• interaction emphasis and primary actions
• typographic rhythm
• navigation or control presentation

Keep the comparison fair:

• reuse the same content and data across all variations
• keep functional behavior as constant as possible
• share supporting data fixtures/helpers when that reduces duplication
• do not invent a new design system when the repo already has one
• do not put variation names, rationale text, or design commentary inside the UI itself
• make the UI feel shippable rather than like a design exercise

4. Build the switcher

The preview must include a floating switcher anchored at the bottom center of the screen.

The switcher is the only comparison control that should visibly describe the variants. Keep the previewed UI itself clean and presentation-ready.

Requirements:

• one active variation at a time
• clearly labeled variants such as A, B, C, D
• visible active state
• pointer-friendly controls
• mobile-safe placement
• use local app styling rather than foreign widget styling

Nice to have when cheap:

• previous/next controls
• keyboard shortcuts
• query param or route state so the active variation is easy to share or refresh

5. Keep the preview removable

Structure preview code so cleanup is straightforward after the user picks a winner.

Good patterns:

• keep preview-only components grouped in one local folder
• keep variant selection state local to the preview surface
• isolate temporary wrappers and comparison helpers from production code paths

Avoid building a permanent preview framework unless the repo already has one.

6. Verify

Run the lightest relevant checks available in the target repo.

• validate changed files with the repo's normal lint, typecheck, or test commands when practical
• run a focused dev/build check if the app supports it
• if a local app can run and agent-browser is available, use it to confirm the preview route renders and the switcher works
• verify desktop and mobile layout if the surface is responsive

7. Refine visually before handoff

If agent-browser is available, prefer one refinement pass before asking the user to choose.

• open the preview in the browser and inspect the rendered result rather than trusting code alone
• use visual inspection and available vision capabilities to catch awkward spacing, weak hierarchy, cramped mobile layouts, clipping, contrast issues, or component mismatches
• make targeted refinements so each variation looks polished and production-ready
• keep the refinements scoped to the requested surface rather than adding extra UI the user did not ask for

If agent-browser is not available, skip this step and hand off after normal code-level verification.

8. Hand off for review

When the preview is ready, report:

• preview route or entry point
• files changed
• the variant labels and one-line rationale for each
• any known compromises or gaps

Use templates/preview-summary-template.md as the output structure when useful.

Promotion Mode

When the user selects a winning variation, do not leave the repo in a "choose later" state. Finish the job.

1. Promote the winner

• move the winning variation into the real production surface
• preserve the chosen layout, hierarchy, and interaction details
• adapt naming so the final code reads like normal app code, not experiment code
• update imports, tests, stories, snapshots, and callers that depend on the old structure

2. Remove the temporary comparison layer

Delete or collapse preview-only artifacts that are no longer needed:

• preview routes or sandbox pages
• variant switcher UI
• losing variants
• temporary helpers, fixtures, and wrappers that only existed for comparison
• stale imports, dead styles, and orphaned assets

3. Verify the final integrated result

• run the relevant checks again
• if the app can run locally, verify the real surface rather than only the preview route
• confirm no preview-only controls remain visible in the integrated experience

4. Report completion

Summarize:

• which variation won
• where it was integrated
• which temporary artifacts were removed
• which checks were run

Use references/promotion-checklist.md as the final cleanup checklist.

Guardrails

• Favor the app's real primitives, spacing system, tokens, and layout patterns.
• Make the smallest change set that still yields meaningfully different ideas.
• Limit changes to the user-requested surface unless broader page changes were explicitly requested.
• Do not overwrite unrelated work or refactor broadly just to host the preview.
• Keep each variation honest to the product's existing brand and interaction model unless the user explicitly asks for something more radical.
• Do not embed design explanations, variant descriptions, or self-referential experiment text inside the UI.
• Make the preview look production-ready enough that the chosen variation can be promoted with minimal cleanup.
• If visual browser inspection is available, use it to polish the variants before requesting user feedback.
• Do not stop at mockups once the user has chosen a direction. Integrate the winner and clean up the rest.
• Prefer code that is easy to delete or fold into production cleanly.

References

Reference	Purpose
references/discovery-checklist.md	What to inspect before editing
references/promotion-checklist.md	What to remove and verify after a winner is chosen

Templates

Template	Purpose
templates/preview-summary-template.md	Concise handoff summary for the preview phase