@kolkrabbi/kol-foundry 0.2.0 → 0.4.0

package/README.md

@@ -13,6 +13,10 @@ The KOL **type-foundry system** — the type-specimen apparatus, lifted out of `
 | `TypefaceStyleSection` | per-style specimen block |
 | `FontPreviewSection` | size-ladder / preview control |
 | `SpecimenSectionHeader` | shared section header |
+| `TypeSample` | labeled live type-specimen block (props-driven) |
+| `TypeSpecCard` | font-metric data sheet + live sample slot |
+| `TextPressure` | variable-font glyphs deforming toward the pointer |
+| `ColorLoader` | branded loading curtain with a live variable-font wordmark |
 | `glyphSets`, `glyphCategories`, `SPECIMEN_SAMPLE_TEXT` | glyph data |
 
 ```js
@@ -21,4 +25,4 @@ import { TypefaceHero, VariableFontSection } from '@kolkrabbi/kol-foundry'
 
 ## Requirements
 
-Components take flat prop bags — typeface metrics / font files are consumer-supplied. Shared primitives (`Tag`, `Pill`, `Slider`, `Button`, `Divider`, `Dropdown`, `useAxisAnimation`) stay in `@kolkrabbi/kol-component`; this package depends on them. Styling comes from `@kolkrabbi/kol-theme`. Vite + Tailwind v4 consumer (`@source "…/node_modules/@kolkrabbi/kol-foundry/src"`).
+Components take flat prop bags — typeface metrics / font files are consumer-supplied. Shared primitives (`Tag`, `Pill`, `Slider`, `Button`, `Divider`, `Dropdown`, `useAxisAnimation`, `usePrefersReducedMotion`) stay in `@kolkrabbi/kol-component`; this package depends on them. `framer-motion` is a peer (`ColorLoader`). Styling comes from `@kolkrabbi/kol-theme`. Vite + Tailwind v4 consumer (`@source "…/node_modules/@kolkrabbi/kol-foundry/src"` — Tailwind skips `node_modules` when scanning, so without this line the specimen layouts never generate).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-foundry",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "KOL foundry component set — the type-specimen apparatus: typeface hero, variable-font axis playground, parsed-metric glyph inspector, character-set browser, font-preview, and the typeface-catalog grid. Every component renders, inspects, or manipulates a live font. Typeface data is consumer-injected. Sits above @kolkrabbi/kol-{theme,icons,component}.",
   "license": "MIT",
@@ -11,13 +11,14 @@
     ".": "./src/index.js"
   },
   "dependencies": {
-    "@kolkrabbi/kol-theme": "0.7.1",
-    "@kolkrabbi/kol-component": "0.7.0",
-    "@kolkrabbi/kol-icons": "0.5.0"
+    "@kolkrabbi/kol-component": "0.9.0",
+    "@kolkrabbi/kol-icons": "0.5.0",
+    "@kolkrabbi/kol-theme": "0.7.4"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
+    "framer-motion": "^12.0.0",
     "opentype.js": "^1.3.4"
   },
   "peerDependenciesMeta": {

package/src/ColorLoader.jsx

@@ -0,0 +1,155 @@
+import { motion as Motion, useAnimationControls } from 'framer-motion'
+import { useEffect, useRef, useState } from 'react'
+import { usePrefersReducedMotion } from '@kolkrabbi/kol-component'
+import TextPressure from './TextPressure.jsx'
+
+/**
+ * ColorLoader — a full-height branded intro/loading curtain. Fills its parent
+ * on a solid backdrop, times in a variable-font wordmark (a live TextPressure
+ * effect) after `wordmarkDelay`, then reveals a bouncing down-chevron cue after
+ * `scrollDelay`. With `dismissOnClick`, clicking the curtain slides the whole
+ * thing up out of view and fires `onComplete`; otherwise the parent owns
+ * dismissal (unmount when its work is done). Generalized from the app's
+ * KOLKRABBI loader: the cursor trail, `cursor: none`, and window-scroll/keyboard
+ * gesture hijack are all dropped — exit is a plain click or parent-driven.
+ *
+ * Reduced motion → no timers, no tweens: one static frame (wordmark + cue shown
+ * at rest) and `onComplete` fires immediately on mount, so the curtain never
+ * makes a reduced-motion user wait.
+ *
+ * The wordmark needs a variable font — see TextPressure's font contract. Pass
+ * `fontFamily` / `fontUrl` to point at the KOL variable font (a consumer asset).
+ *
+ * @param {string}    text           wordmark string fed to TextPressure
+ * @param {string}    fontFamily     wordmark font family (→ TextPressure)
+ * @param {string}    [fontUrl]      variable-font URL → TextPressure @font-face
+ * @param {() => void} onComplete    fired after the exit slide-up (or at once, reduced)
+ * @param {boolean}   dismissOnClick click the curtain to slide up + complete
+ * @param {string}    bgColor        backdrop color (KOL token / CSS color)
+ * @param {string}    markColor      wordmark + chevron color (KOL token / CSS color)
+ * @param {number}    wordmarkDelay  ms before the wordmark fades in
+ * @param {number}    scrollDelay    ms before the chevron cue reveals
+ * @param {number}    exitDuration   seconds for the slide-up exit tween
+ */
+export default function ColorLoader({
+  text = 'KOLKRABBI',
+  fontFamily = 'var(--kol-font-family-sans)',
+  fontUrl,
+  onComplete,
+  dismissOnClick = false,
+  bgColor = 'var(--kol-surface-primary)',
+  markColor = 'var(--kol-fg-emphasis)',
+  wordmarkDelay = 1000,
+  scrollDelay = 2000,
+  exitDuration = 1.8,
+}) {
+  const reducedMotion = usePrefersReducedMotion()
+  const [showMark, setShowMark] = useState(reducedMotion)
+  const [showCue, setShowCue] = useState(reducedMotion)
+  const [exiting, setExiting] = useState(false)
+  const controls = useAnimationControls()
+  const firedRef = useRef(false)
+
+  const fireComplete = () => {
+    if (firedRef.current) return
+    firedRef.current = true
+    onComplete?.()
+  }
+
+  useEffect(() => {
+    if (reducedMotion) {
+      // Skip the whole sequence: static frame, signal done at once.
+      setShowMark(true)
+      setShowCue(true)
+      fireComplete()
+      return undefined
+    }
+    const markTimer = setTimeout(() => setShowMark(true), wordmarkDelay)
+    const cueTimer = setTimeout(() => setShowCue(true), scrollDelay)
+    return () => {
+      clearTimeout(markTimer)
+      clearTimeout(cueTimer)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reducedMotion, wordmarkDelay, scrollDelay])
+
+  const dismiss = () => {
+    if (exiting) return
+    setExiting(true)
+    if (reducedMotion) {
+      fireComplete()
+      return
+    }
+    controls
+      .start({ y: '-100%', transition: { duration: exitDuration, ease: 'easeInOut' } })
+      .then(fireComplete)
+  }
+
+  return (
+    <Motion.div
+      className={`flex h-full w-full flex-col ${dismissOnClick ? 'cursor-pointer' : ''}`}
+      style={{ backgroundColor: bgColor }}
+      animate={controls}
+      initial={{ y: 0 }}
+      onClick={dismissOnClick ? dismiss : undefined}
+    >
+      {/* Top third — spacer */}
+      <div className="flex flex-1 items-end justify-center self-stretch" />
+
+      {/* Middle third — wordmark + cue */}
+      <div className="flex flex-1 flex-col items-center justify-center gap-12 self-stretch">
+        <Motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: showMark ? 1 : 0 }}
+          transition={{ duration: reducedMotion ? 0 : 0.5 }}
+          className="w-full px-6"
+        >
+          <div className="mx-auto h-20 w-full max-w-[280px] sm:h-24 sm:max-w-[400px] md:h-32 md:max-w-[600px]">
+            <TextPressure
+              text={text}
+              fontFamily={fontFamily}
+              fontUrl={fontUrl}
+              textColor={markColor}
+              flex
+              width
+              weight
+              italic={false}
+              minFontSize={40}
+            />
+          </div>
+        </Motion.div>
+
+        <Motion.div
+          initial={{ opacity: 0, y: 0 }}
+          animate={{
+            opacity: showCue ? 0.6 : 0,
+            y: showCue && !reducedMotion ? [0, 12, 0] : 0,
+          }}
+          transition={{
+            opacity: { duration: reducedMotion ? 0 : 0.5 },
+            y: reducedMotion ? { duration: 0 } : { duration: 1.5, repeat: Infinity, ease: 'easeInOut' },
+          }}
+          className="mt-12"
+          style={{ color: markColor }}
+        >
+          <svg
+            width="32"
+            height="32"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <polyline points="6 9 12 15 18 9" />
+          </svg>
+        </Motion.div>
+      </div>
+
+      {/* Bottom third — spacer */}
+      <div className="flex flex-1 items-end justify-center self-stretch" />
+    </Motion.div>
+  )
+}

