@kolkrabbi/kol-theme 0.140.0 → 0.142.0

package/kol-components-molecules.css

@@ -1834,3 +1834,113 @@
   color: var(--kol-tone-pressed-fg);
 }
 
+
+/* ─────────────────────────── DocsToc · rail ───────────────────────────
+ * The fisheye rail render of `DocsToc` (`variant="rail"`, docstoc-rail-variant,
+ * kol-client-olina 2026-09-03 — built and run there before filing).
+ *
+ * `--m` is the gaussian magnitude (0..1) the component writes per row on
+ * pointer move; EVERY visual here derives from it, so the JS sets one number
+ * per row and the cascade does the rest. This is CSS rather than utilities
+ * because each rule reads a custom property through `calc()` and sets a
+ * child's resting state from the row's variable — neither is expressible as a
+ * Tailwind class, which is the §5 test for when a rule belongs in the theme.
+ * ────────────────────────────────────────────────────────────────────── */
+
+.kol-toc {
+  position: fixed;
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: var(--kol-z-sticky);
+  display: flex;
+  flex-direction: column;
+  padding-block: var(--kol-spacing-8);
+}
+/* The lens scales about the edge the rail is pinned to, so the column's outer
+ * edge stays a straight line while the type breathes. The wide inner padding is
+ * the lens's room to grow into without the labels colliding with the page. */
+.kol-toc--right {
+  right: 0;
+  align-items: flex-end;
+  padding-right: var(--kol-spacing-6);
+  padding-left: var(--kol-spacing-16);
+}
+.kol-toc--left {
+  left: 0;
+  align-items: flex-start;
+  padding-left: var(--kol-spacing-6);
+  padding-right: var(--kol-spacing-16);
+}
+
+.kol-toc-row {
+  --m: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--kol-spacing-3);
+  padding-block: 2px;
+  text-decoration: none;
+}
+.kol-toc--right .kol-toc-row { justify-content: flex-end; }
+.kol-toc--left  .kol-toc-row { flex-direction: row-reverse; justify-content: flex-end; }
+
+/* Away from the pointer the row is small and quiet; under it, large and lit.
+ * BOTH directions matter — grow-only reads as a bump, not a scrub. */
+.kol-toc-label {
+  /* `transform` is ignored on a non-replaced INLINE element, and this label is
+   * a bare <span>: the scale below did nothing at all until this line. It cost
+   * the filer a round trip with the user — opacity and width worked and only
+   * the scale did not. */
+  display: inline-block;
+  white-space: nowrap;
+  opacity: calc(0.26 + 0.74 * var(--m));
+  transform: scale(calc(0.78 + 0.42 * var(--m)));
+  will-change: transform, opacity;
+}
+.kol-toc--right .kol-toc-label { transform-origin: right center; }
+.kol-toc--left  .kol-toc-label { transform-origin: left center; }
+
+.kol-toc-rule {
+  height: 1px;
+  background: var(--kol-fg-24);
+  width: calc(8px + 26px * var(--m));
+}
+
+/* The section you are actually IN reads at rest — full ink and a size step — so
+ * the column says where you are before the pointer arrives. It rests where an
+ * inactive row lands only under the lens. */
+.kol-toc-row[data-active] .kol-toc-label {
+  opacity: calc(0.92 + 0.08 * var(--m));
+  transform: scale(calc(1 + 0.2 * var(--m)));
+  color: var(--kol-fg-96);
+}
+.kol-toc-row[data-active] .kol-toc-rule {
+  width: calc(22px + 26px * var(--m));
+  background: var(--kol-fg-64);
+}
+
+/* Settle on leave — NEVER while the pointer is driving. A transition on a
+ * continuous input lags behind the cursor and reads as sluggish; the component
+ * stamps `data-live` on pointer-enter, which is what this selector reads. */
+.kol-toc:not([data-live]) .kol-toc-label,
+.kol-toc:not([data-live]) .kol-toc-rule {
+  transition: opacity 260ms ease-out, transform 260ms ease-out, width 260ms ease-out;
+}
+
+/* Graduations — the ruler between the labels. Shorter and fainter than a
+ * heading's stroke at every point of the curve, so the labelled marks stay the
+ * ones you read; they exist to give the lens something continuous to cross.
+ * 3px pitch: ten between labels puts a section at ~52px, so a thirteen-section
+ * page still stands inside a laptop viewport. */
+.kol-toc-tick { height: 3px; padding-block: 0; }
+.kol-toc-tick .kol-toc-rule {
+  width: calc(5px + 11px * var(--m));
+  background: var(--kol-fg-12);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .kol-toc-label { opacity: 1; transform: none; }
+  .kol-toc-rule  { width: 12px; }
+  .kol-toc-row[data-active] .kol-toc-rule { width: 24px; }
+  .kol-toc-tick .kol-toc-rule { width: 5px; }
+  .kol-toc-label, .kol-toc-rule { transition: none; }
+}

