@kolkrabbi/kol-component 0.2.0 → 0.4.0

package/src/hooks/useAxisAnimation.js

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import usePrefersReducedMotion from './usePrefersReducedMotion.js'
+
+/**
+ * useAxisAnimation — ping-pong rAF over a variable-font axis range.
+ *
+ * Owns a single numeric value that auto-oscillates between `min` and `max`
+ * (bouncing at each end) while `running` is true, then hands the value + a
+ * setter back to the caller so a slider can scrub it (scrub = call `setValue`,
+ * flip `running` off). This is the reusable core lifted out of the monorepo's
+ * VariableFontSection, whose auto-oscillator was inline and unguarded.
+ *
+ * Timing uses the `performance.now()` interval-accumulator pattern (the same
+ * shape as fontviewer's GlyphAnimator) rather than a `Date.now()` / `delta>16`
+ * throttle — the accumulator carries the sub-interval remainder so the step is
+ * frame-rate independent and doesn't jitter.
+ *
+ * Reduced-motion gate: when the user asks for reduced motion the loop never
+ * mounts and the hook returns its static default (`initial`, else the range
+ * midpoint) — the widget still renders and stays scrubbable, it just doesn't
+ * auto-play. `reduced` is returned so the caller can reflect it in its
+ * play/pause affordance.
+ *
+ * The value is axis-agnostic: the render boundary decides whether it feeds
+ * `fontWeight` (wght) or `font-variation-settings` (wdth/slnt/…).
+ *
+ * @param {Object}  opts
+ * @param {number}  opts.min      - Lower bound of the oscillation + slider min (default 300).
+ * @param {number}  opts.max      - Upper bound of the oscillation + slider max (default 900).
+ * @param {number}  opts.step     - Units advanced per frame (default 2).
+ * @param {number}  opts.fps      - Target frame cadence for the accumulator (default 60).
+ * @param {boolean} opts.running  - Whether the loop is active (default true). Gated by reduced-motion.
+ * @param {number}  opts.initial  - Starting / reduced-motion static value (default range midpoint).
+ * @returns {{ value: number, setValue: (v:number)=>void, reduced: boolean }}
+ */
+export default function useAxisAnimation({
+  min = 300,
+  max = 900,
+  step = 2,
+  fps = 60,
+  running = true,
+  initial,
+} = {}) {
+  const reduced = usePrefersReducedMotion()
+  const staticDefault = initial ?? Math.round((min + max) / 2)
+
+  const [value, setValueState] = useState(staticDefault)
+  const valueRef = useRef(staticDefault)
+  const dirRef = useRef(1)
+  const rafRef = useRef(null)
+
+  // External override (slider scrub). Keeps the ref in sync so a subsequent
+  // resume ping-pongs from where the user left it, not from a stale value.
+  const setValue = useCallback((v) => {
+    valueRef.current = v
+    setValueState(v)
+  }, [])
+
+  useEffect(() => {
+    if (reduced || !running) return
+
+    const interval = 1000 / fps
+    let last = performance.now()
+
+    const animate = (now) => {
+      const elapsed = now - last
+      if (elapsed >= interval) {
+        let next = valueRef.current + dirRef.current * step
+        if (next >= max) {
+          next = max
+          dirRef.current = -1
+        } else if (next <= min) {
+          next = min
+          dirRef.current = 1
+        }
+        valueRef.current = next
+        setValueState(next)
+        // Carry the sub-interval remainder so the cadence stays even.
+        last = now - (elapsed % interval)
+      }
+      rafRef.current = requestAnimationFrame(animate)
+    }
+
+    rafRef.current = requestAnimationFrame(animate)
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current)
+    }
+  }, [reduced, running, min, max, step, fps])
+
+  return { value, setValue, reduced }
+}

package/src/hooks/usePrefersReducedMotion.js

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * True when the user asks for reduced motion. The DS-wide motion gate:
+ * every animated/effect component checks this and renders its static
+ * form when true (the monorepo sources never did — added on recreate).
+ */
+export default function usePrefersReducedMotion() {
+  const [reduced, setReduced] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches,
+  )
+
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)')
+    const onChange = () => setReduced(mq.matches)
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [])
+
+  return reduced
+}

package/src/hooks/useTilt.js

