@kolkrabbi/kol-theme 0.19.0 → 0.30.2

package/kol-components-atoms.css

@@ -888,6 +888,26 @@ a:hover .icon-hover,
   padding: 0;
 }
 
+/* An ACTIONABLE frame — `onClick`/`href` (user ruling 2026-08-01: *"you dont
+ * use a button… you use the ICON COMPONENT… it has no interactive states"*).
+ *
+ * The "no states" property used to be an accident of the element: a <span>
+ * cannot be hovered-as-a-control, so the frame's own docstring warned that
+ * reusing kol-btn-* on one suppressed states BY TAG rather than by contract.
+ * Handing the frame a click makes it a <button>/<a>, which brings the user
+ * agent's own chrome back with it — so the reset is declared here and the
+ * absence of state rules stays a PROPERTY OF THE CLASS, which is what the
+ * original ruling actually asked for. There is deliberately no :hover, no
+ * :active and no :focus fill below: a frame that lights up is a Button. */
+button.kol-icon-frame,
+a.kol-icon-frame {
+  appearance: none;
+  -webkit-appearance: none;
+  font: inherit;
+  cursor: pointer;
+  text-decoration: none;
+}
+
 /* 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,

package/kol-components-molecules.css

@@ -97,6 +97,14 @@
   border: 1px solid var(--kol-border-default);
 }
 
+/* Pill takes the TRACKING but NOT the transform (user rulings 2026-08-01).
+ * Pill has no single base class, so its size classes carry it. The uppercase
+ * exception is Tag's alone: a Pill's label IS authored at the call site, so the
+ * no-`text-transform` law applies to it unchanged. */
+.pill-sm,
+.pill-md,
+.pill-lg { letter-spacing: 0.04em; }
+
 /* PADDING ONLY — type is kol-helper-*, applied in Pill.jsx. Same ruling as
  * .kol-tag--* above (2026-08-01). */
 .pill-sm { padding: 2px 10px; }
@@ -126,6 +134,22 @@
   border-radius: var(--kol-radius-full);
   border: 1px solid transparent;
   transition: background-color 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+  /* THE CHIP'S OWN TYPE (user rulings 2026-08-01, in two passes).
+   *
+   * First pass: the chip was moved onto the `kol-helper-*` ramp for its
+   * `line-height: 1` and inherited `letter-spacing: 0.10em` with it — the
+   * ramp's eyebrow tracking, and far too wide on a tag string. Set to `normal`.
+   *
+   * Second pass: `normal` is zero, which is too tight for caps. The chip is
+   * uppercase at **0.04em** — between the two, and the value the user named.
+   *
+   * UPPERCASE IS AN EXPLICIT EXCEPTION to the no-`text-transform` law, and the
+   * only one in the component tier. That law says casing is authored at the
+   * CALL SITE — which works because a call site exists. A tag has none: the
+   * string is `#domain/design-system`, generated from frontmatter data, so
+   * there is nowhere to author it. The transform lives here or nowhere. */
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
 }
 
 /* PADDING ONLY. Type is the kol-helper-* ramp, applied at the call site
@@ -413,6 +437,12 @@
   margin-block: 1.5rem;
 }
 
+/* THE BLOCK. Everything here is the SURFACE — fill, frame, font, wrapping.
+ * The two dimensional values (pad and type size) moved OUT to the size classes
+ * below (user ruling 2026-08-01: *"it has sizes, ok but its not set, so its
+ * just whatever its defaulting to? is that good? instead of saying sm or md?"*).
+ * They were unnamed constants sitting in this rule, so nothing could ask for a
+ * smaller block and nothing recorded that a choice had been made. */
 .kol-codeblock {
   /* verbatim from the reference build's rule (user DevTools, 2026-07-28) */
   background: var(--kol-surface-tertiary);
@@ -420,14 +450,28 @@
   font-family: var(--kol-font-family-mono);
   white-space: pre-wrap;
   overflow-wrap: break-word;
-  border-radius: 4px;
-  padding: 1rem;
-  font-size: 14px;
+  border-radius: var(--kol-radius-sm);
   line-height: 1.6;
   position: relative;
   overflow-x: auto;
 }
 
