@kolkrabbi/kol-theme 0.13.6 → 0.18.0

package/kol-components-atoms.css

@@ -166,23 +166,17 @@
   max-width: 100%;
 }
 
+/* POSITION ONLY. The control is a DS Button (quiet, icon-only) as of
+ * 2026-08-01 — it brings its own box, border, colour set and states, so this
+ * class stopped painting one. It used to hand-draw a bordered square around a
+ * literal `×` CHARACTER, which is why the button had no hover, no focus ring
+ * and no glyph. The inset is --kol-spacing-3, the rung that already carried
+ * this value. */
 .kol-overlay-close {
   position: absolute;
-  top: 12px;
-  right: 12px;
+  top: var(--kol-spacing-3);
+  right: var(--kol-spacing-3);
   z-index: 10;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 32px;
-  height: 32px;
-  border-radius: var(--kol-radius-sm);
-  border: 1px solid var(--kol-oq-16);
-  background: var(--kol-surface-primary);
-  color: var(--kol-surface-on-primary);
-  font-size: 16px;
-  line-height: 1;
-  cursor: pointer;
 }
 
 /* ═══════════════════════════════════════════════════════════════
@@ -894,6 +888,13 @@ a:hover .icon-hover,
   padding: 0;
 }
 
+/* Radius (2026-07-30 ruling): either the system's 4px or a full round, nothing
+ * between. `sm` is the default and carries no class — it's on .kol-icon-frame
+ * above. `full` is a deliberate exception to the hard 4px repo invariant,
+ * because a round frame is its own chrome idiom (edge-straddling controls,
+ * avatars, status dots) rather than a radius tweak. */
+.kol-icon-frame-radius-full { border-radius: 9999px; }
+
 /* pinned squares — the box never moves with glyph size (user law 2026-07-28) */
 .kol-icon-frame-sm { width: 28px; height: 28px; }
 .kol-icon-frame-md { width: 32px; height: 32px; }

package/kol-components-molecules.css

@@ -73,7 +73,6 @@
   padding: 4px 16px;
   border-radius: var(--kol-radius-full);
   background-color: var(--kol-surface-on-primary);
-  font-family: var(--kol-font-family-mono);
   color: var(--kol-surface-primary);
   border: none;
 }
@@ -84,7 +83,6 @@
   padding: 4px 16px;
   border-radius: var(--kol-radius-full);
   background-color: color-mix(in srgb, var(--kol-surface-on-primary) 16%, transparent);
-  font-family: var(--kol-font-family-mono);
   color: var(--kol-surface-on-primary);
   border: 1px solid transparent;
 }
@@ -95,238 +93,102 @@
   padding: 4px 16px;
   border-radius: var(--kol-radius-full);
   background-color: var(--kol-surface-primary);
-  font-family: var(--kol-font-family-mono);
   color: var(--kol-surface-on-primary);
   border: 1px solid var(--kol-border-default);
 }
 
-.pill-sm {
-  font-size: 10px;
-  font-weight: 470;
-  padding: 2px 10px;
-}
-
-.pill-md {
-  font-size: 12px;
-  font-weight: 470;
-  padding: 4px 16px;
-}
-
-.pill-lg {
-  font-size: 14px;
-  font-weight: 470;
-  padding: 6px 20px;
-}
+/* PADDING ONLY — type is kol-helper-*, applied in Pill.jsx. Same ruling as
+ * .kol-tag--* above (2026-08-01). */
+.pill-sm { padding: 2px 10px; }
+.pill-md { padding: 4px 16px; }
+.pill-lg { padding: 6px 20px; }
 
 
 /* ─────────────────────────────────────────────────────────────────────
- * Tag — molecules/Tag.jsx
- *   .tag-control / -sm / -md / -lg
- *   .control-unified-inverse  (inverse variant — ad-hoc legacy naming)
+ * Tag — atoms/Tag.jsx.  REBUILT ON PILL'S MODEL (user ruling 2026-08-01).
+ *
+ * Was: four class schemes for one component (.tag-control, .tag, .tag-naked,
+ * .tag-control-inverse), four declared variants, and exactly ONE :hover rule
+ * between them. Passing `color` swapped the base class off .tag-control and
+ * silently cost the chip its interaction state.
+ *
+ * Now: ONE scheme. `.kol-tag` is the box; `--primary|--secondary|--inverse` is
+ * the look, matching Pill and Button's vocabulary; `--sm|--md|--lg` is the
+ * scale. EVERY variant carries hover and active — a variant without a state is
+ * the defect this rewrite exists to remove, and `pnpm validate:chrome` fails
+ * any that lacks one.
  * ───────────────────────────────────────────────────────────────────── */
 
