@kolkrabbi/kol-styleguide 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Brand guide components and the brand tool",
   "license": "MIT",
@@ -8,7 +8,8 @@
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./src/*": "./src/*"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.188.0",
@@ -19,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.237.0",
-    "@kolkrabbi/kol-icons": "^0.33.0",
-    "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-theme": "^0.163.0"
+    "@kolkrabbi/kol-framework": "^0.57.0",
+    "@kolkrabbi/kol-component": "^0.305.0",
+    "@kolkrabbi/kol-icons": "^0.47.0",
+    "@kolkrabbi/kol-theme": "^0.191.0"
   },
   "files": [
     "src",

package/src/BrandBook.jsx

@@ -148,7 +148,7 @@ function TypographySection({ s, brand }) {
       <Prose blocks={s.blocks} />
       {/* Sans italic at display size — real italic cuts, fired by plain font-style: italic. */}
       <div className="mt-12 flex flex-col gap-2 py-3 border-b border-fg-08">
-        <span className="kol-helper-12 text-meta uppercase tracking-wider">
+        <span className="kol-mono-12 text-meta uppercase tracking-wider">
           .kol-prose-display-md · sans narrow · roman + italic
         </span>
         <p className="kol-prose-display-md m-0">

package/src/BrandGuide.jsx

