@kolkrabbi/kol-component 0.233.0 → 0.235.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.233.0",
-  "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
+  "version": "0.235.0",
+  "description": "The core component library",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -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/hooks/useDragResize.js

@@ -135,9 +135,20 @@ const readBack = (n) => {
  *
  *           STATE is untouched: collapsed/expanded still persists via
  *           `stateKey`, unconditionally, as it always did. The ticket says the
- *           two are separate questions and only asks about the width. */
+ *           two are separate questions and only asks about the width.
+ *   variant — how the handle DRAWS and what a click does (2026-10-01, user: *"we should make another
+ *           drag to resize variant: on hover this pointer, and either hover or click to highlight
+ *           the border, with double click expanding (like if sidebar with icons)"*):
+ *             'pill' (default) — the short pill that wakes as the pointer nears; a CLICK toggles.
+ *             'line'           — the whole edge lights up on hover and while dragging; a click does
+ *                                nothing and a DOUBLE-CLICK toggles expand ↔ collapse (the two
+ *                                cannot share one gesture — see "double-click reset is gone" above,
+ *                                which is why this is a variant and not an addition). */
 export default function useDragResize(ref, options = {}) {
-  const { token = 'kol-sidenav', side = 'left', defaultCollapsed = false, persistWidth = false } = options
+  const { token = 'kol-sidenav', side = 'left', defaultCollapsed = false, persistWidth = false, variant = 'pill' } = options
+  const line = variant === 'line'
+  const lineRef = useRef(line)
+  lineRef.current = line
   /* -1 on a right-hand rail: the same rightward pointer travel that widens a
    * left rail must NARROW a right one, because its handle faces the canvas. */
   const dir = side === 'right' ? -1 : 1
@@ -221,7 +232,7 @@ export default function useDragResize(ref, options = {}) {
       root().removeAttribute(names.draggingAttr)
       document.body.style.cursor = ''
       document.body.style.userSelect = ''
-      if (!moved) { toggleCollapsed(); return } // a click, not a drag
+      if (!moved) { if (!lineRef.current) toggleCollapsed(); return } // a click, not a drag — `line` toggles on double-click
       /* Snap-to-default: release near the stylesheet default clears the
        * override entirely. */
       const { collapsed: c, widthPx: w } = readBack(names)
@@ -304,7 +315,8 @@ export default function useDragResize(ref, options = {}) {
       /* the pill is drawn by `.kol-rail-grab` (kol-animation.css) — the hook
        * only supplies `is-near` and `--kol-rail-grab-y`. A consumer's own
        * className, spread after this, still wins. */
-      className: 'kol-rail-grab',
+      className: line ? 'kol-rail-grab kol-rail-grab--line' : 'kol-rail-grab',
+      ...(line ? { onDoubleClick: toggleCollapsed } : {}),
       role: 'separator',
       'aria-orientation': 'vertical',
       'aria-label': 'Resize navigation',

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)

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

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.
  *

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").

package/src/molecules/SplitToolButton.jsx

@@ -4,7 +4,7 @@ import { PopoverPanel, usePopover, Tooltip } from '../utilities/Popover.jsx'
 import { glyphSize } from '../hooks/glyphLadders.js'
 
 /**
- * SplitToolButton — single-trigger split tool button + variant menu (the
+ * SplitToolButton — A tool button with a variant menu. single-trigger split tool button + variant menu (the
  * tool-palette idiom: Select · Text · [Shape ◢] · Pattern). A pinned-square
  * quiet/pressed trigger shows the current variant while the group is `active`
  * (else the `lastPicked` variant) plus a corner fold indicator; ONE click both
@@ -65,7 +65,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {string} props.className - Additional classes on the trigger
  */
 
-/* Corner fold marker — `fold-indicator`, promoted into kol-icon-set-v1
+/* Corner fold marker — `fold-indicator`, promoted into kol-icon-set-interface
  * 2026-09-03 from kol-fxr's own drawing (editor-set-is-behind-its-source); the
  * comment that stood here said it did not exist yet and should be promoted, so
  * this is that. Lives inside the button so it dims with kol-btn-quiet and

package/src/molecules/Stepper.jsx

@@ -1,5 +1,5 @@
 /**
- * Stepper — number input + chevron buttons, built on the .kol-control shell.
+ * Stepper — A number input with step buttons. number input + chevron buttons, built on the .kol-control shell.
  *
  *   size="xs" / "sm" (default) / "md" / "lg" — matched padding + type class.
  *   Chevron scale follows the size: 6 / 8 / 10 / 12 px each, stacked. xs is the

package/src/molecules/SwatchControls.jsx

@@ -92,7 +92,7 @@ export function SwatchStack({
 }
 
 /**
- * EyedropPick — eyedropper icon button + a sample chip of the sampled color.
+ * EyedropPick — Sample a color from the screen. 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
@@ -173,7 +173,7 @@ function NoneMarker({ onClear }) {
 }
 
 /**
- * SwatchControls — the composed colour-panel top row: SwatchStack (fill /
+ * SwatchControls — Fill and stroke swatches with an eyedropper. The composed colour-panel top row: SwatchStack (fill /
  * stroke paint chips + swap + none) alongside EyedropPick (eyedropper +
  * sample chip). Fully controlled and store-free; the app owns the swap, clear,
  * and pick handlers.

package/src/molecules/TabsRow.jsx

@@ -5,7 +5,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 /* taxonomy-ok: nests kol-icons's Icon */
 
 /**
- * TabsRow — labeled underline tab strip: text tabs where the active tab gets
+ * TabsRow — Text tabs with an underline. labeled underline tab strip: text tabs where the active tab gets
  * a 2px bottom underline and emphasis color; inactive tabs are muted and
  * brighten on hover. Optional leading close button and trailing minimise
  * chevron render only when their handlers are passed — no outer chrome, the

package/src/molecules/TiltBento.jsx

@@ -64,7 +64,7 @@ function Media({ src, poster, className }) {
 }
 
 /**
- * TiltBento — media hover-card for grid/bento walls, the Tilt family's composed
+ * TiltBento — A tilting media card for bento walls. media hover-card for grid/bento walls, the Tilt family's composed
  * tile (was `BentoCard` until 2026-08-27, user ruling: the three tilting things
  * in the estate are ONE prefix family — `TiltCard` the bare frame, `TiltBento`
  * this tile, `useTilt` the one hook; `BentoCard` is the alias on the retirement

package/src/molecules/VideoBlock.jsx

@@ -15,7 +15,7 @@ export function getEmbedUrl(url) {
 }
 
 /**
- * VideoBlock — a captioned prose video: the DS Figure shell (optional label,
+ * VideoBlock — A captioned video for prose. a captioned prose video: the DS Figure shell (optional label,
  * aspect-locked bordered frame, optional figcaption) wrapping either an
  * <iframe> embed (YouTube/Vimeo, auto-parsed from `url`) or a native <video>
  * file player. Embed wins when `url` parses; otherwise the `file` player runs.

package/src/molecules/VideoSheet.jsx

@@ -5,7 +5,7 @@ import QuickLookFrame from './QuickLookFrame.jsx'
 /* taxonomy-ok: molecule — nests PlaybackBar + QuickLookFrame (relative). */
 
 /**
- * VideoSheet — video in the Quick Look window: the frame at the video's own aspect ratio, the
+ * VideoSheet — A video in the preview window. video in the Quick Look window: the frame at the video's own aspect ratio, the
  * QuickTime bar docked in the window's footer (2026-09-23 — it floated over the picture, which
  * made video the one kind whose controls sat on the media). No native controls; click on the
  * video toggles play; no autoplay (user 2026-09-23 — Quick Look opens paused), `playsInline`, `preload="metadata"`.