@kolkrabbi/kol-framework 0.10.3 → 0.13.0

package/kol-framework.css

@@ -31,8 +31,21 @@ body {
 
 :root {
   --kol-topnav-h: 0px;
-  --kol-sidenav-w: 260px;
+  /* 16rem — the rail width, one number (2026-07-31). It read 260 while every
+     grid track that had to line up with it read 256, so the shell header's
+     brand block sat 4 off the sidebar column it exists to align to. */
+  --kol-sidenav-w: 16rem;
   --kol-sidenav-w-collapsed: 56px;
+  /* The workshop shell's RIGHT rail. EQUAL TO THE LEFT (user ruling
+     2026-08-01) — the two rails frame the same content and a lopsided frame is
+     a frame nobody drew on purpose; it read 14rem against the left's 16rem.
+     Kept as its own token rather than aliased: the right rail can be ruled
+     different later without touching the sidenav.
+     The track is RESERVED whether or not the rail has anything in it — a rail
+     that vanishes on a heading-less page re-flows main, so the same shell
+     renders at two widths. Distinct from --kol-toc-w further down, which is
+     the BRAND layout's rail: same concept, two shells, two numbers. */
+  --kol-shell-toc-w: 16rem;
   --kol-container-max: 100%;
 
   /* Opacity tokens (--kol-fg-*) + text-role tokens (--kol-text-*) live in
@@ -44,6 +57,15 @@ body {
      Intentional: site chrome uses browser-ease for a softer feel. */
   --kol-t-btn: background 200ms ease, color 200ms ease, border-color 200ms ease;
 
+  /* Shell CHROME inset (2026-07-31, user ruling: "24, it's what lives in
+     kolkrabbi") — a separate concern from the page ladder below, and
+     deliberately tighter: chrome is not page content. The shell header and the
+     shell content frame both read this, so they cannot disagree; before it,
+     the header carried bare Tailwind steps and the frame carried the page ramp.
+     FLAT, not stepped — one value at every width, on the user's word.
+     Do NOT reach for this on page containers — that is --kol-pad-section-x. */
+  --kol-pad-chrome-x: var(--kol-spacing-6);
+
   /* Stepped page / section / band padding tokens.
      Used by chrome (topnav, sidenav) and landing bands. Scaled at 768 / 1024
      breakpoints so one set of rules covers mobile → desktop without clamp(). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.10.3",
+  "version": "0.13.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,8 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.15.1",
-    "@kolkrabbi/kol-icons": "0.8.11"
+    "@kolkrabbi/kol-component": "0.24.0",
+    "@kolkrabbi/kol-icons": "0.10.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/AppShell.jsx

@@ -53,7 +53,7 @@ export default function AppShell({ navTree = [], getActivePage, header, footer,
             </button>
 
             <div
-              className="kol-sidenav-backdrop fixed inset-0 z-20 bg-black/50 opacity-0 pointer-events-none transition-opacity duration-200 md:hidden"
+              className="kol-sidenav-backdrop fixed inset-0 z-20 kol-overlay-scrim opacity-0 pointer-events-none transition-opacity duration-200 md:hidden"
               onClick={() => setDrawerOpen(false)}
               aria-hidden="true"
             />

package/src/ShellHeader.jsx

@@ -1,5 +1,5 @@
 import { Icon } from '@kolkrabbi/kol-icons'
-import { SearchInput, Tooltip } from '@kolkrabbi/kol-component'
+import { IconFrame, SearchInput, Tooltip, glyphSize } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle.jsx'
 
 /**
@@ -42,8 +42,35 @@ import ThemeToggle from './ThemeToggle.jsx'
  * @param {string}    className      extra classes on the outer bar
  */
 
-const iconBtnCls =
-  'flex h-9 w-9 items-center justify-center rounded p-0 bg-transparent border-0 cursor-pointer transition-colors hover:bg-fg-08 hover:text-emphasis'
+/* ONE header-action glyph size (user 2026-08-01: "icon in navbar is small and
+ * wrong"). The row mixed sizes: the ThemeToggle draws its solo glyph at 24 on
+ * the `lg` rung while search, GitHub and the hamburger sat at 18 — four
+ * controls, two scales, in a row eight inches wide.
+ *
+ * It is NOT an independent number. Every header control is a `lg` rung, and
+ * `SOLO.lg` (hooks/glyphLadders.js) is 24 — this constant is that ladder rung
+ * under a name the chrome can import. Naming it once was not enough on its own:
+ * it shipped exported and the two rail toggles still hardcoded 18 three rows
+ * below it, which is the whole reason the row looked wrong after the fix. The
+ * durable answer is that no header control writes a glyph size at all — it
+ * writes `size="lg"` and the ladder resolves it.
+ *
+ * @deprecated 2026-08-01 — **zero consumers as of this change.** Every header
+ * control now names its rung and takes the glyph from `SOLO`. Kept exported
+ * because it is public API of a published package (breaking an export needs a
+ * changeset + major bump); a consumer still importing it gets the right number,
+ * it is just no longer how the chrome decides. Passing it as `iconSize` is the
+ * anti-pattern this whole change removes: it pins the glyph while leaving the
+ * SQUARE on whatever rung the call site forgot to set, which is precisely how
+ * the search trigger ended up drawing an lg glyph in an md box. */
+export const HEADER_ICON = 24
+
+/* `iconBtnCls` lived here — a private class string re-implementing the icon
+ * button box (h-9 w-9, rounded, transparent, hover wash) on three call sites,
+ * with a near-duplicate of it hand-written in the showcase's GitHub link. Four
+ * containers, one job. Deleted 2026-08-01: the box has an owner, and it is
+ * `Button variant="ghost" quiet iconOnly` — the shape the search trigger in
+ * ShellLayout had been calling correctly the entire time. */
 
 export default function ShellHeader({
   brand,
@@ -66,7 +93,11 @@ export default function ShellHeader({
     <header className={`kol-shell-header sticky top-0 z-50 shrink-0 bg-surface-primary ${className}`.trim()}>
       {/* Row 1: brand block + controls */}
       <div className="border-b border-fg-08">
-        <div className="w-full px-4 py-4 md:px-5 lg:px-6">
+        {/* Chrome inset from --kol-pad-chrome-x, not Tailwind steps
+          * (2026-07-31): the header sat on its own improvised steps while the
+          * shell content frame sat on the page ramp, so the sidebar hung right
+          * of the wordmark above it. One token, both surfaces. */}
+        <div className="w-full py-4" style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
           <div className="flex items-center justify-between">
             {/* kol-shell-header-brand reserves the nav-column width at lg+ so
              * the Row-2 tabs align to the shell grid. */}
@@ -82,19 +113,24 @@ export default function ShellHeader({
                     * quiet square = button geometry + fill none + no label
                     * (was the old `icon` variant default). */}
                   <span className="hidden lg:inline-flex"><ThemeToggle fill="none" label={false} size="lg" /></span>
-                  <span className="lg:hidden"><ThemeToggle fill="none" label={false} /></span>
+                  <span className="lg:hidden"><ThemeToggle fill="none" label={false} size="lg" /></span>
                 </Tooltip>
               )}
               {onMenuClick && (
                 <Tooltip label="Open navigation menu">
-                  <button
-                    type="button"
-                    className={`${iconBtnCls} text-fg-64`}
+                  {/* IconFrame, not Button (user ruling 2026-08-01). Header
+                    * chrome takes a click but must not light up; the frame has
+                    * no state rules at all, which is the property Button can
+                    * only approximate by dropping its own. `nav` rests at
+                    * oq-64 — the `text-fg-64` this control hand-wrote for
+                    * months. */}
+                  <IconFrame
+                    name="hamburger"
+                    variant="nav"
+                    size="lg"
                     onClick={onMenuClick}
                     aria-label="Open navigation menu"
-                  >
-                    <Icon name="hamburger" size={18} />
-                  </button>
+                  />
                 </Tooltip>
               )}
             </div>
@@ -105,7 +141,7 @@ export default function ShellHeader({
       {/* Row 2: section tabs + inline search + rail toggles */}
       {hasTabRow && (
         <div className="border-b border-fg-08">
-          <div className="w-full px-4 md:px-5 lg:px-6">
+          <div className="w-full" style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
             <div className="kol-shell-header-tabs">
               <nav className="flex flex-1 gap-6" aria-label="Sections">
                 {nav.map((item) => {
@@ -118,7 +154,12 @@ export default function ShellHeader({
                       aria-current={active ? 'page' : undefined}
                       onClick={onNavigate ? (event) => onNavigate(event, item) : undefined}
                     >
-                      {item.icon && <Icon name={item.icon} size={14} />}
+                      {/* The ladder, not a literal (2026-08-01). This hardcoded
+                        * 14 — the same value ADJACENT.sm carries, but written
+                        * out, so the tab could not follow the rule it was
+                        * meant to. The tab's own type is 14/18, which is that
+                        * rung. */}
+                      {item.icon && <Icon name={item.icon} size={glyphSize('sm')} />}
                       {item.label}
                     </a>
                   )
@@ -135,28 +176,32 @@ export default function ShellHeader({
                 <div className="hidden lg:flex items-center gap-1 pb-2">
                   {onNavToggle && (
                     <Tooltip label="Toggle navigation sidebar">
-                      <button
-                        type="button"
-                        className={`${iconBtnCls} ${navCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      {/* The collapsed tint is a VARIANT SWAP, not a state:
+                        * `ghost` rests at oq-48, `nav` at oq-64, and both are
+                        * static classes with no rules to fire. That is the only
+                        * honest way to express it on a frame — Button's `quiet`
+                        * is an opacity transition, i.e. exactly the kind of
+                        * behaviour this control was ruled out of. */}
+                      <IconFrame
+                        name="panel-left"
+                        variant={navCollapsed ? 'ghost' : 'nav'}
+                        size="sm"
                         onClick={onNavToggle}
                         aria-label="Toggle navigation sidebar"
                         aria-pressed={!navCollapsed}
-                      >
-                        <Icon name="panel-left" size={18} />
-                      </button>
+                      />
                     </Tooltip>
                   )}
                   {onTocToggle && (
                     <Tooltip label="Toggle table of contents sidebar">
-                      <button
-                        type="button"
-                        className={`${iconBtnCls} ${tocCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      <IconFrame
+                        name="panel-right"
+                        variant={tocCollapsed ? 'ghost' : 'nav'}
+                        size="sm"
                         onClick={onTocToggle}
                         aria-label="Toggle table of contents sidebar"
                         aria-pressed={!tocCollapsed}
-                      >
-                        <Icon name="panel-right" size={18} />
-                      </button>
+                      />
                     </Tooltip>
                   )}
                 </div>

package/src/index.js

@@ -10,7 +10,7 @@
 export { default as AppShell } from './AppShell.jsx'
 export { ShellTocContext, ShellTocCollapsedContext } from './AppShell.jsx'
 export { default as SideNav } from './SideNav.jsx'
-export { default as ShellHeader } from './ShellHeader.jsx'
+export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
 export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY } from './theme.js'
 export { default as Layout } from './Layout.jsx'