@@ -0,0 +1,49 @@
+import { useRef } from 'react'
+import { useMotionValue, useSpring, useTransform } from 'framer-motion'
+
+/**
+ * Pointer-driven 3D tilt (framer-motion springs) — the ONE tilt hook.
+ * Ported from the monorepo's useBentoTiltMotion; TiltCard, BentoCard and
+ * friends all compose this instead of forking their own.
+ *
+ * Returns `{ ref, style, onMouseMove, onMouseLeave, motionValues }` —
+ * spread `ref`/handlers on a `motion.div` and pass `style` to it.
+ * `motionValues` exposes the raw springs for derived variants
+ * (e.g. TiltCard's `grounded` zone-snapping).
+ *
+ * Defaults are the design: tilt ±4°, spring 350/35, perspective 700,
+ * rest position center (0.5/0.5).
+ */
+export default function useTilt({
+  magnitude = 4,
+  perspective = 700,
+  stiffness = 350,
+  damping = 35,
+} = {}) {
+  const ref = useRef(null)
+  const mouseX = useMotionValue(0.5)
+  const mouseY = useMotionValue(0.5)
+
+  const rotateX = useSpring(useTransform(mouseY, [0, 1], [magnitude, -magnitude]), { stiffness, damping })
+  const rotateY = useSpring(useTransform(mouseX, [0, 1], [-magnitude, magnitude]), { stiffness, damping })
+
+  const onMouseMove = (e) => {
+    const rect = ref.current?.getBoundingClientRect()
+    if (!rect) return
+    mouseX.set((e.clientX - rect.left) / rect.width)
+    mouseY.set((e.clientY - rect.top) / rect.height)
+  }
+
+  const onMouseLeave = () => {
+    mouseX.set(0.5)
+    mouseY.set(0.5)
+  }
+
+  return {
+    ref,
+    style: { rotateX, rotateY, transformStyle: 'preserve-3d', transformPerspective: perspective },
+    onMouseMove,
+    onMouseLeave,
+    motionValues: { mouseX, mouseY, rotateX, rotateY },
+  }
+}

package/src/index.js

@@ -6,7 +6,7 @@
  * lives in @kol/theme (kol-components-*.css).
  *
  * Placement follows the taxonomy rules in
- * docs/taxonomy/01-component-placement.md:
+ * docs/documentation/02-components/02-placement.md:
  *   atom     — nests no KOL component (kol-loader Icon/Graphic are
  *              infrastructure, they don't count)
  *   molecule — nests at least one KOL component
@@ -16,22 +16,33 @@
  */
 
 // atoms
+export { default as AnimatedTitle } from './atoms/AnimatedTitle.jsx'
+export { default as AssetGrid } from './atoms/AssetGrid.jsx'
 export { default as AssetPlaceholder } from './atoms/AssetPlaceholder.jsx'
 export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
 export { default as CopyButton } from './atoms/CopyButton.jsx'
+export { default as CurveOverlay } from './atoms/CurveOverlay.jsx'
 export { default as Divider } from './atoms/Divider.jsx'
+export { default as DocsToc } from './atoms/DocsToc.jsx'
 export { default as DropdownTagFilter } from './atoms/DropdownTagFilter.jsx'
+export { default as EmptyState } from './atoms/EmptyState.jsx'
 export { default as ExitPreview } from './atoms/ExitPreview.jsx'
+export { default as Figure } from './atoms/Figure.jsx'
 export { default as FullscreenOverlay } from './atoms/FullscreenOverlay.jsx'
+export { default as HlsVideo } from './atoms/HlsVideo.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 OverlayGlassPanel } from './atoms/OverlayGlassPanel.jsx'
 export { default as Pill } from './atoms/Pill.jsx'
 export { usePopover, PopoverPanel, Tooltip } from './atoms/Popover.jsx'
+export { default as PriceDisplay } from './atoms/PriceDisplay.jsx'
+export { default as ProsePreview } from './atoms/ProsePreview.jsx'
 export { default as QuantityInput } from './atoms/QuantityInput.jsx'
-export { default as QuantityStepper } from './atoms/QuantityStepper.jsx'
+export { default as RotaryDial } from './atoms/RotaryDial.jsx'
+export { default as SearchInput } from './atoms/SearchInput.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'
@@ -41,14 +52,29 @@ 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 TextPressure } from './atoms/TextPressure.jsx'
+export { default as TiltCard } from './atoms/TiltCard.jsx'
 export { default as TransparentX } from './atoms/TransparentX.jsx'
