Add OpenCode skills

ui-variations/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: ui-variations
+description: 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.
+compatibility: 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 |

ui-variations/references/discovery-checklist.md

@@ -0,0 +1,43 @@
+# Discovery Checklist
+
+Inspect only the files needed to answer these questions before editing.
+
+Before expanding scope, identify exactly which page, component, or feature surface the user asked to vary. Keep the rest of the experience stable unless the user explicitly asks for broader page redesign.
+
+## Product And Design Intent
+
+- Is there a stated design philosophy in `README*`, `docs/**`, `CONTRIBUTING*`, or nearby design docs?
+- Does the repo describe brand tone, density preferences, or component usage rules?
+- Are there obvious examples of the same kind of surface elsewhere in the app?
+
+## App Structure
+
+- Which router is in use?
+- Where do page/layout entry points live?
+- Is there an existing internal-only preview, lab, or story route?
+- What is the smallest safe place to add a preview without disturbing production paths?
+
+## Styling System
+
+- Are styles driven by Tailwind, CSS modules, CSS-in-JS, plain CSS, or a component library?
+- Where do colors, spacing, radius, shadows, typography, and breakpoints come from?
+- Are there theme tokens or CSS variables that must be reused?
+
+## Component Primitives
+
+- What shared components should be reused for buttons, cards, inputs, dialogs, tabs, and layout?
+- Are there common container or page-shell components that the preview should preserve?
+- Do components carry motion, focus, or accessibility conventions that must remain intact?
+
+## Data And Content
+
+- Can the preview reuse live data flow safely?
+- If not, what is the smallest local fixture needed for a fair comparison?
+- How can content stay constant across variations so the user compares layout and interaction rather than copy changes?
+- What existing content is already part of the requested surface, and what extra fluff should be avoided because the user did not ask for it?
+
+## Validation
+
+- What are the lightest relevant commands for lint, typecheck, test, or build?
+- Can the app run locally for a browser check?
+- If it can run, what route should be opened to validate the preview?

ui-variations/references/promotion-checklist.md

@@ -0,0 +1,31 @@
+# Promotion Checklist
+
+Use this checklist after the user selects a winning variation.
+
+## Promote The Winner
+
+- Move the chosen variation into the real production path or component.
+- Rename experiment-oriented files and symbols so the final code reads normally.
+- Update call sites, imports, tests, stories, snapshots, and docs that depend on the old surface.
+
+## Remove Comparison Artifacts
+
+- Delete the preview route or preview-only page if it no longer serves a purpose.
+- Remove the floating variant switcher.
+- Delete losing variations.
+- Remove preview-only helpers, fixtures, state, comments, and wrappers.
+- Remove orphaned styles and unused assets.
+
+## Re-Verify
+
+- Re-run the relevant lint, typecheck, test, or build commands.
+- Verify the real integrated page, not just the preview surface.
+- Confirm mobile and desktop still behave correctly when relevant.
+- Confirm no preview controls or experiment labels remain.
+
+## Report
+
+- State which variation won.
+- State where it was integrated.
+- State what temporary files or routes were removed.
+- State which checks were run and whether anything remains unresolved.

ui-variations/templates/preview-summary-template.md

@@ -0,0 +1,30 @@
+# UI Variation Preview
+
+## Target
+
+- Surface:
+- Preview entry point:
+
+## Variants
+
+- A:
+- B:
+- C:
+- D:
+- E:
+
+Remove unused lines if fewer than 5 variants were created.
+
+## Files Changed
+
+-
+
+## Notes
+
+- Shared data/content kept constant across variants:
+- Switcher behavior:
+- Known compromises or follow-up items:
+
+## Next Step
+
+- Waiting for user to choose a winning variation for promotion and cleanup.