@kanzo-tech/theme 0.0.1-alpha

package/tokens.css

@@ -0,0 +1,311 @@
+/*
+ * @kanzo-tech/theme — the utility surface. HAND-WRITTEN, all of it.
+ *
+ * This file used to have two halves: a hand-written one and a generated one carrying a compiled
+ * palette document. **The generated half is gone**, and with it the thirteen-stage derivation that
+ * produced it. A theme is now `themes/<name>.css` — one flat block of about fifty-five
+ * declarations that a person writes, pastes, reviews and diffs. See
+ * `.planning/THEME-REFOUNDATION.md`.
+ *
+ * What is left here is the bridge: `@theme inline` is what makes `bg-primary` and
+ * `text-muted-foreground` resolve to a theme's tokens and follow it live. Plus the shape scale, the
+ * font stacks, two keyframes and the element-level base layer.
+ *
+ * ## Twenty-one carry a value; everything else uses one
+ *
+ * A theme authors twenty-one colours. Every other name in the vocabulary is a *use* of one of
+ * them, declared once, here. That is the rule from `a-role-earns-its-name-or-becomes-a-step`
+ * applied to the whole system rather than to the reference tier: a name is worth having when a
+ * theme would plausibly give it a different value, and a name that can only ever repeat another is
+ * a second spelling.
+ *
+ * Eight names were measured against that rule and lost. Across the sixteen hand-written blocks that
+ * authored them, `--card-foreground` and `--popover-foreground` were byte-identical to
+ * `--foreground`, and six of the eight sidebar tokens were byte-identical to the core token they
+ * shadow — ninety-six declarations writing a value that was already written. Nothing authors any of
+ * the eight today, in any of the twenty-nine. The NAMES stay, because Shark's recipes paste them
+ * verbatim and that clause is what keeps a Shark name alive. What stopped is authoring them per
+ * theme. `themes.test.ts` resolves each deleted name through this bridge in every shipped theme and
+ * fails if a fallback lands somewhere other than the token it replaced, so this is checked rather
+ * than remembered.
+ *
+ * ## Why they are bridged here and NOT declared in `:root`
+ *
+ * This is the trap, and it is worth the paragraph because nothing about it is a compile error.
+ *
+ * `:root { --sidebar-primary: var(--primary) }` looks equivalent and is not. A custom property
+ * inherits its **computed** value: `--sidebar-primary` resolves once, on `<html>`, against that
+ * element's `--primary`. A scoped preview — `<div data-theme="dracula">` — sets a new `--primary`
+ * on the div, but `--sidebar-primary` was already substituted on the ancestor and inherits that
+ * old value. The div renders Dracula's brand with Nord's sidebar, silently.
+ *
+ * `@theme inline` has no such problem: Tailwind inlines the value into the *utility*, so
+ * `bg-sidebar-primary` compiles to `background-color: var(--primary)` and the `var()` is resolved
+ * on the element that wears the class. Scoped themes work, and they work at any nesting depth.
+ *
+ * That is also why the whole colour vocabulary is bridged and none of it is re-declared: a theme
+ * block is self-contained by construction, which is the property that makes a preview a `div`.
+ *
+ * ## The status families keep Shark's asymmetry
+ *
+ * For NEUTRAL and BRAND, the base name is the fill and `-foreground` is the ink meant to sit on it.
+ * The STATUS families do not follow that rule, and this is inherited from Shark verbatim — do not
+ * "fix" it, it would fork us. There, `-foreground` is a *readable-on-the-page variant of the same
+ * hue*: error text, invalid rings, destructive menu items — never text on the fill. On-fill ink is
+ * a third token per family, `--*-content`, which is daisyUI's word for exactly this role.
+ */
+
+@theme inline {
+  /* ── The twenty-one a theme authors ───────────────────────────────────────── */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground, var(--foreground));
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground, var(--foreground));
+  --color-destructive: var(--destructive);
+  --color-destructive-content: var(--destructive-content);
+  --color-info: var(--info);
+  --color-info-content: var(--info-content);
+  --color-success: var(--success);
+  --color-success-content: var(--success-content);
+  --color-warning: var(--warning);
+  --color-warning-content: var(--warning-content);
+  --color-border: var(--border);
+  --color-ring: var(--ring);
+
+  /* ── Authored today, pending a measured `color-mix` default ───────────────────
+     Each of these is NOT an alias in any shipped theme — measured — so none of them could be
+     dropped without moving a real value. Each is its own question later; the fallback is what a
+     theme that omits it gets. */
+  --color-popover: var(--popover, var(--card));
+  --color-popover-foreground: var(--foreground);
+  --color-card-foreground: var(--foreground);
+  --color-input: var(--input, var(--border));
+  --color-field: var(--field, var(--muted));
+  --color-faint: var(--faint, var(--muted-foreground));
+  --color-destructive-foreground: var(--destructive-foreground, var(--destructive));
+  --color-info-foreground: var(--info-foreground, var(--info));
+  --color-success-foreground: var(--success-foreground, var(--success));
+  --color-warning-foreground: var(--warning-foreground, var(--warning));
+
+  /* ── Sidebar: none authored, eight that only ever repeated ───────────────────
+     `--sidebar` was `--popover` in all sixteen hand-written themes and `--sidebar-foreground` was
+     `--muted-foreground` in all sixteen, so the fallbacks point there and the themes stopped
+     writing them. The chain for `--sidebar` runs on to `--card`, which is where `--popover` itself
+     defers. A theme that wants a sidebar of its own still says so; none of the twenty-nine does
+     today, and the thirteen imported from daisyUI never had a sidebar channel to carry. */
+  --color-sidebar: var(--sidebar, var(--popover, var(--card)));
+  --color-sidebar-foreground: var(--sidebar-foreground, var(--muted-foreground));
+  --color-sidebar-border: var(--border);
+  --color-sidebar-primary: var(--primary);
+  --color-sidebar-primary-foreground: var(--primary-foreground);
+  --color-sidebar-accent: var(--accent);
+  --color-sidebar-accent-foreground: var(--accent-foreground);
+  --color-sidebar-ring: var(--ring);
+
+  /* ── The categorical set ──────────────────────────────────────────────────────
+     A theme authors these or it does not; the eight it gets by saying nothing are DECLARED in the
+     `:root` block at the foot of this file rather than written as a fallback here, and the note
+     there says why this one default is a value where every other is an alias. */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-chart-6: var(--chart-6);
+  --color-chart-7: var(--chart-7);
+  --color-chart-8: var(--chart-8);
+
+  /* ── Shape: three radius knobs where there was one ────────────────────────────
+     daisyUI's split, and it buys something the single knob could not express — a rounded selector
+     beside a square card. The size scale below is unchanged and still hangs off ONE knob, so every
+     existing `rounded-*` call site keeps its pixels; `--radius` now defaults to `--radius-field`,
+     which is the knob a button and an input answer to. Recipes migrate to the three role
+     utilities (`rounded-box` / `rounded-field` / `rounded-selector`) component by component.
+
+     Multiplicative, which is Shark's exact ratios: every step is a multiple of one knob, so the
+     scale holds its proportions at any setting and `0` collapses cleanly to square. An additive
+     `calc(--radius - Npx)` scale diverges off the default and clamps small corners to 0 — that was
+     the bug.
+
+     The size scale hangs off `--radius-field` DIRECTLY rather than off an intermediate `--radius`,
+     and that is not a tidy-up: an intermediate declared in `:root` inherits already substituted, so
+     a scoped `<div data-theme>` with a different field radius would never reach it. Same trap as the
+     colour bridge above, same fix — resolve in the utility, on the element. */
+  --radius-box: var(--radius-box, 0.75rem);
+  --radius-field: var(--radius-field, 0.5rem);
+  --radius-selector: var(--radius-selector, 0.25rem);
+
+  --radius-xs: calc(var(--radius-field, 0.5rem) * 0.25);
+  --radius-sm: calc(var(--radius-field, 0.5rem) * 0.5);
+  --radius-md: calc(var(--radius-field, 0.5rem) * 0.75);
+  --radius-lg: calc(var(--radius-field, 0.5rem) * 1);
+  --radius-xl: calc(var(--radius-field, 0.5rem) * 1.5);
+  --radius-2xl: calc(var(--radius-field, 0.5rem) * 2);
+  --radius-3xl: calc(var(--radius-field, 0.5rem) * 3);
+  --radius-4xl: calc(var(--radius-field, 0.5rem) * 4);
+
+  /* Fonts — a theme may carry them now, so a tenant ships a typeface with their colours. These
+     are the fallbacks, and the shape is Shark's. daisyUI has no font in its theme at all; keeping
+     `--font-heading` separate from `--font-sans` is the single most identity-carrying typographic
+     choice a white-label document can make. */
+  --font-sans: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  --font-heading: var(--font-heading, ui-sans-serif, system-ui, sans-serif);
+  --font-mono: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+
+  /* Height-based expand/collapse for Ark Collapsible / TreeView. Ark supplies `--height`
+     at runtime (tw-animate-css can't measure it), so we ship the `expand`/`collapse` pair
+     its components reference. These live in the TOKEN layer, not the bundled `styles.css`,
+     because Tailwind-native consumers (the playground, keasy) scan the DS source and emit
+     `animate-expand` / `animate-[collapse_…]` themselves — they import these tokens, not
+     the compiled sheet. Without the keyframes here the exit animation never runs, so Ark's
+     `unmountOnExit` never fires its `animationend` and collapsed branches stay mounted. */
+  --animate-expand: expand 200ms ease-out;
+  --animate-collapse: collapse 200ms ease-out;
+
+  /* The arrival of one streamed word — `MessageText` in `@kanzo-tech/ai`. Here for the reason the
+     pair above is here: a Tailwind-native consumer scans the source, emits `animate-arrive`
+     itself, and would otherwise get a utility with no keyframes behind it.
+
+     The numbers are Streamdown's, which is what AI Elements renders a streamed answer with:
+     150ms and `ease`, not a longer curve — the cascade is what reads as writing, and a slow word
+     reads as a page loading. `both`, so a word scheduled behind the cascade holds at `opacity: 0`
+     until its delay elapses. */
+  --animate-arrive: arrive 150ms ease both;
+}
+
+@keyframes expand {
+  from { height: 0; }
+  to { height: var(--height); }
+}
+@keyframes collapse {
+  from { height: var(--height); }
+  to { height: 0; }
+}
+/* Opacity and nothing else, which is `sd-fadeIn` — Streamdown's default of three. Its other two
+   are `sd-blurIn` (a 4px blur out) and `sd-slideUp` (a 4px rise); neither is here, because one
+   arrival is the fundamental and the other two are taste with a compositing cost.
+
+   An earlier draft of this tinted the word and settled it to `inherit`. That was not taken from
+   anywhere: no reference colours a word by who wrote it, and the tint made the settle a second
+   event to get right. */
+@keyframes arrive {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* Element-level base defaults that the COMPONENTS depend on (Shark's canonical base
+   layer). These live in the token layer — not the bundled `styles.css` — because Shark's
+   primitives write bare `border` / `border-t` (no colour) and rely on this rule to paint
+   them with `--border`; without it, Tailwind v4 falls back to `currentColor`, so every
+   card/dialog/table border inherits the (dark) text colour instead. Tailwind-native
+   consumers (the playground, keasy) import these tokens, not the compiled sheet, so the
+   rule must ship here for their borders + focus outlines to resolve correctly.
+   Document/app-shell defaults (`html`, `body`) stay in `styles.css` — a library shouldn't
+   impose page background on a Tailwind-native consumer.
+
+   `border-width` reads the theme's `--stroke` rather than Tailwind's 1px, which is what makes
+   "this tenant draws a 2px hairline" a theme declaration instead of a fork. `--stroke` and not
+   `--border`, because `--border` is the line COLOUR here and the width in daisyUI — one of the two
+   had to move, and renaming ours would have forked every Shark recipe. */
+@layer base {
+  *,
+  ::after,
+  ::before {
+    @apply border-border outline-ring/50;
+    border-width: 0;
+    border-style: solid;
+  }
+  ::selection {
+    @apply bg-primary/80 text-primary-foreground;
+  }
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+}
+
+:root {
+  /* ── The categorical set a theme gets by saying nothing ───────────────────────
+     Sixteen themes author their own; thirteen do not, because daisyUI has no such channel to
+     import, and their slots resolved to nothing.
+
+     **Declared here, not bridged, and it is the one fallback in this file that is a literal.**
+     Every other name above defers to another token, so it must resolve on the element that uses
+     it — hence `@theme inline`. These defer to nothing: they are values. That makes a plain `:root`
+     declaration correct where it would be a bug anywhere else, and it is the only shape that
+     works, because a chart does not read a utility. `categoricalColor` returns `var(--chart-N)`
+     and the chart pipeline resolves it against the live element, so a fallback written into the
+     bridge would reach `bg-chart-1` and never reach a mark. Declared here it inherits, a
+     `[data-theme]` block overrides it slot by slot on the element that carries it, and both paths
+     get the same answer.
+
+     Chosen by search under the bars a chart is actually read against, all of them re-run by
+     `categorical.test.ts` over the shipped files rather than trusted here:
+
+       · every slot inside OKLCH L 0.48–0.67, the INTERSECTION of the light band (0.43–0.77) and
+         the dark one — the only way one set is in band on `#ffffff` and on `#09002f`;
+       · ≥ 3:1 against **all twenty-nine** backgrounds, not against the two ends. The ends are not
+         the hard case: `dim` (#2a303c) and `cyberpunk` (#fff248) between them leave a window of
+         relative luminance 0.188–0.251, and a set validated only at the extremes failed on six
+         themes in the middle;
+       · worst adjacent pair 17.6 ΔE under protan/deutan simulation, 14.4 under tritan and 21.4 to
+         normal vision. The old per-document bar was 15;
+       · ≥ 8 ΔE from all fifty-two distinct status fills the twenty-nine publish, so a series does
+         not read as a state.
+
+     There is no deriving these from `--primary`: `--chart-6` takes twelve distinct values across
+     the sixteen authored sets. A set answers to *separation*, which is a property of the eight
+     together.
+
+     A theme that declines the channel outright still says so with `--chart-capacity: 0`, and these
+     colours simply go unread — `monochrome` is the one, and `monochrome-is-a-palette-not-a-look`
+     is the record. */
+  --chart-1: #aa5aee;
+  --chart-2: #dc356d;
+  --chart-3: #737fee;
+  --chart-4: #b36d2a;
+  --chart-5: #2d84bf;
+  --chart-6: #96822c;
+  --chart-7: #d036b6;
+  --chart-8: #6a8a2a;
+
+  /* The shape knobs with no theme applied. Plain values, never `var()` of one another — see the
+     inheritance note on the radius scale. `themes.css` re-points them per `data-radius`, which is
+     the user's preference layered over the theme's own declaration.
+
+     There is no `--radius` any more. It was one knob standing for three, and the size-named
+     utilities now answer to `--radius-field` — `rounded-lg` sits on a button far more often than
+     on a card. */
+  --stroke: 1px;
+  --depth: 0;
+  --size-field: 0.25rem;
+  --size-selector: 0.25rem;
+
+  /* ── The three type sizes below Tailwind's floor ──────────────────────────────
+     Not in Shark, and not in Tailwind either: its scale stops at `text-xs`, 12px. These are the
+     IDE tier — a code pane, a preferences label, a marker badge — and they exist because the
+     smallest thing Tailwind offers is too big for all three.
+
+     **They were deleted by `6c602df` and three components kept asking for them**, which is why
+     this comment is longer than the block. That commit's subject is colour and its scope was the
+     colour half of this file; the block went with it, and nothing failed — an undefined custom
+     property makes `font-size` invalid at computed-value time, so the declaration is dropped and
+     the element silently inherits. Measured on 2026-08-23: `Badge size="xs"` computed 16px inside
+     its own `h-4` box, and since the recipe carries `overflow-hidden` the text was clipped by
+     3px — a 19px content in a 16px box, visible in `app-shell` and `job-studio` and in no test.
+     `theme-tokens.test.ts` is the guard that makes the next deletion fail out loud.
+
+     `CodeEditor` reads two of these with a literal fallback and so kept rendering — at 14px and
+     12px rather than 13px and 11px. That is the same defect wearing a fallback, and it is the
+     reason a fallback is not the fix here. */
+  --kanzo-font-size-base: 0.8125rem;   /* 13px — IDE base (below Tailwind text-xs) */
+  --kanzo-font-size-small: 0.6875rem;  /* 11px */
+  --kanzo-font-size-xs: 0.625rem;      /* 10px — `obligations.ts` grades this one */
+}