variantkit 0.1.0

package/variantkit/README.md

@@ -0,0 +1,32 @@
+# variantkit/ — what gets installed
+
+This directory is the distributable. `init.mjs` copies the runtime into a target project
+and wires everything; see the [repo README](../README.md) for positioning and
+[docs/quickstart.md](../docs/quickstart.md) for usage.
+
+```sh
+npx variantkit [init|doctor|remove] [targetDir] [flags]
+```
+
+- `buildDecision.ts` — pure core: dot-path flatten (schema 2), override diff (taste
+  signal), prune list, `submitDecision` (dev transport, "✓ Saved") with clipboard fallback
+  ("✓ Copied"), `defaultsFromConfig`
+- `configs.ts` — panel assembly helpers (`panelConfig`, `defaultsOf`, `regOf`); VariantKit
+  adds only the variant select + finalize around YOUR controls
+- `schemas/sections.ts` — composable control sections + token resolvers (SHADOWS, FONT_STACKS)
+- `schemas/archetypes.ts` — 11 per-element checklists of design axes (see
+  [docs/archetypes.md](../docs/archetypes.md)) — adapt + seed, never paste
+- `react.tsx` — `Studio` (N elements → one panel, folder each, finalize routing,
+  focus-on-hover) + `useDialkitTheme` (panel dark mode with header toggle)
+- `react/VariantBar.tsx` — bottom bar: variant tabs, keys 1-9, Compare, Finalize;
+  auto-discovers sets (shell or Studio layout) from DialKit's documented store
+- `react/VariantStage.tsx` — live side-by-side compare grid for the classic shell
+- `dialkit-clean.css` / `dialkit-dark.css` / `motion.css` — panel chrome polish (hide
+  redundant copy button, dark palette, micro-motion; never touches project UI)
+- `patches/dialkit+1.2.0.patch` — delightful panel minimize/expand morph (patch-package)
+- `vite-plugin.mjs` (+ `.d.mts`) — dev-only decision transport for Vite
+- `templates/` — Next.js App/Pages Router transport routes
+- `skill/SKILL.md` — global Claude Code skill (installed to `~/.claude/skills/variantkit`)
+- `../AGENT.md` — the agent contract: scaffold convention, authoring rules, decision
+  schema 2, prune + self-check, §7 completeness bar, §6 deslop, §8 taste memory
+- `../NAMING.md` — the vocabulary (one word per concept)

package/variantkit/buildDecision.ts

