variantkit 0.1.0 → 0.3.0

package/AGENT.md

@@ -10,7 +10,7 @@ do two things: **scaffold** variant sets when asked for "options/variants/takes"
 Pruning must be reliable. It is mostly file deletion plus one file rename. Never move JSX
 between files by hand. Follow this exactly.
 
-**Vocabulary:** element, variant, control, configuration, snapshot, finalize, decision, prune
+**Vocabulary:** element, variant, control, configuration, finalize, decision, prune
 — one word per concept, defined in `NAMING.md`. Use them consistently.
 
 ---
@@ -19,9 +19,10 @@ between files by hand. Follow this exactly.
 
 **Default to divergence.** When the developer asks you to build or change any user-facing
 UI — a component, screen, section, state, layout, or visual treatment — do NOT commit to a
-single interpretation. Scaffold a **variant set** of 2–4 structural takes (§1) and let the
-developer choose live in the panel, then finalize. Generating N is the point; one is the
-exception.
+single interpretation. Scaffold a **variant set** of **2-3 structural takes** (§1) — a 4th
+only when the directions genuinely diverge, since each take is more generation the developer
+waits on — and let them choose live in the panel, then finalize. Generating N is the point;
+one is the exception.
 
 Offer variants especially when:
 - the request is aesthetic or open-ended ("a pricing card", "make this nicer", "a hero")
@@ -199,27 +200,19 @@ and a live grid of all variants when Compare is on (clicking a cell selects it):
 return <VariantStage name="PricingCard" registry={registry} active={String(v.variant)} props={variantProps} />
 ```
 
-### Hide the redundant copy button
+### Hide DialKit's top toolbar
 
 Import these three stylesheets once (the `Studio` helper assumes them):
-- `variantkit/dialkit-clean.css` — hides the redundant "Copy parameters" button and the
-  folder/header dividers (panel reads on spacing, like DialKit's own UI). **Keeps the preset
-  toolbar** — that's the snapshot mechanism (below).
+- `variantkit/dialkit-clean.css` — hides DialKit's entire top toolbar row (the preset/"Version"
+  manager + the "Copy parameters" button) and the folder/header dividers (panel reads on
+  spacing, like DialKit's own UI). VariantKit has no snapshots concept: the variant selector is
+  the first thing in the panel — pick a variant, tweak it, Finalize.
 - `variantkit/dialkit-dark.css` — the dark palette DialKit lacks. Call `useDialkitTheme()`
   (from `variantkit/react`) once: it applies the theme, persists it, and injects a sun/moon
   toggle into the panel header so the user flips the panel's light/dark right there.
 - `variantkit/motion.css` — press feedback, theme-switch cross-fade, reduced-motion. Scoped
   strictly to the panel chrome; it never styles or animates the project's UI.
 
-### Snapshots — keep two tunings and compare
-
-A **Snapshot** = a saved (variant + control values) state, so you can keep two tunings of one
-element (Slab/12/green vs Inverse/4/amber) and pick one. This is DialKit's **preset toolbar**
-(the ≡+ "add" and the Version dropdown), reused: because the variant is itself a control, a
-preset captures variant+values, and DialKit restores them atomically on switch. Finalize acts
-on the **active** snapshot. So: tune → ≡+ to snapshot → tune differently → switch between them
-→ Finalize the winner. (We hide only the redundant Copy button, not the preset toolbar.)
-
 ## 3. `decision.json` schema (schema 2)
 
 Finalize writes one decision per component. Values are **dot-path flattened** — folder
@@ -337,15 +330,28 @@ tabs are an intentional, system-wide tool chrome, not slop.
 ## 7. Full configuration, not three sliders — the completeness bar
 
 The §0 rules stand: controls come from the element, defaults come from the code. This
-section adds the other half: **a panel with 2-3 loose sliders is a failure.** During
-exploration the panel must feel like the element's actual configuration panel — covering
-every design decision the element really has, grouped the way a real settings panel would
-group them.
-
-**Paramify rule.** Every design literal a variant renders — px sizes, radii, colors, font
-sizes, weights, spacing, shadows, durations — becomes a control, fed through props from the
-shell. No hardcoded design value stays outside the panel during exploration, except a
-variant's structural identity (below).
+section adds the other half: for a rich element, **a panel with 2-3 loose sliders is a
+failure.** During exploration the panel must feel like the element's actual configuration
+panel — covering every design decision the element really has, grouped the way a real
+settings panel would group them.
+
+But **scale the panel to the element.** Every control and every variant is generation the
+developer waits on — over-building a button into 20 controls is what makes VariantKit feel
+slow for no payoff. Match the work to the ask (see the minimum bar below).
+
+**Paramify rule — expose the decisions, not every number.** A control earns its place only
+if a developer would plausibly reach for it while exploring THIS element. Run that test over
+every design literal a variant renders — px sizes, radii, colors, font sizes, weights,
+spacing, shadows, durations: if it's a real, tweakable design decision, it becomes a control
+fed from the shell; if it's a fixed structural constant, a value the layout simply dictates,
+or something nobody would touch, leave it inline. The bar is *"would they turn this dial?"*,
+not *"is there a number here?"*. No **meaningful** design value stays outside the panel — and
+no useless one clutters it. (A variant's structural identity always stays inline — see below.)
+
+Curating is the job, not a shortcut. A panel of 8 controls that all matter beats one of 20
+where half are noise — the developer scans every row, so each junk control is a small tax.
+When a control feels borderline, drop it (or collapse it into a secondary folder); the
+developer can always ask for more.
 
 **Archetype checklists.** `variantkit/schemas/archetypes.ts` ships per-element-family
 checklists of design axes:
@@ -367,8 +373,15 @@ They are **checklists to adapt, not sets to paste** (§2 authoring rules apply u
   `[def,min,max,step?]`, boolean, text, color (hex), select, spring, easing, action, nested
   folders (`_collapsed: true`).
 
-**Minimum bar.** Non-trivial element ⇒ ≥4 folders, 12-25 controls. Trivial element (icon,
-divider, single label) ⇒ a flat 3-5 control panel is fine. Collapse secondary folders.
+**Proportional bar** — size the panel to the element, smallest sufficient first:
+- **Trivial** (icon, divider, single label, tag) ⇒ a flat 3-5 control panel.
+- **Small** (button, badge, single input, chip) ⇒ the ~3-8 controls that genuinely matter; one
+  or two folders at most. Resist padding it out.
+- **Rich** (hero, pricing card, navbar, modal, form, table) ⇒ the full set: ≥4 folders,
+  ~12-25 controls, secondary folders collapsed.
+
+When unsure between two tiers, build the smaller one — an under-built panel is a quick add;
+an over-built one already cost the developer the wait.
 
 **Identity exception.** A control must be honest. If a value IS the variant's structural
 identity (the dark variant's background, the outlined variant's transparent surface), do

package/NAMING.md

@@ -8,12 +8,11 @@ term here conflicts with how you named something, this file wins — rename the
 | Term | Means | Not to be called |
 |------|-------|------------------|
 | **Element** | The UI thing being designed: a pricing card, a button, a hero. The subject of a session. | "component" (too generic), "widget" |
-| **Variant** | One structural take on an element — different code/layout, same role (Slab vs Ledger vs Inverse). The agent generates several. | "version" (means snapshot), "option" (fine in plain English, but the type is `variant`) |
+| **Variant** | One structural take on an element — different code/layout, same role (Slab vs Ledger vs Inverse). The agent generates several. | "version", "option" (fine in plain English, but the type is `variant`) |
 | **Control** | One tunable setting of an element (radius, accent, padding). | "param" (ok internally), "knob" |
-| **Configuration** | The full set of controls exposed for an element — the settings panel for it. Authored per element by the agent, contextual; there is no predefined menu. | "config object" (that's the DialKit wiring, see below), "preset" (that word is reserved for DialKit's snapshot toolbar) |
+| **Configuration** | The full set of controls exposed for an element — the settings panel for it. Authored per element by the agent, contextual; there is no predefined menu. | "config object" (that's the DialKit wiring, see below), "preset" |
 | **Defaults** | The frozen reference values a variant ships with. The override diff is measured against these. | "initial" |
 | **Override** | A control whose value differs from its default — the "taste signal". The set of them = the **override diff**. | "change", "delta" |
-| **Snapshot** | A saved (variant + control values) state kept so you can compare two tunings of the same element. Implemented via DialKit's preset toolbar (≡+ / Version dropdown), reused. | — |
 | **Finalize** | Committing the chosen variant + its current values. Produces a decision. | "save", "submit" |
 | **Decision** | The machine-readable result of finalize: `{ component, finalized, values, overridesFromDefault, prune, … }`. The handoff to the agent. | "result", "output" |
 | **Prune** | The agent deleting the losing variants down to the clean winner. | "cleanup", "resolve" |
@@ -37,6 +36,5 @@ term here conflicts with how you named something, this file wins — rename the
 ## One sentence, all of it
 
 > The agent scaffolds a **set** of **variants** for an **element**; you tune each variant's
-> **controls** (its **configuration**) in the **panel**, optionally keeping **snapshots** to
-> compare; you **finalize** the winner, which writes a **decision**; the agent **prunes** the
-> losers to a clean component.
+> **controls** (its **configuration**) in the **panel**; you **finalize** the winner, which
+> writes a **decision**; the agent **prunes** the losers to a clean component.

package/README.md

@@ -67,8 +67,6 @@ Flags: `--dry-run` `--skip-install` `--no-mount` `--no-skill` (init) · `--keep-
 
 - **Studio** — exploring several elements at once? One panel, a folder per element, each
   with its own controls and Finalize; hovering an element focuses its folder.
