@kolkrabbi/kol-component 0.45.0 → 0.47.0

package/src/molecules/ContentMedia.jsx

@@ -0,0 +1,91 @@
+import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
+
+/**
+ * ContentMedia — the media slot of the content-card system.
+ *
+ * Ratio is the only knob (`fit` was cut 2026-08-15 — a card image covers,
+ * full stop). No children → AssetPlaceholder at the same ratio, so a card
+ * with no media is visibly flagged, never collapsed.
+ *
+ * `ratio` is a FREE prop (06-content-card-system.md §4 — the A4 question is
+ * open; nothing hardcodes a ratio). The ruled per-variant defaults live in
+ * ContentCard/ContentRow, not here.
+ *
+ * `radius` (2026-08-15 user ruling): OFF when the host frame already clips its
+ * own corners. A card that clips and a media slot that rounds are two radii on
+ * one edge — the visible double-round. ContentCard turns it off for its framed
+ * variants; the ROW keeps it, because a row does not clip.
+ *
+ * `fit` (2026-08-15) — `cover` crops to fill, which is right for a photograph
+ * and wrong for a diagram or a screenshot, where the crop eats the content.
+ * `natural` and `compact` are GridCard's `previewFit` under the family's name;
+ * the shipped values are kept so a catalog grid can move over without a
+ * re-tune. `cover` stays the default — every card in the family today is a
+ * photograph.
+ *
+ * THREE separate edge treatments, because the shipped components use three:
+ *
+ *   frame   a TINTED box + border UNDER the media — article's card media is
+ *           `bg-fg-04 border-fg-08`, and the tint shows wherever a 16/9 thumb
+ *           does not fill its box
+ *   border  border ONLY, no tint — WorkListItem's thumb is `border-fg-08` over
+ *           a full-bleed image, where a tint would never be seen anyway and
+ *           painting one is just a wrong value nobody notices
+ *   ring    an inset hairline OVER the artwork — how a print card keeps a light
+ *           image from bleeding into a light page
+ *
+ * `bg` tints without any border — ListingCard's row thumb is `bg-fg-12` bare.
+ * They compose; a frame behind a full-bleed cover image is invisible, a ring
+ * over one is the only thing you see.
+ *
+ * NOT here, deliberately: `loading="lazy"` and the fade-on-load. The media is
+ * consumer-INJECTED — the real `<img>` is theirs — so lazy is one attribute on
+ * their own element, and taking it over would mean cloneElement'ing a node the
+ * family does not own to attach an onLoad it cannot guarantee fires (a cached
+ * image never does). Reaching into someone else's element to animate it is the
+ * kind of magic that breaks silently a year later.
+ *
+ * @param {string}    ratio     CSS aspect-ratio, e.g. '1 / 1', '16 / 9', '1 / 1.41421'
+ * @param {boolean}   radius    round the media's own corners (default true)
+ * @param {string}    fit       cover | natural | compact — how the child sits in the box
+ * @param {boolean}   frame     tinted box + border UNDER the media
+ * @param {boolean}   border    border only, no tint
+ * @param {string}    bg        tint only, no border — a raw token value
+ * @param {string}    borderHover  border colour on hover (article's fg-16 step)
+ * @param {boolean}   ring      hairline border OVER the media, inset
+ * @param {ReactNode} children  the real media
+ */
+const FIT = {
+  cover:   '[&>img]:h-full [&>img]:w-full [&>img]:object-cover [&>video]:h-full [&>video]:w-full [&>video]:object-cover',
+  natural: '[&>img]:h-full [&>img]:w-full [&>img]:object-contain [&>video]:h-full [&>video]:w-full [&>video]:object-contain',
+  compact: 'grid place-items-center [&>img]:max-h-[70%] [&>img]:max-w-[70%] [&>img]:object-contain',
+}
+
+export default function ContentMedia({
+  ratio = '1 / 1',
+  radius = true,
+  fit = 'cover',
+  frame = false,
+  border = false,
+  bg,
+  borderHover,
+  ring = false,
+  children,
+  className = '',
+}) {
+  if (children == null) {
+    return <AssetPlaceholder radius={radius} aspectRatio={ratio ?? undefined} className={ratio == null ? `h-full ${className}` : className} />
+  }
+  const round = radius ? 'rounded-[var(--kol-radius-sm)]' : ''
+  return (
+    <div
+      className={`relative w-full overflow-hidden ${round} ${FIT[fit] ?? FIT.cover} ${frame ? 'bg-fg-04 border border-fg-08' : ''} ${border ? 'border border-fg-08' : ''} ${borderHover ? 'transition-colors hover:border-fg-16' : ''} ${ratio == null ? 'h-full' : ''} ${className}`.trim()}
+      style={{ ...(ratio != null ? { aspectRatio: ratio } : null), background: bg }}
+    >
+      {children}
+      {/* OVER the artwork, and inert — a hairline that must not eat the click
+        * the card above it is listening for. */}
+      {ring && <div className={`pointer-events-none absolute inset-0 border border-fg-08 ${round}`} />}
+    </div>
+  )
+}