@@ -0,0 +1,264 @@
+// VariantKit core — pure, no React imports. Builds the finalize decision (winner +
+// override diff + prune list) and ships it to your agent so it can prune the variant
+// set down to the winner. See AGENT.md for the contract.
+//
+//   live values (nested folders ok) + defaults
+//            │
+//            ▼
+//   buildDecision ── finalized (winner key)
+//                ├── values (dot-path flattened final params to inline)
+//                ├── overridesFromDefault (only-changed; the taste signal)
+//                └── prune (every registry key except the winner)
+//
+// Decision schema 2: values/overrides are dot-path flattened ("surface.radius": 12)
+// so folder-grouped configurations produce flat, inlineable decisions.
+
+export type ParamValue = number | string | boolean
+
+// A control-output object (spring, easing) — carries a string `type` and is treated
+// as a single leaf value. Plain objects WITHOUT `type` are folders and get flattened.
+export interface ControlObject {
+  type: string
+  [key: string]: unknown
+}
+
+export type LeafValue = ParamValue | ControlObject
+// Loose on purpose: accepts both resolved DialKit values and raw config objects
+// (defaultsFromConfig walks configs, which contain slider tuples, selects, actions).
+export type NestedValues = Record<string, unknown>
+
+export interface Override {
+  from: LeafValue
+  to: LeafValue
+}
+
+export interface Decision {
+  schema: 2
+  component: string
+  finalized: string
+  values: Record<string, LeafValue>
+  overridesFromDefault: Record<string, Override>
+  prune: string[]
+  note: string
+  status: 'pending'
+  timestamp: string
+}
+
+// Keys present in the DialKit values object that are NOT design params.
+const RESERVED = new Set(['variant', 'finalize'])
+
+const HEX = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+
+function normalizeHex(s: string): string {
+  let h = s.toLowerCase()
+  if (h.length === 4) h = '#' + h[1] + h[1] + h[2] + h[2] + h[3] + h[3]
+  return h
+}
+
+function isControlObject(v: unknown): v is ControlObject {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) && typeof (v as ControlObject).type === 'string'
+}
+
+function isFolder(v: unknown): v is NestedValues {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) && !isControlObject(v)
+}
+
+// Equality that treats #FFF and #ffffff as the same color. Control objects (spring,
+// easing) compare on the keys present in `a` (the default) so library-filled extras
+// in the live value don't read as user overrides. Everything else strict.
+export function valuesEqual(a: LeafValue, b: LeafValue): boolean {
+  if (typeof a === 'string' && typeof b === 'string' && HEX.test(a) && HEX.test(b)) {
+    return normalizeHex(a) === normalizeHex(b)
+  }
+  if (isControlObject(a) && isControlObject(b)) {
+    for (const k of Object.keys(a)) {
+      if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) return false
+    }
+    return true
+  }
+  return a === b
+}
+
+// Flatten nested folder values to dot-paths. Skips reserved keys (variant/finalize at
+// any depth — folder-per-element configs nest them), config-only keys (_collapsed),
+// and DialKit internals (__mode).
+export function flattenValues(nested: NestedValues, prefix = ''): Record<string, LeafValue> {
+  const out: Record<string, LeafValue> = {}
+  for (const k of Object.keys(nested)) {
+    if (k.startsWith('_')) continue
+    if (k.endsWith('__mode')) continue
+    if (RESERVED.has(k)) continue
+    const v = nested[k]
+    if (v === undefined) continue
+    const path = prefix ? `${prefix}.${k}` : k
+    if (isFolder(v)) {
+      Object.assign(out, flattenValues(v as NestedValues, path))
+    } else {
+      out[path] = v as LeafValue
+    }
+  }
+  return out
+}
+
+// Derive the frozen defaults from a DialKit config object — the reference the
+// override diff is measured against. Walks folders; one default per control:
+//   number/string/boolean -> itself      [def, min, max, step?] -> def
+//   select -> default ?? first option    color/text -> default
+//   spring/easing -> the config object   action -> skipped (no value)
+export function defaultsFromConfig(config: NestedValues): NestedValues {
+  const out: NestedValues = {}
+  for (const k of Object.keys(config)) {
+    if (k.startsWith('_')) continue
+    if (RESERVED.has(k)) continue
+    const v = config[k]
+    if (v === undefined) continue
+    if (typeof v === 'number' || typeof v === 'string' || typeof v === 'boolean') {
+      out[k] = v
+    } else if (Array.isArray(v)) {
+      out[k] = v[0] as ParamValue
+    } else if (isControlObject(v)) {
+      if (v.type === 'action') continue
+      if (v.type === 'select') {
+        const opts = (v as { options?: unknown[] }).options ?? []
+        const first = opts[0]
+        const firstValue = typeof first === 'object' && first !== null ? (first as { value: string }).value : (first as string)
+        out[k] = ((v as { default?: string }).default ?? firstValue) as ParamValue
+      } else if (v.type === 'color' || v.type === 'text') {
+        out[k] = ((v as { default?: string }).default ?? '') as ParamValue
+      } else {
+        out[k] = v // spring / easing / unknown control: the object IS the default
+      }
+    } else if (isFolder(v)) {
+      out[k] = defaultsFromConfig(v as NestedValues)
+    }
+  }
+  return out
+}
+
+export function buildDecision(
+  component: string,
+  liveValues: NestedValues,
+  defaults: NestedValues,
+  registry: Record<string, unknown>,
+  opts?: { now?: string; note?: string },
+): Decision {
+  // No `variant` in the live values means a single-variant set (no dropdown was rendered):
+  // the winner is the registry's only key.
+  const finalized = liveValues.variant !== undefined ? String(liveValues.variant) : (Object.keys(registry)[0] ?? '')
+
+  const values = flattenValues(liveValues)
+  const flatDefaults = flattenValues(defaults)
+
+  const overridesFromDefault: Record<string, Override> = {}
+  for (const k of Object.keys(values)) {
+    if (!(k in flatDefaults)) continue
+    if (!valuesEqual(flatDefaults[k], values[k])) {
+      overridesFromDefault[k] = { from: flatDefaults[k], to: values[k] }
+    }
+  }
+
+  const prune = Object.keys(registry).filter((k) => k !== finalized)
+
+  return {
+    schema: 2,
+    component,
+    finalized,
+    values,
+    overridesFromDefault,
+    prune,
+    note: opts?.note ?? '',
+    status: 'pending',
+    timestamp: opts?.now ?? new Date().toISOString(),
+  }
+}
+
+// Briefly morph the element's Finalize button (e.g. to "✓ Copied"), in the PANEL only —
+// never an overlay on the app UI. Runs from copyDecision/submitDecision so EVERY finalize
+// gets feedback, however it was wired. DialKit renders an action as
+// `<button class="dialkit-button">Finalize X</button>` and does not re-render on an action
+// (no value changed), so a direct text swap sticks until we revert it.
+function flashFinalized(component: string, text: string): void {
+  if (typeof document === 'undefined') return
+  const buttons = Array.from(document.querySelectorAll<HTMLButtonElement>('.dialkit-root .dialkit-button'))
+  // Prefer the exact "Finalize <component>" button; fall back to the sole action button.
+  let btn = buttons.find((b) => b.textContent?.trim() === `Finalize ${component}`)
+  if (!btn && buttons.length === 1) btn = buttons[0]
+  if (!btn || btn.dataset.vkFlashing) return
+  const original = btn.textContent ?? ''
+  btn.dataset.vkFlashing = '1'
+  btn.textContent = text
+  setTimeout(() => {
+    if (btn!.dataset.vkFlashing) {
+      btn!.textContent = original
+      delete btn!.dataset.vkFlashing
+    }
+  }, 1500)
+}
+
+// Ship the decision to the dev server (vite plugin / Next route) so it lands in
+// .variantkit/decisions/ and the agent can apply it with zero copy-paste. Falls back to
+// the clipboard when no transport is running. NEVER fails silently.
+const TRANSPORT_ENDPOINTS = ['/__variantkit/decision', '/api/__variantkit/decision']
+
+export async function submitDecision(decision: Decision): Promise<void> {
+  if (typeof fetch !== 'undefined') {
+    for (const endpoint of TRANSPORT_ENDPOINTS) {
+      try {
+        const res = await fetch(endpoint, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(decision),
+        })
+        if (res.ok) {
+          flashFinalized(decision.component, '✓  Saved')
+          console.info(`[variantkit] decision saved to .variantkit/decisions/${decision.component}.json — tell your agent: "apply decision".`)
+          return
+        }
+      } catch {
+        // endpoint not running — try the next, then the clipboard
+      }
+    }
+  }
+  await copyDecision(decision)
+}
+
+// Copy the decision JSON to the clipboard. NEVER fail silently: if the Clipboard API is
+// unavailable (insecure context, old webview), fall back to execCommand, then to a log.
+// Also flashes the Finalize button to "✓ Copied" (panel-side feedback, no toast/overlay).
+export async function copyDecision(decision: Decision): Promise<void> {
+  flashFinalized(decision.component, '✓  Copied')
+  const json = JSON.stringify(decision, null, 2)
+  try {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(json)
+      console.info('[variantkit] decision copied. Paste it to your agent to prune.')
+      return
+    }
+    throw new Error('clipboard API unavailable')
+  } catch {
+    fallbackCopy(json)
+  }
+}
+
+function fallbackCopy(json: string): void {
+  if (typeof document === 'undefined') {
+    console.warn('[variantkit] no clipboard + no DOM. Decision:\n' + json)
+    return
+  }
+  const ta = document.createElement('textarea')
+  ta.value = json
+  ta.style.position = 'fixed'
+  ta.style.opacity = '0'
+  document.body.appendChild(ta)
+  ta.focus()
+  ta.select()
+  let ok = false
+  try {
+    ok = document.execCommand('copy')
+  } catch {
+    ok = false
+  }
+  document.body.removeChild(ta)
+  if (ok) console.info('[variantkit] decision copied via fallback. Paste it to your agent.')
+  else console.warn('[variantkit] could not copy automatically. Decision:\n' + json)
+}

