@kolkrabbi/kol-component 0.229.0 → 0.231.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.229.0",
+  "version": "0.231.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -25,8 +25,8 @@
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-markdown": "^0.1.1",
-    "@kolkrabbi/kol-search": "^0.2.0"
+    "@kolkrabbi/kol-search": "^0.2.0",
+    "@kolkrabbi/kol-markdown": "^0.1.2"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-icons": ">=0.22.0",
@@ -37,7 +37,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.29.0"
+    "@kolkrabbi/kol-icons": "^0.31.0"
   },
   "files": [
     "src",

package/src/atoms/ActionButton.jsx

@@ -146,7 +146,7 @@ export default function ActionButton({
     const rest = restRef.current
     const on = onRef.current
     /* no confirmIcon = ONE glyph, and the state is carried by the class alone
-     * (a fill, a colour). Nothing to crossfade. */
+     * (a fill, a color). Nothing to crossfade. */
     if (!rest || !on) return undefined
 
     if (first.current) {

package/src/atoms/Button.jsx

@@ -18,7 +18,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {string} props.iconRight - Icon name to display on the right
  * @param {string} props.iconLeftHover - Icon to show on hover (left position)
  * @param {string} props.iconRightHover - Icon to show on hover (right position)
- * @param {'primary'|'secondary'|'inverted'|'outline'|'ghost'|'grey'|'sunken'} props.tone - the ground (`secondary` = the page surface, `inverted` = the text colour as fill — what `variant="secondary"` paints) (tone-is-the-ground-axis, 2026-09-03) — wins over `variant` on the same element; unset = inherit the wrapper's. `sunken` = the control set's dark well + fg-96 ink (ControlToneSunken); `inverse` aliased
+ * @param {'primary'|'secondary'|'inverted'|'outline'|'ghost'|'grey'|'sunken'} props.tone - the ground (`secondary` = the page surface, `inverted` = the text color as fill — what `variant="secondary"` paints) (tone-is-the-ground-axis, 2026-09-03) — wins over `variant` on the same element; unset = inherit the wrapper's. `sunken` = the control set's dark well + fg-96 ink (ControlToneSunken); `inverse` aliased
  * @param {string} props.iconOnly - Icon name for icon-only button
  * @param {string} props.iconOnlyHover - Icon to show on hover (icon-only)
  * @param {boolean} props.animateIcon - Disable default hover states to focus on icon animation
@@ -82,7 +82,7 @@ const Button = ({
    * rung, oq-80 ink + aria-current — it had lived in the theme with no
    * component able to emit it, the direct cause of the four-container header. */
   /* An UNKNOWN variant is a typo, not a request for the inverted fill — it fell back to
-   * `kol-btn-secondary` (the text colour as fill) until 2026-09-29, so a misspelt variant
+   * `kol-btn-secondary` (the text color as fill) until 2026-09-29, so a misspelt variant
    * shipped inverted. It now stamps nothing, like an unset variant: the wrapper's tone,
    * else primary — and says so in dev. */
   const KNOWN = ['primary', 'secondary', 'accent', 'outline', 'ghost', 'nav', 'danger', 'grey']

package/src/atoms/IconFrame.jsx

@@ -22,7 +22,7 @@ import { toneClass } from '../utilities/tone.js'
  * frame's own classes declare the same background, foreground and geometry and
  * simply have no state rules to inherit.
  *
- * `variant` borrows the kol-btn COLOUR SET verbatim so the frame sits in the
+ * `variant` borrows the kol-btn COLOR SET verbatim so the frame sits in the
  * same visual system as real buttons; `primary` and `secondary` are inverse
  * pairs that flip with the theme, so light/dark comes free from the tokens with
  * no per-theme props.

package/src/atoms/Kbd.jsx

@@ -0,0 +1,33 @@
+/**
+ * Kbd — a key cap: one key or chord (↵, ⌘K, Esc) shown as an affordance.
+ * Replaces the two hand-rolled <kbd> chips (SearchInput's shortcut hint and
+ * the palette footer) that had drifted apart (2026-09-30). A plate, so it
+ * takes oq — never fg (icons-use-oq law).
+ *
+ * aria-hidden by default: a cap is a hint beside a label, not the label.
+ *
+ * @param {'sm'|'md'} size  sm = inside a control (16px, helper-10) ·
+ *                          md = beside helper-12 text (20px)
+ * @param {string}    icon  kol-icons name drawn before the children — a key
+ *                          with a symbol (↵ `corner-down-left`, ⌘ `command`)
+ *                          is a GLYPH, never a typed character in the mono face
+ */
+import { Icon } from '@kolkrabbi/kol-icons'
+
+const SIZE = {
+  sm: 'h-4 min-w-4 px-1 kol-helper-10',
+  md: 'h-5 min-w-5 px-1.5 kol-helper-12',
+}
+
+export default function Kbd({ size = 'md', icon, className = '', children, ...rest }) {
+  return (
+    <kbd
+      aria-hidden="true"
+      className={`inline-flex items-center justify-center gap-0.5 shrink-0 rounded-[var(--kol-radius-xs)] bg-oq-08 text-oq-64 ${SIZE[size] ?? SIZE.md} ${className}`.trim()}
+      {...rest}
+    >
+      {icon && <Icon name={icon} size={12} />}
+      {children}
+    </kbd>
+  )
+}

package/src/atoms/SizeOrDownload.jsx

@@ -21,7 +21,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * click, and this one is inside the link rather than being it.
  *
  * Both hover parts ink on the OPACITY scale (`text-oq-80`), not an `fg-*` role:
- * a stroke glyph on a flat fg colour reads wrong against the plate, and oq is
+ * a stroke glyph on a flat fg color reads wrong against the plate, and oq is
  * what the rest of the chrome uses.
  *
  * ONE type class throughout — kol-mono-12. helper-12 is line-height 1 against

package/src/atoms/Tag.jsx

@@ -18,7 +18,7 @@ const ICON_SIZES = { xs: 8, sm: 10, md: 12, lg: 14 }
  *     `:hover` rule between them, on `.tag-control`. Every other path rendered
  *     dead.
  *   - `color` was a SECOND axis that silently swapped the base class from
- *     `tag-control` to `tag tag--{color}` — so passing a colour cost you the
+ *     `tag-control` to `tag tag--{color}` — so passing a color cost you the
  *     interaction state, invisibly. That is what shipped a solid blue pill you
  *     could not hover.
  *   - `variant="solid"` and a `solid` boolean did the same job.
@@ -28,8 +28,8 @@ const ICON_SIZES = { xs: 8, sm: 10, md: 12, lg: 14 }
  *
  * Now it is Pill's vocabulary — `primary` (filled) · `secondary` (outlined) ·
  * `inverse` — one size scale, ONE class scheme (`kol-tag--*`), and every
- * variant carries hover + active. Colour is not a prop: a chip's look is its
- * variant, exactly as it is on Pill and Button. Tag colour BY TAXONOMY returns
+ * variant carries hover + active. Color is not a prop: a chip's look is its
+ * variant, exactly as it is on Pill and Button. Tag color BY TAXONOMY returns
  * later as its own decision, on top of the variants rather than instead of them.
  *
  * @param {ReactNode} children   label content

package/src/hooks/colorMath.js

@@ -116,7 +116,7 @@ export function harmonyColors(hue, harmony, { saturation = 100, lightness = 50 }
  * package's `colors` payload was half-ignorable).
  *
  * A slot that is `locked`, empty, or has no hex is passed through untouched —
- * locking a colour is the one instruction a re-hue must not overrule.
+ * locking a color is the one instruction a re-hue must not overrule.
  *
  * @param {number} hue base hue, 0–360
  * @param {string|object} harmony harmony id or object

package/src/index.js

@@ -22,14 +22,14 @@ export { default as AssetPlaceholder } from './utilities/AssetPlaceholder.jsx'
 export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
-export { default as CloseButton } from './utilities/CloseButton.jsx'
+export { default as CloseButton } from './atoms/CloseButton.jsx'
 export { default as ActionButton } from './atoms/ActionButton.jsx'
 export { default as FileIcon } from './atoms/FileIcon.jsx'
 export { default as SizeOrDownload } from './atoms/SizeOrDownload.jsx'
 export { default as SortHeader } from './atoms/SortHeader.jsx'
 export { default as SortControls } from './molecules/SortControls.jsx'
 export { default as CopyButton } from './molecules/CopyButton.jsx'
-export { default as CurveOverlay } from './atoms/CurveOverlay.jsx'
+export { default as CurveOverlay } from './utilities/CurveOverlay.jsx'
 export { default as Divider } from './atoms/Divider.jsx'
 export { default as DocsToc } from './molecules/DocsToc.jsx'
 export { default as DropdownTagFilter } from './molecules/DropdownTagFilter.jsx'
@@ -49,7 +49,7 @@ export { default as LabeledControl } from './molecules/LabeledControl.jsx'
 export { default as OverlayGlassPanel } from './utilities/OverlayGlassPanel.jsx'
 export { default as Pill } from './atoms/Pill.jsx'
 export { usePopover, PopoverPanel, Tooltip } from './utilities/Popover.jsx'
-export { default as ContextMenu, useContextMenu } from './utilities/ContextMenu.jsx'
+export { default as ContextMenu, useContextMenu } from './molecules/ContextMenu.jsx'
 export { default as ProsePreview } from './utilities/ProsePreview.jsx'
 export { default as QuantityInput } from './molecules/QuantityInput.jsx'
 export { default as RotaryDial } from './atoms/RotaryDial.jsx'
@@ -59,6 +59,7 @@ export { default as SectionText } from './molecules/SectionText.jsx'
 export { default as SectionLabel } from './atoms/SectionLabel.jsx'
 export { default as SegmentedToggle } from './atoms/SegmentedToggle.jsx'
 export { default as Stepper } from './molecules/Stepper.jsx'
+export { default as Kbd } from './atoms/Kbd.jsx'
 export { default as Tag } from './atoms/Tag.jsx'
 export { default as Textarea } from './atoms/Textarea.jsx'
 export { default as ToggleBracket } from './atoms/ToggleBracket.jsx'
@@ -73,8 +74,8 @@ export { default as InspectorRail } from './molecules/InspectorRail.jsx'
 /* SelectionOverlay's two siblings — same 1080-virtual contract, same zoom
  * division (editor-panels-the-held-specs B2). `pathMath` is their geometry,
  * exported because the editor engine re-exports it rather than keep a copy. */
-export { default as PathNodeOverlay } from './atoms/PathNodeOverlay.jsx'
-export { default as CropOverlay } from './atoms/CropOverlay.jsx'
+export { default as PathNodeOverlay } from './utilities/PathNodeOverlay.jsx'
+export { default as CropOverlay } from './utilities/CropOverlay.jsx'
 export { default as LayerStack, AddLayerButton, BLEND_MODES } from './organisms/LayerStack.jsx'
 export { TYPE_LABELS, BOOL_OP_LABELS, SHAPE_KIND_LABELS, labelForLayer, rowLabelForLayer, findLayerDeep } from './hooks/layerTree.js'
 export { default as TimelineDock, sampleTrack, TIMELINE_EASINGS } from './organisms/TimelineDock.jsx'
@@ -88,7 +89,7 @@ export { default as ButtonGroup } from './utilities/ButtonGroup.jsx'
 /* monorepo sets (P6–P10) — molecule members */
 export { default as AlignmentGrid } from './molecules/AlignmentGrid.jsx'
 export { default as ImageBlock } from './molecules/ImageBlock.jsx'
-export { default as SelectionOverlay } from './atoms/SelectionOverlay.jsx'
+export { default as SelectionOverlay } from './utilities/SelectionOverlay.jsx'
 export { default as VideoBlock, getEmbedUrl } from './molecules/VideoBlock.jsx'
 export { default as SectionCardItem, default as CardFeatureItem } from './molecules/SectionCardItem.jsx'
 export { default as CodeBlock } from './molecules/CodeBlock.jsx'

package/src/molecules/ColorInputRow.jsx

@@ -243,7 +243,7 @@ export default function ColorInputRow({
           )}
           {/* QUICK STATES. Theme (the auto value — a token that flips with
               light/dark) is offered only where the field HAS one; None is
-              always available, because clearing a colour is not a palette
+              always available, because clearing a color is not a palette
               decision. Both were dropped in the first port, which is what left
               `value == null` renderable but unreachable. */}
           <div className="flex items-center gap-2">

package/src/molecules/ContentCard.jsx

@@ -47,7 +47,7 @@ const BOX = {
   /* SLIDE (slide-variant-and-shelf-preset, kol-client-olina 2026-09-03; user: "they are genuinely
    * different with 16:9 layout and those exposed properties"): file's stack — cover on top, the
    * plate below — on the PAGE'S surface, rest and hover (olina's /slide-deck, read off the render).
-   * The plate is not a tone (user: "no just controls"); it is this kind's colour. */
+   * The plate is not a tone (user: "no just controls"); it is this kind's color. */
   slide: { layout: 'stack', border: null, bg: 'var(--kol-surface-primary)', pad: 'var(--kol-pad-card-sm)' },
   /* THE FRAME READS BACKWARDS (CatalogCardFrameAndZoom, kol-website 2026-08-28 — user, on a 212-tile
    * grid: no frame at rest; the old rest value is the hover): a wall of fg-04 frames is a grid of boxes,
@@ -94,7 +94,7 @@ const BOX = {
  * has no surface of its own to step, so it dims its title instead. */
 const HOVER = {
   file:  'var(--kol-oq-04)',
-  slide: 'var(--kol-surface-primary)', /* the plate holds its colour on hover; the drawer control is the affordance */
+  slide: 'var(--kol-surface-primary)', /* the plate holds its color on hover; the drawer control is the affordance */
   catalog:  'var(--kol-surface-tertiary)',
   /* article and work take NO surface hover, and that is a decision not a gap:
    * article has no surface of its own (its media frame, when on, steps its
@@ -168,7 +168,7 @@ export default function ContentCard({
    * print draw it); `false` turns it off without an `!important` in a consumer sheet */
   plateRule,
   /* `bg` — the card's REST fill, overriding the variant's. It sets
-   * `--kol-card-bg`, not a background, because the rest colours are custom
+   * `--kol-card-bg`, not a background, because the rest colors are custom
    * properties so the hover class can win; that is also why
    * `className="bg-oq-48"` does nothing here and a consumer reaching around the
    * component had to write `className="[--kol-card-bg:var(--kol-oq-48)]"`
@@ -437,7 +437,7 @@ export default function ContentCard({
     'data-tags': isHero && Array.isArray(text.tags) && text.tags.length ? text.tags.join(' ') : undefined,
     className: `kol-card group flex ${box.layout === 'canvas' && reveal != null ? 'has-reveal' : ''} ${expanded ? 'flex-col md:flex-row-reverse' : 'flex-col'} ${box.layout === 'drawer' ? 'relative overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${framed ? 'overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${box.border ? 'border' : ''} ${box.layout === 'canvas' ? 'relative' : ''} ${interactive ? 'cursor-pointer select-none' : ''} ${hoverBg && interactive ? 'kol-content-hover' : ''} ${interactive && box.frameHover ? 'kol-content-hover-frame' : ''} ${className}`.trim(),
     style: {
-      /* same reason as ContentRow: rest colours are PROPERTIES, because an
+      /* same reason as ContentRow: rest colors are PROPERTIES, because an
        * inline background/borderColor outranks the hover class and the step
        * would never render. */
       '--kol-card-bg': bg ?? box.bg ?? undefined,
@@ -464,7 +464,7 @@ export default function ContentCard({
         onContextMenu={onContextMenu}
         onDoubleClick={onDoubleClick}
         /* SELECTED HAS TO SHOW (user 2026-09-23: a click in the grid "should select/highlight").
-         * `selected` only flipped a border colour on the variants that HAVE a border, and the file
+         * `selected` only flipped a border color on the variants that HAVE a border, and the file
          * wall's cards have none — so the prop was true and the card looked untouched. The
          * attribute is the hook; the theme paints it, once, for every variant. */
         data-selected={selected || undefined}

package/src/molecules/ContentMedia.jsx

@@ -57,7 +57,7 @@ import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
  * @param {boolean}   frame     tinted box + border UNDER the media
  * @param {boolean}   border    border only, no tint
  * @param {string}    bg        tint only, no border — a raw token value
- * @param {string}    borderHover  border colour on hover (article's fg-16 step)
+ * @param {string}    borderHover  border color on hover (article's fg-16 step)
  * @param {boolean}   ring      hairline border OVER the media, inset
  * @param {boolean|'hero'} zoom  the artwork creeps up inside its frame on the
  *                            card's hover — 1.06; `'hero'` = the hero rung, 1.02

package/src/molecules/ContentRow.jsx

@@ -130,7 +130,7 @@ const BOX = {
                      * its background and read as a different interaction from every other listing.
                      *
                      * The three passes are the lesson: the ask was "make it look like /work" and
-                     * each ticket named only the state someone had looked at — rest colours, then
+                     * each ticket named only the state someone had looked at — rest colors, then
                      * the derive's collateral, then this. When a user says make X look like Y,
                      * diff EVERY state: rest, hover, selected, focus. */
                     bg: 'var(--kol-surface-secondary)', frame: 'transparent', frameHover: 'var(--kol-fg-08)' },
@@ -171,7 +171,7 @@ export default function ContentRow({
    * card, `contentcard-bg-and-text-props` 2026-09-03; the pair ships together
    * and a consumer that re-grounds one hits the same wall on the other in the
    * same grid). It sets `--kol-row-bg`, not a background, because the rest
-   * colours are custom properties so the hover class can win — which is why
+   * colors are custom properties so the hover class can win — which is why
    * `className="bg-oq-48"` does nothing here either. `selected` still wins:
    * a selected row is the list's state, not the consumer's ground. For the
    * row's INK, pass `text` — it falls through to ContentText. */

package/src/{utilities → molecules}/ContextMenu.jsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from 'react'
-import { usePopover, PopoverPanel } from './Popover.jsx'
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx'
 
 /**
  * ContextMenu — a right-click menu, anchored at the pointer.

package/src/molecules/DocsToc.jsx

@@ -128,7 +128,7 @@ export default function DocsToc({
                * `block transition-colors focus-visible:ring-focus
                * hover:text-emphasis text-body` as utilities, so the same rung
                * rendered a different className here than in the left tree.
-               * Layout, colour, hover and focus live in `.shell-nav-item` now;
+               * Layout, color, hover and focus live in `.shell-nav-item` now;
                * active is the shared `is-active` marker, not `text-emphasis`
                * typed at one call site. Matches RailRow exactly. */
               className={`shell-nav-item kol-mono-14${activeId === item.id ? ' is-active' : ''}`}

package/src/molecules/PaletteHarmonyWheel.jsx

@@ -43,11 +43,11 @@ import { HARMONIES, harmonyById, harmonyColors, normHue, reHueSlots } from '../h
  * @param {Array}         harmonies   injectable scheme table (default HARMONIES)
  * @param {Array}         slots       the CURRENT palette in role order (`{hex, locked}` objects or plain hex strings). Given, `colors` re-hues these — each slot keeps its own S/L, locked and empty entries pass through — instead of generating flat ones
  * @param {Function}      onChange    ({ hue, colors }) => void
- * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colours
+ * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colors
  */
 
 /* Marker outline — white for contrast against the fully-saturated ring hues
- * (theme-independent: the wheel's colours, not the surface, sit behind it). */
+ * (theme-independent: the wheel's colors, not the surface, sit behind it). */
 const MARKER_STROKE = '#FFFFFF'
 
 export default function PaletteHarmonyWheel({
@@ -74,9 +74,9 @@ export default function PaletteHarmonyWheel({
   /* Emit next hue + its harmony colors. Held in a ref so the pointer/key
    * handlers stay stable while always seeing the latest props.
    *
-   * With `slots`, the colours are the CALLER'S palette re-hued — each slot
+   * With `slots`, the colors are the CALLER'S palette re-hued — each slot
    * keeping its own saturation and lightness — rather than a fresh flat set.
-   * Both fire, so a caller can take the hue and ignore the colours. */
+   * Both fire, so a caller can take the hue and ignore the colors. */
   emitRef.current = (nextHue) => {
     const h = normHue(nextHue)
     const colors = slots?.length

package/src/molecules/ProfileCard.jsx

@@ -27,7 +27,7 @@ import { surfaceClass } from '../utilities/sectionSurface.js'
  * `inverse` with inverse ink, exactly as shipped. `controlVariant` goes straight
  * to the disclosure's `IconFrame`; `pad` is `ContentCard`'s — one step on
  * `--kol-pad-card-*`, overriding the size ramp's padding. The logo is a slot
- * and stays one: its ink follows the shelf, a coloured mark is the asset's.
+ * and stays one: its ink follows the shelf, a colored mark is the asset's.
  *
  * THE SHELF SIZES TO ITS CONTENT. The source held it in a fixed box
  * (`h-60`/`h-44`/`h-32`/`h-24`, `overflow-hidden`) and every vertical size

package/src/molecules/QuickLookFrame.jsx

@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react'
 import Button from '../atoms/Button.jsx'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 
 /* taxonomy-ok: molecule — nests Button (atom) + CloseButton (utility). */
 

package/src/molecules/SearchInput.jsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import { toneClass } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { glyphSize } from '../hooks/glyphLadders.js'
+import Kbd from '../atoms/Kbd.jsx'
 
 /**
  * SearchInput — controlled search field on the .kol-control shell. The
@@ -200,8 +201,10 @@ export default function SearchInput({
   const shellCls = [
     bare
       /* kol-control--bare: zero-chrome marker so the theme's coarse-pointer
-       * 16px floor covers this body plan too (OverlaySearchFieldZoomsIOS) */
-      ? 'kol-control--bare flex w-full gap-2.5 px-4 py-3'
+       * 16px floor covers this body plan too (OverlaySearchFieldZoomsIOS).
+       * Chrome off, geometry on: the size's padding + a transparent 1px ring
+       * land it on the 22 · 26 · 32 · 40 ladder like the shell (09-sizes) */
+      ? `kol-control--bare kol-control-${size} flex w-full border border-transparent gap-2`
       : `kol-control${variant ? ` kol-control--${variant}` : ''} kol-control-${size} gap-2${toneClass(tone) ? ` ${toneClass(tone)}` : ''}`,
     'items-center cursor-text',
     SIZE_TYPE[size],
@@ -225,7 +228,7 @@ export default function SearchInput({
     <label className={shellCls}>
       <span
         aria-hidden="true"
-        className={`flex items-center shrink-0 ${bare ? 'text-fg-48' : 'text-auto opacity-50'}`}
+        className={`flex items-center shrink-0 ${bare ? 'text-oq-48' : 'text-auto opacity-50'}`}
       >
         {/* ADJACENT — this glyph sits in the field's line box beside the query */}
         <Icon name="search" size={iconSize ?? glyphSize(size)} />
@@ -254,12 +257,10 @@ export default function SearchInput({
         </button>
       ) : shortcutHint ? (
         /* aria-hidden — affordance, not a label (same stance as Input's prefix/suffix) */
-        <kbd
-          aria-hidden="true"
-          className="inline-flex items-center justify-center shrink-0 h-4 min-w-4 px-1 rounded-[var(--kol-radius-xs)] bg-fg-08 kol-helper-10 text-fg-48"
-        >
-          {shortcutHint}
-        </kbd>
+        /* ⌘ is drawn, not typed — the mono face's ⌘ is the "drawn by a child" cap */
+        shortcutHint.startsWith('⌘')
+          ? <Kbd size="sm" icon="command">{shortcutHint.slice(1)}</Kbd>
+          : <Kbd size="sm">{shortcutHint}</Kbd>
       ) : null}
     </label>
   )

package/src/molecules/ShellDrawer.jsx

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import { pushLayer, popLayer, isTopLayer } from '../utilities/layerStack.js'
 import { createPortal } from 'react-dom'
 import { Icon } from '@kolkrabbi/kol-icons'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /* taxonomy-ok: nests kol-icons's Icon (a package import the relative-import

package/src/molecules/SwatchControls.jsx

@@ -4,7 +4,7 @@ import ColorSwatch from '../atoms/ColorSwatch.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /*
- * SwatchControls — the Photoshop-style top row of the colour panel, in two
+ * SwatchControls — the Photoshop-style top row of the color panel, in two
  * hand-tuned pieces plus the composed row. Hand-tuned visuals (fixed pixel
  * slots, the overlap-by-DOM-order trick, the double-ring halo, the red-slash
  * "none" marker). DO NOT refactor pieces to atoms — the look is intentional
@@ -20,7 +20,7 @@ import { Tooltip } from '../utilities/Popover.jsx'
  *       No z-index, no transform — DOM order alone stacks them.
  *
  *   <EyedropPick sampleColor onPick disabled />
- *     — eyedropper icon button + a small sample chip of the sampled colour.
+ *     — eyedropper icon button + a small sample chip of the sampled color.
  *       The button is feature-gated: it is hidden entirely when the browser
  *       EyeDropper API is unavailable, and `disabled` dims it when supported
  *       but unusable. The actual EyeDropper call + canvas sampling live at the
@@ -92,7 +92,7 @@ export function SwatchStack({
 }
 
 /**
- * EyedropPick — eyedropper icon button + a sample chip of the sampled colour.
+ * EyedropPick — eyedropper icon button + a sample chip of the sampled color.
  * The button is hidden when the browser EyeDropper API is unavailable (no
  * affordance for an action that can't run); when supported but unusable pass
  * `disabled` to dim it. `onPick` is the app seam where EyeDropper + canvas

package/src/molecules/TabsRow.jsx

@@ -1,5 +1,5 @@
 import { useRef } from 'react'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 import { Icon } from '@kolkrabbi/kol-icons'
 
 /* taxonomy-ok: nests kol-icons's Icon */

package/src/organisms/Canvas.jsx

@@ -93,7 +93,7 @@ export function CanvasFrame({
   const { ratio, label } = resolveAspect(aspect, customRatio, aspects)
   /* NO guideColor → THEME INK (editor DS sync 2026-09-27, from the design editor's copy, which had
    * it and this lift had not): the border and label follow the theme, so the frame reads on a light
-   * page and a dark one. A guideColor (a type frame's own colour) still tints both. */
+   * page and a dark one. A guideColor (a type frame's own color) still tints both. */
   const borderColor = guideColor ? `color-mix(in srgb, ${guideColor} 24%, transparent)` : 'var(--kol-oq-24)'
   const labelColor = guideColor ? `color-mix(in srgb, ${guideColor} 70%, transparent)` : 'var(--kol-fg-64)'
   const virtualH = CANVAS_VIRTUAL_W / ratio

package/src/organisms/ContentFilters.jsx

@@ -395,7 +395,7 @@ const ContentFilters = ({
               * 05-control-chrome.md:109 — "any icon-only control in chrome is
               * IconFrame; nothing hand-writes the square". This wore
               * `kol-btn-md kol-btn-icon` and then removed the background, the
-              * border and the colour by inline style, which is the whole button
+              * border and the color by inline style, which is the whole button
               * paid for and thrown away — and it left the control with no
               * states at all while the search beside it had hover.
               *

package/src/organisms/MediaLibraryPages.jsx

@@ -22,7 +22,7 @@ import { filterMedia, rankMedia } from '../utilities/mediaSearch.js'
 import { useMasthead, mastheadTitleClass } from '../utilities/masthead.js'
 import { MenuItem, MenuDropdownItem, MenuDropdownDivider } from '../molecules/MenuItem.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
-import ContextMenu, { useContextMenu } from '../utilities/ContextMenu.jsx'
+import ContextMenu, { useContextMenu } from '../molecules/ContextMenu.jsx'
 import useMarquee from '../hooks/useMarquee.js'
 import useLongPress from '../hooks/useLongPress.js'
 import useMediaQuery from '../hooks/useMediaQuery.js'

package/src/organisms/SectionCards.jsx

@@ -36,7 +36,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    sectionClassName · wrapperClassName · cardsWrapperClassName · actionsClassName · headerClassName · headerTextWidthClass  layout seams

package/src/organisms/SectionCta.jsx

@@ -30,7 +30,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    className     extra classes on the section

package/src/organisms/SectionFaq.jsx

@@ -21,7 +21,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    className · innerClassName  layout seams

package/src/organisms/SectionNewsletter.jsx

@@ -60,7 +60,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}   [fullBleed=false]  the FILL breaks the page gutter while the content keeps it
  *   (SectionNewsletterFullBleed, kol-website 2026-08-31). This card is a filled surface inside
  *   `.kol-page`, so the gutter clipped its background and left strips of page down both sides of the
- *   colour. Fill and content padding are the same box, so a consumer could not bleed one without
+ *   color. Fill and content padding are the same box, so a consumer could not bleed one without
  *   dragging the other out with it. The breakout literal is SectionHero's, character for character —
  *   two organisms in one family must not invent two ways to leave a gutter. The section's own
  *   `px-5 sm:px-8` then re-insets the content, so only the fill moves.

package/src/organisms/ShellSearchOverlay.jsx

@@ -1,6 +1,26 @@
 import { useEffect, useId, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
 import SearchInput from '../molecules/SearchInput.jsx'
 import Tag from '../atoms/Tag.jsx'
+import Kbd from '../atoms/Kbd.jsx'
+
+/* ONE COLUMN (2026-09-30): rows, headings and footer sit on the field's own
+ * geometry — the p-2 inset, then the md control's 1px ring + 16px pad — so
+ * every glyph and word lines up under the field's icon and caret. */
+import { glyphSize } from '../hooks/glyphLadders.js'
+
+/* Rows bucketed by `group` in first-seen order, rank kept inside a group —
+ * one heading per group; arrows rove this order, not the engine's. */
+function groupRows(rows) {
+  const order = []
+  const byGroup = new Map()
+  rows.forEach((r) => {
+    const g = r.group ?? ''
+    if (!byGroup.has(g)) { byGroup.set(g, []); order.push(g) }
+    byGroup.get(g).push(r)
+  })
+  return order.flatMap((g) => byGroup.get(g))
+}
 
 /**
  * HighlightMatch — default row renderer: underlines the first
@@ -56,7 +76,9 @@ export function HighlightMatch({ label, query, ranges }) {
  *
  * @param {boolean}  open          mount/unmount the overlay
  * @param {Function} onClose       () => void — backdrop click, Escape, post-select
- * @param {Array}    results       pre-filtered rows: { id, label, group?, hint? }
+ * @param {Array}    results       pre-filtered rows: { id, label, group?, hint?, icon? }
+ * @param {Array}    [suggestions] rows shown while the query is empty (same shape) —
+ *                                 the palette opens on somewhere to go, not a blank box
  * @param {string}   query         controlled query (drives the highlight slice)
  * @param {Function} onQueryChange (string) => void — input change
  * @param {Function} onSelect      (item) => void — row click / Enter; consumer navigates
@@ -69,7 +91,8 @@ export function HighlightMatch({ label, query, ranges }) {
 export default function ShellSearchOverlay({
   open,
   onClose,
-  results = [],
+  results: rawResults = [],
+  suggestions = [],
   /* EXPANDED — the palette's second state (user ruling 2026-08-01). Enter
    * commits the query and opens `children` as the results body; the palette
    * and the old tag overlay are one surface with two states, not two
@@ -92,6 +115,7 @@ export default function ShellSearchOverlay({
   /* Has the user actually chosen a row? See the Enter branch — without this,
    * index 0 counts as a selection and Enter navigates somewhere unasked. */
   const [navigated, setNavigated] = useState(false)
+  const results = groupRows(query ? rawResults : suggestions)
   const active = results.length > 0 ? Math.min(activeIndex, results.length - 1) : -1
 
   /* Focus in on open, restore the opener on close. querySelector instead of
@@ -110,7 +134,7 @@ export default function ShellSearchOverlay({
   /* Keep the active row visible inside the scrolling list. */
   useEffect(() => {
     if (active < 0) return
-    listRef.current?.children[active]?.scrollIntoView({ block: 'nearest' })
+    listRef.current?.querySelectorAll('[role="option"]')[active]?.scrollIntoView({ block: 'nearest' })
   }, [active])
 
   if (!open) return null
@@ -141,7 +165,8 @@ export default function ShellSearchOverlay({
        * highlighted" is true from the first keystroke and testing `active >= 0`
        * made Enter navigate to whatever happened to be first. Committing a
        * query must never be a navigation you didn't choose. */
-      if (navigated) select(results[active])
+      /* An empty query has nothing to commit — Enter goes to the top suggestion. */
+      if (active >= 0 && (navigated || !query)) select(results[active])
       else onExpand?.()
     } else if (e.key === 'Tab') {
       /* Focus trap — the input is the palette's only tab stop. */
@@ -182,8 +207,11 @@ export default function ShellSearchOverlay({
             ))}
           </div>
         )}
+        {/* A REAL FIELD, inset in the panel (2026-09-30, shadcn's palette as
+          * the aim) — the flush `bare` strip read as a hole, not a control. */}
+        <div className="kol-tone-grey p-2">
         <SearchInput
-          bare
+          className="w-full"
           value={query}
           onChange={(e) => onQueryChange?.(e.target.value)}
           placeholder={chips.length > 0 ? 'Narrow these results…' : placeholder}
@@ -193,6 +221,7 @@ export default function ShellSearchOverlay({
           aria-controls={listId}
           aria-activedescendant={active >= 0 ? optionId(results[active]) : undefined}
         />
+        </div>
 
         {/* WHY THIS IS NOT `molecules/Dropdown` (asked 2026-08-01). Dropdown is
           * a SELECT: a trigger, a `value`, `onChange(value)`, and rows that are
@@ -204,7 +233,8 @@ export default function ShellSearchOverlay({
           *
           * THE ROW CONTRACT (was documented nowhere):
           *   label     the row's text, match-highlighted against the query
-          *   group     right-aligned origin — 'Atoms', 'Documentation', 'Tags'
+          *   group     section heading the row files under — 'Atoms', 'Documentation', 'Tags'
+          *   icon      optional leading glyph (kol-icons name)
           *   hint      subtext shown when the LABEL was not what matched
           *   href      a destination; dismisses the palette
           *   action    a closure; runs and KEEPS the palette open (tag rows)
@@ -212,46 +242,60 @@ export default function ShellSearchOverlay({
         {expanded ? (
           <div className="border-t border-fg-08 max-h-[70vh] overflow-y-auto">{children}</div>
         ) : results.length > 0 && (
+          /* FIXED BODY HEIGHT — the panel holds still while the list narrows. */
           <ul
             ref={listRef}
             id={listId}
             role="listbox"
-            className="border-t border-fg-08 max-h-80 overflow-y-auto py-1"
+            className="kol-tone-grey h-80 overflow-y-auto px-2 pb-2"
           >
-            {results.map((item, i) => (
-              <li
-                key={item.id}
-                id={optionId(item)}
-                role="option"
-                aria-selected={i === active}
-                /* preventDefault keeps focus in the input through the click */
-                onMouseDown={(e) => e.preventDefault()}
-                onClick={() => select(item)}
-                onMouseEnter={() => { setActiveIndex(i); setNavigated(true) }}
-                className={`flex items-center gap-2 px-4 py-1.5 cursor-pointer kol-mono-14 transition-colors ${
-                  i === active ? 'bg-fg-08 text-fg' : 'text-fg-80'
-                }`}
-              >
-                <span className="flex flex-col min-w-0">
-                  <span className="truncate">
-                    <HighlightMatch label={item.label} query={query} ranges={item.highlights} />
-                  </span>
-                  {item.hint && (
-                    <span className="kol-mono-12 text-fg-48 truncate">{item.hint}</span>
+            {results.map((item, i) => {
+              const heading = (item.group ?? '') !== (results[i - 1]?.group ?? '') || i === 0
+              return (
+                <li key={item.id} role="presentation">
+                  {heading && item.group && (
+                    <p className="kol-helper-12 text-fg-48 px-4 border-x border-transparent pt-3 pb-2">{item.group}</p>
                   )}
-                </span>
-                {item.group && (
-                  <span className="ml-auto shrink-0 kol-helper-10 text-fg-48">{item.group}</span>
-                )}
-              </li>
-            ))}
+                  <div
+                    id={optionId(item)}
+                    role="option"
+                    aria-selected={i === active}
+                    /* preventDefault keeps focus in the input through the click */
+                    onMouseDown={(e) => e.preventDefault()}
+                    onClick={() => select(item)}
+                    onMouseEnter={() => { setActiveIndex(i); setNavigated(true) }}
+                    /* the md control's box: 1px ring + 6/16 pad + gap-2 → 32px, same as the field */
+                    className={`flex items-center gap-2 px-4 py-1.5 border border-transparent min-h-[var(--kol-ctl-md)] rounded-[var(--kol-radius-sm)] cursor-pointer kol-mono-14 transition-colors ${
+                      i === active ? 'bg-[var(--kol-tone-bg,var(--kol-surface-secondary))] text-fg' : 'text-fg-80'
+                    }`}
+                  >
+                    {item.icon && (
+                      <span aria-hidden="true" className="flex shrink-0 text-oq-48">
+                        <Icon name={item.icon} size={glyphSize('md')} />
+                      </span>
+                    )}
+                    <span className="flex flex-col min-w-0">
+                      <span className="truncate">
+                        <HighlightMatch label={item.label} query={query} ranges={item.highlights} />
+                      </span>
+                      {item.hint && (
+                        <span className="kol-mono-12 text-fg-48 truncate">{item.hint}</span>
+                      )}
+                    </span>
+                  </div>
+                </li>
+              )
+            })}
           </ul>
         )}
-        {!expanded && enterLabel && query && (
-          <p className="flex items-center gap-2 border-t border-fg-08 px-4 py-2 kol-helper-12 text-fg-64">
-            <kbd className="kol-helper-12 rounded-[var(--kol-radius-sm)] bg-fg-08 px-1.5 py-0.5 text-fg">↵</kbd>
-            {enterLabel}
-          </p>
+        {/* THE FOOTER SAYS WHAT ENTER DOES — always, not only once typing. */}
+        {!expanded && ((!query && results.length > 0) || (query && enterLabel)) && (
+          <div className="border-t border-fg-08 py-2">
+            <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent">
+              <Kbd icon="corner-down-left" />
+              {query ? enterLabel : 'Go to page'}
+            </p>
+          </div>
         )}
       </div>
     </div>

package/src/organisms/sectionBleed.js

@@ -7,7 +7,7 @@
  *
  * WHY IT IS A FILLED-SECTION PROBLEM, not a newsletter one. Any member of the
  * family can be a filled surface, and a filled surface inside `.kol-page` has its
- * colour clipped by the page gutter on mobile — strips of page down both sides of
+ * color clipped by the page gutter on mobile — strips of page down both sides of
  * the fill. Reported once per organism until the prop is shared.
  *
  * NOT `.kol-full-bleed`: that escape is CONTAINER-relative, so on an organism

package/src/utilities/FullscreenOverlay.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'react'
 import { pushLayer, popLayer, isTopLayer } from './layerStack.js'
-import CloseButton from './CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 
 /**
  * FullscreenOverlay — the scrim + centred sheet every overlay in the repo

package/src/utilities/LoaderOverlay.jsx

@@ -8,7 +8,7 @@ import FullscreenOverlay from './FullscreenOverlay.jsx'
  * `loader` slot — as the overlay content. Being mounted IS being visible;
  * the parent removes this element to dismiss.
  *
- * The loader is a SLOT, not a built-in: inject a curtain (e.g. `<ColorLoader/>`
+ * The loader is a SLOT, not a built-in: inject a curtain (e.g. `<IntroLoader/>`
  * from `@kolkrabbi/kol-foundry`) via `loader` and wire its completion callback
  * yourself. The slot is mounted in a `fixed inset-0` box that escapes
  * FullscreenOverlay's centered, `--kol-container-max`-width sheet so the loader
@@ -16,7 +16,7 @@ import FullscreenOverlay from './FullscreenOverlay.jsx'
  * With neither, the loader slot renders nothing (the overlay still works).
  *
  * @param {ReactNode} children overlay content, centered (takes precedence)
- * @param {ReactNode} loader   full-screen loading curtain, e.g. foundry's ColorLoader
+ * @param {ReactNode} loader   full-screen loading curtain, e.g. foundry's IntroLoader
  */
 export default function LoaderOverlay({ children, loader }) {
   return (

package/src/utilities/Popover.jsx

@@ -7,6 +7,7 @@ import {
   flip as flipMw,
   shift as shiftMw,
   size as sizeMw,
+  hide as hideMw,
   FloatingPortal,
   FloatingFocusManager,
   useClick,
@@ -101,6 +102,7 @@ export function usePopover({
    * external DOM node (e.g. a parent container ref) instead of wiring
    * `setReference` onto the trigger. Used by TypeBlockToolbar to anchor
    * to its TypeFrame parent. */
+  middleware.push(hideMw({ strategy: 'referenceHidden' })) // last — it reads the final position
   const data = useFloating({
     open,
     onOpenChange,
@@ -110,6 +112,13 @@ export function usePopover({
     elements: referenceElement ? { reference: referenceElement } : undefined,
   })
 
+  /* A PANEL FOLLOWS ITS TRIGGER OUT OF SIGHT (2026-09-30 — docs/menus: an open menu painted over
+   * the sticky header when its trigger scrolled under it, and floated at the page's foot when it
+   * scrolled away). The panel is portalled to <body>, so no scroll container can clip it; `hide`
+   * reports when the trigger is clipped, and the panel hides with it. */
+  const hidden = data.middlewareData.hide?.referenceHidden
+  const floatingStyles = hidden ? { ...data.floatingStyles, visibility: 'hidden' } : data.floatingStyles
+
   const interactions = useInteractions([
     useClick(data.context, { enabled: click }),
     useHover(data.context, { enabled: hover, delay: hoverDelay, move: false }),
@@ -118,7 +127,7 @@ export function usePopover({
     useRole(data.context, { role }),
   ])
 
-  return { ...data, ...interactions, open }
+  return { ...data, floatingStyles, ...interactions, open }
 }
 
 /**

package/src/utilities/tone.js

@@ -4,7 +4,7 @@
  *
  *   primary · secondary · inverted · outline · ghost · grey · sunken
  *
- * `secondary` paints the PAGE SURFACE and `inverted` the text colour as fill
+ * `secondary` paints the PAGE SURFACE and `inverted` the text color as fill
  * (tone-secondary-is-inverse, 2026-09-03; user: "that tone should be called
  * secondary. What is currently secondary should be called inverted") — 0.134.0
  * had lifted `secondary` from Button's variant, which was already an inverse.