variantkit 0.1.0

package/AGENT.md

@@ -0,0 +1,428 @@
+# VariantKit — Agent Contract
+
+`contractVersion: 0.3`
+
+VariantKit lets a developer generate N structural variants of a component, choose one
+live in the running app, tweak its params, and finalize a winner. You (the coding agent)
+do two things: **scaffold** variant sets when asked for "options/variants/takes", and
+**prune** a set down to the chosen winner when a decision is finalized.
+
+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
+— one word per concept, defined in `NAMING.md`. Use them consistently.
+
+---
+
+## 0. When to offer variants (read this first)
+
+**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.
+
+Offer variants especially when:
+- the request is aesthetic or open-ended ("a pricing card", "make this nicer", "a hero")
+- there are real directions to explore (layout, density, tone, emphasis, structure)
+- the developer has not pinned exact specs
+
+Skip variants only when the change is mechanical and unambiguous (a copy fix, a wired bug,
+an exact pixel spec) or the developer explicitly says "just one". When unsure, offer options.
+
+Each variant you generate must pass the deslop rules in §6 — generated UI should not look
+AI-generated.
+
+**VariantKit presents; the project decides.** VariantKit is the panel, the wiring, the
+finalize → prune loop — nothing else. It has no opinion on what the variants look like or
+what their controls are:
+
+- **Design comes from the project.** You already know this project's design system, tokens,
+  and guidelines — every variant follows them, exactly as a hand-built component would.
+  VariantKit ships no colors, radii, fonts, spacings, or "house style". Never introduce a
+  VariantKit default into project UI.
+- **Controls come from the element.** For each element, author the controls that genuinely
+  matter for tweaking THAT element — its real design axes. Any number, any kind. There is no
+  standard control set, and no control is required besides finalize.
+- **Defaults come from the code.** Every control's default is the element's current/intended
+  value from the project (its tokens, its existing CSS) — never an invented value.
+- **The rendered element stays untouched.** No rings, badges, overlays, entrance animations,
+  or layout imposed on project UI. The user must be able to judge the element exactly as it
+  will ship.
+
+---
+
+## 1. Scaffolding a variant set
+
+When the developer asks for "options" / "N takes" / "variants" of a component, create a
+folder, file-per-variant:
+
+```
+ComponentName/
+  index.tsx          # thin shell: drives selection via DialKit, renders the active variant.
+                     # THE ONLY FILE THAT IMPORTS dialkit / variantkit / registry / buildDecision.
+  registry.ts        # maps variant key -> { component, label }
+  variants/
+    <keyA>.tsx        # one self-contained component per variant
+    <keyB>.tsx
+    <keyC>.tsx
+```
+
+Rules:
+- Each `variants/<key>.tsx` **default-exports** a component taking the SAME props.
+- Each variant file is **self-contained**: it imports nothing from VariantKit/DialKit and
+  nothing from a shared variant helper. Whatever it needs (e.g. the transition) is a local
+  const in that file.
+- **Shared transition (morph rule):** every variant declares the *identical* transition
+  local const on the morph-able properties (radius, padding, shadow, color). Duplicated on
+  purpose so the winner is self-contained after prune and switching reads as a morph, not a
+  snap.
+- Only `index.tsx` wires the tool. That single-point-of-wiring is what makes prune a
+  deletion, not surgery.
+
+## 2. Build on DialKit (v0)
+
+`index.tsx` drives selection through DialKit — variant choice is a `select`, params are
+controls, finalize is an `action`. **You author the controls per element** — there is no
+preset menu. `panelConfig(controls, variantKeys, opts)` (from `variantkit/configs`) wraps
+your controls with the structural parts: a `variant` select (only when there are 2+ keys) and
+a `finalize` action. Derive `defaults` with `defaultsOf` so you never hand-maintain a separate
+defaults object.
+
+```tsx
+import { useDialKit } from 'dialkit'
+import { registry } from './registry'
+import { buildDecision, submitDecision } from '../../variantkit/buildDecision'
+import { panelConfig, defaultsOf, regOf } from '../../variantkit/configs'
+
+const KEYS = ['ledger', 'slab', 'inverse']
+// These controls are EXAMPLES — derive yours from this element + this project's tokens.
+const cfg = panelConfig(
+  {
+    density: { type: 'select', options: ['compact', 'comfortable'], default: 'comfortable' },
+    accent: tokens.brand,          // default = the project's real token, not an invented hex
+    showAnnualToggle: true,
+  },
+  KEYS,
+  { component: 'PricingCard' },
+)
+
+export default function PricingCard(props: { plan?: string }) {
+  const v = useDialKit('PricingCard', cfg, {
+    onAction: () => submitDecision(buildDecision('PricingCard', v, defaultsOf(cfg), regOf(KEYS))),
+  })
+  const Active = registry[v.variant].component
+  return <Active {...props} density={v.density} accent={v.accent} showAnnualToggle={v.showAnnualToggle} />
+}
+```
+
+### Authoring controls — contextual, unrestricted
+
+Ask: *which axes of this element would the developer actually want to tweak before
+committing?* Those are the controls. Nothing else.
+
+- **Any DialKit control is fair game:** number `[default, min, max]` → slider; string →
+  text input; `#hex` string → color picker; boolean → segmented Off|On toggle; `select` →
+  dropdown; `{ type: 'spring' | 'transition' }` → motion editor (only for elements that
+  actually move); a nested object → a folder (group related controls of a complex element).
+- **Any count.** A button might need two controls; a data table might need ten in two
+  folders. More is not better — show what this element needs, nothing it doesn't.
+- **Never copy a control set** from this file, another element, or a previous project. The
+  set that repeats across unrelated elements is by definition not contextual. (The archetype
+  schemas in §7 are checklists of design axes to ADAPT and seed from the code — not sets to
+  paste.)
+- **Cover the element fully.** Contextual does not mean minimal — §7 sets the completeness
+  bar: the panel should feel like the element's actual configuration panel.
+- **Defaults are the project's values.** Pull them from the design tokens or the element's
+  current styles. If you typed a literal that exists nowhere in the project, it's wrong.
+
+### Multiple elements → ONE panel (folders), never many
+
+DialKit renders one panel per `useDialKit` call, so calling it from each component clutters
+the screen with stacked panels. For 2+ elements in play, make a **single** `useDialKit` call
+whose config has **one folder per element** (a nested object becomes a folder). Route each
+folder's finalize via `onAction(path)` — `path` is dot-notation, e.g. `PricingCard.finalize`.
+
+```tsx
+const ELEMENTS = [
+  { name: 'Hero', keys: ['centered','split','minimal'], controls: heroControls },
+  { name: 'PricingCard', keys: ['slab','ledger','inverse'], controls: cardControls },
+]
+const combined = Object.fromEntries(
+  ELEMENTS.map((e, i) => [e.name, { ...panelConfig(e.controls, e.keys, { component: e.name }), _collapsed: i !== 0 }]),
+)
+const all = useDialKit('VariantKit', combined, {
+  onAction: (path) => {
+    const e = ELEMENTS.find((x) => x.name === path.split('.')[0])!
+    submitDecision(buildDecision(e.name, all[e.name], defaultsOf(panelConfig(e.controls, e.keys)), regOf(e.keys)))
+  },
+})
+// values are nested: all.Hero.headingSize, all.PricingCard.density, ...
+```
+
+`_collapsed: true` starts a folder closed (first one open). Result: one panel, a section per
+element, each with its contextual controls and its own Finalize. See `examples/contextual`.
+
+**Easiest path — the `Studio` helper.** Don't hand-write the wiring above; use it:
+
+```tsx
+import { Studio, type ElementDef } from './variantkit/react'
+
+const ELEMENTS: ElementDef[] = [
+  { name: 'PricingCard', keys: ['slab','ledger','inverse'], controls: cardControls, render: (variant, v) => <Card variant={variant} {...v} /> },
+  // ...more elements, each with ITS OWN authored controls
+]
+<Studio elements={ELEMENTS} focusOnHover />   // one panel, folders, finalize routing, focus
+```
+
+`focusOnHover` expands the panel folder of the element you hover — so the panel always shows
+"the element you're editing." It is panel-side only: **nothing is ever drawn on or around the
+rendered element** (no rings, badges, or overlays — the user must see the element exactly as
+it ships). For a SINGLE element, just pass one entry (one folder, nothing extra); with one
+variant key, no variant dropdown is shown. DialKit's `<DialRoot/>` must be mounted once in
+the app root.
+
+### On-canvas chrome — VariantBar and VariantStage
+
+`<VariantBar/>` (`variantkit/react/VariantBar`) mounts once next to `<DialRoot/>`: a slim
+bottom bar with variant tabs, keys 1..9, a live side-by-side **Compare** toggle, and
+Finalize. It auto-discovers every variant set from DialKit's store — both the classic
+shell layout and the Studio's folder-per-element layout — no per-component wiring. It is
+tool chrome at the screen edge; it never decorates the rendered element itself.
+
+For the classic single-set shell, render through `<VariantStage/>`
+(`variantkit/react/VariantStage`) instead of a bare `<Active/>` — same render normally,
+and a live grid of all variants when Compare is on (clicking a cell selects it):
+
+```tsx
+return <VariantStage name="PricingCard" registry={registry} active={String(v.variant)} props={variantProps} />
+```
+
+### Hide the redundant copy button
+
+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-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
+groups become `"surface.radius"` — so grouped configurations stay flat and inlineable.
+
+```jsonc
+{
+  "schema": 2,
+  "component": "PricingCard",
+  "finalized": "slab",                                  // the winning variant key
+  "values": {                                           // final live values to inline
+    "density": "compact",
+    "surface.radius": 12,
+    "accent": "#175048"
+  },
+  "overridesFromDefault": {                             // only changed keys; the taste signal
+    "density": { "from": "comfortable", "to": "compact" },
+    "accent": { "from": "#1F5E54", "to": "#175048" }    // from = the project's own default
+  },
+  "prune": ["ledger", "inverse"],                       // loser keys to delete
+  "note": "",
+  "status": "pending",
+  "timestamp": "2026-06-09T00:00:00Z"
+}
+```
+
+When inlining (§4), a dot-path maps to the prop the shell derived from it: the prop fed by
+`v.surface.radius` gets the literal at `"surface.radius"`. Token values (`"shadow": "lg"`)
+inline as the **resolved CSS** the shell produced, not the token string.
+
+## 4. Prune algorithm (the reliable part)
+
+**Where decisions come from.** Finalize ships the decision through the dev transport
+(vite plugin / Next route) into `.variantkit/decisions/<Component>.json`. When no
+transport is running it falls back to the clipboard and the developer pastes it to you.
+
+**When to apply.** On "apply decision" / "apply the decision" — and at the start of any
+session in a VariantKit project — scan `.variantkit/decisions/*.json` for
+`status: "pending"` and prune each one. A pasted decision JSON is applied the same way.
+
+Given a decision with `status: "pending"`:
+
+1. **INLINE** the `values` into the winner file `variants/<finalized>.tsx` — replace the
+   prop-driven values with the literals (so the component needs no incoming params).
+2. **PROMOTE by rename** — `mv variants/<finalized>.tsx index.tsx`, overwriting the old
+   shell. **Do NOT copy code into the old index by hand.** (Rule 1A: rename, never move JSX.)
+3. **DELETE** every loser in `prune` plus any leftover `variants/*.tsx`; remove the now-empty
+   `variants/` folder.
+4. **DELETE** `registry.ts`.
+5. Mark the decision `resolved`: append the decision (with `"status": "resolved"`) as one
+   line to `.variantkit/history/log.jsonl`, then delete
+   `.variantkit/decisions/<Component>.json`. For pasted decisions, append the same way.
+
+Net diff: deleted files + one renamed file + inlined literals. No JSX moved between files.
+
+## 5. Self-check after pruning (ALL must be true)
+
+- [ ] No file imports `dialkit`, `variantkit`, `./registry`, or `buildDecision`.
+- [ ] `variants/` is gone; `registry.ts` is gone.
+- [ ] `index.tsx` renders the winner with the finalized `values` inlined as literals.
+- [ ] The component's visible output matches the winning variant before prune.
+
+If any box is unchecked, the prune is wrong. Re-read this file; do not hand-patch around it.
+
+---
+
+## 6. Deslop — generated variants must not look AI-generated
+
+Apply this to every variant you generate. Also run it as a pass on request ("deslop",
+"remove the AI slop", "this looks AI-generated", "strip the AI tells").
+
+**Core principle:** slop is *decoration without a system*. A tell is slop when it appears as
+a one-off for "flavor"; it is fine when it is a consistent, intentional, repeated system. The
+test is never "does this pattern appear" — it is "does it earn its place in a repeated
+system." Default to **keep** when meaning is unclear; never delete load-bearing meaning.
+**Subtract, never add** — deslop introduces no new color, font, or decoration.
+
+Catalog (signature → slop when → fix), adapted from the design-deslop skill:
+
+1. **Random italics** — `italic`, `<em>/<i>` on headings/labels/captions → one-off "flavor"
+   → remove italic; use weight/size for emphasis. Keep true inline prose emphasis.
+2. **Random mono font** — `font-mono`, `*mono*` family on labels/eyebrows/body → "tech feel"
+   with no data reason → revert to UI font; for numbers use `tabular-nums`, not a mono face.
+3. **All-caps + wide tracking "eyebrows"** — `uppercase` + `tracking-wide*` kicker above every
+   heading (the single most common AI tell) → delete it, or keep at most one system-wide,
+   normal-case at real hierarchy.
+4. **Decorative accent / divider lines** — `w-8 h-px`, `h-1 w-10 bg-{color}`, `::before` bars
+   under headings → remove. Keep only full-width structural rules doing layout work.
+5. **Ornamental colored dots** — `w-1.5 h-1.5 rounded-full bg-{color}`, `•`, `animate-pulse`
+   dots that convey no status → remove. Keep dots that encode real state (online, unread).
+6. **Unmotivated warm accents** — amber/orange/rose (`#f59e0b #f97316 #fb923c #f43f5e`, warm
+   gradients) injected for "energy" when warm is not the brand → map back to the design's
+   real tokens. Reserve warm for true semantic meaning (a real warning).
+7. **Decorative single letters / monograms** — lone styled `A`/`01`/drop-cap/letter-in-a-box
+   standing for nothing → remove. Keep real initial avatars for named entities.
+8. **Oversized rounded corners** — `rounded-3xl`, radius ≥ 20px on cards/buttons/inputs →
+   bring to ~8–12px, consistent and concentric (inner = outer − padding). Pills/avatars stay
+   full-round on purpose.
+9. **One-sided / gradient highlight borders** — `border-t-2 border-{accent}` top stripes,
+   gradient/`mask` borders, one-side glows for flair → use a uniform 1px border or none.
+   Reserve edge accents for real selected/semantic states.
+10. **Em dashes in copy** — replace `—` with commas, colons, or separate sentences.
+11. **Emoji in product UI** — remove decorative emoji from interface copy and labels.
+
+**Deslop-on-request workflow:** scope (the named files or the current diff) → scan each
+signature → judge each hit with the Intentional Test above → remove only the slop → verify
+in the browser (before/after) → report a table (`# | tell | file:line | removed/kept | why`).
+
+**Scope note:** this applies to the **generated app components** (the variants). It does NOT
+apply to the VariantKit/DialKit dev panel — the panel's mono labels, amber accent, and pill
+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).
+
+**Archetype checklists.** `variantkit/schemas/archetypes.ts` ships per-element-family
+checklists of design axes:
+
+`button · card · hero · navbar · modal · form · table · list · badge · pricing · section`
+
+built from section builders in `variantkit/schemas/sections.ts` (`layoutSection`,
+`surfaceSection`, `typographySection`, `colorSection`, `motionSection`, `statesSection`).
+They are **checklists to adapt, not sets to paste** (§2 authoring rules apply unchanged):
+
+- **Seed every default from the code.** Pass the element's rendered values as overrides —
+  `pricingArchetype({ surface: { radius: 18 }, color: { accent: tokens.brand } })` — so the
+  panel opens matching what's on screen. The builders' fallback values are scaffolding for
+  brand-new elements only; on an existing element, an unseeded default is a §0 violation.
+- **Adapt the set.** Drop axes this element doesn't have, add the ones it does (`extra`),
+  rename folders if the element thinks in different terms. Two unrelated elements ending up
+  with identical panels means you pasted, not adapted.
+- **Copy control shapes, never invent control types.** DialKit supports: slider
+  `[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.
+
+**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
+not expose it — drop that control by destructuring and leave the literal in the variant:
+
+```ts
+const { bg: _bg, ...surface } = sections.surface  // variants own their surface bg
+```
+
+**Token resolution.** Selects may return tokens (`shadow: 'lg'`, `family: 'mono'`). The
+SHELL resolves tokens to CSS (`SHADOWS` / `FONT_STACKS` from the schemas) and passes plain
+CSS values as props. Variants never import from variantkit/schemas — they stay
+self-contained (§1).
+
+**Standalone paramify (no variants).** On "paramify this" / "let me tweak this" / "give me
+controls for this" for an EXISTING component: wrap it with a full configuration — no
+registry, no variants/ folder, no variant select. Just `useDialKit` (or a single-entry
+`Studio`) with the adapted archetype + a finalize action, props fed from panel values. On
+finalize: inline the final values back as literals and strip the wiring completely (§5
+self-check applies, minus the registry/variants boxes).
+
+---
+
+## 8. Taste memory — decisions compound
+
+Every resolved decision is one line in `.variantkit/history/log.jsonl`. The
+`overridesFromDefault` fields are the developer telling you, with numbers, where your
+defaults were wrong. Use them.
+
+**Distill (after resolving, when history has ≥3 entries).** Write or update
+`.variantkit/TASTE.md` with observed preferences. Rules:
+
+- **Grounded only.** Every claim cites ≥2 decisions with the actual values. No claim from
+  a single data point; no speculation ("seems to like minimal" is banned — "finalized
+  radius 8-12 in 4/4 decisions, always below my default" is the format).
+- **Track the dimensions that repeat:** radius range, accent hue temperature, spacing
+  density (padding/gap direction vs default), shadow level, type scale, variant character
+  (which structural take keeps winning: dense/outlined/dark...).
+- **Keep it short** — a scannable bullet list, ≤15 lines, newest evidence first.
+- **Update, don't append forever:** revise existing bullets as new decisions land; drop
+  bullets the data stops supporting.
+
+Format:
+
+```markdown
+# Taste — observed from finalized decisions
+<!-- distilled by the agent from .variantkit/history/log.jsonl — grounded claims only -->
+
+- Radius lands 8-12 (18→12, 16→8, 12→10 across PricingCard, Hero, Modal). Default to 10.
+- Accents shift cooler + darker (#1F5E54→#175048, #3B82F6→#1D4ED8). Avoid warm accents.
+- Picks the densest structural take (slab 2x, compact-table 1x). Offer one dense variant first.
+```
+
+**Read back (before generating).** Before scaffolding any variant set or paramify panel,
+read `.variantkit/TASTE.md` if it exists. Seed defaults toward the observed preferences —
+and still include ONE variant that deliberately breaks the pattern, so taste keeps getting
+tested rather than ossified.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepak Maurya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NAMING.md

@@ -0,0 +1,42 @@
+# VariantKit — Vocabulary
+
+One word per concept, used the same way everywhere (code, UI, docs, agent contract). If a
+term here conflicts with how you named something, this file wins — rename the code.
+
+## The core nouns
+
+| 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`) |
+| **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) |
+| **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" |
+
+## Supporting terms
+
+| Term | Means |
+|------|-------|
+| **Panel** | The floating dev-time UI that hosts the controls (DialKit). One panel per session. |
+| **Folder** | One element's collapsible section inside the single panel. One folder = one element. |
+| **Registry** | Map of variant key → component, per element. Used to render the active variant and to compute the prune list. |
+| **Set** (variant set) | An element plus its variants + registry + the shell that wires them. What the agent scaffolds. |
+| **DialKit config object** | The technical config you pass to `useDialKit` (controls + the `variant` select + the `finalize` action). The *implementation* of a Configuration. Don't say "config" when you mean the user-facing Configuration. |
+| **Archetype** | A per-element-family CHECKLIST of design axes (`variantkit/schemas/archetypes.ts`) used to assemble a complete Configuration — adapted per element and seeded from the project's values, never pasted as-is. |
+| **Section** | One design dimension's worth of controls (layout, surface, typography, color, motion, states) — the building blocks archetypes compose. |
+| **Paramify** | Wrapping an EXISTING component in its full Configuration (no variants) so the user can tune it live, then inline the result. |
+| **Transport** | The dev-only channel (vite plugin / Next route) that carries a Decision from Finalize into `.variantkit/decisions/`. Clipboard is the fallback. |
+| **Compare** | VariantBar's side-by-side mode: every variant rendered live in a grid (VariantStage). |
+| **Taste** | `.variantkit/TASTE.md` — grounded preferences distilled from resolved Decisions, read back before generating. |
+
+## 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.