+export { default as TypeSample } from './atoms/TypeSample.jsx'
+export { default as TypeSpecCard } from './atoms/TypeSpecCard.jsx'
 export { default as ViewToggle } from './atoms/ViewToggle.jsx'
 
 // molecules
 export { Accordion, AccordionPanel } from './molecules/Accordion.jsx'
+/* monorepo sets (P6–P10) — molecule members */
+export { default as AlignmentGrid } from './molecules/AlignmentGrid.jsx'
+export { default as ArticleCard } from './molecules/ArticleCard.jsx'
+export { default as ImageBlock } from './molecules/ImageBlock.jsx'
+export { default as SelectionOverlay } from './molecules/SelectionOverlay.jsx'
+export { default as VideoBlock, getEmbedUrl } from './molecules/VideoBlock.jsx'
+export { default as WorkListItem } from './molecules/WorkListItem.jsx'
+export { default as CardFeatureItem } from './molecules/CardFeatureItem.jsx'
 export { default as CodeBlock } from './molecules/CodeBlock.jsx'
+export { default as ColorInputRow } from './molecules/ColorInputRow.jsx'
+export { default as ColorRamp } from './molecules/ColorRamp.jsx'
 export { default as ColorSwatch } from './molecules/ColorSwatch.jsx'
 export { default as Dropdown } from './molecules/Dropdown.jsx'
+export { default as FramedMediaBand } from './molecules/FramedMediaBand.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'
@@ -56,11 +82,45 @@ export { MenuItem, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } fro
 export { MenuPopover } from './molecules/MenuPopover.jsx'
 export { ModalProvider, useModal } from './molecules/Modal.jsx'
 export { default as PropertyInput } from './molecules/PropertyInput.jsx'
+export { default as ShapeDropdown } from './molecules/ShapeDropdown.jsx'
+export { default as ShellDrawer } from './molecules/ShellDrawer.jsx'
+export { default as ShellSearchOverlay } from './molecules/ShellSearchOverlay.jsx'
 export { default as Slider } from './molecules/Slider.jsx'
+export { default as SpecList } from './molecules/SpecList.jsx'
+export { default as SpectrumControls, HueStrip, SBSquare, WheelTriangle } from './molecules/SpectrumControls.jsx'
+export { default as SwatchControls, SwatchStack, EyedropPick } from './molecules/SwatchControls.jsx'
+export { default as TabsRow } from './molecules/TabsRow.jsx'
 
 // organisms
+/* monorepo sets (P6–P10) — organism members. Foundry members are isolated
+   under the './foundry' subpath (opentype-heavy) — not re-exported here. */
+export { default as ArticleHeader } from './organisms/ArticleHeader.jsx'
+export { default as Canvas, CanvasFrame, PanViewport, CANVAS_VIRTUAL_W, DEFAULT_ASPECTS, CANVAS_DEFAULTS } from './organisms/Canvas.jsx'
+export { default as DiagonalMarqueeRiver } from './organisms/DiagonalMarqueeRiver.jsx'
+export { default as EditorShell } from './organisms/EditorShell.jsx'
+export { default as GalleryCarousel } from './organisms/GalleryCarousel.jsx'
+export { default as ParallaxShelf } from './organisms/ParallaxShelf.jsx'
+export { default as PortableTextRenderer, slugify } from './organisms/PortableTextRenderer.jsx'
+export { default as ProductDetailLayout } from './organisms/ProductDetailLayout.jsx'
+export { default as ScrollDriftGallery } from './organisms/ScrollDriftGallery.jsx'
+export { default as StackHero } from './organisms/StackHero.jsx'
+export { default as WorkCard } from './organisms/WorkCard.jsx'
+export { default as WorkViewToggle } from './organisms/WorkViewToggle.jsx'
+export { default as AsciiCursor } from './organisms/AsciiCursor.jsx'
+export { default as BentoCard } from './organisms/BentoCard.jsx'
 export { default as Carousel } from './organisms/Carousel.jsx'
+export { default as ColorLoader } from './organisms/ColorLoader.jsx'
 export { default as ContentFilters } from './organisms/ContentFilters.jsx'