package/src/molecules/ContentRow.jsx

@@ -0,0 +1,145 @@
+import ContentMedia from './ContentMedia.jsx'
+import ContentText from './ContentText.jsx'
+
+/**
+ * ContentRow — 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
+ * line with a 48px thumb; catalog/print are framed between-headers with no
+ * thumb; article rides a 120px 16:9 thumb; work a framed 64px row; typeface a
+ * framed no-thumb block.
+ *
+ * @param {string}    variant   default | catalog | print | article | work | typeface
+ * @param {ReactNode} media     thumb content (omit → placeholder)
+ * @param {number}    thumb     thumb edge px — overrides the ruled default; 0 hides
+ * @param {string}    ratio     thumb aspect-ratio — overrides the ruled default
+ * @param {number}    paddingY  vertical padding px — overrides the ruled default
+ * @param {boolean}   selected
+ * @param {Function}  onClick
+ * text slots + *Class seams forwarded to ContentText.
+ */
+
+/* ruled row boxes per variant (the §2 review) — paddings/gaps spell the
+ * --kol-spacing-* tokens (2=8 · 3=12 · 4=16 · 6=24), never a literal */
+const S2 = 'var(--kol-spacing-2)', S3 = 'var(--kol-spacing-3)', S4 = 'var(--kol-spacing-4)', S6 = 'var(--kol-spacing-6)'
+const BOX = {
+  default:  { thumb: 48,  ratio: '1 / 1',  pad: `${S2} 0`,     gap: S3, align: 'items-center', divider: true, hover: 'var(--kol-oq-04)' },
+  /* catalog/print rows render AT 36px — the shipped GridCard list row is a
+   * fixed 36 and the Y padding was what pushed it past that. X padding stays;
+   * `minH` is now the whole height budget and the row centres inside it. */
+  catalog:  { thumb: 0,   ratio: '1 / 1',  pad: `0 ${S3}`,     gap: S3, frame: 'var(--kol-fg-04)', bg: 'var(--kol-surface-tertiary)', minH: 36, align: 'items-center', hover: 'var(--kol-oq-04)' },
+  print:    { thumb: 0,   ratio: '1 / 1',  pad: `0 ${S3}`,     gap: S3, frame: 'var(--kol-fg-04)', bg: 'var(--kol-surface-tertiary)', minH: 36, align: 'items-center', hover: 'var(--kol-oq-04)' },
+  /* ListingCard's row thumb is `bg-fg-12` bare — a tint, no border. */
+  article:  { thumb: 120, ratio: '1 / 1',  pad: '0',           gap: S6, align: 'items-start', thumbBg: 'var(--kol-fg-12)' },
+  /* work and typeface step UP at md — the shipped rows both do, and a work row
+   * at a fixed 96 cannot hold the display-03 line it was ruled to carry. */
+  work:     { thumb: 64,  thumbMd: 112, ratio: '1 / 1', pad: S4, padMd: S6, gap: S4, gapMd: S6, frame: 'transparent', frameHover: 'var(--kol-fg-16)', bg: 'var(--kol-surface-secondary)', minH: 96, minHMd: 160, align: 'items-stretch', thumbRadius: 'var(--kol-radius-xs)', thumbBorder: true },
+  /* typeface's row is a COLUMN, not a line: a header (name/styles left,
+   * classification/year right) with a full-width specimen band under it. The
+   * shipped item is `flex-col gap-6`, and forcing it into the horizontal
+   * thumb-beside-text shape is what turned its alphabet into a 160px thumb. */
+  typeface: { thumb: 0,   ratio: '1 / 1',  pad: S6,            gap: S6, column: true, frame: 'var(--kol-fg-08)', bg: 'transparent', minH: 160, align: 'items-start', hover: 'color-mix(in srgb, var(--kol-surface-on-primary) 1%, transparent)', frameHover: 'color-mix(in srgb, var(--kol-surface-on-primary) 24%, transparent)' },
+}
+
+export default function ContentRow({
+  variant = 'default',
+  media,
+  thumb,
+  ratio,
+  paddingY,
+  actions,
+  footer,
+  selected = false,
+  onClick,
+  href,
+  onNavigate,
+  className = '',
+  ...text
+}) {
+  const box = BOX[variant] ?? BOX.default
+  const thumbPx = thumb ?? box.thumb
+
+  /* The md: STEP is a custom property, not a Tailwind variant. Tailwind cannot
+   * generate `md:min-h-40` from package source (the SegmentedToggle rule), and
+   * these values are per-variant data rather than markup, so the row publishes
+   * `--kol-row-*` / `--kol-row-*-md` and one media query in kol-theme swaps
+   * them. A variant with no md value publishes nothing and never steps. */
+  const vars = {
+    '--kol-row-pad': paddingY != null ? `${paddingY}px 0` : box.pad,
+    '--kol-row-pad-md': box.padMd,
+    '--kol-row-gap': box.gap,
+    '--kol-row-gap-md': box.gapMd,
+    '--kol-row-min-h': box.minH != null ? `${box.minH}px` : undefined,
+    '--kol-row-min-h-md': box.minHMd != null ? `${box.minHMd}px` : undefined,
+    '--kol-row-thumb': `${thumbPx}px`,
+    '--kol-row-thumb-md': box.thumbMd != null ? `${box.thumbMd}px` : undefined,
+    '--kol-content-hover-bg': box.hover,
+    '--kol-content-hover-border': box.frameHover,
+    /* rest values are PROPERTIES, not inline declarations — an inline
+     * `background`/`borderColor` outranks every class, so the hover rules in
+     * kol-theme could never win and no row hover fired at all. */
+    '--kol-row-bg': selected ? 'var(--kol-fg-04)' : box.bg,
+    '--kol-row-border': box.frame || undefined,
+  }
+
+  const nav = (event) => {
+    if (onNavigate) onNavigate(event, href)
+    if (onClick) onClick(event)
+  }
+  const interactive = href || onClick
+
+  /* COLUMN rows stack their band under the text instead of laying a thumb
+   * beside it — `footer` is that band, and it is a node because what goes in it
+   * (a rendered alphabet, a waveform, a sparkline) is never the family's. */
+  const inner = box.column ? (
+    <>
+      <ContentText variant={variant} form="row" className="w-full" {...text} />
+      {footer}
+    </>
+  ) : (
+    <>
+      {thumbPx > 0 && (
+        <div className="kol-row-thumb shrink-0">
+          <ContentMedia
+            ratio={ratio ?? box.ratio}
+            border={box.thumbBorder ?? false}
+            bg={box.thumbBg}
+            className={box.thumbRadius ? 'rounded-[var(--kol-radius-xs)]' : ''}
+          >
+            {media}
+          </ContentMedia>
+        </div>
+      )}
+      <ContentText variant={variant} form="row" className="flex-1" {...text} />
+      {/* trailing edge, never in the text flow — MediaRow's placement */}
+      {actions && <div className="shrink-0">{actions}</div>}
+    </>
+  )
+
+  const common = {
+    className: `kol-row flex ${box.column ? 'flex-col' : ''} ${box.align} ${box.divider ? 'border-b border-fg-08' : ''} ${box.frame ? 'rounded-[var(--kol-radius-sm)] border' : ''} ${interactive ? 'cursor-pointer select-none' : ''} ${interactive && box.hover ? 'kol-content-hover' : ''} ${interactive && box.frameHover ? 'kol-content-hover-frame' : ''} ${className}`.trim(),
+    style: vars,
+  }
+
+  /* same root-follows-the-affordance rule as ContentCard */
+  if (href) return <a href={href} onClick={nav} {...common}>{inner}</a>
+  if (onClick) {
+    return (
+      <div
+        onClick={onClick}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key !== 'Enter' && e.key !== ' ') return
+          e.preventDefault()
+          onClick(e)
+        }}
+        {...common}
+      >
+        {inner}
+      </div>
+    )
+  }
+  return <div {...common}>{inner}</div>
+}