+/* THE SIZE AXIS — declared, not defaulted. `md` carries exactly the values the
+ * base rule used to hide, so nothing changes appearance until a call site asks
+ * for `sm`. Padding is the box, type is the ramp; both step together, because a
+ * tight box around 14px type is a different defect from small type in a roomy
+ * box. Size is INDEPENDENT of `bare`: bare removes the FRAME, size sets the
+ * BOX. A bare block still has a size. */
+.kol-codeblock--md {
+  padding: var(--kol-spacing-4);
+  font-size: var(--kol-text-body-02);
+}
+
+.kol-codeblock--sm {
+  padding: var(--kol-spacing-3);
+  font-size: var(--kol-text-body-03);
+}
+
 /* the ONE chip — filename if present, else the language. In-flow above the
  * code. VERBATIM from the live reference build (index-Bro9Jnn6.css). */
 /* bare — the host owns the frame (PreviewCard Code tab); the border/radius go,

package/kol-components-organisms.css

@@ -48,17 +48,9 @@
    * audit finding 4); oq-* mirrors the same visual weight without alpha */
   border: 1px solid var(--kol-oq-08);
   border-radius: 4px;
-  /* Scroll affordance: with the scrollbar hidden, a clipped table reads as
-   * cut-off data on narrow viewports. Edge shadows appear only on the
-   * scrollable side (surface-colored covers ride the content and mask them
-   * at the extremes). */
-  /* scroll edges: surface-colored FADE only — no shadow band (user ruling
-   * 2026-07-28: the content dissolves into the background, no 3d edge) */
-  background:
-    linear-gradient(to right, var(--kol-surface-primary) 40%, transparent) left / 32px 100%,
-    linear-gradient(to left, var(--kol-surface-primary) 40%, transparent) right / 32px 100%;
-  background-repeat: no-repeat;
-  background-attachment: local, local;
+  /* no scroll-edge paint — the 2026-07-28 ruling bans shadow bands, and the
+   * surface-primary "cover" gradients that outlived it rendered as exactly
+   * that band on any non-primary surface (brand app dark, 2026-08-09) */
 }
 
 .kol-table-wrapper::-webkit-scrollbar { display: none; }
@@ -178,7 +170,11 @@
   /* 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;
+  /* Radius is the shared chip radius, not a literal (2026-08-01). This one
+   * value was the last thing making a table token and a prose inline code chip
+   * read as two different objects — see the inline-code block in
+   * kol-type-roles.css, which owns the shared fill/radius/colour answer. */
+  border-radius: var(--kol-radius-sm);
   font-family: var(--kol-font-family-mono);
   font-size: 0.75rem;
   font-weight: 400;

package/kol-components-workshop.css

@@ -215,11 +215,11 @@
  *   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
+ * difference was `.text-default` — 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 —
+ * The weight is the difference, and it stays INSIDE the one ramp: 700 here
+ * against the page row's 100. Not a second type class —
  * R1 exists to stop a second RAMP in the rails, and a weight within one ramp
  * is not one.
  *
@@ -228,7 +228,14 @@
  * borrow this class — that is how the right rail drifted; use
  * .shell-sidebar-toggle. */
 .shell-nav-group-header {
+  /* MEDIUM + SHOUT (user ruling 2026-08-01, the settled pair). 700 was tried
+   * for one turn and reverted: with the page rows at Thin 100 the weight gap
+   * already carries, so the CHAPTER buys its prominence from INK instead —
+   * `shout` (88) against the rows' `fg-64`. Weight and colour each doing half
+   * the work beats either doing all of it, and 500 keeps the chapter inside
+   * the ramp's normal range. */
   font-weight: 500;
+  color: var(--kol-fg-shout);
   padding: var(--kol-pad-rail-row-y) 0;
   cursor: pointer;
   display: flex;
@@ -241,6 +248,52 @@
   color: color-mix(in srgb, var(--kol-surface-on-primary) 90%, transparent);
 }
 