package/variantkit/configs.ts

@@ -0,0 +1,70 @@
+// VariantKit — panel assembly helpers. VariantKit does NOT decide what the controls are.
+//
+// The agent building the project authors the controls per element — contextual, specific,
+// derived from that element's actual design axes and the project's design system. Any control
+// DialKit supports is fair game: slider, select, toggle (boolean), color, text, spring /
+// transition, nested folder groups. There is no preset menu and no VariantKit default value:
+// every default comes from the project (its tokens, or the element's current values).
+//
+// VariantKit's only additions are structural:
+//   - a `variant` select (only when there are 2+ variants)
+//   - a `finalize` action
+//
+// Usage in a component's index.tsx (built on DialKit):
+//   const cfg = panelConfig(
+//     { tone: { type: 'select', options: ['quiet','bold'], default: 'quiet' },  // yours,
+//       accent: tokens.brand, compact: false },                                  // per element
+//     ['solid', 'outline', 'ghost'],
+//     { component: 'Button' },
+//   )
+//   const v = useDialKit('Button', cfg, { onAction: () =>
+//     copyDecision(buildDecision('Button', v, defaultsOf(cfg), regOf(['solid','outline','ghost']))) })
+
+// Loose config shape — these are DialKit config objects; we don't import DialKit's types here
+// so the helpers stay framework-light. `any` keeps the result assignable to DialKit's own
+// config type at the useDialKit call site without coupling this file to DialKit.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Control = any
+export type PanelConfig = Record<string, Control>
+
+const RESERVED = new Set(['variant', 'finalize'])
+
+// Assemble the full DialKit config for a variant set: [variant select +] the element's own
+// controls + a finalize action. With a single variant key, no dropdown is added — the panel
+// is just the element's controls + finalize.
+export function panelConfig(
+  controls: PanelConfig,
+  variantKeys: string[],
+  opts?: { finalizeLabel?: string; component?: string },
+): PanelConfig {
+  return {
+    ...(variantKeys.length > 1
+      ? { variant: { type: 'select', options: variantKeys, default: variantKeys[0] } }
+      : {}),
+    ...controls,
+    finalize: { type: 'action', label: opts?.finalizeLabel ?? `Finalize ${opts?.component ?? ''}`.trim() },
+  }
+}
+
+// Resolve the frozen default value of each control — feeds buildDecision's `defaults`.
+export function defaultsOf(cfg: PanelConfig): Record<string, number | string | boolean> {
+  const out: Record<string, number | string | boolean> = {}
+  for (const [key, c] of Object.entries(cfg)) {
+    if (RESERVED.has(key)) continue
+    if (typeof c === 'number' || typeof c === 'string' || typeof c === 'boolean') {
+      out[key] = c
+    } else if (Array.isArray(c)) {
+      out[key] = c[0] as number
+    } else if (c && typeof c === 'object') {
+      const o = c as { type?: string; default?: unknown }
+      if (o.type === 'action') continue
+      if (o.default !== undefined) out[key] = o.default as number | string | boolean
+    }
+  }
+  return out
+}
+
+// Convenience: registry object from variant keys, for buildDecision's prune computation.
+export function regOf(variantKeys: string[]): Record<string, true> {
+  return Object.fromEntries(variantKeys.map((k) => [k, true]))
+}