-- **Snapshots** — keep two tunings of the same element (DialKit's preset toolbar) and
-  switch between them; Finalize acts on the active one.
 - **Panel polish** — dark mode with a header toggle, a delightful minimize/expand morph
   (shipped as a patch-package patch), micro-motion. All panel-side: nothing is ever drawn
   over your UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "variantkit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The configuration panel for AI-built UI: your agent generates variants with a full contextual control panel, you tweak and finalize, the losers get pruned from the codebase. Built on DialKit.",
   "type": "module",
   "bin": {

package/variantkit/configs.ts

@@ -38,8 +38,11 @@ export function panelConfig(
   opts?: { finalizeLabel?: string; component?: string },
 ): PanelConfig {
   return {
+    // `segmented: true` makes DialKit render the variant as clean separated selection pills
+    // (one per take) instead of a dropdown — the variant is the panel's hero choice, so it
+    // shows every option at a glance. Pills wrap when names are long / the panel is narrow.
     ...(variantKeys.length > 1
-      ? { variant: { type: 'select', options: variantKeys, default: variantKeys[0] } }
+      ? { variant: { type: 'select', options: variantKeys, default: variantKeys[0], segmented: true } }
       : {}),
     ...controls,
     finalize: { type: 'action', label: opts?.finalizeLabel ?? `Finalize ${opts?.component ?? ''}`.trim() },
@@ -68,3 +71,29 @@ export function defaultsOf(cfg: PanelConfig): Record<string, number | string | b
 export function regOf(variantKeys: string[]): Record<string, true> {
   return Object.fromEntries(variantKeys.map((k) => [k, true]))
 }
+
+// Flatten a (possibly nested) config into the path→default map DialKit addresses values by:
+// dot-joined raw keys (`headingSize`, `Pricing Card.accent`). Used by the header Reset button
+// to push every control — INCLUDING the variant — back to where it started. Folders are plain
+// objects without a `type`; `_`-prefixed keys (e.g. `_collapsed`) and actions are skipped.
+export function flatDefaults(cfg: PanelConfig, prefix = ''): Record<string, number | string | boolean> {
+  const out: Record<string, number | string | boolean> = {}
+  for (const [key, c] of Object.entries(cfg)) {
+    if (key.startsWith('_') || c == null) continue
+    const path = prefix ? `${prefix}.${key}` : key
+    if (typeof c === 'number' || typeof c === 'string' || typeof c === 'boolean') {
+      out[path] = c
+    } else if (Array.isArray(c)) {
+      out[path] = c[0] as number
+    } else if (typeof c === 'object') {
+      const o = c as { type?: string; default?: unknown }
+      if (o.type === 'action') continue
+      if (o.type) {
+        if (o.default !== undefined) out[path] = o.default as number | string | boolean
+      } else {
+        Object.assign(out, flatDefaults(c as PanelConfig, path)) // nested folder of controls
+      }
+    }
+  }
+  return out
+}

package/variantkit/dialkit-clean.css

@@ -1,9 +1,10 @@
 /* VariantKit panel cleanup for DialKit.
-   - Hide only the "Copy parameters" clipboard button (redundant with Finalize). The preset
-     toolbar STAYS — it's VariantKit's snapshot mechanism (save a tuned variant, switch, then
-     finalize the active one). See AGENT.md "Snapshots".
+   - Hide DialKit's entire top toolbar row (the preset/"Version" manager + the "Copy
+     parameters" button). VariantKit has no snapshots concept: you pick a variant, tweak it,
+     and Finalize. The preset toolbar only confused people ("what is Version 1, why first?"),
+     so the whole row goes — leaving the variant selector as the first thing in the panel.
    - Remove folder/header dividers so the panel reads on spacing alone, like DialKit's own UI. */
-.dialkit-root [title='Copy parameters'] {
+.dialkit-root .dialkit-panel-toolbar {
   display: none !important;
 }
 
@@ -12,20 +13,199 @@
    bubble sets its own uniform 12px, so this only affects the open panel. */
 .dialkit-root .dialkit-panel-inner:not([data-collapsed='true']) {
   padding-bottom: 12px;
+  /* DialKit sets an inline pixel `height` from its own content measurement — but it under-measures
+     by ~14px (our bottom padding + the wrapped variant pills aren't counted), so the last control
+     (Finalize) gets clipped on EVERY window size, not just short ones. Force `height: auto` so the
+     panel hugs its real content, then cap to the viewport and scroll if a short window demands it.
+     Scoped to the expanded panel so DialKit's collapse animation (which drives `data-collapsed`)
+     is left untouched. */
+  height: auto !important;
+  max-height: calc(100vh - 28px);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: var(--dial-surface-hover) transparent;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true'])::-webkit-scrollbar {
+  width: 8px;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true'])::-webkit-scrollbar-thumb {
+  background: var(--dial-surface-hover);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
 }
 .dialkit-root .dialkit-panel-header {
-  border-bottom: none !important;
+  /* A quiet divider + breathing room separates the header (title + chrome) from the controls,
+     so the panel reads as "identity up top, then the body". */
+  border-bottom: 1px solid var(--dial-border) !important;
+  padding-bottom: 12px !important;
+  margin-bottom: 12px !important;
+}
+.dialkit-root .dialkit-panel-header .dialkit-folder-header-top {
+  padding-bottom: 0 !important;
 }
 .dialkit-root .dialkit-folder {
   border-top: none !important;
   border-bottom: none !important;
 }
 
-/* The injected panel theme toggle — placed just left of DialKit's settings icon (right:12). */
+/* ── Variant selector: clean separated selection pills ───────────────────────────────────
+   DialKit renders the `variant` control (segmented:true) as a row of separated pills, one
+   per take, instead of a dropdown. The variant is the panel's hero choice, so every option
+   stays visible. Pills wrap to new lines when labels are long or the panel is narrow — they
+   never overflow or clip the row. */
+.dialkit-root .dialkit-vk-pills {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+  align-items: stretch;
+}
+.dialkit-root .dialkit-vk-pills .dialkit-select-label {
+  /* Drop the "Variant" caption — the segmented pills are the first thing under the title and are
+     self-evidently the take selector. A lone label above them just read as an orphaned control
+     row. The panel now opens straight into the pills, like a tab bar. */
+  display: none;
+}
+.dialkit-root .dialkit-vk-pills-track {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+}
+.dialkit-root .dialkit-vk-pill {
+  /* DialKit absolutely-positions panel buttons; pills must opt back into normal flow so the
+     track lays them out in a wrapping row. Inactive pills are quiet (faint surface, no border)
+     so the selected one carries all the emphasis. */
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 60px;
+  max-width: 100%;
+  padding: 7px 11px;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  background: var(--dial-surface-subtle);
+  color: var(--dial-text-secondary);
+  font: 500 12px/1.15 system-ui, -apple-system, 'Segoe UI', sans-serif;
+  letter-spacing: 0.01em;
+  text-align: center;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  cursor: pointer;
+  -webkit-font-smoothing: antialiased;
+  transition:
+    background-color 180ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 180ms cubic-bezier(0.23, 1, 0.32, 1),
+    box-shadow 180ms cubic-bezier(0.23, 1, 0.32, 1),
+    transform 120ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+.dialkit-root .dialkit-vk-pill:hover {
+  background: var(--dial-surface-hover);
+  color: var(--dial-text-primary);
+}
+.dialkit-root .dialkit-vk-pill:active {
+  transform: scale(0.96);
+}
+.dialkit-root .dialkit-vk-pill[data-active='true'] {
+  /* Solid fill + a small lift = unmistakable selection. `--dial-glass-bg` is the solid panel
+     colour (dark in dark mode, light in light mode), so the label always contrasts the fill. */
+  background: var(--dial-text-primary);
+  color: var(--dial-glass-bg);
+  font-weight: 600;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.16), 0 3px 10px rgba(0, 0, 0, 0.13);
+}
+.dialkit-root .dialkit-vk-pill[data-active='true']:hover {
+  color: var(--dial-glass-bg);
+}
+
+/* ── Panel icon: collapse glyph (expanded) + brand mark (collapsed) ───────────────────────
+   DialKit's `.dialkit-panel-icon` sits top-right; clicking it (via the header's toggle) collapses
+   the panel. We paint it with a CSS mask in `currentColor` (themes itself, survives React
+   re-renders): a contract/minimize glyph while EXPANDED — that's its real job, the panel's
+   collapse affordance — and VariantKit's brand mark on the COLLAPSED bubble, where the panel
+   needs a face (two rounded cards, one solid, echoing the variant pills). */
+.dialkit-root .dialkit-panel-icon > * {
+  display: none; /* hide DialKit's own dial paths */
+}
+.dialkit-root .dialkit-panel-icon {
+  background-color: currentColor;
+  cursor: pointer;
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-position: center;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true']) .dialkit-panel-icon {
+  -webkit-mask-image: var(--vk-collapse-mark);
+  mask-image: var(--vk-collapse-mark);
+}
+.dialkit-root .dialkit-panel-inner[data-collapsed='true'] .dialkit-panel-icon {
+  -webkit-mask-image: var(--vk-brand-mark);
+  mask-image: var(--vk-brand-mark);
+}
+.dialkit-root {
+  --vk-brand-mark: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%3E%3Crect%20x='2.2'%20y='4.4'%20width='5.2'%20height='7.2'%20rx='1.7'%20fill='black'/%3E%3Crect%20x='8.6'%20y='4.4'%20width='5.2'%20height='7.2'%20rx='1.7'%20fill='none'%20stroke='black'%20stroke-width='1.3'%20opacity='.5'/%3E%3C/svg%3E");
+  --vk-collapse-mark: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2016%2016'%3E%3Cpath%20d='M12.8%203.2%20L9%207%20M9%204.7%20L9%207%20L11.3%207'%20fill='none'%20stroke='black'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3Cpath%20d='M3.2%2012.8%20L7%209%20M7%2011.3%20L7%209%20L4.7%209'%20fill='none'%20stroke='black'%20stroke-width='1.5'%20stroke-linecap='round'%20stroke-linejoin='round'/%3E%3C/svg%3E");
+}
+
+/* ── Element actions: Shuffle + Reset, beside the element name ────────────────────────────
+   Two quiet icon buttons sit right after the title, in the same row — they act on the ELEMENT,
+   so they read as the element's own controls. Panel chrome (theme + collapse) stays on the far
+   right; the title row reserves space for it so the two groups never collide. */
+.dialkit-root .dialkit-panel-header .dialkit-folder-title-row {
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  padding-right: 76px; /* clear the theme toggle (right 40) + collapse icon (right 12) */
+}
+.dialkit-root .dialkit-panel-header .dialkit-folder-title-row .dialkit-folder-title {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dialkit-root .vk-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 1px;
+  margin-left: 4px;
+  flex: 0 0 auto;
+}
+.dialkit-root .vk-action-btn {
+  width: 24px;
+  height: 24px;
+  display: inline-grid;
+  place-items: center;
+  border: none;
+  background: transparent;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--dial-text-secondary);
+  transition:
+    background-color 140ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 140ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+.dialkit-root .vk-action-btn:hover {
+  background: var(--dial-surface-hover);
+  color: var(--dial-text-primary);
+}
+.dialkit-root .vk-action-btn:active {
+  transform: scale(0.9);
+}
+.dialkit-root .vk-action-btn svg {
+  display: block;
+}
+
+/* ── Header chrome: theme toggle ─────────────────────────────────────────────────────────
+   Panel chrome on the right — the theme toggle, just left of the collapse/brand icon. */
 .dialkit-root .vk-theme-toggle {
   position: absolute;
   top: 6px;
-  right: 40px;
+  right: 40px; /* just left of the collapse icon (DialKit's panel-icon at right ~12) */
+  z-index: 2;
   width: 26px;
   height: 26px;
   display: inline-grid;
@@ -35,11 +215,13 @@
   border-radius: 7px;
   cursor: pointer;
   color: var(--dial-text-secondary);
-  z-index: 2;
-  transition: background-color 140ms cubic-bezier(0.23, 1, 0.32, 1);
+  transition:
+    background-color 140ms cubic-bezier(0.23, 1, 0.32, 1),
+    color 140ms cubic-bezier(0.23, 1, 0.32, 1);
 }
 .dialkit-root .vk-theme-toggle:hover {
   background: var(--dial-surface-hover);
+  color: var(--dial-text-primary);
 }
 .dialkit-root .vk-theme-toggle:active {
   transform: scale(0.92);

package/variantkit/motion.css

@@ -60,6 +60,35 @@
   }
 }
 
+/* ── Header actions feedback ─────────────────────────────────────────────────────────────
+   Reset spins its arrow once counter-clockwise; Shuffle gives its icon a quick tumble. Both
+   are keyed off a data attribute the JS sets for ~480ms, so each click animates fresh. */
+.dialkit-root .vk-reset[data-spinning] svg {
+  animation: vk-reset-spin 480ms var(--vk-ease-out);
+}
+@keyframes vk-reset-spin {
+  from {
+    transform: rotate(0);
+  }
+  to {
+    transform: rotate(-360deg);
+  }
+}
+.dialkit-root .vk-shuffle[data-shuffling] svg {
+  animation: vk-shuffle-tumble 420ms var(--vk-ease-out);
+}
+@keyframes vk-shuffle-tumble {
+  0% {
+    transform: rotate(0) scale(1);
+  }
+  45% {
+    transform: rotate(16deg) scale(0.86);
+  }
+  100% {
+    transform: rotate(0) scale(1);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .dialkit-root.vk-theming,
   .dialkit-root.vk-theming * {
@@ -68,6 +97,10 @@
   .vk-theme-toggle .vk-swap {
     animation: none;
   }
+  .dialkit-root .vk-reset[data-spinning] svg,
+  .dialkit-root .vk-shuffle[data-shuffling] svg {
+    animation: none;
+  }
   .dialkit-root button:active {
     transform: none;
   }

package/variantkit/patches/dialkit+1.2.0.patch

@@ -1,7 +1,16 @@
 diff --git a/node_modules/dialkit/dist/index.cjs b/node_modules/dialkit/dist/index.cjs
-index d9f4837..4bf4e6d 100644
+index d9f4837..ce0432f 100644
 --- a/node_modules/dialkit/dist/index.cjs
 +++ b/node_modules/dialkit/dist/index.cjs
+@@ -337,7 +337,7 @@ var DialStoreClass = class {
+       } else if (this.isActionConfig(value)) {
+         controls.push({ type: "action", path, label: value.label || label });
+       } else if (this.isSelectConfig(value)) {
+-        controls.push({ type: "select", path, label, options: value.options });
++        controls.push({ type: "select", path, label, options: value.options, segmented: value.segmented });
+       } else if (this.isColorConfig(value)) {
+         controls.push({ type: "color", path, label });
+       } else if (this.isTextConfig(value)) {
 @@ -1006,8 +1006,9 @@ function Folder({ title, children, defaultOpen = true, isRoot = false, inline =
          style: panelStyle,
          onClick: !isOpen ? handleToggle : void 0,
@@ -14,10 +23,68 @@ index d9f4837..4bf4e6d 100644
          children: folderContent
        }
      );
+@@ -1034,6 +1035,7 @@ function Slider({
+   shortcut,
+   shortcutActive
+ }) {
++  if (typeof value !== "number") value = typeof min === "number" ? min : 0;
+   const wrapperRef = (0, import_react5.useRef)(null);
+   const trackRef = (0, import_react5.useRef)(null);
+   const inputRef = (0, import_react5.useRef)(null);
+@@ -1825,6 +1827,7 @@ function EaseTextInput({ ease, onChange }) {
+ // src/components/TextControl.tsx
+ var import_jsx_runtime10 = require("react/jsx-runtime");
+ function TextControl({ label, value, onChange, placeholder }) {
++  if (typeof value !== "string") value = "";
+   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { className: "dialkit-text-control", children: [
+     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("label", { className: "dialkit-text-label", children: label }),
+     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+@@ -1853,6 +1856,15 @@ function normalizeOptions(options) {
+     (opt) => typeof opt === "string" ? { value: opt, label: toTitleCase(opt) } : opt
+   );
+ }
++function VKSegmented({ label, value, options, onChange }) {
++  const normalized = normalizeOptions(options);
++  return (0, import_jsx_runtime11.jsxs)("div", { className: "dialkit-vk-pills", children: [
++    (0, import_jsx_runtime11.jsx)("span", { className: "dialkit-select-label", children: label }),
++    (0, import_jsx_runtime11.jsxs)("div", { className: "dialkit-vk-pills-track", children: normalized.map(function(o) {
++      return (0, import_jsx_runtime11.jsx)("button", { type: "button", className: "dialkit-vk-pill", "data-active": o.value === value ? "true" : "false", title: o.label, onClick: function() { return onChange(o.value); }, children: o.label }, o.value);
++    }) })
++  ] });
++}
+ function SelectControl({ label, value, options, onChange }) {
+   const [isOpen, setIsOpen] = (0, import_react10.useState)(false);
+   const triggerRef = (0, import_react10.useRef)(null);
+@@ -1966,6 +1978,7 @@ var import_react12 = require("react");
+ var import_jsx_runtime12 = require("react/jsx-runtime");
+ var HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+ function ColorControl({ label, value, onChange }) {
++  if (typeof value !== "string") value = "#000000";
+   const [isEditing, setIsEditing] = (0, import_react12.useState)(false);
+   const [editValue, setEditValue] = (0, import_react12.useState)(value);
+   const colorInputRef = (0, import_react12.useRef)(null);
+@@ -2266,7 +2279,7 @@ Apply these values as the new defaults in the useDialKit call.`;
+         );
+       case "select":
+         return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+-          SelectControl,
++          (control.segmented ? VKSegmented : SelectControl),
+           {
+             label: control.label,
+             value,
 diff --git a/node_modules/dialkit/dist/index.js b/node_modules/dialkit/dist/index.js
-index f8d8baf..7a0e7b3 100644
+index f8d8baf..47a7e4d 100644
 --- a/node_modules/dialkit/dist/index.js
 +++ b/node_modules/dialkit/dist/index.js
+@@ -297,7 +297,7 @@ var DialStoreClass = class {
+       } else if (this.isActionConfig(value)) {
+         controls.push({ type: "action", path, label: value.label || label });
+       } else if (this.isSelectConfig(value)) {
+-        controls.push({ type: "select", path, label, options: value.options });
++        controls.push({ type: "select", path, label, options: value.options, segmented: value.segmented });
+       } else if (this.isColorConfig(value)) {
+         controls.push({ type: "color", path, label });
+       } else if (this.isTextConfig(value)) {
 @@ -966,8 +966,9 @@ function Folder({ title, children, defaultOpen = true, isRoot = false, inline =
          style: panelStyle,
          onClick: !isOpen ? handleToggle : void 0,
@@ -30,3 +97,52 @@ index f8d8baf..7a0e7b3 100644
          children: folderContent
        }
      );
+@@ -994,6 +995,7 @@ function Slider({
+   shortcut,
+   shortcutActive
+ }) {
++  if (typeof value !== "number") value = typeof min === "number" ? min : 0;
+   const wrapperRef = useRef4(null);
+   const trackRef = useRef4(null);
+   const inputRef = useRef4(null);
+@@ -1785,6 +1787,7 @@ function EaseTextInput({ ease, onChange }) {
+ // src/components/TextControl.tsx
+ import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
+ function TextControl({ label, value, onChange, placeholder }) {
++  if (typeof value !== "string") value = "";
+   return /* @__PURE__ */ jsxs9("div", { className: "dialkit-text-control", children: [
+     /* @__PURE__ */ jsx10("label", { className: "dialkit-text-label", children: label }),
+     /* @__PURE__ */ jsx10(
+@@ -1813,6 +1816,15 @@ function normalizeOptions(options) {
+     (opt) => typeof opt === "string" ? { value: opt, label: toTitleCase(opt) } : opt
+   );
+ }
++function VKSegmented({ label, value, options, onChange }) {
++  const normalized = normalizeOptions(options);
++  return jsxs10("div", { className: "dialkit-vk-pills", children: [
++    jsx11("span", { className: "dialkit-select-label", children: label }),
++    jsxs10("div", { className: "dialkit-vk-pills-track", children: normalized.map(function(o) {
++      return jsx11("button", { type: "button", className: "dialkit-vk-pill", "data-active": o.value === value ? "true" : "false", title: o.label, onClick: function() { return onChange(o.value); }, children: o.label }, o.value);
++    }) })
++  ] });
++}
+ function SelectControl({ label, value, options, onChange }) {
+   const [isOpen, setIsOpen] = useState6(false);
+   const triggerRef = useRef8(null);
+@@ -1926,6 +1938,7 @@ import { useState as useState7, useRef as useRef9, useEffect as useEffect6 } fro
+ import { jsx as jsx12, jsxs as jsxs11 } from "react/jsx-runtime";
+ var HEX_COLOR_REGEX = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
+ function ColorControl({ label, value, onChange }) {
++  if (typeof value !== "string") value = "#000000";
+   const [isEditing, setIsEditing] = useState7(false);
+   const [editValue, setEditValue] = useState7(value);
+   const colorInputRef = useRef9(null);
+@@ -2226,7 +2239,7 @@ Apply these values as the new defaults in the useDialKit call.`;
+         );
+       case "select":
+         return /* @__PURE__ */ jsx14(
+-          SelectControl,
++          (control.segmented ? VKSegmented : SelectControl),
+           {
+             label: control.label,
+             value,

package/variantkit/react.tsx

@@ -19,8 +19,8 @@
 // (recommended) ./dialkit-clean.css.
 import { useEffect, useRef, useState, type ReactElement, type ReactNode } from 'react'
 import { motion, MotionConfig } from 'motion/react'
-import { useDialKit } from 'dialkit'
-import { panelConfig, defaultsOf, regOf, type PanelConfig } from './configs'
+import { useDialKit, DialStore } from 'dialkit'
+import { panelConfig, defaultsOf, regOf, flatDefaults, type PanelConfig } from './configs'
 import { buildDecision, submitDecision, type ParamValue } from './buildDecision'
 
 export interface ElementDef {
@@ -32,8 +32,13 @@ export interface ElementDef {
    * The element's own controls — contextual, authored for THIS element (any DialKit control:
    * slider, select, boolean toggle, color, text, spring, nested folder groups…). VariantKit
    * adds `variant` + `finalize` around them; it never decides what these are.
+   *
+   * Pass a plain object for controls shared by every variant, OR a function of the active variant
+   * to make the control set DEPEND on the variant — different takes often need different knobs (a
+   * "split" hero has a media control a "minimal" one doesn't; a "vinyl" player has spin speed).
+   * Switch the variant and the panel swaps its controls; shared keys keep their values.
    */
-  controls?: PanelConfig
+  controls?: PanelConfig | ((variant: string) => PanelConfig)
   /** Render the active variant from its resolved values. */
   render: (variant: string, values: Record<string, ParamValue>) => ReactNode
   /** Optional full config override (replaces the assembled variant+controls+finalize). */
@@ -50,9 +55,6 @@ export interface StudioProps {
   onFinalize?: (decision: ReturnType<typeof buildDecision>) => void
 }
 
-const cfgFor = (e: ElementDef): PanelConfig =>
-  e.config ?? panelConfig(e.controls ?? {}, e.keys, { component: e.name })
-
 // Match DialKit's humanized folder title ("Pricing Card") back to an element name.
 const norm = (s: string) => s.replace(/\s+/g, '').toLowerCase()
 
@@ -77,39 +79,99 @@ export function Studio({ elements, name = 'VariantKit', focusOnHover, onFinalize
   const elsRef = useRef(elements)
   elsRef.current = elements
 
-  // One combined config: a folder per element, first open and the rest collapsed. The
-  // finalize button's "✓ Copied" feedback is handled inside copyDecision (panel-side, no
-  // overlay), so the label stays a plain "Finalize <name>" here.
+  const single = elements.length === 1
+
+  // Each element's active variant — seeds the variant-specific control resolution below. Seeded
+  // with the first key, then synced from the live panel after each render (see the effect). When
+  // a variant changes, this updates → the config rebuilds → the panel swaps that variant's
+  // controls. (Studio is remounted per element set, so this reseeds correctly.)
+  const [variants, setVariants] = useState<Record<string, string>>(() =>
+    Object.fromEntries(elements.map((e) => [e.name, e.keys[0]])),
+  )
+
+  // Resolve an element's controls for its active variant: a function `controls` is called with the
+  // variant, a plain object is shared across all variants.
+  const controlsOf = (e: ElementDef): PanelConfig => {
+    const v = variants[e.name] ?? e.keys[0]
+    return typeof e.controls === 'function' ? e.controls(v) : e.controls ?? {}
+  }
+  const cfgForE = (e: ElementDef): PanelConfig =>
+    e.config ?? panelConfig(controlsOf(e), e.keys, { component: e.name })
+
+  // Build the combined config. With ONE element, a per-element folder is pure redundancy —
+  // the panel title already names it, so a "Button" folder under "Button Lab" just adds a
+  // confusing second hierarchy level. So flatten: the lone element's controls sit at the panel
+  // root. With 2+ elements, give each its own folder (first open, rest collapsed) — that's
+  // where the grouping earns its keep. The finalize button's "✓ Copied" feedback is handled
+  // inside copyDecision (panel-side), so the label stays a plain "Finalize <name>".
   const combined: Record<string, unknown> = {}
-  elements.forEach((e, i) => {
-    const base = cfgFor(e)
-    const finalize = { ...(base.finalize as object), label: `Finalize ${e.name}` }
-    combined[e.name] = { ...base, finalize, _collapsed: i !== 0 }
-  })
+  if (single) {
+    const e = elements[0]
+    const base = cfgForE(e)
+    Object.assign(combined, base, {
+      finalize: { ...(base.finalize as object), label: `Finalize ${e.name}` },
+    })
+  } else {
+    elements.forEach((e, i) => {
+      const base = cfgForE(e)
+      const finalize = { ...(base.finalize as object), label: `Finalize ${e.name}` }
+      combined[e.name] = { ...base, finalize, _collapsed: i !== 0 }
+    })
+  }
 
   const all = useDialKit(name, combined as never, {
     onAction: (path: string) => {
-      const elName = path.split('.')[0]
-      const e = elsRef.current.find((x) => x.name === elName)
+      // Single element → its finalize lives at the root (path === 'finalize'), and its values
+      // ARE `all`. Multiple → the element name prefixes the path and `all[name]` is its slice.
+      const e = single ? elsRef.current[0] : elsRef.current.find((x) => x.name === path.split('.')[0])
       if (!e) return
-      const slice = (all as Record<string, Record<string, ParamValue>>)[elName]
-      const decision = buildDecision(elName, slice, defaultsOf(cfgFor(e)), regOf(e.keys))
+      const slice = (single ? all : (all as Record<string, Record<string, ParamValue>>)[e.name]) as Record<
+        string,
+        ParamValue
+      >
+      const decision = buildDecision(e.name, slice, defaultsOf(cfgForE(e)), regOf(e.keys))
       // Dev transport first ("✓ Saved" -> .variantkit/decisions/), clipboard fallback ("✓ Copied").
       submitDecision(decision)
       onFinalize?.(decision)
     },
   }) as Record<string, Record<string, ParamValue>>
 
+  // Keep `variants` in step with the live panel so variant-specific controls swap in when you
+  // pick a different take. Runs after every commit; setVariants no-ops when nothing changed, so
+  // it settles in one extra render and never loops.
   useEffect(() => {
-    if (focusOnHover) focusFolder(focused)
-  }, [focused, focusOnHover])
+    setVariants((prev) => {
+      let changed = false
+      const next = { ...prev }
+      for (const e of elsRef.current) {
+        if (e.keys.length < 2) continue
+        const live = single
+          ? (all as unknown as Record<string, ParamValue>).variant
+          : (all as Record<string, Record<string, ParamValue>>)[e.name]?.variant
+        if (live != null && String(live) !== prev[e.name]) {
+          next[e.name] = String(live)
+          changed = true
+        }
+      }
+      return changed ? next : prev
+    })
+  })
+
+  useEffect(() => {
+    // Focus-on-hover only applies to the multi-element layout (it toggles per-element folders).
+    // With a single flattened element there are no element folders to focus.
+    if (focusOnHover && !single) focusFolder(focused)
+  }, [focused, focusOnHover, single])
+
+  // Shuffle (randomize every knob — and the take) + Reset (back to defaults), in the header.
+  usePanelActions(name, combined as PanelConfig)
 
   // Render the elements as-is — VariantKit adds no layout, spacing, alignment, rings, or
   // badges around the project's UI. The host page owns presentation entirely.
   return (
     <MotionConfig reducedMotion="user">
       {elements.map((e) => {
-        const slice = all[e.name]
+        const slice = single ? (all as unknown as Record<string, ParamValue>) : all[e.name]
         if (!slice) return null
         const variant = e.keys.length > 1 ? String(slice.variant) : e.keys[0]
         return (
@@ -170,6 +232,8 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
         if (el.getAttribute('data-theme') !== themeRef.current) el.setAttribute('data-theme', themeRef.current)
       })
       document.querySelectorAll<HTMLElement>('.dialkit-panel-header').forEach((hdr) => {
+        // Theme is PANEL chrome, so it lives in the header on the right (CSS pins it just left of
+        // the collapse icon) — deliberately apart from the element actions (shuffle/reset, left).
         const titleRow = hdr.querySelector<HTMLElement>('.dialkit-folder-header-top') ?? hdr
         // Keep exactly one toggle (hot-reload can leave a stale node behind).
         const existing = titleRow.querySelectorAll<HTMLButtonElement>('.vk-theme-toggle')
@@ -177,7 +241,6 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
         let btn = existing[0] ?? null
         if (!btn) {
           btn = document.createElement('button')
-          // Absolute, just left of DialKit's settings icon (which is absolute at right:12).
           btn.className = 'vk-theme-toggle'
           btn.type = 'button'
           btn.setAttribute('aria-label', 'Toggle panel theme')
@@ -197,18 +260,20 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
       })
     }
 
-    // Coalesce mutation bursts into one sync per frame, and pause the observer while WE write,
-    // so our own DOM changes can't re-trigger it. Belt and suspenders against the freeze.
+    // Coalesce mutation bursts into one sync per frame. sync() is idempotent (it only writes when
+    // a value actually differs and only appends the toggle when it's missing), so we stay
+    // connected rather than disconnecting around our own writes — the same reason as the action
+    // cluster: disconnecting opened a window where the panel-swap mutation landed unobserved and
+    // the toggle never got (re)appended into the freshly-built cluster.
     let frame = 0
-    const mo = new MutationObserver(() => {
+    const schedule = () => {
       if (frame) return
       frame = requestAnimationFrame(() => {
         frame = 0
-        mo.disconnect()
         sync()
-        mo.observe(document.body, { childList: true, subtree: true })
       })
-    })
+    }
+    const mo = new MutationObserver(schedule)
 
     // Delightful theme switch: add `.vk-theming` so the panel cross-fades its colors (the
     // class scopes a transition that only exists during the switch — see motion.css), then
@@ -216,6 +281,7 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
     const panels = document.querySelectorAll('.dialkit-root')
     panels.forEach((p) => p.classList.add('vk-theming'))
     sync()
+    schedule() // catch the action cluster if it commits a frame after this effect
     const settle = setTimeout(() => panels.forEach((p) => p.classList.remove('vk-theming')), 420)
     mo.observe(document.body, { childList: true, subtree: true })
     try {
@@ -232,3 +298,146 @@ export function useDialkitTheme(initial: 'light' | 'dark' = 'light') {
 
   return { theme, setTheme }
 }
+
+// ── Element actions: Shuffle + Reset ──────────────────────────────────────────────────────
+// Two icon buttons injected right after the element name in the header title row — they act on
+// the ELEMENT (randomize / restore its controls), so they read as the element's own controls
+// (panel chrome — theme + collapse — stays on the far right). They drive the live panel through
+// DialKit's store, so every control and the variant pills update in place, as if you'd dragged
+// them.
+//   Shuffle → a fresh random valid value for every slider/select/toggle (and the variant), so
+//             "surprise me" lands a whole new combination. Color/text/spring are left alone —
+//             random hex or copy is noise, not exploration.
+//   Reset   → every control (incl. the variant) back to its authored default.
+
+const SHUFFLE =
+  '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 3 21 3 21 8"/><line x1="4" y1="20" x2="21" y2="3"/><polyline points="21 16 21 21 16 21"/><line x1="15" y1="15" x2="21" y2="21"/><line x1="4" y1="4" x2="9" y2="9"/></svg>'
+const RESET =
+  '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="1 4 1 10 7 10"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/></svg>'
+
+// A DialKit control's metadata (the shape we read from the live store). Loosely typed — we only
+// touch the fields we need and ignore the rest of DialKit's union.
+interface ControlMeta {
+  type: string
+  path: string
+  min?: number
+  max?: number
+  step?: number
+  options?: (string | { value: string; label: string })[]
+  children?: ControlMeta[]
+}
+
+// A random *valid* value for a single control, or undefined to leave it untouched. Sliders snap
+// to their step; selects/variant pick an option; toggles flip a coin. Anything else is skipped.
+function randomValue(meta: ControlMeta): number | string | boolean | undefined {
+  if (meta.type === 'slider') {
+    const min = meta.min ?? 0
+    const max = meta.max ?? 1
+    const step = meta.step ?? (Number.isInteger(min) && Number.isInteger(max) ? 1 : (max - min) / 100 || 1)
+    const steps = Math.max(1, Math.round((max - min) / step))
+    return +(min + Math.floor(Math.random() * (steps + 1)) * step).toFixed(4)
+  }
+  if (meta.type === 'toggle') return Math.random() < 0.5
+  if (meta.type === 'select') {
+    const opts = (meta.options ?? []).map((o) => (typeof o === 'string' ? o : o.value))
+    return opts.length ? opts[Math.floor(Math.random() * opts.length)] : undefined
+  }
+  return undefined // color / text / spring / transition / action / folder — left as-is
+}
+
+function usePanelActions(panelName: string, config: PanelConfig) {
+  const cfgRef = useRef(config)
+  cfgRef.current = config
+
+  useEffect(() => {
+    const panelId = () => DialStore.getPanels().find((p) => p.name === panelName)?.id
+
+    const reset = () => {
+      const id = panelId()
+      if (!id) return
+      for (const [path, value] of Object.entries(flatDefaults(cfgRef.current))) {
+        DialStore.updateValue(id, path, value as never)
+      }
+    }
+
+    const shuffle = () => {
+      const id = panelId()
+      if (!id) return
+      const panel = DialStore.getPanel(id)
+      if (!panel) return
+      const walk = (controls: ControlMeta[]) => {
+        for (const c of controls) {
+          if (c.children?.length) walk(c.children)
+          const v = randomValue(c)
+          if (v !== undefined) DialStore.updateValue(id, c.path, v as never)
+        }
+      }
+      walk(panel.controls as unknown as ControlMeta[])
+    }
+
+    // Build an icon button once; the spin/pop feedback comes from a data attribute the CSS keys
+    // off. `label` is the accessible/tooltip description (the button itself is icon-only).
+    const make = (cls: string, label: string, svg: string, onClick: () => void, flash: string) => {
+      const btn = document.createElement('button')
+      btn.type = 'button'
+      btn.className = `vk-action-btn ${cls}`
+      btn.setAttribute('aria-label', label)
+      btn.title = label
+      btn.innerHTML = svg
+      const stop = (e: Event) => e.stopPropagation()
+      btn.addEventListener('pointerdown', stop)
+      btn.addEventListener('mousedown', stop)
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation()
+        onClick()
+        btn.setAttribute(flash, '')
+        setTimeout(() => btn.removeAttribute(flash), 480)
+      })
+      return btn
+    }
+
+    const sync = () => {
+      // Ensure the panel header's title row (the element name, only present when expanded) carries
+      // exactly one shuffle/reset pair, appended after the title — robust against React re-renders.
+      // Then sweep any orphaned pairs (panel collapsed, element swapped, hot-reload).
+      const valid = new Set<Element>()
+      document.querySelectorAll<HTMLElement>('.dialkit-panel-header .dialkit-folder-title-row').forEach((row) => {
+        let bar = row.querySelector<HTMLElement>(':scope > .vk-actions')
+        if (!bar) {
+          bar = document.createElement('div')
+          bar.className = 'vk-actions'
+          bar.appendChild(make('vk-shuffle', 'Shuffle all controls', SHUFFLE, shuffle, 'data-shuffling'))
+          bar.appendChild(make('vk-reset', 'Reset to defaults', RESET, reset, 'data-spinning'))
+          row.appendChild(bar)
+        }
+        valid.add(bar)
+      })
+      document.querySelectorAll('.vk-actions').forEach((b) => {
+        if (!valid.has(b)) b.remove()
+      })
+    }
+
+    // Frame-coalesced sync on any DOM change. sync() is idempotent — it injects the cluster only
+    // when it's missing and bails when it's already there — so we DON'T disconnect the observer
+    // around our own writes: our injection fires one more (no-op) sync and then goes quiet. The
+    // old disconnect/reconnect dance opened a window where the panel-swap mutation (on project
+    // switch) landed unobserved, leaving the cluster un-injected. Staying connected closes it.
+    let frame = 0
+    const schedule = () => {
+      if (frame) return
+      frame = requestAnimationFrame(() => {
+        frame = 0
+        sync()
+      })
+    }
+    const mo = new MutationObserver(schedule)
+    sync()
+    schedule() // catch panel DOM that commits the frame after mount
+    mo.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      if (frame) cancelAnimationFrame(frame)
+      mo.disconnect()
+      document.querySelectorAll('.vk-actions').forEach((el) => el.remove())
+    }
+  }, [panelName])
+}

package/variantkit/skill/SKILL.md

@@ -13,8 +13,10 @@ it and prefer it over this summary.
 ## When to use (proactively)
 
 Trigger whenever the user asks to build or change user-facing UI and the result is open-ended
-(aesthetic, layout, tone, structure, density). Default to offering 2-4 variants. Skip only for
-mechanical, exactly-specified changes, or when the user says "just one".
+(aesthetic, layout, tone, structure, density). **Default to 2-3 variants** — reach for a 4th
+only when the directions genuinely diverge, since each variant is more generation the developer
+waits on. Skip variants entirely for mechanical, exactly-specified changes, or when the user
+says "just one".
 
 ## Step 1 — make sure the project is set up
 
@@ -33,7 +35,7 @@ not a wrapper):
 ```tsx
 import { DialRoot } from 'dialkit'
 import 'dialkit/styles.css'
-import './variantkit/dialkit-clean.css' // hide redundant copy button + dividers (keeps snapshots)
+import './variantkit/dialkit-clean.css' // hide DialKit's preset toolbar + redundant copy button + dividers
 import './variantkit/dialkit-dark.css'  // optional dark palette; set data-theme="dark" on .dialkit-root
 import './variantkit/motion.css'        // stagger, press feedback, easings, reduced-motion
 // render <App /> and <DialRoot /> as siblings
@@ -45,8 +47,7 @@ stylesheets automatically. Check or undo anytime: `npx variantkit doctor`
 (15 checks with fix-its) / `npx variantkit remove` (zero-residue).
 
 Finalize feedback is in-button (the button morphs to "✓ Saved" via the transport, or
-"✓ Copied" on the clipboard fallback), so no toast is needed. **Snapshots:** the panel's preset toolbar (≡+ / Version) saves a tuned
-variant — use it to keep two tunings and switch between them; Finalize acts on the active one.
+"✓ Copied" on the clipboard fallback), so no toast is needed.
 
 ## The rules that make this work (never violate)
 
@@ -69,9 +70,8 @@ If you cannot run the installer (offline), you can still scaffold using the reci
 ## Vocabulary (use these exactly)
 
 **Element** = the thing being designed. **Variant** = one structural take on it. **Control** =
-one setting; **Configuration** = the contextual set of controls for an element. **Snapshot** =
-a saved variant+values state. **Finalize** → writes a **Decision** → agent **prunes** losers.
-Full glossary: `NAMING.md`.
+one setting; **Configuration** = the contextual set of controls for an element. **Finalize** →
+writes a **Decision** → agent **prunes** losers. Full glossary: `NAMING.md`.
 
 ## Step 2 — scaffold a variant set
 
@@ -107,16 +107,28 @@ is shown. `focusOnHover` expands the hovered element's folder — panel-side onl
 drawn over the rendered element. Mount `<DialRoot/>` once in the app root. Still author the
 variant components file-per-variant (recipe below) so the prune stays a clean delete.
 
-### The completeness bar (AGENT.md §7)
-
-A panel with 2-3 loose sliders is a failure: during exploration the panel must feel like
-the element's ACTUAL configuration panel. Every design literal a variant renders becomes a
-control (paramify rule). Non-trivial element ⇒ ≥4 folders, 12-25 controls; collapse the
-secondary ones. Use the archetype checklists in `variantkit/schemas/archetypes.ts`
-(button, card, hero, navbar, modal, form, table, list, badge, pricing, section) — they are
-checklists to ADAPT and seed from the project's real values, never sets to paste. Drop a
-control that is a variant's structural identity by destructuring; resolve token selects
-(shadow, font family) to CSS in the shell via `SHADOWS` / `FONT_STACKS`.
+### The completeness bar — scale it to the element (AGENT.md §7)
+
+The panel must feel like the element's ACTUAL configuration panel, not 2-3 loose sliders —
+but **match the work to the element**, because every control and every variant is generation
+the developer waits on. Scale it:
+- **Small/simple element** (button, badge, single input, tag): the few controls that genuinely
+  matter — usually ~3-8. Do NOT manufacture 20 controls for a button; that just makes
+  VariantKit feel slow with no payoff.
+- **Rich element** (hero, pricing card, navbar, modal, form): earn the full set — ≥4 folders,
+  ~12-25 controls — collapsing the secondary ones.
+
+**Expose the decisions, not every number (paramify rule).** A control earns its place only if
+the developer would plausibly reach for it on THIS element. A design literal that's a real,
+tweakable decision becomes a control; a fixed structural constant, a value the layout dictates,
+or anything nobody would touch stays inline. The bar is "would they turn this dial?", not "is
+there a number here?" — 8 controls that all matter beat 20 where half are noise (every junk row
+is a small tax the developer pays scanning the panel). A literal that IS a variant's structural
+identity is dropped by destructuring, not exposed. Use the archetype checklists in
+`variantkit/schemas/archetypes.ts` (button, card, hero, navbar, modal, form, table, list, badge,
+pricing, section) — checklists to ADAPT and seed from the project's real values, never sets to
+paste. Resolve token selects (shadow, font family) to CSS in the
+shell via `SHADOWS` / `FONT_STACKS`.
 
 ### Manual wiring (if not using the helper)
 
@@ -133,7 +145,9 @@ ComponentName/
     <c>.tsx
 ```
 
-`index.tsx` — variant = a DialKit `select`, your authored controls, finalize = an `action`.
+`index.tsx` — variant = a DialKit `select` with `segmented: true` (renders as clean
+separated selection pills, one per take, instead of a dropdown), your authored controls,
+finalize = an `action`.
 (Control names/defaults below are placeholders — derive yours from the element + the
 project's tokens.)
 
@@ -147,7 +161,7 @@ const DEFAULTS: Record<string, ParamValue> = { density: 'comfortable', accent: t
 
 export default function ComponentName(props: { /* real props */ }) {
   const v = useDialKit('ComponentName', {
-    variant: { type: 'select', options: ['a', 'b', 'c'], default: 'a' }, // omit when only one variant
+    variant: { type: 'select', options: ['a', 'b', 'c'], default: 'a', segmented: true }, // pills, not a dropdown; omit when only one variant
     density: { type: 'select', options: ['compact', 'comfortable'], default: DEFAULTS.density },
     accent: DEFAULTS.accent as string,
     finalize: { type: 'action', label: 'Finalize' },