+/* THE RAIL STACK — the SECTION container, owned here for exactly the reason
+ * `.shell-nav-items` below owns the ROW gap (user ruling 2026-08-01, said in
+ * anger and said before): *"I HAVE TOLD YOU LEFT AND RIGHT = THE SAME LAYOUT
+ * MARGINPADDING"*.
+ *
+ * The row gap was fixed on 2026-08-01 and the stack above it was not, so one
+ * layout shipped as FOUR idioms:
+ *
+ *   left rail   `flex flex-col gap-6`     ShellChrome.jsx
+ *   right rail  `space-y-6`               DocumentationReader.jsx
+ *   sidebars    `space-y-4`               ShellSidebar / WorkshopSidebar
+ *   rows        `space-y-0`               (the one already fixed)
+ *
+ * `gap` and `space-y-*` are not the same mechanism either — `space-y` is a
+ * margin on every child but the first, so it fights any child that sets its own
+ * margin, and the eyebrow box DOES (see the box law above). Flex gap does not.
+ *
+ * Two rungs, two gaps, one definition each. A rail stack is never a utility. */
+.shell-rail-stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kol-spacing-6);
+}
+
+/* Between GROUPS inside one category — tighter than between categories. The
+ * left rail said 16 and the right said 24 for the same relationship. */
+.shell-rail-stack-inner {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kol-spacing-4);
+}
+
+/* THE TAG SHELF — chips indented to the ROW text edge (user ruling 2026-08-01:
+ * "indent the tags like it was a text"). They were flush to the rail's left
+ * edge while every row beside them started one indent in, so the one block that
+ * is not a row was the only thing setting the rail's left margin. The inset is
+ * `.shell-nav-item`'s own left padding, read from the same declaration rather
+ * than typed again. */
+.shell-rail-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--kol-spacing-2);
+  padding-left: var(--kol-pad-rail-row-x);
+  padding-top: var(--kol-spacing-2);
+}
+
 /* 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 {
@@ -258,15 +311,34 @@
  *
  * `.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
+ * strings across five files — `block kol-mono-14 text-default 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`. */
+ * `RailRow`; `validate:rails` R4 fails a hand-written `shell-nav-item`.
+ *
+ * WEIGHT IS THIN (user ruling 2026-08-01, asked five times).
+ *
+ * The arithmetic, measured on the H stem at this size:
+ *
+ *   400 vs 500  1.26 → 1.39   the original pair. Invisible.
+ *   300 vs 500  1.11 → 1.39   +25%. Also invisible — applied, correct in the
+ *                             cascade, and unseeable.
+ *   200 vs 500  0.92 → 1.39   +51%. Still not enough for him.
+ *   100 vs 700  0.70 → 1.75   +150%. THE PAIR. Both ends of the usable axis.
+ *
+ * I argued against 100 on the grounds that it falls under one device pixel and
+ * antialiases to a wash. He ruled it anyway, and against 700 rather than 500
+ * the contrast carries the hierarchy the stroke alone could not.
+ *
+ * Renderable only because the family went VARIABLE the same day
+ * (kol-typography-mono.css, `wght 100 800`). Under the old static set the
+ * lightest cut was 300 and this line would have rounded back to 400. */
 .shell-nav-item {
+  font-weight: 100;
   display: flex;
   align-items: center;
   gap: 8px;
@@ -280,6 +352,11 @@
   color: var(--kol-fg-64);
   cursor: pointer;
   transition: color 0.15s ease, background-color 0.15s ease;
+  /* THE TEXT INDENT, named (2026-08-01). It was the last value of the padding
+   * shorthand above and nothing else could read it, so the tag shelf beside
+   * these rows had to guess and guessed flush-left. Declared after the
+   * shorthand deliberately — it overrides that slot and nothing else. */
+  padding-left: var(--kol-pad-rail-row-x);
 }
 
 .shell-nav-item:hover {
@@ -291,9 +368,36 @@
   outline-offset: -1px;
 }
 