+export { default as CtaGlobal } from './organisms/CtaGlobal.jsx'
+export { default as ErrorBoundary } from './organisms/ErrorBoundary.jsx'
+export { default as FeatureSplit } from './organisms/FeatureSplit.jsx'
+export { default as FeaturedCarousel } from './organisms/FeaturedCarousel.jsx'
+export { default as FeaturesCardSection } from './organisms/FeaturesCardSection.jsx'
+export { default as FullBleedHero } from './organisms/FullBleedHero.jsx'
+export { default as LoaderOverlay } from './organisms/LoaderOverlay.jsx'
+export { default as MediaViewer } from './organisms/MediaViewer.jsx'
+export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
+export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'
 export { default as Table } from './organisms/Table.jsx'
 
 // loaders (re-export — infrastructure, documented on /docs/loaders)
@@ -70,5 +130,9 @@ export { Icon } from '@kolkrabbi/kol-loader'
 export { default as Graphic, GRAPHICS } from './graphics/Graphic.jsx'
 
 // hooks
+export { default as usePrefersReducedMotion } from './hooks/usePrefersReducedMotion.js'
 export { default as useReveal } from './hooks/useReveal.js'
 export { default as useScrollSpy } from './hooks/useScrollSpy.js'
+export { default as useTilt } from './hooks/useTilt.js'
+export { default as useAxisAnimation } from './hooks/useAxisAnimation.js'
+export { resolveCssVar, resolveCssColor, isLight } from './hooks/cssVar.js'

package/src/molecules/AlignmentGrid.jsx

@@ -0,0 +1,53 @@
+import Button from '../atoms/Button.jsx'
+
+/**
+ * AlignmentGrid — a six-cell alignment row: horizontal start/center/end then
+ * vertical start/center/end, each a quiet icon Button that emits an
+ * `(axis, mode)` alignment intent. Driven off a static config array (the
+ * default 6, overridable via `items`). Presentation only — the consumer wires
+ * `onAlign` to whatever "align these" means in its context (align a box to the
+ * canvas bounds, align a multi-selection's common bbox, …).
+ *
+ * Ported from the brand editor's AlignmentPanel with the store coupling
+ * dropped (per lobby spec): `useComposeState().alignSelected` → an `onAlign`
+ * prop; the hand-rolled `kol-btn-quiet` buttons → DS `Button` (quiet +
+ * iconOnly) so the DS owns the button atom; `EditorIcon` → the DS Icon
+ * (through Button).
+ *
+ * [icon-gap] The source's `align-h-{start,center,end}` / `align-v-{start,
+ * center,end}` glyph names are NOT in the loader. Remapped to the closest
+ * existing loader glyphs (stroke/layout): `align-horizontal-{left,center,
+ * right}` and `align-vertical-{top,center,bottom}`. Same six align marks,
+ * different names — no visual gap.
+ *
+ * @param {(axis:'h'|'v', mode:'start'|'center'|'end') => void} onAlign  fired on cell click
+ * @param {Array} items  [{ axis, mode, icon, title }] cells (default the standard 6)
+ */
+const ALIGN_BUTTONS = [
+  { axis: 'h', mode: 'start',  icon: 'align-horizontal-left',   title: 'Align left' },
+  { axis: 'h', mode: 'center', icon: 'align-horizontal-center', title: 'Align horizontal center' },
+  { axis: 'h', mode: 'end',    icon: 'align-horizontal-right',  title: 'Align right' },
+  { axis: 'v', mode: 'start',  icon: 'align-vertical-top',      title: 'Align top' },
+  { axis: 'v', mode: 'center', icon: 'align-vertical-center',   title: 'Align vertical center' },
+  { axis: 'v', mode: 'end',    icon: 'align-vertical-bottom',   title: 'Align bottom' },
+]
+
+export default function AlignmentGrid({ onAlign, items = ALIGN_BUTTONS }) {
+  return (
+    <div className="grid grid-cols-6 gap-1">
+      {items.map((b) => (
+        <Button
+          key={`${b.axis}-${b.mode}`}
+          quiet
+          iconOnly={b.icon}
+          iconSize={16}
+          onClick={() => onAlign?.(b.axis, b.mode)}
+          title={b.title}
+          aria-label={b.title}
+          className="w-full"
+          style={{ height: 28, padding: 6 }}
+        />
+      ))}
+    </div>
+  )
+}