@@ -0,0 +1,313 @@
+/* BrandGuide — kol-branding's guide renderer (src/template/book/BrandBook.jsx + Brand.jsx, 2026-10-24), carried
+ * class-for-class for the brand guide outline (BrandGuideOutlineTwoVersions, kol-hq 2026-10-27). Two changes, both
+ * because a package cannot carry them: the research line under each chapter (`Source`, kol-branding's own citations)
+ * stays there, and the Contents card is an in-page anchor only (no router in this package). */
+import { useState } from 'react'
+import { ColorRamp, ContentCollection, DocsToc, FullscreenOverlay, Table } from '@kolkrabbi/kol-component'
+import { Icon } from '@kolkrabbi/kol-icons'
+import PageHero from '@kolkrabbi/kol-framework/src/PageHero.jsx'
+import PageSection from '@kolkrabbi/kol-framework/src/PageSection.jsx'
+import LogoCard from './LogoCard.jsx'
+import AssetTable from './AssetTable.jsx'
+import AssetCard from './AssetCard.jsx'
+import BrandMark from './BrandMark.jsx'
+import { BrandAvatar } from './SocialMocks.jsx'
+import { BusinessCardBack, BusinessCardFront, EmailSignature, Envelope, Letterhead } from './StationeryMocks.jsx'
+import { brandInfo, STATIONERY_MARKS, BRANDED_ASSET_ROWS, scrollToAnchor, svgDims, downloadRecolored } from './brandBook.js'
+import { guideSections, guideToc, stopHex, contrast } from './guideBook.js'
+
+/* taxonomy-ok: organism — a brand guide: PageHero + one PageSection per chapter, each chapter the same anatomy, the chapters on a rail */
+
+/**
+ * BrandGuide — A brand guide. one scrolling page: the hero, then one chapter per row of the list it is handed, with the
+ * chapters on a rail. Every chapter has one anatomy — eyebrow · title · lede · prose · rules · the specimen its `kind`
+ * draws · spec table · do / don't · word list · closing prose — and only the specimen differs by kind. The outline is
+ * `@kolkrabbi/kol-brand-template`'s `GUIDE_SECTIONS`; its blank copy is `GUIDE_TEMPLATE`.
+ *
+ * @param {Object}   brand        a brand manifest (`@kolkrabbi/kol-brand-template` schema; `book` carries the copy)
+ * @param {Array}    sections     the chapter list (see `GUIDE_SECTIONS` for a row)
+ * @param {Function} Logo         optional mark component, `<Logo variant="wordmark" />`
+ * @param {Object}   logoSources  `{ [logoId]: rawSvg }` — drawn when no `Logo` is given
+ * @param {Object}   structure    `{ [logoId]: { logo, grid, keyline } }` raw svgs — Lockups' clear-space toggle
+ * @param {string}   className    classes on the root
+ */
+export default function BrandGuide({ brand, sections, Logo, logoSources, structure, className = '' }) {
+  const list = guideSections(brand, sections)
+  const mark = (id, props) => <BrandMark id={id} Logo={Logo} sources={logoSources} {...props} />
+  const index = list.filter((s) => s.nav)
+  return (
+    /* `xl:pr-32` — the rail is `position: fixed` on the right edge from xl up, and the pages' grids
+       run to the frame's edge; the padding keeps the last column out from under it */
+    <div className={`xl:pr-32 ${className}`.trim()}>
+      {list.map((s) => (s.kind === 'hero'
+        ? <PageHero key={s.key} id={s.id} label={s.label} title={s.title} lede={s.lede} />
+        : <Chapter key={s.key} s={s} brand={brand} mark={mark} index={index} logoSources={logoSources} structure={structure} />))}
+      <DocsToc variant="rail" toc={guideToc(brand, sections)} onNavigate={scrollToAnchor} className="hidden xl:flex" />
+    </div>
+  )
+}
+
+function Chapter({ s, brand, mark, index, logoSources, structure }) {
+  const Specimen = SPECIMENS[s.kind ?? 'prose']
+  return (
+    <PageSection id={s.id} label={s.label} title={s.title} body={s.lede}>
+      <Prose blocks={s.blocks} />
+      {s.rules?.length > 0 && <Rules items={s.rules} />}
+      {Specimen && <Specimen s={s} brand={brand} mark={mark} index={index} logoSources={logoSources} structure={structure} />}
+      {s.spec && <Spec spec={s.spec} />}
+      {(s.dos?.length > 0 || s.donts?.length > 0) && <Pair left={{ title: 'Do', items: s.dos }} right={{ title: "Don't", items: s.donts }} />}
+      {s.words && <Pair left={{ title: 'Words we use', items: s.words.use }} right={{ title: 'Words we avoid', items: s.words.avoid }} />}
+      <Prose blocks={s.after} />
+    </PageSection>
+  )
+}
+
+/** Book copy → `.kol-prose`: a string is a paragraph, `{ h }` a sub-heading, `{ lead, text }` a
+ *  paragraph opening on a bold lead. `head` renders inside the same block, after the copy. */
+function Prose({ blocks, head, className = 'mt-12' }) {
+  if (!blocks?.length && !head) return null
+  return (
+    <div className={`kol-prose ${className}`}>
+      {(blocks ?? []).map((b, i) => {
+        if (typeof b === 'string') return <p key={i}>{b}</p>
+        if (b.h) return <h3 key={i}>{b.h}</h3>
+        return <p key={i}><strong>{b.lead}</strong> {b.text}</p>
+      })}
+      {head}
+    </div>
+  )
+}
+
+/* The rules, as a list in the prose voice. */
+function Rules({ items }) {
+  return <div className="kol-prose mt-8"><ul>{items.map((r, i) => <li key={i}>{r}</li>)}</ul></div>
+}
+
+/* Two lists side by side — do / don't, use / avoid. */
+/* Two lists side by side (do / don't, words). A side with no items is left out; the titles are labels, not headings. */
+function Pair({ left, right }) {
+  const cols = [left, right].filter((c) => c.items?.length)
+  if (!cols.length) return null
+  return (
+    <div className="mt-16 grid grid-cols-1 gap-8 md:grid-cols-2 max-w-panel">
+      {cols.map(({ title, items }) => (
+        <div key={title} className="flex flex-col gap-3">
+          <h3 className="kol-prose-label m-0">{title}</h3>
+          <div className="kol-prose"><ul>{items.map((t, i) => <li key={i}>{t}</li>)}</ul></div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/* A measured spec — columns and rows from the manifest, on the DS table. */
+function Spec({ spec }) {
+  const columns = spec.columns.map((h, i) => ({ accessor: `c${i}`, header: h, wrap: true }))
+  const rows = spec.rows.map((r, n) => Object.fromEntries([['id', n], ...r.map((v, i) => [`c${i}`, v])]))
+  return <Table variant="simple" caption={spec.caption ?? 'Specification'} columns={columns} rows={rows} className="mt-8" />
+}
+
+/* The contents: every indexed chapter as a row, its eyebrow carrying the number; grouped by `part` when the list has parts. */
+function Contents({ index }) {
+  if (!index.length) return null
+  const parts = [...new Set(index.map((s) => s.part ?? ''))]
+  const row = (s) => (
+    <li key={s.id}>
+      <IndexCard href={`#${s.id}`} onClick={scrollToAnchor} label={s.label} title={s.title ?? s.nav} />
+    </li>
+  )
+  return (
+    <div className="mt-12 flex flex-col gap-10 max-w-panel">
+      {parts.map((p) => (
+        <div key={p || 'all'} className="flex flex-col gap-4">
+          {p && <h3 className="kol-prose-label m-0">{p}</h3>}
+          <ul className="m-0 grid list-none grid-cols-1 gap-2 p-0 md:grid-cols-2">{index.filter((s) => (s.part ?? '') === p).map(row)}</ul>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/* The book's index card — the Contents row: a label, the title, one small line and the arrow (kol-branding's IndexCard,
+ * the in-page anchor half). */
+function IndexCard({ href, onClick, label, title, meta }) {
+  return (
+    <a href={href} onClick={onClick} className="kol-card kol-card-interactive flex items-center justify-between gap-4 px-4 py-3 no-underline group">
+      <span className="flex min-w-0 flex-col gap-1">
+        {label && <span className="kol-mono-12 text-meta uppercase">{label}</span>}
+        <span className="kol-mono-14 text-emphasis">{title}</span>
+        {meta && <span className="kol-mono-10 text-meta mt-1">{meta}</span>}
+      </span>
+      <Icon name="arrow-right" size={16} className="shrink-0 text-oq-48 group-hover:text-emphasis transition-colors" />
+    </a>
+  )
+}
+
+/* ── the specimens, by kind ───────────────────────────────────────────────────────────────────── */
+
+function Marks({ s, mark }) {
+  return <div className="kol-grid mt-12">{(s.marks ?? []).map((id) => <LogoCard key={id} logo={mark(id)} frame={false} />)}</div>
+}
+
+/* A raw svg string as a layer node — ClearspaceDiagram stretches the svg inside to its box. */
+const Raw = ({ svg }) => <span dangerouslySetInnerHTML={{ __html: svg }} />
+
+/* With a mark's construction (`structure[id]`) the card draws the padded diagram and offers the clear-space toggle. */
+function Lockups({ s, brand, mark, structure }) {
+  return (
+    <div className="mt-12 grid grid-cols-1 gap-6 md:grid-cols-2 max-w-panel">
+      {(s.marks ?? []).map((id) => {
+        const st = structure?.[id]
+        return (
+          <LogoCard key={id} logo={st ? <Raw svg={st.logo} /> : mark(id)} grid={st && <Raw svg={st.grid} />} keyline={st && <Raw svg={st.keyline} />}
+            caption={brand?.logos?.find((l) => l.id === id)?.name ?? id} className="[&_figcaption]:uppercase" />
+        )
+      })}
+    </div>
+  )
+}
+
+/* Colour — one compact ramp row per family (its name, its role, the anchor dot), then the approved pairs with their contrast. */
+function Color({ s, brand }) {
+  const ramps = brand?.ramps ?? []
+  return (
+    <>
+      {/* chips at one fixed height instead of ColorRamp's squares, so a family is a strip, not a screen */}
+      <div className="mt-12 max-w-panel [&_.aspect-square]:aspect-auto [&_.aspect-square]:h-14">
+        {ramps.map((r) => (
+          <ColorRamp key={r.id} label={r.label} note={r.note} anchor={`${r.id}-${r.anchor}`}
+            colors={(r.stops ?? []).map((st) => [`${r.id}-${st.stop}`, st.value])} />
+        ))}
+      </div>
+      {s.pairs?.length > 0 && <Pairs pairs={s.pairs} brand={brand} />}
+    </>
+  )
+}
+
+/* Approved text / background pairs, contrast computed from the ramps — the accessibility rule, kept where the values are. */
+function Pairs({ pairs, brand }) {
+  const grade = (r) => (r >= 7 ? 'AAA' : r >= 4.5 ? 'AA' : r >= 3 ? 'AA, large text only' : 'fails')
+  const rows = pairs.map((p, i) => {
+    const [t, b] = [stopHex(brand, p.text), stopHex(brand, p.bg)]
+    const r = contrast(t, b)
+    return { id: i, text: `${p.text}${t ? ` · ${t}` : ''}`, bg: `${p.bg}${b ? ` · ${b}` : ''}`, ratio: r ? `${r.toFixed(2)} : 1` : '—', passes: r ? grade(r) : '—', use: p.use ?? '' }
+  })
+  const columns = [{ accessor: 'text', header: 'Text' }, { accessor: 'bg', header: 'Background' }, { accessor: 'ratio', header: 'Contrast' }, { accessor: 'passes', header: 'WCAG 2' }, { accessor: 'use', header: 'Use', wrap: true }]
+  return <Table variant="simple" caption="Approved color pairs" columns={columns} rows={rows} className="mt-8" />
+}
+
+/* Type — the brand's families, each set in its own cut. The brand's scale is copy (`spec` or `after`), not KOL's system. */
+function Typography({ brand }) {
+  const families = brand?.type?.families ?? []
+  if (!families.length) return null
+  return (
+    <div className="mt-12 flex flex-col gap-6">
+      {families.map((f) => (
+        <div key={f.token} className="flex flex-col gap-2 border-b border-fg-08 py-3">
+          <span className="kol-mono-12 text-meta uppercase tracking-wider">{f.token}</span>
+          <span className="text-emphasis" style={{ fontFamily: `var(${f.token})`, fontSize: 28 }}>{f.cut}</span>
+          <span className="kol-mono-12 text-subtle">{f.role}</span>
+        </div>
+      ))}
+      {brand?.type?.note && <p className="kol-mono-14 text-meta m-0">{brand.type.note}</p>}
+    </div>
+  )
+}
+
+/* The pair the Logos table's Color column swings between. */
+const INK_TOKENS = { ink: '--kol-surface-on-primary', surface: '--kol-surface-primary' }
+
+/* The logo asset table — ink toggle, zoom, recoloured download. */
+function LogosTable({ brand, mark, logoSources }) {
+  const [zoom, setZoom] = useState(null)
+  const rows = (brand?.logos ?? []).map((logo) => {
+    const raw = logoSources?.[logo.id]
+    return {
+      id: logo.id, name: logo.id.replace(/-/g, ' / '), preview: mark(logo.id), previewWidth: logo.previewWidth ?? 48,
+      path: logo.file?.replace(/^\.\//, ''), format: 'SVG', dimensions: svgDims(raw), raw,
+      onDownload: raw ? (row, ink) => downloadRecolored(row.raw, ink, `${logo.id}.svg`) : undefined,
+    }
+  })
+  return (
+    <>
+      <AssetTable caption="Logos" rows={rows} inkTokens={INK_TOKENS} onPreviewZoom={(row, ink) => setZoom({ row, ink })} className="mt-8" />
+      <FullscreenOverlay open={!!zoom} onClose={() => setZoom(null)}>
+        {zoom && <span className="inline-flex items-center p-12" style={{ color: zoom.ink, width: 'min(60vw, 480px)' }}>{zoom.row.preview}</span>}
+      </FullscreenOverlay>
+    </>
+  )
+}
+
+const TokenName = ({ children }) => <code className="kol-helper-12 text-emphasis">{children}</code>
+const brandedAssetCols = [
+  { accessor: 'item', header: 'Item', render: (r) => <TokenName>{r.item}</TokenName> },
+  { accessor: 'aspect', header: 'Aspect' },
+  { accessor: 'surface', header: 'Surface' },
+  { accessor: 'status', header: 'Status', render: (r) => <span className="kol-helper-12 text-meta uppercase tracking-widest">{r.status}</span> },
+  { accessor: 'note', header: 'Note' },
+]
+function Branded() {
+  return <Table variant="simple" caption="Branded assets" columns={brandedAssetCols} rows={BRANDED_ASSET_ROWS} className="mt-8" />
+}
+
+/* Stationery — the five mocks with the manifest's marks and contact details. */
+function Stationery({ brand, mark }) {
+  const marks = { ...STATIONERY_MARKS, ...(brand?.stationery?.marks ?? {}) }
+  const info = brandInfo(brand)
+  return (
+    <div className="kol-grid mt-8">
+      <div className="col-span-2"><AssetCard caption="Business card, front"><div className="aspect-[85/55]"><BusinessCardFront mark={mark(marks.card, { className: 'max-h-[70%]' })} /></div></AssetCard></div>
+      <div className="col-span-2"><AssetCard caption="Envelope"><div className="aspect-[220/110]"><Envelope mark={mark(marks.envelope)} info={info} /></div></AssetCard></div>
+      <div className="col-span-2 flex flex-col gap-3">
+        <AssetCard caption="Business card, back"><div className="aspect-[85/55]"><BusinessCardBack info={info} /></div></AssetCard>
+        <AssetCard caption="Email signature"><EmailSignature mark={mark(marks.signature)} info={info} /></AssetCard>
+      </div>
+      <div className="col-span-2"><AssetCard caption="Letterhead"><div className="aspect-[210/297]"><Letterhead mark={mark(marks.letter, { style: { height: '100%', width: 'auto' } })} info={info} /></div></AssetCard></div>
+    </div>
+  )
+}
+
+/* Social — one frame per template at its ratio; the image when the manifest has one, the mark on a plain ground when not. */
+function Social({ brand, mark }) {
+  const templates = brand?.social?.templates ?? []
+  if (!templates.length) return null
+  return (
+    <ContentCollection cols={3} className="mt-8 items-start">
+      {templates.map(({ caption, ratio, src }) => (
+        <AssetCard key={caption ?? src} caption={caption}>
+          <div className={`relative overflow-hidden ${src ? '' : 'bg-fg-08'}`} style={{ aspectRatio: ratio }}>
+            {src && <img src={src} alt="" loading="lazy" className="absolute inset-0 h-full w-full object-cover" />}
+            {src && <div className="absolute inset-x-0 bottom-0 h-1/3 bg-gradient-to-t from-black/60 to-transparent" aria-hidden="true" />}
+            <div className={`absolute bottom-[6%] left-[6%] w-[42%] ${src ? 'text-fg-inverse' : 'text-emphasis'}`}>
+              {mark(brand.social.mark ?? 'wordmark', { title: brand?.meta?.name })}
+            </div>
+          </div>
+        </AssetCard>
+      ))}
+    </ContentCollection>
+  )
+}
+
+function Profile({ brand, mark }) {
+  const avatars = brand?.social?.avatars ?? []
+  const marks = { ...STATIONERY_MARKS, ...(brand?.stationery?.marks ?? {}) }
+  if (!avatars.length) return null
+  return (
+    <div className="kol-grid mt-8 items-start">
+      {avatars.map(({ bg, polarity }, i) => <AssetCard key={i}><BrandAvatar mark={mark(marks.avatar, { className: 'w-1/2' })} bg={bg} polarity={polarity} /></AssetCard>)}
+    </div>
+  )
+}
+
+const SPECIMENS = {
+  contents: Contents,
+  logo: Marks,
+  lockups: Lockups,
+  color: Color,
+  typography: Typography,
+  'logos-table': LogosTable,
+  branded: Branded,
+  stationery: Stationery,
+  social: Social,
+  profile: Profile,
+}

package/src/ColorLab.jsx

@@ -0,0 +1,144 @@
+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'
+
+/* 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.
+ *
+ * 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
+ * a brand and emit it as CSS without rendering the lab.
+ *
+ * @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
+ */
+const LABEL = 'kol-helper-10 tracking-widest text-meta uppercase'
+const BARE_SWITCH = '[&>.toggle-switch-label]:hidden'
+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)
+
+function Swatch({ hex, name, selected, onClick, info }) {
+  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 }}>
+      <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>
+      </span>
+    </button>
+  )
+}
+
+const Row = ({ children }) => <div className="grid grid-cols-10 gap-2" style={{ maxWidth: ROW_MAX }}>{children}</div>
+
+const Switch = ({ label, checked, onChange }) => (
+  <span className="flex items-center gap-2"><span className={LABEL}>{label}</span><ToggleSwitch size="sm" className={BARE_SWITCH} checked={checked} onChange={onChange} /></span>
+)
+
+function Section({ title, info, onInfo, extra, children }) {
+  return (
+    <section className="flex flex-col gap-3">
+      <div className="flex items-center gap-6">
+        <h3 className="m-0 kol-eyebrow text-fg-80">{title}</h3>
+        {onInfo && <Switch label="Info" checked={info} onChange={onInfo} />}
+        {extra}
+      </div>
+      {children}
+    </section>
+  )
+}
+
+export default function ColorLab({ value: valueProp, onChange, className = '' }) {
+  const [own, setOwn] = useState(DEFAULT_COLOR_LAB)
+  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 infoFor = (k) => ({ info: info[k], onInfo: (v) => setInfo((x) => ({ ...x, [k]: v })) })
+  const c = deriveColorLab(value)
+
+  /* a swatch click fills the selected slot (0–3) or composition share (4–6) */
+  const assign = (hex) => {
+    if (slot === null) return
+    if (slot >= 4) set({ picks: [0, 1, 2].map((i) => (i === slot - 4 ? hex : value.picks?.[i] ?? null)) })
+    else set({ slots: c.slots.map((v, i) => (i === slot ? hex : v)) })
+    setSlot(null)
+  }
+  const toggleSlot = (i) => setSlot(slot === i ? null : i)
+  const picked = (hex) => c.slots.includes(hex)
+
+  return (
+    <div className={`flex flex-col gap-10 ${className}`.trim()}>
+      <Section title="Harmony">
+        <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>
+        <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>
+      </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>
+      </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>
+        {[['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>
+          </div>
+        ))}
+      </Section>
+
+      <Section title="Ramps" {...infoFor('ramps')}>
+        <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)} />
+          }))}
+        </Row>
+      </Section>
+
+      <Section title="Composition" {...infoFor('mix')}>
+        <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]) }}>
+                <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>
+            ))}
+          </div>
+          <div className="mt-6 grid grid-cols-1 gap-6 sm:grid-cols-3">
+            {COLOR_MIX.map(([, label, note], i) => (
+              <div key={label}>
+                <div className="mb-1.5 flex items-center gap-2.5">
+                  <span className="size-4 rounded-[3px] border border-fg-16" style={{ background: c.mix[i] }} />
+                  <span className="kol-sans-body-02 text-emphasis">{label}</span>
+                </div>
+                <p className="m-0 kol-sans-body-03 text-meta">{note}</p>
+              </div>
+            ))}
+          </div>
+        </div>
+      </Section>
+    </div>
+  )
+}

