@kolkrabbi/kol-styleguide 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "private": false,
   "description": "Brand guide components and the brand tool",
   "license": "MIT",
@@ -9,23 +9,24 @@
   "module": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./lab": "./src/lab/index.js",
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.188.0",
-    "@kolkrabbi/kol-framework": ">=0.39.0",
+    "@kolkrabbi/kol-component": ">=0.315.0",
+    "@kolkrabbi/kol-framework": ">=0.64.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "@kolkrabbi/kol-print": ">=0.1.0",
-    "@kolkrabbi/kol-theme": ">=0.53.0",
+    "@kolkrabbi/kol-theme": ">=0.198.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.313.0",
-    "@kolkrabbi/kol-framework": "^0.62.4",
-    "@kolkrabbi/kol-icons": "^0.52.0",
+    "@kolkrabbi/kol-component": "^0.316.0",
     "@kolkrabbi/kol-print": "^0.1.1",
-    "@kolkrabbi/kol-theme": "^0.196.0"
+    "@kolkrabbi/kol-framework": "^0.64.0",
+    "@kolkrabbi/kol-icons": "^0.52.0",
+    "@kolkrabbi/kol-theme": "^0.199.0"
   },
   "files": [
     "src",

package/src/ColorLab.jsx

@@ -1,21 +1,24 @@
 import { useState } from 'react'
 import { ColorPickerPopover, Dropdown, HARMONIES, PaletteHarmonyWheel, ToggleSwitch, hslToHex } from '@kolkrabbi/kol-component'
-import { COLOR_MIX, COLOR_ROLES, COLOR_SLOTS, DEFAULT_COLOR_LAB, deriveColorLab, rgbText } from './colorLab.js'
-import { fgOn } from './comboMath.js'
+import { COLOR_MIX, COLOR_ROLES, COLOR_SLOTS, DEFAULT_COLOR_LAB, INK_LEVELS, colorLab, inkOn, rgbText } from './colorLab.js'
 
 /* taxonomy-ok: organism — the color builder: harmony wheel, roles, slots, palette, ramps and the 60/30/10 strip over one value */
 
 /**
- * ColorLab — an interactive palette builder from one base color.
+ * ColorLab — A brand's colour, generated from one base colour.
  *
  * Carried from kol-atlas's Color page (2026-10-20). Six sections over ONE value: Harmony (base +
  * rule on KOL's wheel), Roles (the harmony's five), Brand slots (four, two dark two light), Palette
  * (ten hues 36° apart + blue-grey and grey ramps), Ramps (five blend steps per hue) and Composition
  * (60/30/10). Select a slot or a composition share, then click any swatch to fill it.
  *
- * The math is `colorLab.js` (`deriveColorLab`, `colorLabCss`), so a consumer can save the value into
+ * The math is `colorLab.js` (`colorLab`, `colorLabCss`), so a consumer can save the value into
  * a brand and emit it as CSS without rendering the lab.
  *
+ * A COLOUR DEFINITION (BrandLabToolGaps, kol-atlas 2026-10-29): every swatch's info carries its contrast against the
+ * brand's own ink (ratio and WCAG grade); Ink shows the brand's text levels on its light and dark grounds; Dark shows
+ * the roles, slots and composition as the dark theme takes them.
+ *
  * @param {Object}   value     `{ base, harmony, blueBase, greyBase, blueLinked, slots, picks }` — controlled; omit for internal
  * @param {Function} onChange  `(next) => void`
  * @param {string}   className classes on the root
@@ -26,14 +29,18 @@ const PICKER = '[&>*]:!size-3'
 /* ten columns capped so the 5-row ramp fits the window — a swatch is the same size in every section */
 const ROW_MAX = 'calc((100vh - 200px) * 2)'
 const isHex = (hex) => /^#[0-9a-f]{6}/i.test(hex)
+/* a ratio floored, never rounded — 4.497 must not read as 4.5 beside a grade that says it misses AA */
+const ratioText = (r) => (Math.floor(r * 10) / 10).toFixed(1)
 
-function Swatch({ hex, name, selected, onClick, info }) {
+function Swatch({ hex, name, selected, onClick, info, inks, ring }) {
+  const ink = inks ? inkOn(hex, inks) : null
   return (
-    <button type="button" onClick={onClick} title={`${name} ${hex}`} className={`group relative aspect-square cursor-pointer overflow-hidden rounded ${selected ? 'ring-2 ring-[var(--kol-accent-primary)]' : ''}`} style={{ background: hex }}>
+    <button type="button" onClick={onClick} title={`${name} ${hex}`} className={`group relative aspect-square cursor-pointer overflow-hidden rounded ${selected ? 'ring-2 ring-[var(--kol-accent-primary)]' : ''}`} style={{ background: hex, boxShadow: ring && !selected ? `inset 0 0 0 1px ${ring}` : undefined }}>
       <span className={`absolute inset-x-0 bottom-0 flex flex-col gap-0.5 bg-surface-primary px-1.5 py-1 text-left kol-mono-10 leading-tight transition-opacity ${info ? 'opacity-100' : 'opacity-0 group-hover:opacity-100'}`}>
         <span className="truncate text-emphasis">{name}</span>
         <span className="truncate text-meta">{hex}</span>
         <span className="truncate text-meta">{rgbText(hex)}</span>
+        {ink && <span className="truncate text-meta">{ratioText(ink.ratio)} · {ink.grade}</span>}
       </span>
     </button>
   )
@@ -63,9 +70,9 @@ export default function ColorLab({ value: valueProp, onChange, className = '' })
   const value = valueProp ?? own
   const set = (patch) => { const next = { ...value, ...patch }; if (valueProp === undefined) setOwn(next); onChange?.(next) }
   const [slot, setSlot] = useState(null)
-  const [info, setInfo] = useState({ roles: false, brand: false, palette: false, ramps: false, mix: false })
+  const [info, setInfo] = useState({ roles: false, brand: false, palette: false, ramps: false, mix: false, dark: false })
   const infoFor = (k) => ({ info: info[k], onInfo: (v) => setInfo((x) => ({ ...x, [k]: v })) })
-  const c = deriveColorLab(value)
+  const c = colorLab(value)
 
   /* a swatch click fills the selected slot (0–3) or composition share (4–6) */
   const assign = (hex) => {
@@ -83,26 +90,26 @@ export default function ColorLab({ value: valueProp, onChange, className = '' })
         <div className="flex flex-wrap items-start gap-x-8 gap-y-4">
           <div className="flex flex-col gap-2"><span className={LABEL}>Base</span><span className="flex h-8 items-center gap-2"><ColorPickerPopover size="sm" className={PICKER} color={c.base} onChange={(hex) => isHex(hex) && set({ base: hex.slice(0, 7).toUpperCase() })} label="Base color" /><span className="kol-mono-10 text-meta">{c.base}</span></span></div>
           <div className="flex flex-col gap-2"><span className={LABEL}>Harmony</span><Dropdown size="sm" value={c.harmony} onChange={(v) => set({ harmony: v })} options={HARMONIES.map((x) => ({ value: x.id, label: x.label }))} /></div>
-          <div className="flex flex-col gap-2"><span className={LABEL}>Info</span><span className="flex h-8 items-center"><ToggleSwitch size="sm" className={BARE_SWITCH} checked={Object.values(info).every(Boolean)} onChange={(v) => setInfo({ roles: v, brand: v, palette: v, ramps: v, mix: v })} /></span></div>
+          <div className="flex flex-col gap-2"><span className={LABEL}>Info</span><span className="flex h-8 items-center"><ToggleSwitch size="sm" className={BARE_SWITCH} checked={Object.values(info).every(Boolean)} onChange={(v) => setInfo({ roles: v, brand: v, palette: v, ramps: v, mix: v, dark: v })} /></span></div>
         </div>
         <PaletteHarmonyWheel size={220} hue={c.h} harmony={c.harmony} saturation={c.s} lightness={c.l} onHueChange={(hh) => set({ base: hslToHex(hh, c.s, c.l).toUpperCase() })} />
       </Section>
 
       <Section title="Roles" {...infoFor('roles')}>
-        <Row>{c.roles.map((hex, i) => <Swatch key={i} info={info.roles} hex={hex} name={COLOR_ROLES[i]} onClick={() => assign(hex)} />)}</Row>
+        <Row>{c.roles.map((hex, i) => <Swatch inks={c.inks} key={i} info={info.roles} hex={hex} name={COLOR_ROLES[i]} onClick={() => assign(hex)} />)}</Row>
       </Section>
 
       <Section title="Brand slots" {...infoFor('brand')}>
-        <Row>{c.slots.map((hex, i) => <Swatch key={i} info={info.brand} hex={hex} name={COLOR_SLOTS[i]} selected={slot === i} onClick={() => toggleSlot(i)} />)}</Row>
+        <Row>{c.slots.map((hex, i) => <Swatch inks={c.inks} key={i} info={info.brand} hex={hex} name={COLOR_SLOTS[i]} selected={slot === i} onClick={() => toggleSlot(i)} />)}</Row>
       </Section>
 
       <Section title="Palette" {...infoFor('palette')} extra={<Switch label="Link blue" checked={c.blueLinked} onChange={(v) => set({ blueLinked: v })} />}>
-        <Row>{c.hues.map((x) => <Swatch key={x.name + x.hex} info={info.palette} hex={x.hex} name={x.name} selected={picked(x.hex)} onClick={() => assign(x.hex)} />)}</Row>
+        <Row>{c.hues.map((x) => <Swatch inks={c.inks} key={x.name + x.hex} info={info.palette} hex={x.hex} name={x.name} selected={picked(x.hex)} onClick={() => assign(x.hex)} />)}</Row>
         {[['Blue-grey', c.blueGrey, c.blueBase, 'blueBase', true], ['Grey', c.grey, c.greyBase, 'greyBase', false]].map(([row, ramp, rb, key, linkable]) => (
           <div key={row} className="mt-4 flex flex-col gap-2">
             <span className="flex h-4 items-center gap-3"><span className={`${LABEL} w-[120px]`}>{row} base</span>
               {!(linkable && c.blueLinked) && <><ColorPickerPopover size="sm" className={PICKER} color={rb} onChange={(hex) => isHex(hex) && set({ [key]: hex.slice(0, 7).toUpperCase() })} label={`${row} base`} /><span className="kol-mono-10 text-meta">{rb}</span></>}</span>
-            <Row>{ramp.map((hex, i) => <Swatch key={row + i} info={info.palette} hex={hex} name={`${row} ${(i + 1) * 100}`} selected={picked(hex)} onClick={() => assign(hex)} />)}</Row>
+            <Row>{ramp.map((hex, i) => <Swatch inks={c.inks} key={row + i} info={info.palette} hex={hex} name={`${row} ${(i + 1) * 100}`} selected={picked(hex)} onClick={() => assign(hex)} />)}</Row>
           </div>
         ))}
       </Section>
@@ -111,7 +118,7 @@ export default function ColorLab({ value: valueProp, onChange, className = '' })
         <Row>
           {[0, 1, 2, 3, 4].flatMap((step) => c.ramps.map((hue) => {
             const hex = hue.steps[step]
-            return <Swatch key={hue.hex + step} info={info.ramps} hex={hex} name={`${hue.name} ${(step + 1) * 100}`} selected={picked(hex)} onClick={() => assign(hex)} />
+            return <Swatch inks={c.inks} key={hue.hex + step} info={info.ramps} hex={hex} name={`${hue.name} ${(step + 1) * 100}`} selected={picked(hex)} onClick={() => assign(hex)} />
           }))}
         </Row>
       </Section>
@@ -120,7 +127,7 @@ export default function ColorLab({ value: valueProp, onChange, className = '' })
         <div style={{ maxWidth: ROW_MAX }}>
           <div className="flex h-40 overflow-hidden rounded">
             {COLOR_MIX.map(([share, label], i) => (
-              <button key={label} type="button" onClick={() => toggleSlot(4 + i)} title={`${label} ${c.mix[i]}`} className={`flex min-w-0 cursor-pointer flex-col justify-between p-3 text-left transition-colors ${slot === 4 + i ? 'ring-2 ring-inset ring-[var(--kol-accent-primary)]' : ''}`} style={{ flex: share, background: c.mix[i], color: fgOn(c.mix[i]) }}>
+              <button key={label} type="button" onClick={() => toggleSlot(4 + i)} title={`${label} ${c.mix[i]}`} className={`flex min-w-0 cursor-pointer flex-col justify-between p-3 text-left transition-colors ${slot === 4 + i ? 'ring-2 ring-inset ring-[var(--kol-accent-primary)]' : ''}`} style={{ flex: share, background: c.mix[i], color: inkOn(c.mix[i], c.inks).ink }}>
                 <span className="kol-sans-heading-03 leading-none">{share * 10}</span>
                 <span className={`truncate kol-mono-10 leading-tight transition-opacity ${info.mix ? 'opacity-100' : 'opacity-0'}`}>{c.mix[i]}</span>
               </button>
@@ -139,6 +146,33 @@ export default function ColorLab({ value: valueProp, onChange, className = '' })
           </div>
         </div>
       </Section>
+
+      {/* THE BRAND'S INK: its text levels on its own grounds, light and dark, each with its contrast */}
+      <Section title="Ink">
+        <div className="grid grid-cols-1 gap-2 sm:grid-cols-2" style={{ maxWidth: ROW_MAX }}>
+          {[['Light', c.slots[2], c.ink.light, c.inkGrades.light], ['Dark', c.dark.slots[2], c.ink.dark, c.inkGrades.dark]].map(([mode, ground, ink, grades]) => (
+            <div key={mode} className="flex flex-col gap-2 rounded p-4" style={{ background: ground }}>
+              {INK_LEVELS.map(([id]) => (
+                <span key={id} className="flex items-baseline justify-between gap-3" style={{ color: ink[id] }}>
+                  <span className="kol-sans-body-02">{mode} · {id}</span>
+                  <span className="kol-mono-10">{ink[id]} · {ratioText(grades[id].ratio)} {grades[id].grade}</span>
+                </span>
+              ))}
+            </div>
+          ))}
+        </div>
+      </Section>
+
+      {/* THE DARK THEME: the slots swapped, each role moved along its ramp until it passes AA on the dark ground */}
+      <Section title="Dark" {...infoFor('dark')}>
+        <div className="flex flex-col gap-4 rounded p-4" style={{ background: c.dark.slots[2], maxWidth: ROW_MAX }}>
+          <Row>{c.dark.roles.map((hex, i) => <Swatch ring={`${c.inks.light}40`} inks={c.inks} key={`dr${i}`} info={info.dark} hex={hex} name={COLOR_ROLES[i]} />)}</Row>
+          <Row>{c.dark.slots.map((hex, i) => <Swatch ring={`${c.inks.light}40`} inks={c.inks} key={`ds${i}`} info={info.dark} hex={hex} name={COLOR_SLOTS[i]} />)}</Row>
+          <div className="flex h-16 overflow-hidden rounded border" style={{ borderColor: `${c.inks.light}40` }}>
+            {COLOR_MIX.map(([share, label], i) => <span key={label} style={{ flex: share, background: c.dark.mix[i] }} title={`${label} ${c.dark.mix[i]}`} />)}
+          </div>
+        </div>
+      </Section>
     </div>
   )
 }

package/src/ComboLab.jsx

@@ -2,6 +2,7 @@ import { useState } from 'react'
 import { ViewToggle } from '@kolkrabbi/kol-component'
 import { LAYOUT_COMPONENTS, COMBO_LAYOUTS } from './comboLayouts.jsx'
 import { generatePalette } from './comboMath.js'
+import { DEFAULT_COMBO_LAB } from './comboLab.js'
 
 /**
  * ComboLab — the 60 / 30 / 10 color-combination playground.
@@ -20,6 +21,8 @@ import { generatePalette } from './comboMath.js'
  *                  `palettes` nor `pool`, Randomize derives a fresh palette from
  *                  the current primary (seed mode).
  *   - `logo`     — a React node dropped into the logo slots.
+ *   - `onChange` — `(palette) => void` when Randomize or the Palette toggle picks one (the lab family's
+ *                  one value — `comboLabCss(palette)` emits it; BrandLabToolGaps 2026-10-29).
  *
  * Chrome (borders, type, state) is DS-owned via `.kol-combo-*` +
  * `kol-helper-*` + `text-*` utilities; the only inline values are the palette's
@@ -28,19 +31,9 @@ import { generatePalette } from './comboMath.js'
  * See the monorepo severance notes in lobby/ComboLab.md.
  */
 
-/* Canonical Kolkrabbi composition. Literal hex (this is a plain module with no
-   CSS-var resolver) mirroring the DS brand tokens:
-   yellow-300 / red-200 / cream-100 / blue-400 / orange-300. */
-export const DEFAULT_PALETTE = {
-  id: 'kolkrabbi',
-  label: 'Kolkrabbi',
-  description: 'Yellow hero · rust secondary · navy ink on cream — the canonical composition',
-  primary:   '#FFCF33',
-  secondary: '#AD5038',
-  light:     '#FAF7F0',
-  dark:      '#222D3D',
-  accent:    '#DF760B',
-}
+/* the canonical Kolkrabbi composition is comboLab.js's DEFAULT_COMBO_LAB; DEFAULT_PALETTE is its old name */
+/** @deprecated 2026-10-29 — DEFAULT_COMBO_LAB */
+export const DEFAULT_PALETTE = DEFAULT_COMBO_LAB
 
 const ROLE_LABELS = ['Primary', 'Secondary', 'Light', 'Dark', 'Accent']
 
@@ -95,12 +88,15 @@ export default function ComboLab({
   logo = null,
   pool,
   mode = 'random',
+  onChange,
   className = '',
 }) {
-  const initialPalette = palette ?? palettes?.[0] ?? DEFAULT_PALETTE
+  const initialPalette = palette ?? palettes?.[0] ?? DEFAULT_COMBO_LAB
 
   const [layoutId, setLayoutId] = useState(layout ?? layouts[0]?.id ?? COMBO_LAYOUTS[0].id)
-  const [active, setActive]     = useState(initialPalette)
+  const [active, setOwn]       = useState(initialPalette)
+  /* the palette reported as it changes, so a draft can keep it (the lab family's one-value contract, 2026-10-29) */
+  const setActive = (p) => { setOwn(p); onChange?.(p) }
   const [logoOn, setLogoOn]     = useState(Boolean(logo))
 
   const LayoutComponent = LAYOUT_COMPONENTS[layoutId] ?? LAYOUT_COMPONENTS[COMBO_LAYOUTS[0].id]

package/src/DocumentIndex.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { FullscreenOverlay, KindPreview, PageHeader, QuickLookFrame, KIND_LABEL } from '@kolkrabbi/kol-component'
+import { FileQuickLook, PageHeader, KIND_LABEL } from '@kolkrabbi/kol-component'
 import { Contents } from './BrandGuide.jsx'
 
 /* DOCUMENT INDEX — a folder's pages as the brand book's contents cards (BrandGuide's `Contents`, routed), grouped by
@@ -24,22 +24,19 @@ export default function DocumentIndex({ rows, title, lede, onNavigate }) {
   const index = rows.map((r) => (r.file
     ? { ...r, href: r.file, meta: r.meta ?? fileLabel(r), onClick: (e) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return; e.preventDefault(); setOpen(files.indexOf(r)) } }
     : r))
-  const cur = open === null ? null : files[open]
-  const step = (d) => setOpen((i) => (i + d + files.length) % files.length)
   return (
     <div className="kol-page flex flex-col gap-6">
       {title && <PageHeader title={title} subtitle={lede} size="sm" voice="mono" />}
       <Contents index={index} onNavigate={onNavigate} />
-      {cur && (
-        /* QUICK LOOK DIMS, it does not black out — the list stays in view (MediaLibraryPages' rule) */
-        <FullscreenOverlay open onClose={() => setOpen(null)} closeButton={false} scrim>
-          <QuickLookFrame title={cur.title} meta={fileLabel(cur)} onClose={() => setOpen(null)} nav={files.length > 1 ? { index: open, total: files.length, onPrev: () => step(-1), onNext: () => step(1) } : undefined}>
-            {cur.kind === 'image' || /^(png|jpe?g|webp|gif|svg|avif)$/i.test(cur.ext ?? '')
-              ? <img src={cur.file} alt={cur.title} className="kol-quicklook-media" />
-              : <KindPreview key={cur.file} o={{ key: cur.file.split('?')[0], url: cur.file }} fit="sheet" urlOf={(x) => x.url} />}
-          </QuickLookFrame>
-        </FullscreenOverlay>
-      )}
+      {/* the DS Quick Look over the folder's files (kol-component FileQuickLook, 2026-10-29 — the composition this file drew
+        * by hand: dims, pages ‹ ›, a download) */}
+      <FileQuickLook
+        files={files.map((f) => ({ key: f.file.split('?')[0], name: f.title, url: f.file, type: f.kind === 'image' ? 'image/' : undefined }))}
+        index={open}
+        onIndex={setOpen}
+        onClose={() => setOpen(null)}
+        meta={(x) => fileLabel(files.find((f) => f.file === x.url))}
+      />
     </div>
   )
 }

package/src/DocumentLibrary.jsx

@@ -0,0 +1,113 @@
+import { useState } from 'react'
+import { Button, FileQuickLook, Table } from '@kolkrabbi/kol-component'
+import { MarkdownPage, PageSection, libraryLinks } from '@kolkrabbi/kol-framework'
+import DocumentIndex from './DocumentIndex.jsx'
+
+/* DOCUMENT LIBRARY — a `documentLibrary` (kol-framework) drawn: a sortable table per folder, the title opening the text,
+ * the originals opening in the DS Quick Look, the markdown downloading (DocumentLibraryAndBoardParts, kol-website
+ * 2026-10-29 — record's DocumentsIndex · FolderTable · Files · MdDownload, made the DS's so brand and record draw their
+ * documents the same way: *"I already asked for tables, and download and file preview"*).
+ *
+ *   <DocumentLibrary library={lib} onNavigate={navigate} urlOf={(f) => f.url} />          every folder, a section each
+ *   <DocumentLibrary library={lib} folder="press" … />                                   one folder
+ *   <DocumentView library={lib} row={row} urlOf={…} resolveLink={…} assetUrl={…} />     the open document
+ *
+ * DocumentLibrary
+ *   library    `{ rows, folders }` from documentLibrary
+ *   folder     one folder's id; omitted, every folder
+ *   columns    the table's columns — an array of keys (`title · kind · date · lang · assets · markdown`) and/or Table column
+ *              objects, or `(defaults) => columns` to drop, reorder or add
+ *   view       `table` (default) · `cards` (DocumentIndex's contents cards, for anyone who still wants them)
+ *   onNavigate (to) => void — a title's click; the link is a real `href` too
+ *   urlOf      (file) => string — an original's URL (default `file.url`; record serves the bucket in prod and a mirror in dev)
+ *
+ * DocumentFiles — the Assets cell on its own: a button per original, labelled by extension, two of one kind told apart by
+ * language (`PDF IS`, `PDF EN`); each opens Quick Look over the row's files. `DocumentMarkdown` — the source as `<stem>.md`. */
+const LANGS = ['is', 'en', 'de']
+const ext = (f) => (f.key ?? f.name ?? '').split('.').pop().toUpperCase()
+export const fileLabel = (files, f) => (files.filter((x) => ext(x) === ext(f)).length > 1
+  ? `${ext(f)} ${(f.key ?? f.name).split('/').pop().split(/[-.]/).filter((t) => LANGS.includes(t)).join(' ').toUpperCase()}`.trim()
+  : ext(f))
+const plain = (e) => !(e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0)
+
+/* the one Quick Look a page holds: `open(files, index)` and the overlay to render */
+export function useFileQuickLook(urlOf) {
+  const [look, setLook] = useState(null)
+  const overlay = look && <FileQuickLook files={look.files} index={look.index} onIndex={(index) => setLook({ ...look, index })} onClose={() => setLook(null)} urlOf={urlOf} />
+  return [(files, index) => setLook({ files, index }), overlay]
+}
+
+export function DocumentFiles({ row, onOpen }) {
+  if (!row.files?.length) return null
+  return (
+    <div className="flex flex-wrap gap-1">
+      {row.files.map((f, i) => <Button key={f.key} variant="nav" size="sm" onClick={() => onOpen(row.files, i)} title={f.name ?? f.key.split('/').pop()}>{fileLabel(row.files, f)}</Button>)}
+    </div>
+  )
+}
+
+export const DocumentMarkdown = ({ row }) => (
+  <Button variant="nav" size="sm" iconOnly="download" href={`data:text/markdown;charset=utf-8,${encodeURIComponent(row.source ?? '')}`} download={`${row.id.split('/').pop()}.md`} aria-label="Download markdown" />
+)
+
+const DEFAULT_KEYS = ['title', 'kind', 'date', 'lang', 'assets', 'markdown']
+
+function columnsFor({ onNavigate, onOpen }) {
+  return {
+    title: { header: 'Title', accessor: 'title', wrap: true, sortable: true, render: (r) => (
+      <a href={r.to} className="underline-offset-2 hover:underline" onClick={onNavigate ? (e) => { if (!plain(e)) return; e.preventDefault(); onNavigate(r.to) } : undefined}>{r.title}</a>
+    ) },
+    kind: { header: 'Kind', accessor: 'kind', sortable: true },
+    date: { header: 'Date', accessor: 'date', sortable: true },
+    lang: { header: 'Language', accessor: 'lang' },
+    assets: { header: 'Assets', accessor: 'files', render: (r) => <DocumentFiles row={r} onOpen={onOpen} /> },
+    markdown: { header: 'Markdown', accessor: 'source', render: (r) => <DocumentMarkdown row={r} /> },
+  }
+}
+
+export default function DocumentLibrary({ library, folder, columns, view = 'table', onNavigate, urlOf = (f) => f.url }) {
+  const [open, overlay] = useFileQuickLook(urlOf)
+  const named = columnsFor({ onNavigate, onOpen: open })
+  const defaults = DEFAULT_KEYS.map((k) => named[k])
+  const resolve = (c) => (typeof c === 'string' ? named[c] : c)
+  const cols = (typeof columns === 'function' ? columns(defaults) : columns ?? DEFAULT_KEYS).map(resolve).filter(Boolean)
+  const folders = folder != null ? library.folders.filter((f) => f.id === folder) : library.folders
+
+  if (view === 'cards') {
+    /* the contents cards: pages as cards in their folder's part, the originals as file cards (DocumentIndex opens them) */
+    const rows = folders.flatMap((f) => library.rows.filter((r) => r.folder === f.id).flatMap((r) => [
+      { id: r.id, to: r.to, title: r.title, label: r.kind || undefined, part: f.label },
+      ...(r.files ?? []).map((x) => ({ id: `${r.id}:${x.key}`, file: urlOf(x), title: x.name ?? x.key.split('/').pop(), part: f.label })),
+    ]))
+    return <DocumentIndex rows={rows} onNavigate={onNavigate} />
+  }
+  return (
+    <div>
+      {folders.map((f) => (
+        <PageSection key={f.id || 'root'} id={f.id || 'documents'} label={f.label}>
+          <Table columns={cols} rows={library.rows.filter((r) => r.folder === f.id)} width="column" variant="simple" />
+        </PageSection>
+      ))}
+      {overlay}
+    </div>
+  )
+}
+
+/* THE OPEN DOCUMENT: the same Assets and Markdown buttons above `MarkdownPage`, then `actions` — record's DocumentsPage.
+ * Every other prop goes to MarkdownPage (`resolveLink`, `assetUrl`, `toc`, `numbered`, …); `resolveLink` defaults to the
+ * library's own (`libraryLinks`, kol-framework) when the caller passes `library` and no resolver. */
+export function DocumentView({ row, library, urlOf = (f) => f.url, actions, markdown = true, ...page }) {
+  const [open, overlay] = useFileQuickLook(urlOf)
+  if (library && !page.resolveLink) page.resolveLink = libraryLinks(library)
+  return (
+    <>
+      <div className="kol-page flex items-center justify-end gap-1 pb-0">
+        <DocumentFiles row={row} onOpen={open} />
+        {markdown && <DocumentMarkdown row={row} />}
+        {actions}
+      </div>
+      <MarkdownPage key={row.id} source={row.source} {...page} />
+      {overlay}
+    </>
+  )
+}

package/src/LockupBuilder.jsx

@@ -1,60 +1,10 @@
-import { useState } from 'react'
-import { Input, Label, SegmentedToggle } from '@kolkrabbi/kol-component'
-import Lockup from './Lockup.jsx'
-
-/* taxonomy-ok: organism — the live lockup builder: name / descriptor / variant / scale controls beside a Lockup stage, preset rows below */
+import LockupLab from './LockupLab.jsx'
 
 /**
- * LockupBuilder — Build a product lockup from a name. Type a product name, add descriptors, pick a variant and scale; the presets run a
- * brand's naming levels through the same Lockup.
- *
- * Carried from kol-atlas `components/lockup/LiveLockup.jsx` (2026-10-20); the parent, the mark, the
- * face and the presets are the brand's, passed in.
- *
- * @param {string}    parent    the parent brand name
- * @param {ReactNode} mark      the mark (see Lockup)
- * @param {string}    font      CSS font-family for the names
- * @param {Object}    presets   `{ [level]: string[] }` — e.g. `{ Products: ['Hosting', …] }`
- * @param {string}    className classes on the root
+ * @deprecated 2026-10-29 — `LockupLab` (the lab family's name, BrandLabToolGaps). Same component, same props; drops when
+ * nobody imports it (04-retirements.md).
+ * LockupBuilder — A product lockup, generated from a name. The old name of LockupLab.
  */
-const VARIANTS = [{ value: 'horizontal', label: 'Horizontal' }, { value: 'hero', label: 'Hero' }, { value: 'wordmark', label: 'Wordmark' }]
-const SCALES = ['sm', 'md', 'lg', 'xl'].map((s) => ({ value: s, label: s.toUpperCase() }))
-
-const Field = ({ label, children }) => <div className="flex flex-col gap-2"><Label>{label}</Label>{children}</div>
-
-export default function LockupBuilder({ parent = 'Brand', mark, font, presets = {}, className = '' }) {
-  const first = Object.values(presets)[0]?.[0] ?? ''
-  const [s, setS] = useState({ product: first, descriptor: '', descriptor2: '', variant: 'horizontal', scale: 'lg' })
-  const set = (patch) => setS((p) => ({ ...p, ...patch }))
-  const brand = { parent, mark, font }
-
-  return (
-    <div className={`flex flex-col gap-6 ${className}`.trim()}>
-      <div className="grid gap-6 md:grid-cols-[300px_minmax(0,1fr)]">
-        <div className="flex flex-col gap-5 self-start rounded-lg border border-fg-08 p-5">
-          <Field label="Product name"><Input value={s.product} onChange={(e) => set({ product: e.target.value })} placeholder="e.g. Hosting" /></Field>
-          <Field label="Descriptor"><Input value={s.descriptor} onChange={(e) => set({ descriptor: e.target.value })} placeholder="e.g. IS, EU" /></Field>
-          {s.variant === 'hero' && <Field label="Descriptor 2"><Input value={s.descriptor2} onChange={(e) => set({ descriptor2: e.target.value })} placeholder="e.g. Solution" /></Field>}
-          <Field label="Variant"><SegmentedToggle size="sm" value={s.variant} onChange={(v) => set({ variant: v })} options={VARIANTS} /></Field>
-          <Field label="Scale"><SegmentedToggle size="sm" value={s.scale} onChange={(v) => set({ scale: v })} options={SCALES} /></Field>
-        </div>
-        <div className="flex min-h-[320px] items-center justify-center overflow-auto rounded-lg border border-fg-08 text-emphasis">
-          <Lockup {...brand} {...s} />
-        </div>
-      </div>
-      {Object.entries(presets).map(([group, names]) => (
-        <div key={group}>
-          <Label>{group}</Label>
-          <div className="mt-2 grid grid-cols-[repeat(auto-fill,minmax(260px,1fr))] gap-3">
-            {names.map((n) => (
-              <button key={n} type="button" onClick={() => set({ product: n, descriptor: '', variant: 'horizontal' })}
-                className="flex min-h-[96px] cursor-pointer items-center justify-center overflow-hidden rounded-lg border border-fg-08 text-left text-emphasis hover:bg-fg-04">
-                <Lockup {...brand} product={n} scale="sm" />
-              </button>
-            ))}
-          </div>
-        </div>
-      ))}
-    </div>
-  )
+export default function LockupBuilder(props) {
+  return <LockupLab {...props} />
 }

package/src/LockupLab.jsx

@@ -0,0 +1,61 @@
+import { useState } from 'react'
+import { Input, Label, SegmentedToggle } from '@kolkrabbi/kol-component'
+import Lockup from './Lockup.jsx'
+
+/* taxonomy-ok: organism — the lockup generator: name / descriptor / variant / scale controls beside a Lockup stage, preset rows below */
+
+/**
+ * LockupLab — A product lockup, generated from a name. Was `LockupBuilder` — renamed into the lab family beside TypeLab,
+ * ColorLab and ComboLab (BrandLabToolGaps, 2026-10-29); the props are the same. Type a product name, add descriptors, pick a variant and scale; the presets run a
+ * brand's naming levels through the same Lockup.
+ *
+ * Carried from kol-atlas `components/lockup/LiveLockup.jsx` (2026-10-20); the parent, the mark, the
+ * face and the presets are the brand's, passed in.
+ *
+ * @param {string}    parent    the parent brand name
+ * @param {ReactNode} mark      the mark (see Lockup)
+ * @param {string}    font      CSS font-family for the names
+ * @param {Object}    presets   `{ [level]: string[] }` — e.g. `{ Products: ['Hosting', …] }`
+ * @param {string}    className classes on the root
+ */
+const VARIANTS = [{ value: 'horizontal', label: 'Horizontal' }, { value: 'hero', label: 'Hero' }, { value: 'wordmark', label: 'Wordmark' }]
+const SCALES = ['sm', 'md', 'lg', 'xl'].map((s) => ({ value: s, label: s.toUpperCase() }))
+
+const Field = ({ label, children }) => <div className="flex flex-col gap-2"><Label>{label}</Label>{children}</div>
+
+export default function LockupLab({ parent = 'Brand', mark, font, presets = {}, className = '' }) {
+  const first = Object.values(presets)[0]?.[0] ?? ''
+  const [s, setS] = useState({ product: first, descriptor: '', descriptor2: '', variant: 'horizontal', scale: 'lg' })
+  const set = (patch) => setS((p) => ({ ...p, ...patch }))
+  const brand = { parent, mark, font }
+
+  return (
+    <div className={`flex flex-col gap-6 ${className}`.trim()}>
+      <div className="grid gap-6 md:grid-cols-[300px_minmax(0,1fr)]">
+        <div className="flex flex-col gap-5 self-start rounded-lg border border-fg-08 p-5">
+          <Field label="Product name"><Input value={s.product} onChange={(e) => set({ product: e.target.value })} placeholder="e.g. Hosting" /></Field>
+          <Field label="Descriptor"><Input value={s.descriptor} onChange={(e) => set({ descriptor: e.target.value })} placeholder="e.g. IS, EU" /></Field>
+          {s.variant === 'hero' && <Field label="Descriptor 2"><Input value={s.descriptor2} onChange={(e) => set({ descriptor2: e.target.value })} placeholder="e.g. Solution" /></Field>}
+          <Field label="Variant"><SegmentedToggle size="sm" value={s.variant} onChange={(v) => set({ variant: v })} options={VARIANTS} /></Field>
+          <Field label="Scale"><SegmentedToggle size="sm" value={s.scale} onChange={(v) => set({ scale: v })} options={SCALES} /></Field>
+        </div>
+        <div className="flex min-h-[320px] items-center justify-center overflow-auto rounded-lg border border-fg-08 text-emphasis">
+          <Lockup {...brand} {...s} />
+        </div>
+      </div>
+      {Object.entries(presets).map(([group, names]) => (
+        <div key={group}>
+          <Label>{group}</Label>
+          <div className="mt-2 grid grid-cols-[repeat(auto-fill,minmax(260px,1fr))] gap-3">
+            {names.map((n) => (
+              <button key={n} type="button" onClick={() => set({ product: n, descriptor: '', variant: 'horizontal' })}
+                className="flex min-h-[96px] cursor-pointer items-center justify-center overflow-hidden rounded-lg border border-fg-08 text-left text-emphasis hover:bg-fg-04">
+                <Lockup {...brand} product={n} scale="sm" />
+              </button>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/TypeLab.jsx

@@ -0,0 +1,108 @@
+import { useState } from 'react'
+import { Dropdown, Input } from '@kolkrabbi/kol-component'
+import { DEFAULT_TYPE_LAB, TYPE_CASES, TYPE_FACES, TYPE_INKS, TYPE_RATIOS, TYPE_STEPS, typeLab } from './typeLab.js'
+
+/* taxonomy-ok: organism — the type generator: base + ratio controls, a spec row and live sample per step, the roles table */
+
+/**
+ * TypeLab — A brand's type, generated. A base size and a musical ratio set every step; each step's line height is the
+ * brand's to tune; sixteen roles sit on the steps, each with its face, weight, tracking, case and ink (`typeLab.js`).
+ * Was `TypeScaleLab` (carried from kol-atlas's Typography page, 2026-10-20), which stopped at sizes — renamed into the lab
+ * family and grown to a brand's whole type (BrandLabToolGaps, kol-atlas 2026-10-29). The faces are the BRAND's, passed in —
+ * the lab never sets KOL's type.
+ *
+ * @param {Object}   value     `{ base, ratio, leading, roles }` — controlled; omit for internal
+ * @param {Function} onChange  `(next) => void`
+ * @param {Object}   faces     `{ display, heading, text, mono }` — `{ family, label, weight }` each
+ * @param {Object}   samples   `{ headline, text }` — the sample strings
+ * @param {string}   className classes on the root
+ */
+const LABEL = 'kol-helper-10 tracking-widest text-meta uppercase'
+const FACES = {
+  display: { family: 'var(--kol-font-family-sans-narrow)', label: 'Right Grotesk Narrow', weight: 500 },
+  heading: { family: 'var(--kol-font-family-sans-compact)', label: 'Right Grotesk Compact', weight: 500 },
+  text: { family: 'var(--kol-font-family-sans)', label: 'Right Grotesk', weight: 400 },
+  mono: { family: 'var(--kol-font-family-mono)', label: 'JetBrains Mono', weight: 400 },
+}
+const SAMPLES = {
+  headline: 'The quick brown fox jumps over the lazy dog',
+  text: 'A modular scale sets every size from one base and one ratio, so the steps keep the same proportion from the smallest note to the largest headline.',
+}
+const INK = { emphasis: 'var(--kol-fg-emphasis)', strong: 'var(--kol-fg-strong)', lede: 'var(--kol-fg-lede)', body: 'var(--kol-fg-body)', meta: 'var(--kol-fg-meta)' }
+const CASE = { none: 'none', upper: 'uppercase', lower: 'lowercase', title: 'capitalize' }
+const opts = (list) => list.map((x) => ({ value: x, label: x }))
+
+export default function TypeLab({ value: valueProp, onChange, faces = FACES, samples = SAMPLES, className = '' }) {
+  const [own, setOwn] = useState(DEFAULT_TYPE_LAB)
+  const value = { ...DEFAULT_TYPE_LAB, ...(valueProp ?? own) }
+  const set = (patch) => { const next = { ...value, ...patch }; if (valueProp === undefined) setOwn(next); onChange?.(next) }
+  const setRole = (id, patch) => set({ roles: { ...value.roles, [id]: { ...value.roles?.[id], ...patch } } })
+  const t = typeLab(value)
+  const face = (k) => ({ ...FACES[k], ...faces[k] })
+
+  return (
+    <div className={`flex flex-col gap-10 ${className}`.trim()}>
+      <div className="flex flex-col gap-6">
+        <div className="flex max-w-[724px] flex-col gap-2">
+          <h3 className="m-0 kol-sans-heading-04 text-emphasis">{t.ratio.label} {t.ratio.note}</h3>
+          <p className="m-0 kol-sans-body-02 text-fg-80">{t.ratio.about}</p>
+        </div>
+        <div className="flex flex-wrap items-end gap-x-8 gap-y-4">
+          <div className="flex flex-col gap-2"><span className={LABEL}>Base</span><Input type="number" size="sm" unit="px" chars={4} value={value.base} onChange={(e) => { const v = Number(e.target.value); if (v >= 8 && v <= 32) set({ base: v }) }} /></div>
+          <div className="flex flex-col gap-2"><span className={LABEL}>Ratio</span><Dropdown size="sm" value={t.ratio.id} onChange={(v) => set({ ratio: v })} options={TYPE_RATIOS.map((x) => ({ value: x.id, label: `${x.label} · ${x.note}` }))} /></div>
+        </div>
+        {/* the spec rows keep their columns on a phone and scroll sideways */}
+        <div className="overflow-x-auto overscroll-x-contain"><div className="min-w-[760px]">
+          {t.steps.map((s) => {
+            const f = face(s.face)
+            return (
+              <div key={s.id} className="border-t border-fg-08 py-5">
+                <div className="mb-3 grid grid-cols-[120px_minmax(0,1.4fr)_minmax(0,1.8fr)_repeat(3,minmax(0,1fr))_auto] items-center gap-x-6">
+                  <span className={LABEL}>{s.role}</span>
+                  <code className="kol-doc-code-inline justify-self-start whitespace-nowrap">--type-{s.id}</code>
+                  <span className={LABEL}>{f.label}</span>
+                  <span className={LABEL}>W: {f.weight}</span>
+                  <span className={LABEL}>S: <span className="normal-case">{s.size}px</span></span>
+                  <span className={LABEL}>LH: <span className="normal-case">{s.lh}px</span></span>
+                  {/* the step's line-height factor, the brand's to tune */}
+                  <Input type="number" size="sm" chars={4} step={0.05} aria-label={`${s.role} line height`} value={s.k}
+                    onChange={(e) => { const k = Number(e.target.value); if (k >= 0.8 && k <= 2.4) set({ leading: { ...value.leading, [s.id]: k } }) }} />
+                </div>
+                <p className="m-0 truncate text-emphasis" style={{ fontFamily: f.family, fontWeight: f.weight, fontSize: s.size, lineHeight: `${s.lh}px` }}>
+                  {s.face === 'text' ? samples.text : samples.headline}
+                </p>
+              </div>
+            )
+          })}
+        </div></div>
+      </div>
+
+      <section className="flex flex-col gap-3">
+        <h3 className="m-0 kol-eyebrow text-fg-80">Roles</h3>
+        <p className="m-0 max-w-[724px] kol-sans-body-03 text-meta">What the brand sets text as: each role on a step, in a face, with its weight, tracking, case and ink.</p>
+        <div className="overflow-x-auto overscroll-x-contain"><div className="min-w-[960px]">
+          <div className="grid grid-cols-[100px_repeat(6,minmax(0,1fr))_minmax(0,2.2fr)] items-center gap-x-4 border-b border-fg-08 pb-2">
+            {['Role', 'Step', 'Face', 'Weight', 'Tracking %', 'Case', 'Ink', 'Sample'].map((h) => <span key={h} className={LABEL}>{h}</span>)}
+          </div>
+          {t.roles.map((r) => {
+            const f = face(r.face)
+            return (
+              <div key={r.id} className="grid grid-cols-[100px_repeat(6,minmax(0,1fr))_minmax(0,2.2fr)] items-center gap-x-4 border-b border-fg-08 py-2">
+                <span className={LABEL}>{r.label}</span>
+                <Dropdown size="sm" value={r.step} onChange={(v) => setRole(r.id, { step: v })} options={TYPE_STEPS.map((s) => ({ value: s.id, label: s.role }))} />
+                <Dropdown size="sm" value={r.face} onChange={(v) => setRole(r.id, { face: v })} options={opts(TYPE_FACES)} />
+                <Input type="number" size="sm" chars={4} step={100} aria-label={`${r.label} weight`} value={r.weight} onChange={(e) => { const w = Number(e.target.value); if (w >= 100 && w <= 900) setRole(r.id, { weight: w }) }} />
+                <Input type="number" size="sm" chars={4} step={0.5} aria-label={`${r.label} tracking`} value={Math.round(r.tracking * 1000) / 10} onChange={(e) => { const p = Number(e.target.value); if (p >= -10 && p <= 30) setRole(r.id, { tracking: p / 100 }) }} />
+                <Dropdown size="sm" value={r.case} onChange={(v) => setRole(r.id, { case: v })} options={opts(TYPE_CASES)} />
+                <Dropdown size="sm" value={r.ink} onChange={(v) => setRole(r.id, { ink: v })} options={opts(TYPE_INKS)} />
+                <span className="truncate" style={{ fontFamily: f.family, fontWeight: r.weight, fontSize: Math.min(r.size, 40), lineHeight: 1.2, letterSpacing: `${r.tracking}em`, textTransform: CASE[r.case], color: INK[r.ink] }}>
+                  {r.label} {r.size}/{r.lh}
+                </span>
+              </div>
+            )
+          })}
+        </div></div>
+      </section>
+    </div>
+  )
+}

package/src/TypeScaleLab.jsx

@@ -1,71 +1,10 @@
-import { useState } from 'react'
-import { Dropdown, Input } from '@kolkrabbi/kol-component'
-import { DEFAULT_TYPE_SCALE, TYPE_RATIOS, typeScale } from './typeScale.js'
-
-/* taxonomy-ok: organism — the type-scale generator: base + ratio controls over a spec row and a live sample per step */
+import TypeLab from './TypeLab.jsx'
 
 /**
- * TypeScaleLab — a modular type scale to try ratios on.
- *
- * Carried from kol-atlas's Typography page (2026-10-20). A base size and a musical ratio set every
- * step (`typeScale.js`); each row is a spec label (role · token · face · weight · size · line height)
- * over a live sample. The faces are the BRAND's, passed in — the lab never sets KOL's type.
- *
- * @param {Object}   value     `{ base, ratio }` — controlled; omit for internal
- * @param {Function} onChange  `(next) => void`
- * @param {Object}   faces     `{ display, heading, text }` — `{ family, label, weight }` each
- * @param {Object}   samples   `{ headline, text }` — the sample strings
- * @param {string}   className classes on the root
+ * @deprecated 2026-10-29 — `TypeLab` (the lab family's name, BrandLabToolGaps), which also sets the roles. Same value
+ * (`{ base, ratio }` still works); drops when nobody imports it (04-retirements.md).
+ * TypeScaleLab — A brand's type, generated. The old name of TypeLab.
  */
-const LABEL = 'kol-helper-10 tracking-widest text-meta uppercase'
-const FACES = {
-  display: { family: 'var(--kol-font-family-sans-narrow)', label: 'Right Grotesk Narrow', weight: 500 },
-  heading: { family: 'var(--kol-font-family-sans-compact)', label: 'Right Grotesk Compact', weight: 500 },
-  text: { family: 'var(--kol-font-family-sans)', label: 'Right Grotesk', weight: 400 },
-}
-const SAMPLES = {
-  headline: 'The quick brown fox jumps over the lazy dog',
-  text: 'A modular scale sets every size from one base and one ratio, so the steps keep the same proportion from the smallest note to the largest headline.',
-}
-
-export default function TypeScaleLab({ value: valueProp, onChange, faces = FACES, samples = SAMPLES, className = '' }) {
-  const [own, setOwn] = useState(DEFAULT_TYPE_SCALE)
-  const value = valueProp ?? own
-  const set = (patch) => { const next = { ...value, ...patch }; if (valueProp === undefined) setOwn(next); onChange?.(next) }
-  const r = TYPE_RATIOS.find((x) => x.id === value.ratio) ?? TYPE_RATIOS[3]
-  const face = (k) => ({ ...FACES[k], ...faces[k] })
-
-  return (
-    <div className={`flex flex-col gap-6 ${className}`.trim()}>
-      <div className="flex max-w-[724px] flex-col gap-2">
-        <h3 className="m-0 kol-sans-heading-04 text-emphasis">{r.label} {r.note}</h3>
-        <p className="m-0 kol-sans-body-02 text-fg-80">{r.about}</p>
-      </div>
-      <div className="flex flex-wrap items-end gap-x-8 gap-y-4">
-        <div className="flex flex-col gap-2"><span className={LABEL}>Base</span><Input type="number" size="sm" unit="px" chars={4} value={value.base} onChange={(e) => { const v = Number(e.target.value); if (v >= 8 && v <= 32) set({ base: v }) }} /></div>
-        <div className="flex flex-col gap-2"><span className={LABEL}>Ratio</span><Dropdown size="sm" value={r.id} onChange={(v) => set({ ratio: v })} options={TYPE_RATIOS.map((x) => ({ value: x.id, label: `${x.label} · ${x.note}` }))} /></div>
-      </div>
-      {/* the spec rows keep their columns on a phone and scroll sideways */}
-      <div className="overflow-x-auto overscroll-x-contain"><div className="min-w-[720px]">
-        {typeScale(value).map((s) => {
-          const f = face(s.face)
-          return (
-            <div key={s.id} className="border-t border-fg-08 py-5">
-              <div className="mb-3 grid grid-cols-[120px_minmax(0,1.6fr)_minmax(0,2fr)_repeat(3,minmax(0,1fr))] items-center gap-x-6">
-                <span className={LABEL}>{s.role}</span>
-                <code className="kol-doc-code-inline justify-self-start whitespace-nowrap">--type-{s.id}</code>
-                <span className={LABEL}>{f.label}</span>
-                <span className={LABEL}>W: {f.weight}</span>
-                <span className={LABEL}>S: <span className="normal-case">{s.size}px</span></span>
-                <span className={LABEL}>LH: <span className="normal-case">{s.lh}px</span></span>
-              </div>
-              <p className="m-0 truncate text-emphasis" style={{ fontFamily: f.family, fontWeight: f.weight, fontSize: s.size, lineHeight: `${s.lh}px` }}>
-                {s.face === 'text' ? samples.text : samples.headline}
-              </p>
-            </div>
-          )
-        })}
-      </div></div>
-    </div>
-  )
+export default function TypeScaleLab(props) {
+  return <TypeLab {...props} />
 }

package/src/colorLab.js

@@ -10,6 +10,15 @@
  *             Multiply (darker) of the base over itself at 50%, applied once and twice.
  *   Slots     four brand slots, two dark and two light, picked from any swatch.
  *   Mix       60 / 30 / 10 by area, following Light · Secondary · Primary until a share has its own pick.
+ *
+ * A COLOUR DEFINITION, NOT ONLY A PALETTE (BrandLabToolGaps, kol-atlas 2026-10-29), and renamed into the lab family
+ * (`colorLab` · `colorLabCss` · `DEFAULT_COLOR_LAB`; `deriveColorLab` is its old name):
+ *   Contrast  every colour against the brand's own ink — the Brand black slot on light, the Light slot on dark — with
+ *             its WCAG ratio and grade (`contrastRatio` · `contrastGrade` · `inkOn`).
+ *   Ink       the brand's text levels, emphasis · strong · lede · body · meta, from its ink at KOL's opacities, for light
+ *             and for dark — a brand no longer borrows `--kol-fg-*`.
+ *   Dark      the slots swapped (the dark slots become the ground), and each role and composition share moved along its
+ *             own blend ramp until it passes AA on the dark ground.
  */
 import { generateHarmony, hexToHsl, hslToHex } from '@kolkrabbi/kol-component'
 
@@ -47,8 +56,41 @@ export const DEFAULT_COLOR_LAB = {
   slots: null, picks: [null, null, null],
 }
 
-/** everything the lab draws, from its value */
-export function deriveColorLab(value) {
+/* ── contrast (WCAG 2) ── */
+const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+const luminance = (hex) => { const [r, g, b] = toRgb(hex).map(lin); return 0.2126 * r + 0.7152 * g + 0.0722 * b }
+/** the WCAG contrast ratio of two hex colours, 1 … 21 */
+export function contrastRatio(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((m, n) => n - m)
+  return (x + 0.05) / (y + 0.05)
+}
+/** `AAA` (7) · `AA` (4.5) · `AA large` (3) · `fail` — the grade for body text, large text at 3 */
+export const contrastGrade = (ratio) => (ratio >= 7 ? 'AAA' : ratio >= 4.5 ? 'AA' : ratio >= 3 ? 'AA large' : 'fail')
+/** the brand's ink that reads best on `hex`, its ratio and grade — `inks` is `{ dark, light }` */
+export function inkOn(hex, inks) {
+  const [ink, ratio] = [inks.dark, inks.light].map((i) => [i, contrastRatio(hex, i)]).sort((m, n) => n[1] - m[1])[0]
+  return { ink, ratio, grade: contrastGrade(ratio) }
+}
+
+/* the brand's text levels at KOL's opacities (kol-opacity.css: emphasis full, strong 80, lede 72, body 64, meta 48) */
+export const INK_LEVELS = [['emphasis', 1], ['strong', 0.8], ['lede', 0.72], ['body', 0.64], ['meta', 0.48]]
+const alpha = (hex, a) => (a >= 1 ? hex : `${hex}${Math.round(a * 255).toString(16).padStart(2, '0').toUpperCase()}`)
+const inkRamp = (hex) => Object.fromEntries(INK_LEVELS.map(([id, a]) => [id, alpha(hex, a)]))
+/* the ink at its opacity over its ground, as the eye sees it — what its contrast is measured on */
+const over = (fg, bg, a) => toHex(toRgb(fg).map((c, i) => c * a + toRgb(bg)[i] * (1 - a)))
+const inkContrast = (hex, ground) => Object.fromEntries(INK_LEVELS.map(([id, a]) => {
+  const r = contrastRatio(over(hex, ground, a), ground)
+  return [id, { ratio: r, grade: contrastGrade(r) }]
+}))
+
+/* a role on the dark ground: along its own blend ramp from the base toward the lightest, the first step at AA */
+const forDark = (hex, ground) => {
+  const ramp = blendRamp(hex)
+  return [2, 1, 0].map((i) => ramp[i]).find((x) => contrastRatio(x, ground) >= 4.5) ?? ramp[0]
+}
+
+/** everything the lab draws, from its value — `deriveColorLab` before 2026-10-29 */
+export function colorLab(value) {
   const v = { ...DEFAULT_COLOR_LAB, ...value }
   const { h, s, l } = hexToHsl(v.base)
   const hues = Array.from({ length: 10 }, (_, i) => { const hh = (h + i * 36) % 360; return { name: hueName(hh), hex: hslToHex(hh, s, l).toUpperCase() } })
@@ -59,23 +101,44 @@ export function deriveColorLab(value) {
   const roles = generateHarmony(v.base, v.harmony)
   const mix = [slots[2], roles[1], roles[0]].map((hex, i) => v.picks?.[i] ?? hex)
   const ramps = hues.map((x) => ({ ...x, steps: blendRamp(x.hex) }))
-  return { ...v, h, s, l, hues, blueGrey, grey, slots, roles, mix, ramps }
+  /* the ink: Brand black on the light ground, Light on the dark one */
+  const inks = { dark: slots[1], light: slots[2] }
+  const darkSlots = [slots[2], slots[3], slots[0], slots[1]]
+  const darkGround = darkSlots[2]
+  const dark = {
+    slots: darkSlots,
+    roles: roles.map((x) => forDark(x, darkGround)),
+    mix: [darkGround, forDark(mix[1], darkGround), forDark(mix[2], darkGround)],
+  }
+  const ink = { light: inkRamp(inks.dark), dark: inkRamp(inks.light) }
+  const inkGrades = { light: inkContrast(inks.dark, slots[2]), dark: inkContrast(inks.light, darkGround) }
+  return { ...v, h, s, l, hues, blueGrey, grey, slots, roles, mix, ramps, inks, ink, inkGrades, dark }
 }
+/** @deprecated 2026-10-29 — `colorLab` (the lab family's name) */
+export const deriveColorLab = colorLab
 
 const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
 
-/** the lab's result as CSS custom properties — one `:root` block, brand-prefixed */
-export function colorLabCss(value, prefix = 'brand') {
-  const c = deriveColorLab(value)
+/** the lab's result as CSS custom properties — brand-prefixed: the `:root` block (roles, slots, mix, ink, the ramps), then
+ *  the dark block under `darkSelector` (roles, slots, mix and ink for the dark ground) */
+export function colorLabCss(value, prefix = 'brand', { darkSelector = '[data-theme="dark"]' } = {}) {
+  const c = colorLab(value)
   const line = (name, hex) => `  --${prefix}-${name}: ${hex};`
+  const themed = (t, ink) => [
+    ...COLOR_ROLES.map((r, i) => line(`role-${slug(r)}`, t.roles[i])),
+    ...COLOR_SLOTS.map((r, i) => line(`slot-${slug(r)}`, t.slots[i])),
+    ...COLOR_MIX.map(([, label], i) => line(`mix-${slug(label).replace(/^\d+-/, '')}`, t.mix[i])),
+    ...INK_LEVELS.map(([id]) => line(`ink-${id}`, ink[id])),
+  ]
   return [
     ':root {',
-    ...COLOR_ROLES.map((r, i) => line(`role-${slug(r)}`, c.roles[i])),
-    ...COLOR_SLOTS.map((r, i) => line(`slot-${slug(r)}`, c.slots[i])),
-    ...COLOR_MIX.map(([, label], i) => line(`mix-${slug(label).replace(/^\d+-/, '')}`, c.mix[i])),
+    ...themed(c, c.ink.light),
     ...c.ramps.flatMap((x) => x.steps.map((hex, i) => line(`${slug(x.name)}-${(i + 1) * 100}`, hex))),
     ...c.blueGrey.map((hex, i) => line(`blue-grey-${(i + 1) * 100}`, hex)),
     ...c.grey.map((hex, i) => line(`grey-${(i + 1) * 100}`, hex)),
     '}',
+    `${darkSelector} {`,
+    ...themed(c.dark, c.ink.dark),
+    '}',
   ].join('\n')
 }

package/src/comboLab.js

@@ -0,0 +1,34 @@
+/**
+ * comboLab — the math behind ComboLab in the lab family's shape (BrandLabToolGaps, kol-atlas 2026-10-29 — the user:
+ * *"the group of those tools that generate should ship together … and have unified name system"*): `comboLab` makes a
+ * palette, `comboLabCss` emits one, `DEFAULT_COMBO_LAB` is where ComboLab starts. The engine is `comboMath.js`'s
+ * `generatePalette`, unchanged.
+ *
+ * A palette is five roles — primary · secondary · light · dark · accent — the 60/30/10 composition's.
+ */
+import { generatePalette } from './comboMath.js'
+
+/* Canonical Kolkrabbi composition — yellow-300 / red-200 / cream-100 / blue-400 / orange-300 */
+export const DEFAULT_COMBO_LAB = {
+  id: 'kolkrabbi',
+  label: 'Kolkrabbi',
+  description: 'Yellow hero · rust secondary · navy ink on cream — the canonical composition',
+  primary: '#FFCF33',
+  secondary: '#AD5038',
+  light: '#FAF7F0',
+  dark: '#222D3D',
+  accent: '#DF760B',
+}
+export const COMBO_ROLES = ['primary', 'secondary', 'light', 'dark', 'accent']
+
+/** a new palette: from `pool` (hexes to sample) by `mode` (a GENERATION_MODES id), keeping the roles `locks` marks
+ *  (booleans in COMBO_ROLES order) from `current`; with no pool, seeded from `base` (default `current.primary`) */
+export function comboLab({ pool = [], mode = 'random', current = DEFAULT_COMBO_LAB, locks = [], base } = {}) {
+  const colors = generatePalette(pool, mode, COMBO_ROLES.map((r) => current[r]), locks, pool.length ? undefined : (base ?? current.primary))
+  return { ...current, id: 'generated', label: 'Generated', ...Object.fromEntries(COMBO_ROLES.map((r, i) => [r, colors[i] ?? current[r]])) }
+}
+
+/** a palette as CSS custom properties — `--<prefix>-combo-<role>` */
+export function comboLabCss(palette = DEFAULT_COMBO_LAB, prefix = 'brand') {
+  return [':root {', ...COMBO_ROLES.map((r) => `  --${prefix}-combo-${r}: ${palette[r]};`), '}'].join('\n')
+}

package/src/index.js

@@ -15,7 +15,7 @@ export { WEIGHTS, CUTS, CASES, familyFor } from './typographyCuts.js'
 export { default as LogoCard } from './LogoCard.jsx'
 export { default as ClearspaceDiagram, hasFramework } from './ClearspaceDiagram.jsx'
 export { default as LogoScaling } from './LogoScaling.jsx'
-export { default as ComboLab, DEFAULT_PALETTE } from './ComboLab.jsx'
+export { DEFAULT_PALETTE } from './ComboLab.jsx'
 export {
   RatioBar, Tower, QuadSplit, CardRow, StripeRow, AppliedCard,
   LAYOUT_COMPONENTS, COMBO_LAYOUTS,
@@ -27,6 +27,7 @@ export { generatePalette, fgOn, hexToHsl, hslToHex, GENERATION_MODES } from './c
 export { default as AssetCard } from './AssetCard.jsx'
 /* a folder's pages as the brand book's contents cards (plan-2026-10-28-document W5.2) */
 export { default as DocumentIndex } from './DocumentIndex.jsx'
+export { default as DocumentLibrary, DocumentView, DocumentFiles, DocumentMarkdown, useFileQuickLook } from './DocumentLibrary.jsx'
 /* print (PdfToolsFromStudio, 2026-10-28): A4 sheets for any content, and markdown to PDF · DOCX · MD on @kolkrabbi/kol-print */
 export { default as A4Pages } from './A4Pages.jsx'
 export { default as PrintStudio } from './PrintStudio.jsx'
@@ -60,11 +61,17 @@ export { brandSections, brandToc, brandInfo, BRAND_VIEWS, BOOK_SECTIONS, ASSET_S
 export { default as BrandGuide } from './BrandGuide.jsx'
 export { guideSections, guideToc } from './guideBook.js'
 
-// The brand lab (2026-10-20): the generators a brand is MADE with — carried from kol-atlas's Assets pages.
-// Each is controlled by one value, and the math is exported so a brand can be emitted without the UI.
-export { default as ColorLab } from './ColorLab.jsx'
-export { deriveColorLab, colorLabCss, blendRamp, neutralRamp, DEFAULT_COLOR_LAB, COLOR_ROLES, COLOR_SLOTS, COLOR_MIX } from './colorLab.js'
+// THE LAB (2026-10-20; one name system and its own subpath 2026-10-29, BrandLabToolGaps): the generators a brand is MADE
+// with — TypeLab · ColorLab · ComboLab · LockupLab, each `<x>Lab(value)` · `<x>LabCss` · `DEFAULT_<X>_LAB`. The same
+// names ship from `@kolkrabbi/kol-styleguide/lab`.
+export {
+  TypeLab, typeLab, typeLabCss, DEFAULT_TYPE_LAB, TYPE_RATIOS, TYPE_STEPS, TYPE_ROLES, TYPE_FACES, TYPE_CASES, TYPE_INKS,
+  ColorLab, colorLab, colorLabCss, DEFAULT_COLOR_LAB, COLOR_ROLES, COLOR_SLOTS, COLOR_MIX, INK_LEVELS, contrastRatio, contrastGrade, inkOn, blendRamp, neutralRamp,
+  ComboLab, comboLab, comboLabCss, DEFAULT_COMBO_LAB, COMBO_ROLES,
+  LockupLab, Lockup, LOCKUP_SCALES,
+} from './lab/index.js'
+// the names before the lab family (deprecated 2026-10-29, 04-retirements.md)
 export { default as TypeScaleLab } from './TypeScaleLab.jsx'
-export { typeScale, typeScaleCss, TYPE_RATIOS, TYPE_STEPS, DEFAULT_TYPE_SCALE } from './typeScale.js'
-export { default as Lockup, LOCKUP_SCALES } from './Lockup.jsx'
+export { typeScale, typeScaleCss, DEFAULT_TYPE_SCALE } from './typeLab.js'
+export { deriveColorLab } from './colorLab.js'
 export { default as LockupBuilder } from './LockupBuilder.jsx'

package/src/lab/index.js

@@ -0,0 +1,22 @@
+/* THE LAB — the generators a brand is MADE with, shipped together under one name system (BrandLabToolGaps, kol-atlas
+ * 2026-10-29 — the user: *"the group of those tools that generate should ship together with combolab and logo lockup
+ * generator, and have unified name system"*). `@kolkrabbi/kol-styleguide/lab`; the main barrel exports the same names.
+ *
+ *   <X>Lab          the generator's UI, controlled by one value
+ *   <x>Lab(value)   everything it draws, from the value
+ *   <x>LabCss(…)    the result as CSS custom properties
+ *   DEFAULT_<X>_LAB where it starts
+ *
+ *   type     TypeLab · typeLab · typeLabCss · DEFAULT_TYPE_LAB
+ *   colour   ColorLab · colorLab · colorLabCss · DEFAULT_COLOR_LAB
+ *   combo    ComboLab · comboLab · comboLabCss · DEFAULT_COMBO_LAB
+ *   lockup   LockupLab (it draws a lockup around the brand's mark; there is no value to emit) */
+export { default as TypeLab } from '../TypeLab.jsx'
+export { typeLab, typeLabCss, DEFAULT_TYPE_LAB, TYPE_RATIOS, TYPE_STEPS, TYPE_ROLES, TYPE_FACES, TYPE_CASES, TYPE_INKS } from '../typeLab.js'
+export { default as ColorLab } from '../ColorLab.jsx'
+export { colorLab, colorLabCss, DEFAULT_COLOR_LAB, COLOR_ROLES, COLOR_SLOTS, COLOR_MIX, INK_LEVELS, contrastRatio, contrastGrade, inkOn, blendRamp, neutralRamp } from '../colorLab.js'
+export { default as ComboLab } from '../ComboLab.jsx'
+export { comboLab, comboLabCss, DEFAULT_COMBO_LAB, COMBO_ROLES } from '../comboLab.js'
+export { GENERATION_MODES } from '../comboMath.js'
+export { default as LockupLab } from '../LockupLab.jsx'
+export { default as Lockup, LOCKUP_SCALES } from '../Lockup.jsx'

package/src/typeLab.js

@@ -0,0 +1,125 @@
+/**
+ * typeLab — the math behind TypeLab: a brand's type, from a base size and a ratio to every role it sets.
+ *
+ * Carried from kol-atlas `components/graphics/ScaleLab.jsx` (2026-10-20) as `typeScale`; grown into a brand's whole type
+ * definition and renamed into the lab family (BrandLabToolGaps, kol-atlas 2026-10-29 — the user: *"the group of those
+ * tools that generate should ship together … and have unified name system"*: `TypeLab` · `typeLab` · `typeLabCss` ·
+ * `DEFAULT_TYPE_LAB`, beside the colour, combo and lockup labs).
+ *
+ *   Steps   base × ratio^n, rounded to a whole px; the line height is the step's factor × size, snapped up to the 4px
+ *           grid. The factor is 1.2 for display and headings, 1.5 for text, and the brand's to tune (`leading`).
+ *   Roles   what a brand sets text AS — sixteen, each on a step with its face (display · heading · text · mono), weight,
+ *           tracking, case and ink (the colour lab's text levels). `roles` overrides any of them.
+ *
+ * The ramp owes nothing to KOL's own type scale — it is a brand's.
+ */
+export const TYPE_RATIOS = [
+  { id: 'M2', label: 'Major 2nd', ratio: 9 / 8, note: '9:8', about: 'The gentlest step, with neighbouring sizes close together. It suits dense interfaces and long documents, where hierarchy comes from weight and spacing more than from size.' },
+  { id: 'm3', label: 'Minor 3rd', ratio: 6 / 5, note: '6:5', about: 'A modest step with clear but quiet contrast between levels. It works for product interfaces and editorial text that need order and calm rather than drama.' },
+  { id: 'M3', label: 'Major 3rd', ratio: 5 / 4, note: '5:4', about: 'A balanced step and a common default for websites. Headings stand apart from body text, while the largest sizes stay practical for headlines and page titles.' },
+  { id: 'P4', label: 'Perfect 4th', ratio: 4 / 3, note: '4:3', about: 'A confident step with strong contrast between levels. It suits marketing pages and brand material, where headlines lead and body text supports them below.' },
+  { id: 'A4', label: 'Augmented 4th', ratio: Math.SQRT2, note: '1:√2', about: 'The ratio of A-series paper, set between a fourth and a fifth. Its large jumps read as deliberate and architectural, suited to print and structured layouts.' },
+  { id: 'P5', label: 'Perfect 5th', ratio: 3 / 2, note: '3:2', about: 'A wide step, with few sizes far apart. It suits posters, decks and expressive layouts, where display type carries the page and body text stays secondary.' },
+  { id: 'G', label: 'Golden ratio', ratio: (1 + Math.sqrt(5)) / 2, note: '1:φ', about: 'The widest step here, where sizes grow fast. It is best kept to display and editorial work, since the text end of the scale thins out quickly.' },
+]
+
+/* step n from the base; `face` is which of the brand's faces sets it, `k` the default line-height factor */
+export const TYPE_STEPS = [
+  { id: 'display-1', role: 'Display 1', n: 6, face: 'display', k: 1.2 },
+  { id: 'display-2', role: 'Display 2', n: 5, face: 'display', k: 1.2 },
+  { id: 'heading-1', role: 'Heading 1', n: 4, face: 'display', k: 1.2 },
+  { id: 'heading-2', role: 'Heading 2', n: 3, face: 'heading', k: 1.2 },
+  { id: 'heading-3', role: 'Heading 3', n: 2, face: 'heading', k: 1.2 },
+  { id: 'heading-4', role: 'Heading 4', n: 1, face: 'heading', k: 1.2 },
+  { id: 'body', role: 'Body', n: 0, face: 'text', k: 1.5 },
+  { id: 'small', role: 'Small', n: -1, face: 'text', k: 1.5 },
+]
+
+export const TYPE_FACES = ['display', 'heading', 'text', 'mono']
+export const TYPE_CASES = ['none', 'upper', 'lower', 'title']
+/* the colour lab's ink levels (colorLab `INK_LEVELS`), strongest first */
+export const TYPE_INKS = ['emphasis', 'strong', 'lede', 'body', 'meta']
+
+/* THE ROLES (kol-atlas apps/lab roles.css, 2026-10-29): sixteen roles on the eight steps — several share one. Tracking
+ * is in em (−0.015 = −1.5 %). */
+export const TYPE_ROLES = [
+  { id: 'display-1', label: 'Display 1', step: 'display-1', face: 'display', weight: 700, tracking: -0.02, case: 'none', ink: 'emphasis' },
+  { id: 'display-2', label: 'Display 2', step: 'display-2', face: 'display', weight: 700, tracking: -0.02, case: 'none', ink: 'emphasis' },
+  { id: 'h1', label: 'Heading 1', step: 'heading-1', face: 'display', weight: 700, tracking: -0.015, case: 'none', ink: 'emphasis' },
+  { id: 'h2', label: 'Heading 2', step: 'heading-2', face: 'heading', weight: 600, tracking: -0.01, case: 'none', ink: 'emphasis' },
+  { id: 'h3', label: 'Heading 3', step: 'heading-3', face: 'heading', weight: 600, tracking: -0.005, case: 'none', ink: 'emphasis' },
+  { id: 'h4', label: 'Heading 4', step: 'heading-4', face: 'heading', weight: 600, tracking: 0, case: 'none', ink: 'emphasis' },
+  { id: 'h5', label: 'Heading 5', step: 'body', face: 'heading', weight: 600, tracking: 0, case: 'none', ink: 'emphasis' },
+  { id: 'h6', label: 'Heading 6', step: 'small', face: 'heading', weight: 600, tracking: 0, case: 'none', ink: 'strong' },
+  { id: 'quote', label: 'Quote', step: 'heading-4', face: 'heading', weight: 400, tracking: 0, case: 'none', ink: 'lede' },
+  { id: 'lead', label: 'Lead', step: 'heading-4', face: 'text', weight: 400, tracking: 0, case: 'none', ink: 'lede' },
+  { id: 'body', label: 'Body', step: 'body', face: 'text', weight: 400, tracking: 0, case: 'none', ink: 'body' },
+  { id: 'small', label: 'Small', step: 'small', face: 'text', weight: 400, tracking: 0, case: 'none', ink: 'body' },
+  { id: 'caption', label: 'Caption', step: 'small', face: 'text', weight: 400, tracking: 0, case: 'none', ink: 'meta' },
+  { id: 'eyebrow', label: 'Eyebrow', step: 'small', face: 'mono', weight: 500, tracking: 0.08, case: 'upper', ink: 'meta' },
+  { id: 'label', label: 'Label', step: 'small', face: 'mono', weight: 500, tracking: 0.04, case: 'upper', ink: 'body' },
+  { id: 'data', label: 'Data', step: 'small', face: 'mono', weight: 400, tracking: 0, case: 'none', ink: 'body' },
+]
+
+const GRID = 4
+/** the lab's starting value; `leading` (stepId → factor) and `roles` (roleId → partial role) override the defaults */
+export const DEFAULT_TYPE_LAB = { base: 16, ratio: 'P4', leading: {}, roles: {} }
+
+/** everything the lab draws, from its value: `{ ...value, ratio, steps, roles }` — steps with `size` and `lh` in px, roles
+ *  resolved onto their step */
+export function typeLab(value) {
+  const v = { ...DEFAULT_TYPE_LAB, ...value }
+  const ratio = TYPE_RATIOS.find((x) => x.id === v.ratio) ?? TYPE_RATIOS[3]
+  const steps = TYPE_STEPS.map((s) => {
+    const k = v.leading?.[s.id] ?? s.k
+    const size = Math.round(v.base * ratio.ratio ** s.n)
+    return { ...s, k, size, lh: Math.ceil((size * k) / GRID) * GRID }
+  })
+  const roles = TYPE_ROLES.map((r) => {
+    const role = { ...r, ...v.roles?.[r.id] }
+    const step = steps.find((s) => s.id === role.step) ?? steps[6]
+    return { ...role, size: step.size, lh: step.lh }
+  })
+  return { ...v, ratio, steps, roles }
+}
+
+const CASE_CSS = { none: 'none', upper: 'uppercase', lower: 'lowercase', title: 'capitalize' }
+
+/** the type as CSS: the faces, each step's size and line height, each role's settings as variables, and a `.type-<role>`
+ *  class per role that reads them. `faces` (`{ display: { family }, … }`) fills the family variables; the ink reads the
+ *  colour lab's `--<inkPrefix>-ink-<level>` */
+export function typeLabCss(value, { prefix = 'type', faces = value?.faces, inkPrefix = 'brand' } = {}) {
+  const t = typeLab(value)
+  const v = (name, val) => `  --${prefix}-${name}: ${val};`
+  return [
+    ':root {',
+    ...TYPE_FACES.filter((f) => faces?.[f]?.family).map((f) => v(`face-${f}`, faces[f].family)),
+    ...t.steps.flatMap((s) => [v(`${s.id}-size`, `${s.size}px`), v(`${s.id}-lh`, `${s.lh}px`)]),
+    ...t.roles.flatMap((r) => [
+      v(`${r.id}-weight`, r.weight),
+      v(`${r.id}-tracking`, `${r.tracking}em`),
+    ]),
+    '}',
+    ...t.roles.map((r) => [
+      `.${prefix}-${r.id} {`,
+      `  font-family: var(--${prefix}-face-${r.face});`,
+      `  font-size: var(--${prefix}-${r.step}-size);`,
+      `  line-height: var(--${prefix}-${r.step}-lh);`,
+      `  font-weight: var(--${prefix}-${r.id}-weight);`,
+      `  letter-spacing: var(--${prefix}-${r.id}-tracking);`,
+      `  text-transform: ${CASE_CSS[r.case] ?? 'none'};`,
+      `  color: var(--${inkPrefix}-ink-${r.ink});`,
+      '}',
+    ].join('\n')),
+  ].join('\n')
+}
+
+/* ── the names before the lab family (deprecated 2026-10-29, on the retirement ledger) ── */
+/** @deprecated use `typeLab(value).steps` */
+export const typeScale = (value) => typeLab(value).steps
+/** @deprecated use `typeLabCss` — this emits the steps alone, as it did */
+export function typeScaleCss(value, prefix = 'type') {
+  return [':root {', ...typeScale(value).flatMap((s) => [`  --${prefix}-${s.id}-size: ${s.size}px;`, `  --${prefix}-${s.id}-lh: ${s.lh}px;`]), '}'].join('\n')
+}
+/** @deprecated use DEFAULT_TYPE_LAB */
+export const DEFAULT_TYPE_SCALE = { base: 16, ratio: 'P4' }

package/src/typeScale.js

@@ -1,45 +0,0 @@
-/**
- * typeScale — a modular type scale from two inputs: a base size and a musical ratio.
- *
- * Carried from kol-atlas `components/graphics/ScaleLab.jsx` (2026-10-20). Each step is base × ratio^n,
- * rounded to a whole px; line heights snap up to the 4px grid (1.2 for display and headings, 1.5 for
- * text). The ramp owes nothing to KOL's own type scale — it is a brand's.
- */
-export const TYPE_RATIOS = [
-  { id: 'M2', label: 'Major 2nd', ratio: 9 / 8, note: '9:8', about: 'The gentlest step, with neighbouring sizes close together. It suits dense interfaces and long documents, where hierarchy comes from weight and spacing more than from size.' },
-  { id: 'm3', label: 'Minor 3rd', ratio: 6 / 5, note: '6:5', about: 'A modest step with clear but quiet contrast between levels. It works for product interfaces and editorial text that need order and calm rather than drama.' },
-  { id: 'M3', label: 'Major 3rd', ratio: 5 / 4, note: '5:4', about: 'A balanced step and a common default for websites. Headings stand apart from body text, while the largest sizes stay practical for headlines and page titles.' },
-  { id: 'P4', label: 'Perfect 4th', ratio: 4 / 3, note: '4:3', about: 'A confident step with strong contrast between levels. It suits marketing pages and brand material, where headlines lead and body text supports them below.' },
-  { id: 'A4', label: 'Augmented 4th', ratio: Math.SQRT2, note: '1:√2', about: 'The ratio of A-series paper, set between a fourth and a fifth. Its large jumps read as deliberate and architectural, suited to print and structured layouts.' },
-  { id: 'P5', label: 'Perfect 5th', ratio: 3 / 2, note: '3:2', about: 'A wide step, with few sizes far apart. It suits posters, decks and expressive layouts, where display type carries the page and body text stays secondary.' },
-  { id: 'G', label: 'Golden ratio', ratio: (1 + Math.sqrt(5)) / 2, note: '1:φ', about: 'The widest step here, where sizes grow fast. It is best kept to display and editorial work, since the text end of the scale thins out quickly.' },
-]
-
-/* step n from the base; `face` is which of the brand's faces sets it, `k` the line-height factor */
-export const TYPE_STEPS = [
-  { id: 'display-1', role: 'Display 1', n: 6, face: 'display', k: 1.2 },
-  { id: 'display-2', role: 'Display 2', n: 5, face: 'display', k: 1.2 },
-  { id: 'heading-1', role: 'Heading 1', n: 4, face: 'display', k: 1.2 },
-  { id: 'heading-2', role: 'Heading 2', n: 3, face: 'heading', k: 1.2 },
-  { id: 'heading-3', role: 'Heading 3', n: 2, face: 'heading', k: 1.2 },
-  { id: 'heading-4', role: 'Heading 4', n: 1, face: 'heading', k: 1.2 },
-  { id: 'body', role: 'Body', n: 0, face: 'text', k: 1.5 },
-  { id: 'small', role: 'Small', n: -1, face: 'text', k: 1.5 },
-]
-
-const GRID = 4
-export const DEFAULT_TYPE_SCALE = { base: 16, ratio: 'P4' }
-
-/** the steps for `{ base, ratio }` (ratio is a TYPE_RATIOS id) — each with `size` and `lh` in px */
-export function typeScale({ base, ratio } = DEFAULT_TYPE_SCALE) {
-  const r = (TYPE_RATIOS.find((x) => x.id === ratio) ?? TYPE_RATIOS[3]).ratio
-  return TYPE_STEPS.map((s) => {
-    const size = Math.round(base * r ** s.n)
-    return { ...s, size, lh: Math.ceil((size * s.k) / GRID) * GRID }
-  })
-}
-
-/** the scale as CSS custom properties — `--<prefix>-<step>-size` / `-lh` */
-export function typeScaleCss(value, prefix = 'type') {
-  return [':root {', ...typeScale(value).flatMap((s) => [`  --${prefix}-${s.id}-size: ${s.size}px;`, `  --${prefix}-${s.id}-lh: ${s.lh}px;`]), '}'].join('\n')
-}