-/* The active row — one definition, not `text-emphasis` typed at each site. */
+/* THE ACTIVE ROW — `emphasis`, the role, not a raw token (user ruling
+ * 2026-08-01). One definition for both rails: the left tree's current PAGE and
+ * the right rail's current SECTION are the same state, and where-you-are is the
+ * one thing in a rail that earns max ink. It read `var(--kol-surface-on-primary)`
+ * — the same value, reached without going through the ladder, which is how a
+ * role set ends up with call sites that do not know it exists. */
 .shell-nav-item.is-active {
-  color: var(--kol-surface-on-primary);
+  color: var(--kol-fg-emphasis);
+}
+
+/* THIS PAGE'S OWN ROW — brighter than the rest of the list (user ruling
+ * 2026-08-01, twice). The first attempt put `text-emphasis` on the row from the
+ * JSX and nothing happened: `.text-emphasis` and `.shell-nav-item` are both
+ * single-class selectors in the same cascade layer, and this file loads AFTER
+ * kol-opacity.css, so the rail's resting `--kol-fg-64` won every time. A colour
+ * utility cannot brighten a row whose own rule sets colour — the modifier has
+ * to live beside that rule. Same file, same specificity, declared later. */
+.shell-nav-item--own {
+  color: var(--kol-fg-emphasis);
+  font-weight: 500;
+}
+
+/* …AND THE REST STEP DOWN (user ruling 2026-08-01: *"no needs more"*). Raising
+ * the page's own tags to full ink was not enough on its own, because the rows
+ * beneath them sat at the rail's resting `fg-64` — close enough that the two
+ * ranks read as one list with a slightly brighter top. Contrast is a GAP, not a
+ * value: the other rank drops to `meta`, so the distance is 100 against 48
+ * rather than 100 against 64, and the weight moves too. */
+.shell-nav-item--muted {
+  color: var(--kol-fg-meta);
 }
 
 /* The trailing slot: counts, doc numbers, anything pushed right. */
@@ -401,7 +505,7 @@
   gap: 8px;
 }
 
-/* Doc meta row — layout only; type/color in JSX (kol-helper-10 text-body). */
+/* Doc meta row — layout only; type/color in JSX (kol-helper-10 text-default). */
 .docs-meta {
   display: flex;
   flex-wrap: wrap;
@@ -449,7 +553,35 @@
   min-width: 120px;
 }
 
-.docs-frontmatter-row:has(.tag) {
+/* THE VALUE COLUMN — it had no rule at all, so it was an auto-width flex item
+ * next to a fixed-width key: a long `description` or a `sources` path list had
+ * nothing telling it to shrink, and ran straight off the right edge of the
+ * panel (user screenshot 2026-08-01). `min-width: 0` is the half of the flex
+ * contract that was missing; `overflow-wrap: anywhere` handles the paths,
+ * which have no spaces to break at. */
+.docs-frontmatter-value {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+/* A MULTI-VALUE FIELD IS A LIST WITH A CEILING (2026-08-01). Stacked one per
+ * line, and capped at roughly eight rows before it scrolls in place — a doc
+ * with fifteen `sources` would otherwise push its own article fifteen lines
+ * down and turn the metadata panel into the page. */
+.docs-frontmatter-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kol-spacing-1);
+  max-height: 11rem;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* `.tag` was the Tag component's base class until it was rebuilt on Pill's
+ * model (2026-08-01) and the scheme became `kol-tag`. The selector has matched
+ * nothing since. */
+.docs-frontmatter-row:has(.kol-tag) {
   align-items: center;
 }
 

package/kol-opacity.css

@@ -5,6 +5,8 @@
  * scattered across kol-color-simple.css and framework/app.css.
  *
  * Scale: 01, 02, 04, 08, 12, 16, 24, 32, 40, 48, 64, 80, 88, 96 (14 stops)
+ *        + 72 in the STANDARD tier only (2026-08-01) — 15 stops there, 14
+ *        everywhere else. The exception is stated at the token itself.
  *
  * Tier pairs:
  * - Standard (foreground on primary surface — var(--kol-surface-on-primary))
@@ -18,9 +20,9 @@
  * Every color-mix expression uses `var(<token>, currentColor)` — fallback is
  * load-bearing for SVG theming where the element's `color:` is the active paint.
  *
- * Semantic text role classes (.text-emphasis/lede/body/meta/subtle) live here
- * too — they map directly to the fg-* primitives below, no intermediate alias
- * tokens. Single source of truth per opacity stop.
+ * Semantic text roles live here too — EIGHT of them since 2026-08-01
+ * (subtle · meta · body · lede · strong · shout · scream · emphasis), each an
+ * alias over one fg-* stop. `default` is a deprecated alias of `body`.
  */
 
 :root {
@@ -39,6 +41,15 @@
   --kol-fg-40: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent);
   --kol-fg-48: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent);
   --kol-fg-64: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent);