package/src/molecules/ArticleCard.jsx

@@ -0,0 +1,178 @@
+import Pill from '../atoms/Pill.jsx'
+import Image from './Image.jsx'
+
+/**
+ * Optional link wrapper — the one place routing lives. `http*`/`mailto` hrefs
+ * open in a new tab; any other href renders a plain same-tab anchor with an
+ * `onNavigate(event)` seam an SPA consumer intercepts (preventDefault + its
+ * router). No `href` → the bare content, no anchor.
+ */
+function CardLink({ href, onNavigate, className, children }) {
+  if (!href) return <div className={className}>{children}</div>
+  const isExternal = href.startsWith('http') || href.startsWith('mailto')
+  return (
+    <a
+      href={href}
+      onClick={isExternal ? undefined : onNavigate}
+      target={isExternal ? '_blank' : undefined}
+      rel={isExternal ? 'noreferrer noopener' : undefined}
+      className={className}
+    >
+      {children}
+    </a>
+  )
+}
+
+/** Cover-fit thumbnail (or fg-token placeholder box when no src). */
+function Thumb({ src, alt }) {
+  if (!src) return null
+  return (
+    <Image
+      src={src}
+      alt={alt}
+      className="object-cover"
+      style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+    />
+  )
+}
+
+/**
+ * ArticleCard — one blog-card family with three sizes (`default` / `hero` /
+ * `mini`), collapsing what were three byte-identical duplicate components. All
+ * three share the flat view-model (title, excerpt, thumbnail, tags, meta) and
+ * the link seam; `size` picks the layout.
+ *
+ * - **default** — grid tile: thumbnail (landscape/portrait) over tag Pills, a
+ *   mono title, an excerpt, and a `date • readingTime` meta Pill.
+ * - **hero** — index masthead: an optional header row (`label` + `meta`),
+ *   a big 16/9 image that zooms on hover, then kicker → title → summary.
+ * - **mini** — sidebar row: a fixed 120×120 thumbnail beside title → summary →
+ *   meta.
+ *
+ * De-Sanitized flat props, no router import. Placeholder thumbnails use
+ * fg-opacity tokens (theme-aware — no `.dark` style injection). Every string
+ * is authored at the call site in its final case — no `text-transform`, no JS
+ * casing (the kicker/meta `uppercase` are presentational classes only).
+ *
+ * @param {'default'|'hero'|'mini'} size  layout preset (default 'default')
+ * @param {string}   title       card title
+ * @param {string}   excerpt     summary/excerpt paragraph (alias: `summary`)
+ * @param {string}   summary     alias for `excerpt` (hero/mini call it this)
+ * @param {string}   kicker      hero-only eyebrow above the title
+ * @param {string}   label       hero header label (was the hardcoded "Featured")
+ * @param {string[]} meta        hero header chips / mini meta line (joined ` • `)
+ * @param {string}   date        default meta — left of the `•`
+ * @param {string}   readingTime default meta — right of the `•`
+ * @param {string[]} tags        default: rendered as Pills; hero/mini: `data-tags` only
+ * @param {string}   thumbnail   image src (omit → fg-token placeholder)
+ * @param {'landscape'|'portrait'} aspect  default thumbnail ratio (default 'landscape')
+ * @param {boolean}  showHeader  hero: show the label/meta header row (default true)
+ * @param {string}   href        link target; `http*`/`mailto` → new tab, else same-tab seam
+ * @param {Function} onNavigate  (event) => void — same-tab click seam (SPA intercept)
+ * @param {string}   className   extra classes on the root
+ */
+export default function ArticleCard({
+  size = 'default',
+  title,
+  excerpt,
+  summary,
+  kicker,
+  label,
+  meta,
+  date,
+  readingTime,
+  tags = [],
+  thumbnail,
+  aspect = 'landscape',
+  showHeader = true,
+  href,
+  onNavigate,
+  className = '',
+}) {
+  const body = excerpt ?? summary
+  const dataTags = tags?.length ? tags.join(' ') : undefined
+
+  if (size === 'hero') {
+    return (
+      <CardLink href={href} onNavigate={onNavigate} className={`block group ${className}`.trim()}>
+        <article className="w-full" data-tags={dataTags}>
+          {showHeader && (label || meta?.length) && (
+            <div className="flex justify-between items-center mb-4">
+              {label && <div className="kol-helper-14 text-fg-64">{label}</div>}
+              {meta?.length > 0 && (
+                <div className="flex gap-3 kol-helper-12 text-fg-48">
+                  {meta.map((item, i) => <span key={i}>{item}</span>)}
+                </div>
+              )}
+            </div>
+          )}
+          <div className="aspect-[16/9] mb-4 overflow-hidden w-full bg-fg-04 border border-fg-08 hover:border-fg-16 rounded">
+            {thumbnail && (
+              <Image
+                src={thumbnail}
+                alt={title}
+                className="object-cover transition-transform duration-300 group-hover:scale-105"
+                style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+              />
+            )}
+          </div>
+          <div className="space-y-3">
+            {kicker && (
+              <div className="kol-helper-16 uppercase tracking-wide text-fg-64">{kicker}</div>
+            )}
+            <h2 className="kol-sans-heading-03 transition-opacity duration-200 group-hover:opacity-70 line-clamp-2">
+              {title}
+            </h2>
+            {body && <p className="kol-mono-14 text-fg-48 line-clamp-3">{body}</p>}
+          </div>
+        </article>
+      </CardLink>
+    )
+  }
+
+  if (size === 'mini') {
+    const metaText = Array.isArray(meta) ? meta.join(' • ') : meta
+    return (
+      <CardLink
+        href={href}
+        onNavigate={onNavigate}
+        className={`group flex gap-6 items-start transition-opacity hover:opacity-80 ${className}`.trim()}
+      >
+        <div className="flex-shrink-0 w-[120px] h-[120px] overflow-hidden rounded bg-fg-12" data-tags={dataTags}>
+          <Thumb src={thumbnail} alt={title} />
+        </div>
+        <div className="flex-1 min-w-0 flex flex-col gap-2.5">
+          <h4 className="kol-mono-14 line-clamp-2 transition-opacity group-hover:opacity-80">{title}</h4>
+          {body && <p className="kol-mono-14 text-fg-64 line-clamp-2">{body}</p>}
+          {metaText && <div className="kol-helper-12 text-fg-80 uppercase">{metaText}</div>}
+        </div>
+      </CardLink>
+    )
+  }
+
+  // size === 'default'
+  return (
+    <CardLink href={href} onNavigate={onNavigate} className={`block group cursor-pointer w-full max-w-full ${className}`.trim()}>
+      <article className="w-full max-w-full" data-tags={dataTags}>
+        <div
+          className="mb-4 overflow-hidden w-full rounded bg-fg-04 border border-fg-08"
+          style={{ aspectRatio: aspect === 'portrait' ? '3/4' : '16/9' }}
+        >
+          <Thumb src={thumbnail} alt={title} />
+        </div>
+        {tags.length > 0 && (
+          <div className="flex flex-wrap gap-2 mb-2">
+            {tags.map((tag, i) => (
+              <Pill key={i} variant="inverse" size="sm">{tag}</Pill>
+            ))}
+          </div>
+        )}
+        <h3 className="mb-2 kol-mono-20 transition-opacity duration-200 group-hover:opacity-70">{title}</h3>
+        {body && <p className="mb-2 kol-mono-14 text-fg-64">{body}</p>}
+        {(date || readingTime) && (
+          <Pill variant="subtle" size="sm">{[date, readingTime].filter(Boolean).join(' • ')}</Pill>
+        )}
+      </article>
+    </CardLink>
+  )
+}