package/src/TextPressure.jsx

@@ -0,0 +1,331 @@
+import { useEffect, useRef, useState } from 'react'
+import { usePrefersReducedMotion } from '@kolkrabbi/kol-component'
+
+// Variable-font axis rest values — where every glyph sits with no pointer near.
+const DEFAULTS = { wdth: 100, wght: 400, ital: 0, alpha: 1 }
+const STATIC_VARIATION = "'wght' 400, 'wdth' 100, 'ital' 0.00"
+
+/**
+ * TextPressure — a single line of variable-font text whose glyphs deform
+ * toward the pointer: characters nearest the cursor grow widest / heaviest /
+ * most italic, and the effect falls off linearly with distance. A
+ * requestAnimationFrame loop lerps a smoothed follower toward the raw cursor
+ * (container-scoped listeners) and writes per-glyph `font-variation-settings`
+ * each frame. On mouse-leave the glyphs coast back to their rest axis values
+ * (`returnToDefault`) or freeze in place, then the loop auto-stops until the
+ * pointer returns. Ported from the react-bits / JuanFuentes effect, collapsed
+ * from three source variants into one.
+ *
+ * ── Font contract ──────────────────────────────────────────────────────────
+ * The effect only *moves* if the resolved font is a VARIABLE font exposing the
+ * `wght` / `wdth` / `ital` axes. The KOL variable font is a CONSUMER asset —
+ * the design system does not ship one. Two ways to supply it:
+ *   • `fontUrl` given → an `@font-face` is injected at runtime for `fontFamily`
+ *     (e.g. fontFamily="TG Root-Tune" fontUrl="/fonts/TGRoot-TuneVF.ttf").
+ *   • `fontUrl` omitted → the already-loaded `fontFamily` is used as-is; the
+ *     default `var(--kol-font-family-sans)` animates only if that theme font is
+ *     itself variable — otherwise the text renders correctly but static.
+ *
+ * Reduced motion → no listeners, no rAF; glyphs render static at the rest axis
+ * values (wght 400 / wdth 100 / ital 0). Casing is authored by the caller —
+ * this component never text-transforms.
+ *
+ * @param {string}  text          the line; split into one <span> per character
+ * @param {string}  fontFamily    applied family + injected @font-face family
+ * @param {string}  [fontUrl]     variable-font URL → injects @font-face when set
+ * @param {boolean} width         animate the `wdth` axis (5–150)
+ * @param {boolean} weight        animate the `wght` axis (100–900)
+ * @param {boolean} italic        animate the `ital` axis (0–1)
+ * @param {boolean} alpha         animate per-glyph opacity (0–1)
+ * @param {boolean} flex          distribute glyphs with justify-between
+ * @param {boolean} stroke        add an outlined ghost layer behind each glyph
+ * @param {boolean} scale         vertically scale the line to fill the container
+ * @param {string}  textColor     glyph color (KOL token / CSS color)
+ * @param {string}  strokeColor   stroke color when `stroke` is on
+ * @param {string}  className     extra classes on the <h1>
+ * @param {number}  minFontSize   floor for the responsive font size
+ * @param {number}  [maxFontSize] cap for the responsive font size
+ * @param {boolean} returnToDefault true: coast back to rest on leave; false: freeze
+ */
+export default function TextPressure({
+  text = 'Compressa',
+  fontFamily = 'var(--kol-font-family-sans)',
+  fontUrl,
+
+  width = true,
+  weight = true,
+  italic = true,
+  alpha = false,
+
+  flex = true,
+  stroke = false,
+  scale = false,
+
+  textColor = 'var(--kol-fg-emphasis)',
+  strokeColor = 'var(--kol-accent-primary)',
+  className = '',
+
+  minFontSize = 24,
+  maxFontSize = null,
+  returnToDefault = true,
+}) {
+  const containerRef = useRef(null)
+  const titleRef = useRef(null)
+  const spansRef = useRef([])
+
+  const mouseRef = useRef({ x: 0, y: 0 })
+  const cursorRef = useRef({ x: 0, y: 0 })
+  const currentValuesRef = useRef([])
+  const velocityRef = useRef([])
+
+  const [fontSize, setFontSize] = useState(minFontSize)
+  const [scaleY, setScaleY] = useState(1)
+  const [lineHeight, setLineHeight] = useState(1)
+  const [isHovering, setIsHovering] = useState(false)
+
+  const reducedMotion = usePrefersReducedMotion()
+  const chars = text.split('')
+
+  const dist = (a, b) => {
+    const dx = b.x - a.x
+    const dy = b.y - a.y
+    return Math.sqrt(dx * dx + dy * dy)
+  }
+
+  // Container-scoped pointer tracking (never window). Skipped for reduced motion.
+  useEffect(() => {
+    if (reducedMotion) return undefined
+    const container = containerRef.current
+    if (!container) return undefined
+
+    const handleMouseMove = (e) => {
+      cursorRef.current.x = e.clientX
+      cursorRef.current.y = e.clientY
+    }
+    const handleTouchMove = (e) => {
+      const t = e.touches[0]
+      cursorRef.current.x = t.clientX
+      cursorRef.current.y = t.clientY
+    }
+    const handleMouseEnter = () => setIsHovering(true)
+    const handleMouseLeave = () => setIsHovering(false)
+
+    container.addEventListener('mousemove', handleMouseMove)
+    container.addEventListener('touchmove', handleTouchMove, { passive: false })
+    container.addEventListener('mouseenter', handleMouseEnter)
+    container.addEventListener('mouseleave', handleMouseLeave)
+
+    const { left, top, width: w, height: h } = container.getBoundingClientRect()
+    mouseRef.current.x = left + w / 2
+    mouseRef.current.y = top + h / 2
+    cursorRef.current.x = mouseRef.current.x
+    cursorRef.current.y = mouseRef.current.y
+
+    return () => {
+      container.removeEventListener('mousemove', handleMouseMove)
+      container.removeEventListener('touchmove', handleTouchMove)
+      container.removeEventListener('mouseenter', handleMouseEnter)
+      container.removeEventListener('mouseleave', handleMouseLeave)
+    }
+  }, [reducedMotion])
+
+  // Responsive sizing (layout, not motion — runs regardless of reduced motion).
+  useEffect(() => {
+    const setSize = () => {
+      if (!containerRef.current || !titleRef.current) return
+      const { width: containerW, height: containerH } = containerRef.current.getBoundingClientRect()
+
+      let newFontSize = containerW / (chars.length / 2)
+      newFontSize = Math.max(newFontSize, minFontSize)
+      if (maxFontSize) newFontSize = Math.min(newFontSize, maxFontSize)
+
+      setFontSize(newFontSize)
+      setScaleY(1)
+      setLineHeight(1)
+
+      requestAnimationFrame(() => {
+        if (!titleRef.current) return
+        const textRect = titleRef.current.getBoundingClientRect()
+        if (scale && textRect.height > 0) {
+          const yRatio = containerH / textRect.height
+          setScaleY(yRatio)
+          setLineHeight(yRatio)
+        }
+      })
+    }
+
+    setSize()
+    window.addEventListener('resize', setSize)
+    return () => window.removeEventListener('resize', setSize)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [scale, text, minFontSize, maxFontSize])
+
+  // The pressure loop. Skipped entirely for reduced motion (glyphs stay static).
+  useEffect(() => {
+    if (reducedMotion) return undefined
+    let rafId
+
+    const animate = () => {
+      if (isHovering) {
+        mouseRef.current.x += (cursorRef.current.x - mouseRef.current.x) / 15
+        mouseRef.current.y += (cursorRef.current.y - mouseRef.current.y) / 15
+
+        if (titleRef.current && containerRef.current) {
+          const containerRect = containerRef.current.getBoundingClientRect()
+          const maxDist = containerRect.width / 2
+
+          spansRef.current.forEach((span, i) => {
+            if (!span) return
+            const rect = span.getBoundingClientRect()
+            const charCenter = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 }
+            const d = dist(mouseRef.current, charCenter)
+
+            const getAttr = (distance, minVal, maxVal) => {
+              const val = maxVal - Math.abs((maxVal * distance) / maxDist)
+              return Math.max(minVal, val + minVal)
+            }
+
+            const wdth = width ? Math.floor(getAttr(d, 5, 150)) : 100
+            const wght = weight ? Math.floor(getAttr(d, 100, 900)) : 400
+            const italVal = italic ? getAttr(d, 0, 1) : 0
+            const alphaVal = alpha ? getAttr(d, 0, 1) : 1
+
+            const prev = currentValuesRef.current[i]
+            if (prev && !returnToDefault) {
+              velocityRef.current[i] = {
+                wdth: wdth - prev.wdth,
+                wght: wght - prev.wght,
+                ital: italVal - prev.ital,
+                alpha: alphaVal - prev.alpha,
+              }
+            }
+            currentValuesRef.current[i] = { wdth, wght, ital: italVal, alpha: alphaVal }
+
+            span.style.opacity = alphaVal
+            span.style.fontVariationSettings = `'wght' ${wght}, 'wdth' ${wdth}, 'ital' ${italVal.toFixed(2)}`
+          })
+        }
+      } else {
+        // Coast back to rest (returnToDefault) or settle into a frozen pose.
+        let allSettled = true
+
+        spansRef.current.forEach((span, i) => {
+          if (!span) return
+          const current = currentValuesRef.current[i] || { ...DEFAULTS }
+          if (!velocityRef.current[i]) velocityRef.current[i] = { wdth: 0, wght: 0, ital: 0, alpha: 0 }
+          const velocity = velocityRef.current[i]
+
+          if (returnToDefault) {
+            const springStrength = 0.05
+            const damping = 0.88
+            velocity.wdth += (DEFAULTS.wdth - current.wdth) * springStrength
+            velocity.wght += (DEFAULTS.wght - current.wght) * springStrength
+            velocity.ital += (DEFAULTS.ital - current.ital) * springStrength
+            velocity.alpha += (DEFAULTS.alpha - current.alpha) * springStrength
+            velocity.wdth *= damping
+            velocity.wght *= damping
+            velocity.ital *= damping
+            velocity.alpha *= damping
+
+            const newWdth = current.wdth + velocity.wdth
+            const newWght = current.wght + velocity.wght
+            const newItal = current.ital + velocity.ital
+            const newAlpha = current.alpha + velocity.alpha
+
+            if (
+              Math.abs(newWdth - DEFAULTS.wdth) > 0.5 ||
+              Math.abs(newWght - DEFAULTS.wght) > 0.5 ||
+              Math.abs(velocity.wdth) > 0.1 ||
+              Math.abs(velocity.wght) > 0.1
+            ) {
+              allSettled = false
+            }
+
+            currentValuesRef.current[i] = { wdth: newWdth, wght: newWght, ital: newItal, alpha: newAlpha }
+            span.style.opacity = newAlpha
+            span.style.fontVariationSettings = `'wght' ${Math.round(newWght)}, 'wdth' ${Math.round(newWdth)}, 'ital' ${newItal.toFixed(2)}`
+          } else {
+            const damping = 0.75
+            velocity.wdth *= damping
+            velocity.wght *= damping
+            velocity.ital *= damping
+            velocity.alpha *= damping
+
+            const newWdth = current.wdth + velocity.wdth
+            const newWght = current.wght + velocity.wght
+            const newItal = current.ital + velocity.ital
+            const newAlpha = current.alpha + velocity.alpha
+
+            if (
+              Math.abs(velocity.wdth) > 0.01 ||
+              Math.abs(velocity.wght) > 0.01 ||
+              Math.abs(velocity.ital) > 0.0001 ||
+              Math.abs(velocity.alpha) > 0.0001
+            ) {
+              allSettled = false
+            }
+
+            currentValuesRef.current[i] = { wdth: newWdth, wght: newWght, ital: newItal, alpha: newAlpha }
+            span.style.opacity = newAlpha
+            span.style.fontVariationSettings = `'wght' ${Math.round(newWght)}, 'wdth' ${Math.round(newWdth)}, 'ital' ${newItal.toFixed(2)}`
+          }
+        })
+
+        if (allSettled) {
+          cancelAnimationFrame(rafId)
+          return
+        }
+      }
+
+      rafId = requestAnimationFrame(animate)
+    }
+
+    animate()
+    return () => cancelAnimationFrame(rafId)
+  }, [width, weight, italic, alpha, chars.length, isHovering, returnToDefault, reducedMotion])
+
+  const titleClass = [
+    'kol-text-pressure-title m-0 w-full max-w-full overflow-hidden box-border text-center whitespace-nowrap select-none origin-top font-thin',
+    flex ? 'flex justify-between' : '',
+    stroke ? 'kol-text-pressure--stroke' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <div
+      ref={containerRef}
+      className="kol-text-pressure relative flex h-full w-full max-w-full items-center justify-center overflow-hidden"
+    >
+      {fontUrl && (
+        <style>{`@font-face { font-family: '${fontFamily}'; src: url('${fontUrl}'); font-style: normal; }`}</style>
+      )}
+
+      <h1
+        ref={titleRef}
+        className={titleClass}
+        style={{
+          fontFamily,
+          fontSize,
+          lineHeight,
+          transform: `scale(1, ${scaleY})`,
+          color: textColor,
+          '--kol-text-pressure-stroke': strokeColor,
+        }}
+      >
+        {chars.map((char, i) => (
+          <span
+            key={i}
+            ref={(el) => (spansRef.current[i] = el)}
+            data-char={char}
+            className="kol-text-pressure-char inline-block"
+            style={{ fontVariationSettings: STATIC_VARIATION }}
+          >
+            {char}
+          </span>
+        ))}
+      </h1>
+    </div>
+  )
+}