package/src/molecules/ContentText.jsx

@@ -0,0 +1,223 @@
+/**
+ * ContentText — the ruled text block of the content-card system.
+ *
+ * Renders the per-variant / per-form type ramp ruled 2026-08-15
+ * (docs/documentation/03-components/06-content-card-system.md §3). The laws:
+ * title is the ONLY slot that steps between card and row (size only, one
+ * family); body and meta are identical in both forms; ink is three roles
+ * (emphasis · body · meta). `kol-helper-*` is out of this family — it is not
+ * mono with line-height 1, it also carries weight 500 and 0.06em tracking, so
+ * a helper field beside a mono one reads as a different voice.
+ *
+ * Every type class is a SEAM: pass `<slot>Class` to replace the ruled
+ * class+ink string whole (consumers on their own faces swap here). Passing
+ * nothing renders the ruled values.
+ *
+ * @param {string} variant   default | catalog | print | article | work | typeface
+ * @param {string} form      card | row
+ * @param {ReactNode} title
+ * @param {ReactNode} body       article · work · typeface
+ * @param {ReactNode} kicker     article only
+ * @param {ReactNode} detail     catalog · print
+ * @param {ReactNode} date       default · article · typeface
+ * @param {ReactNode} size       default · article (file size / read length)
+ * @param {ReactNode} meta       work only
+ * @param {number}    gap        inner line gap in px (defaults per variant/form)
+ * @param {string}    titleClass … kickerClass, bodyClass, detailClass,
+ *                    dateClass, sizeClass, metaClass — full class overrides
+ */
+
+/* [variant][form][slot] → 'type-class ink-role', verbatim from the ruled table */
+const RAMP = {
+  default: {
+    card: { title: 'kol-sans-heading-04 text-emphasis truncate', date: 'kol-mono-12 text-meta', size: 'kol-mono-12 text-meta' },
+    row:  { title: 'kol-sans-heading-05 text-emphasis truncate', date: 'kol-mono-12 text-meta', size: 'kol-mono-12 text-meta' },
+  },
+  catalog: {
+    card: { title: 'kol-mono-14 text-emphasis', detail: 'kol-mono-10 text-meta' },
+    row:  { title: 'kol-mono-12 text-emphasis', detail: 'kol-mono-10 text-meta' },
+  },
+  print: {
+    card: { title: 'kol-mono-14 text-body', detail: 'kol-mono-10 text-meta' },
+    row:  { title: 'kol-mono-10 text-body', detail: 'kol-mono-10 text-meta' },
+  },
+  article: {
+    card: { kicker: 'kol-mono-12 text-body', title: 'kol-sans-heading-03 text-emphasis', body: 'kol-mono-14 text-body', date: 'kol-mono-12 text-meta', size: 'kol-mono-12 text-body', tags: 'flex flex-wrap gap-2' },
+    row:  { kicker: 'kol-mono-12 text-body', title: 'kol-sans-heading-04 text-emphasis', body: 'kol-mono-12 text-body', date: 'kol-mono-12 text-meta', size: 'kol-mono-12 text-body', tags: 'flex flex-wrap gap-2' },
+  },
+  work: {
+    /* INVERSE ink — the card's plate is the drawer, `surface-inverse`. Leaving
+     * these on `text-emphasis` painted light type on a light plate and the
+     * caption disappeared. */
+    card: { title: 'kol-sans-display-03 text-fg-inverse', meta: 'kol-mono-12 text-fg-inverse-48', body: 'kol-mono-14 text-fg-inverse', date: 'kol-mono-12 text-fg-inverse-48', tags: 'flex flex-wrap gap-2' },
+    /* verbatim from WorkListItem: title `kol-mono-14` truncated · type
+     * `kol-mono-12 md:kol-mono-14` at FULL ink, no opacity step · year
+     * `kol-mono-12 text-fg-64` · description `kol-sans-heading-03 text-auto`.
+     * Title and type are the pair — same rung, same full ink; only the year
+     * steps down. */
+    row:  { title: 'kol-mono-12 text-emphasis uppercase truncate', body: 'kol-sans-heading-03 leading-tight text-emphasis truncate', meta: 'kol-mono-12 text-emphasis', date: 'kol-mono-12 text-fg-64', tags: 'flex flex-wrap items-center gap-1.5' },
+  },
+  typeface: {
+    card: { title: 'kol-mono-16 text-emphasis', body: 'kol-mono-14 text-fg-64', date: 'kol-mono-12 text-fg-64' },
+    row:  { title: 'kol-mono-14 uppercase text-emphasis', body: 'kol-mono-12 text-fg-64', detail: 'kol-mono-14 text-emphasis', date: 'kol-mono-12 text-fg-64' },
+  },
+}
+
+/* render order per variant/form. Strings are slots; arrays are ONE line:
+ * ['group', …] = 16px baseline group · ['between', …] = header.between ·
+ * ['line', …] = one flex line, first slot flex-1 truncating, rest fixed ·
+ * ['stack', …] = a vertical block on the tight 4px gap, nestable inside any of
+ * the above. In a `between`, the LEADING part flexes and the trailing one hugs.
+ * Directions are the RULED structures (06-content-card-system.md §2 boxes),
+ * read off the shipped components and the live pages they render on. */
+const ORDER = {
+  default:  { card: ['title', ['group', 'date', 'size']], row: ['title', ['group', 'date', 'size']] },
+  catalog:  { card: ['title', 'detail'], row: [['between', 'title', 'detail']] },
+  print:    { card: ['title', 'detail'], row: [['between', 'title', 'detail']] },
+  /* title + body are ONE block in BOTH forms — a `stack`, so they sit on the
+   * tight 4px internal gap while tags, kicker and the meta group keep the
+   * form's own outer gap. A flat column gave every line the same gap, which
+   * read as unrelated lines rather than a heading with its standfirst. */
+  article:  { card: ['tags', 'kicker', ['stack', 'title', 'body'], ['group', 'date', 'size']], row: ['kicker', ['stack', 'title', 'body'], ['group', 'date', 'size']] },
+  /* work CARD = the drawer's two lines: title, then one meta line.
+   *
+   * work ROW = WorkListItem, read off the live /work listing: a LEFT column of
+   * title (small) → tags → description (the big line), and a RIGHT column of
+   * type over year. The big line is the DESCRIPTION, not the title — the
+   * earlier "the fields are crossed, uncross them" reading was wrong, and the
+   * shipped page shows the small-title / big-description order is the design. */
+  /* WorkListItem's inner column is `justify-between` with the header row on
+   * top and the description BELOW IT, spanning the full width — not tucked
+   * inside the left column, which is what squeezed the big line. */
+  work:     { card: ['title', 'meta'], row: [['between', ['stack', 'title', 'tags'], ['stack', 'meta', 'date']], 'body'] },
+  /* typeface row = ONE header line, both sides stacked: name over styles on the
+   * left, classification over year on the right. Verbatim from the shipped
+   * item, which had been flattened into title-left / date-right and lost the
+   * styles line into a body slot below. */
+  typeface: { card: ['title', 'body'], row: [['between', ['stack', 'title', 'body'], ['stack', 'detail', 'date']]] },
+}
+
+/* inner line gap per variant/form, read from the shipped boxes and spelled in
+ * --kol-spacing-* tokens — ALL of them. article's row carried a raw `10px` off
+ * the scale, inherited from the shipped card; once its title and body became a
+ * `stack` this gap stopped separating lines and started separating blocks, so
+ * it sits on the 12px rung the rest of the family uses for that. */
+/* Variants whose ROW text column STRETCHES: the block fills the row's height
+ * and pushes its last child to the floor, so the big line bottom-aligns with
+ * the thumb beside it instead of floating under the header. WorkListItem's
+ * inner column is `flex flex-col justify-between … flex-1`.
+ *
+ * `self-stretch`, NOT `h-full` — the row carries `min-height`, never `height`,
+ * so `height: 100%` resolves against an indefinite parent, computes to auto,
+ * and shrink-wraps the column. Which is exactly what it did. */
+const FILL = { work: true }
+
+/* gap INSIDE a ['stack', …] block. Defaults to the tight 4px pair article
+ * wants; work's header stack is the shipped gap-1 md:gap-2. */
+const STACK = {
+  work: 'var(--kol-spacing-2)',
+  typeface: 'var(--kol-spacing-2)',
+}
+
+const GAPS = {
+  default: { card: 'var(--kol-spacing-3)', row: 'var(--kol-spacing-2)' },
+  catalog: { card: 'var(--kol-spacing-1)', row: 'var(--kol-spacing-2)' },
+  print: { card: 'var(--kol-spacing-2)', row: 'var(--kol-spacing-2)' },
+  article: { card: 'var(--kol-spacing-3)', row: 'var(--kol-spacing-3)' },
+  work: { card: 'var(--kol-spacing-2)', row: 'var(--kol-spacing-4)' },
+  typeface: { card: 'var(--kol-spacing-2)', row: 'var(--kol-spacing-6)' },
+}
+
+export default function ContentText({
+  variant = 'default',
+  form = 'card',
+  title, body, kicker, detail, date, size, meta, tags,
+  gap, clamp,
+  titleClass, bodyClass, kickerClass, detailClass, dateClass, sizeClass, metaClass, tagsClass,
+  className = '',
+}) {
+  const ramp = RAMP[variant]?.[form] ?? RAMP.default[form] ?? RAMP.default.card
+  const order = ORDER[variant]?.[form] ?? ORDER.default.card
+  const values = { title, body, kicker, detail, date, size, meta, tags }
+  const overrides = { title: titleClass, body: bodyClass, kicker: kickerClass, detail: detailClass, date: dateClass, size: sizeClass, meta: metaClass, tags: tagsClass }
+
+  /* the clamp rides the BODY only — it is the one slot that carries prose long
+   * enough to need cutting, and clamping a title is what `truncate` in the ramp
+   * already does on one line. Number in, `line-clamp-N` out; unset = no clamp,
+   * so a card that wants the whole excerpt simply does not pass it. */
+  const extra = (slot) => (slot === 'body' && clamp ? ` line-clamp-${clamp}` : '')
+
+  const line = (slot) =>
+    values[slot] == null ? null : (
+      <div key={slot} className={`${overrides[slot] ?? ramp[slot] ?? ''}${extra(slot)}`.trim()}>{values[slot]}</div>
+    )
+
+  /* RECURSIVE (2026-08-15) — an entry inside a line/between/group may itself be
+   * an entry, so a trailing COLUMN can hold two stacked fields. typeface's row
+   * needs exactly that: classification over year at the right edge, which a
+   * flat slot list cannot express and which was previously collapsed into one
+   * `date` slot that lost a value. */
+  const render = (entry, i) => {
+    if (typeof entry === 'string') return line(entry)
+    const [kind, ...slots] = entry
+    const parts = slots.map((s, j) => render(s, j)).filter(Boolean)
+    if (!parts.length) return null
+    if (kind === 'stack') {
+      return (
+        <div key={`stack-${i}`} className="flex w-full min-w-0 flex-col" style={{ gap: STACK[variant] ?? 'var(--kol-spacing-1)' }}>
+          {parts}
+        </div>
+      )
+    }
+    if (kind === 'line') {
+      /* ruled (default row): title flex-1 truncate · date w-24 · size w-20,
+       * trailing fields in fixed columns so rows align in a list.
+       *
+       * Trailing fields HUG their content and sit on the group's 24px gap, so
+       * the row and the card space their meta identically. They used to be
+       * fixed 96/80px right-aligned columns: the date never filled 96px, so a
+       * row showed leftover column PLUS the gap, and anything that grew on
+       * hover (the size/download affordance) expanded leftwards in a row and
+       * rightwards in a card. */
+      return (
+        <div key={`line-${i}`} className="flex items-baseline min-w-0" style={{ gap: 'var(--kol-spacing-6)' }}>
+          {parts.map((p, j) => (j === 0
+            ? <div key={j} className="flex-1 min-w-0 truncate">{p}</div>
+            : <div key={j} className="shrink-0">{p}</div>))}
+        </div>
+      )
+    }
+    return (
+      <div
+        key={`${kind}-${i}`}
+        /* a `between` whose trailing part is a STACK aligns on the top, not the
+         * baseline — a two-line column has no single baseline to share with the
+         * title beside it, and baseline-aligning it hangs the second line below
+         * the row's floor. */
+        className={`flex min-w-0 ${parts.length > 1 && Array.isArray(slots[slots.length - 1]) ? 'items-center' : 'items-baseline'} ${kind === 'between' ? 'justify-between' : ''}`}
+        style={{ gap: 'var(--kol-spacing-6)' }}
+      >
+        {/* the LEADING part of a `between` takes the room; the trailing column
+          * hugs its content. Without this the left stack sized to its content
+          * and the big line truncated at a quarter of the row's width while
+          * empty space sat between the two columns. */}
+        {kind === 'between' && parts.length > 1
+          ? parts.map((p, j) => (
+              <div key={j} className={j === 0 ? 'min-w-0 flex-1' : 'shrink-0'}>{p}</div>
+            ))
+          : parts}
+      </div>
+    )
+  }
+
+  const nodes = order.map(render)
+
+  return (
+    <div
+      className={`flex min-w-0 flex-col ${FILL[variant] && form === 'row' ? 'self-stretch justify-between' : ''} ${className}`.trim()}
+      style={{ gap: typeof gap === 'number' ? `${gap}px` : gap ?? GAPS[variant]?.[form] ?? 'var(--kol-spacing-2)' }}
+    >
+      {nodes}
+    </div>
+  )
+}