package/README.md

@@ -0,0 +1,111 @@
+# VariantKit
+
+**The configuration panel for AI-built UI.**
+
+You: *"three takes on the pricing card."*
+Your agent builds three real variants in your running app — wired to a full control panel
+with every knob that matters: layout, surface, typography, color, motion. You switch with
+keys 1-2-3, compare them side by side, drag sliders until it's right, hit **Finalize** —
+and the losers are pruned from your codebase. What ships is a plain component with zero
+tool residue.
+
+![VariantKit demo: switching variants with keys, live compare grid, finalize](https://raw.githubusercontent.com/deepshal99/variantkit/main/docs/demo.gif)
+
+![VariantKit: three live variants, full contextual panel, compare grid, finalize bar](https://raw.githubusercontent.com/deepshal99/variantkit/main/docs/demo-compare.png)
+
+Stop describing tweaks in chat. Tweak the thing, then hand your agent the decision.
+
+## Install
+
+From inside your project (Vite or Next.js, React 18+):
+
+```sh
+npx variantkit
+```
+
+(or straight from GitHub: `npx github:deepshal99/variantkit`)
+
+One command does everything:
+
+- installs `dialkit` + `motion`
+- copies the runtime (`buildDecision`, archetype schemas, `VariantBar`/`VariantStage`)
+- wires the decision transport (Vite plugin or Next API route)
+- mounts `<DialRoot/>` + `<VariantBar/>` in your app entry
+- teaches your AI the contract (`AGENT.md` + a pointer in `CLAUDE.md`/`AGENTS.md`/Cursor rules)
+- installs the global Claude Code skill (so every project gets variants proactively)
+
+Check or undo anytime:
+
+```sh
+npx variantkit doctor    # 15 checks with fix-its
+npx variantkit remove    # zero-residue uninstall (git-clean verified)
+```
+
+Flags: `--dry-run` `--skip-install` `--no-mount` `--no-skill` (init) · `--keep-deps` (remove)
+
+## The loop
+
+1. **Ask for options.** "Give me three takes on the hero." The agent scaffolds a variant
+   set: 2-4 self-contained components + a thin shell wiring the panel.
+2. **Get a real panel, not 3 sliders.** The agent authors the controls for YOUR element
+   (VariantKit presents; the project decides) using **archetype checklists** per element
+   type (`button · card · hero · navbar · modal · form · table · list · badge · pricing ·
+   section`) — adapted, grouped in folders, every default seeded from your code.
+3. **Explore.** Switch variants with the bottom bar or keys 1-9. **Compare** renders all
+   variants in a live grid — drag a slider, every variant reacts.
+4. **Finalize.** The decision (winner + your overrides — the taste signal) lands in
+   `.variantkit/decisions/` via the dev server. No copy-paste. (Clipboard fallback when no
+   transport is running.)
+5. **"Apply decision."** The agent inlines your final values into the winner, renames it to
+   `index.tsx`, deletes the losers and all tool wiring. Deterministic: deletion + one
+   rename + literal inlining — no JSX surgery.
+6. **It compounds.** Resolved decisions append to `.variantkit/history/`. After 3+, the
+   agent distills `TASTE.md` — grounded observations ("radius lands 8-12, 3/3 decisions")
+   that seed better defaults next time.
+
+## Also in the box
+
+- **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.
+
+## Not just variants: paramify anything
+
+*"Let me tweak this"* on any existing component wraps it in its archetype panel — no
+variants, no registry. Tune it live, finalize, and the values inline back as literals with
+the wiring stripped.
+
+## Why not just ask the AI to build a switcher?
+
+You can — every time, ad hoc, with 2-3 controls it happens to think of, and then ask it to
+rip its own scaffolding back out and hope. VariantKit makes that loop a **contract**:
+archetype panels with the controls the element actually needs, one keyboard-driven bar for
+every set, a schema'd decision file, a prune algorithm with a self-check, and an uninstall
+that leaves `git status` clean. Compared to Storybook knobs: this runs **in your real app**,
+against real data and layout — and removes itself when you decide.
+
+## How it relates to DialKit
+
+[DialKit](https://github.com/joshpuckett/dialkit) answers *"what number should this be?"*
+VariantKit answers *"which direction should this go?"* — and uses DialKit as its control
+panel through its documented store API (no fork; the one patch-package patch is cosmetic —
+the panel's minimize/expand morph — and entirely optional).
+
+## Repo map
+
+- `variantkit/` — what gets installed: `buildDecision.ts` (pure core), `configs.ts`
+  (panel assembly), `schemas/` (sections + 11 archetype checklists), `react.tsx` (Studio +
+  panel theme), `react/` (VariantBar, VariantStage), panel css, `patches/` (panel morph),
+  `vite-plugin.mjs`, `templates/` (Next routes), `init.mjs` (init/doctor/remove), `skill/`
+- `AGENT.md` — the agent contract: scaffold convention, authoring rules, decision schema
+  (v2, dot-paths), prune + self-check, §7 completeness bar, deslop, taste memory
+- `NAMING.md` — the vocabulary (one word per concept)
+- `examples/sandbox/` — wired Vite example (PricingCard, 3 variants, 19-control panel);
+  `examples/panel-studio/` — the Studio dogfood
+- `fixture/` — prune before/after proof + taste distillation fixture
+
+MIT.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "variantkit",
+  "version": "0.1.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": {
+    "variantkit": "variantkit/init.mjs"
+  },
+  "files": [
+    "variantkit",
+    "AGENT.md",
+    "NAMING.md"
+  ],
+  "scripts": {
+    "init": "node variantkit/init.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepshal99/variantkit.git"
+  },
+  "keywords": [
+    "ai",
+    "ui",
+    "design",
+    "variants",
+    "claude-code",
+    "cursor",
+    "dialkit",
+    "dev-tools",
+    "react"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}