package/src/TypeSample.jsx

@@ -0,0 +1,50 @@
+/**
+ * TypeSample — a single labeled type-specimen block: an optional mono caption
+ * over one paragraph whose typography is driven entirely by props via inline
+ * style. The atomic unit of the type-specimen kit — stack several to show a
+ * scale, a weight range, or a family; adjacent samples get a hairline
+ * separator (`.kol-type-sample + .kol-type-sample`).
+ *
+ * Presentational — arbitrary px values are the point, so props map to inline
+ * style rather than fixed kol-* size stops. Label and children render
+ * verbatim as authored.
+ *
+ * @param {string}    family     font family name (wrapped as `"family", sans-serif`); defaults to the KOL sans token
+ * @param {number}    weight     font-weight
+ * @param {boolean}   italic     italic sample
+ * @param {number}    size       font-size in px
+ * @param {number}    lineHeight line-height in px; unitless 1.2 when unset
+ * @param {string}    label      mono caption above the sample (omit to hide)
+ * @param {ReactNode} children   the specimen text itself
+ */
+export default function TypeSample({
+  family,
+  weight = 400,
+  italic = false,
+  size = 32,
+  lineHeight,
+  label,
+  children,
+}) {
+  return (
+    <div className="kol-type-sample py-6">
+      {label && (
+        <p className="kol-helper-12 tracking-wider text-meta m-0 mb-3">
+          {label}
+        </p>
+      )}
+      <p
+        className="kol-type-sample-body m-0 text-auto"
+        style={{
+          fontFamily: family ? `"${family}", sans-serif` : 'var(--kol-font-family-sans)',
+          fontWeight: weight,
+          fontStyle: italic ? 'italic' : 'normal',
+          fontSize: `${size}px`,
+          lineHeight: lineHeight ? `${lineHeight}px` : '1.2',
+        }}
+      >
+        {children}
+      </p>
+    </div>
+  )
+}

