@kolkrabbi/kol-component 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
   "dependencies": {
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
-    "@kolkrabbi/kol-loader": "0.1.1"
+    "@kolkrabbi/kol-loader": "0.3.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/{primitives → atoms}/AssetPlaceholder.jsx

@@ -21,8 +21,10 @@ export default function AssetPlaceholder({
       role="img"
       aria-label={`${label || 'asset'} — ${note}`}
     >
-      <span className="kol-asset-placeholder-note text-[12px] uppercase [letter-spacing:0.12em] text-fg-48">{note}</span>
-      {label && <span className="kol-asset-placeholder-label text-[12px] text-fg-40 [letter-spacing:0.04em]">{label}</span>}
+      {/* note is single-line → helper scale; label can wrap (category · name
+        * in a narrow tile) → line-height-bearing mono scale */}
+      <span className="kol-asset-placeholder-note kol-helper-12 uppercase [letter-spacing:0.12em] text-fg-48">{note}</span>
+      {label && <span className="kol-asset-placeholder-label kol-mono-12 text-fg-40 [letter-spacing:0.04em]">{label}</span>}
     </div>
   )
 }

package/src/atoms/Avatar.jsx

@@ -1,8 +1,8 @@
 const SIZE_MAP = {
-  sm: 'w-8 h-8 text-xs',
-  md: 'w-10 h-10 text-sm',
-  lg: 'w-14 h-14 text-base',
-  xl: 'w-24 h-24 text-3xl',
+  sm: 'w-8 h-8 kol-helper-12',
+  md: 'w-10 h-10 kol-helper-14',
+  lg: 'w-14 h-14 kol-helper-16',
+  xl: 'w-24 h-24 kol-helper-20',
 }
 
 export default function Avatar({ initial, size = 'sm', className = '' }) {

package/src/atoms/Button.jsx

@@ -117,13 +117,16 @@ const Button = ({
       return renderIcon(iconOnly, iconOnlyHover)
     }
 
-    // Button with icon(s) and text
+    // Button with icon(s) and text. Icons render directly as flex items —
+    // wrapper spans (with the old -2px optical margins) sat the glyphs on
+    // the span's text baseline instead of letting align-items center them
+    // against the label.
     if (iconLeft || iconRight || iconLeftHover || iconRightHover) {
       return (
         <span className="flex items-center" style={{ gap: iconGap ?? 8 }}>
-          {(iconLeft || iconLeftHover) && <span style={{ marginLeft: -2 }}>{renderIcon(iconLeft, iconLeftHover)}</span>}
+          {(iconLeft || iconLeftHover) && renderIcon(iconLeft, iconLeftHover)}
           {children}
-          {(iconRight || iconRightHover) && <span style={{ marginRight: -2 }}>{renderIcon(iconRight, iconRightHover)}</span>}
+          {(iconRight || iconRightHover) && renderIcon(iconRight, iconRightHover)}
         </span>
       )
     }

package/src/atoms/CopyButton.jsx

@@ -0,0 +1,50 @@
+import { useState } from 'react'
+
+/**
+ * CopyButton — copy-to-clipboard chip. Clipboard icon + Copy/Copied label
+ * swap with a 1.8s reset; silent when the clipboard is blocked. Chrome
+ * comes from .kol-copy-btn (kol-theme); parents add their own positioning
+ * class (e.g. CodeBlock's .kol-codeblock-copy).
+ *
+ * Props:
+ *   text      — string (or () => string) written to the clipboard
+ *   label     — show the Copy/Copied text next to the icon (default true;
+ *               false = icon-only for tight spots)
+ *   className — extra classes (positioning etc.)
+ */
+export default function CopyButton({ text, label = true, className = '', ...props }) {
+  const [copied, setCopied] = useState(false)
+
+  const onCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(typeof text === 'function' ? text() : String(text ?? ''))
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1800)
+    } catch {
+      /* clipboard blocked — silent */
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      className={`kol-copy-btn ${className}`.trim()}
+      onClick={onCopy}
+      aria-label={copied ? 'Copied' : 'Copy to clipboard'}
+      title={copied ? 'Copied' : 'Copy'}
+      {...props}
+    >
+      {copied ? (
+        <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
+          <path d="M5 10 L9 14 L15 6" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      ) : (
+        <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
+          <rect x="6" y="3" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
+          <rect x="4" y="6" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
+        </svg>
+      )}
+      {label && <span>{copied ? 'Copied' : 'Copy'}</span>}
+    </button>
+  )
+}

package/src/{molecules → atoms}/DropdownTagFilter.jsx

@@ -16,9 +16,10 @@ const DropdownTagFilter = ({
   selectedValues = new Set(),
   onChange,
   className = '',
+  defaultOpen = false,
   size
 }) => {
-  const [isOpen, setIsOpen] = useState(false)
+  const [isOpen, setIsOpen] = useState(defaultOpen)
   const dropdownRef = useRef(null)
   const [resolvedSize, setResolvedSize] = useState('md')
 

package/src/atoms/Input.jsx

@@ -102,10 +102,15 @@ export default function Input({
       {prefix !== undefined && (
         <span aria-hidden="true" className="text-meta pr-1 shrink-0">{prefix}</span>
       )}
+      {/* Controlled only when a `value` prop is passed — otherwise stay
+        * uncontrolled so prop-less usages (search stubs, quick demos) type
+        * normally instead of freezing on a value-without-onChange input.
+        * Controlled + no onChange = deliberate display-only → readOnly. */}
       <input
         type={type}
-        value={value ?? ''}
-        onChange={onChange}
+        {...(value !== undefined
+          ? { value: value ?? '', onChange, readOnly: !onChange || undefined }
+          : { onChange })}
         placeholder={placeholder}
         disabled={disabled}
         spellCheck={false}

package/src/{molecules → atoms}/SegmentedToggle.jsx

@@ -1,7 +1,9 @@
 /**
- * SegmentedToggle — N-way segmented control. Joined buttons sharing one
- * outer stroke; thin dividers between cells; no gap. Active cell uses
- * bg-fg-04 + text-emphasis, inactive is text-meta with hover lifting.
+ * SegmentedToggle — N-way segmented control. Joined cells sharing one
+ * outer stroke; thin dividers between cells; no gap. Active cell fills
+ * with surface-secondary + text-emphasis, inactive is text-meta with
+ * hover lifting. Chrome comes from .kol-seg* in kol-theme (NOT Tailwind
+ * utilities — those never generate from package sources).
  *
  *   <SegmentedToggle
  *     value={current}
@@ -17,6 +19,9 @@
  * Labels accept any node — pass strings or inline SVG previews. Optional
  * `ariaLabel` per option for non-text labels.
  *
+ * A11y: radiogroup/radio semantics with a roving tabindex — Tab enters
+ * the group on the active cell, ←/→ (or ↑/↓) move selection + focus.
+ *
  * Props:
  *   value     — current option value
  *   onChange  — handler (newValue) => void
@@ -25,27 +30,41 @@
  *               only options (e.g. line-style previews) where text labels
  *               aren't used; the cells still center their contents but the
  *               outer height is tighter.
+ *   ariaLabel — accessible name for the group
  *   className — additional classes on the outer shell
  */
-export default function SegmentedToggle({ value, onChange, options = [], size = 'md', className = '' }) {
-  const wrapHeight = size === 'sm' ? 'h-4' : 'h-[26px]'   /* 16 vs 26 */
-  const cellType   = size === 'sm' ? '' : 'kol-mono-12'
+export default function SegmentedToggle({ value, onChange, options = [], size = 'md', ariaLabel, className = '' }) {
+  const cellType = size === 'sm' ? '' : 'kol-mono-12'
+  const focusIdx = Math.max(0, options.findIndex((opt) => opt.value === value))
+
+  const handleKeyDown = (e) => {
+    const dir = { ArrowLeft: -1, ArrowUp: -1, ArrowRight: 1, ArrowDown: 1 }[e.key]
+    if (!dir || !options.length) return
+    e.preventDefault()
+    const next = (focusIdx + dir + options.length) % options.length
+    onChange?.(options[next].value)
+    e.currentTarget.children[next]?.focus()
+  }
+
   return (
-    <div className={`flex ${wrapHeight} border border-fg-04 rounded overflow-hidden ${className}`}>
+    <div
+      role="radiogroup"
+      aria-label={ariaLabel}
+      onKeyDown={handleKeyDown}
+      className={['kol-seg', size === 'sm' && 'kol-seg--sm', className].filter(Boolean).join(' ')}
+    >
       {options.map((opt, i) => {
         const isActive = opt.value === value
         return (
           <button
             key={opt.value}
             type="button"
-            onClick={() => onChange?.(opt.value)}
-            aria-pressed={isActive}
+            role="radio"
+            aria-checked={isActive}
             aria-label={opt.ariaLabel}
-            className={[
-              `flex-1 ${cellType} inline-flex items-center justify-center cursor-pointer`,
-              isActive ? 'bg-surface-secondary text-emphasis' : 'text-meta hover:text-emphasis',
-              i > 0 ? 'border-l border-fg-04' : '',
-            ].filter(Boolean).join(' ')}
+            tabIndex={i === focusIdx ? 0 : -1}
+            onClick={() => onChange?.(opt.value)}
+            className={['kol-seg-cell', cellType, isActive && 'is-active'].filter(Boolean).join(' ')}
           >
             {opt.label}
           </button>

package/src/atoms/ToggleCheckbox.jsx

@@ -31,7 +31,7 @@ const ToggleCheckbox = ({
       </span>
       <span className="toggle-checkbox-label kol-helper-12 uppercase tracking-[0.08em]">
         {label}
-        {hint ? <span className="ml-2 opacity-60 normal-case tracking-normal text-[10px]">{hint}</span> : null}
+        {hint ? <span className="ml-2 opacity-60 normal-case tracking-normal kol-helper-10">{hint}</span> : null}
       </span>
     </label>
   )

package/src/atoms/ToggleSwitch.jsx

@@ -29,7 +29,7 @@ const ToggleSwitch = ({
       <span className="toggle-switch-label">
         {label}
         {hint ? (
-          <span className="ml-2 opacity-60 normal-case tracking-normal text-[10px]">
+          <span className="ml-2 opacity-60 normal-case tracking-normal kol-helper-10">
             {hint}
           </span>
         ) : null}

package/src/{molecules → atoms}/ViewToggle.jsx

@@ -14,13 +14,16 @@ import { Icon } from '@kolkrabbi/kol-loader'
  *                      where a segmented two-button toggle is overkill.
  *
  * Built on the .kol-control shell. Default options use grid-06 / list-01
- * icons; consumers can pass `options` to override. For `variant="single"`,
- * the FIRST option in `options` is the "off" value; the SECOND is "on".
+ * icons; consumers can pass `options` to override. `iconVariant` picks the
+ * icon cut for variant="icon" ('stroke' default; 'solid' reads better at
+ * 14px). For `variant="single"`, the FIRST option in `options` is the "off"
+ * value; the SECOND is "on".
  */
 const ViewToggle = ({
   viewMode,
   onViewChange,
   variant = 'text',
+  iconVariant = 'stroke',
   options = [
     { value: 'grid', label: 'Grid view', icon: 'grid-06' },
     { value: 'list', label: 'List view', icon: 'list-01' }
@@ -88,7 +91,7 @@ const ViewToggle = ({
           title={option.label}
         >
           {isIconVariant && option.icon ? (
-            <Icon name={option.icon} size={14} />
+            <Icon name={option.icon} size={14} variant={iconVariant} />
           ) : (
             option.label
           )}

package/src/graphics/Graphic.jsx

@@ -4,29 +4,54 @@
  * Globs ./svg/<category>/<name>.svg at build time. Usage:
  *   <Graphic category="patterns" name="pattern-05" />
  *
- * When an asset is missing, renders an AssetPlaceholder with the
- * category/name labeled — missing graphics are visible rather than silently
- * empty. Matches the logo loader pattern (loader lives with assets).
+ * The raw SVG strings (~4.8 MB) live in ./graphicData.js behind a single
+ * dynamic import — their chunk streams in parallel with boot instead of
+ * bloating the consumer's entry chunk (same pattern as kol-loader's Icon).
+ * Until the chunk lands, renders a sized empty box (no layout shift); a
+ * genuinely missing asset renders an AssetPlaceholder so it's visible rather
+ * than silently empty.
  */
-import AssetPlaceholder from '../primitives/AssetPlaceholder.jsx'
+import { useEffect, useState } from 'react'
+import AssetPlaceholder from '../atoms/AssetPlaceholder.jsx'
 
-const svgModules = import.meta.glob('./svg/**/*.svg', { eager: true, query: '?raw', import: 'default' })
+let RAW = null              // category → name → raw svg, once the chunk resolves
+let loadPromise = null
+const subscribers = new Set()
 
-// category → name → raw SVG string. Exported so gallery/table consumers
-// (e.g. AssetTable) read raw markup without a cross-package glob.
-export const GRAPHIC_RAW = Object.entries(svgModules).reduce((acc, [path, svg]) => {
+const loadGraphics = () => {
+  if (!loadPromise) {
+    loadPromise = import('./graphicData.js').then((mod) => {
+      RAW = mod.GRAPHIC_RAW
+      subscribers.forEach((fn) => fn())
+      return mod
+    })
+  }
+  return loadPromise
+}
+
+// Start fetching at module eval — in flight alongside the rest of boot.
+loadGraphics()
+
+const useGraphicsReady = () => {
+  const [ready, setReady] = useState(() => !!RAW)
+  useEffect(() => {
+    if (RAW) return undefined
+    const cb = () => setReady(true)
+    subscribers.add(cb)
+    loadGraphics()
+    return () => subscribers.delete(cb)
+  }, [])
+  return ready
+}
+
+/* Inventory (category → sorted names) from a keys-only glob — paths resolve at
+ * build time without pulling any SVG content into the chunk. */
+export const GRAPHICS = Object.keys(import.meta.glob('./svg/**/*.svg')).reduce((acc, path) => {
   const [category, file] = path.replace('./svg/', '').split('/')
-  const name = file.replace('.svg', '')
-  if (!acc[category]) acc[category] = {}
-  acc[category][name] = svg
+  ;(acc[category] ||= []).push(file.replace('.svg', ''))
   return acc
 }, {})
-
-const GRAPHIC_CACHE = GRAPHIC_RAW
-
-export const GRAPHICS = Object.fromEntries(
-  Object.entries(GRAPHIC_CACHE).map(([category, items]) => [category, Object.keys(items).sort()])
-)
+for (const names of Object.values(GRAPHICS)) names.sort()
 
 export default function Graphic({
   category,
@@ -36,7 +61,20 @@ export default function Graphic({
   title,
   aspectRatio = '1 / 1',
 }) {
-  const raw = GRAPHIC_CACHE[category]?.[name]
+  const ready = useGraphicsReady()
+
+  // Chunk still streaming — hold a same-sized box so layout doesn't shift.
+  if (!ready) {
+    return (
+      <span
+        aria-hidden="true"
+        className={`kol-graphic inline-flex w-full h-auto ${className}`.trim()}
+        style={{ aspectRatio, ...style }}
+      />
+    )
+  }
+
+  const raw = RAW[category]?.[name]
   if (!raw) {
     if (import.meta.env.DEV) console.warn(`Graphic: ${category}/${name} not found`)
     return <AssetPlaceholder category={category} name={name} aspectRatio={aspectRatio} note="pending" className={className} />

package/src/graphics/graphicData.js

@@ -0,0 +1,19 @@
+/**
+ * graphicData — the raw SVG map behind <Graphic>.
+ *
+ * ~4.8 MB of illustration SVGs (some wrap embedded raster images) eager-inline
+ * here, but this module is only reached via the dynamic `import()` in
+ * Graphic.jsx — the bundler splits it into its own async chunk instead of
+ * folding it into the consumer's entry chunk. Same pattern as kol-loader's
+ * iconData.js (kol-labs-single 2026-06-19 entry-chunk fix).
+ */
+const svgModules = import.meta.glob('./svg/**/*.svg', { eager: true, query: '?raw', import: 'default' })
+
+// category → name → raw SVG string.
+export const GRAPHIC_RAW = Object.entries(svgModules).reduce((acc, [path, svg]) => {
+  const [category, file] = path.replace('./svg/', '').split('/')
+  const name = file.replace('.svg', '')
+  if (!acc[category]) acc[category] = {}
+  acc[category][name] = svg
+  return acc
+}, {})

package/src/index.js

@@ -1,59 +1,74 @@
 /**
  * @kol/component - Canonical KOL design-system primitives
  *
- * Shared atoms/molecules consumed by both apps/web (via @kol/ui re-export)
- * and apps/brand. Components emit canonical kol-* classes; CSS lives in
- * @kol/theme (kol-components-*.css).
+ * Shared atoms/molecules/organisms consumed by both apps/web (via @kol/ui
+ * re-export) and apps/brand. Components emit canonical kol-* classes; CSS
+ * lives in @kol/theme (kol-components-*.css).
+ *
+ * Placement follows the taxonomy rules in
+ * docs/taxonomy/01-component-placement.md:
+ *   atom     — nests no KOL component (kol-loader Icon/Graphic are
+ *              infrastructure, they don't count)
+ *   molecule — nests at least one KOL component
+ *   organism — a self-contained composed UI region
+ * `scripts/validate-taxonomy.mjs` enforces the closed folder set and the
+ * downward-only import rule (atoms never import molecules/organisms).
  */
 
-export { default as Divider } from './atoms/Divider.jsx'
-export { default as DropdownTagFilter } from './molecules/DropdownTagFilter.jsx'
-export { default as QuantityInput } from './molecules/QuantityInput.jsx'
-export { default as QuantityStepper } from './molecules/QuantityStepper.jsx'
-export { default as Pill } from './molecules/Pill.jsx'
-export { default as ToggleCheckbox } from './atoms/ToggleCheckbox.jsx'
-export { default as ToggleSwitch } from './atoms/ToggleSwitch.jsx'
-export { default as ToggleBracket } from './molecules/ToggleBracket.jsx'
-export { Icon } from '@kolkrabbi/kol-loader'
-export { default as Tag } from './molecules/Tag.jsx'
-export { default as Badge } from './molecules/Badge.jsx'
-export { default as SectionLabel } from './molecules/SectionLabel.jsx'
-export { default as Section } from './molecules/Section.jsx'
-export { default as Button } from './atoms/Button.jsx'
-export { default as Input } from './atoms/Input.jsx'
-export { default as Slider } from './atoms/Slider.jsx'
-export { default as Dropdown } from './molecules/Dropdown.jsx'
-export { usePopover, PopoverPanel, Tooltip } from './molecules/Popover.jsx'
-export { MenuItem, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } from './molecules/MenuItem.jsx'
-
-/* ── Folded from apps/brand (Phase 4 — brand is canonical, brand wins) ────── */
 // atoms
+export { default as AssetPlaceholder } from './atoms/AssetPlaceholder.jsx'
 export { default as Avatar } from './atoms/Avatar.jsx'
-export { default as ColorSwatch } from './atoms/ColorSwatch.jsx'
+export { default as Badge } from './atoms/Badge.jsx'
+export { default as Button } from './atoms/Button.jsx'
+export { default as CopyButton } from './atoms/CopyButton.jsx'
+export { default as Divider } from './atoms/Divider.jsx'
+export { default as DropdownTagFilter } from './atoms/DropdownTagFilter.jsx'
+export { default as ExitPreview } from './atoms/ExitPreview.jsx'
+export { default as FullscreenOverlay } from './atoms/FullscreenOverlay.jsx'
+export { default as Input } from './atoms/Input.jsx'
 export { default as Label } from './atoms/Label.jsx'
+export { default as LabeledControl } from './atoms/LabeledControl.jsx'
+export { default as Pill } from './atoms/Pill.jsx'
+export { usePopover, PopoverPanel, Tooltip } from './atoms/Popover.jsx'
+export { default as QuantityInput } from './atoms/QuantityInput.jsx'
+export { default as QuantityStepper } from './atoms/QuantityStepper.jsx'
+export { default as Section } from './atoms/Section.jsx'
+export { default as SectionLabel } from './atoms/SectionLabel.jsx'
+export { default as SegmentedToggle } from './atoms/SegmentedToggle.jsx'
 export { default as Stepper } from './atoms/Stepper.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'
+export { default as ToggleCheckbox } from './atoms/ToggleCheckbox.jsx'
+export { default as ToggleSwitch } from './atoms/ToggleSwitch.jsx'
 export { default as TransparentX } from './atoms/TransparentX.jsx'
+export { default as ViewToggle } from './atoms/ViewToggle.jsx'
+
 // molecules
-export { default as ContentFilters } from './molecules/ContentFilters.jsx'
-export { default as LabeledControl } from './molecules/LabeledControl.jsx'
+export { Accordion, AccordionPanel } from './molecules/Accordion.jsx'
+export { default as CodeBlock } from './molecules/CodeBlock.jsx'
+export { default as ColorSwatch } from './molecules/ColorSwatch.jsx'
+export { default as Dropdown } from './molecules/Dropdown.jsx'
+export { default as Image } from './molecules/Image.jsx'
+export { default as MediaCard } from './molecules/MediaCard.jsx'
+export { default as MediaRow } from './molecules/MediaRow.jsx'
+export { MenuItem, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } from './molecules/MenuItem.jsx'
 export { MenuPopover } from './molecules/MenuPopover.jsx'
 export { ModalProvider, useModal } from './molecules/Modal.jsx'
 export { default as PropertyInput } from './molecules/PropertyInput.jsx'
-export { default as SegmentedToggle } from './molecules/SegmentedToggle.jsx'
-export { default as ViewToggle } from './molecules/ViewToggle.jsx'
-// primitives
-export { Accordion, AccordionPanel } from './primitives/Accordion.jsx'
-export { default as AssetPlaceholder } from './primitives/AssetPlaceholder.jsx'
-export { default as Carousel } from './primitives/Carousel.jsx'
-export { default as CodeBlock } from './primitives/CodeBlock.jsx'
-export { default as ExitPreview } from './primitives/ExitPreview.jsx'
-export { default as FullscreenOverlay } from './primitives/FullscreenOverlay.jsx'
-export { default as Image } from './primitives/Image.jsx'
-// graphics (SVG illustration loader — globs its own ./graphics/svg/**)
-export { default as Graphic, GRAPHICS, GRAPHIC_RAW } from './graphics/Graphic.jsx'
+export { default as Slider } from './molecules/Slider.jsx'
+
 // organisms
+export { default as Carousel } from './organisms/Carousel.jsx'
+export { default as ContentFilters } from './organisms/ContentFilters.jsx'
 export { default as Table } from './organisms/Table.jsx'
+
+// loaders (re-export — infrastructure, documented on /docs/loaders)
+export { Icon } from '@kolkrabbi/kol-loader'
+
+// graphics (SVG illustration loader — globs its own ./graphics/svg/**)
+export { default as Graphic, GRAPHICS } from './graphics/Graphic.jsx'
+
 // hooks
 export { default as useReveal } from './hooks/useReveal.js'
 export { default as useScrollSpy } from './hooks/useScrollSpy.js'

package/src/{primitives → molecules}/Accordion.jsx

@@ -1,6 +1,9 @@
 /**
  * Accordion — collapsible panel group.
  *
+ * taxonomy-ok: molecule — Accordion nests AccordionPanel in this same file,
+ * which the import-based validator can't see.
+ *
  * Composition-based: <Accordion> wraps <AccordionPanel> children. Each panel
  * owns its open/closed state independently (additive — multiple can be open).
  * For single-open behavior, manage state from the parent and pass controlled
@@ -37,7 +40,7 @@ export function AccordionPanel({
       >
         <span className="kol-accordion-title kol-helper-12 uppercase tracking-widest">{title}</span>
         {meta && <span className="kol-accordion-meta kol-helper-12 uppercase tracking-widest text-fg-48 ml-auto mr-3">{meta}</span>}
-        <span className="kol-accordion-chevron font-mono text-[18px] text-fg-48 min-w-3 transition-colors duration-[120ms] ml-auto" aria-hidden="true">{open ? '−' : '+'}</span>
+        <span className="kol-accordion-chevron kol-helper-16 text-fg-48 min-w-3 transition-colors duration-[120ms] ml-auto" aria-hidden="true">{open ? '−' : '+'}</span>
       </button>
       {open && <div className="kol-accordion-body pt-2 pb-6">{children}</div>}
     </div>

package/src/molecules/CodeBlock.jsx

@@ -0,0 +1,11 @@
+import CopyButton from '../atoms/CopyButton.jsx'
+
+export default function CodeBlock({ children, language }) {
+  return (
+    <div className="kol-codeblock">
+      {language && <span className="kol-codeblock-lang">{language}</span>}
+      <CopyButton text={String(children)} className="kol-codeblock-copy" />
+      <pre><code>{children}</code></pre>
+    </div>
+  )
+}

package/src/{atoms → molecules}/ColorSwatch.jsx

@@ -34,7 +34,7 @@
  *   onClick         — if provided, renders as <button>; else <span>.
  *   title           — passes through.
  */
-import TransparentX from './TransparentX'
+import TransparentX from '../atoms/TransparentX'
 
 const SIZE_CLASSES = {
   fill:    'w-full aspect-square',

package/src/molecules/Dropdown.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-loader'
 import { MenuDropdownItem } from './MenuItem.jsx'
-import { PopoverPanel, usePopover } from './Popover.jsx'
+import { PopoverPanel, usePopover } from '../atoms/Popover.jsx'
 
 const SIZE_MAP = {
   sm: { fontSize: 12, paddingY: 4, paddingX: 12, radius: 14, panelRadius: 14, icon: 10 },
@@ -17,9 +17,10 @@ const Dropdown = ({
   onChange,
   size,
   variant = 'default',
+  defaultOpen = false,
   className = ''
 }) => {
-  const [isOpen, setIsOpen] = useState(false)
+  const [isOpen, setIsOpen] = useState(defaultOpen)
   const [resolvedSize, setResolvedSize] = useState('md')
   const [dropdownWidth, setDropdownWidth] = useState('100px')
 

package/src/{primitives → molecules}/Image.jsx

@@ -6,7 +6,7 @@
  * visible at its intended size (aspect-ratio preserved).
  */
 import { useState } from 'react'
-import AssetPlaceholder from './AssetPlaceholder'
+import AssetPlaceholder from '../atoms/AssetPlaceholder'
 
 export default function Image({
   src,

package/src/molecules/MediaCard.jsx

@@ -0,0 +1,97 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: nests kol-loader's Icon (a package import the relative-import
+ * check can't see) plus the same-file SelectIndicator. */
+
+/**
+ * SelectIndicator — passive square check indicator for multi-select rows and
+ * cards. `on` = checked. Deliberately NOT ToggleCheckbox: that is a labeled
+ * form control with a real <input>, which double-fires inside a click-target
+ * card and misleads assistive tech — here the CARD is the toggle, this is
+ * only its visual state. Inline CSS vars because `bg-fg-default` isn't a
+ * generated Tailwind utility; the checked fill reads from
+ * `--kol-surface-on-primary` (solid fg, theme-correct).
+ *
+ * Shared by MediaCard and MediaRow; not exported from the package barrel.
+ */
+export function SelectIndicator({ on = false }) {
+  return (
+    <span
+      className="w-4 h-4 shrink-0 rounded-sm border flex items-center justify-center transition-colors"
+      style={
+        on
+          ? { background: 'var(--kol-surface-on-primary)', borderColor: 'var(--kol-surface-on-primary)' }
+          : { background: 'var(--kol-fg-absolute-16, rgba(0,0,0,0.15))', borderColor: 'var(--kol-fg-absolute-48, rgba(0,0,0,0.4))' }
+      }
+      aria-hidden="true"
+    >
+      {on && <Icon name="check" size={11} style={{ color: 'var(--kol-surface-primary)' }} />}
+    </span>
+  )
+}
+
+/**
+ * MediaCard — grid tile for one media object: square thumbnail with a
+ * top-right download overlay (or a top-left select checkbox in select mode),
+ * then name / meta / actions stacked below. The grid-view counterpart to
+ * MediaRow (same slot contract).
+ *
+ * Presentational — the parent supplies rendered slots; no media loading,
+ * fetch, or rename logic lives here. Grid track sizing belongs to the parent
+ * list; the card just fills its cell.
+ *
+ * @param {ReactNode} thumb        square thumbnail (image/video/placeholder)
+ * @param {ReactNode} name         name cell (plain text or an inline editor)
+ * @param {string}    meta         one-line secondary text (e.g. "1.2 MB · 2026-06-19")
+ * @param {ReactNode} actions      row of action buttons (hidden in select mode)
+ * @param {string}    downloadHref href for the overlay download button (omit to hide)
+ * @param {boolean}   selectMode   selection mode on → checkbox replaces download, whole card toggles
+ * @param {boolean}   selected     this card is selected (stronger border + checked box)
+ * @param {Function}  onSelect     (event) => void — card click in select mode; gets shiftKey for range
+ */
+export default function MediaCard({
+  thumb,
+  name,
+  meta,
+  actions,
+  downloadHref,
+  selectMode = false,
+  selected = false,
+  onSelect,
+}) {
+  return (
+    <li
+      onClick={selectMode ? onSelect : undefined}
+      className={`flex flex-col rounded overflow-hidden border bg-fg-02 ${selectMode ? 'cursor-pointer select-none' : ''}`}
+      style={{ borderColor: selected ? 'var(--kol-fg-64)' : 'var(--kol-fg-12)' }}
+    >
+      <div className="aspect-square relative">
+        {thumb}
+        {selectMode ? (
+          <span
+            className="absolute top-3 left-3 rounded p-1"
+            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+          >
+            <SelectIndicator on={selected} />
+          </span>
+        ) : downloadHref ? (
+          <a
+            href={downloadHref}
+            aria-label="Download"
+            title="Download"
+            className="absolute top-3 right-3 inline-flex items-center justify-center w-8 h-8 rounded text-emphasis hover:bg-fg-absolute-24 transition-colors"
+            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Icon name="download" size={16} />
+          </a>
+        ) : null}
+      </div>
+      <div className="p-3 flex flex-col gap-2">
+        {name}
+        <p className="kol-mono-12 text-fg-48">{meta}</p>
+        {!selectMode && actions}
+      </div>
+    </li>
+  )
+}

package/src/molecules/MediaRow.jsx

@@ -0,0 +1,49 @@
+import { SelectIndicator } from './MediaCard.jsx'
+
+/**
+ * MediaRow — list row for one media object: optional select checkbox, small
+ * thumbnail, name (flex), fixed-width date + size columns, then actions.
+ * The list-view counterpart to MediaCard (same slot contract).
+ *
+ * Presentational — the parent supplies rendered slots; interaction outside
+ * select mode lives in the thumb / name / actions slots. Column widths are
+ * consumer-tunable via `dateWidth` / `sizeWidth`.
+ *
+ * @param {ReactNode} thumb       small thumbnail (48px square)
+ * @param {ReactNode} name        name cell (plain text or an inline editor)
+ * @param {string}    date        right-aligned date column
+ * @param {string}    size        right-aligned size column
+ * @param {ReactNode} actions     row of action buttons (hidden in select mode)
+ * @param {string}    dateWidth   Tailwind width class for the date column
+ * @param {string}    sizeWidth   Tailwind width class for the size column
+ * @param {boolean}   selectMode  selection mode on → checkbox shown, whole row toggles, actions hidden
+ * @param {boolean}   selected    this row is selected (highlight + checked box)
+ * @param {Function}  onSelect    (event) => void — row click in select mode; gets shiftKey for range
+ */
+export default function MediaRow({
+  thumb,
+  name,
+  date,
+  size,
+  actions,
+  dateWidth = 'w-24',
+  sizeWidth = 'w-20',
+  selectMode = false,
+  selected = false,
+  onSelect,
+}) {
+  return (
+    <li
+      onClick={selectMode ? onSelect : undefined}
+      className={`flex items-center gap-3 py-2 border-b ${selectMode ? 'cursor-pointer select-none' : ''} ${selected ? 'bg-fg-08' : ''}`}
+      style={{ borderColor: 'var(--kol-fg-08)' }}
+    >
+      {selectMode && <SelectIndicator on={selected} />}
+      <div className="w-12 h-12 shrink-0 rounded overflow-hidden">{thumb}</div>
+      <div className="flex-1 min-w-0">{name}</div>
+      <p className={`kol-mono-12 text-fg-32 shrink-0 text-right ${dateWidth}`}>{date}</p>
+      <p className={`kol-mono-12 text-fg-48 shrink-0 text-right ${sizeWidth}`}>{size}</p>
+      {!selectMode && <div className="shrink-0">{actions}</div>}
+    </li>
+  )
+}

package/src/molecules/MenuItem.jsx

@@ -1,6 +1,6 @@
 import { useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-loader'
-import { PopoverPanel, usePopover } from './Popover.jsx'
+import { PopoverPanel, usePopover } from '../atoms/Popover.jsx'
 
 /**
  * MenuItem — top-level menu entry. Trigger button + popover panel.
@@ -26,8 +26,9 @@ export function MenuItem({
   panelClassName = '',
   panelStyle,
   buttonClassName = '',
+  defaultOpen = false,
 }) {
-  const [open, setOpen] = useState(false)
+  const [open, setOpen] = useState(defaultOpen)
   const popover = usePopover({
     open,
     onOpenChange: setOpen,

package/src/molecules/MenuPopover.jsx

@@ -1,103 +1,18 @@
-import { useEffect, useRef, useState } from 'react'
+import { MenuItem as MenuTrigger } from './MenuItem.jsx'
 
 /**
- * MenuPopover — generic action-menu / popover primitive.
+ * MenuPopover — DEPRECATED alias of MenuItem (2026-07-02 menu-family
+ * unification).
  *
- *   <MenuPopover label="File">
- *     <MenuItem onClick={…}>Save</MenuItem>
- *     <MenuItem onClick={…}>Export…</MenuItem>
- *   </MenuPopover>
- *
- * Opens on click, closes on outside-click + Escape, anchors to the trigger
- * via getBoundingClientRect + position:fixed so it escapes overflow:auto
- * clipping. Pass `panelClassName` to size the panel (e.g. wider for
- * Templates).
- *
- * For value-list selection (single value, active state) use `Dropdown`
- * instead — this primitive is for action menus / popover panels that
- * hold arbitrary children.
+ * The two triggers had an identical API (label, children incl. ({ close })
+ * render-prop, align, panelClassName, panelStyle, buttonClassName,
+ * defaultOpen) and did the same job — MenuPopover with hand-rolled
+ * fixed positioning, MenuItem on floating-ui (portal, auto-flip, focus
+ * management). One implementation now: MenuItem. This alias keeps existing
+ * call-sites working; migrate imports to MenuItem. Removal in the next major.
  */
-export function MenuPopover({
-  label,
-  children,
-  align = 'start',
-  panelClassName = '',
-  panelStyle,
-  buttonClassName = '',
-}) {
-  const [open, setOpen] = useState(false)
-  const wrapRef   = useRef(null)
-  const buttonRef = useRef(null)
-  const [panelPos, setPanelPos] = useState(null)
-
-  useEffect(() => {
-    if (!open) return
-    const onDown = (e) => {
-      if (!wrapRef.current?.contains(e.target)) setOpen(false)
-    }
-    const onKey = (e) => { if (e.key === 'Escape') setOpen(false) }
-    document.addEventListener('mousedown', onDown)
-    document.addEventListener('keydown',   onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDown)
-      document.removeEventListener('keydown',   onKey)
-    }
-  }, [open])
-
-  useEffect(() => {
-    if (!open) { setPanelPos(null); return }
-    const update = () => {
-      const rect = buttonRef.current?.getBoundingClientRect()
-      if (!rect) return
-      setPanelPos({ top: rect.bottom + 4, left: rect.left, right: rect.right })
-    }
-    update()
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
-    return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
-    }
-  }, [open])
-
-  const close = () => setOpen(false)
-
-  const positioned = panelPos && (
-    align === 'end'
-      ? { top: panelPos.top, right: window.innerWidth - panelPos.right }
-      : { top: panelPos.top, left: panelPos.left }
-  )
-
-  return (
-    <div ref={wrapRef} className="relative inline-block">
-      <button
-        ref={buttonRef}
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        aria-haspopup="menu"
-        aria-expanded={open}
-        className={`kol-helper-12 px-3 h-8 inline-flex items-center gap-1 rounded text-meta hover:text-emphasis transition-colors ${buttonClassName}`}
-      >
-        <span>{label}</span>
-        <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
-          <path d="m3 5 3 3 3-3" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" strokeLinejoin="round" fill="none" />
-        </svg>
-      </button>
-      {open && positioned && (
-        <div
-          role="menu"
-          className={`fixed z-[1000] bg-surface-primary border border-fg-08 rounded shadow-lg ${panelClassName}`}
-          style={{ ...positioned, ...panelStyle }}
-          onClick={(e) => {
-            /* close on item click — items inside fire their handler then bubble. */
-            if (e.target.closest('[data-menu-item]')) close()
-          }}
-        >
-          {typeof children === 'function' ? children({ close }) : children}
-        </div>
-      )}
-    </div>
-  )
+export function MenuPopover(props) {
+  return <MenuTrigger {...props} />
 }
 
 /**

package/src/{atoms → molecules}/Slider.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from 'react'
-import Input from './Input.jsx'
+import Input from '../atoms/Input.jsx'
 
 /**
  * Slider — range slider with label and an editable value readout.

package/src/{molecules → organisms}/ContentFilters.jsx

@@ -1,8 +1,8 @@
 import { useState, useMemo, useRef, useEffect } from 'react'
-import Tag from './Tag.jsx'
+import Tag from '../atoms/Tag.jsx'
 import Divider from '../atoms/Divider.jsx'
 import { Icon } from '@kolkrabbi/kol-loader'
-import ViewToggle from './ViewToggle'
+import ViewToggle from '../atoms/ViewToggle'
 
 /**
  * ContentFilters — universal filter component for content grids.

package/src/primitives/CodeBlock.jsx

@@ -1,41 +0,0 @@
-import { useState } from 'react'
-
-export default function CodeBlock({ children, language }) {
-  const [copied, setCopied] = useState(false)
-
-  const onCopy = async () => {
-    try {
-      await navigator.clipboard.writeText(String(children))
-      setCopied(true)
-      setTimeout(() => setCopied(false), 1800)
-    } catch {
-      /* clipboard blocked — silent */
-    }
-  }
-
-  return (
-    <div className="kol-codeblock">
-      {language && <span className="kol-codeblock-lang">{language}</span>}
-      <button
-        type="button"
-        className="kol-codeblock-copy"
-        onClick={onCopy}
-        aria-label={copied ? 'Copied' : 'Copy to clipboard'}
-        title={copied ? 'Copied' : 'Copy'}
-      >
-        {copied ? (
-          <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
-            <path d="M5 10 L9 14 L15 6" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
-          </svg>
-        ) : (
-          <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
-            <rect x="6" y="3" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
-            <rect x="4" y="6" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
-          </svg>
-        )}
-        <span className="leading-none">{copied ? 'Copied' : 'Copy'}</span>
-      </button>
-      <pre><code>{children}</code></pre>
-    </div>
-  )
-}