+  /* 72 — THE ONE OFF-RAMP STOP (user ruling 2026-08-01). The scale is a
+   * 14-stop signature and this makes it 15, deliberately and in ONE tier only:
+   * the eight TEXT roles below needed a step between body (64) and strong (80)
+   * for `lede`, and text chains exclusively through --kol-fg-*. The absolute
+   * and inverse tiers below, and the whole --kol-oq-* family, do NOT get a 72:
+   * they exist for fills and for theme-independent chrome, and neither has a
+   * role asking for this step. If a FILL ever needs 72, that is the signal to
+   * add it across all five families rather than widen this exception. */
+  --kol-fg-72: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent);
   --kol-fg-80: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent);
   --kol-fg-88: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent);
   --kol-fg-96: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent);
@@ -113,6 +124,7 @@
 .bg-fg-40 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .bg-fg-48 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .bg-fg-64 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.bg-fg-72 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .bg-fg-80 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .bg-fg-88 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .bg-fg-96 { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -170,6 +182,7 @@
 .hover\:bg-fg-40:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .hover\:bg-fg-48:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .hover\:bg-fg-64:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.hover\:bg-fg-72:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .hover\:bg-fg-80:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .hover\:bg-fg-88:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .hover\:bg-fg-96:hover { background-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -204,6 +217,7 @@
 .text-fg-40 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .text-fg-48 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .text-fg-64 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.text-fg-72 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .text-fg-80 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .text-fg-88 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .text-fg-96 { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -238,6 +252,7 @@
 .hover\:text-fg-40:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .hover\:text-fg-48:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .hover\:text-fg-64:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.hover\:text-fg-72:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .hover\:text-fg-80:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .hover\:text-fg-88:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .hover\:text-fg-96:hover { color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -272,6 +287,7 @@
 .border-fg-40 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .border-fg-48 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .border-fg-64 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.border-fg-72 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .border-fg-80 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .border-fg-88 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .border-fg-96 { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -306,6 +322,7 @@
 .hover\:border-fg-40:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 40%, transparent); }
 .hover\:border-fg-48:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 48%, transparent); }
 .hover\:border-fg-64:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 64%, transparent); }
+.hover\:border-fg-72:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 72%, transparent); }
 .hover\:border-fg-80:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 80%, transparent); }
 .hover\:border-fg-88:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 88%, transparent); }
 .hover\:border-fg-96:hover { border-color: color-mix(in srgb, var(--kol-surface-on-primary, currentColor) 96%, transparent); }