-.tag-control {
+.kol-tag {
   display: inline-flex;
   align-items: center;
-  padding: 4px 16px;
+  gap: 6px;
   border-radius: var(--kol-radius-full);
-  background-color: var(--kol-surface-primary);
-  font-size: 10px;
-  font-weight: 400;
-  font-family: var(--kol-font-family-mono);
-  color: var(--kol-surface-on-primary);
-  border: 1px solid var(--kol-border-default);
-  transition: background-color var(--kol-transition-base),
-              color var(--kol-transition-base);
+  border: 1px solid transparent;
+  transition: background-color 0.15s ease, color 0.15s ease, border-color 0.15s ease;
 }
 
-/* ─────────────────────────────────────────────────────────────────────
- * Dropdown — molecules/Dropdown.jsx (2026-07-08 chrome law).
- *   The trigger IS button chrome: JSX emits kol-btn kol-btn-{primary|
- *   outline} kol-btn-{size}, so fills/hover/active/focus come from the
- *   button rules. Classes below only add trigger layout + the open/panel
- *   fusion: primary = one piece (same fill, no border, no gap, hairline
- *   divider inside); outline = bordered pair, trigger's bottom edge is
- *   the divider.
- * ───────────────────────────────────────────────────────────────────── */
-
-.kol-dd-trigger {
-  width: 100%;
-  justify-content: space-between;
-}
+/* PADDING ONLY. Type is the kol-helper-* ramp, applied at the call site
+ * (Tag.jsx) — these rules used to hardcode font-size + font-weight and set no
+ * line-height, so a 10px chip inherited the body's ~1.5 and stood 22px tall
+ * beside 14px rows. Two owners of one concept is the drift this repo keeps
+ * paying for; the class owns the type, the rule owns the box. */
+.kol-tag--sm { padding: 2px 10px; }
+.kol-tag--md { padding: 4px 16px; }
+.kol-tag--lg { padding: 6px 20px; }
 
-/* Dropdowns have NO hover and NO clicked state (2026-07-15 ruling) — the
- * trigger borrows Button chrome for geometry/fill but its only states are
- * rest and open. Scoped here so Button's own rules stay untouched. */
-.kol-dd-trigger.kol-btn-primary:not(.kol-btn-animate):hover,
-.kol-dd-trigger.kol-btn-primary:not(.kol-btn-animate):not(:disabled):active {
-  background: var(--kol-surface-secondary);
-  color: var(--kol-surface-on-primary);
-}
-.kol-dd-trigger.kol-btn-outline:not(.kol-btn-animate):hover,
-.kol-dd-trigger.kol-btn-outline:not(.kol-btn-animate):not(:disabled):active {
-  background: transparent;
-  border-color: var(--kol-oq-16);
+/* primary — the filled chip. Mirrors .pill-subtle's weight. */
+.kol-tag--primary {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 16%, transparent);
   color: var(--kol-surface-on-primary);
 }
-
-.kol-dd-trigger--open {
-  border-radius: var(--kol-radius-sm) var(--kol-radius-sm) 0 0;
+.kol-tag--primary:hover {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 24%, transparent);
 }
-
-.kol-dd-panel {
-  color: var(--kol-surface-on-primary);
-  border-radius: 0 0 var(--kol-radius-sm) var(--kol-radius-sm);
-  padding-bottom: 4px;
+.kol-tag--primary.is-active {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 32%, transparent);
+  border-color: currentColor;
 }
 
-.kol-dd-panel--primary { background-color: var(--kol-surface-secondary); }
-
-.kol-dd-panel--outline {
+/* secondary — the outlined chip. Mirrors .pill-outline. */
+.kol-tag--secondary {
   background-color: var(--kol-surface-primary);
-  border: 1px solid var(--kol-oq-16);
-  border-top: none;
-}
-
-/* grey — the opaque grey chrome (oq-12, fill law:
- * interactive surfaces never translucent). Dropdown-only chrome; rest = hover
- * = active per the no-states dropdown ruling (no kol-btn-* class emitted, so
- * no button state rules ever apply). */
-.kol-dd-trigger--grey {
-  background-color: var(--kol-oq-12);
   color: var(--kol-surface-on-primary);
-  border: 1px solid transparent;
-}
-
-.kol-dd-panel--grey { background-color: var(--kol-oq-12); }
-
-.kol-dd-div {
-  height: 1px;
-  background-color: var(--kol-border-default);
-  margin: 0 12px;
-}
-
-/* The option list — chrome, not consumer utilities (brief-2.0 defect 2: a
- * consumer without @source got an uncapped, unscrollable panel). */
-.kol-dd-list {
-  display: flex;
-  flex-direction: column;
-  align-items: stretch;
-  max-height: 300px;
-  overflow-y: auto;
+  border-color: var(--kol-border-default);
 }
-
-/* The trigger chevron — pushed to the trailing edge, flips on open state.
- * Replaces the ml-auto utility + inline rotate style in Dropdown.jsx. */
-.kol-dd-caret {
-  margin-left: auto;
-  transition: transform 300ms;
+.kol-tag--secondary:hover {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 08%, transparent);
 }
-
-.kol-dd-trigger[data-state="open"] .kol-dd-caret {
-  transform: rotate(180deg);
+.kol-tag--secondary.is-active {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 16%, transparent);
+  border-color: currentColor;
 }
 
-.tag-control:hover {
-  background-color: var(--kol-oq-12);
-  color: var(--kol-surface-on-primary);
-  border-color: transparent;
+/* inverse — the flipped chip. Mirrors .pill-inverse. */
+.kol-tag--inverse {
+  background-color: var(--kol-surface-on-primary);
+  color: var(--kol-surface-primary);
 }
-
-.tag-control.is-active {
-  background-color: var(--kol-oq-12);
-  color: var(--kol-surface-on-primary);
-  border-color: var(--kol-oq-12);
+.kol-tag--inverse:hover {
+  background-color: color-mix(in srgb, var(--kol-surface-on-primary) 88%, transparent);
 }
-
-.tag-sm { font-size: 10px; font-weight: 470; padding: 4px 10px; }
-.tag-md { font-size: 12px; font-weight: 470; padding: 5px 12px; }
-.tag-lg { font-size: 14px; font-weight: 470; padding: 6px 14px; }
-
-/* ─────────────────────────────────────────────────────────────────────
- * Tag color family — molecules/Tag.jsx `color` prop (wave-4 vault parity,
- * 2026-07-30). Tag emits `tag tag--{color}` (chip) / `tag-naked
- * tag--{color}` (text-only); the classes shipped in the JSX but the RULES
- * never migrated out of the monorepo workshop — the same dangling trap as
- * the palette tokens themselves (kol-color.css, 2026-07-16) — so every
- * colored tag rendered dead. Re-authored from the monorepo colors spec
- * (02-design-system/01-colors.md § Tag Color Classes): light mode =
- * palette-*-light fill + dark ink; dark mode = saturated palette-* fill +
- * light ink (yellow keeps dark ink); `dark` = the on-primary/surface flip.
- * Inks are LITERALS (the surface poles): on a fixed palette fill a
- * theme-flipping token is wrong by definition.
- * ───────────────────────────────────────────────────────────────────── */
-
-.tag {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  border-radius: var(--kol-radius-full);
-  font-family: var(--kol-font-family-mono);
-  border: 1px solid transparent;
-  transition: background-color var(--kol-transition-base),
-              color var(--kol-transition-base);
+.kol-tag--inverse.is-active {
+  border-color: var(--kol-surface-primary);
 }
 
-/* naked — text-only: no fill, no chip padding (the reader-sidebar voice).
- * Sits AFTER .tag-{size} so its padding reset wins at equal specificity. */
-.tag-naked {
+.kol-tag-dismiss {
   display: inline-flex;
   align-items: center;
-  gap: 6px;
-  padding: 0;
-  background: transparent;
-  border: none;
-  font-family: var(--kol-font-family-mono);
+  cursor: pointer;
+  opacity: 0.64;
+  transition: opacity 0.15s ease;
 }
+.kol-tag-dismiss:hover { opacity: 1; }
 
-/* Light mode (default): light fill + dark ink */
-.tag--blue   { background-color: var(--kol-palette-blue-light);   color: #121215; }
-.tag--teal   { background-color: var(--kol-palette-teal-light);   color: #121215; }
-.tag--green  { background-color: var(--kol-palette-green-light);  color: #121215; }
-.tag--yellow { background-color: var(--kol-palette-yellow-light); color: #121215; }
-.tag--red    { background-color: var(--kol-palette-red-light);    color: #121215; }
-.tag--orange { background-color: var(--kol-palette-orange-light); color: #121215; }
-.tag--purple { background-color: var(--kol-palette-purple-light); color: #121215; }
-.tag--dark   { background-color: var(--kol-surface-on-primary);   color: var(--kol-surface-primary); }
-
-/* naked + color = saturated text, both modes (no fill to carry the pair) */
-.tag-naked.tag--blue   { background: transparent; color: var(--kol-palette-blue); }
-.tag-naked.tag--teal   { background: transparent; color: var(--kol-palette-teal); }
-.tag-naked.tag--green  { background: transparent; color: var(--kol-palette-green); }
-.tag-naked.tag--yellow { background: transparent; color: var(--kol-palette-yellow); }
-.tag-naked.tag--red    { background: transparent; color: var(--kol-palette-red); }
-.tag-naked.tag--orange { background: transparent; color: var(--kol-palette-orange); }
-.tag-naked.tag--purple { background: transparent; color: var(--kol-palette-purple); }
-.tag-naked.tag--dark   { background: transparent; color: var(--kol-surface-on-primary); }
-
-/* active (Tag.jsx emits .tag--active when active + colored) */
-.tag--active { border-color: currentColor; }
-
-/* Dark mode: saturated fill + light ink (yellow keeps dark ink). Scoped to
- * .tag.tag--{color} so the chip flips while .tag-naked (equal specificity,
- * earlier in the sheet) keeps its saturated TEXT — a bare .tag--{color}
- * override here would out-order the naked rules and give text tags a fill.
- * MIRROR of the system-follow block below — edit both. */
-:is([data-theme="dark"], .dark) .tag.tag--blue   { background-color: var(--kol-palette-blue);   color: #fafafa; }
-:is([data-theme="dark"], .dark) .tag.tag--teal   { background-color: var(--kol-palette-teal);   color: #fafafa; }
-:is([data-theme="dark"], .dark) .tag.tag--green  { background-color: var(--kol-palette-green);  color: #fafafa; }
-:is([data-theme="dark"], .dark) .tag.tag--yellow { background-color: var(--kol-palette-yellow); color: #121215; }
-:is([data-theme="dark"], .dark) .tag.tag--red    { background-color: var(--kol-palette-red);    color: #fafafa; }
-:is([data-theme="dark"], .dark) .tag.tag--orange { background-color: var(--kol-palette-orange); color: #fafafa; }
-:is([data-theme="dark"], .dark) .tag.tag--purple { background-color: var(--kol-palette-purple); color: #fafafa; }
-
-/* System-follow dark — only when no explicit theme is stamped (explicit >
- * system > light, USER law). MIRROR of the block above — edit both. */
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme]) .tag.tag--blue   { background-color: var(--kol-palette-blue);   color: #fafafa; }
-  :root:not([data-theme]) .tag.tag--teal   { background-color: var(--kol-palette-teal);   color: #fafafa; }
-  :root:not([data-theme]) .tag.tag--green  { background-color: var(--kol-palette-green);  color: #fafafa; }
-  :root:not([data-theme]) .tag.tag--yellow { background-color: var(--kol-palette-yellow); color: #121215; }
-  :root:not([data-theme]) .tag.tag--red    { background-color: var(--kol-palette-red);    color: #fafafa; }
-  :root:not([data-theme]) .tag.tag--orange { background-color: var(--kol-palette-orange); color: #fafafa; }
-  :root:not([data-theme]) .tag.tag--purple { background-color: var(--kol-palette-purple); color: #fafafa; }
-}
+/* The per-colour tag palette was DELETED 2026-08-01 with the `color` prop.
+ * A chip's look is its variant now (kol-tag--primary|secondary|inverse), the
+ * same vocabulary Pill and Button use. Tag colour BY TAXONOMY returns later
+ * as its own decision, layered ON the variants rather than replacing them. */
 
 .control-unified-inverse {
   display: inline-flex;
@@ -608,3 +470,47 @@
   background: color-mix(in srgb, var(--kol-surface-on-primary) 8%, transparent);
   color: var(--kol-surface-on-primary);
 }
+
+/* ─────────────────────────────────────────────────────────────────────
+ * OVERLAY CHROME — the ONE floating surface (user ruling 2026-08-01).
+ *
+ * There was none. `.kol-modal` is an unstyled hook, and ShellSearchOverlay
+ * hand-wrote its own look at the call site: `rounded-[var(--kol-radius-2xl)]`,
+ * `shadow-[0_20px_60px_rgba(0,0,0,0.4)]`, `bg-black/60`, `backdrop-blur-[1px]`
+ * — four arbitrary values, none of them referenced anywhere else. The 20px
+ * radius in particular appears NOWHERE else in this repo's chrome (which uses
+ * `sm` and `full`, counted), which is exactly why it read as foreign.
+ *
+ * TagModeOverlay meanwhile rendered as a page-like <article> with no overlay
+ * chrome at all — one product, two floating surfaces, nothing in common.
+ *
+ * Both wear these two classes now. `validate:chrome` C3 fails any arbitrary
+ * rounded-[…] / shadow-[…] / bg-black/NN / backdrop-blur-[…] in package chrome.
+ * ───────────────────────────────────────────────────────────────────── */
+
+/* LOOK ONLY — the call site owns the box. Three scrims exist and two are
+ * `fixed inset-0` while one is `absolute inset-0`; baking position in would
+ * have forced a wrong one on two of them. The class owns what was drifting:
+ * the tint (60 / 50 / 50 across three files) and the blur. */
+.kol-overlay-scrim {
+  background-color: color-mix(in srgb, #000 60%, transparent);
+  backdrop-filter: blur(1px);
+}
+
+.kol-overlay-panel {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  background-color: var(--kol-surface-primary);
+  /* NO BORDER, NO SHADOW (user 2026-08-01). Both were tried and both were
+   * wrong: the shadow was another product's floating-card idiom, and the
+   * hairline left an empty palette reading as a bordered empty box. The SCRIM
+   * is the separation — a 60% tint plus blur is already a stronger edge than
+   * an 8%-opacity line. */
+  /* `sm` — the radius this repo's chrome actually uses. */
+  border-radius: var(--kol-radius-sm);
+  /* NO SHADOW (user ruling 2026-08-01). The border and the scrim already
+   * separate the panel; a drop-shadow on top is the floating-card idiom from
+   * another product. --kol-shadow-overlay was added for this an hour earlier
+   * and is deleted with it: it solved the wrong problem. */
+}

package/kol-components-organisms.css

@@ -175,13 +175,22 @@
   display: inline-flex;
   align-items: center;
   padding: 2px 4px;
-  margin: 0 4px;
+  /* No outer margin: spacing is the CONTAINER's job. The margin here
+   * double-spaced against every flex row's own gap, which is the ragged
+   * rhythm the metadata rows showed. */
   border-radius: 2px;
   font-family: var(--kol-font-family-mono);
   font-size: 0.75rem;
   font-weight: 400;
   line-height: 1;
   white-space: nowrap;
+  /* Carries its OWN fill as of 2026-08-01. The look lived only in the
+   * `.kol-table code` descendant rule below, so a token chip rendered right
+   * inside a table and completely unstyled anywhere else — which is why the
+   * component pages hand-rolled a Tailwind lookalike. One concept, two
+   * spellings: exactly the drift `.text-fg-*` vs `--kol-fg-*` taught. */
+  color: var(--kol-fg-80);
+  background-color: var(--kol-fg-08);
 }
 
 .kol-table-wrapper.kol-table--simple { border: none; border-radius: 0; }
@@ -425,3 +434,125 @@
   object-fit: cover;
   object-position: center;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+ * MediaLibrary — organisms/MediaLibrary.jsx
+ * The picker card, the tile grid, the tree rows and the path bar.
+ * The card width and tile floor were inline literals in the four consumer
+ * forks (kol-ds-fxr MediaPicker.jsx:214 and :274) — they are tokens here
+ * because geometry is referenced, never re-guessed per consumer.
+ * NOT here: the scrim, the centring, Esc/backdrop dismiss and the corner
+ * close — FullscreenOverlay (.kol-overlay) already owns all of it.
+ * NO elevation. A drop shadow under the modal was smuggled in 2026-08-01
+ * and struck out the same day (user ruling) — the scrim is the separation.
+ * ═══════════════════════════════════════════════════════════════ */
+
+.kol-media-picker {
+  /* The card's resting width. Was 45rem and the ContentFilters header could
+   * not fit in it: "10 of 10" wrapped to three lines, the view toggle clipped,
+   * and the close button collided with it. The header is the constraint, not
+   * the grid. It still shrinks inside .kol-overlay's padding. */
+  --kol-media-picker-w: 64rem;
+  /* the grid's tile floor — auto-fill packs as many as clear this */
+  --kol-media-tile-min: 10rem;
+
+  display: flex;
+  flex-direction: column;
+  width: var(--kol-media-picker-w);
+  max-width: 100%;
+  max-height: 85vh;
+  /* min-height:0 + the body owning the scroll — the card itself scrolling was
+   * what dragged the sticky header out of view. */
+  min-height: 0;
+  overflow: hidden;
+  /* Extra block-start: FullscreenOverlay's close button is absolutely placed
+   * on the SHEET corner, so at even padding it landed on top of the view
+   * toggle. The card reserves the lane instead of the close moving. */
+  padding: var(--kol-spacing-12) var(--kol-spacing-5) var(--kol-spacing-5);
+  border: 1px solid var(--kol-oq-08);
+  border-radius: var(--kol-radius-sm);
+  background: var(--kol-surface-primary);
+}
+
+/* The browser is the same body with no card around it — it fills whatever
+ * box the consumer gives it, so a page can host it full-bleed. */
+.kol-media-browser {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  --kol-media-tile-min: 10rem;
+}
+
+.kol-media-grid {
+  display: grid;
+  gap: var(--kol-spacing-4);
+  grid-template-columns: repeat(auto-fill, minmax(var(--kol-media-tile-min), 1fr));
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.kol-media-list {
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+/* One folder row in the tree. Finder's list model: the chevron discloses in
+ * place, so the parent never leaves the screen and there is no breadcrumb
+ * stacked above a divider. Same row idiom as the rails — a drill-down and a
+ * nav row are the same gesture. */
+.kol-media-folder {
+  display: flex;
+  align-items: center;
+  gap: var(--kol-spacing-2);
+  padding-block: var(--kol-pad-rail-row-y);
+  border-radius: var(--kol-radius-sm);
+  cursor: pointer;
+  transition: background-color var(--kol-transition-fast);
+}
+
+.kol-media-folder:hover {
+  background: var(--kol-oq-04);
+}
+
+/* The path bar rides the FOOT, where Finder puts it. */
+.kol-media-pathbar {
+  display: flex;
+  align-items: center;
+  gap: var(--kol-spacing-1);
+  margin-block-start: auto;
+  padding-block-start: var(--kol-spacing-3);
+  border-top: 1px solid var(--kol-oq-08);
+}
+
+/* The BODY scrolls, never the card — a scrolling card dragged the header out
+ * of view, which is what made the picker feel broken. */
+.kol-media-scroll {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* Sortable header — a real button inside the <th> so it is keyboard-reachable.
+ * The glyph is always in the layout box (opacity, not display) so the header
+ * does not reflow on first sort. */
+.kol-table-sort {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--kol-spacing-1);
+  font: inherit;
+  color: inherit;
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+}
+
+.kol-table-sort:hover { color: var(--kol-surface-on-primary); }
+.kol-table-sort svg { opacity: 0.25; transition: opacity var(--kol-transition-fast); }
+.kol-table-sort:hover svg { opacity: 0.6; }
+[aria-sort] .kol-table-sort svg { opacity: 1; }

package/kol-components-workshop.css

@@ -93,33 +93,64 @@
   display: none;
 }
 
-/* Sidebar toggle buttons (collapsible section headers) — layout only.
- * Type/color carried in JSX (kol-helper-10 text-meta). */
-/* Vertical rhythm matches .shell-nav-group-header (6px rows) — ledger-2.0
- * #2.6 ruling (final, user-reviewed 2026-07-15): the rail keeps its quieter
- * 10px label scale (deliberate hierarchy vs the nav's 14px), row rhythm is
- * shared. */
-.shell-sidebar-toggle {
+/* THE EYEBROW ROW — the ONE owner of a rail section header's box (user ruling
+ * 2026-08-01). Left and right rails render the same row and composed it
+ * differently, so they drifted: the left stacked `.shell-sidebar-toggle` +
+ * `.shell-sidebar-label` on the wrapper AND `.shell-sidebar-label` again on
+ * the inner label — two margin-owners on one row — plus an inline height on
+ * the chevron; the right borrowed `.shell-nav-group-header` (the nav row, a
+ * different scale) with one `.shell-sidebar-label`. Same eyebrow, two boxes,
+ * no version difference between them: the failure ARCHITECTURE §5 records for
+ * cascade layers, pointed at spacing.
+ *
+ * The rule: an eyebrow row wears ONE box class and NOTHING else beside
+ * kol-doc-eyebrow. Two names, by role, sharing one definition so they cannot
+ * drift from each other either:
+ *
+ *   .shell-sidebar-toggle   the eyebrow that collapses its section
+ *   .shell-sidebar-label    the eyebrow that is just a label
+ *
+ * Both own padding AND margin. Do not stack them, do not set y-spacing inline,
+ * do not repeat a spacing class on a child. Type/colour come from
+ * kol-doc-eyebrow. `pnpm validate:rails` R3 enforces it.
+ *
+ * Vertical rhythm matches .shell-nav-group-header via --kol-pad-rail-row-y —
+ * ledger-2.0 #2.6 ruling (final, user-reviewed 2026-07-15): the rail keeps its
+ * quieter label scale (deliberate hierarchy vs the nav's), row rhythm is
+ * shared. It is shared by a token now, not by copies of a number. */
+.shell-sidebar-toggle,
+.shell-sidebar-label {
   display: flex;
   align-items: center;
-  gap: 6px;
-  cursor: pointer;
+  justify-content: space-between;
+  gap: var(--kol-pad-rail-row-y);
   width: 100%;
+  text-align: left;
   border: none;
   background: transparent;
-  padding: 6px 0;
+  padding: var(--kol-pad-rail-row-y) 0;
+  margin-bottom: var(--kol-spacing-2);
   transition: color 0.15s ease;
 }
 
-.shell-sidebar-toggle:hover {
-  color: color-mix(in srgb, var(--kol-surface-on-primary) 72%, transparent);
+/* Interactivity is a property of the element, not a second class at the call
+ * site — a static eyebrow and a clickable one must not have to remember a
+ * different class pair to get the same box. */
+.shell-sidebar-toggle,
+.shell-sidebar-label:is(button, a, [role='button']) {
+  cursor: pointer;
 }
 
-/* Sidebar section labels — margin only; type/color in JSX. */
-.shell-sidebar-label {
-  margin-bottom: 8px;
+.shell-sidebar-toggle:hover,
+.shell-sidebar-label:is(button, a, [role='button']):hover {
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 72%, transparent);
 }
 
+/* NB — the old `.shell-sidebar-label { margin-bottom }` rule was DELETED here
+ * (2026-08-01). It was the second box owner: it re-declared the eyebrow's
+ * bottom margin below the shared rule above, so an element wearing both
+ * classes got its spacing decided by source order. The shared rule owns it. */
+
 /* Sidebar links — layout only; type/color (+ active) in JSX. */
 .shell-sidebar-link {
   padding: 4px 0;
@@ -176,9 +207,29 @@
   margin-bottom: 12px;
 }
 
-/* Navigation group header — layout only; type/color in JSX. */
+/* THE CHAPTER ROW (the rail's names, user 2026-08-01):
+ *
+ *   CATEGORY  the eyebrow          .shell-sidebar-toggle / -label
+ *   CHAPTER   `Foundations (5)`    .shell-nav-group-header   ← this
+ *   PAGE      `Tokens`             .shell-nav-item
+ *   SECTION   the right rail's rows (same PAGE row idiom)
+ *
+ * CHAPTER and PAGE were indistinguishable: both `kol-mono-14`, and the only
+ * difference was `.text-body` — which is a COLOUR utility, not type. A parent
+ * and its children reading identically is not a hierarchy.
+ *
+ * The weight is the difference, and it stays INSIDE the one ramp: 500 here
+ * against kol-mono-14's own 400 on the page row. Not a second type class —
+ * R1 exists to stop a second RAMP in the rails, and a weight within one ramp
+ * is not one.
+ *
+ * Layout: same y-rhythm as the eyebrow (--kol-pad-rail-row-y), no bottom
+ * margin because .shell-nav-items owns the gap under it. A CATEGORY must never
+ * borrow this class — that is how the right rail drifted; use
+ * .shell-sidebar-toggle. */
 .shell-nav-group-header {
-  padding: 6px 0 6px 0;
+  font-weight: 500;
+  padding: var(--kol-pad-rail-row-y) 0;
   cursor: pointer;
   display: flex;
   justify-content: space-between;
@@ -190,24 +241,66 @@
   color: color-mix(in srgb, var(--kol-surface-on-primary) 90%, transparent);
 }
 
+/* THE ROW CONTAINER — owns the gap so the two rails cannot disagree. They
+ * did: `space-y-0` on one side, `space-y-4` on the other, for the same list. */
 .shell-nav-items {
   display: flex;
   flex-direction: column;
-  gap: 4px;
+  gap: 0;
   margin-top: 4px;
 }
 
 /* Navigation items — layout only; type/color (+ active) in JSX. */
+/* THE PAGE ROW — L3, the class owns the whole look (user ruling 2026-08-01).
+ * PAGE in the rail's vocabulary (`Tokens`); the right rail's rows are SECTIONS
+ * and wear this same idiom deliberately. Weight stays the ramp's own 400 — the
+ * CHAPTER above it carries 500, and that difference IS the hierarchy.
+ *
+ * `.shell-nav-item` was the shared name and nothing else: every call site
+ * hand-wrote its own utility stack around it, so ONE row idiom shipped as NINE
+ * strings across five files — `block kol-mono-14 text-body transition-colors
+ * focus-visible:ring-focus hover:text-emphasis` in one rail, bare
+ * `kol-mono-14` in the other, `flex items-center gap-2 …` for actions. R1/R2
+ * locked the TYPE class and nothing locked the stack: the eyebrow-box failure,
+ * one rung down.
+ *
+ * Layout, colour, hover, transition and focus live HERE now. Markup comes from
+ * `RailRow`; `validate:rails` R4 fails a hand-written `shell-nav-item`. */
 .shell-nav-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
   padding: 4px 12px 4px 20px;
+  border: none;
+  background: transparent;
+  text-align: left;
   border-radius: 0px;
   text-decoration: none;
-  transition: all 0.15s ease;
-  display: block;
+  color: var(--kol-fg-64);
+  cursor: pointer;
+  transition: color 0.15s ease, background-color 0.15s ease;
 }
 
 .shell-nav-item:hover {
-  color: color-mix(in srgb, var(--kol-surface-on-primary) 100%, transparent);
+  color: var(--kol-surface-on-primary);
+}
+
+.shell-nav-item:focus-visible {
+  outline: 1px solid var(--kol-fg-32);
+  outline-offset: -1px;
+}
+
+/* The active row — one definition, not `text-emphasis` typed at each site. */
+.shell-nav-item.is-active {
+  color: var(--kol-surface-on-primary);
+}
+
+/* The trailing slot: counts, doc numbers, anything pushed right. */
+.shell-nav-item-trailing {
+  margin-left: auto;
+  flex-shrink: 0;
+  color: var(--kol-fg-48);
 }
 
 .shell-nav-item-doc {

package/kol-theme.css

@@ -72,6 +72,15 @@
   --kol-spacing-gap-md: var(--kol-spacing-4);
   --kol-spacing-gap-lg: var(--kol-spacing-6);
 
+  /* RAIL ROW rhythm (2026-08-01) — the y-padding every sidebar row shares:
+   * the eyebrow (.shell-sidebar-toggle) and the nav group header
+   * (.shell-nav-group-header). Deliberately OFF the spacing scale — a tighter
+   * chrome rhythm than --kol-spacing-1, and both rules already carried the
+   * same literal in two places. Named here so the left and right rails cannot
+   * disagree about it again; the row's bottom separation is --kol-spacing-2
+   * and needs no alias of its own. */
+  --kol-pad-rail-row-y: 0.375rem;
+
   /* Content widths (2026-07-28; panel added 2026-07-30) — ONE frame, three
    * inner caps (chess law). Every page: mx-auto max-w-shell + the one padding
    * rhythm, content LEFT-ANCHORED inside. Width is a content decision, never a
@@ -81,7 +90,16 @@
    * text. Nothing else — a hardcoded max-w-[Npx] at a call site means this
    * scale failed; file it, don't improvise it.
    * kol-framework's --kol-container-max is the responsive RESOLUTION of the
-   * shell (100% → 1400 → 1600 → shell), not a rival family. */
+   * shell (100% → 1400 → 1600 → shell), not a rival family.
+   *
+   * canvas (2026-07-31, user ruling) — the rung between shell and panel: the
+   * BODY of a page inside the shell's main column, i.e. item fields (swatch
+   * grids, the icon wall, card galleries) that panel would squeeze and the
+   * frame does not bind. Authored in rem because it is a max-width, not a
+   * device measure: 87.5rem = 1400 at the default root size. Flat at every
+   * breakpoint — a max-width only bites once there is room for it, and it
+   * nests: a table inside it still stops at panel, a paragraph at measure. */
+  --kol-content-canvas: 87.5rem;
   --kol-content-shell: 1800px;
   --kol-content-panel: 960px;
   --kol-content-column: 768px;
@@ -89,6 +107,11 @@
 
   /* Border radius (4px increments) */
   --kol-radius-none: 0;
+  /* xs (2026-08-01) — the hairline rung. Claimed out loud: 2px had SIX
+     hand-written `rounded-[2px]` call sites (swatches, colour rows, the
+     glass panel) and no token, so the scale's 4px floor was simply being
+     ignored rather than followed. A value used six times is a rung. */
+  --kol-radius-xs: 2px;
   --kol-radius-sm: 4px;
   --kol-radius-md: 8px;
   --kol-radius-lg: 12px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-theme",
-  "version": "0.13.6",
+  "version": "0.18.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",