package/src/TypeSpecCard.jsx

@@ -0,0 +1,42 @@
+/**
+ * TypeSpecCard — a two-column type-spec row: a left meta panel of key/value
+ * pairs (font metrics) beside a live sample slot on the right, with an
+ * optional corner label. The "data-sheet" member of the type-specimen kit —
+ * pairs the numeric spec of a type style with a rendered example of it
+ * (often a TypeSample passed as children, composed at the call site).
+ *
+ * Single column on mobile; `240px + fluid` two-column at lg. `meta` is
+ * arbitrary tuples — no fixed metric schema. Sample paragraphs get 16px
+ * rhythm via `.kol-type-spec-sample p` (Preflight zeroes <p> margins).
+ *
+ * @param {string}                label    corner caption, absolute top-left (omit to hide)
+ * @param {Array<[string, ReactNode]>} meta key/value rows in the left panel
+ * @param {ReactNode}             children the live type sample on the right
+ */
+export default function TypeSpecCard({ label, meta = [], children }) {
+  return (
+    <div className="kol-type-spec relative py-12 border-t border-fg-08">
+      {label && (
+        <span className="kol-type-spec-label kol-helper-12 tracking-widest text-meta absolute top-4 left-0">
+          {label}
+        </span>
+      )}
+      <div className="kol-type-spec-row grid grid-cols-1 gap-6 lg:grid-cols-[240px_minmax(0,1fr)] lg:gap-12 items-start pt-6">
+        <div className="kol-type-spec-meta flex flex-col">
+          {meta.map(([key, value]) => (
+            <div
+              key={key}
+              className="kol-type-spec-meta-row grid grid-cols-[auto_minmax(0,1fr)] gap-4 items-baseline py-2 border-b border-[var(--kol-fg-04)] last:border-b-0"
+            >
+              <span className="kol-helper-10 text-meta">{key}</span>
+              <span className="kol-helper-10 text-strong text-right [overflow-wrap:anywhere]">{value}</span>
+            </div>
+          ))}
+        </div>
+        <div className="kol-type-spec-sample min-w-0">
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/TypeSpecimenLive.jsx

@@ -0,0 +1,130 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+
+/* taxonomy-ok: organism — self-measuring live specimen; owns getComputedStyle
+ * I/O over rendered font samples. */
+
+/**
+ * TypeSpecimenLive — a self-measuring type specimen. One row per type class,
+ * each rendering a live sample and reading its OWN `getComputedStyle` to print
+ * the resolved typeface / weight / size / leading / tracking beside it. Because
+ * the labels are measured off the real rendered element, they can never drift
+ * from the CSS: retune a token and the specimen follows.
+ *
+ * Ported from the kol portfolio-kit's `TypeSpecimen` page and generalised for
+ * the design system — the kit's hardcoded row list is now the consumer-injected
+ * `specs` prop, and the PP-Right-Grotesk / JetBrains-Mono weight-name maps are
+ * overridable props (defaulted to the kit's fonts). Casing is untouched: class
+ * names and samples render verbatim.
+ *
+ * WHY IT EXISTS: `TypeSpecCard` is a STATIC data sheet — the consumer types the
+ * metric tuples in by hand next to a sample. This component is its live cousin:
+ * it MEASURES the sample, so there's nothing to type and nothing to keep in
+ * sync. Richer, and honest by construction.
+ *
+ * @param {Object} props
+ * @param {Array<{className:string, sample:React.ReactNode, label?:string}>} props.specs
+ *   The rows. `className` is the type class to render + measure; `sample` is the
+ *   live copy; `label` overrides the printed class name (defaults to className).
+ * @param {string} [props.title] Optional header title (rendered verbatim).
+ * @param {string} [props.description] Optional header description (verbatim).
+ * @param {string} [props.sampleClassName] Extra class(es) on every sample element
+ *   (default `text-emphasis` for a legible default color; pass '' to opt out).
+ * @param {Object<number,string>} [props.sansWeightNames] weight→name for
+ *   proportional faces (default PP Right Grotesk ramp).
+ * @param {Object<number,string>} [props.monoWeightNames] weight→name for mono
+ *   faces (default JetBrains Mono ramp).
+ * @param {{mono:string, sans:string}} [props.typefaceNames] Friendly typeface
+ *   labels chosen by the mono/proportional split (default RG / JetBrains).
+ * @param {string} [props.className] Class(es) on the root <div>.
+ */
+
+const DEFAULT_SANS_WEIGHTS = { 100: 'Fine', 300: 'Light', 400: 'Regular', 500: 'Medium', 600: 'Dark', 700: 'Bold', 900: 'Black' }
+const DEFAULT_MONO_WEIGHTS = { 400: 'Regular', 500: 'Medium', 600: 'SemiBold', 700: 'Bold' }
+const DEFAULT_TYPEFACE_NAMES = { mono: 'JetBrains Mono', sans: 'Right Grotesk' }
+
+/**
+ * Read a computed-style object into a printable metric record. Exported so
+ * consumers can reuse the exact same derivation in tests or custom rows.
+ */
+export function readMeta(cs, {
+  sansWeightNames = DEFAULT_SANS_WEIGHTS,
+  monoWeightNames = DEFAULT_MONO_WEIGHTS,
+  typefaceNames = DEFAULT_TYPEFACE_NAMES,
+} = {}) {
+  const fam = cs.fontFamily.split(',')[0].replace(/["']/g, '').trim()
+  const mono = /mono/i.test(fam)
+  const typeface = mono ? typefaceNames.mono : typefaceNames.sans
+  const width = /Narrow/.test(fam) ? 'Narrow' : /Compact/.test(fam) ? 'Compact' : mono ? 'Monospace' : 'Regular'
+  const w = parseInt(cs.fontWeight, 10)
+  const wname = (mono ? monoWeightNames : sansWeightNames)[w]
+  const size = parseFloat(cs.fontSize)
+  const lh = parseFloat(cs.lineHeight)
+  const leading = Number.isNaN(lh) ? cs.lineHeight : `${+lh.toFixed(1)}px (${(lh / size).toFixed(2)}×)`
+  const ls = parseFloat(cs.letterSpacing)
+  const tracking = !ls ? '0' : `${cs.letterSpacing} (${(ls / size).toFixed(3)}em)`
+  return { fam, typeface, width, weight: `${w}${wname ? ` ${wname}` : ''}`, size: `${+size.toFixed(1)}px`, leading, tracking }
+}
+
+function SpecimenRow({ className, sample, label, sampleClassName, metaConfig }) {
+  const ref = useRef(null)
+  const [m, setM] = useState(null)
+
+  useLayoutEffect(() => {
+    const measure = () => { if (ref.current) setM(readMeta(getComputedStyle(ref.current), metaConfig)) }
+    measure()
+    // Re-measure once webfonts land — line-height can resolve as `normal`
+    // (font-dependent) before the face loads, which would print a stale leading.
+    let cancelled = false
+    if (typeof document !== 'undefined' && document.fonts?.ready) {
+      document.fonts.ready.then(() => { if (!cancelled) measure() })
+    }
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [className])
+
+  return (
+    <div className="flex flex-col gap-2 py-4 border-b border-fg-08">
+      <div ref={ref} className={sampleClassName ? `${className} ${sampleClassName}` : className}>{sample}</div>
+      {m && (
+        <div className="kol-mono-10 text-meta flex flex-col gap-0.5">
+          <span className="text-body">{label ?? className}</span>
+          <span>{m.typeface} · {m.fam} · {m.width} · {m.weight}</span>
+          <span>{m.size} · leading {m.leading} · tracking {m.tracking}</span>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default function TypeSpecimenLive({
+  specs = [],
+  title,
+  description,
+  sampleClassName = 'text-emphasis',
+  sansWeightNames = DEFAULT_SANS_WEIGHTS,
+  monoWeightNames = DEFAULT_MONO_WEIGHTS,
+  typefaceNames = DEFAULT_TYPEFACE_NAMES,
+  className = '',
+}) {
+  const metaConfig = { sansWeightNames, monoWeightNames, typefaceNames }
+  return (
+    <div className={`kol-type-specimen-live flex flex-col ${className}`}>
+      {(title || description) && (
+        <header className="mb-4">
+          {title && <h2 className="kol-sans-heading-04 text-emphasis mb-3">{title}</h2>}
+          {description && <p className="kol-sans-body-03 text-meta">{description}</p>}
+        </header>
+      )}
+      {specs.map((s, i) => (
+        <SpecimenRow
+          key={s.className ? `${s.className}-${i}` : i}
+          className={s.className}
+          sample={s.sample}
+          label={s.label}
+          sampleClassName={sampleClassName}
+          metaConfig={metaConfig}
+        />
+      ))}
+    </div>
+  )
+}

package/src/index.js

@@ -22,6 +22,18 @@ export { default as TypefaceLibraryGridWithVariables } from './TypefaceLibraryGr
 export { default as TypefaceLibraryItem } from './TypefaceLibraryItem.jsx'
 export { default as TypefaceVariablePreview } from './TypefaceVariablePreview.jsx'
 
+// type-specimen kit — prop-driven specimen blocks (moved from @kolkrabbi/kol-component 2026-07-09)
+export { default as TypeSample } from './TypeSample.jsx'
+export { default as TypeSpecCard } from './TypeSpecCard.jsx'
+export { default as TypeSpecimenLive, readMeta } from './TypeSpecimenLive.jsx'
+
+// font-metric hook — opentype.js parsing (optional peer, degrades gracefully)
+export { default as useFontMetrics, extractFaceMetrics, buildOutlinePaths, glyphMetricsOf } from './useFontMetrics.js'
+
+// live-font effects — variable-font axes, animated
+export { default as TextPressure } from './TextPressure.jsx'
+export { default as ColorLoader } from './ColorLoader.jsx'
+
 // reference composition (severed page — data via props, no router/SEO/data-fetch)
 export { default as TypefaceSpecimenPage } from './TypefaceSpecimenPage.jsx'
 

package/src/useFontMetrics.js

@@ -0,0 +1,251 @@
+import { useEffect, useMemo, useState } from 'react'
+
+/**
+ * useFontMetrics — parse a real font with opentype.js and expose its metrics +
+ * text→outline geometry. The parsing engine ported from the kol type-editor's
+ * `fontLoader.js` (async fetch + parse + promise cache) and `textOutline.js`
+ * (tracking-aware advance measurement, greedy soft-wrap, CSS half-leading
+ * baseline math). Generalised off the editor's `layer` object into plain args
+ * and stripped of the editor's case-folding — casing is a content concern, so
+ * text is measured and outlined verbatim.
+ *
+ * WHY IT EXISTS: `GlyphMetricsGrid` already injects a FontFace and parses face-
+ * level metrics (ascender/descender/cap/x-height) inline. This hook is the
+ * reusable, parse-only layer beneath that — and it adds what the grid can't
+ * currently show: per-glyph advance/bounding-box readouts and true glyph
+ * OUTLINE path data (`<path d>`) for any string, at any size/tracking, wrapped
+ * to a box. A consumer can feed those straight into an SVG specimen.
+ *
+ * GRACEFUL DEGRADATION: opentype.js is an OPTIONAL peer, loaded via dynamic
+ * import. Absent it, the hook resolves to `status: 'unavailable'` with a null
+ * font — every derived helper returns an empty/zero result instead of throwing,
+ * exactly like the grid's overlay simply not drawing.
+ *
+ * @param {string} [fontUrl] Same-origin URL of a `.ttf`/`.otf` to fetch + parse.
+ * @param {Object} [options]
+ * @param {ArrayBuffer} [options.buffer] Pre-fetched font bytes — skips the fetch
+ *   (use when a caller already holds the buffer, e.g. an upload). Takes priority
+ *   over `fontUrl`; the two share the same parse/metric path.
+ * @param {string} [options.cacheKey] Override the cache key when passing a raw
+ *   buffer (defaults to a per-buffer identity key, so repeat buffers re-parse).
+ * @returns {{
+ *   status: 'idle'|'loading'|'ready'|'unavailable'|'error',
+ *   opentypeAvailable: boolean,
+ *   font: object|null,
+ *   metrics: {unitsPerEm:number,ascender:number,descender:number,capHeight:number,xHeight:number}|null,
+ *   error: Error|null,
+ *   getAdvanceWidth: (text:string, size:number, opts?:{tracking?:number}) => number,
+ *   getGlyphMetrics: (char:string, size?:number) => object|null,
+ *   getOutlinePaths: (text:string, opts?:object) => string[],
+ * }}
+ */
+
+/* ── opentype loader — cached dynamic import; null once we know it's absent ──
+ * Mirrors GlyphMetricsGrid's inline dynamic import so the two agree on how the
+ * optional peer is resolved (mod.parse ?? mod.default.parse ?? mod.default). */
+let opentypePromise = null
+function loadOpentype() {
+  if (opentypePromise) return opentypePromise
+  opentypePromise = import('opentype.js')
+    .then((mod) => ({ parse: mod.parse || mod.default?.parse || mod.default }))
+    .catch(() => null)
+  return opentypePromise
+}
+
+/* Resolved { font, metrics } promises, keyed like fontLoader's cache so repeat
+ * calls for the same cut never re-fetch or re-parse. A rejected/absent parse is
+ * evicted so a later attempt can retry. */
+const cache = new Map()
+
+/* Face-level metric extraction with the SAME fallback chains GlyphMetricsGrid
+ * uses (os2 ?? hhea ?? literal) so an incomplete font degrades instead of
+ * throwing. */
+function extractFaceMetrics(font) {
+  const os2 = font.tables?.os2
+  const hhea = font.tables?.hhea
+  return {
+    unitsPerEm: font.unitsPerEm || 1000,
+    ascender: os2?.sTypoAscender ?? hhea?.ascender ?? 800,
+    descender: os2?.sTypoDescender ?? hhea?.descender ?? -200,
+    capHeight: os2?.sCapHeight ?? 700,
+    xHeight: os2?.sxHeight ?? 500,
+  }
+}
+
+async function loadFontMetrics(key, source) {
+  if (cache.has(key)) return cache.get(key)
+  const promise = (async () => {
+    const ot = await loadOpentype()
+    if (!ot?.parse) return { font: null, metrics: null, reason: 'unavailable' }
+    const buffer =
+      source.buffer ??
+      (await fetch(source.url).then((r) => {
+        if (!r.ok) throw new Error(`Font fetch failed: ${source.url}`)
+        return r.arrayBuffer()
+      }))
+    const font = ot.parse(buffer)
+    return { font, metrics: extractFaceMetrics(font), reason: 'ready' }
+  })()
+  cache.set(key, promise)
+  promise.catch(() => cache.delete(key))
+  return promise
+}
+
+/* opentype render options for an em tracking value. Non-zero tracking clears
+ * ligature features — matching CSS ("UAs should not apply optional ligatures
+ * when letter-spacing is non-zero"); kerning stays on via the defaults. */
+const renderOpts = (track) =>
+  !track ? {} : { letterSpacing: track, features: [] }
+
+/* Greedy soft-wrap of one hard line to maxW, measured with the same advance/
+ * kerning/letter-spacing engine that draws the glyphs. Whitespace never forces
+ * a break (trailing space hangs); a word wider than the box splits at char
+ * level (overflow-wrap: break-word). Ported verbatim from textOutline.js. */
+function wrapLine(font, text, size, opts, maxW) {
+  if (!text.trim() || maxW <= 0) return [text]
+  const measure = (s) => font.getAdvanceWidth(s.replace(/\s+$/, ''), size, opts)
+  const tokens = text.split(/(\s+)/).filter(Boolean)
+  const lines = []
+  let cur = ''
+  for (const tok of tokens) {
+    if (/^\s+$/.test(tok)) { cur += tok; continue }
+    if (cur.trim() && measure(cur + tok) > maxW) { lines.push(cur); cur = tok }
+    else cur += tok
+    while (measure(cur) > maxW && cur.trim().length > 1) {
+      let n = cur.length - 1
+      while (n > 1 && measure(cur.slice(0, n)) > maxW) n -= 1
+      lines.push(cur.slice(0, n))
+      cur = cur.slice(n)
+    }
+  }
+  lines.push(cur)
+  return lines
+}
+
+/**
+ * Glyph outlines as layer-local `<path d>` strings, one per rendered line.
+ * Ported from textOutline.js `textOutlinePaths` — baselines via the CSS half-
+ * leading model over hhea ascent/descent (what Chrome/mac uses for the line-box
+ * content area). Text is outlined verbatim (no case-folding). When `boxWidth`
+ * is 0 the text is treated as a single unwrapped line; when `boxHeight` is 0 the
+ * block is top-anchored (top = 0) rather than vertically centered.
+ */
+function buildOutlinePaths(font, metrics, text, opts = {}) {
+  const {
+    size = 96,
+    tracking = 0,
+    lineHeight = 1.05,
+    align = 'left',
+    boxWidth = 0,
+    boxHeight = 0,
+    decimals = 2,
+  } = opts
+  const display = String(text ?? '')
+  if (!display.trim()) return []
+
+  const ropts = renderOpts(tracking)
+  const lines = display
+    .split('\n')
+    .flatMap((ln) => (boxWidth > 0 ? wrapLine(font, ln, size, ropts, boxWidth) : [ln]))
+
+  const scale = size / metrics.unitsPerEm
+  const ascent = metrics.ascender * scale
+  const descent = -metrics.descender * scale        /* hhea descender is negative */
+  const lineH = lineHeight * size
+  const blockH = Math.max(lines.length * lineH, size)  /* min-height: 1em */
+  const top = boxHeight > 0 ? (boxHeight - blockH) / 2 : 0
+
+  const paths = []
+  lines.forEach((line, i) => {
+    const t = line.replace(/\s+$/, '')             /* trailing spaces hang */
+    if (!t) return                                 /* blank line still holds its slot */
+    const lineW = font.getAdvanceWidth(t, size, ropts)
+    const lx =
+      align === 'left' ? 0 : align === 'right' ? boxWidth - lineW : (boxWidth - lineW) / 2
+    const baseY = top + i * lineH + (lineH - (ascent + descent)) / 2 + ascent
+    const d = font.getPath(t, lx, baseY, size, ropts).toPathData(decimals)
+    if (d) paths.push(d)
+  })
+  return paths
+}
+
+/* Per-glyph readout for the first char of `char`, in font units and (if a size
+ * is given) scaled px. Upgrades GlyphMetricsGrid: it can now print each cell's
+ * real advance + bounding box, not just the face-level lines. */
+function glyphMetricsOf(font, char, size) {
+  const ch = String(char ?? '').charAt(0)
+  if (!ch) return null
+  const glyph = font.charToGlyph(ch)
+  if (!glyph) return null
+  const bbox = glyph.getBoundingBox?.() ?? { x1: 0, y1: 0, x2: 0, y2: 0 }
+  const advanceUnits = glyph.advanceWidth ?? 0
+  const base = {
+    name: glyph.name,
+    unicode: glyph.unicode,
+    index: glyph.index,
+    advanceWidth: advanceUnits,
+    boundingBox: bbox,
+    leftSideBearing: glyph.leftSideBearing ?? bbox.x1,
+  }
+  if (!size) return base
+  const scale = size / (font.unitsPerEm || 1000)
+  return {
+    ...base,
+    advanceWidthPx: advanceUnits * scale,
+    widthPx: (bbox.x2 - bbox.x1) * scale,
+    heightPx: (bbox.y2 - bbox.y1) * scale,
+  }
+}
+
+export default function useFontMetrics(fontUrl, options = {}) {
+  const { buffer, cacheKey } = options
+  const key = buffer ? cacheKey ?? `buffer:${cacheKey ?? Math.random()}` : fontUrl
+
+  const [state, setState] = useState({
+    status: 'idle',
+    font: null,
+    metrics: null,
+    error: null,
+  })
+
+  useEffect(() => {
+    if (!buffer && !fontUrl) {
+      setState({ status: 'idle', font: null, metrics: null, error: null })
+      return
+    }
+    let cancelled = false
+    setState((s) => ({ ...s, status: 'loading', error: null }))
+    loadFontMetrics(key, buffer ? { buffer } : { url: fontUrl })
+      .then(({ font, metrics, reason }) => {
+        if (cancelled) return
+        if (!font) { setState({ status: 'unavailable', font: null, metrics: null, error: null }); return }
+        setState({ status: reason === 'ready' ? 'ready' : 'unavailable', font, metrics, error: null })
+      })
+      .catch((error) => {
+        if (!cancelled) setState({ status: 'error', font: null, metrics: null, error })
+      })
+    return () => { cancelled = true }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+
+  const { font, metrics } = state
+
+  // Stable helper identities per parsed font — safe to pass to children/memos.
+  const helpers = useMemo(() => ({
+    getAdvanceWidth: (text, size, opts = {}) =>
+      font ? font.getAdvanceWidth(String(text ?? ''), size, renderOpts(opts.tracking)) : 0,
+    getGlyphMetrics: (char, size) => (font ? glyphMetricsOf(font, char, size) : null),
+    getOutlinePaths: (text, opts) => (font && metrics ? buildOutlinePaths(font, metrics, text, opts) : []),
+  }), [font, metrics])
+
+  return {
+    status: state.status,
+    opentypeAvailable: state.status !== 'unavailable',
+    font,
+    metrics,
+    error: state.error,
+    ...helpers,
+  }
+}
+
+export { extractFaceMetrics, buildOutlinePaths, glyphMetricsOf }