@@ -326,30 +343,51 @@
 .hover\:border-fg-inverse-96:hover { border-color: color-mix(in srgb, var(--kol-surface-on-inverse, currentColor) 96%, transparent); }
 
 /* ==============================================================================
- * SEMANTIC OPACITY DESCRIPTORS
+ * SEMANTIC OPACITY DESCRIPTORS — EIGHT ROLES (user ruling 2026-08-01)
  *
- * Six-stop hierarchy: subtle / mute / meta / body / strong / emphasis. Each
- * stop is a token (--kol-fg-*) and a class family (text-*, bg-*, border-*,
- * ring-*) so the same descriptor names work across every property.
+ * Each role is a token (--kol-fg-*) and a text class, so the same name works
+ * wherever ink is set.
  *
- * Stops:
  *   subtle    24% — dividers, disabled hints, faintest visible
- *   mute      32% — dim labels, quiet UI hints
- *   meta      48% — labels, eyebrows, captions  (current text-meta workhorse)
- *   body      64% — running copy, links         (current text-body default)
- *   strong    80% — emphasized body, <strong>   (renamed from text-lede)
- *   emphasis 100% — headings, max ink            (current text-emphasis)
+ *   meta      48% — labels, captions
+ *   body      64% — running copy, links (the resting ink)
+ *   lede      72% — the step that did not exist; see --kol-fg-72 above
+ *   strong    80% — emphasized body, <strong>, eyebrows
+ *   shout     88% — chrome that has to cut through
+ *   scream    96% — the loudest thing that is not full ink
+ *   emphasis 100% — headings, max ink
  *
- * Tokens chain through the existing fg-opacity ramp — single source of truth
- * (the 14-stop --kol-fg-{01..96} family) is preserved; descriptors are aliases.
+ * WHAT CHANGED, AND WHAT DELIBERATELY DID NOT. `default` became `body` —
+ * the name 25 files spelled as the resting ink while four others already wrote
+ * `text-body` into a class that did not exist. `emphasis` STAYS at 100%: 83
+ * files reach for it as max ink, and moving it would have dimmed every heading
+ * in the estate silently, with nothing failing. Three roles are new over stops
+ * that already existed; only `lede` needed a new stop.
+ *
+ * The naming shifts register at 88 — subtle…strong are document roles, shout
+ * and scream are volume. That is deliberate: the top two are for chrome, not
+ * for text.
+ *
+ * `mute` (32%) was retired 2026-04-30 with zero consumers and does not return.
+ *
+ * Tokens chain through the fg ramp — single source of truth is preserved;
+ * descriptors are aliases, never their own colour values.
  * ============================================================================== */
 
 :root {
   --kol-fg-subtle:    var(--kol-fg-24);
   --kol-fg-meta:      var(--kol-fg-48);
   --kol-fg-body:      var(--kol-fg-64);
+  --kol-fg-lede:      var(--kol-fg-72);
   --kol-fg-strong:    var(--kol-fg-80);
+  --kol-fg-shout:     var(--kol-fg-88);
+  --kol-fg-scream:    var(--kol-fg-96);
   --kol-fg-emphasis:  var(--kol-surface-on-primary);
+
+  /* DEPRECATED ALIAS — `default` is the old name for `body`, kept pointing at
+   * the same stop so a consumer mid-sweep cannot render colourless. Remove once
+   * no source references it. */
+  --kol-fg-default:   var(--kol-fg-body);
 }
 
 /* ─── Text descriptors (5 stops — `mute` retired 2026-04-30, 0 consumers).
@@ -359,11 +397,21 @@
 .text-subtle    { color: var(--kol-fg-subtle); }
 .text-meta      { color: var(--kol-fg-meta); }
 .text-body      { color: var(--kol-fg-body); }
+.text-lede      { color: var(--kol-fg-lede); }
 .text-strong    { color: var(--kol-fg-strong); }
+.text-shout     { color: var(--kol-fg-shout); }
+.text-scream    { color: var(--kol-fg-scream); }
 .text-emphasis  { color: var(--kol-fg-emphasis); }
 
+/* Deprecated alias — see the token block. */
+.text-default   { color: var(--kol-fg-body); }
+
 .hover\:text-subtle:hover    { color: var(--kol-fg-subtle); }
 .hover\:text-meta:hover      { color: var(--kol-fg-meta); }
 .hover\:text-body:hover      { color: var(--kol-fg-body); }