package/src/molecules/CopyButton.jsx

@@ -0,0 +1,41 @@
+import ActionButton from '../atoms/ActionButton.jsx'
+
+/**
+ * CopyButton — 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
+ * Copy/Copied label chip (one-off SVGs outside the icon set) is retired.
+ * Chrome comes from .kol-copy-btn (kol-theme); parents add their own
+ * positioning class (e.g. .kol-frame-control).
+ *
+ * The flip itself moved to ActionButton (2026-08-15) — it was the only
+ * confirm-feedback in the system and it was welded to the clipboard, so no
+ * other in-frame control could acknowledge a click. This is now clipboard
+ * behaviour plus that component; the public API is unchanged, and the swap
+ * gained an animation it never had.
+ *
+ * Props:
+ *   text      — string (or () => string) written to the clipboard
+ *   className — extra classes (positioning etc.)
+ */
+export default function CopyButton({ text, className = '', ...props }) {
+  return (
+    <ActionButton
+      icon="copy"
+      confirmIcon="check"
+      label="Copy to clipboard"
+      confirmLabel="Copied"
+      size="sm"
+      className={className}
+      onAction={async () => {
+        try {
+          await navigator.clipboard.writeText(typeof text === 'function' ? text() : String(text ?? ''))
+        } catch {
+          /* clipboard blocked — silent */
+        }
+      }}
+      {...props}
+    />
+  )
+}