package/variantkit/dialkit-clean.css

@@ -0,0 +1,46 @@
+/* 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".
+   - Remove folder/header dividers so the panel reads on spacing alone, like DialKit's own UI. */
+.dialkit-root [title='Copy parameters'] {
+  display: none !important;
+}
+
+/* DialKit ships the expanded panel with zero bottom padding (10px 12px 0 12px), so the last
+   control — usually Finalize — sits flush against the edge. Match the sides. The collapsed
+   bubble sets its own uniform 12px, so this only affects the open panel. */
+.dialkit-root .dialkit-panel-inner:not([data-collapsed='true']) {
+  padding-bottom: 12px;
+}
+.dialkit-root .dialkit-panel-header {
+  border-bottom: none !important;
+}
+.dialkit-root .dialkit-folder {
+  border-top: none !important;
+  border-bottom: none !important;
+}
+
+/* The injected panel theme toggle — placed just left of DialKit's settings icon (right:12). */
+.dialkit-root .vk-theme-toggle {
+  position: absolute;
+  top: 6px;
+  right: 40px;
+  width: 26px;
+  height: 26px;
+  display: inline-grid;
+  place-items: center;
+  border: none;
+  background: transparent;
+  border-radius: 7px;
+  cursor: pointer;
+  color: var(--dial-text-secondary);
+  z-index: 2;
+  transition: background-color 140ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+.dialkit-root .vk-theme-toggle:hover {
+  background: var(--dial-surface-hover);
+}
+.dialkit-root .vk-theme-toggle:active {
+  transform: scale(0.92);
+}

package/variantkit/dialkit-dark.css

@@ -0,0 +1,27 @@
+/* Dark theme for DialKit's panel — cool, near-black, crisp (matches DialKit's own dark mode).
+   DialKit ships a light palette only and reads CSS vars on .dialkit-root[data-theme]; this
+   supplies the dark set. Set data-theme="dark" on .dialkit-root to activate. */
+.dialkit-root[data-theme='dark'] {
+  --dial-glass-bg: #0c0c0d;
+  --dial-dropdown-bg: #1b1b1e;
+
+  --dial-surface: rgba(255, 255, 255, 0.055);
+  --dial-surface-hover: rgba(255, 255, 255, 0.09);
+  --dial-surface-active: rgba(255, 255, 255, 0.14);
+  --dial-surface-subtle: rgba(255, 255, 255, 0.04);
+
+  --dial-text-root: #fafafa;
+  --dial-text-section: rgba(255, 255, 255, 0.92);
+  --dial-text-label: rgba(255, 255, 255, 0.62);
+  --dial-text-focus: #ffffff;
+  --dial-text-primary: rgba(255, 255, 255, 0.95);
+  --dial-text-secondary: rgba(255, 255, 255, 0.55);
+  --dial-text-tertiary: rgba(255, 255, 255, 0.34);
+
+  --dial-border: rgba(255, 255, 255, 0.08);
+  --dial-border-hover: rgba(255, 255, 255, 0.16);
+
+  --dial-shadow: 0 16px 50px rgba(0, 0, 0, 0.6);
+  --dial-shadow-collapsed: 0 4px 16px rgba(0, 0, 0, 0.5);
+  --dial-shadow-dropdown: 0 12px 32px rgba(0, 0, 0, 0.55);
+}