@kolkrabbi/kol-component 0.232.0 → 0.234.0

package/package.json

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

package/src/atoms/ActionButton.jsx

@@ -6,7 +6,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * ActionButton — an icon control that CONFIRMS what it did (2026-08-15 user
+ * ActionButton — An icon button that confirms what it did. an icon control that CONFIRMS what it did (2026-08-15 user
  * ruling: *"where is the 'code copied' or whatever message"*).
  *
  * The confirm-flip existed exactly once, welded to the clipboard inside

package/src/atoms/AnimatedTitle.jsx

@@ -6,7 +6,7 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 gsap.registerPlugin(ScrollTrigger)
 
 /**
- * AnimatedTitle — scroll-triggered heading that reveals its words one by
+ * AnimatedTitle — A heading whose words fly in on scroll. scroll-triggered heading that reveals its words one by
  * one as it scrolls into view: each word starts far off-screen right,
  * rotated in 3D, and flies into place with a fast stagger (GSAP +
  * ScrollTrigger; plays entering the viewport, reverses scrolling back

package/src/atoms/AudioPlayer.jsx

@@ -1,5 +1,5 @@
 /**
- * AudioPlayer — the interactive audio atom: one native <audio> with the UA's
+ * AudioPlayer — A native audio player with a label. the interactive audio atom: one native <audio> with the UA's
  * own control strip, and an optional label line above it.
  *
  * WHY IT EXISTS. Audio was the one media kind the design system had nothing for,

package/src/atoms/Avatar.jsx

@@ -8,7 +8,7 @@ const SIZE_MAP = {
 }
 
 /**
- * Avatar — the initials disc, or a photo at the same geometry.
+ * Avatar — Initials or a photo in a disc. the initials disc, or a photo at the same geometry.
  *
  * `src` was added when the ArticleHeader reconciliation (2026-08-15) found the
  * consumer hand-rolling `<img className="w-12 h-12 rounded-full object-cover">`

package/src/atoms/Badge.jsx

@@ -1,5 +1,5 @@
 /**
- * Badge — status / categorization indicator
+ * Badge — A small status label. status / categorization indicator
  *
  * Converted from Badge.tsx (shadcn/CVA) → plain JSX with kol- CSS variables.
  * CSS classes live in components.css under 2-LABELS → Badges.

package/src/atoms/Figure.jsx

@@ -1,5 +1,5 @@
 /**
- * Figure — the shared caption'd media shell for long-form prose: optional
+ * Figure — Captioned media for long-form prose. the shared caption'd media shell for long-form prose: optional
  * label above, an aspect-locked bordered frame around `children`, optional
  * figcaption below. ImageBlock and VideoBlock (and the portable-text image
  * renderer) all compose this one shell.

package/src/atoms/FileIcon.jsx

@@ -1,7 +1,7 @@
 import { Icon } from '@kolkrabbi/kol-icons'
 
 /**
- * FileIcon — the file as a page: folded corner, the kind's glyph, the extension under it.
+ * FileIcon — A file drawn as a page. the file as a page: folded corner, the kind's glyph, the extension under it.
  * Finder's generic document icon (user 2026-09-23: *"a generic preview for that like wav and
  * the type below that finder has"*). What a file shows when it has nothing of its own to draw:
  * audio without cover art, an empty file, a kind no renderer handles.

package/src/atoms/Kbd.jsx

@@ -1,5 +1,5 @@
 /**
- * Kbd — a key cap: one key or chord (↵, ⌘K, Esc) shown as an affordance.
+ * Kbd — A key cap for a shortcut. 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).

package/src/atoms/Pill.jsx

@@ -1,5 +1,5 @@
 /**
- * Pill — the STATIC chip: a label, category, or status word. Not clickable.
+ * Pill — A static label chip. the STATIC chip: a label, category, or status word. Not clickable.
  *
  * The chip family, so the right one gets reached for (documented at source,
  * 2026-07-30):

package/src/atoms/Tag.jsx

@@ -1,9 +1,10 @@
 import { Icon } from '@kolkrabbi/kol-icons'
 
 const ICON_SIZES = { xs: 8, sm: 10, md: 12, lg: 14 }
+const PALETTE = new Set(['blue', 'teal', 'green', 'yellow', 'red', 'orange', 'purple'])
 
 /**
- * Tag — the INTERACTIVE chip: filterable, selectable, removable.
+ * Tag — An interactive chip to filter or select. the INTERACTIVE chip: filterable, selectable, removable.
  *
  * The chip family (documented at source, 2026-07-30):
  *   Pill  — static label. No states, no handlers. Reach for this for decoration.
@@ -53,9 +54,17 @@ export default function Tag({
   icon,
   onRemove,
   onClick,
+  color,
   className = '',
+  style,
   ...props
 }) {
+  /* COLOR (the showcase review W17, 2026-09-30 — user: "do we hate color? there is no tag colors, no
+   * active error warning nothing"). A palette key (blue · teal · green · yellow · red · orange · purple,
+   * what kol-markdown's getTagColor returns). It sets one hue the variant's fill and ink mix from, so
+   * hover and active stay the variant's own; `dark` and unknown keys stay neutral. Status is Badge's
+   * job (success · warning · error · info), not a Tag color. */
+  const hue = PALETTE.has(color) ? `var(--kol-palette-${color})` : null
   const isInteractive = !!(onClick || onRemove)
   const Element = isInteractive ? 'button' : 'span'
   const iconSize = ICON_SIZES[size] || 12
@@ -84,6 +93,7 @@ export default function Tag({
     VARIANTS[variant] ?? VARIANTS.primary,
     `kol-tag--${size}`,
     active ? 'is-active' : '',
+    hue ? 'kol-tag--hue' : '',
     className
   ].filter(Boolean).join(' ')
 
@@ -97,6 +107,7 @@ export default function Tag({
       {...props}
       type={isInteractive ? 'button' : undefined}
       className={classes}
+      style={hue ? { ...style, '--kol-tag-hue': hue } : style}
       onClick={onClick}
     >
       {icon && <Icon name={icon} size={iconSize} />}

package/src/atoms/Textarea.jsx

@@ -2,7 +2,7 @@
 import { Icon } from '@kolkrabbi/kol-icons'
 
 /**
- * Textarea — multi-line text atom built on the .kol-control shell with the
+ * Textarea — Multi-line text input. multi-line text atom built on the .kol-control shell with the
  * `--textarea` modifier (display: block).
  *
  *   variant="filled" (default) — persistent solid bg
@@ -14,7 +14,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * Default rows = 3 (kept short — long content gets scrollbars instead of
  * dominating the panel). Resize is real (2026-07-08): native resize is
  * OFF (Firefox's built-in grip cannot be hidden any other way) and the
- * kol-icon-set-v1 `resize-grip` icon IS the drag handle — corner drag,
+ * kol-icon-set-interface `resize-grip` icon IS the drag handle — corner drag,
  * min 120×40. One grip, every browser.
  *
  * The X-drag is container-clamped (2026-08-12, TextareaResizeClamp): the

package/src/atoms/ToggleSwitch.jsx

@@ -1,7 +1,7 @@
 import React from 'react'
 
 /**
- * ToggleSwitch — bare by default (2026-07-08 chrome law rewrite).
+ * ToggleSwitch — An on/off switch. bare by default (2026-07-08 chrome law rewrite).
  *
  *   variant="bare" (default) — label + track, no box
  *   variant="primary"        — filled shell (surface-secondary), button geometry

package/src/atoms/XYPad.jsx

@@ -1,7 +1,7 @@
 import { useRef } from 'react'
 
 /**
- * XYPad — a two-axis control pad: drag one puck to vary two values at once.
+ * XYPad — Drag one puck to set two values. a two-axis control pad: drag one puck to vary two values at once.
  *
  * Lifted verbatim from kol-fxr's editor (`compose/inspectors/XYPad.jsx`,
  * `editor-panels-the-held-specs` A6, 2026-09-03 — the row the filer marked

package/src/molecules/AlignmentGrid.jsx

@@ -3,7 +3,7 @@ import SegmentedToggle from '../atoms/SegmentedToggle.jsx'
 import { glyphSize } from '../hooks/glyphLadders.js'
 
 /**
- * AlignmentGrid — the align control: TWO three-way strips, X and Y.
+ * AlignmentGrid — Align on X and Y. the align control: TWO three-way strips, X and Y.
  *
  * Rebuilt on `SegmentedToggle` 2026-09-03 (`editor-chrome-review`, the user's
  * own pass over the running editor: *"alignment isnt using segmentedtoggle?"*).

package/src/molecules/AudioSheet.jsx

@@ -18,7 +18,7 @@ function useCover(src) {
 }
 
 /**
- * AudioSheet — audio in the Quick Look window, Finder's layout (user 2026-09-23, the reference
+ * AudioSheet — Audio in the preview window. audio in the Quick Look window, Finder's layout (user 2026-09-23, the reference
  * shot): the artwork square left, `Time: mm:ss` beside it, the QuickTime bar docked in the
  * window's footer. Artwork = the file's embedded ID3 `APIC` cover (`readCover`); no cover →
  * `FileIcon`, the same page the tile shows. The `cover` / `sheet` variants are gone — there is

package/src/molecules/CodeBlock.jsx

@@ -3,7 +3,7 @@ import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism'
 import CopyButton from './CopyButton.jsx'
 
 /**
- * CodeBlock — REPLICATED from the elder reference
+ * CodeBlock — Highlighted code with a copy button. REPLICATED from the elder reference
  * (kol-website/packages/ui/src/molecules/CodeBlock.jsx, 2026-07-28 user
  * mandate): react-syntax-highlighter (Prism) with the oneDark theme flattened
  * onto KOL chrome — transparent bg, 14px/1.6 mono, no text-shadow — a single

package/src/molecules/ColorRamp.jsx

@@ -3,7 +3,7 @@ import ColorSwatch from '../atoms/ColorSwatch.jsx'
 import { resolveCssVar, isLight } from '../hooks/cssVar.js'
 
 /**
- * ColorRamp — one specimen row of color chips for a token-doc page. A label
+ * ColorRamp — One row of color chips. one specimen row of color chips for a token-doc page. A label
  * (+ optional note) above a run of ColorSwatch chips, each captioned with its
  * name and resolved value. Merges the former Ramp (static hex) + ColorRamp
  * (live CSS var) widgets into one component with two mutually-exclusive inputs:

package/src/molecules/ContentItem.jsx

@@ -2,7 +2,7 @@ import ContentCard from './ContentCard.jsx'
 import ContentRow from './ContentRow.jsx'
 
 /**
- * ContentItem — the form switch the estate hand-wrote nine times
+ * ContentItem — A card or a row by layout. the form switch the estate hand-wrote nine times
  * (`layout === 'list' ? row : card`). One prop picks the form; everything
  * else passes through to ContentCard / ContentRow unchanged, so a listing
  * under a LIST/GRID toggle is one component with one prop flipped.

package/src/molecules/ContentRow.jsx

@@ -2,7 +2,7 @@ import ContentMedia from './ContentMedia.jsx'
 import ContentText from './ContentText.jsx'
 
 /**
- * ContentRow — the row form of the content-card system: leading thumb (where
+ * ContentRow — The row form of a content card. the row form of the content-card system: leading thumb (where
  * the variant has one) beside the ruled text. Box values — thumb size, gap,
  * padding, frame — default per variant to the RULED structures from the live
  * review (06-content-card-system.md §2 boxes): default is a bare table-like

package/src/molecules/CopyButton.jsx

@@ -1,7 +1,7 @@
 import ActionButton from '../atoms/ActionButton.jsx'
 
 /**
- * CopyButton — THE copy-to-clipboard control (2026-08-09 user ruling): the
+ * CopyButton — Copy text to the clipboard. THE copy-to-clipboard control (2026-08-09 user ruling): the
  * 32×32 icon button — `copy` glyph flipping to `check` for 2s on copied,
  * no text label. This is the button CodeBlock carried privately since the
  * 2026-07-28 elder replication, promoted to the one shared atom; the old

package/src/molecules/DocFrontmatter.jsx

@@ -50,7 +50,7 @@ const orderFields = (metadata) => {
 }
 
 /**
- * DocFrontmatter — the frontmatter block above a markdown document's prose: the
+ * DocFrontmatter — A document's frontmatter block. the frontmatter block above a markdown document's prose: the
  * `FRONTMATTER` eyebrow, icon + label keys, mono values, tags as `Tag` chips,
  * arrays stacked, a hairline below. A member of `DocPage`.
  *

package/src/molecules/DocPage.jsx

@@ -3,7 +3,7 @@ import DocFrontmatter from './DocFrontmatter.jsx'
 /* taxonomy-ok: molecule — nests DocFrontmatter (relative). */
 
 /**
- * DocPage — ONE plate for every document (DocPageAndKindShowcase, kol-r2b2
+ * DocPage — A page for any text document. ONE plate for every document (DocPageAndKindShowcase, kol-r2b2
  * 2026-08-27, user ruling): markdown · text · code · JSON · YAML render on the
  * same page. Where it sits decides its presentation, in kol-theme (≥0.75.0):
  *

package/src/molecules/DocsToc.jsx

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef } from 'react'
 import useScrollSpy from '../hooks/useScrollSpy.js'
 
 /**
- * DocsToc — on-page table of contents for long docs pages: a flat list of
+ * DocsToc — A page's table of contents. on-page table of contents for long docs pages: a flat list of
  * anchor links that highlights the heading currently in view. The scroll
  * spy is useScrollSpy (IntersectionObserver + edge lock); this component
  * only renders the nav and maps the active id onto the links.

package/src/molecules/Dropdown.jsx

@@ -6,7 +6,7 @@ import { PopoverPanel, usePopover } from '../utilities/Popover.jsx'
 import { glyphSize, indicatorSize } from '../hooks/glyphLadders.js'
 
 /**
- * Dropdown — trigger IS button chrome (2026-07-08 chrome law).
+ * Dropdown — Pick one value from a list. trigger IS button chrome (2026-07-08 chrome law).
  *
  * The trigger emits `kol-btn kol-btn-{variant} kol-btn-{size}` so it renders
  * pixel-identical to a Button of the same variant/size — fills, hover,

package/src/molecules/DropdownTagFilter.jsx

@@ -7,6 +7,7 @@ const SIZE_MAP = {
 }
 
 /**
+ * @deprecated 2026-10-01 — use SettingsMulti (a many-of-N `Dropdown`). Drops when nobody imports it (04-retirements.md).
  * Dropdown Tag Filter
  * Multi-select dropdown where all items start selected
  * Click to deselect, with "Deselect All" option

package/src/molecules/EmptyState.jsx

@@ -1,5 +1,5 @@
 /**
- * EmptyState — a stacked "nothing here yet / nothing selected" text block
+ * EmptyState — What a panel shows when it has nothing. a stacked "nothing here yet / nothing selected" text block
  * for inspectors, empty rails and unshipped panels. Ported from the brand
  * editor's inspector Placeholder (renamed: AssetPlaceholder already owns
  * the placeholder name). All lines render as authored — no auto casing

package/src/molecules/FieldRow.jsx

@@ -6,7 +6,7 @@ import Dropdown from './Dropdown'
 import OptionRow from './OptionRow.jsx'
 
 /**
- * FieldRow — one labeled field row in a record surface (lobby: RecordManager).
+ * FieldRow — One labelled field in a record. one labeled field row in a record surface (lobby: RecordManager).
  * Label column left, control right; `type` picks the control:
  *
  *   text   → Input, with an optional hint line under it (the slug's derived URL)
@@ -100,7 +100,6 @@ export function StatusChip({ value, options = [], onChange, variant = 'neutral',
                   role="option"
                   aria-selected={val === value}
                   size="sm"
-                  selected={val === value}
                   className="w-full"
                   onClick={() => {
                     onChange?.(val)

package/src/molecules/ImageBlock.jsx

@@ -2,7 +2,7 @@ import Figure from '../atoms/Figure.jsx'
 import Image from '../atoms/Image.jsx'
 
 /**
- * ImageBlock — a captioned prose image: the DS Figure shell (optional label,
+ * ImageBlock — A captioned image for prose. a captioned prose image: the DS Figure shell (optional label,
  * aspect-locked bordered frame, optional figcaption) wrapping a cover-fit DS
  * Image. The long-form counterpart to VideoBlock — both compose the same
  * Figure atom, so the frame chrome lives in one place.

package/src/molecules/KindPreview.jsx

@@ -13,7 +13,7 @@ import DocPage from './DocPage.jsx'
 /* taxonomy-ok: molecule — nests the DS media atoms + CodeBlock (relative). */
 
 /**
- * KindPreview — a preview for any kind of file: kol-r2b2's `KindPreview.jsx`,
+ * KindPreview — A preview for any kind of file. a preview for any kind of file: kol-r2b2's `KindPreview.jsx`,
  * promoted 2026-08-27 (SettingsPanelChromeAndColumnPreview). Before it, anything
  * that was not an image or a video showed a grey box with the word "text".
  * HLS → `HlsVideo` (inert — the DS's background-video atom, preview only),

package/src/molecules/MediaTile.jsx

@@ -2,7 +2,7 @@
 import RowMenuButton from './RowMenuButton.jsx'
 
 /**
- * MediaTile — one file in the grid view, Finder's icon view (user 2026-09-23: *"skip the container
+ * MediaTile — One file in the grid view. one file in the grid view, Finder's icon view (user 2026-09-23: *"skip the container
  * card, just show the title and preview, give it hilight focus state … we are fighting the card
  * component"*). The grid borrowed `ContentCard` from the content-filters set — a card with a date,
  * a size and two buttons — so the one view of files that should read like the other two carried
@@ -28,7 +28,7 @@ export default function MediaTile({ preview, name, selected = false, markKey, on
       onContextMenu={onContextMenu}
       onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); onDoubleClick?.(e) } }}>
       <div className="kol-media-tile-thumb">{preview}</div>
-      <span className="kol-media-tile-name">{name}</span>
+      <span className="kol-media-tile-name kol-item-name">{name}</span>
       <RowMenuButton variant="grey" onOpen={onContextMenu} className="absolute top-1 right-1" />
     </div>
   )

package/src/molecules/MenuPopover.jsx

@@ -2,7 +2,7 @@ import { MenuItem as MenuTrigger } from './MenuItem.jsx'
 
 /**
  * @deprecated 2026-07-02 — alias of MenuItem (menu-family unify). Drops when nobody imports it (04-retirements.md).
- * MenuPopover — DEPRECATED alias of MenuItem (2026-07-02 menu-family
+ * MenuPopover — Old name for MenuItem. DEPRECATED alias of MenuItem (2026-07-02 menu-family
  * unification).
  *
  * The two triggers had an identical API (label, children incl. ({ close })

package/src/molecules/OptionRow.jsx

@@ -1,5 +1,5 @@
 /**
- * OptionRow — one row in a list you move through: the palette's results, a browser's rows, a
+ * OptionRow — One row in a list you move through. one row in a list you move through: the palette's results, a browser's rows, a
  * dropdown's options. Lifted out of ShellSearchOverlay (2026-09-30), where it was hand-rolled next to
  * DropdownTagFilter's, FieldRow's and ColumnBrowser's own — four rows for one job.
  *
@@ -7,26 +7,26 @@
  * transparent ring, so a row lines up with the field or button beside it at the same size.
  *
  * States, strongest first:
+ *   selected — the picked item: the tone's PRESSED fill (white in dark, as the grid's picked name)
  *   active   — the keyboard cursor / hover: the tone fill, full ink
- *   selected — the picked item: oq-08
- *   trail    — on the path to the picked item (a browser's parent folders): oq-04
+ *   trail    — on the path to the picked item (a browser's parent folders): oq-08
  *
  * Renders no role — the caller owns the list semantics (`role="option"`, `aria-selected`, ids)
  * and passes them through `...rest`.
  *
  * @param {'xs'|'sm'|'md'|'lg'} size   the control ramp step
+ * @param {string}    type     a type class instead of the ramp's (file lists: `kol-item-name`)
  * @param {string}    icon     kol-icons name, drawn in oq (icons-use-oq law)
  * @param {ReactNode} leading  anything else in the icon column (a check, a thumb) — wins over icon
  * @param {ReactNode} label
- * @param {ReactNode} hint     a second line under the label
+ * @param {ReactNode} hint     secondary text — beside the label, right-aligned on its baseline
  * @param {ReactNode} trailing right-aligned (a shortcut, a count, a menu button)
  * @param {string}    as       element to render (`div` · `button` · `li`)
- * @param {boolean}   fill     false = the caller paints the state fills (ColumnBrowser's trail vs
- *                             deepest-selection is decided in CSS by column); the ink still follows
+ * @param {boolean}   hover    false = hover paints nothing (the media browser's ruling, 2026-09-02)
  * @param {boolean}   muted    a row that is there but not the point (fg-48)
  *
- * `ROW_HEIGHT` / `ROW_TYPE` are exported for a row that cannot take this anatomy (the media rows
- * view's table row: twisty, drag hit, columns) — it still sits on the same ramp.
+ * `ROW_HEIGHT` / `ROW_TYPE` / `ROW_FILL` are exported for a row that cannot take this anatomy (the
+ * media rows view's table row: twisty, drag hit, columns) — it still sits on the same ramp and fills.
  */
 import { Icon } from '@kolkrabbi/kol-icons'
 import { glyphSize } from '../hooks/glyphLadders.js'
@@ -41,13 +41,24 @@ export const ROW_HEIGHT = {
 }
 export const ROW_TYPE = { xs: 'kol-mono-12', sm: 'kol-mono-12', md: 'kol-mono-14', lg: 'kol-mono-14' }
 
+const TONE = 'bg-[var(--kol-tone-bg,var(--kol-surface-secondary))]'
+/* SELECTED IS THE TONE'S PRESSED STATE (user 2026-09-30: *"use white as focused item like grid
+ * already does"*) — `--kol-tone-pressed-*`, the fill a pressed button takes; outside a tone, the
+ * same surface-on-primary / surface-primary pair the grid's picked name paints. */
+export const ROW_FILL = {
+  selected: 'bg-[var(--kol-tone-pressed-bg,var(--kol-surface-on-primary))] text-[var(--kol-tone-pressed-fg,var(--kol-surface-primary))]',
+  active: `${TONE} text-fg`,
+  trail: 'bg-oq-08 text-fg',
+}
+
 export default function OptionRow({
   as: Tag = 'div',
   size = 'md',
+  type,
   active = false,
   selected = false,
   trail = false,
-  fill: paints = true,
+  hover = true,
   muted = false,
   icon,
   leading,
@@ -58,23 +69,21 @@ export default function OptionRow({
   children,
   ...rest
 }) {
-  const lit = active || selected || trail
-  /* hover takes the active fill — the palette already moves `active` on hover; a list without a
-   * keyboard cursor gets the same look for free. `fill={false}` rows paint nothing (the columns) */
-  const bg = !paints ? '' : active
-    ? 'bg-[var(--kol-tone-bg,var(--kol-surface-secondary))]'
-    : `${selected ? 'bg-oq-08' : trail ? 'bg-oq-04' : ''} hover:bg-[var(--kol-tone-bg,var(--kol-surface-secondary))]`
-  const fill = `${bg} ${lit ? 'text-fg' : muted ? 'text-fg-48' : 'text-fg-80'}`
+  const state = selected ? ROW_FILL.selected : active ? ROW_FILL.active : trail ? ROW_FILL.trail
+    : `${muted ? 'text-fg-48' : 'text-fg-80'}${hover ? ` hover:${TONE}` : ''}`
   const lead = leading ?? (icon && <Icon name={icon} size={glyphSize(size)} />)
   return (
     <Tag
-      className={`flex items-center gap-2 px-4 border border-transparent ${ROW_HEIGHT[size] ?? ROW_HEIGHT.md} rounded-[var(--kol-radius-sm)] cursor-pointer text-left ${ROW_TYPE[size] ?? ROW_TYPE.md} transition-colors ${fill} ${className}`.trim()}
+      className={`flex items-center gap-2 px-4 border border-transparent ${ROW_HEIGHT[size] ?? ROW_HEIGHT.md} rounded-[var(--kol-radius-sm)] cursor-pointer text-left ${type ?? ROW_TYPE[size] ?? ROW_TYPE.md} transition-colors ${state} ${className}`.trim()}
       {...rest}
     >
-      {lead && <span aria-hidden="true" className="flex shrink-0 text-oq-48">{lead}</span>}
-      <span className="flex flex-1 flex-col min-w-0">
+      {/* the glyph takes the row's ink when selected — a grey mark on a white fill reads as a hole */}
+      {lead && <span aria-hidden="true" className={`flex shrink-0${selected ? '' : ' text-oq-48'}`}>{lead}</span>}
+      {/* ONE LINE (user 2026-09-30): the hint sits beside the label on its baseline, right-aligned,
+       * so the names read as one column and a long name never pushes the path around */}
+      <span className="flex flex-1 items-baseline gap-3 min-w-0">
         <span className="truncate">{label ?? children}</span>
-        {hint && <span className="kol-mono-12 text-fg-48 truncate">{hint}</span>}
+        {hint && <span className={`kol-mono-12 ml-auto truncate${selected ? ' opacity-60' : ' text-fg-48'}`}>{hint}</span>}
       </span>
       {trailing && <span className="flex shrink-0 items-center">{trailing}</span>}
     </Tag>

package/src/molecules/PageHeader.jsx

@@ -1,7 +1,7 @@
 import SectionText from './SectionText.jsx'
 import { TITLE_ROLES, useMasthead } from '../utilities/masthead.js'
 /**
- * PageHeader — the page's masthead: an optional eyebrow, the title, and a
+ * PageHeader — The page masthead. the page's masthead: an optional eyebrow, the title, and a
  * sub-line.
  *
  * LIVES IN kol-component SINCE 2026-09-03 (page-header-one-masthead,

package/src/molecules/PlaybackBar.jsx

@@ -11,7 +11,7 @@ export const clock = (s) => `${String(Math.floor((s || 0) / 60)).padStart(2, '0'
 const RATES = [1, 1.5, 2]
 
 /**
- * PlaybackBar — the QuickTime bar, ruled against the reference (PlaybackBarAndAudioSheet,
+ * PlaybackBar — Play and scrub media. the QuickTime bar, ruled against the reference (PlaybackBarAndAudioSheet,
  * kol-r2b2 2026-08-27; supersedes 0.107.0's strip): a frosted strip over media —
  * `bg-fg-ab-48 backdrop-blur-xl`, **radius 12** (`rounded-xl`, the user's
  * ruling on this surface — the 4px container law stands elsewhere), `h-16 px-8

package/src/molecules/ProfileCard.jsx

@@ -9,7 +9,7 @@ import { surfaceClass } from '../utilities/sectionSurface.js'
  * check can't see). */
 
 /**
- * ProfileCard — the digital namecard (ProfileCard, kol-website 2026-09-01;
+ * ProfileCard — A digital name card. the digital namecard (ProfileCard, kol-website 2026-09-01;
  * carried class-for-class from `apps/web/src/components/ui/ProfileCard.jsx`):
  * a square photo with a disclosure control inset on it, and a SHELF that opens
  * under it (vertical) or beside it (horizontal) — logo, name, mailto, a rack of

package/src/molecules/QuantityInput.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react'
 
 /**
- * QuantityInput — a compact integer quantity picker with two control layouts.
+ * QuantityInput — Pick a whole-number quantity. a compact integer quantity picker with two control layouts.
  *
  *   controls="chevron" (default) — value with a stacked up/down chevron pair
  *                                  on the right, inside a full-width field.

package/src/molecules/QuickLookFrame.jsx

@@ -5,7 +5,7 @@ import CloseButton from '../atoms/CloseButton.jsx'
 /* taxonomy-ok: molecule — nests Button (atom) + CloseButton (utility). */
 
 /**
- * QuickLookFrame — the Finder Quick Look window (user 2026-09-23: *"put them in a container LIKE
+ * QuickLookFrame — The preview window. the Finder Quick Look window (user 2026-09-23: *"put them in a container LIKE
  * FINDER … it just makes everything in the design easier to manage if its wrapped together"*).
  * Every kind sat loose on the scrim with its own chrome — a caption line under a picture, a bar
  * floating over a video, a see-through page — so no two kinds looked like one feature. One

package/src/molecules/RowMenuButton.jsx

@@ -3,7 +3,7 @@ import Button from '../atoms/Button.jsx'
 import useCoarsePointer from '../hooks/useCoarsePointer.js'
 
 /**
- * RowMenuButton — the `···` that stands in for right-click on a touch device (media D-touch,
+ * RowMenuButton — A row's menu on touch devices. the `···` that stands in for right-click on a touch device (media D-touch,
  * 2026-09-23). A finger has no right button, and a held press (`useLongPress`) is invisible until
  * you know it, so on `pointer: coarse` a row or tile that has a context menu wears this. It calls
  * the SAME handler right-click calls, with the tap as the event, so the payload, the selection

package/src/molecules/SectionText.jsx

@@ -1,5 +1,5 @@
 /**
- * SectionText — the ruled text block of the SECTION family (SectionSet,
+ * SectionText — The label, headline and body block. the ruled text block of the SECTION family (SectionSet,
  * kol-website 2026-08-26): label · headline · body · actions, every slot
  * opt-in — an omitted slot renders nothing. The section-tier twin of
  * ContentText: the card family solved "every organism types its own kicker /

package/src/molecules/ShapeDropdown.jsx

@@ -5,7 +5,7 @@ import { PopoverPanel, usePopover, Tooltip } from '../utilities/Popover.jsx'
 import { MenuDropdownItem } from './MenuItem.jsx'
 
 /**
- * ShapeDropdown — split icon-button + variant-menu molecule (the tool-palette
+ * ShapeDropdown — A tool button with a shape menu. split icon-button + variant-menu molecule (the tool-palette
  * idiom: Select · Text · [Shape ▾] · Pattern). The main button reflects the
  * current variant and fires `onAction` with its id; the chevron half opens a
  * menu of all variants — picking one fires `onChange` and closes.

package/src/molecules/ShellDrawer.jsx

@@ -12,7 +12,7 @@ const FOCUSABLE =
   'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
 
 /**
- * ShellDrawer — THE edge drawer: a portalled panel that slides in from the
+ * ShellDrawer — A panel that slides in from an edge. THE edge drawer: a portalled panel that slides in from the
  * left, right or BOTTOM viewport edge over a dimming backdrop. Distinct from Modal
  * (centered prompt/confirm) and FullscreenOverlay (fills the whole viewport,
  * not an edge sheet). Escape, backdrop click and the built-in close button

package/src/molecules/SortControls.jsx

@@ -1,7 +1,7 @@
 import SortHeader from '../atoms/SortHeader.jsx'
 
 /**
- * SortControls — the sortable-header group (ContentFiltersCollection, kol-r2b2
+ * SortControls — A row of sortable headers. the sortable-header group (ContentFiltersCollection, kol-r2b2
  * 2026-08-27): `flex items-center gap-4` of SortHeaders. Click an inactive field
  * → it becomes the sort, ASCENDING; click the active field → the direction
  * flips. `onSort(field)` fires once per click — the consumer writes ONE state

package/src/molecules/SpecList.jsx

@@ -1,7 +1,7 @@
 import Divider from '../atoms/Divider.jsx'
 
 /**
- * SpecList — compact definition list of [label | value] rows: label left and
+ * SpecList — Label and value rows. compact definition list of [label | value] rows: label left and
  * muted, value right-aligned one tone brighter, Divider-separated between
  * rows (never after the last). Data-agnostic "key facts" strip — the caller
  * formats values before passing (e.g. "Limited (30)", "A3, A2, A1").