package/kol-design-tokens.css

@@ -209,4 +209,46 @@
   --z-index-toast:    var(--kol-z-toast);
   --z-index-tooltip:  var(--kol-z-tooltip);
   --z-index-nav:      var(--kol-z-nav);
+
+  /* SPACING (theme-does-not-register-spacing, kol-client-hrafn 2026-09-03).
+   * `--kol-spacing-*` was a real scale Tailwind could not see, so a consumer
+   * chose between `gap-[var(--kol-spacing-6)]` — 28 characters, and a
+   * `var(--kol-*)` read in JSX, which check 2 of the full-consumption contract
+   * flags — and `gap-6`, which is TAILWIND's number: identical today because
+   * both ladders are index × 4, and silently divergent the day KOL moves a
+   * step. hrafn swept 57 call sites twice in one session over exactly that.
+   *
+   * The indices already agree, so this is a no-op visually and a real change
+   * semantically: `p-4` now resolves THROUGH the KOL token, and a step that
+   * moves here moves everywhere.
+   *
+   * THE OFF-LADDER STEPS STILL GENERATE, deliberately. Tailwind v4's `--spacing`
+   * multiplier produces any numeric step on demand (`p-7`, `gap-1.5`), and the
+   * ticket asks for the gaps in the ladder (no 7, 9, 11…) to stop emitting.
+   * Measured before deciding: 130+ off-ladder utilities across this repo's own
+   * packages, kol-website, the clients, fxr, monitor and mirror — `gap-1.5` ×30,
+   * `py-1.5` ×24, `gap-0.5` ×18 alone. Killing the multiplier drops every one of
+   * them to NOTHING EMITTED, no error — the same silent failure this block was
+   * written to end for `z-modal`. Closing the ladder is a real ruling and it
+   * needs its own sweep, not a side effect of registering the scale. */
+  --spacing-1:  var(--kol-spacing-1);
+  --spacing-2:  var(--kol-spacing-2);
+  --spacing-3:  var(--kol-spacing-3);
+  --spacing-4:  var(--kol-spacing-4);
+  --spacing-5:  var(--kol-spacing-5);
+  --spacing-6:  var(--kol-spacing-6);
+  --spacing-8:  var(--kol-spacing-8);
+  --spacing-10: var(--kol-spacing-10);
+  --spacing-12: var(--kol-spacing-12);
+  --spacing-16: var(--kol-spacing-16);
+  --spacing-20: var(--kol-spacing-20);
+  --spacing-24: var(--kol-spacing-24);
+
+  /* The two semantic steps a PAGE RAMP names, registered because they read as
+   * utilities (`py-section`, `px-container`). The three `--kol-spacing-gap-*`
+   * aliases stay CSS-only on purpose: `gap-gap-md` stutters, and `gap-md` would
+   * have to burn `--spacing-md`, a name too generic to spend on three values
+   * that are already `2` / `4` / `6`. */
+  --spacing-section:   var(--kol-spacing-section);
+  --spacing-container: var(--kol-spacing-container);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-theme",
-  "version": "0.140.0",
+  "version": "0.142.0",
   "description": "KOL (Kolkrabbi) design-system tokens + base CSS — brand-neutral. The canonical token/cascade layer every other KOL package and consumer builds on.",
   "license": "MIT",
   "type": "module",