From 66bbb0b3c72c8e4fe732d0baef84cb0e00329104 Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Fri, 3 Jul 2026 17:57:52 -0700
Subject: [PATCH 1/5] fix: real default border color + dither-kit theme toggle

- Tailwind v4 has no --default-border-color mechanism; the bare border
  utility fell back to currentColor (white on dark). Base layer rule now
  points default borders at the border token.
- /dither-kit gets its theme toggle back: page-scoped .dither-light token
  overrides + a dark wrapper class for dark: variants, persisted in
  localStorage. The app itself stays dark-only.
---
 apps/web/src/routes/dither-kit.tsx | 37 ++++++++++++++++++++++++++++--
 apps/web/src/styles.css            | 35 +++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/routes/dither-kit.tsx b/apps/web/src/routes/dither-kit.tsx
index b2aaa3e..e2ae4d9 100644
--- a/apps/web/src/routes/dither-kit.tsx
+++ b/apps/web/src/routes/dither-kit.tsx
@@ -2,8 +2,10 @@ import { createFileRoute } from "@tanstack/react-router"
 import {
   CheckIcon,
   CopyIcon,
+  MoonIcon,
   RefreshCcwIcon,
   SlidersHorizontalIcon,
+  SunIcon,
   XIcon,
 } from "lucide-react"
 import { Fragment, type ReactNode, useEffect, useRef, useState } from "react"
@@ -177,6 +179,24 @@ function useSettled(value: string | number, ms: number, onSettle: () => void) {
   }, [value, ms])
 }
 