+.hover\:text-lede:hover      { color: var(--kol-fg-lede); }
 .hover\:text-strong:hover    { color: var(--kol-fg-strong); }
+.hover\:text-shout:hover     { color: var(--kol-fg-shout); }
+.hover\:text-scream:hover    { color: var(--kol-fg-scream); }
 .hover\:text-emphasis:hover  { color: var(--kol-fg-emphasis); }
+.hover\:text-default:hover   { color: var(--kol-fg-body); }

package/kol-theme.css

@@ -81,6 +81,11 @@
    * and needs no alias of its own. */
   --kol-pad-rail-row-y: 0.375rem;
 
+  /* The row's TEXT INDENT — `.shell-nav-item`'s left padding, named 2026-08-01
+   * so anything else that has to line up with a row (the tag shelf) reads the
+   * indent instead of retyping it. */
+  --kol-pad-rail-row-x: 1.25rem;
+
   /* 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

package/kol-type-roles.css

@@ -24,7 +24,15 @@
  * ============================================================================= */
 
 /* eyebrow — the overline label above a title ("KOL · ICONS"). Single-line
- * chrome → helper ramp (line-height 1); never carries paragraphs. */
+ * chrome → helper ramp (line-height 1); never carries paragraphs.
+ *
+ * Ink: --kol-fg-strong (80%), raised from --kol-fg-meta (48%) on 2026-08-01 by
+ * user ruling. An eyebrow is a SECTION HEADER, not a caption: it names the
+ * material below it and is what the eye lands on when scanning a rail. At the
+ * meta stop it sat at the same weight as the captions and disabled hints it is
+ * supposed to outrank, so the rail read as one flat field. Uppercase mono at
+ * the smallest step with wide tracking is already a quiet treatment — the ink
+ * does not also need to whisper. */
 .kol-doc-eyebrow {
   font-family: var(--kol-font-family-mono);
   font-size: 10px;
@@ -32,7 +40,7 @@
   font-weight: 500;
   letter-spacing: 0.1em;
   text-transform: uppercase;
-  color: var(--kol-fg-meta);
+  color: var(--kol-fg-strong);
 }
 
 /* heading — the page H1 of doc chrome (matches the DocHeader contract). */
@@ -60,7 +68,7 @@
   line-height: 160%;
   font-weight: 400;
   letter-spacing: 0.04em;
-  color: var(--kol-fg-body);
+  color: var(--kol-fg-default);
   max-width: var(--kol-content-measure);
 }
 
@@ -72,7 +80,7 @@
   line-height: 160%;
   font-weight: 400;
   letter-spacing: 0.04em;
-  color: var(--kol-fg-body);
+  color: var(--kol-fg-default);
   max-width: var(--kol-content-measure);
 }
 
@@ -93,13 +101,31 @@
 .kol-doc-code { margin: 0; }
 .kol-prose pre { margin: 24px 0; }   /* prose keeps its editorial block rhythm */
 
-/* inline code */
+/* INLINE CODE — the chip look, shared with `.kol-table-token` (user question
+ * 2026-08-01: *"list all the inline code classes, why do we have more then
+ * one?"*). There are three, and only two of them are one concept:
+ *
+ *   .kol-doc-code-inline   prose inline code. Size is RELATIVE (0.875em) so it
+ *                          tracks whatever text it sits in. Wraps.
+ *   .kol-table-token       the same chip as fixed-size chrome inside a Table.
+ *                          Never wraps. Defined in kol-components-organisms.css
+ *                          because it belongs to that component.
+ *   .kol-doc-table-token   NOT a chip — a `td` SLOT (no fill, no padding, no
+ *                          radius) that types a whole cell as one token. It
+ *                          only shares the word "token".
+ *
+ * The two chips had drifted on every value that makes them look alike: fg-04
+ * against fg-08, radius-sm against a bare literal, no colour against fg-80.
+ * Same concept, two spellings — the `.text-fg-*` vs `--kol-fg-*` lesson again.
+ * FILL, RADIUS and COLOUR are now one answer; size and padding stay per role,
+ * because relative-in-prose and fixed-in-chrome is a real difference. */
 .kol-prose code,
 .kol-doc-code-inline {
   font-family: var(--kol-font-family-mono);
   font-size: 0.875em;
   font-weight: 400;
-  background: var(--kol-fg-04);
+  color: var(--kol-fg-80);
+  background: var(--kol-fg-08);
   padding: 0.1em 0.35em;
   border-radius: var(--kol-radius-sm);
 }
