variantkit 0.1.0 → 0.2.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.2.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() },

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;
 }
 
@@ -15,12 +16,85 @@
 }
 .dialkit-root .dialkit-panel-header {
   border-bottom: none !important;
+  /* The title row carried bottom spacing meant to clear the preset toolbar. With the toolbar
+     hidden that became a ~38px dead gap above the first control — reclaim it so the title sits
+     a normal step above the panel body. */
+  margin-bottom: 2px !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;
 }
 
+/* ── 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 {
+  /* sits on its own line above the pills */
+  padding: 0 2px;
+}
+.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);
+}
+
 /* The injected panel theme toggle — placed just left of DialKit's settings icon (right:12). */
 .dialkit-root .vk-theme-toggle {
   position: absolute;

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..385c7dc 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,44 @@ index d9f4837..4bf4e6d 100644
          children: folderContent
        }
      );
+@@ -1853,6 +1854,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);
+@@ -2266,7 +2276,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..a58300a 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 +73,28 @@ index f8d8baf..7a0e7b3 100644
          children: folderContent
        }
      );
+@@ -1813,6 +1814,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);
+@@ -2226,7 +2236,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

@@ -77,23 +77,39 @@ 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.
+  // 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 single = elements.length === 1
   const combined: Record<string, unknown> = {}
-  elements.forEach((e, i) => {
+  if (single) {
+    const e = elements[0]
     const base = cfgFor(e)
-    const finalize = { ...(base.finalize as object), label: `Finalize ${e.name}` }
-    combined[e.name] = { ...base, finalize, _collapsed: i !== 0 }
-  })
+    Object.assign(combined, base, {
+      finalize: { ...(base.finalize as object), label: `Finalize ${e.name}` },
+    })
+  } else {
+    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 }
+    })
+  }
 
   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(cfgFor(e)), regOf(e.keys))
       // Dev transport first ("✓ Saved" -> .variantkit/decisions/), clipboard fallback ("✓ Copied").
       submitDecision(decision)
       onFinalize?.(decision)
@@ -101,15 +117,17 @@ export function Studio({ elements, name = 'VariantKit', focusOnHover, onFinalize
   }) as Record<string, Record<string, ParamValue>>
 
   useEffect(() => {
-    if (focusOnHover) focusFolder(focused)
-  }, [focused, focusOnHover])
+    // 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])
 
   // 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 (

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' },