package/src/Lockup.jsx

@@ -0,0 +1,93 @@
+/* taxonomy-ok: molecule — a mark beside a parent name, a product name and descriptors */
+
+/**
+ * Lockup — A branded-house lockup of two names. The branded-house lockup: a parent name over a product name and an optional uppercase
+ * descriptor, beside the mark.
+ *
+ * Carried from kol-atlas `components/lockup/Lockup.jsx` (itself kol-client-canalix's branded-house
+ * Lockup), 2026-10-20 — the parent name, the mark and the face are props now, not Atlas's.
+ *
+ *   horizontal — mark + stacked column  ·  hero — big anatomy, framed mark, second descriptor  ·  wordmark — no mark
+ *
+ * Ink is currentColor, so it follows the surface. Without a `mark` a placeholder square stands in.
+ *
+ * @param {string}    parent       the parent brand name, e.g. "Kolkrabbi"
+ * @param {string}    product      the product name; empty → the parent takes the product slot (horizontal)
+ * @param {string}    descriptor   uppercase descriptor, e.g. "IS"
+ * @param {string}    descriptor2  hero only — a second descriptor
+ * @param {'sm'|'md'|'lg'|'xl'} scale
+ * @param {'horizontal'|'hero'|'wordmark'} variant
+ * @param {ReactNode} mark         the mark, drawn at the scale's mark size
+ * @param {string}    font         CSS font-family for the names; inherits by default
+ */
+export const LOCKUP_SCALES = {
+  sm: { mark: 32, wordmark: 12, product: 24, descriptor: 16, gap: 8, wordmarkLH: 16 },
+  md: { mark: 48, wordmark: 14, product: 36, descriptor: 24, gap: 12, wordmarkLH: 18 },
+  lg: { mark: 80, wordmark: 20, product: 56, descriptor: 36, gap: 16, wordmarkLH: 24 },
+  xl: { mark: 128, wordmark: 40, product: 96, descriptor: 56, gap: 20, wordmarkLH: 48 },
+}
+
+const parentCls = 'font-bold whitespace-nowrap'
+const productCls = 'font-bold leading-none whitespace-nowrap tracking-[-0.01em]'
+const descriptorCls = 'font-normal leading-none whitespace-nowrap uppercase tracking-[0.01em]'
+
+function Mark({ size, framed, mark }) {
+  return (
+    <div className={`shrink-0 box-border ${framed ? 'border border-current/16' : ''}`} style={{ width: size, height: size, padding: framed ? size * 0.12 : 0, borderRadius: framed ? Math.max(4, size * 0.08) : 0 }}>
+      {mark
+        ? <div className="flex size-full items-center justify-center [&_svg]:size-full">{mark}</div>
+        : <div className="size-full rounded-[18%] bg-current opacity-80" />}
+    </div>
+  )
+}
+
+export default function Lockup({ parent = 'Brand', product = '', descriptor = '', descriptor2 = '', scale = 'md', variant = 'horizontal', mark, font, className = '' }) {
+  const d = LOCKUP_SCALES[scale] ?? LOCKUP_SCALES.md
+  const style = font ? { fontFamily: font } : undefined
+
+  if (variant === 'hero') {
+    const x = LOCKUP_SCALES.xl
+    return (
+      <div className={`inline-flex items-start ${className}`.trim()} style={{ ...style, gap: x.gap * 1.5, padding: x.gap * 3 }}>
+        <Mark size={x.mark} framed mark={mark} />
+        <div className="flex flex-col justify-between" style={{ gap: x.gap }}>
+          <span className={parentCls} style={{ fontSize: x.wordmark }}>{parent}</span>
+          <div className="flex items-start" style={{ gap: x.gap * 0.75 }}>
+            <div className="flex flex-col" style={{ gap: x.gap * 0.5 }}>
+              {product && <span className={`${productCls} tracking-[-0.015em]`} style={{ fontSize: x.product }}>{product}</span>}
+              {descriptor && <span className={`${descriptorCls} font-medium opacity-40 text-right`} style={{ fontSize: x.descriptor }}>{descriptor}</span>}
+            </div>
+            {descriptor2 && <span className={`${descriptorCls} font-medium opacity-40`} style={{ fontSize: x.descriptor * 1.2, paddingTop: x.gap }}>{descriptor2}</span>}
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  const row = (
+    <div className="flex items-end" style={{ gap: d.gap / 2 }}>
+      {(product || variant === 'horizontal') && <span className={productCls} style={{ fontSize: d.product }}>{product || parent}</span>}
+      {descriptor && <span className={descriptorCls} style={{ fontSize: d.descriptor, paddingBottom: d.descriptor * 0.05 }}>{descriptor}</span>}
+    </div>
+  )
+
+  if (variant === 'wordmark') {
+    return (
+      <div className={`inline-flex flex-col items-start ${className}`.trim()} style={{ ...style, padding: d.gap * 2, gap: d.gap / 2 }}>
+        <span className={parentCls} style={{ fontSize: d.wordmark }}>{parent}</span>
+        {row}
+      </div>
+    )
+  }
+
+  /* horizontal: no product → the parent name takes the product slot */
+  return (
+    <div className={`inline-flex items-end ${className}`.trim()} style={{ ...style, gap: d.gap, padding: d.gap * 2 }}>
+      <Mark size={d.mark} mark={mark} />
+      <div className={`flex flex-col ${product ? 'justify-between' : 'justify-end'}`} style={{ minHeight: d.mark, gap: d.gap / 2 }}>
+        {product && <span className={parentCls} style={{ fontSize: d.wordmark, lineHeight: `${d.wordmarkLH}px` }}>{parent}</span>}
+        {row}
+      </div>
+    </div>
+  )
+}

package/src/LockupBuilder.jsx

@@ -0,0 +1,60 @@
+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 */
+
+/**
+ * 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
+ */
+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>
+  )
+}