+/** Page-scoped theme. The app is dark-only, so instead of a global theme the
+ * page swaps the `.dither-light` token overrides (and the `dark` class that
+ * drives `dark:` variants) on its own wrapper. Persisted per visitor. */
+function usePageTheme() {
+  const [light, setLight] = useState(
+    () =>
+      typeof window !== "undefined" &&
+      window.localStorage.getItem("dither-kit-theme") === "light"
+  )
+  const toggle = () => {
+    setLight((v) => {
+      window.localStorage.setItem("dither-kit-theme", v ? "dark" : "light")
+      return !v
+    })
+  }
+  return { light, toggle }
+}
+
 function useCopy() {
   const [copied, setCopied] = useState(false)
   const copy = (text: string) => {
@@ -658,6 +678,7 @@ function Showcase({
 /* ------------------------------------------------------------------ page */
 
 function DitherKitDocs() {
+  const { light, toggle: toggleTheme } = usePageTheme()
   const [tweaks, setTweaks] = useState<Tweaks>(DEFAULT_TWEAKS)
   const [panelOpen, setPanelOpen] = useState(false)
   const [pm, setPm] = useState<Pm>("npm")
@@ -694,8 +715,8 @@ function DitherKitDocs() {
     // stay in view while you turn the knobs.
     <div
       className={`min-h-screen bg-background text-foreground transition-[padding] duration-200 ${
-        panelOpen ? "lg:pr-80" : ""
-      }`}
+        light ? "dither-light" : "dark"
+      } ${panelOpen ? "lg:pr-80" : ""}`}
     >
       <DitherStrip className="h-2 w-full" />
 
@@ -711,6 +732,18 @@ function DitherKitDocs() {
                 five chart types on one tiny canvas engine, no recharts
               </p>
             </div>
+            <button
+              type="button"
+              aria-label="Toggle theme"
+              onClick={toggleTheme}
+              className="rounded-md border p-2 text-muted-foreground transition-colors hover:border-foreground/25 hover:text-foreground"
+            >
+              {light ? (
+                <MoonIcon className="size-4" />
+              ) : (
+                <SunIcon className="size-4" />
+              )}
+            </button>
           </div>
 
           <p className="max-w-2xl leading-relaxed text-balance text-muted-foreground">
diff --git a/apps/web/src/styles.css b/apps/web/src/styles.css
index f63c8fc..f583f12 100644
--- a/apps/web/src/styles.css
+++ b/apps/web/src/styles.css
@@ -27,9 +27,6 @@
   --font-sans: "Geist", system-ui, sans-serif;
   --font-display: "Playfair Display", Georgia, serif;
 
-  /* Default border color for Tailwind's `border` utility */
-  --default-border-color: #27272a;
-
   /* Tripwire color palette (from prototype) */
   --color-tw-bg: #0d0d0f;
   --color-tw-surface: #17171a;
@@ -92,6 +89,38 @@
   --font-pixel-geist: "Geist Pixel", ui-monospace, monospace;
 }
 
+/* Default border color for Tailwind's `border` utility. v4 defaults to
+   currentColor (which reads as white on our dark theme); pointing it at the
+   border token restores the intended hairlines everywhere. */
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-border);
+  }
+}
+
+/* Light palette for the dither-kit docs page. The app itself is dark-only, so
+   the page's theme toggle swaps these shadcn-alias tokens on its own wrapper
+   instead of a global theme. */
+.dither-light {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.141 0.005 285.823);
+  --color-card: oklch(0.985 0 0);
+  --color-card-foreground: oklch(0.141 0.005 285.823);
+  --color-popover: oklch(1 0 0);
+  --color-popover-foreground: oklch(0.141 0.005 285.823);
+  --color-border: oklch(0.92 0.004 286.32);
+  --color-muted: oklch(0.967 0.001 286.375);
+  --color-muted-foreground: oklch(0.552 0.016 285.938);
+  --color-primary: oklch(0.21 0.006 285.885);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --color-accent: oklch(0.967 0.001 286.375);
+  --color-accent-foreground: oklch(0.21 0.006 285.885);
+}
+
 body {
   @apply m-0 bg-tw-bg text-tw-text-primary antialiased;
   font-family: "Geist", system-ui, sans-serif;

From 84b88fa3f777594d73f1f265f9cdef033b8165b2 Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Fri, 3 Jul 2026 18:04:20 -0700
Subject: [PATCH 2/5] feat: swap the dither-kit tweak panel for DialKit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hand-rolled sidebar (Field/Select/Range/TweakSidebar) is replaced by
DialKit's floating control panel (https://joshpuckett.me/dialkit) —
bloom folder (preset + custom sliders), per-series variant selects,
stacking toggle, pie radius + entrance sliders, and a replay-all action.
productionEnabled so visitors on tripwire.sh get the panel too; the
settle-replay behavior is unchanged (any tweak replays after 300ms).
---
 apps/web/package.json              |   1 +
 apps/web/src/routes/dither-kit.tsx | 348 +++++------------------------
 pnpm-lock.yaml                     |  37 ++-
 3 files changed, 99 insertions(+), 287 deletions(-)

diff --git a/apps/web/package.json b/apps/web/package.json
index aa8e4eb..ac805cb 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -72,6 +72,7 @@
     "clsx": "^2.1.1",
     "d3-scale": "^4.0.2",
     "d3-shape": "^3.2.0",
+    "dialkit": "^1.3.0",
     "drizzle-kit": "^0.31.9",
     "drizzle-orm": "^0.45.1",
     "evlog": "^2.17.0",
diff --git a/apps/web/src/routes/dither-kit.tsx b/apps/web/src/routes/dither-kit.tsx
index e2ae4d9..46f9dce 100644
--- a/apps/web/src/routes/dither-kit.tsx
+++ b/apps/web/src/routes/dither-kit.tsx
@@ -1,12 +1,12 @@
 import { createFileRoute } from "@tanstack/react-router"
+import { DialRoot, useDialKit } from "dialkit"
+import "dialkit/styles.css"
 import {
   CheckIcon,
   CopyIcon,
   MoonIcon,
   RefreshCcwIcon,
-  SlidersHorizontalIcon,
   SunIcon,
-  XIcon,
 } from "lucide-react"
 import { Fragment, type ReactNode, useEffect, useRef, useState } from "react"
 import {
@@ -108,19 +108,6 @@ type Tweaks = {
   duration: number // entrance ms
 }
 
-const DEFAULT_TWEAKS: Tweaks = {
-  bloomPreset: "aura",
-  blur: 24,
-  brightness: 2.9,
-  opacity: 0.1,
-  saturate: 3,
-  primaryVariant: "gradient",
-  secondaryVariant: "hatched",
-  stacked: true,
-  donutRadius: 0.5,
-  duration: 900,
-}
-
 function bloomOf(t: Tweaks): BloomInput {
   return t.bloomPreset === "custom"
     ? {
@@ -359,255 +346,6 @@ function ReplayButton({ onClick }: { onClick: () => void }) {
   )
 }
 
-/* --------------------------------------------------------- tweak sidebar */
-
-function Field({ label, children }: { label: string; children: ReactNode }) {
-  return (
-    <label className="flex flex-col gap-1.5">
-      <span className="font-mono text-[11px] text-muted-foreground">
-        {label}
-      </span>
-      {children}
-    </label>
-  )
-}
-
-function Select<T extends string>({
-  value,
-  options,
-  onChange,
-  ariaLabel,
-}: {
-  value: T
-  options: readonly T[]
-  onChange: (v: T) => void
-  ariaLabel: string
-}) {
-  return (
-    <select
-      value={value}
-      aria-label={ariaLabel}
-      onChange={(e) => onChange(e.target.value as T)}
-      className="rounded-md border bg-card px-2 py-1.5 font-mono text-xs text-foreground transition-colors hover:border-foreground/25"
-    >
-      {options.map((o) => (
-        <option key={o} value={o}>
-          {o}
-        </option>
-      ))}
-    </select>
-  )
-}
-
-function Range({
-  value,
-  min,
-  max,
-  step,
-  onChange,
-  ariaLabel,
-}: {
-  value: number
-  min: number
-  max: number
-  step: number
-  onChange: (v: number) => void
-  ariaLabel: string
-}) {
-  return (
-    <div className="flex items-center gap-3 rounded-md border bg-card px-3 py-2">
-      <input
-        type="range"
-        value={value}
-        aria-label={ariaLabel}
-        min={min}
-        max={max}
-        step={step}
-        onChange={(e) => onChange(Number(e.target.value))}
-        className="w-full accent-foreground"
-      />
-      <span className="w-10 shrink-0 text-right font-mono text-[11px] text-foreground">
-        {value}
-      </span>
-    </div>
-  )
-}
-
-function TweakSidebar({
-  open,
-  onClose,
-  tweaks,
-  setTweaks,
-  onReplayAll,
-}: {
-  open: boolean
-  onClose: () => void
-  tweaks: Tweaks
-  setTweaks: (t: Tweaks) => void
-  onReplayAll: () => void
-}) {
-  const set = <K extends keyof Tweaks>(key: K, value: Tweaks[K]) =>
-    setTweaks({ ...tweaks, [key]: value })
-
-  // Docked, not modal — the page stays visible and interactive alongside, so
-  // you can tweak, watch the charts respond, and tweak again.
-  return (
-    <aside
-      aria-hidden={!open}
-      className={`fixed inset-y-0 right-0 z-40 flex w-80 flex-col border-l bg-background transition-transform duration-200 ${
-        open ? "translate-x-0" : "translate-x-full"
-      }`}
-    >
-      <div className="flex items-center justify-between border-b px-5 py-4">
-        <span className="font-pixel-geist text-sm text-foreground">
-          tweak the charts
-        </span>
-        <button
-          type="button"
-          aria-label="Close"
-          onClick={onClose}
-          className="rounded-md border p-1.5 text-muted-foreground transition-colors hover:text-foreground"
-        >
-          <XIcon className="size-3.5" />
-        </button>
-      </div>
-
-      <div className="flex flex-1 flex-col gap-5 overflow-y-auto px-5 py-5">
-        <p className="font-mono text-[11px] leading-relaxed text-muted-foreground">
-          every preview on this page rebuilds live as you turn these. the code
-          snippets follow along — copy them when it looks right.
-        </p>
-
-        <Field label="bloom">
-          <Select
-            ariaLabel="bloom"
-            value={tweaks.bloomPreset}
-            options={BLOOM_PRESETS}
-            onChange={(v) => set("bloomPreset", v)}
-          />
-        </Field>
-
-        {tweaks.bloomPreset === "custom" && (
-          <div className="flex flex-col gap-3 rounded-lg border p-3">
-            <Field label="blur (px)">
-              <Range
-                ariaLabel="blur (px)"
-                value={tweaks.blur}
-                min={0}
-                max={32}
-                step={1}
-                onChange={(v) => set("blur", v)}
-              />
-            </Field>
-            <Field label="brightness">
-              <Range
-                ariaLabel="brightness"
-                value={tweaks.brightness}
-                min={1}
-                max={4}
-                step={0.1}
-                onChange={(v) => set("brightness", v)}
-              />
-            </Field>
-            <Field label="opacity">
-              <Range
-                ariaLabel="opacity"
-                value={tweaks.opacity}
-                min={0.05}
-                max={1}
-                step={0.05}
-                onChange={(v) => set("opacity", v)}
-              />
-            </Field>
-            <Field label="saturate">
-              <Range
-                ariaLabel="saturate"
-                value={tweaks.saturate}
-                min={1}
-                max={4}
-                step={0.25}
-                onChange={(v) => set("saturate", v)}
-              />
-            </Field>
-          </div>
-        )}
-
-        <Field label="desktop series variant">
-          <Select
-            ariaLabel="desktop series variant"
-            value={tweaks.primaryVariant}
-            options={VARIANTS}
-            onChange={(v) => set("primaryVariant", v)}
-          />
-        </Field>
-        <Field label="mobile series variant">
-          <Select
-            ariaLabel="mobile series variant"
-            value={tweaks.secondaryVariant}
-            options={VARIANTS}
-            onChange={(v) => set("secondaryVariant", v)}
-          />
-        </Field>
-
-        <Field label="stacking (area + bar)">
-          <div className="flex gap-1.5">
-            <Pill
-              label="stacked"
-              active={tweaks.stacked}
-              onClick={() => set("stacked", true)}
-            />
-            <Pill
-              label="overlaid"
-              active={!tweaks.stacked}
-              onClick={() => set("stacked", false)}
-            />
-          </div>
-        </Field>
-
-        <Field label="pie inner radius (0 = full pie)">
-          <Range
-            ariaLabel="pie inner radius (0 = full pie)"
-            value={tweaks.donutRadius}
-            min={0}
-            max={0.8}
-            step={0.05}
-            onChange={(v) => set("donutRadius", v)}
-          />
-        </Field>
-
-        <Field label="entrance duration (ms)">
-          <Range
-            ariaLabel="entrance duration (ms)"
-            value={tweaks.duration}
-            min={300}
-            max={2400}
-            step={100}
-            onChange={(v) => set("duration", v)}
-          />
-        </Field>
-      </div>
-
-      <div className="flex gap-2 border-t px-5 py-4">
-        <button
-          type="button"
-          onClick={onReplayAll}
-          className="flex flex-1 items-center justify-center gap-2 rounded-md bg-primary px-3 py-2 font-mono text-xs text-primary-foreground transition-opacity hover:opacity-90"
-        >
-          <RefreshCcwIcon className="size-3.5" />
-          replay all
-        </button>
-        <button
-          type="button"
-          onClick={() => setTweaks(DEFAULT_TWEAKS)}
-          className="rounded-md border px-3 py-2 font-mono text-xs text-muted-foreground transition-colors hover:text-foreground"
-        >
-          reset
-        </button>
-      </div>
-    </aside>
-  )
-}
-
 /* -------------------------------------------------------------- showcase */
 
 function Showcase({
@@ -679,10 +417,7 @@ function Showcase({
 
 function DitherKitDocs() {
   const { light, toggle: toggleTheme } = usePageTheme()
-  const [tweaks, setTweaks] = useState<Tweaks>(DEFAULT_TWEAKS)
-  const [panelOpen, setPanelOpen] = useState(false)
   const [pm, setPm] = useState<Pm>("npm")
-  const bloom = bloomOf(tweaks)
 
   // One replay counter per showcase so a replay never re-runs its neighbours.
   const [replays, setReplays] = useState({
@@ -703,6 +438,60 @@ function DitherKitDocs() {
         ) as typeof replays
     )
 
+  // The live tweak panel — DialKit (https://joshpuckett.me/dialkit) renders a
+  // floating control surface from this config; every preview and code snippet
+  // on the page follows it.
+  const params = useDialKit(
+    "dither-kit",
+    {
+      bloom: {
+        preset: {
+          type: "select",
+          options: ["off", "low", "high", "aura", "custom"],
+          default: "aura",
+        },
+        blur: [24, 0, 32, 1],
+        brightness: [2.9, 1, 4, 0.1],
+        opacity: [0.1, 0.05, 1, 0.05],
+        saturate: [3, 1, 4, 0.25],
+        _collapsed: true,
+      },
+      desktopVariant: {
+        type: "select",
+        options: VARIANTS,
+        default: "gradient",
+      },
+      mobileVariant: {
+        type: "select",
+        options: VARIANTS,
+        default: "hatched",
+      },
+      stacked: true,
+      pieInnerRadius: [0.5, 0, 0.8, 0.05],
+      entranceMs: [900, 300, 2400, 100],
+      replayAll: { type: "action" },
+    },
+    {
+      onAction: (path: string) => {
+        if (path === "replayAll") replayAll()
+      },
+    }
+  )
+
+  const tweaks: Tweaks = {
+    bloomPreset: params.bloom.preset as BloomPreset,
+    blur: params.bloom.blur,
+    brightness: params.bloom.brightness,
+    opacity: params.bloom.opacity,
+    saturate: params.bloom.saturate,
+    primaryVariant: params.desktopVariant as AreaVariant,
+    secondaryVariant: params.mobileVariant as AreaVariant,
+    stacked: params.stacked,
+    donutRadius: params.pieInnerRadius,
+    duration: params.entranceMs,
+  }
+  const bloom = bloomOf(tweaks)
+
   // Any tweak replays the charts on its own once it settles (300ms after the
   // last change) — no need to reach for "replay all".
   useSettled(JSON.stringify(tweaks), 300, replayAll)
@@ -714,9 +503,9 @@ function DitherKitDocs() {
     // The tweak panel docks on the right; content slides over so the charts
     // stay in view while you turn the knobs.
     <div
-      className={`min-h-screen bg-background text-foreground transition-[padding] duration-200 ${
+      className={`min-h-screen bg-background text-foreground ${
         light ? "dither-light" : "dark"
-      } ${panelOpen ? "lg:pr-80" : ""}`}
+      }`}
     >
       <DitherStrip className="h-2 w-full" />
 
@@ -888,15 +677,9 @@ function DitherKitDocs() {
           <div className="flex items-center gap-3">
             <h2 className="font-pixel-geist text-lg text-foreground">charts</h2>
             <DitherStrip className="h-1.5 flex-1" />
-            <button
-              type="button"
-              onClick={() => setPanelOpen((v) => !v)}
-              aria-pressed={panelOpen}
-              className="flex items-center gap-2 rounded-md bg-primary px-3 py-1.5 font-mono text-xs text-primary-foreground transition-opacity hover:opacity-90"
-            >
-              <SlidersHorizontalIcon className="size-3.5" />
-              tweak these charts
-            </button>
+            <span className="font-mono text-xs text-muted-foreground">
+              tweak these charts from the floating dial panel →
+            </span>
           </div>
 
           <Showcase
@@ -1059,14 +842,7 @@ function DitherKitDocs() {
       </div>
 
       <DitherStrip className="h-2 w-full" />
-
-      <TweakSidebar
-        open={panelOpen}
-        onClose={() => setPanelOpen(false)}
-        tweaks={tweaks}
-        setTweaks={setTweaks}
-        onReplayAll={replayAll}
-      />
+      <DialRoot position="top-right" productionEnabled />
     </div>
   )
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ae8fb98..612d548 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -192,6 +192,9 @@ importers:
       d3-shape:
         specifier: ^3.2.0
         version: 3.2.0
+      dialkit:
+        specifier: ^1.3.0
+        version: 1.3.0(motion@12.42.2(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(solid-js@1.9.12)
       drizzle-kit:
         specifier: ^0.31.9
         version: 0.31.10
@@ -5785,6 +5788,30 @@ packages:
   devlop@1.1.0:
     resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
 
+  dialkit@1.3.0:
+    resolution: {integrity: sha512-//tnKhG+6gWhH3h9L7RpRPQZJkRBj0qQyUu1Og1l0VI6Nn/7iKaZZDFs/hG+Jsrtvwp4hlLrrmzj8M6hkXR3EA==}
+    peerDependencies:
+      motion: '>=11.0.0'
+      motion-v: '>=2.0.0'
+      react: '>=18.0.0'
+      react-dom: '>=18.0.0'
+      solid-js: '>=1.6.0'
+      svelte: '>=5.8.0'
+      vue: '>=3.3.0'
+    peerDependenciesMeta:
+      motion-v:
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+      solid-js:
+        optional: true
+      svelte:
+        optional: true
+      vue:
+        optional: true
+
   diff@8.0.4:
     resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
     engines: {node: '>=0.3.1'}
@@ -10135,7 +10162,7 @@ snapshots:
 
   '@img/sharp-wasm32@0.34.5':
     dependencies:
-      '@emnapi/runtime': 1.10.0
+      '@emnapi/runtime': 1.11.1
     optional: true
 
   '@img/sharp-win32-arm64@0.34.5':
@@ -14183,6 +14210,14 @@ snapshots:
     dependencies:
       dequal: 2.0.3
 
+  dialkit@1.3.0(motion@12.42.2(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react-dom@19.2.5(react@19.2.5))(react@19.2.5)(solid-js@1.9.12):
+    dependencies:
+      motion: 12.42.2(@emotion/is-prop-valid@1.4.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+    optionalDependencies:
+      react: 19.2.5
+      react-dom: 19.2.5(react@19.2.5)
+      solid-js: 1.9.12
+
   diff@8.0.4: {}
 
   dom-accessibility-api@0.5.16: {}

From 5ad41690c17a556e683e26e6197d003381e92148 Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Fri, 3 Jul 2026 18:12:12 -0700
Subject: [PATCH 3/5] fix: DialKit closed on load, tweaks no longer replay the
 entrance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Entrance animation now fires only on page load or the replay buttons —
turning a dial adjusts the live chart without re-running the sweep.
---
 apps/web/src/routes/dither-kit.tsx | 27 ++-------------------------
 1 file changed, 2 insertions(+), 25 deletions(-)

diff --git a/apps/web/src/routes/dither-kit.tsx b/apps/web/src/routes/dither-kit.tsx
index 46f9dce..4994f12 100644
--- a/apps/web/src/routes/dither-kit.tsx
+++ b/apps/web/src/routes/dither-kit.tsx
@@ -8,7 +8,7 @@ import {
   RefreshCcwIcon,
   SunIcon,
 } from "lucide-react"
-import { Fragment, type ReactNode, useEffect, useRef, useState } from "react"
+import { Fragment, type ReactNode, useState } from "react"
 import {
   ActiveDot,
   Area,
@@ -147,25 +147,6 @@ function DitherStrip({ className = "" }: { className?: string }) {
   )
 }
 
-/** Fire `onSettle` once `value` has stopped changing for `ms` (skips mount).
- * Lets the tweak panel replay the charts by itself instead of making you reach
- * for the replay button after every change. */
-function useSettled(value: string | number, ms: number, onSettle: () => void) {
-  const first = useRef(true)
-  const settle = useRef(onSettle)
-  useEffect(() => {
-    settle.current = onSettle
-  }, [onSettle])
-  useEffect(() => {
-    if (first.current) {
-      first.current = false
-      return
-    }
-    const t = setTimeout(() => settle.current(), ms)
-    return () => clearTimeout(t)
-  }, [value, ms])
-}
-
 /** Page-scoped theme. The app is dark-only, so instead of a global theme the
  * page swaps the `.dither-light` token overrides (and the `dark` class that
  * drives `dark:` variants) on its own wrapper. Persisted per visitor. */
@@ -492,10 +473,6 @@ function DitherKitDocs() {
   }
   const bloom = bloomOf(tweaks)
 
-  // Any tweak replays the charts on its own once it settles (300ms after the
-  // last change) — no need to reach for "replay all".
-  useSettled(JSON.stringify(tweaks), 300, replayAll)
-
   // Register the namespace once, then install any chart by name.
   const registries = `// components.json\n{\n  "registries": {\n    "@dither-kit": "${HOST}/r/{name}.json"\n  }\n}`
 
@@ -842,7 +819,7 @@ function DitherKitDocs() {
       </div>
 
       <DitherStrip className="h-2 w-full" />
-      <DialRoot position="top-right" productionEnabled />
+      <DialRoot position="top-right" defaultOpen={false} productionEnabled />
     </div>
   )
 }

From f91cd7ba1340b5446752140b50457c836a3666a6 Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Sat, 4 Jul 2026 00:39:06 -0700
Subject: [PATCH 4/5] refactor: split the docs page + address review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- usePageTheme hardened: localStorage reads/writes wrapped so disabled
  storage can't break the page, and the hook gets an explicit
  PageThemeState return type (review: stability)
- snippets now reflect the entrance slider — non-default entranceMs
  emits animationDuration={n} in every copied chart snippet (review:
  functional correctness)
- the theme button's label says which theme it switches to instead of
  a generic toggle (review: a11y)
- react-doctor's no-giant-component / no-multi-comp on the route: the
  893-line file is now a ~140-line route composing
  components/dither-kit-docs/{content,ui,sections} — data + snippet
  builders, page primitives (strip, copy, highlighter, pills,
  showcase), and the six page sections
---
 apps/web/biome.json                           |  19 +-
 .../src/components/dither-kit-docs/content.ts | 178 ++++
 .../components/dither-kit-docs/sections.tsx   | 441 ++++++++++
 .../web/src/components/dither-kit-docs/ui.tsx | 300 +++++++
 apps/web/src/routes/dither-kit.tsx            | 832 +-----------------
 5 files changed, 974 insertions(+), 796 deletions(-)
 create mode 100644 apps/web/src/components/dither-kit-docs/content.ts
 create mode 100644 apps/web/src/components/dither-kit-docs/sections.tsx
 create mode 100644 apps/web/src/components/dither-kit-docs/ui.tsx

diff --git a/apps/web/biome.json b/apps/web/biome.json
index 6d81bbe..971ccfe 100644
--- a/apps/web/biome.json
+++ b/apps/web/biome.json
@@ -21,7 +21,13 @@
     "enabled": true,
     "indentStyle": "tab"
   },
-  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
   "linter": {
     "enabled": true,
     "rules": {
@@ -43,7 +49,8 @@
     {
       "includes": [
         "**/components/dither-kit/**/*.tsx",
-        "**/routes/dither-kit.tsx"
+        "**/routes/dither-kit.tsx",
+        "**/components/dither-kit-docs/**/*.tsx"
       ],
       "linter": {
         "rules": {
@@ -54,7 +61,9 @@
       }
     },
     {
-      "includes": ["**/components/icons/**/*.tsx"],
+      "includes": [
+        "**/components/icons/**/*.tsx"
+      ],
       "linter": {
         "rules": {
           "correctness": {
@@ -64,7 +73,9 @@
       }
     },
     {
-      "includes": ["**/packages/ui/src/icons/**/*.tsx"],
+      "includes": [
+        "**/packages/ui/src/icons/**/*.tsx"
+      ],
       "linter": {
         "rules": {
           "correctness": {
diff --git a/apps/web/src/components/dither-kit-docs/content.ts b/apps/web/src/components/dither-kit-docs/content.ts
new file mode 100644
index 0000000..1f4f465
--- /dev/null
+++ b/apps/web/src/components/dither-kit-docs/content.ts
@@ -0,0 +1,178 @@
+import type {
+  AreaVariant,
+  BloomInput,
+  ChartConfig,
+} from "#/components/dither-kit"
+
+/** Everything the dither-kit docs page renders from: install commands, demo
+ * data, the tweak model, and the live code snippets. */
+
+/** Where the registry lives once deployed. */
+export const HOST = "https://tripwire.sh"
+
+/* ------------------------------------------------------- package manager */
+
+export const PMS = ["npm", "pnpm", "yarn", "bun"] as const
+export type Pm = (typeof PMS)[number]
+
+/** The runner each package manager uses for one-off CLIs. */
+const PM_RUNNER: Record<Pm, string> = {
+  npm: "npx",
+  pnpm: "pnpm dlx",
+  yarn: "yarn dlx",
+  bun: "bunx --bun",
+}
+
+export const addCmd = (pm: Pm, item: string): string =>
+  `${PM_RUNNER[pm]} shadcn@latest add ${item}`
+
+/* ------------------------------------------------------------------ data */
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug"]
+export const series = MONTHS.map((month, i) => ({
+  month,
+  desktop: Math.round(120 + 90 * Math.sin(i * 0.7) + i * 14),
+  mobile: Math.round(70 + 50 * Math.cos(i * 0.5) + i * 8),
+}))
+export const config: ChartConfig = {
+  desktop: { label: "Desktop", color: "blue" },
+  mobile: { label: "Mobile", color: "purple" },
+}
+export const pieData = [
+  { browser: "chrome", visitors: 275 },
+  { browser: "safari", visitors: 200 },
+  { browser: "firefox", visitors: 187 },
+  { browser: "edge", visitors: 120 },
+  { browser: "other", visitors: 90 },
+]
+export const pieConfig: ChartConfig = {
+  chrome: { label: "Chrome", color: "blue" },
+  safari: { label: "Safari", color: "green" },
+  firefox: { label: "Firefox", color: "orange" },
+  edge: { label: "Edge", color: "purple" },
+  other: { label: "Other", color: "grey" },
+}
+export const radarData = [
+  { skill: "Speed", desktop: 186, mobile: 120 },
+  { skill: "Power", desktop: 205, mobile: 98 },
+  { skill: "Range", desktop: 137, mobile: 160 },
+  { skill: "Defense", desktop: 173, mobile: 125 },
+  { skill: "Magic", desktop: 160, mobile: 190 },
+  { skill: "Luck", desktop: 144, mobile: 110 },
+]
+
+/* ---------------------------------------------------------- live tweaks */
+
+export const VARIANTS: AreaVariant[] = [
+  "gradient",
+  "dotted",
+  "hatched",
+  "solid",
+]
+export const BLOOM_PRESETS = ["off", "low", "high", "aura", "custom"] as const
+export type BloomPreset = (typeof BLOOM_PRESETS)[number]
+
+export type Tweaks = {
+  bloomPreset: BloomPreset
+  blur: number
+  brightness: number
+  opacity: number
+  saturate: number
+  primaryVariant: AreaVariant
+  secondaryVariant: AreaVariant
+  stacked: boolean
+  donutRadius: number // 0 = full pie
+  duration: number // entrance ms
+}
+
+export function bloomOf(t: Tweaks): BloomInput {
+  return t.bloomPreset === "custom"
+    ? {
+        blur: t.blur,
+        brightness: t.brightness,
+        opacity: t.opacity,
+        saturate: t.saturate,
+      }
+    : t.bloomPreset
+}
+
+/* ------------------------------------------------------------- snippets */
+
+/** How the current bloom reads in the code snippets. */
+function bloomAttr(t: Tweaks): string {
+  if (t.bloomPreset === "custom") {
+    return ` bloom={{ blur: ${t.blur}, brightness: ${t.brightness}, opacity: ${t.opacity}, saturate: ${t.saturate} }}`
+  }
+  return t.bloomPreset === "off" ? "" : ` bloom="${t.bloomPreset}"`
+}
+
+const stackAttr = (t: Tweaks): string =>
+  t.stacked ? ' stackType="stacked"' : ""
+
+/** Non-default entrance timing shows up in the copied code too. */
+const durationAttr = (t: Tweaks): string =>
+  t.duration === 900 ? "" : ` animationDuration={${t.duration}}`
+
+export const areaCode = (t: Tweaks): string =>
+  `<AreaChart data={data} config={config}${stackAttr(t)}${bloomAttr(t)}${durationAttr(t)}>
+  <XAxis dataKey="month" />
+  <YAxis />
+  <Legend isClickable />
+  <Tooltip labelKey="month" />
+  <Area dataKey="desktop" variant="${t.primaryVariant}" />
+  <Area dataKey="mobile" variant="${t.secondaryVariant}" />
+</AreaChart>`
+
+export const barCode = (t: Tweaks): string =>
+  `<BarChart data={data} config={config}${stackAttr(t)}${bloomAttr(t)}${durationAttr(t)}>
+  <XAxis dataKey="month" />
+  <YAxis />
+  <Legend isClickable />
+  <Tooltip labelKey="month" />
+  <Bar dataKey="desktop" variant="${t.primaryVariant}" />
+  <Bar dataKey="mobile" variant="${t.secondaryVariant}" />
+</BarChart>`
+
+export const lineCode = (t: Tweaks): string =>
+  `// LineChart ships in the area-chart item (line = area + glow)
+<LineChart data={data} config={config}${bloomAttr(t)}${durationAttr(t)}>
+  <XAxis dataKey="month" />
+  <YAxis />
+  <Legend isClickable />
+  <Tooltip labelKey="month" />
+  <Line dataKey="desktop" />
+  <Line dataKey="mobile" strokeVariant="dashed" />
+</LineChart>`
+
+export const pieCode = (t: Tweaks): string =>
+  `<PieChart data={data} config={config}
+  dataKey="visitors" nameKey="browser"${
+    t.donutRadius > 0 ? ` innerRadius={${t.donutRadius}}` : ""
+  }${bloomAttr(t)}${durationAttr(t)}>
+  <Legend isClickable align="center" />
+  <Tooltip />
+  <Pie variant="${t.primaryVariant}" />
+</PieChart>`
+
+export const radarCode = (t: Tweaks): string =>
+  `<RadarChart data={data} config={config} nameKey="skill"${bloomAttr(t)}${durationAttr(t)}>
+  <Legend isClickable align="center" />
+  <Tooltip />
+  <Radar dataKey="desktop" variant="${t.primaryVariant}" />
+  <Radar dataKey="mobile" variant="${t.secondaryVariant}" />
+</RadarChart>`
+
+export const PROPS: [string, string][] = [
+  ["variant", '"gradient" | "dotted" | "hatched" | "solid"'],
+  [
+    "bloom",
+    '"off" | "low" | "high" | "aura" | { blur, brightness, opacity, saturate }',
+  ],
+  ["stackType", '"default" | "stacked" | "percent"'],
+  ["colors", "green blue purple pink orange red grey"],
+  ["animate", "animationDuration + replayToken for entrance and replay"],
+  ["interactive", "false = decorative spark, no crosshair or tooltip"],
+]
+
+export const SPARKLINE_CODE = `// tiny decorative spark — no axes, no tooltip
+<Sparkline data={[3, 7, 5, 9, 8, 12]} color="green" bloom="aura" />`
diff --git a/apps/web/src/components/dither-kit-docs/sections.tsx b/apps/web/src/components/dither-kit-docs/sections.tsx
new file mode 100644
index 0000000..d465857
--- /dev/null
+++ b/apps/web/src/components/dither-kit-docs/sections.tsx
@@ -0,0 +1,441 @@
+"use client"
+
+import { MoonIcon, SunIcon } from "lucide-react"
+import {
+  ActiveDot,
+  Area,
+  AreaChart,
+  Bar,
+  BarChart,
+  type BloomInput,
+  Legend,
+  Line,
+  LineChart,
+  Pie,
+  PieChart,
+  Radar,
+  RadarChart,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "#/components/dither-kit"
+import {
+  addCmd,
+  areaCode,
+  barCode,
+  config,
+  HOST,
+  lineCode,
+  pieCode,
+  pieConfig,
+  pieData,
+  type Pm,
+  PMS,
+  PROPS,
+  radarCode,
+  radarData,
+  series,
+  SPARKLINE_CODE,
+  type Tweaks,
+} from "./content"
+import {
+  Code,
+  CodeBlock,
+  CopyLine,
+  DitherStrip,
+  Pill,
+  ReplayButton,
+  Showcase,
+} from "./ui"
+
+/** The docs page, section by section — the route composes these. */
+
+export type Replays = {
+  hero: number
+  area: number
+  bar: number
+  line: number
+  pie: number
+  radar: number
+}
+export type ReplayKey = keyof Replays
+
+export function HeroSection({
+  light,
+  onToggleTheme,
+  tweaks,
+  bloom,
+  replayToken,
+  onReplay,
+}: {
+  light: boolean
+  onToggleTheme: () => void
+  tweaks: Tweaks
+  bloom: BloomInput
+  replayToken: number
+  onReplay: () => void
+}) {
+  return (
+    <header className="flex flex-col gap-8">
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex flex-col gap-1.5">
+          <h1 className="font-pixel-geist text-4xl text-foreground sm:text-5xl">
+            dither-kit
+          </h1>
+          <p className="font-mono text-xs text-muted-foreground">
+            five chart types on one tiny canvas engine, no recharts
+          </p>
+        </div>
+        <button
+          type="button"
+          aria-label={light ? "Switch to dark theme" : "Switch to light theme"}
+          onClick={onToggleTheme}
+          className="rounded-md border p-2 text-muted-foreground transition-colors hover:border-foreground/25 hover:text-foreground"
+        >
+          {light ? (
+            <MoonIcon className="size-4" />
+          ) : (
+            <SunIcon className="size-4" />
+          )}
+        </button>
+      </div>
+
+      <p className="max-w-2xl leading-relaxed text-balance text-muted-foreground">
+        Composable, <span className="text-foreground">dithered</span> charts
+        with a recharts-style children-as-config API. Ordered-dither fills that
+        hold up in light and dark, entrance animations, a gliding scrub tooltip,
+        selection, winking sparkles, and colour bloom.
+      </p>
+
+      {/* Hero chart */}
+      <div className="flex flex-col gap-3">
+        <div className="flex items-center justify-between">
+          <span className="font-mono text-xs text-muted-foreground">
+            scrub it, hover a legend entry to spotlight that series, click to
+            lock it
+          </span>
+          <ReplayButton onClick={onReplay} />
+        </div>
+        <div className="h-72">
+          <AreaChart
+            data={series}
+            config={config}
+            stackType={tweaks.stacked ? "stacked" : "default"}
+            bloom={bloom}
+            animationDuration={tweaks.duration}
+            replayToken={replayToken}
+          >
+            <XAxis dataKey="month" />
+            <YAxis />
+            <Legend isClickable />
+            <Tooltip labelKey="month" />
+            <Area
+              dataKey="desktop"
+              variant={tweaks.primaryVariant}
+              strokeVariant="dashed"
+              isClickable
+            >
+              <ActiveDot variant="colored-border" />
+            </Area>
+            <Area
+              dataKey="mobile"
+              variant={tweaks.secondaryVariant}
+              isClickable
+            >
+              <ActiveDot variant="colored-border" />
+            </Area>
+          </AreaChart>
+        </div>
+      </div>
+    </header>
+  )
+}
+
+export function InstallSection({
+  pm,
+  onPmChange,
+}: {
+  pm: Pm
+  onPmChange: (pm: Pm) => void
+}) {
+  // Register the namespace once, then install any chart by name.
+  const registries = `// components.json\n{\n  "registries": {\n    "@dither-kit": "${HOST}/r/{name}.json"\n  }\n}`
+  return (
+    <section className="flex flex-col gap-5">
+      <div className="flex items-center gap-3">
+        <h2 className="font-pixel-geist text-lg text-foreground">install</h2>
+        <DitherStrip className="h-1.5 flex-1" />
+        <div className="flex items-center gap-1.5">
+          {PMS.map((p) => (
+            <Pill
+              key={p}
+              label={p}
+              active={pm === p}
+              onClick={() => onPmChange(p)}
+            />
+          ))}
+        </div>
+      </div>
+
+      <div className="grid gap-6 md:grid-cols-2">
+        <div className="flex flex-col gap-2">
+          <span className="font-mono text-xs text-muted-foreground">
+            1. register the namespace in{" "}
+            <span className="text-foreground">components.json</span>
+          </span>
+          <CodeBlock code={registries} />
+        </div>
+        <div className="flex flex-col gap-2">
+          <span className="font-mono text-xs text-muted-foreground">
+            2. add charts — each pulls{" "}
+            <span className="text-foreground">@dither-kit/core</span>{" "}
+            automatically
+          </span>
+          <div className="flex flex-col gap-1.5">
+            <CopyLine text={addCmd(pm, "@dither-kit/area-chart")} />
+            <CopyLine text={addCmd(pm, "@dither-kit/pie-chart")} />
+            <CopyLine text={addCmd(pm, "@dither-kit/dither-kit")} />
+          </div>
+        </div>
+      </div>
+
+      <p className="font-mono text-[11px] leading-relaxed text-muted-foreground">
+        also available: <span className="text-foreground">bar-chart</span> and{" "}
+        <span className="text-foreground">radar-chart</span>.{" "}
+        <span className="text-foreground">@dither-kit/dither-kit</span> grabs
+        everything. skipping the namespace config? the raw URL works:{" "}
+        <span className="text-foreground">
+          shadcn add {HOST}/r/radar-chart.json
+        </span>
+        . files land in{" "}
+        <span className="text-foreground">components/dither-kit/</span>.
+      </p>
+    </section>
+  )
+}
+
+export function CreditAside() {
+  return (
+    <aside className="flex flex-col gap-3">
+      <DitherStrip className="h-1.5 w-full" />
+      <p className="max-w-2xl text-sm leading-relaxed">
+        <span className="font-pixel-geist text-foreground">
+          huge thanks to Evil Charts.
+        </span>{" "}
+        <span className="text-muted-foreground">
+          dither-kit exists because of{" "}
+          <a
+            href="https://www.evilcharts.com"
+            target="_blank"
+            rel="noreferrer"
+            className="text-foreground underline underline-offset-2 hover:text-muted-foreground"
+          >
+            Evil Charts
+          </a>{" "}
+          by{" "}
+          <a
+            href="https://github.com/legions-developer/evilcharts"
+            target="_blank"
+            rel="noreferrer"
+            className="text-foreground underline underline-offset-2 hover:text-muted-foreground"
+          >
+            legions-developer
+          </a>{" "}
+          — the original dithered, composable chart aesthetic that inspired
+          every pixel here. Even the per-chart{" "}
+          <span className="text-foreground">@namespace/chart</span> install flow
+          is theirs. Go star it.
+        </span>
+      </p>
+    </aside>
+  )
+}
+
+export function ChartGallery({
+  pm,
+  tweaks,
+  bloom,
+  replays,
+  onReplay,
+}: {
+  pm: Pm
+  tweaks: Tweaks
+  bloom: BloomInput
+  replays: Replays
+  onReplay: (key: ReplayKey) => void
+}) {
+  return (
+    <div className="flex flex-col gap-14">
+      <div className="flex items-center gap-3">
+        <h2 className="font-pixel-geist text-lg text-foreground">charts</h2>
+        <DitherStrip className="h-1.5 flex-1" />
+        <span className="font-mono text-xs text-muted-foreground">
+          tweak these charts from the floating dial panel →
+        </span>
+      </div>
+
+      <Showcase
+        title="area"
+        install={addCmd(pm, "@dither-kit/area-chart")}
+        code={areaCode(tweaks)}
+        toolbar={<ReplayButton onClick={() => onReplay("area")} />}
+      >
+        <AreaChart
+          data={series}
+          config={config}
+          stackType={tweaks.stacked ? "stacked" : "default"}
+          bloom={bloom}
+          animationDuration={tweaks.duration}
+          replayToken={replays.area}
+        >
+          <XAxis dataKey="month" />
+          <YAxis />
+          <Legend isClickable />
+          <Tooltip labelKey="month" />
+          <Area dataKey="desktop" variant={tweaks.primaryVariant} />
+          <Area dataKey="mobile" variant={tweaks.secondaryVariant} />
+        </AreaChart>
+      </Showcase>
+
+      <Showcase
+        title="bar"
+        install={addCmd(pm, "@dither-kit/bar-chart")}
+        code={barCode(tweaks)}
+        toolbar={<ReplayButton onClick={() => onReplay("bar")} />}
+      >
+        <BarChart
+          data={series}
+          config={config}
+          stackType={tweaks.stacked ? "stacked" : "default"}
+          bloom={bloom}
+          animationDuration={tweaks.duration}
+          replayToken={replays.bar}
+        >
+          <XAxis dataKey="month" />
+          <YAxis />
+          <Legend isClickable />
+          <Tooltip labelKey="month" />
+          <Bar dataKey="desktop" variant={tweaks.primaryVariant} />
+          <Bar dataKey="mobile" variant={tweaks.secondaryVariant} />
+        </BarChart>
+      </Showcase>
+
+      <Showcase
+        title="line"
+        install={addCmd(pm, "@dither-kit/area-chart")}
+        code={lineCode(tweaks)}
+        toolbar={<ReplayButton onClick={() => onReplay("line")} />}
+      >
+        <LineChart
+          data={series}
+          config={config}
+          bloom={bloom}
+          animationDuration={tweaks.duration}
+          replayToken={replays.line}
+        >
+          <XAxis dataKey="month" />
+          <YAxis />
+          <Legend isClickable />
+          <Tooltip labelKey="month" />
+          <Line dataKey="desktop" />
+          <Line dataKey="mobile" strokeVariant="dashed" />
+        </LineChart>
+      </Showcase>
+
+      <div className="grid gap-14 lg:grid-cols-2 lg:gap-8">
+        <Showcase
+          title="pie"
+          install={addCmd(pm, "@dither-kit/pie-chart")}
+          code={pieCode(tweaks)}
+          tall
+          toolbar={<ReplayButton onClick={() => onReplay("pie")} />}
+        >
+          <PieChart
+            data={pieData}
+            config={pieConfig}
+            dataKey="visitors"
+            nameKey="browser"
+            innerRadius={tweaks.donutRadius}
+            bloom={bloom}
+            animationDuration={tweaks.duration}
+            replayToken={replays.pie}
+          >
+            <Legend isClickable align="center" />
+            <Tooltip />
+            <Pie variant={tweaks.primaryVariant} />
+          </PieChart>
+        </Showcase>
+
+        <Showcase
+          title="radar"
+          install={addCmd(pm, "@dither-kit/radar-chart")}
+          code={radarCode(tweaks)}
+          tall
+          toolbar={<ReplayButton onClick={() => onReplay("radar")} />}
+        >
+          <RadarChart
+            data={radarData}
+            config={config}
+            nameKey="skill"
+            bloom={bloom}
+            animationDuration={tweaks.duration}
+            replayToken={replays.radar}
+          >
+            <Legend isClickable align="center" />
+            <Tooltip />
+            <Radar dataKey="desktop" variant={tweaks.primaryVariant} />
+            <Radar dataKey="mobile" variant={tweaks.secondaryVariant} />
+          </RadarChart>
+        </Showcase>
+      </div>
+    </div>
+  )
+}
+
+export function KnobsSection() {
+  return (
+    <section className="flex flex-col gap-4">
+      <div className="flex items-baseline gap-3">
+        <h2 className="font-pixel-geist text-lg text-foreground">knobs</h2>
+        <DitherStrip className="h-1.5 flex-1 self-center" />
+      </div>
+      <dl className="flex flex-col gap-2.5 font-mono text-xs">
+        {PROPS.map(([prop, desc]) => (
+          <div
+            key={prop}
+            className="grid items-baseline gap-1.5 sm:grid-cols-[10rem_1fr] sm:gap-4"
+          >
+            <dt>
+              <code className="w-fit rounded-md border bg-card px-1.5 py-0.5 text-[11px] text-violet-600 dark:text-violet-400">
+                {prop}
+              </code>
+            </dt>
+            <dd className="leading-relaxed text-muted-foreground">
+              <Code code={desc} />
+            </dd>
+          </div>
+        ))}
+      </dl>
+      <CodeBlock code={SPARKLINE_CODE} />
+    </section>
+  )
+}
+
+export function DocsFooter() {
+  return (
+    <footer className="flex flex-wrap items-center justify-between gap-3 border-t pt-6 text-xs text-muted-foreground">
+      <span className="font-pixel-geist">dither-kit</span>
+      <span className="font-mono">
+        built on the shoulders of{" "}
+        <a
+          href="https://www.evilcharts.com"
+          target="_blank"
+          rel="noreferrer"
+          className="text-foreground underline underline-offset-2"
+        >
+          Evil Charts
+        </a>
+      </span>
+    </footer>
+  )
+}
diff --git a/apps/web/src/components/dither-kit-docs/ui.tsx b/apps/web/src/components/dither-kit-docs/ui.tsx
new file mode 100644
index 0000000..7ffc1d3
--- /dev/null
+++ b/apps/web/src/components/dither-kit-docs/ui.tsx
@@ -0,0 +1,300 @@
+"use client"
+
+import { CheckIcon, CopyIcon, RefreshCcwIcon } from "lucide-react"
+import { Fragment, type ReactNode, useState } from "react"
+
+/** The dither-kit docs page's building blocks: the checkerboard strip motif,
+ * copy affordances, the tiny syntax highlighter, and the showcase card. */
+
+/** The page's signature motif: a strip of ordered-dither checkerboard that
+ * fades out — the same texture the charts are made of, as page chrome. */
+export function DitherStrip({ className = "" }: { className?: string }) {
+  return (
+    <div
+      aria-hidden
+      className={`text-border ${className}`}
+      style={{
+        backgroundImage:
+          "repeating-conic-gradient(currentColor 0% 25%, transparent 0% 50%)",
+        backgroundSize: "6px 6px",
+        maskImage:
+          "linear-gradient(to right, transparent, black 18%, black 82%, transparent)",
+      }}
+    />
+  )
+}
+
+/* ---------------------------------------------------------------- theme */
+
+export type PageThemeState = {
+  light: boolean
+  toggle: () => void
+}
+
+// Storage can be disabled (private mode, embedded webviews) — the toggle
+// keeps working in memory either way.
+const readPageTheme = (): boolean => {
+  try {
+    return window.localStorage.getItem("dither-kit-theme") === "light"
+  } catch {
+    return false
+  }
+}
+
+const writePageTheme = (light: boolean): void => {
+  try {
+    window.localStorage.setItem("dither-kit-theme", light ? "light" : "dark")
+  } catch {
+    // Keep the in-memory toggle working.
+  }
+}
+
+/** Page-scoped theme. The app is dark-only, so instead of a global theme the
+ * page swaps the `.dither-light` token overrides (and the `dark` class that
+ * drives `dark:` variants) on its own wrapper. Persisted per visitor. */
+export function usePageTheme(): PageThemeState {
+  const [light, setLight] = useState(
+    () => typeof window !== "undefined" && readPageTheme()
+  )
+  const toggle = () => {
+    setLight((value) => {
+      const next = !value
+      writePageTheme(next)
+      return next
+    })
+  }
+  return { light, toggle }
+}
+
+/* ----------------------------------------------------------------- copy */
+
+function useCopy() {
+  const [copied, setCopied] = useState(false)
+  const copy = (text: string) => {
+    navigator.clipboard?.writeText(text)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 1400)
+  }
+  return { copied, copy }
+}
+
+/** A copyable terminal line. */
+export function CopyLine({ text }: { text: string }) {
+  const { copied, copy } = useCopy()
+  return (
+    <button
+      type="button"
+      onClick={() => copy(text)}
+      className="group flex w-full items-center justify-between gap-4 rounded-lg border bg-card/60 px-4 py-2.5 text-left font-mono text-xs text-foreground transition-colors hover:border-foreground/25 hover:bg-card"
+    >
+      <span className="truncate">
+        <span className="text-muted-foreground select-none">$ </span>
+        {text}
+      </span>
+      <span className="shrink-0 text-muted-foreground transition-colors group-hover:text-foreground">
+        {copied ? (
+          <CheckIcon className="size-3.5" />
+        ) : (
+          <CopyIcon className="size-3.5" />
+        )}
+      </span>
+    </button>
+  )
+}
+
+/* --------------------------------------------------- syntax highlighting */
+
+type TokenType = "comment" | "string" | "tag" | "attr" | "number" | "punct"
+
+const TOKEN_RE =
+  /(\/\/[^\n]*)|("(?:[^"\\]|\\.)*")|(<\/?[A-Za-z][\w.]*|\/?>)|(\b\d+(?:\.\d+)?\b|\btrue\b|\bfalse\b)|([A-Za-z_]\w*(?==))|([{}()[\]=|,:])/g
+
+const TOKEN_CLASS: Record<TokenType, string> = {
+  comment: "text-muted-foreground/60 italic",
+  string: "text-emerald-600 dark:text-emerald-400",
+  tag: "text-sky-600 dark:text-sky-400",
+  number: "text-orange-600 dark:text-orange-400",
+  attr: "text-violet-600 dark:text-violet-400",
+  punct: "text-muted-foreground/70",
+}
+
+type Token = { type: TokenType | null; text: string; start: number }
+
+/** Pure tokenizer — `matchAll` leaves the shared regex untouched, and each
+ * token carries its source offset for a stable render key. */
+function tokenize(code: string): Token[] {
+  const tokens: Token[] = []
+  let last = 0
+  for (const m of code.matchAll(TOKEN_RE)) {
+    const start = m.index ?? 0
+    if (start > last)
+      tokens.push({ type: null, text: code.slice(last, start), start: last })
+    const type: TokenType = m[1]
+      ? "comment"
+      : m[2]
+        ? "string"
+        : m[3]
+          ? "tag"
+          : m[4]
+            ? "number"
+            : m[5]
+              ? "attr"
+              : "punct"
+    tokens.push({ type, text: m[0], start })
+    last = start + m[0].length
+  }
+  if (last < code.length)
+    tokens.push({ type: null, text: code.slice(last), start: last })
+  return tokens
+}
+
+/** Tiny JSX-ish highlighter for the docs snippets — no dependency, themed to
+ * the dither palette, adapts to light and dark via classes. */
+export function Code({ code }: { code: string }) {
+  return (
+    <>
+      {tokenize(code).map((t) =>
+        t.type ? (
+          <span key={t.start} className={TOKEN_CLASS[t.type]}>
+            {t.text}
+          </span>
+        ) : (
+          <Fragment key={t.start}>{t.text}</Fragment>
+        )
+      )}
+    </>
+  )
+}
+
+export function CodeBlock({ code }: { code: string }) {
+  const { copied, copy } = useCopy()
+  return (
+    <div className="group relative">
+      <pre className="h-full overflow-x-auto rounded-lg border bg-card/60 p-4 font-mono text-[11px] leading-relaxed text-muted-foreground">
+        <code>
+          <Code code={code} />
+        </code>
+      </pre>
+      <button
+        type="button"
+        onClick={() => copy(code)}
+        aria-label="Copy code"
+        className="absolute top-2 right-2 rounded-md border bg-background/80 p-1.5 text-muted-foreground opacity-0 backdrop-blur transition-opacity group-hover:opacity-100 hover:text-foreground focus-visible:opacity-100"
+      >
+        {copied ? (
+          <CheckIcon className="size-3" />
+        ) : (
+          <CopyIcon className="size-3" />
+        )}
+      </button>
+    </div>
+  )
+}
+
+/* ---------------------------------------------------------------- pills */
+
+/** Tiny pill toggle used for tabs and boolean tweaks. */
+export function Pill({
+  label,
+  active,
+  onClick,
+}: {
+  label: string
+  active?: boolean
+  onClick: () => void
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={`rounded-md border px-2 py-1 font-mono text-[11px] transition-colors ${
+        active
+          ? "border-transparent bg-primary text-primary-foreground"
+          : "text-muted-foreground hover:border-foreground/25 hover:text-foreground"
+      }`}
+    >
+      {label}
+    </button>
+  )
+}
+
+export function ReplayButton({ onClick }: { onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="Replay entrance animation"
+      className="rounded-md border p-1.5 text-muted-foreground transition-colors hover:border-foreground/25 hover:text-foreground"
+    >
+      <RefreshCcwIcon className="size-3.5" />
+    </button>
+  )
+}
+
+/* -------------------------------------------------------------- showcase */
+
+export function Showcase({
+  title,
+  install,
+  code,
+  toolbar,
+  children,
+  tall = false,
+}: {
+  title: string
+  install: string
+  code: string
+  /** Extra controls rendered in the card toolbar (e.g. replay). */
+  toolbar?: ReactNode
+  children: ReactNode
+  tall?: boolean
+}) {
+  const [tab, setTab] = useState<"preview" | "code">("preview")
+  const { copied, copy } = useCopy()
+  return (
+    <section
+      id={title.toLowerCase().replace(/[^a-z]+/g, "-")}
+      className="flex flex-col gap-4"
+    >
+      {/* Header row */}
+      <div className="flex flex-wrap items-center gap-2">
+        <h3 className="font-pixel-geist text-sm text-foreground">{title}</h3>
+        <button
+          type="button"
+          onClick={() => copy(install)}
+          className="hidden items-center gap-1.5 font-mono text-[11px] text-muted-foreground transition-colors hover:text-foreground sm:flex"
+        >
+          {copied ? (
+            <CheckIcon className="size-3" />
+          ) : (
+            <CopyIcon className="size-3" />
+          )}
+          {install.split(" add ").pop()}
+        </button>
+        <div className="ml-auto flex items-center gap-1.5">
+          {toolbar}
+          <Pill
+            label="preview"
+            active={tab === "preview"}
+            onClick={() => setTab("preview")}
+          />
+          <Pill
+            label="code"
+            active={tab === "code"}
+            onClick={() => setTab("code")}
+          />
+        </div>
+      </div>
+
+      {/* Body */}
+      {tab === "preview" ? (
+        <div className={`relative ${tall ? "h-80" : "h-64"}`}>{children}</div>
+      ) : (
+        <div className={`${tall ? "h-80" : "h-64"} overflow-y-auto`}>
+          <CodeBlock code={code} />
+        </div>
+      )}
+    </section>
+  )
+}
diff --git a/apps/web/src/routes/dither-kit.tsx b/apps/web/src/routes/dither-kit.tsx
index 4994f12..8b8fe52 100644
--- a/apps/web/src/routes/dither-kit.tsx
+++ b/apps/web/src/routes/dither-kit.tsx
@@ -1,407 +1,38 @@
 import { createFileRoute } from "@tanstack/react-router"
 import { DialRoot, useDialKit } from "dialkit"
 import "dialkit/styles.css"
+import { useState } from "react"
+import type { AreaVariant } from "#/components/dither-kit"
 import {
-  CheckIcon,
-  CopyIcon,
-  MoonIcon,
-  RefreshCcwIcon,
-  SunIcon,
-} from "lucide-react"
-import { Fragment, type ReactNode, useState } from "react"
+  type BloomPreset,
+  bloomOf,
+  type Pm,
+  type Tweaks,
+  VARIANTS,
+} from "#/components/dither-kit-docs/content"
 import {
-  ActiveDot,
-  Area,
-  AreaChart,
-  type AreaVariant,
-  Bar,
-  BarChart,
-  type BloomInput,
-  type ChartConfig,
-  Legend,
-  Line,
-  LineChart,
-  Pie,
-  PieChart,
-  Radar,
-  RadarChart,
-  Tooltip,
-  XAxis,
-  YAxis,
-} from "#/components/dither-kit"
+  ChartGallery,
+  CreditAside,
+  DocsFooter,
+  HeroSection,
+  InstallSection,
+  KnobsSection,
+  type ReplayKey,
+  type Replays,
+} from "#/components/dither-kit-docs/sections"
+import { DitherStrip, usePageTheme } from "#/components/dither-kit-docs/ui"
 
 export const Route = createFileRoute("/dither-kit")({
   ssr: false,
   component: DitherKitDocs,
 })
 
-/** Where the registry lives once deployed. */
-const HOST = "https://tripwire.sh"
-
-/* ------------------------------------------------------- package manager */
-
-const PMS = ["npm", "pnpm", "yarn", "bun"] as const
-type Pm = (typeof PMS)[number]
-
-/** The runner each package manager uses for one-off CLIs. */
-const PM_RUNNER: Record<Pm, string> = {
-  npm: "npx",
-  pnpm: "pnpm dlx",
-  yarn: "yarn dlx",
-  bun: "bunx --bun",
-}
-
-const addCmd = (pm: Pm, item: string) =>
-  `${PM_RUNNER[pm]} shadcn@latest add ${item}`
-
-/* ------------------------------------------------------------------ data */
-
-const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug"]
-const series = MONTHS.map((month, i) => ({
-  month,
-  desktop: Math.round(120 + 90 * Math.sin(i * 0.7) + i * 14),
-  mobile: Math.round(70 + 50 * Math.cos(i * 0.5) + i * 8),
-}))
-const config: ChartConfig = {
-  desktop: { label: "Desktop", color: "blue" },
-  mobile: { label: "Mobile", color: "purple" },
-}
-const pieData = [
-  { browser: "chrome", visitors: 275 },
-  { browser: "safari", visitors: 200 },
-  { browser: "firefox", visitors: 187 },
-  { browser: "edge", visitors: 120 },
-  { browser: "other", visitors: 90 },
-]
-const pieConfig: ChartConfig = {
-  chrome: { label: "Chrome", color: "blue" },
-  safari: { label: "Safari", color: "green" },
-  firefox: { label: "Firefox", color: "orange" },
-  edge: { label: "Edge", color: "purple" },
-  other: { label: "Other", color: "grey" },
-}
-const radarData = [
-  { skill: "Speed", desktop: 186, mobile: 120 },
-  { skill: "Power", desktop: 205, mobile: 98 },
-  { skill: "Range", desktop: 137, mobile: 160 },
-  { skill: "Defense", desktop: 173, mobile: 125 },
-  { skill: "Magic", desktop: 160, mobile: 190 },
-  { skill: "Luck", desktop: 144, mobile: 110 },
-]
-
-/* ---------------------------------------------------------- live tweaks */
-
-const VARIANTS: AreaVariant[] = ["gradient", "dotted", "hatched", "solid"]
-const BLOOM_PRESETS = ["off", "low", "high", "aura", "custom"] as const
-type BloomPreset = (typeof BLOOM_PRESETS)[number]
-
-type Tweaks = {
-  bloomPreset: BloomPreset
-  blur: number
-  brightness: number
-  opacity: number
-  saturate: number
-  primaryVariant: AreaVariant
-  secondaryVariant: AreaVariant
-  stacked: boolean
-  donutRadius: number // 0 = full pie
-  duration: number // entrance ms
-}
-
-function bloomOf(t: Tweaks): BloomInput {
-  return t.bloomPreset === "custom"
-    ? {
-        blur: t.blur,
-        brightness: t.brightness,
-        opacity: t.opacity,
-        saturate: t.saturate,
-      }
-    : t.bloomPreset
-}
-
-/** How the current bloom reads in the code snippets. */
-function bloomAttr(t: Tweaks): string {
-  if (t.bloomPreset === "custom") {
-    return ` bloom={{ blur: ${t.blur}, brightness: ${t.brightness}, opacity: ${t.opacity}, saturate: ${t.saturate} }}`
-  }
-  return t.bloomPreset === "off" ? "" : ` bloom="${t.bloomPreset}"`
-}
-
-/* ------------------------------------------------------------ primitives */
-
-/** The page's signature motif: a strip of ordered-dither checkerboard that
- * fades out — the same texture the charts are made of, as page chrome. */
-function DitherStrip({ className = "" }: { className?: string }) {
-  return (
-    <div
-      aria-hidden
-      className={`text-border ${className}`}
-      style={{
-        backgroundImage:
-          "repeating-conic-gradient(currentColor 0% 25%, transparent 0% 50%)",
-        backgroundSize: "6px 6px",
-        maskImage:
-          "linear-gradient(to right, transparent, black 18%, black 82%, transparent)",
-      }}
-    />
-  )
-}
-
-/** Page-scoped theme. The app is dark-only, so instead of a global theme the
- * page swaps the `.dither-light` token overrides (and the `dark` class that
- * drives `dark:` variants) on its own wrapper. Persisted per visitor. */
-function usePageTheme() {
-  const [light, setLight] = useState(
-    () =>
-      typeof window !== "undefined" &&
-      window.localStorage.getItem("dither-kit-theme") === "light"
-  )
-  const toggle = () => {
-    setLight((v) => {
-      window.localStorage.setItem("dither-kit-theme", v ? "dark" : "light")
-      return !v
-    })
-  }
-  return { light, toggle }
-}
-
-function useCopy() {
-  const [copied, setCopied] = useState(false)
-  const copy = (text: string) => {
-    navigator.clipboard?.writeText(text)
-    setCopied(true)
-    setTimeout(() => setCopied(false), 1400)
-  }
-  return { copied, copy }
-}
-
-/** A copyable terminal line. */
-function CopyLine({ text }: { text: string }) {
-  const { copied, copy } = useCopy()
-  return (
-    <button
-      type="button"
-      onClick={() => copy(text)}
-      className="group flex w-full items-center justify-between gap-4 rounded-lg border bg-card/60 px-4 py-2.5 text-left font-mono text-xs text-foreground transition-colors hover:border-foreground/25 hover:bg-card"
-    >
-      <span className="truncate">
-        <span className="text-muted-foreground select-none">$ </span>
-        {text}
-      </span>
-      <span className="shrink-0 text-muted-foreground transition-colors group-hover:text-foreground">
-        {copied ? (
-          <CheckIcon className="size-3.5" />
-        ) : (
-          <CopyIcon className="size-3.5" />
-        )}
-      </span>
-    </button>
-  )
-}
-
-/* --------------------------------------------------- syntax highlighting */
-
-type TokenType = "comment" | "string" | "tag" | "attr" | "number" | "punct"
-
-const TOKEN_RE =
-  /(\/\/[^\n]*)|("(?:[^"\\]|\\.)*")|(<\/?[A-Za-z][\w.]*|\/?>)|(\b\d+(?:\.\d+)?\b|\btrue\b|\bfalse\b)|([A-Za-z_]\w*(?==))|([{}()[\]=|,:])/g
-
-const TOKEN_CLASS: Record<TokenType, string> = {
-  comment: "text-muted-foreground/60 italic",
-  string: "text-emerald-600 dark:text-emerald-400",
-  tag: "text-sky-600 dark:text-sky-400",
-  number: "text-orange-600 dark:text-orange-400",
-  attr: "text-violet-600 dark:text-violet-400",
-  punct: "text-muted-foreground/70",
-}
-
-type Token = { type: TokenType | null; text: string; start: number }
-
-/** Pure tokenizer — `matchAll` leaves the shared regex untouched, and each
- * token carries its source offset for a stable render key. */
-function tokenize(code: string): Token[] {
-  const tokens: Token[] = []
-  let last = 0
-  for (const m of code.matchAll(TOKEN_RE)) {
-    const start = m.index ?? 0
-    if (start > last)
-      tokens.push({ type: null, text: code.slice(last, start), start: last })
-    const type: TokenType = m[1]
-      ? "comment"
-      : m[2]
-        ? "string"
-        : m[3]
-          ? "tag"
-          : m[4]
-            ? "number"
-            : m[5]
-              ? "attr"
-              : "punct"
-    tokens.push({ type, text: m[0], start })
-    last = start + m[0].length
-  }
-  if (last < code.length)
-    tokens.push({ type: null, text: code.slice(last), start: last })
-  return tokens
-}
-
-/** Tiny JSX-ish highlighter for the docs snippets — no dependency, themed to
- * the dither palette, adapts to light and dark via classes. */
-function Code({ code }: { code: string }) {
-  return (
-    <>
-      {tokenize(code).map((t) =>
-        t.type ? (
-          <span key={t.start} className={TOKEN_CLASS[t.type]}>
-            {t.text}
-          </span>
-        ) : (
-          <Fragment key={t.start}>{t.text}</Fragment>
-        )
-      )}
-    </>
-  )
-}
-
-function CodeBlock({ code }: { code: string }) {
-  const { copied, copy } = useCopy()
-  return (
-    <div className="group relative">
-      <pre className="h-full overflow-x-auto rounded-lg border bg-card/60 p-4 font-mono text-[11px] leading-relaxed text-muted-foreground">
-        <code>
-          <Code code={code} />
-        </code>
-      </pre>
-      <button
-        type="button"
-        onClick={() => copy(code)}
-        aria-label="Copy code"
-        className="absolute top-2 right-2 rounded-md border bg-background/80 p-1.5 text-muted-foreground opacity-0 backdrop-blur transition-opacity group-hover:opacity-100 hover:text-foreground focus-visible:opacity-100"
-      >
-        {copied ? (
-          <CheckIcon className="size-3" />
-        ) : (
-          <CopyIcon className="size-3" />
-        )}
-      </button>
-    </div>
-  )
-}
-
-/** Tiny pill toggle used for tabs and boolean tweaks. */
-function Pill({
-  label,
-  active,
-  onClick,
-}: {
-  label: string
-  active?: boolean
-  onClick: () => void
-}) {
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      aria-pressed={active}
-      className={`rounded-md border px-2 py-1 font-mono text-[11px] transition-colors ${
-        active
-          ? "border-transparent bg-primary text-primary-foreground"
-          : "text-muted-foreground hover:border-foreground/25 hover:text-foreground"
-      }`}
-    >
-      {label}
-    </button>
-  )
-}
-
-function ReplayButton({ onClick }: { onClick: () => void }) {
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      aria-label="Replay entrance animation"
-      className="rounded-md border p-1.5 text-muted-foreground transition-colors hover:border-foreground/25 hover:text-foreground"
-    >
-      <RefreshCcwIcon className="size-3.5" />
-    </button>
-  )
-}
-
-/* -------------------------------------------------------------- showcase */
-
-function Showcase({
-  title,
-  install,
-  code,
-  toolbar,
-  children,
-  tall = false,
-}: {
-  title: string
-  install: string
-  code: string
-  /** Extra controls rendered in the card toolbar (e.g. replay). */
-  toolbar?: ReactNode
-  children: ReactNode
-  tall?: boolean
-}) {
-  const [tab, setTab] = useState<"preview" | "code">("preview")
-  const { copied, copy } = useCopy()
-  return (
-    <section
-      id={title.toLowerCase().replace(/[^a-z]+/g, "-")}
-      className="flex flex-col gap-4"
-    >
-      {/* Header row */}
-      <div className="flex flex-wrap items-center gap-2">
-        <h3 className="font-pixel-geist text-sm text-foreground">{title}</h3>
-        <button
-          type="button"
-          onClick={() => copy(install)}
-          className="hidden items-center gap-1.5 font-mono text-[11px] text-muted-foreground transition-colors hover:text-foreground sm:flex"
-        >
-          {copied ? (
-            <CheckIcon className="size-3" />
-          ) : (
-            <CopyIcon className="size-3" />
-          )}
-          {install.split(" add ").pop()}
-        </button>
-        <div className="ml-auto flex items-center gap-1.5">
-          {toolbar}
-          <Pill
-            label="preview"
-            active={tab === "preview"}
-            onClick={() => setTab("preview")}
-          />
-          <Pill
-            label="code"
-            active={tab === "code"}
-            onClick={() => setTab("code")}
-          />
-        </div>
-      </div>
-
-      {/* Body */}
-      {tab === "preview" ? (
-        <div className={`relative ${tall ? "h-80" : "h-64"}`}>{children}</div>
-      ) : (
-        <div className={`${tall ? "h-80" : "h-64"} overflow-y-auto`}>
-          <CodeBlock code={code} />
-        </div>
-      )}
-    </section>
-  )
-}
-
-/* ------------------------------------------------------------------ page */
-
 function DitherKitDocs() {
   const { light, toggle: toggleTheme } = usePageTheme()
   const [pm, setPm] = useState<Pm>("npm")
 
   // One replay counter per showcase so a replay never re-runs its neighbours.
-  const [replays, setReplays] = useState({
+  const [replays, setReplays] = useState<Replays>({
     hero: 0,
     area: 0,
     bar: 0,
@@ -409,14 +40,14 @@ function DitherKitDocs() {
     pie: 0,
     radar: 0,
   })
-  const replay = (key: keyof typeof replays) =>
+  const replay = (key: ReplayKey) =>
     setReplays((r) => ({ ...r, [key]: r[key] + 1 }))
   const replayAll = () =>
     setReplays(
       (r) =>
         Object.fromEntries(
           Object.entries(r).map(([k, v]) => [k, v + 1])
-        ) as typeof replays
+        ) as Replays
     )
 
   // The live tweak panel — DialKit (https://joshpuckett.me/dialkit) renders a
@@ -473,12 +104,7 @@ function DitherKitDocs() {
   }
   const bloom = bloomOf(tweaks)
 
-  // Register the namespace once, then install any chart by name.
-  const registries = `// components.json\n{\n  "registries": {\n    "@dither-kit": "${HOST}/r/{name}.json"\n  }\n}`
-
   return (
-    // The tweak panel docks on the right; content slides over so the charts
-    // stay in view while you turn the knobs.
     <div
       className={`min-h-screen bg-background text-foreground ${
         light ? "dither-light" : "dark"
@@ -487,335 +113,25 @@ function DitherKitDocs() {
       <DitherStrip className="h-2 w-full" />
 
       <div className="mx-auto flex max-w-4xl flex-col gap-20 px-6 py-16">
-        {/* Hero */}
-        <header className="flex flex-col gap-8">
-          <div className="flex items-start justify-between gap-4">
-            <div className="flex flex-col gap-1.5">
-              <h1 className="font-pixel-geist text-4xl text-foreground sm:text-5xl">
-                dither-kit
-              </h1>
-              <p className="font-mono text-xs text-muted-foreground">
-                five chart types on one tiny canvas engine, no recharts
-              </p>
-            </div>
-            <button
-              type="button"
-              aria-label="Toggle theme"
-              onClick={toggleTheme}
-              className="rounded-md border p-2 text-muted-foreground transition-colors hover:border-foreground/25 hover:text-foreground"
-            >
-              {light ? (
-                <MoonIcon className="size-4" />
-              ) : (
-                <SunIcon className="size-4" />
-              )}
-            </button>
-          </div>
-
-          <p className="max-w-2xl leading-relaxed text-balance text-muted-foreground">
-            Composable, <span className="text-foreground">dithered</span> charts
-            with a recharts-style children-as-config API. Ordered-dither fills
-            that hold up in light and dark, entrance animations, a gliding scrub
-            tooltip, selection, winking sparkles, and colour bloom.
-          </p>
-
-          {/* Hero chart */}
-          <div className="flex flex-col gap-3">
-            <div className="flex items-center justify-between">
-              <span className="font-mono text-xs text-muted-foreground">
-                scrub it, hover a legend entry to spotlight that series, click
-                to lock it
-              </span>
-              <ReplayButton onClick={() => replay("hero")} />
-            </div>
-            <div className="h-72">
-              <AreaChart
-                data={series}
-                config={config}
-                stackType={tweaks.stacked ? "stacked" : "default"}
-                bloom={bloom}
-                animationDuration={tweaks.duration}
-                replayToken={replays.hero}
-              >
-                <XAxis dataKey="month" />
-                <YAxis />
-                <Legend isClickable />
-                <Tooltip labelKey="month" />
-                <Area
-                  dataKey="desktop"
-                  variant={tweaks.primaryVariant}
-                  strokeVariant="dashed"
-                  isClickable
-                >
-                  <ActiveDot variant="colored-border" />
-                </Area>
-                <Area
-                  dataKey="mobile"
-                  variant={tweaks.secondaryVariant}
-                  isClickable
-                >
-                  <ActiveDot variant="colored-border" />
-                </Area>
-              </AreaChart>
-            </div>
-          </div>
-        </header>
-
-        {/* Install */}
-        <section className="flex flex-col gap-5">
-          <div className="flex items-center gap-3">
-            <h2 className="font-pixel-geist text-lg text-foreground">
-              install
-            </h2>
-            <DitherStrip className="h-1.5 flex-1" />
-            <div className="flex items-center gap-1.5">
-              {PMS.map((p) => (
-                <Pill
-                  key={p}
-                  label={p}
-                  active={pm === p}
-                  onClick={() => setPm(p)}
-                />
-              ))}
-            </div>
-          </div>
-
-          <div className="grid gap-6 md:grid-cols-2">
-            <div className="flex flex-col gap-2">
-              <span className="font-mono text-xs text-muted-foreground">
-                1. register the namespace in{" "}
-                <span className="text-foreground">components.json</span>
-              </span>
-              <CodeBlock code={registries} />
-            </div>
-            <div className="flex flex-col gap-2">
-              <span className="font-mono text-xs text-muted-foreground">
-                2. add charts — each pulls{" "}
-                <span className="text-foreground">@dither-kit/core</span>{" "}
-                automatically
-              </span>
-              <div className="flex flex-col gap-1.5">
-                <CopyLine text={addCmd(pm, "@dither-kit/area-chart")} />
-                <CopyLine text={addCmd(pm, "@dither-kit/pie-chart")} />
-                <CopyLine text={addCmd(pm, "@dither-kit/dither-kit")} />
-              </div>
-            </div>
-          </div>
-
-          <p className="font-mono text-[11px] leading-relaxed text-muted-foreground">
-            also available: <span className="text-foreground">bar-chart</span>{" "}
-            and <span className="text-foreground">radar-chart</span>.{" "}
-            <span className="text-foreground">@dither-kit/dither-kit</span>{" "}
-            grabs everything. skipping the namespace config? the raw URL works:{" "}
-            <span className="text-foreground">
-              shadcn add {HOST}/r/radar-chart.json
-            </span>
-            . files land in{" "}
-            <span className="text-foreground">components/dither-kit/</span>.
-          </p>
-        </section>
-
-        {/* Credit */}
-        <aside className="flex flex-col gap-3">
-          <DitherStrip className="h-1.5 w-full" />
-          <p className="max-w-2xl text-sm leading-relaxed">
-            <span className="font-pixel-geist text-foreground">
-              huge thanks to Evil Charts.
-            </span>{" "}
-            <span className="text-muted-foreground">
-              dither-kit exists because of{" "}
-              <a
-                href="https://www.evilcharts.com"
-                target="_blank"
-                rel="noreferrer"
-                className="text-foreground underline underline-offset-2 hover:text-muted-foreground"
-              >
-                Evil Charts
-              </a>{" "}
-              by{" "}
-              <a
-                href="https://github.com/legions-developer/evilcharts"
-                target="_blank"
-                rel="noreferrer"
-                className="text-foreground underline underline-offset-2 hover:text-muted-foreground"
-              >
-                legions-developer
-              </a>{" "}
-              — the original dithered, composable chart aesthetic that inspired
-              every pixel here. Even the per-chart{" "}
-              <span className="text-foreground">@namespace/chart</span> install
-              flow is theirs. Go star it.
-            </span>
-          </p>
-        </aside>
-
-        {/* Gallery */}
-        <div className="flex flex-col gap-14">
-          <div className="flex items-center gap-3">
-            <h2 className="font-pixel-geist text-lg text-foreground">charts</h2>
-            <DitherStrip className="h-1.5 flex-1" />
-            <span className="font-mono text-xs text-muted-foreground">
-              tweak these charts from the floating dial panel →
-            </span>
-          </div>
-
-          <Showcase
-            title="area"
-            install={addCmd(pm, "@dither-kit/area-chart")}
-            code={areaCode(tweaks)}
-            toolbar={<ReplayButton onClick={() => replay("area")} />}
-          >
-            <AreaChart
-              data={series}
-              config={config}
-              stackType={tweaks.stacked ? "stacked" : "default"}
-              bloom={bloom}
-              animationDuration={tweaks.duration}
-              replayToken={replays.area}
-            >
-              <XAxis dataKey="month" />
-              <YAxis />
-              <Legend isClickable />
-              <Tooltip labelKey="month" />
-              <Area dataKey="desktop" variant={tweaks.primaryVariant} />
-              <Area dataKey="mobile" variant={tweaks.secondaryVariant} />
-            </AreaChart>
-          </Showcase>
-
-          <Showcase
-            title="bar"
-            install={addCmd(pm, "@dither-kit/bar-chart")}
-            code={barCode(tweaks)}
-            toolbar={<ReplayButton onClick={() => replay("bar")} />}
-          >
-            <BarChart
-              data={series}
-              config={config}
-              stackType={tweaks.stacked ? "stacked" : "default"}
-              bloom={bloom}
-              animationDuration={tweaks.duration}
-              replayToken={replays.bar}
-            >
-              <XAxis dataKey="month" />
-              <YAxis />
-              <Legend isClickable />
-              <Tooltip labelKey="month" />
-              <Bar dataKey="desktop" variant={tweaks.primaryVariant} />
-              <Bar dataKey="mobile" variant={tweaks.secondaryVariant} />
-            </BarChart>
-          </Showcase>
-
-          <Showcase
-            title="line"
-            install={addCmd(pm, "@dither-kit/area-chart")}
-            code={lineCode(tweaks)}
-            toolbar={<ReplayButton onClick={() => replay("line")} />}
-          >
-            <LineChart
-              data={series}
-              config={config}
-              bloom={bloom}
-              animationDuration={tweaks.duration}
-              replayToken={replays.line}
-            >
-              <XAxis dataKey="month" />
-              <YAxis />
-              <Legend isClickable />
-              <Tooltip labelKey="month" />
-              <Line dataKey="desktop" />
-              <Line dataKey="mobile" strokeVariant="dashed" />
-            </LineChart>
-          </Showcase>
-
-          <div className="grid gap-14 lg:grid-cols-2 lg:gap-8">
-            <Showcase
-              title="pie"
-              install={addCmd(pm, "@dither-kit/pie-chart")}
-              code={pieCode(tweaks)}
-              tall
-              toolbar={<ReplayButton onClick={() => replay("pie")} />}
-            >
-              <PieChart
-                data={pieData}
-                config={pieConfig}
-                dataKey="visitors"
-                nameKey="browser"
-                innerRadius={tweaks.donutRadius}
-                bloom={bloom}
-                animationDuration={tweaks.duration}
-                replayToken={replays.pie}
-              >
-                <Legend isClickable align="center" />
-                <Tooltip />
-                <Pie variant={tweaks.primaryVariant} />
-              </PieChart>
-            </Showcase>
-
-            <Showcase
-              title="radar"
-              install={addCmd(pm, "@dither-kit/radar-chart")}
-              code={radarCode(tweaks)}
-              tall
-              toolbar={<ReplayButton onClick={() => replay("radar")} />}
-            >
-              <RadarChart
-                data={radarData}
-                config={config}
-                nameKey="skill"
-                bloom={bloom}
-                animationDuration={tweaks.duration}
-                replayToken={replays.radar}
-              >
-                <Legend isClickable align="center" />
-                <Tooltip />
-                <Radar dataKey="desktop" variant={tweaks.primaryVariant} />
-                <Radar dataKey="mobile" variant={tweaks.secondaryVariant} />
-              </RadarChart>
-            </Showcase>
-          </div>
-        </div>
-
-        {/* Props reference */}
-        <section className="flex flex-col gap-4">
-          <div className="flex items-baseline gap-3">
-            <h2 className="font-pixel-geist text-lg text-foreground">knobs</h2>
-            <DitherStrip className="h-1.5 flex-1 self-center" />
-          </div>
-          <dl className="flex flex-col gap-2.5 font-mono text-xs">
-            {PROPS.map(([prop, desc]) => (
-              <div
-                key={prop}
-                className="grid items-baseline gap-1.5 sm:grid-cols-[10rem_1fr] sm:gap-4"
-              >
-                <dt>
-                  <code className="w-fit rounded-md border bg-card px-1.5 py-0.5 text-[11px] text-violet-600 dark:text-violet-400">
-                    {prop}
-                  </code>
-                </dt>
-                <dd className="leading-relaxed text-muted-foreground">
-                  <Code code={desc} />
-                </dd>
-              </div>
-            ))}
-          </dl>
-          <CodeBlock code={SPARKLINE_CODE} />
-        </section>
-
-        {/* Footer */}
-        <footer className="flex flex-wrap items-center justify-between gap-3 border-t pt-6 text-xs text-muted-foreground">
-          <span className="font-pixel-geist">dither-kit</span>
-          <span className="font-mono">
-            built on the shoulders of{" "}
-            <a
-              href="https://www.evilcharts.com"
-              target="_blank"
-              rel="noreferrer"
-              className="text-foreground underline underline-offset-2"
-            >
-              Evil Charts
-            </a>
-          </span>
-        </footer>
+        <HeroSection
+          light={light}
+          onToggleTheme={toggleTheme}
+          tweaks={tweaks}
+          bloom={bloom}
+          replayToken={replays.hero}
+          onReplay={() => replay("hero")}
+        />
+        <InstallSection pm={pm} onPmChange={setPm} />
+        <CreditAside />
+        <ChartGallery
+          pm={pm}
+          tweaks={tweaks}
+          bloom={bloom}
+          replays={replays}
+          onReplay={replay}
+        />
+        <KnobsSection />
+        <DocsFooter />
       </div>
 
       <DitherStrip className="h-2 w-full" />
@@ -823,71 +139,3 @@ function DitherKitDocs() {
     </div>
   )
 }
-
-/* ------------------------------------------------------------- snippets */
-
-const stackAttr = (t: Tweaks) => (t.stacked ? ' stackType="stacked"' : "")
-
-const areaCode = (t: Tweaks) =>
-  `<AreaChart data={data} config={config}${stackAttr(t)}${bloomAttr(t)}>
-  <XAxis dataKey="month" />
-  <YAxis />
-  <Legend isClickable />
-  <Tooltip labelKey="month" />
-  <Area dataKey="desktop" variant="${t.primaryVariant}" />
-  <Area dataKey="mobile" variant="${t.secondaryVariant}" />
-</AreaChart>`
-
-const barCode = (t: Tweaks) =>
-  `<BarChart data={data} config={config}${stackAttr(t)}${bloomAttr(t)}>
-  <XAxis dataKey="month" />
-  <YAxis />
-  <Legend isClickable />
-  <Tooltip labelKey="month" />
-  <Bar dataKey="desktop" variant="${t.primaryVariant}" />
-  <Bar dataKey="mobile" variant="${t.secondaryVariant}" />
-</BarChart>`
-
-const lineCode = (t: Tweaks) =>
-  `// LineChart ships in the area-chart item (line = area + glow)
-<LineChart data={data} config={config}${bloomAttr(t)}>
-  <XAxis dataKey="month" />
-  <YAxis />
-  <Legend isClickable />
-  <Tooltip labelKey="month" />
-  <Line dataKey="desktop" />
-  <Line dataKey="mobile" strokeVariant="dashed" />
-</LineChart>`
-
-const pieCode = (t: Tweaks) =>
-  `<PieChart data={data} config={config}
-  dataKey="visitors" nameKey="browser"${
-    t.donutRadius > 0 ? ` innerRadius={${t.donutRadius}}` : ""
-  }${bloomAttr(t)}>
-  <Legend isClickable align="center" />
-  <Tooltip />
-  <Pie variant="${t.primaryVariant}" />
-</PieChart>`
-
-const radarCode = (t: Tweaks) =>
-  `<RadarChart data={data} config={config} nameKey="skill"${bloomAttr(t)}>
-  <Legend isClickable align="center" />
-  <Tooltip />
-  <Radar dataKey="desktop" variant="${t.primaryVariant}" />
-  <Radar dataKey="mobile" variant="${t.secondaryVariant}" />
-</RadarChart>`
-
-const PROPS: [string, string][] = [
-  ["variant", '"gradient" | "dotted" | "hatched" | "solid"'],
-  [
-    "bloom",
-    '"off" | "low" | "high" | "aura" | { blur, brightness, opacity, saturate }',
-  ],
-  ["stackType", '"default" | "stacked" | "percent"'],
-  ["colors", "green blue purple pink orange red grey"],
-  ["animate", "animationDuration + replayToken for entrance and replay"],
-  ["interactive", "false = decorative spark, no crosshair or tooltip"],
-]
-
-const SPARKLINE_CODE = `// tiny decorative spark — no axes, no tooltip
-<Sparkline data={[3, 7, 5, 9, 8, 12]} color="green" bloom="aura" />`

From 3c16dc4308c9d45cfdfb0d87e387083fd7a2a2af Mon Sep 17 00:00:00 2001
From: grim <75869731+ripgrim@users.noreply.github.com>
Date: Sat, 4 Jul 2026 00:42:12 -0700
Subject: [PATCH 5/5] chore: format biome.json

---
 apps/web/biome.json | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/apps/web/biome.json b/apps/web/biome.json
index 971ccfe..98aa695 100644
--- a/apps/web/biome.json
+++ b/apps/web/biome.json
@@ -61,9 +61,7 @@
       }
     },
     {
-      "includes": [
-        "**/components/icons/**/*.tsx"
-      ],
+      "includes": ["**/components/icons/**/*.tsx"],
       "linter": {
         "rules": {
           "correctness": {
@@ -73,9 +71,7 @@
       }
     },
     {
-      "includes": [
-        "**/packages/ui/src/icons/**/*.tsx"
-      ],
+      "includes": ["**/packages/ui/src/icons/**/*.tsx"],
       "linter": {
         "rules": {
           "correctness": {