variantkit 0.1.0

package/variantkit/schemas/archetypes.ts

@@ -0,0 +1,216 @@
+// VariantKit archetypes — per-element-family CHECKLISTS of design axes, composed from
+// section builders (./sections.ts) plus the element's own controls. They exist so a
+// configuration covers everything that's actually a design decision for an element
+// (layout, surface, typography, color, motion, states, element-specific knobs) instead
+// of 2-3 loose sliders.
+//
+// "VariantKit presents; the project decides" still holds (AGENT.md §0/§7): adapt the
+// set per element, seed every default from the project's rendered values/tokens, drop
+// axes the element doesn't have. The fallback values below are scaffolding for brand-new
+// elements only — on an existing element, an unseeded default is a contract violation.
+//
+// Contract (AGENT.md §7): a non-trivial element gets an archetype panel — ≥4 folders,
+// 12-25 controls — with defaults seeded from the code as rendered:
+//
+//   useDialKit('PricingCard', {
+//     variant: { type: 'select', options: [...], default: '...' },
+//     ...pricingArchetype({ surface: { radius: 18 }, color: { accent: '#1F5E54' } }),
+//     finalize: { type: 'action', label: 'Finalize' },
+//   })
+//
+// Pure data — safe to import anywhere, prunes away cleanly.
+
+import {
+  layoutSection,
+  surfaceSection,
+  typographySection,
+  colorSection,
+  motionSection,
+  statesSection,
+  type SectionConfig,
+  type Slider,
+  type SelectOption,
+} from './sections'
+
+export * from './sections'
+
+type Overrides = {
+  layout?: Parameters<typeof layoutSection>[0]
+  surface?: Parameters<typeof surfaceSection>[0]
+  typography?: Parameters<typeof typographySection>[0]
+  color?: Parameters<typeof colorSection>[0]
+  motion?: Parameters<typeof motionSection>[0]
+  states?: Parameters<typeof statesSection>[0]
+  /** Extra top-level controls or folders merged into the panel. */
+  extra?: SectionConfig
+}
+
+const select = (options: SelectOption[], def?: string) => ({ type: 'select' as const, options, default: def })
+
+// ---------------------------------------------------------------------------
+
+export function buttonArchetype(o: Overrides & { size?: string; iconPosition?: string; fullWidth?: boolean } = {}) {
+  return {
+    size: select(['sm', 'md', 'lg'], o.size ?? 'md'),
+    iconPosition: select(['none', 'left', 'right'], o.iconPosition ?? 'none'),
+    fullWidth: o.fullWidth ?? false,
+    surface: surfaceSection({ radius: 8, shadow: 'none', ...o.surface }),
+    typography: typographySection({ size: 14, weight: '600', ...o.typography }),
+    color: colorSection(o.color),
+    states: statesSection(o.states),
+    motion: motionSection(o.motion, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function cardArchetype(o: Overrides & { media?: string; density?: string } = {}) {
+  return {
+    media: select(['none', 'top', 'left'], o.media ?? 'none'),
+    density: select(['compact', 'regular', 'spacious'], o.density ?? 'regular'),
+    layout: layoutSection({ padding: 24, gap: 12, ...o.layout }),
+    surface: surfaceSection(o.surface),
+    typography: typographySection(o.typography, { collapsed: true }),
+    color: colorSection(o.color),
+    states: statesSection(o.states, { collapsed: true }),
+    motion: motionSection(o.motion, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function heroArchetype(o: Overrides & { alignment?: string; ctaStyle?: string; minHeight?: number } = {}) {
+  return {
+    alignment: select(['left', 'center'], o.alignment ?? 'left'),
+    ctaStyle: select(['solid', 'outline', 'ghost'], o.ctaStyle ?? 'solid'),
+    minHeight: [o.minHeight ?? 480, 240, 960, 10] as Slider,
+    layout: layoutSection({ padding: 64, gap: 24, maxWidth: 960, ...o.layout }),
+    typography: typographySection({ size: 44, weight: '700', lineHeight: 1.1, tracking: -0.5, ...o.typography }),
+    color: colorSection(o.color),
+    motion: motionSection(o.motion, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function navbarArchetype(o: Overrides & { height?: number; sticky?: boolean; blur?: number; linkGap?: number } = {}) {
+  return {
+    height: [o.height ?? 56, 40, 96, 1] as Slider,
+    sticky: o.sticky ?? true,
+    blur: [o.blur ?? 8, 0, 24, 1] as Slider,
+    linkGap: [o.linkGap ?? 24, 8, 64, 1] as Slider,
+    surface: surfaceSection({ shadow: 'xs', radius: 0, ...o.surface }),
+    typography: typographySection({ size: 14, ...o.typography }, { collapsed: true }),
+    color: colorSection(o.color),
+    motion: motionSection(o.motion, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function modalArchetype(o: Overrides & { width?: number; overlayOpacity?: number; backdropBlur?: number } = {}) {
+  return {
+    width: [o.width ?? 440, 280, 880, 10] as Slider,
+    overlayOpacity: [o.overlayOpacity ?? 0.5, 0, 1, 0.05] as Slider,
+    backdropBlur: [o.backdropBlur ?? 0, 0, 16, 1] as Slider,
+    layout: layoutSection({ padding: 24, gap: 16, ...o.layout }),
+    surface: surfaceSection({ radius: 12, shadow: 'xl', ...o.surface }),
+    typography: typographySection(o.typography, { collapsed: true }),
+    color: colorSection(o.color),
+    motion: motionSection(o.motion),
+    ...o.extra,
+  }
+}
+
+export function formArchetype(o: Overrides & { labelPosition?: string; fieldGap?: number; inputRadius?: number } = {}) {
+  return {
+    labelPosition: select(['top', 'left', 'floating'], o.labelPosition ?? 'top'),
+    fieldGap: [o.fieldGap ?? 16, 4, 48, 1] as Slider,
+    inputRadius: [o.inputRadius ?? 8, 0, 24, 1] as Slider,
+    layout: layoutSection({ padding: 0, gap: 16, ...o.layout }, { collapsed: true }),
+    surface: surfaceSection(o.surface, { collapsed: true }),
+    typography: typographySection({ size: 14, ...o.typography }),
+    color: colorSection(o.color),
+    states: statesSection(o.states, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function tableArchetype(o: Overrides & { density?: string; rowHeight?: number; striped?: boolean; dividers?: string } = {}) {
+  return {
+    density: select(['compact', 'regular', 'relaxed'], o.density ?? 'regular'),
+    rowHeight: [o.rowHeight ?? 44, 28, 72, 1] as Slider,
+    striped: o.striped ?? false,
+    dividers: select(['none', 'rows', 'all'], o.dividers ?? 'rows'),
+    surface: surfaceSection({ shadow: 'none', ...o.surface }),
+    typography: typographySection({ size: 13, ...o.typography }),
+    color: colorSection(o.color),
+    states: statesSection(o.states, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function listArchetype(o: Overrides & { marker?: string; itemGap?: number; dense?: boolean } = {}) {
+  return {
+    marker: select(['none', 'dot', 'check', 'number'], o.marker ?? 'none'),
+    itemGap: [o.itemGap ?? 8, 0, 32, 1] as Slider,
+    dense: o.dense ?? false,
+    layout: layoutSection({ padding: 0, gap: 8, ...o.layout }, { collapsed: true }),
+    typography: typographySection(o.typography),
+    color: colorSection(o.color),
+    states: statesSection(o.states, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function badgeArchetype(o: Overrides & { size?: string; pill?: boolean; tone?: string } = {}) {
+  return {
+    size: select(['sm', 'md'], o.size ?? 'sm'),
+    pill: o.pill ?? true,
+    tone: select(['neutral', 'accent', 'success', 'warning', 'danger'], o.tone ?? 'neutral'),
+    surface: surfaceSection({ radius: 6, shadow: 'none', borderWidth: 1, ...o.surface }),
+    typography: typographySection({ size: 12, weight: '500', ...o.typography }),
+    color: colorSection(o.color),
+    ...o.extra,
+  }
+}
+
+export function pricingArchetype(o: Overrides & { priceSize?: number; featured?: boolean; ctaStyle?: string } = {}) {
+  return {
+    priceSize: [o.priceSize ?? 36, 20, 64, 1] as Slider,
+    featured: o.featured ?? false,
+    ctaStyle: select(['solid', 'outline', 'ghost'], o.ctaStyle ?? 'solid'),
+    layout: layoutSection({ padding: 28, gap: 16, maxWidth: 380, ...o.layout }),
+    surface: surfaceSection(o.surface),
+    typography: typographySection(o.typography, { collapsed: true }),
+    color: colorSection(o.color),
+    states: statesSection(o.states, { collapsed: true }),
+    motion: motionSection(o.motion, { collapsed: true }),
+    ...o.extra,
+  }
+}
+
+export function sectionArchetype(o: Overrides & { paddingY?: number } = {}) {
+  return {
+    paddingY: [o.paddingY ?? 80, 0, 240, 4] as Slider,
+    layout: layoutSection({ padding: 24, gap: 32, maxWidth: 1120, ...o.layout }),
+    surface: surfaceSection({ shadow: 'none', radius: 0, ...o.surface }),
+    typography: typographySection({ size: 32, weight: '700', ...o.typography }),
+    color: colorSection(o.color),
+    ...o.extra,
+  }
+}
+
+// Lookup for agents: archetype key -> builder. Pick the closest archetype; when nothing
+// fits, compose sections directly per AGENT.md §7.
+export const ARCHETYPES = {
+  button: buttonArchetype,
+  card: cardArchetype,
+  hero: heroArchetype,
+  navbar: navbarArchetype,
+  modal: modalArchetype,
+  form: formArchetype,
+  table: tableArchetype,
+  list: listArchetype,
+  badge: badgeArchetype,
+  pricing: pricingArchetype,
+  section: sectionArchetype,
+} as const
+
+export type ArchetypeKey = keyof typeof ARCHETYPES

package/variantkit/schemas/sections.ts

@@ -0,0 +1,151 @@
+// VariantKit section builders — composable chunks of a DialKit config. Each returns a
+// plain config object (a DialKit folder body) covering one design dimension with the
+// controls that dimension actually needs. Archetypes (./archetypes.ts) compose these
+// into full panels so an element's panel feels like its real configuration panel,
+// not 2-3 loose sliders.
+//
+// Pure data — no imports from dialkit/react. Pass current-code values as overrides so
+// the panel opens matching what's rendered:
+//
+//   surface: surfaceSection({ radius: 16, bg: '#0A0A0A' })
+//
+// Drop a control you don't need by destructuring:
+//
+//   const { maxWidth, ...layout } = layoutSection()
+
+export type SelectOption = string | { value: string; label: string }
+export type Select = { type: 'select'; options: SelectOption[]; default?: string }
+export type Color = { type: 'color'; default?: string }
+export type Slider = [number, number, number] | [number, number, number, number]
+export type Spring = { type: 'spring'; visualDuration?: number; bounce?: number; stiffness?: number; damping?: number; mass?: number }
+export type SectionConfig = Record<string, unknown>
+
+export interface SectionOpts {
+  collapsed?: boolean
+}
+
+function section<T extends SectionConfig>(body: T, opts?: SectionOpts): T {
+  return (opts?.collapsed ? { _collapsed: true, ...body } : body) as T
+}
+
+const select = (options: SelectOption[], def?: string): Select => ({ type: 'select', options, default: def })
+const color = (def: string): Color => ({ type: 'color', default: def })
+
+// ---------------------------------------------------------------------------
+// Token resolvers — selects return tokens; variants map them to CSS with these.
+// ---------------------------------------------------------------------------
+
+export const SHADOWS: Record<string, string> = {
+  none: 'none',
+  xs: '0 1px 2px rgba(0,0,0,0.05)',
+  sm: '0 1px 3px rgba(0,0,0,0.08), 0 1px 2px rgba(0,0,0,0.04)',
+  md: '0 4px 12px rgba(0,0,0,0.08), 0 2px 4px rgba(0,0,0,0.04)',
+  lg: '0 12px 32px rgba(0,0,0,0.12), 0 4px 8px rgba(0,0,0,0.05)',
+  xl: '0 24px 56px rgba(0,0,0,0.16), 0 8px 16px rgba(0,0,0,0.06)',
+}
+
+export const FONT_STACKS: Record<string, string> = {
+  system: "system-ui, -apple-system, 'Segoe UI', sans-serif",
+  sans: "'Inter', system-ui, sans-serif",
+  serif: "'Georgia', 'Times New Roman', serif",
+  mono: "'SF Mono', 'JetBrains Mono', monospace",
+}
+
+export const SHADOW_LEVELS = Object.keys(SHADOWS)
+export const FONT_FAMILIES = Object.keys(FONT_STACKS)
+export const WEIGHTS = ['400', '500', '600', '700', '800']
+
+// ---------------------------------------------------------------------------
+// Sections
+// ---------------------------------------------------------------------------
+
+export function layoutSection(
+  d: Partial<{ padding: number; gap: number; align: 'start' | 'center' | 'end'; direction: 'row' | 'column'; maxWidth: number }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      padding: [d.padding ?? 24, 0, 96, 1] as Slider,
+      gap: [d.gap ?? 12, 0, 64, 1] as Slider,
+      align: select(['start', 'center', 'end'], d.align ?? 'start'),
+      direction: select(['column', 'row'], d.direction ?? 'column'),
+      maxWidth: [d.maxWidth ?? 480, 240, 1440, 10] as Slider,
+    },
+    opts,
+  )
+}
+
+export function surfaceSection(
+  d: Partial<{ bg: string; radius: number; borderWidth: number; borderColor: string; shadow: string }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      bg: color(d.bg ?? '#ffffff'),
+      radius: [d.radius ?? 12, 0, 32, 1] as Slider,
+      borderWidth: [d.borderWidth ?? 1, 0, 4, 1] as Slider,
+      borderColor: color(d.borderColor ?? '#e4e4e7'),
+      shadow: select(SHADOW_LEVELS, d.shadow ?? 'sm'),
+    },
+    opts,
+  )
+}
+
+export function typographySection(
+  d: Partial<{ size: number; weight: string; tracking: number; lineHeight: number; family: string }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      size: [d.size ?? 16, 10, 48, 1] as Slider,
+      weight: select(WEIGHTS, d.weight ?? '500'),
+      tracking: [d.tracking ?? 0, -1, 2, 0.05] as Slider,
+      lineHeight: [d.lineHeight ?? 1.4, 1, 2, 0.05] as Slider,
+      family: select(FONT_FAMILIES, d.family ?? 'system'),
+    },
+    opts,
+  )
+}
+
+export function colorSection(
+  d: Partial<{ accent: string; fg: string; bg: string; muted: string }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      accent: color(d.accent ?? '#18181b'),
+      fg: color(d.fg ?? '#18181b'),
+      bg: color(d.bg ?? '#ffffff'),
+      muted: color(d.muted ?? '#71717a'),
+    },
+    opts,
+  )
+}
+
+export function motionSection(
+  d: Partial<{ spring: Spring; hoverScale: number; duration: number }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      spring: d.spring ?? ({ type: 'spring', visualDuration: 0.3, bounce: 0.15 } as Spring),
+      hoverScale: [d.hoverScale ?? 1.02, 1, 1.12, 0.005] as Slider,
+      duration: [d.duration ?? 0.25, 0, 1.5, 0.05] as Slider,
+    },
+    opts,
+  )
+}
+
+export function statesSection(
+  d: Partial<{ hoverBg: string; hoverShadow: string; activeScale: number }> = {},
+  opts?: SectionOpts,
+) {
+  return section(
+    {
+      hoverBg: color(d.hoverBg ?? '#fafafa'),
+      hoverShadow: select(SHADOW_LEVELS, d.hoverShadow ?? 'md'),
+      activeScale: [d.activeScale ?? 0.98, 0.9, 1, 0.005] as Slider,
+    },
+    opts,
+  )
+}

package/variantkit/skill/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: variantkit
+description: AI-assisted UI exploration. When the user asks to build, design, or change any user-facing UI (a component, screen, section, state, hero, card, layout, or visual treatment), generate 2-4 structural variants instead of one and wire them to a live, FULL configuration panel so they can switch, tweak everything, finalize, and have the losers pruned to one clean component. Also wraps existing components in their own configuration panel on "paramify" / "let me tweak this" / "give me controls", applies pending decisions on "apply decision", and handles "deslop" / "remove the AI slop" requests. Triggers on building/redesigning UI, "give me options/takes/variants", "explore directions", "paramify", "let me tweak", "give me controls", "apply decision", "deslop", "this looks AI-generated".
+---
+
+# VariantKit
+
+Make UI exploration cheap and structured: generate several variants the user judges live,
+then prune to the winner. This skill is self-contained — you can scaffold and prune from it
+alone. If the project has an `AGENT.md` with a VariantKit section, that is authoritative; read
+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".
+
+## Step 1 — make sure the project is set up
+
+Check for `dialkit` in the project's deps and a `buildDecision.ts` (usually `src/variantkit/`).
+If missing, set it up from the project root:
+
+```sh
+npx variantkit
+```
+
+That installs `dialkit motion` + the runtime (`buildDecision`, `configs`, `react` Studio
+helper, `dialkit-clean.css`, `dialkit-dark.css`, `motion.css`), `AGENT.md`, and a rules pointer.
+Ensure the panel host + stylesheets are set up once in the app root (DialRoot is a sibling,
+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-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
+```
+
+The installer also wires the decision transport (vite plugin / Next API route), mounts
+`<DialRoot/>` + `<VariantBar/>` (tabs, keys 1..9, live Compare grid, Finalize) and the
+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.
+
+## The rules that make this work (never violate)
+
+**VariantKit presents; the project decides.**
+- **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, or "house style"; never introduce one.
+- **Controls come from the element.** Author the controls that genuinely matter for tweaking
+  THIS element — its real design axes. Any number, any kind of control; there is no standard
+  set. Never reuse a control set across unrelated elements.
+- **Defaults come from the code.** Every control default is the element's current/intended
+  value from the project (tokens, existing styles) — never an invented literal.
+- **The rendered element stays untouched.** No rings, badges, overlays, or layout imposed on
+  the project's UI — the user judges the element exactly as it ships. All feedback lives in
+  the panel.
+
+If you cannot run the installer (offline), you can still scaffold using the recipe below; add
+`dialkit motion` to deps and copy `buildDecision.ts` from the variantkit repo when possible.
+
+## 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`.
+
+## Step 2 — scaffold a variant set
+
+**Easiest path — the `Studio` helper.** For one OR many elements, prefer it over hand-wiring;
+it gives one panel, a folder per element, finalize routing, and focus-on-hover:
+
+```tsx
+import { Studio, type ElementDef } from './variantkit/react'
+
+const ELEMENTS: ElementDef[] = [
+  {
+    name: 'PricingCard',
+    keys: ['slab', 'ledger', 'inverse'],
+    // Authored for THIS element, defaults from THIS project's tokens — not a fixed menu.
+    controls: {
+      density: { type: 'select', options: ['compact', 'comfortable'], default: 'comfortable' },
+      accent: tokens.brand,
+      showAnnualToggle: true,
+    },
+    render: (variant, v) => <Card variant={variant} {...v} />,
+  },
+  // add more elements here; each gets its own folder + its own authored controls
+]
+<Studio elements={ELEMENTS} focusOnHover />
+```
+
+`controls` is whatever fits the element — any DialKit control: number `[default,min,max]` →
+slider, string → text, `#hex` → color, boolean → segmented toggle, `select` → dropdown,
+`spring`/`transition` → motion editor (only for elements that move), nested object → folder
+group. Ask "which axes of this element would the developer tweak before committing?" and
+expose exactly those. For a single element, pass one entry; with one variant key no dropdown
+is shown. `focusOnHover` expands the hovered element's folder — panel-side only, nothing is
+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`.
+
+### Manual wiring (if not using the helper)
+
+File-per-variant. Only `index.tsx` wires the tool; each variant is a plain, self-contained
+component. This is what makes the later prune reliable (delete files + one rename).
+
+```
+ComponentName/
+  index.tsx          # the ONLY file importing dialkit / registry / buildDecision
+  registry.ts        # { key: { component, label } }
+  variants/
+    <a>.tsx          # 2-4 self-contained components, same props, same morph transition
+    <b>.tsx
+    <c>.tsx
+```
+
+`index.tsx` — variant = a DialKit `select`, your authored controls, finalize = an `action`.
+(Control names/defaults below are placeholders — derive yours from the element + the
+project's tokens.)
+
+```tsx
+import { useDialKit } from 'dialkit'
+import { registry } from './registry'
+import { buildDecision, submitDecision, type ParamValue } from '../../core/buildDecision'
+
+// Defaults = the project's real values (tokens / current styles), never invented literals.
+const DEFAULTS: Record<string, ParamValue> = { density: 'comfortable', accent: tokens.brand }
+
+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
+    density: { type: 'select', options: ['compact', 'comfortable'], default: DEFAULTS.density },
+    accent: DEFAULTS.accent as string,
+    finalize: { type: 'action', label: 'Finalize' },
+  }, {
+    onAction: () => submitDecision(buildDecision('ComponentName', v as Record<string, ParamValue>, DEFAULTS, registry)),
+  }) as Record<string, ParamValue>
+
+  const Active = registry[String(v.variant)].component
+  return <Active {...props} density={String(v.density)} accent={v.accent as string} />
+}
+```
+
+Each variant declares the **same** transition (a local const, duplicated on purpose so it
+stays self-contained), so switching morphs rather than snaps:
+
+```ts
+const morph = { transition: 'border-radius .25s ease, background-color .25s ease, box-shadow .25s ease, padding .25s ease' }
+```
+
+Every variant must pass the deslop checklist below — generated UI must not look AI-generated.
+
+## Step 3 — finalize → prune
+
+Finalize ships a `decision.json` (schema 2, dot-path values): `{ schema, component,
+finalized, values, overridesFromDefault, prune[], note, status, timestamp }` — through the
+dev transport into `.variantkit/decisions/<Component>.json`, or to the clipboard when no
+transport is running. On "apply decision" (or at session start) scan
+`.variantkit/decisions/*.json` for `status: "pending"`; a pasted decision applies the same
+way. Prune (mechanical — never move JSX between files):
+
+1. Inline `values` (as literals) into the winner file `variants/<finalized>.tsx`.
+2. Rename that file to `index.tsx`, overwriting the shell. Do NOT copy code by hand.
+3. Delete every loser in `prune` + leftover `variants/*`; delete `registry.ts`.
+4. Remove the DialKit wiring. If this was the last variant set, also drop `<DialRoot/>`.
+5. Resolve: append the decision (status "resolved") to `.variantkit/history/log.jsonl`,
+   delete the pending decision file.
+
+## Paramify an existing component (no variants)
+
+On "paramify this" / "let me tweak this" / "give me controls for this": wrap the EXISTING
+component in its full configuration per AGENT.md §7 — adapted archetype + finalize action,
+props fed from panel values; no registry, no variants/. On finalize: inline the chosen
+values as literals and strip the wiring completely.
+
+## Taste memory
+
+Before scaffolding, read `.variantkit/TASTE.md` if present — seed defaults toward the
+observed preferences, plus one variant that deliberately breaks the pattern. After
+resolving, if `.variantkit/history/log.jsonl` has ≥3 entries, distill/update `TASTE.md`
+per AGENT.md §8 — grounded claims only, every bullet cites ≥2 decisions with real values.
+
+Self-check (all must hold): no file imports `dialkit` / `registry` / `buildDecision`;
+`variants/` and `registry.ts` gone; `index.tsx` renders the winner with values inlined; the
+visible output matches the chosen variant.
+
+## Deslop — applies to generated UI, never the DialKit panel
+
+Slop is decoration without a system: a tell is slop as a one-off, fine as a consistent,
+repeated system. Default to keep when unsure; subtract, never add. On "deslop" / "this looks
+AI-generated", run a pass: scope → scan → judge each → remove only slop → verify in browser →
+report a table. Catalog:
+
+1. Random italics on headings/labels → remove; use weight/size for emphasis.
+2. Random mono font for "tech feel" → revert to UI font; numbers use `tabular-nums`.
+3. All-caps + wide-tracking "eyebrow" kickers → delete, or keep at most one system-wide.
+4. Decorative accent/divider stub lines → remove; keep only full structural rules.
+5. Ornamental colored/pulsing dots → remove; keep dots that encode real state.
+6. Unmotivated warm accents (amber/orange/rose) → map to real tokens; reserve for semantics.
+7. Decorative single letters/monograms standing for nothing → remove.
+8. Oversized radii (≥20px) → 8-12px, concentric (inner = outer − padding).
+9. One-sided / gradient highlight borders for flair → uniform 1px or none.
+10. Em dashes in copy → commas, colons, or separate sentences.
+11. Emoji in product UI → remove.

package/variantkit/templates/next-pages-api.ts

@@ -0,0 +1,33 @@
+// VariantKit decision transport for Next.js (Pages Router) — dev-only. Installed by
+// `variantkit init` at pages/api/__variantkit/decision.ts. Returns 404 outside development.
+
+import { mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { NextApiRequest, NextApiResponse } from 'next'
+
+const NAME_OK = /^[A-Za-z0-9_-]+$/
+
+export default function handler(req: NextApiRequest, res: NextApiResponse): void {
+  if (process.env.NODE_ENV !== 'development') {
+    res.status(404).end('not found')
+    return
+  }
+  if (req.method !== 'POST') {
+    res.status(405).end('method not allowed')
+    return
+  }
+  const decision = req.body
+  const component = String(decision?.component ?? '')
+  if (!NAME_OK.test(component)) {
+    res.status(400).end('invalid component name')
+    return
+  }
+  const dir = join(process.cwd(), '.variantkit', 'decisions')
+  const historyDir = join(process.cwd(), '.variantkit', 'history')
+  mkdirSync(dir, { recursive: true })
+  mkdirSync(historyDir, { recursive: true })
+  writeFileSync(join(dir, `${component}.json`), JSON.stringify(decision, null, 2) + '\n')
+  appendFileSync(join(historyDir, 'log.jsonl'), JSON.stringify(decision) + '\n')
+  console.log(`[variantkit] decision saved: .variantkit/decisions/${component}.json`)
+  res.status(200).json({ ok: true })
+}

package/variantkit/templates/next-route.ts

@@ -0,0 +1,33 @@
+// VariantKit decision transport for Next.js (App Router) — dev-only. The panel's
+// finalize button POSTs here; the decision lands in .variantkit/decisions/ and the
+// agent applies it per AGENT.md §4. Installed by `variantkit init` at
+// app/api/__variantkit/decision/route.ts. Returns 404 outside development.
+
+import { mkdirSync, writeFileSync, appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const NAME_OK = /^[A-Za-z0-9_-]+$/
+
+export async function POST(req: Request): Promise<Response> {
+  if (process.env.NODE_ENV !== 'development') {
+    return new Response('not found', { status: 404 })
+  }
+  let decision: { component?: unknown }
+  try {
+    decision = await req.json()
+  } catch {
+    return new Response('bad decision payload', { status: 400 })
+  }
+  const component = String(decision.component ?? '')
+  if (!NAME_OK.test(component)) {
+    return new Response('invalid component name', { status: 400 })
+  }
+  const dir = join(process.cwd(), '.variantkit', 'decisions')
+  const historyDir = join(process.cwd(), '.variantkit', 'history')
+  mkdirSync(dir, { recursive: true })
+  mkdirSync(historyDir, { recursive: true })
+  writeFileSync(join(dir, `${component}.json`), JSON.stringify(decision, null, 2) + '\n')
+  appendFileSync(join(historyDir, 'log.jsonl'), JSON.stringify(decision) + '\n')
+  console.log(`[variantkit] decision saved: .variantkit/decisions/${component}.json`)
+  return Response.json({ ok: true })
+}

package/variantkit/vite-plugin.d.mts

@@ -0,0 +1,8 @@
+// Types for vite-plugin.mjs — keeps strict vite.config.ts type-checks green without
+// depending on vite's own types being installed.
+declare function variantkit(): {
+  name: string
+  apply: 'serve'
+  configureServer(server: unknown): void
+}
+export default variantkit