package/src/TypeScaleLab.jsx

@@ -0,0 +1,71 @@
+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 */
+
+/**
+ * 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
+ */
+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>
+  )
+}

package/src/brandBook.js

@@ -16,6 +16,7 @@ export const BOOK_SECTIONS = [
   { key: 'hero', id: 'hero', label: 'brand guidelines', lede: 'Client-facing identity guidelines — chapter-structured for handoff. Mirrors the shape of the deliverable PDF.' },
   { key: 'overview', id: 'brand-overview', label: 'Overview', title: 'Chapters', lede: 'Each chapter is its own page. They read in order, but every one stands alone for handoff.' },
   { key: 'about', id: 'about', nav: 'About', label: '01 — about', copy: true },
+  { key: 'messages', id: 'key-messages', nav: 'Key messages', label: '01 — about · key messages', title: 'Key messages', copy: true },
   { key: 'tone', id: 'voice', nav: 'Tone', label: '02 — tone', title: 'Tone', copy: true },
   { key: 'look', id: 'look', nav: 'Look', label: '03 — look', title: 'Look', copy: true },
   { key: 'logo', id: 'logos-concept', nav: 'Logo', label: '04 — logos · concept', title: 'The mark', marks: ['wordmark', 'logomark'] },
@@ -29,8 +30,13 @@ export const ASSET_SECTIONS = [
   { key: 'logos', id: 'logos', nav: 'Logos', label: '01 — logos', title: 'Logos' },
   { key: 'branded', id: 'branded-assets', nav: 'Branded', label: '04 — branded', title: 'Branded assets' },
   { key: 'stationery', id: 'assets-stationery', nav: 'Stationery', label: '08 — assets · stationery', title: 'Stationery', lede: 'Standard correspondence — business card, envelope, letterhead, email signature. Quiet typography, generous space, monochrome restraint.' },
+  { key: 'labels', id: 'labels', nav: 'Labels', label: '09 — labels', title: 'Labels', copy: true },
+  { key: 'packaging', id: 'packaging', nav: 'Packaging', label: '10 — packaging', title: 'Packaging', copy: true },
+  { key: 'mockups', id: 'mockups', nav: 'Mockups', label: '11 — mockups', title: 'Mockups', copy: true },
   { key: 'social', id: 'social-sizes', nav: 'Social', label: '12 — social · sizes', title: 'Post sizes', lede: 'One template at each of the three Instagram aspect ratios — square feed (1:1), portrait feed (4:5), and story / reel (9:16). Editorial photography, restrained typography, a deliberate cadence.' },
   { key: 'profile', id: 'social-profile', nav: 'Profile', label: '13 — social · profile', title: 'Profile', lede: 'Avatar treatment for profile pictures across platforms — round-cropped on burgundy, signature centered.' },
+  { key: 'generators', id: 'generators', nav: 'Generators', label: '14 — generators', title: 'Generators', copy: true },
+  { key: 'deck', id: 'slide-deck', nav: 'Slide deck', label: '15 — slide deck', title: 'Slide deck', copy: true },
 ]
 
 /* the two pages, for a view switch */
@@ -47,6 +53,8 @@ function shows(s, brand) {
   if (s.copy) return hasCopy(s)
   if (s.key === 'color') return Boolean(brand?.ramps?.length) || hasCopy(s)
   if (s.key === 'logos') return Boolean(brand?.logos?.length)
+  /* the marks sections draw the manifest's logos — their default lede is not enough to show empty frames */
+  if (s.key === 'logo' || s.key === 'lockups') return Boolean(brand?.logos?.length || s.blocks?.length || s.after?.length)
   if (s.key === 'social') return Boolean(brand?.social?.templates?.length)
   if (s.key === 'profile') return Boolean(brand?.social?.avatars?.length)
   return true

package/src/colorLab.js

@@ -0,0 +1,81 @@
+/**
+ * colorLab — the math behind ColorLab: one base color + a harmony rule → the whole palette.
+ *
+ * Carried from kol-atlas `components/graphics/ColorLab.jsx` (2026-10-20), its store lifted out
+ * into a plain value so the lab is controlled and the result can be saved into a brand.
+ *
+ *   Palette   ten hues 36° apart at the base's saturation and lightness; blue-grey and grey ramps
+ *             of ten steps, each from its own base (blue-grey follows the base hue while linked).
+ *   Ramps     five steps per hue by the "Material Girl" blend: the base, Screen (lighter) and
+ *             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.
+ */
+import { generateHarmony, hexToHsl, hslToHex } from '@kolkrabbi/kol-component'
+
+/* the twelve standard hue names, 30° apart; hues 36° apart never share one */
+const HUE_NAMES = ['Red', 'Orange', 'Yellow', 'Chartreuse', 'Green', 'Spring', 'Cyan', 'Azure', 'Blue', 'Violet', 'Magenta', 'Rose']
+export const hueName = (h) => HUE_NAMES[Math.round(h / 30) % 12]
+
+const toRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
+const toHex = (rgb) => '#' + rgb.map((c) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, '0')).join('').toUpperCase()
+const screen = (c) => c + 0.5 * (1 - (1 - c) ** 2 - c)
+const multiply = (c) => c + 0.5 * (c * c - c)
+export const rgbText = (hex) => `rgb(${toRgb(hex).map((c) => Math.round(c * 255)).join(', ')})`
+
+/** five steps, 100 lightest … 500 darkest, the base at 300 */
+export function blendRamp(hex) {
+  const base = toRgb(hex)
+  const s1 = base.map(screen), m1 = base.map(multiply)
+  return [s1.map(screen), s1, base, m1, m1.map(multiply)].map(toHex)
+}
+
+/** ten steps of one hue and saturation, lightness 97 → 12 */
+export const neutralRamp = (h, s) => Array.from({ length: 10 }, (_, i) => hslToHex(h, s, Math.round(97 - i * 9.5)).toUpperCase())
+
+export const COLOR_SLOTS = ['Brand dark', 'Brand black', 'Light', 'Light 2']
+export const COLOR_ROLES = ['Primary', 'Secondary', 'Light', 'Dark', 'Accent']
+export const COLOR_MIX = [
+  [6, '60% Neutral', 'Surface, page canvas.'],
+  [3, '30% Secondary', 'Support. Blocks, containers, structural chrome.'],
+  [1, '10% Primary', 'Signature. Brand moment, CTA, identity plate.'],
+]
+
+/** the lab's starting value; `slots` / `picks` null means "follow the derived default" */
+export const DEFAULT_COLOR_LAB = {
+  base: '#3D7FF0', harmony: 'analogous', blueBase: '#6B7A99', greyBase: '#808080', blueLinked: true,
+  slots: null, picks: [null, null, null],
+}
+
+/** everything the lab draws, from its value */
+export function deriveColorLab(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() } })
+  const nb = hexToHsl(v.blueBase), ng = hexToHsl(v.greyBase)
+  const blueGrey = v.blueLinked ? neutralRamp(h, 20) : neutralRamp(nb.h, nb.s)
+  const grey = neutralRamp(ng.h, ng.s)
+  const slots = v.slots ?? [blueGrey[7], grey[9], grey[0], grey[1]]
+  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 }
+}
+
+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)
+  const line = (name, hex) => `  --${prefix}-${name}: ${hex};`
+  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])),
+    ...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)),
+    '}',
+  ].join('\n')
+}