@@ -147,7 +173,7 @@
   padding: 12px 16px;
   border-bottom: 1px solid var(--kol-fg-08);
   vertical-align: top;
-  color: var(--kol-fg-body);
+  color: var(--kol-fg-default);
 }
 .kol-prose tbody tr:last-child td,
 .kol-doc-table tbody tr:last-child td { border-bottom: 0; }

package/kol-typography-mono.css

@@ -7,60 +7,44 @@
  * the scale with its own mono font — fonts are per-app (brand = JetBrains Mono,
  * web = RightGroteskMono). The umbrella kol-theme.css imports both files.
  *
- * Italic note: only 500i is bundled (Medium Italic). 400i (Regular Italic)
- * deferred until a consumer requires it.
+ * VARIABLE, since 2026-08-01. Two files carry every weight in the family.
  *
  * Architecture: docs/kol-migration/locked/typography-system.md
  */
 
 /* =============================================================================
- * FONT-FACE — JetBrains Mono (6 faces: 400, 400i, 500, 500i, 600, 600i)
+ * FONT-FACE — JetBrains Mono, VARIABLE (2 faces: roman + italic, wght 100–800)
+ *
+ * WHY (user ruling 2026-08-01). This was SEVEN static cuts and it still could
+ * not answer a simple design question. The rail needed a Page weight lighter
+ * than its Chapter; the folder's lightest cut was 300, and 300 against 500 is a
+ * 0.28px difference in stroke at 14px — applied, correct in the cascade, and
+ * invisible. Reaching a weight that reads meant shipping another static, and
+ * the next question would have meant another one.
+ *
+ * The axis removes the question. `wght 100 800` means any weight is a NUMBER,
+ * not a new file — and the payload went DOWN: two variable faces at ~230 kb
+ * against 1024 kb of statics, with four weights the statics never had.
+ *
+ * The tradeoff, stated: a variable file is one download, so the page fetches
+ * the whole axis or none of it. At this size that is still less than the two
+ * static cuts it replaces.
  * ============================================================================= */
 
 @font-face {
   font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-Regular.woff2') format('woff2');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-Italic.woff2') format('woff2');
-  font-weight: 400;
-  font-style: italic;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-Medium.woff2') format('woff2');
-  font-weight: 500;
-  font-style: normal;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-MediumItalic.woff2') format('woff2');
-  font-weight: 500;
-  font-style: italic;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-SemiBold.woff2') format('woff2');
-  font-weight: 600;
+  src: url('/fonts/jetbrains-mono/JetBrainsMono-Variable.woff2') format('woff2-variations'),
+       url('/fonts/jetbrains-mono/JetBrainsMono-Variable.woff2') format('woff2');
+  font-weight: 100 800;
   font-style: normal;
   font-display: swap;
 }
 
 @font-face {
   font-family: 'JetBrains Mono';
-  src: url('/fonts/jetbrains-mono/JetBrainsMono-SemiBoldItalic.woff2') format('woff2');
-  font-weight: 600;
+  src: url('/fonts/jetbrains-mono/JetBrainsMono-Italic-Variable.woff2') format('woff2-variations'),
+       url('/fonts/jetbrains-mono/JetBrainsMono-Italic-Variable.woff2') format('woff2');
+  font-weight: 100 800;
   font-style: italic;
   font-display: swap;
 }

package/package.json

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