package/src/molecules/CardFeatureItem.jsx

@@ -0,0 +1,130 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: nests only kol-loader's Icon (a package import the
+ * relative-import check can't see). */
+
+/**
+ * CardFeatureItem — fixed-height feature card: a title + optional icon
+ * header, a flexible visual middle, and a mono description footer. The
+ * card's visual is polymorphic: an `.svg` URL string renders as a
+ * `mask-image` block tinted with `currentColor` (theme-correct line-art),
+ * any other string renders as a cover-fit `<img>`, a ReactNode renders
+ * as-is, and no visual falls back to a large 96px `Icon` (the header's
+ * `icon` name). The grid child of FeaturesCardSection.
+ *
+ * Optionally the whole card is a link. `http*` / `mailto` hrefs open in a
+ * new tab; any other href renders a plain same-tab anchor with an
+ * `onNavigate(event)` seam — an SPA consumer intercepts there
+ * (preventDefault + its router) instead of this component importing one.
+ *
+ * Title and description render exactly as authored — no casing transforms;
+ * author strings in their final case at the call site.
+ *
+ * @param {ReactNode} title            header heading (kol-helper-16)
+ * @param {string}    icon             Icon name for the header (16px); also the 96px no-visual fallback
+ * @param {string|ReactNode} visual    image URL, `.svg` mask URL, or inline node
+ * @param {ReactNode} description      footer line (kol-mono-12, muted)
+ * @param {string}    backgroundColor  card background utility class
+ * @param {string}    href             link target; `http*`/`mailto` → new tab, else plain same-tab anchor
+ * @param {Function}  onNavigate       (event) => void — click seam on the same-tab anchor (SPA intercept)
+ * @param {'auto'|'9/6'|'10/6'|'16/9'|'1/1'} imageAspectRatio  aspect class on the visual middle
+ * @param {string}    imagePosition    `<img>` object-position
+ */
+export default function CardFeatureItem({
+  title,
+  icon,
+  visual,
+  description,
+  backgroundColor = 'bg-surface-primary',
+  href,
+  onNavigate,
+  imageAspectRatio = 'auto',
+  imagePosition = 'center',
+}) {
+  const isSvgUrl = typeof visual === 'string' && visual.endsWith('.svg')
+
+  const aspectClasses = {
+    'auto': '',
+    '9/6': 'aspect-[9/6]',
+    '10/6': 'aspect-[10/6]',
+    '16/9': 'aspect-video',
+    '1/1': 'aspect-square',
+  }
+  const aspectClass = aspectClasses[imageAspectRatio] || ''
+
+  const content = (
+    <>
+      <div className="w-full flex items-center justify-between gap-2">
+        <h3 className="kol-helper-16">{title}</h3>
+        {icon && <Icon name={icon} size={16} className="shrink-0" />}
+      </div>
+
+      <div className={`w-full flex-1 flex items-center justify-center overflow-hidden ${aspectClass}`.trim()}>
+        {visual ? (
+          typeof visual === 'string' ? (
+            isSvgUrl ? (
+              /* currentColor line-art: the SVG paints as a mask over bg-current */
+              <div
+                className="w-full h-full bg-current rounded"
+                style={{
+                  maskImage: `url(${visual})`,
+                  maskSize: 'contain',
+                  maskRepeat: 'no-repeat',
+                  maskPosition: 'center',
+                  WebkitMaskImage: `url(${visual})`,
+                  WebkitMaskSize: 'contain',
+                  WebkitMaskRepeat: 'no-repeat',
+                  WebkitMaskPosition: 'center',
+                }}
+              />
+            ) : (
+              <img
+                src={visual}
+                alt={typeof title === 'string' ? title : ''}
+                className="w-full h-full object-cover rounded"
+                style={{ objectPosition: imagePosition }}
+              />
+            )
+          ) : (
+            visual
+          )
+        ) : (
+          <Icon name={icon} size={96} />
+        )}
+      </div>
+
+      <p className="kol-mono-12 text-fg-48">{description}</p>
+    </>
+  )
+
+  const baseClasses = `w-full flex-1 h-[304px] md:h-72 p-4 md:p-6 gap-4 ${backgroundColor} rounded border border-fg-08 flex flex-col justify-between items-start overflow-hidden`
+
+  if (href) {
+    const isExternal = href.startsWith('http') || href.startsWith('mailto')
+
+    if (isExternal) {
+      return (
+        <a
+          href={href}
+          className={`${baseClasses} hover:border-fg-32 transition-colors duration-300`}
+          target="_blank"
+          rel="noreferrer noopener"
+        >
+          {content}
+        </a>
+      )
+    }
+
+    return (
+      <a
+        href={href}
+        onClick={onNavigate}
+        className={`${baseClasses} hover:border-fg-24 transition-colors duration-300`}
+      >
+        {content}
+      </a>
+    )
+  }
+
+  return <div className={baseClasses}>{content}</div>
+}