package/src/guideBook.js

@@ -0,0 +1,56 @@
+/* The brand guide's chapter model — kol-branding's src/template/book/brandBook.js (2026-10-24), carried for `BrandGuide`
+ * (BrandGuideOutlineTwoVersions, 2026-10-27). The book owns no chapter list: it renders the one it is handed —
+ * `@kolkrabbi/kol-brand-template`'s `GUIDE_SECTIONS`, or a client's own. The helpers the identity book already
+ * exports (brandInfo, the stationery marks, the anchor scroll, the svg helpers) stay in ./brandBook.js. */
+
+const hasCopy = (s) => Boolean(s.lede || s.blocks?.length || s.after?.length || s.rules?.length || s.spec || s.dos?.length || s.donts?.length || s.words || s.pairs?.length)
+
+/* Whether a chapter has anything to show for this manifest. The specimen kinds need the data they draw;
+ * everything else shows when it has copy. */
+export function shows(s, brand) {
+  const kind = s.kind ?? 'prose'
+  if (kind === 'hero' || kind === 'contents' || kind === 'branded' || kind === 'stationery') return true
+  if (kind === 'logos-table') return Boolean(brand?.logos?.length)
+  if (kind === 'logo' || kind === 'lockups') return Boolean(brand?.logos?.length) || hasCopy(s)
+  if (kind === 'color') return Boolean(brand?.ramps?.length) || hasCopy(s)
+  if (kind === 'typography') return Boolean(brand?.type?.families?.length) || hasCopy(s)
+  if (kind === 'social') return Boolean(brand?.social?.templates?.length) || hasCopy(s)
+  if (kind === 'profile') return Boolean(brand?.social?.avatars?.length) || hasCopy(s)
+  return hasCopy(s)
+}
+
+/** The guide's chapters for a manifest — the list's rows merged with `brand.book`, the empty ones dropped. */
+export function guideSections(brand, sections = []) {
+  const name = brand?.meta?.name
+  return sections
+    .map((d) => {
+      const s = { ...d, ...(brand?.book?.[d.key] ?? {}) }
+      if (d.kind === 'hero' && !s.title) s.title = name
+      if (d.key === 'about' && !s.title && name) s.title = `About ${name}`
+      return s
+    })
+    .filter((s) => shows(s, brand))
+}
+
+/** The rail's entries — `[{ id, label }]`. */
+export const guideToc = (brand, sections) =>
+  guideSections(brand, sections).filter((s) => s.nav).map((s) => ({ id: s.id, label: s.nav }))
+
+/* The ramp stop a pair names (`teal-300`) → its hex, from the manifest's ramps. */
+export function stopHex(brand, ref) {
+  const m = /^(.*)-(\d+)$/.exec(ref ?? '')
+  if (!m) return undefined
+  return brand?.ramps?.find((r) => r.id === m[1])?.stops?.find((s) => String(s.stop) === m[2])?.value
+}
+
+/* WCAG 2 contrast ratio of two hexes — the number a color chapter's approved pairs carry. */
+export function contrast(hexA, hexB) {
+  const lum = (hex) => {
+    const n = parseInt(hex.replace('#', ''), 16)
+    const c = [16, 8, 0].map((sh) => ((n >> sh) & 255) / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]
+  }
+  if (!hexA || !hexB) return undefined
+  const [a, b] = [lum(hexA), lum(hexB)]
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
+}

package/src/index.js

@@ -49,3 +49,17 @@ export { default as Brand } from './Brand.jsx'
 export { default as BrandBook } from './BrandBook.jsx'
 export { default as BrandAssets } from './BrandAssets.jsx'
 export { brandSections, brandToc, brandInfo, BRAND_VIEWS, BOOK_SECTIONS, ASSET_SECTIONS } from './brandBook.js'
+
+// The brand guide (2026-10-27): kol-branding's guide renderer over a chapter list it is handed —
+// kol-brand-template's GUIDE_SECTIONS, blank (GUIDE_TEMPLATE) or filled by a client's manifest.
+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'
+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 { default as LockupBuilder } from './LockupBuilder.jsx'

package/src/typeScale.js

@@ -0,0 +1,45 @@
+/**
+ * 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')
+}