Appkit UI Variants

UI — Build in Variants, Pick Live, Finalize

User input: $ARGUMENTS

Build the requested UI in several variants wrapped in the <Variants> picker, let the developer choose one live in the browser, and then finalize the chosen variant into source (removing the wrapper).

The picker lets a developer choose between several candidate UIs live in the browser during local dev; you then finalize the chosen one into source.

These rules govern your behavior, not your narration. Apply every rule silently. To the developer, speak only about what you're building and what they need to do — never about the mechanism (the choices file, how a choice is stored, "I read it next turn", or whether you decided to ask).

The pieces

• <Variants> / <Variant> — @databricks/appkit-ui/react. A dev-time wrapper that renders one candidate at a time with a hover-revealed switcher (prev/next, an index pill + label) and a Confirm tick.
• The recorder — built into @databricks/appkit. Records the confirmed choice: Confirm POSTs { blockId, chosenIndex, label } to POST /api/ui-variants/confirm, upserted into a JSONL file keyed by blockId. It runs automatically in dev and drops out of production on its own — there's nothing to set up.
• Choices file — node_modules/.databricks/appkit/.appkit-ui-choices.jsonl, gitignored. A keyed store: one line per <Variants> blockId (not an append log) — re-confirming a variant replaces that block's line, so the file always reflects the current choice: { "ts": "...", "blockId": "hero-cta", "chosenIndex": 1, "label": "Solid" }. Its path is relative to the dev server's cwd, not the repo root, so discover it (finalize step 4) rather than assuming a fixed location.

1. Understand the request

Work out what to build (a component, a section, a page) and where it lives, then pick the natural target file (e.g. a *.route.tsx or a component under src/components/…), and decide the block breakdown before authoring. Two rules shape this step:

• Ask for what and where; build for how it looks. Before generating, ask at most one or two questions only if the answer changes the build — ambiguous target/surface, an unclear axis of variation, or real-vs-placeholder data on a data screen. Do not ask appearance/taste questions ("bold or minimal?", "which color?"); make one bold and one minimal instead. If the request is clear enough, skip questions. Never turn it into a checklist.
• One <Variants> block = one independent decision — default to one block per distinct section the user names (a hero + about page → two blocks), and default 3 meaningfully different variants per block.

2. Author the variants

Wrap each section's candidates in its own <Variants> block, following the authoring rules below. Note the file path + every blockId — you need them to finalize.

• MUST treat one <Variants> block as one independent decision and default to one block per distinct section/region the user names. A page with a hero and an about-us section is two blocks (blockId="hero", blockId="about"), so the developer chooses each section independently. Use a single whole-page block only when the user asks for whole-page options or the sections must move together as one unit.
• MUST give every <Variants> block a stable, unique blockId within its file. Duplicate ids are ambiguous — refuse and disambiguate.
• MUST wrap each candidate in <Variant label="…"> with a short, distinct label. The label is shown in the switcher and recorded on confirm.
• SHOULD default to 3 variants unless the user asks for a specific count. Make them meaningfully different (layout / emphasis / density).
• Keep each variant self-contained: imports it needs should already be present so finalizing to any one of them leaves the file valid.
• Layout: <Variants> defaults to block layout (full-width, stacking) — correct for sections, heroes, and pages. Pass layout="inline" only when wrapping a small inline element such as a single button.

One block per section, each candidate a labelled <Variant>:

import { Variants, Variant } from "@databricks/appkit-ui/react";

// "page with a hero and an about-us section" → one block per section
<Variants blockId="hero">
  <Variant label="Centered">…hero A…</Variant>
  <Variant label="Split with stats">…hero B…</Variant>
  <Variant label="Minimal">…hero C…</Variant>
</Variants>

<Variants blockId="about">
  <Variant label="Two column">…about A…</Variant>
  <Variant label="Timeline">…about B…</Variant>
  <Variant label="Team grid">…about C…</Variant>
</Variants>

3. Ensure the recorder is running

• The recorder runs automatically in dev — no setup needed.
• Confirm the dev server is running so the browser can POST the choice.

4. Hand off to the developer

Tell the developer to make the choice in the browser:

Flip through the variants in the browser (hover the block to reveal the switcher) and click Confirm on the one you want.

Then get the "I've chosen" signal — the developer's next message.

The signal is turn-based. Do not start a background watcher. The confirm is recorded to the file; read it on your next turn. How to prompt for it:

• If your tool has an interactive question prompt and the developer is in an active session, you MAY ask via that prompt — options like "I've picked — finalize" / "Still deciding" / "Cancel" — to save them typing.
• Otherwise, ask in plain text and read the file on a later turn.

Two hard rules: the question must carry a "still deciding / later" option so it never blocks the developer; and only ask when someone is there to answer — if unsure, use plain text. If the developer says "done" but no line exists for the block yet, they haven't clicked Confirm — ask them to, don't finalize nothing.