package/src/molecules/EmptyState.jsx

@@ -5,14 +5,22 @@
  * the placeholder name). All lines render as authored — no auto casing
  * (the source's `uppercase` on the eyebrow was dropped per KOL rules).
  *
- * @param {string} eyebrow  kicker line above the title
- * @param {string} title    headline
- * @param {string} body     optional supporting line
- * @param {string} footer   optional note above a top hairline
+ * `gated` (GatedEmptyState, kol-fxr 2026-08-15) opts this instance into the
+ * app-wide placeholder switch — see usePlaceholders(). It is OPT-IN, not the
+ * default, on purpose: the ruling that placeholder prose defaults to hidden is
+ * the filing app's, and flipping it here would silently blank every surface
+ * already shipping an EmptyState. A consumer that wants the gate asks for it.
+ *
+ * @param {string}  eyebrow  kicker line above the title
+ * @param {string}  title    headline
+ * @param {string}  body     optional supporting line
+ * @param {string}  footer   optional note above a top hairline
+ * @param {boolean} gated    hide unless placeholders are switched on (default false)
+ * @param {string}  className extra classes on the wrapper
  */
-export default function EmptyState({ eyebrow, title, body, footer }) {
+export default function EmptyState({ eyebrow, title, body, footer, gated = false, className = '' }) {
   return (
-    <div>
+    <div className={`${gated ? 'kol-placeholder' : ''}${className ? ` ${className}` : ''}` || undefined}>
       {/* helper (line-height 1) is single-line chrome ONLY — title and footer
         * can wrap, so they ride the line-height-bearing kol-mono-* scale
         * (the type-conform fault line; user, 2026-08-09). Eyebrow stays

package/src/molecules/MediaCard.jsx

@@ -69,7 +69,7 @@ export default function MediaCard({
         {thumb}
         {selectMode ? (
           <span
-            className="absolute top-3 left-3 rounded p-1"
+            className="kol-frame-control kol-frame-control--top-left rounded p-1"
             style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
           >
             <SelectIndicator on={selected} />
@@ -79,7 +79,7 @@ export default function MediaCard({
             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"
+            className="kol-frame-control 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()}
           >

package/src/molecules/SearchInput.jsx

@@ -44,7 +44,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 
 const SIZE_TYPE = { sm: 'kol-mono-12', md: 'kol-mono-14' }
 const ICON_SIZE = { sm: 14, md: 14 }
-const CUBIC_EASE = 'cubic-bezier(0.16, 1, 0.3, 1)'
+const CUBIC_EASE = 'var(--kol-ease-house)'
 
 export default function SearchInput({
   value = '',

package/src/molecules/Section.jsx

@@ -3,10 +3,21 @@
  *
  * A small-caps label above a vertical content stack. Used across the editor
  * inspector panels (palette / pattern / type modes): `<Section label="Aspect">…</Section>`.
+ *
+ * `divided` (InspectorSectionRhythm, 2026-08-15) adds the between-siblings
+ * hairline every rail consumer was retyping locally — the rule lives on the
+ * ADJACENT pair (`.kol-section--divided + .kol-section--divided`) in
+ * kol-components-molecules.css, so the first section in a stack never carries
+ * a stray top border. Set it on every section in the stack; a rail that mixes
+ * divided and plain sections divides only between the divided ones.
+ *
+ * ponytail: a `SectionStack` parent could own this instead of each child
+ * declaring it — that is the upgrade path if a consumer ever needs the stack
+ * to vary the rule per-gap. One prop is a smaller API than a new component.
  */
-export default function Section({ label, children, className = '' }) {
+export default function Section({ label, children, divided = false, className = '' }) {
   return (
-    <div className={`flex flex-col gap-2 ${className}`}>
+    <div className={`flex flex-col gap-2${divided ? ' kol-section--divided' : ''} ${className}`}>
       {label && (
         <p className="kol-helper-10 tracking-widest text-meta">{label}</p>
       )}

package/src/organisms/ContentCollection.jsx

@@ -0,0 +1,56 @@
+import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
+
+/**
+ * ContentCollection — the container half of the content-card system: the
+ * grid/list switch plus the motion that belongs to it. Animation lives in
+ * the wrapper — the only place it can (06-content-card-system.md §6);
+ * cards never animate themselves.
+ *
+ * Children are ContentItem / ContentCard / ContentRow (or anything). The
+ * collection owns the enter stagger, keyed to `form` so the switch re-runs
+ * it. Uses the house curve (--kol-ease-house).
+ *
+ * ponytail: form switch re-mounts with a stagger, no FLIP — add FLIP
+ * (measure → invert → play) when a consumer needs card↔row to tween.
+ *
+ * @param {string}  form     'grid' | 'list'
+ * @param {string}  min      grid track minimum (CSS length), grid form only
+ * @param {number}  gap      px between items
+ * @param {boolean} stagger  enter animation on/off (reduced motion wins)
+ */
+export default function ContentCollection({
+  form = 'grid',
+  min = '12rem',
+  gap = 16,
+  stagger = true,
+  children,
+  className = '',
+}) {
+  const reduced = usePrefersReducedMotion()
+  const animate = stagger && !reduced
+  const items = Array.isArray(children) ? children.flat() : [children]
+
+  return (
+    <ul
+      key={form}
+      className={`m-0 list-none p-0 ${className}`.trim()}
+      style={
+        form === 'grid'
+          ? { display: 'grid', gridTemplateColumns: `repeat(auto-fill, minmax(${min}, 1fr))`, gap: `${gap}px` }
+          : { display: 'flex', flexDirection: 'column', gap: `${gap}px` }
+      }
+    >
+      {items.map((child, i) =>
+        child == null ? null : (
+          <li
+            key={child.key ?? i}
+            className={animate ? 'kol-collection-item' : undefined}
+            style={animate ? { animationDelay: `${i * 40}ms` } : undefined}
+          >
+            {child}
+          </li>
+        ),
+      )}
+    </ul>
+  )
+}