@kolkrabbi/kol-framework 0.44.0 → 0.46.0

package/kol-framework.css

@@ -63,16 +63,17 @@ body {
   --kol-sidenav-step: var(--kol-spacing-4);    /* keyboard resize increment */
   --kol-sidenav-snap-default: var(--kol-sidenav-step); /* release within this of the default clears the override */
   --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;
+  /* THE WORKSHOP SHELL'S RAILS — their own pair, 256px each (showcase
+     refinement 2026-09-28, user: "should they both be the same width? layout
+     feels asymmetrical"). The left rail used to read --kol-sidenav-w, which is
+     the DRAGGABLE app sidenav's ladder (264, 320 from 1536 — useDragResize,
+     NavRail, the labs rail, the deck editor), so the docs shell rendered
+     320 | main | 256: one token, two shells. The workshop rails are not
+     draggable and frame the same content, so they are equal and fixed, in px
+     like every other layout width. Distinct from --kol-toc-w further down,
+     which is the BRAND layout's rail. */
+  --kol-shell-nav-w: 256px;
+  --kol-shell-toc-w: 256px;
   --kol-container-max: 100%;
 
   /* Opacity tokens (--kol-fg-*) + text-role tokens (--kol-text-*) live in
@@ -176,7 +177,7 @@ body {
 }
 /* A nested route GROUP's header (sidenav-nested-groups, kol-studio
  * 2026-08-26): a non-routing label sitting where a leaf sits, its rows one
- * step further in. Type and colour ride the element as utilities
+ * step further in. Type and color ride the element as utilities
  * (kol-helper-10; text-subtle, text-emphasis when a leaf beneath it is the
  * route); the box lives here. No text-transform — the retired fork's
  * `uppercase` does not return (type law: only the display voice carries one). */
@@ -736,7 +737,7 @@ body {
 .kol-portal-footer a { text-decoration: none; transition: opacity 150ms ease; }
 .kol-portal-footer a:hover { opacity: 0.8; }
 
-/* ───── Back link (structural only; use kol-helper-xs uppercase tracking-widest text-fg-64 on JSX) ───── */
+/* ───── Back link (structural only; PageHero sets its type: kol-helper-12 tracking-widest text-body) ───── */
 
 .kol-back-link {
   display: inline-flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.44.0",
+  "version": "0.46.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",
@@ -21,8 +21,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.186.0",
-    "@kolkrabbi/kol-icons": "^0.25.0"
+    "@kolkrabbi/kol-icons": "^0.29.1",
+    "@kolkrabbi/kol-component": "^0.230.0"
   },
   "files": [
     "src",

package/src/PageLayout.jsx

@@ -55,7 +55,7 @@ export const ShellTocCollapsedContext = createContext(null)
  * @param {ReactNode} footer             below the outlet on the plane
  * @param {ReactNode} defaultTocContent  the TOC rail's content when no page registers one
  * @param {object}    sideNav            every SideNav prop this layout does not own, spread onto the rail
- * @param {string}    pageWash           the plane's wash, a CSS colour (e.g. `'var(--kol-fg-02)'`)
+ * @param {string}    pageWash           the plane's wash, a CSS color (e.g. `'var(--kol-fg-02)'`)
  * @param {boolean}   bare               plane + outlet only (default false)
  */
 export default function PageLayout({ navTree = [], header, footer, defaultTocContent, sideNav, pageWash, bare = false }) {
@@ -117,6 +117,7 @@ export default function PageLayout({ navTree = [], header, footer, defaultTocCon
             data-drawer-open={drawerOpen ? 'true' : undefined}
             data-toc={showToc ? 'true' : undefined}
           >
+            {/* tip-ok: phone-only (md:hidden) — a hover tip never shows on touch; the aria-label names it */}
             <button
               type="button"
               className="kol-sidenav-hamburger md:hidden fixed top-3 left-3 z-30 w-10 h-10 inline-flex items-center justify-center rounded-full bg-surface-primary border border-fg-08 text-emphasis"

package/src/ShellHeader.jsx

@@ -128,15 +128,15 @@ export default function ShellHeader({
             <div className="flex shrink-0 items-center gap-1">
               {actions}
               {showThemeToggle && (
-                <Tooltip label="Toggle theme">
+                <>
                   {/* md at every width (user re-rule 2026-08-09: the whole
                     * header glyph row rides md, full ink — the earlier lg-at-lg+
                     * split is repealed, which also collapsed the two spans). */}
                   <ThemeToggle fill="none" label={false} size="md" />
-                </Tooltip>
+                </>
               )}
               {onMenuClick && (
-                <Tooltip label="Open navigation menu">
+                <Tooltip label="Menu">
                   {/* 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
@@ -193,7 +193,7 @@ export default function ShellHeader({
               {(onNavToggle || onTocToggle) && (
                 <div className="hidden lg:flex items-center gap-1 pb-2">
                   {onNavToggle && (
-                    <Tooltip label="Toggle navigation sidebar">
+                    <Tooltip label="Navigation">
                       {/* 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
@@ -211,7 +211,7 @@ export default function ShellHeader({
                     </Tooltip>
                   )}
                   {onTocToggle && (
-                    <Tooltip label="Toggle table of contents sidebar">
+                    <Tooltip label="Contents">
                       <IconFrame
                         name="panel-right"
                         variant={tocCollapsed ? 'ghost' : 'nav'}

package/src/SideNav.jsx

@@ -398,7 +398,7 @@ function SideNavInner({
        * the aside's position/height/stack live in .kol-sidenav
        * (kol-framework.css). `sticky … h-dvh z-20` here outranked the 767px
        * drawer rule's `position: fixed`, so every consumer page opened one
-       * viewport down on phones. Only colour utilities ride the element. */
+       * viewport down on phones. Only color utilities ride the element. */
       className={`kol-sidenav${background ? ' bg-surface-primary' : ''}${hairline ? ' border-r border-fg-08' : ''}${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
     >
       {/* NO chip Button in either state (user build order 2026-08-09 — "MAKE

package/src/ThemeToggle.jsx

@@ -1,4 +1,5 @@
 import { Icon } from '@kolkrabbi/kol-icons'
+import { Tooltip } from '@kolkrabbi/kol-component'
 import { useTheme } from './theme.js'
 
 /**
@@ -88,6 +89,12 @@ export default function ThemeToggle({
    * ink, so the toggle beside a sunken Dropdown matches it; `inverse` aliased. Rules in kol-theme. */
   tone = 'default',
   className = '',
+  /* THE TOGGLE CARRIES ITS OWN TOOLTIP (2026-09-28). It set a native `title`
+   * AND the header wrapped it in a KOL Tooltip, so hovering showed both — the
+   * browser's "Switch to light mode · following your system" under the DS's
+   * "Toggle theme". One tip now, the DS one, with the richer text; `false`
+   * leaves the button bare for a caller that wraps it itself. */
+  tooltip = true,
 }) {
   const { theme, mode, cycle, clear } = useTheme()
   /* six tones (tone-is-the-ground-axis, 2026-09-03); unset inherits the wrapper's */
@@ -148,13 +155,16 @@ export default function ThemeToggle({
   const shared = {
     type: 'button',
     onClick,
-    'aria-label': `Switch to ${next} mode`,
-    title: `Switch to ${next} mode${resetHint}`,
+    'aria-label': `Switch to ${next} mode${resetHint}`,
   }
+  /* ONE WORD (2026-09-30, open questions Round 1 Q4 — ruled many times); the alt-click hint
+   * stays in the aria-label and the S sheet, not the tooltip */
+  const tip = 'Theme'
+  const wrap = (node) => (tooltip ? <Tooltip label={tip}>{node}</Tooltip> : node)
 
   /* ── DEPRECATED aliases — old chrome verbatim (0.6.x) ── */
   if (variant === 'icon') {
-    return (
+    return wrap(
       <button {...shared} className={`kol-theme-toggle kol-theme-toggle-none kol-btn-${size} kol-btn-icon ${extra}`.trim()}>
         {iconSwap(glyphSolo)}
       </button>
@@ -176,7 +186,7 @@ export default function ThemeToggle({
     const chromeCls = bare
       ? `w-full inline-flex items-center justify-start gap-2 ${barePadY} px-6 ${mono} bg-transparent text-emphasis`
       : 'kol-theme-toggle kol-theme-toggle-subtle kol-btn-md kol-mono-14 w-full justify-start gap-2'
-    return (
+    return wrap(
       <button {...shared} className={`${chromeCls} ${extra}`.trim()}>
         <span className="inline-flex items-center justify-center shrink-0" aria-hidden="true">
           {iconSwap(bare ? glyphWithText : glyphSolo)}
@@ -194,7 +204,7 @@ export default function ThemeToggle({
   if (variant === 'flush') {
     const glyph = label ? glyphWithText : glyphSolo
     const cls = `kol-theme-toggle kol-theme-toggle-flush gap-2 ${mono} ${width} ${extra}`
-    return (
+    return wrap(
       <button {...shared} className={cls.replace(/\s+/g, ' ').trim()}>
         {!iconRight && iconSwap(glyph)}
         {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>}
@@ -209,13 +219,13 @@ export default function ThemeToggle({
   const fillCls = fill === 'none' ? 'kol-theme-toggle-none' : 'kol-theme-toggle-subtle'
   if (!label) {
     // icon-only pins the square box per rung — geometry condition, not a variant
-    return (
+    return wrap(
       <button {...shared} className={`kol-theme-toggle ${fillCls} kol-btn-${size} kol-btn-icon ${width} ${extra}`.replace(/\s+/g, ' ').trim()}>
         {iconSwap(glyphSolo)}
       </button>
     )
   }
-  return (
+  return wrap(
     <button {...shared} className={`kol-theme-toggle ${fillCls} kol-btn-${size} ${mono} gap-2 ${width} ${extra}`.replace(/\s+/g, ' ').trim()}>
       {!iconRight && iconSwap(glyphWithText)}
       <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>