@kolkrabbi/kol-theme 0.36.0 → 0.38.0

package/README.md

@@ -21,6 +21,17 @@ Cascade order is load-bearing — `kol-theme` must come after Tailwind so its co
 
 All KOL rule CSS lives in the `components` cascade layer, so your Tailwind utility classes always win over KOL chrome (`<Input className="hidden sm:block">` behaves as written). Your own unlayered CSS wins over everything KOL ships.
 
+## The `@source` contract — required for every KOL package that ships JSX
+
+Tailwind v4 **does not scan `node_modules`**, so layout utilities emitted inside KOL components never generate unless you point the scanner at each package's source. Without these lines components **silently degrade** — no error, no warning, just missing layout/motion (a frozen ThemeToggle roll, a collapsed AppShell grid). Paste one line per installed KOL package, next to the imports above:
+
+```css
+@source "../node_modules/@kolkrabbi/kol-component/src";
+@source "../node_modules/@kolkrabbi/kol-framework/src";
+```
+
+(Adjust the relative path to your CSS file's location. Component-load-bearing *chrome* lives in this package's CSS and needs no `@source` — the contract covers the remaining per-render utilities.)
+
 ## Fonts
 
 The typography CSS references the brand fonts at absolute paths (`/fonts/Right-Grotesk/…`, `/fonts/jetbrains-mono/…`). **The package does not ship the font files** — your app must serve them from `/fonts/` (e.g. drop them in your `public/` dir). The showcase in this repo does exactly that. Without them, type falls back to system fonts.

package/kol-components-atoms.css

@@ -1012,3 +1012,26 @@ a.kol-icon-frame {
   border-radius: 0;
   padding: 0;
 }
+
+/* The ROLL mechanics — .kol-roll (ComponentTailwindSourceTrap, 2026-08-12).
+ * These were Tailwind utilities emitted in ThemeToggle's JSX (overflow-hidden,
+ * transition-transform, duration-500, ease-in-out) — and Tailwind never scans
+ * node_modules, so any consumer without the @source lines got a SILENTLY
+ * static glyph: visible, clickable, no travel, no coin-roll, no error.
+ * A component's own moving parts live HERE, in the CSS it ships — the
+ * consumer's scanner owes it nothing. Widths/transforms stay inline in JSX
+ * (they are per-render geometry, not chrome). */
+.kol-roll {
+  position: relative;
+  display: inline-block;
+  overflow: hidden;
+}
+.kol-roll-strip {
+  display: flex;
+  transition: transform 500ms ease-in-out;
+}
+.kol-roll-slot {
+  display: inline-flex;
+  line-height: 0;
+  transition: transform 500ms ease-in-out;
+}

package/kol-components-molecules.css

@@ -472,11 +472,20 @@
   border: 1px solid var(--kol-fg-04);
   border-radius: var(--kol-radius-sm);
   overflow: hidden;
-}
-
-/* Sizes mirror .kol-btn-{sm,md,lg} exactly: cell padding per size (below) +
- * mono type (12/14/16) applied on the cell in JSX. Height is padding-driven,
- * so a strip matches a Button of the same size. md is the base. */
+  /* The button-height LAW (2026-08-12): the strip's OUTER height is PINNED
+   * to the .kol-btn ladder — 26 / 32 / 40 — regardless of what a cell holds
+   * (icon or text) and regardless of variant (the filled variant drops the
+   * group border, so padding-driven height ran 2px short — the bug that
+   * forced the pin). Same principle as .kol-btn-icon's pinned square:
+   * the box never moves. */
+  box-sizing: border-box;
+  height: 32px; /* md — .kol-btn-md */
+}
+
+/* Sizes mirror .kol-btn-{sm,md,lg} exactly: pinned height above + cell
+ * padding per size (below) + mono type (12/14/16) applied in JSX. */
+.kol-seg--sm { height: 26px; }
+.kol-seg--lg { height: 40px; }
 .kol-seg--sm .kol-seg-cell { padding: 4px 12px; }
 .kol-seg--lg .kol-seg-cell { padding: 8px 20px; }
 
@@ -490,7 +499,11 @@
   border: none;
   cursor: pointer;
   white-space: nowrap;
-  color: var(--kol-fg-meta);
+  /* OPAQUE rest paint (estate opaque-icons law, 2026-08-12): cells host
+   * icon labels, and alpha ink (--kol-fg-meta) compounds where strokes
+   * overlap — oq-48 reads identical on the resting surface but stays
+   * opaque. Hover/active use fg-emphasis, which is full ink (no alpha). */
+  color: var(--kol-oq-48);
   transition: color var(--kol-transition-base),
               background-color var(--kol-transition-base);
 }
@@ -509,10 +522,12 @@
   outline-offset: -2px;
 }
 
-/* Filled variant — the segmented state law (2026-08-12): every cell is a
- * FILLED TILE (input surface tone) with 1px transparent gaps — never an
- * outline shell around the group; the outlined treatment marks ONLY the
- * selected cell (inset ring). Group radius clips the outer tile corners. */
+/* Filled variant — the CORRECTED segmented state law (2026-08-12, second
+ * ruling — SegmentedFilledStateFix): the SELECTED cell is the DARK FILLED
+ * tile (input surface tone) + bright glyph — the dark state IS the selection
+ * marker. Unselected cells are QUIET: transparent, dim, hover brightens.
+ * NO outline ring, ever. (The 0.36.0 first reading — always-tiled cells +
+ * inset ring on selected — was the inversion this block repeals.) */
 .kol-seg--filled {
   border: none;
   gap: 1px;
@@ -520,14 +535,22 @@
 }
 
 .kol-seg--filled .kol-seg-cell {
-  background: var(--kol-surface-secondary);
+  background: transparent;
+  /* the dark tile rounds itself (SegBar reference geometry) */
+  border-radius: var(--kol-radius-sm);
 }
 
 .kol-seg--filled .kol-seg-cell + .kol-seg-cell { border-left: none; }
 
 .kol-seg--filled .kol-seg-cell.is-active {
   background: var(--kol-surface-secondary);
-  box-shadow: inset 0 0 0 1px var(--kol-fg-24);
+  color: var(--kol-fg-emphasis);
+}
+
+/* Tonal variant (2026-08-12, user ask): same quiet-unselected law, but the
+ * clicked cell marks itself on the tertiary tone. */
+.kol-seg--tonal .kol-seg-cell.is-active {
+  background: var(--kol-surface-tertiary);
   color: var(--kol-fg-emphasis);
 }
 

package/package.json

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