@kolkrabbi/kol-styleguide 0.4.0 → 0.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
-  "description": "KOL style-guide / brand-guide component set — the visual specimens a brand manual is built from: color anatomy + combination lab, logo construction / clearspace / scaling, mood tiles, type blocks, and asset spec tables. Raided from the apps/brand styleguide. Sits above @kolkrabbi/kol-{theme,icons,component}.",
+  "description": "KOL style-guide / brand-guide component set — the visual specimens a brand manual is built from: color anatomy + combination lab, logo construction / clearspace / scaling, mood tiles, type blocks, and asset spec tables. Raided from the apps/brand styleguide. Also the brand tool itself — `Brand` (BrandBook ⇄ BrandAssets) renders a whole brand book from one brand manifest. Sits above @kolkrabbi/kol-{theme,icons,component,framework}.",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -11,16 +11,18 @@
     ".": "./src/index.js"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.70.0",
+    "@kolkrabbi/kol-component": ">=0.188.0",
+    "@kolkrabbi/kol-framework": ">=0.39.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "@kolkrabbi/kol-theme": ">=0.53.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.182.0",
-    "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-theme": "^0.139.0"
+    "@kolkrabbi/kol-component": "^0.225.0",
+    "@kolkrabbi/kol-framework": "^0.44.0",
+    "@kolkrabbi/kol-icons": "^0.27.1",
+    "@kolkrabbi/kol-theme": "^0.151.0"
   },
   "files": [
     "src",

package/src/Brand.jsx

@@ -0,0 +1,42 @@
+import { useState } from 'react'
+import { DocsToc, ViewToggle } from '@kolkrabbi/kol-component'
+import BrandBook from './BrandBook.jsx'
+import BrandAssets from './BrandAssets.jsx'
+import { BRAND_VIEWS, brandToc, scrollToAnchor } from './brandBook.js'
+
+/* taxonomy-ok: organism — the brand tool: BrandBook ⇄ BrandAssets under a view switch, with the page's section rail */
+
+/**
+ * Brand — the whole brand tool: the brand book's two pages over one manifest, BRAND (the identity)
+ * and ASSETS (what you download or reproduce), a switch between them, and the page's sections on a
+ * rail. ONE component so every app that carries a brand renders the same tool (apps/brand alone,
+ * media-shell's Brand tab) — kol-notes' `Notes` shape.
+ *
+ * The manifest is `@kolkrabbi/kol-brand-template`'s schema; its `book` field carries the copy. The
+ * marks come from `Logo` (a component taking `variant`) or `logoSources` (id → raw SVG, which the
+ * Logos table also needs for dimensions and downloads — pass it either way).
+ *
+ * @param {Object}   brand        the manifest
+ * @param {Function} Logo         optional `<Logo variant="wordmark" />`
+ * @param {Object}   logoSources  `{ [logoId]: rawSvg }`
+ * @param {'brand'|'assets'} view · onViewChange   controlled page; or internal
+ * @param {string}   className    classes on the root
+ */
+export default function Brand({ brand, Logo, logoSources, view: viewProp, onViewChange, className = '' }) {
+  const [viewState, setViewState] = useState('brand')
+  const view = viewProp ?? viewState
+  const setView = (v) => { if (viewProp === undefined) setViewState(v); onViewChange?.(v) }
+  const Page = view === 'assets' ? BrandAssets : BrandBook
+
+  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()}>
+      <div className="kol-page flex justify-end pt-6 pb-0">
+        <ViewToggle variant="text" options={BRAND_VIEWS} viewMode={view} onViewChange={setView} />
+      </div>
+      <Page brand={brand} Logo={Logo} logoSources={logoSources} />
+      <DocsToc key={view} variant="rail" toc={brandToc(brand, view)} onNavigate={scrollToAnchor} className="hidden xl:flex" />
+    </div>
+  )
+}

package/src/BrandAssets.jsx

@@ -0,0 +1,152 @@
+import { useState } from 'react'
+import { ContentCollection, FullscreenOverlay, Table } from '@kolkrabbi/kol-component'
+import PageSection from '@kolkrabbi/kol-framework/src/PageSection.jsx'
+import AssetTable from './AssetTable.jsx'
+import AssetCard from './AssetCard.jsx'
+import { ProfileAvatar } from './SocialMocks.jsx'
+import { BusinessCardBack, BusinessCardFront, EmailSignature, Envelope, Letterhead } from './StationeryMocks.jsx'
+import BrandMark from './BrandMark.jsx'
+import { Prose, SectionIndex } from './BrandBook.jsx'
+import {
+  brandSections, brandInfo, STATIONERY_MARKS, BRANDED_ASSET_ROWS, svgDims, downloadRecolored,
+} from './brandBook.js'
+
+/* taxonomy-ok: organism — the brand book's assets page: PageSection chapters over AssetTable, Table, AssetCard and the stationery / social mocks */
+
+/* The pair the Logos table's Color column swings between. */
+const INK_TOKENS = { ink: '--kol-surface-on-primary', surface: '--kol-surface-primary' }
+
+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' },
+]
+
+/**
+ * BrandAssets — the ASSETS page of the brand tool: what you download or reproduce. Logos (the
+ * mark table, with the ink toggle, zoom and recoloured download), the branded-asset register,
+ * stationery, social post sizes and profile avatars.
+ *
+ * kol-olina's apps/brand `pages/assets/*`, carried class-for-class; the client's marks, contact
+ * details, templates and avatar grounds come from the manifest (`logos`, `meta`, `stationery.marks`,
+ * `social`). Sections with nothing to show are left out — see `brandSections`.
+ *
+ * @param {Object}   brand     a brand manifest (`@kolkrabbi/kol-brand-template` schema)
+ * @param {Function} Logo      optional mark component, `<Logo variant="wordmark" />`
+ * @param {Object}   logoSources  `{ [logoId]: rawSvg }` — the table's dimensions and downloads, and
+ *                             the marks themselves when no `Logo` is given
+ */
+export default function BrandAssets({ brand, Logo, logoSources }) {
+  const sections = brandSections(brand, 'assets')
+  const mark = (id, props) => <BrandMark id={id} Logo={Logo} sources={logoSources} {...props} />
+  const index = sections.filter((s) => s.nav)
+  const marks = { ...STATIONERY_MARKS, ...(brand?.stationery?.marks ?? {}) }
+  const info = brandInfo(brand)
+  const [zoom, setZoom] = useState(null)
+
+  const logoRows = (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 (
+    <>
+      {sections.map((s) => {
+        const head = { id: s.id, label: s.label, title: s.title, body: s.lede }
+        switch (s.key) {
+          case 'assetsOverview': return (
+            <PageSection key={s.key} {...head}>
+              <SectionIndex sections={index} />
+            </PageSection>
+          )
+          case 'logos': return (
+            <PageSection key={s.key} {...head}>
+              <AssetTable
+                caption="Logos"
+                rows={logoRows}
+                inkTokens={INK_TOKENS}
+                onPreviewZoom={(row, ink) => setZoom({ row, ink })}
+              />
+              <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>
+            </PageSection>
+          )
+          case 'branded': return (
+            <PageSection key={s.key} {...head}>
+              <Table caption="Branded assets" columns={brandedAssetCols} rows={BRANDED_ASSET_ROWS} className="mt-8" />
+            </PageSection>
+          )
+          case 'stationery': return (
+            <PageSection key={s.key} {...head}>
+              <div className="kol-grid mt-8">
+                <div className="col-span-2"><AssetCard><BusinessCardFront mark={mark(marks.card, { className: 'max-h-[70%]' })} /></AssetCard></div>
+                <div className="col-span-2"><AssetCard><Envelope mark={mark(marks.envelope)} info={info} /></AssetCard></div>
+                <div className="col-span-2 flex flex-col gap-3">
+                  <AssetCard><BusinessCardBack info={info} /></AssetCard>
+                  <AssetCard><EmailSignature mark={mark(marks.signature)} info={info} /></AssetCard>
+                </div>
+                <div className="col-span-2"><AssetCard><Letterhead mark={mark(marks.letter, { style: { height: '100%', width: 'auto' } })} info={info} /></AssetCard></div>
+              </div>
+            </PageSection>
+          )
+          case 'social': return (
+            <PageSection key={s.key} {...head}>
+              <ContentCollection cols={3} className="mt-8 items-start">
+                {brand.social.templates.map(({ caption, ratio, src }) => (
+                  <AssetCard key={caption ?? src} caption={caption}>
+                    <div className="relative overflow-hidden" style={{ aspectRatio: ratio }}>
+                      <img src={src} alt="" loading="lazy" className="absolute inset-0 w-full h-full object-cover" />
+                      <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%] text-fg-inverse">
+                        {mark(brand.social.mark ?? 'wordmark', { title: brand?.meta?.name })}
+                      </div>
+                    </div>
+                  </AssetCard>
+                ))}
+              </ContentCollection>
+            </PageSection>
+          )
+          case 'profile': return (
+            <PageSection key={s.key} {...head}>
+              <div className="kol-grid mt-8 items-start">
+                {brand.social.avatars.map(({ bg, polarity }, i) => (
+                  <AssetCard key={i}><ProfileAvatar mark={mark(marks.avatar, { className: 'w-1/2' })} bg={bg} polarity={polarity} /></AssetCard>
+                ))}
+              </div>
+            </PageSection>
+          )
+          default: return (
+            <PageSection key={s.key} {...head}>
+              <Prose blocks={s.blocks} />
+              <Prose blocks={s.after} />
+            </PageSection>
+          )
+        }
+      })}
+    </>
+  )
+}

package/src/BrandBook.jsx

@@ -0,0 +1,255 @@
+import { ContentCollection } 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 Swatch from './Swatch.jsx'
+import BrandMark from './BrandMark.jsx'
+import { brandSections, scrollToAnchor } from './brandBook.js'
+import { typeSections } from './typeSpecimen.js'
+
+/* taxonomy-ok: organism — the brand book's identity page: PageHero + PageSection chapters over LogoCard, Swatch and the type specimens */
+
+/**
+ * BrandBook — the BRAND page of the brand tool: the identity, one scrolling page of chapters
+ * (About · Tone · Look · Logo · Lockups · Color · Typography) under a hero and a chapter index.
+ *
+ * kol-olina's apps/brand `pages/brand/*`, carried class-for-class; what was that client's copy now
+ * comes from the manifest (`brand.book`, `brand.ramps`, `brand.type`, `brand.logos`). Sections with
+ * nothing to show for the manifest are left out — see `brandSections`.
+ *
+ * @param {Object}   brand     a brand manifest (`@kolkrabbi/kol-brand-template` schema)
+ * @param {Function} Logo      optional mark component, `<Logo variant="wordmark" />`
+ * @param {Object}   logoSources  `{ [logoId]: rawSvg }` — drawn when no `Logo` is given
+ */
+export default function BrandBook({ brand, Logo, logoSources }) {
+  const sections = brandSections(brand, 'brand')
+  const mark = (id, props) => <BrandMark id={id} Logo={Logo} sources={logoSources} {...props} />
+  const index = sections.filter((s) => s.nav)
+
+  return (
+    <>
+      {sections.map((s) => {
+        switch (s.key) {
+          case 'hero': return <PageHero key={s.key} id={s.id} label={s.label} title={s.title} lede={s.lede} />
+          case 'overview': return (
+            <PageSection key={s.key} id={s.id} label={s.label} title={s.title} body={s.lede}>
+              <SectionIndex sections={index} />
+            </PageSection>
+          )
+          case 'logo': return (
+            <PageSection key={s.key} id={s.id} label={s.label} title={s.title} body={s.lede}>
+              <Prose blocks={s.blocks} />
+              <div className="kol-grid mt-12">
+                {s.marks.map((id) => <LogoCard key={id} logo={mark(id)} frame={false} />)}
+              </div>
+              <Prose blocks={s.after} />
+            </PageSection>
+          )
+          case 'lockups': return (
+            <PageSection key={s.key} id={s.id} label={s.label} title={s.title} body={s.lede}>
+              <Prose blocks={s.blocks} />
+              <div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-12">
+                {s.marks.map((id) => (
+                  <LogoCard
+                    key={id}
+                    logo={mark(id)}
+                    caption={brand?.logos?.find((l) => l.id === id)?.name ?? id}
+                    className="[&_figcaption]:uppercase"
+                  />
+                ))}
+              </div>
+              <Prose blocks={s.after} />
+            </PageSection>
+          )
+          case 'color': return <ColorSection key={s.key} s={s} ramps={brand?.ramps ?? []} />
+          case 'typography': return <TypographySection key={s.key} s={s} brand={brand} />
+          default: return (
+            <PageSection key={s.key} id={s.id} label={s.label} title={s.title} body={s.lede}>
+              <Prose blocks={s.blocks} />
+              <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. */
+export 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 page's chapters as cards — olina's CategoryIndex, read from the sections instead of a nav
+ *  tree. The links are the sections' anchors; the click scrolls instead of setting the hash. */
+export function SectionIndex({ sections }) {
+  if (!sections.length) return null
+  return (
+    <ul className="mt-12 grid gap-2 grid-cols-1 md:grid-cols-2 max-w-panel">
+      {sections.map((s) => (
+        <li key={s.id}>
+          <a
+            href={`#${s.id}`}
+            onClick={scrollToAnchor}
+            className="kol-card kol-card-interactive flex items-center justify-between gap-4 px-4 py-3 no-underline group"
+          >
+            <span className="kol-mono-14 text-emphasis">{s.nav}</span>
+            <Icon name="arrow-right" size={16} className="text-oq-48 group-hover:text-emphasis transition-colors" />
+          </a>
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+/* Colour — the copy, then one swatch row per ramp under its label and note. The first ramp's
+ * heading sits in the copy's own prose block (olina's Concept + Greyscale were one block); each
+ * further ramp opens its own, as kol-website's hue ramps did. */
+function ColorSection({ s, ramps }) {
+  const heading = (r) => <><h3>{r.label}</h3>{r.note && <p>{r.note}</p>}</>
+  const swatches = (r) => (
+    <ContentCollection cols={{ sm: 2, md: 5 }} gap={16} className="mt-8">
+      {(r.stops ?? []).map((st) => (
+        <Swatch key={st.stop} hex={st.value} name={`${r.id}-${st.stop}`} anchor={st.stop === r.anchor} />
+      ))}
+    </ContentCollection>
+  )
+  return (
+    <PageSection id={s.id} label={s.label} title={s.title} body={s.lede}>
+      {ramps.map((r, i) => (
+        <div key={r.id ?? i}>
+          {i === 0
+            ? <Prose blocks={s.blocks} head={heading(r)} />
+            : <div className="kol-prose mt-12">{heading(r)}</div>}
+          {swatches(r)}
+        </div>
+      ))}
+      {!ramps.length && <Prose blocks={s.blocks} />}
+      <Prose blocks={s.after} />
+    </PageSection>
+  )
+}
+
+function TypographySection({ s, brand }) {
+  return (
+    <PageSection id={s.id} label={s.label} title={s.title} body={s.lede}>
+      <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">
+          .kol-prose-display-md · sans narrow · roman + italic
+        </span>
+        <p className="kol-prose-display-md m-0">
+          The quick <span className="italic">brown</span> fox jumps over the lazy dog
+        </p>
+      </div>
+
+      {typeSections(brand).map((section) => (
+        <div key={section.id} className="mt-12">
+          <div className="kol-prose max-w-measure">
+            <h3>{section.title}</h3>
+            <p>{section.intro}</p>
+            {section.reasoning && (
+              <p className="text-meta italic">{section.reasoning}</p>
+            )}
+          </div>
+          <div className="mt-8 flex flex-col gap-6">
+            {section.rows.map((row, i) => (
+              <TypeShowcase key={`${section.id}-${i}`} sectionId={section.id} row={row} />
+            ))}
+          </div>
+        </div>
+      ))}
+      <Prose blocks={s.after} />
+    </PageSection>
+  )
+}
+
+/* One specimen row, adapted to its section (olina's brand-bits `TypeShowcase`, verbatim). */
+function TypeShowcase({ sectionId, row }) {
+  if (sectionId === 'sans-families') {
+    return (
+      <div className="flex flex-col gap-2 py-3 border-b border-fg-08">
+        <span className="kol-helper-12 text-meta uppercase tracking-wider">{row.token}</span>
+        <span className="text-emphasis" style={{ fontFamily: `var(${row.token})`, fontSize: 28 }}>
+          {row.cut}
+        </span>
+        <span className="kol-helper-10 text-subtle">{row.role}</span>
+      </div>
+    )
+  }
+
+  if (sectionId === 'sans-atomic') {
+    const cls = row.cls.replace(/^\./, '')
+    return (
+      <div className="flex flex-col gap-2 py-3 border-b border-fg-08">
+        <span className="kol-helper-12 text-meta uppercase tracking-wider">
+          {row.cls} · {row.family} · {row.weight}
+        </span>
+        <div className={cls}>The quick brown fox jumps over the lazy dog</div>
+      </div>
+    )
+  }
+
+  if (sectionId === 'prose') {
+    const tag = (row.class.match(/h[1-6]|p|code|pre/) || [])[0]
+    const word = row.role
+    let sample
+    if (tag === 'h1') sample = <h1>{word}</h1>
+    else if (tag === 'h2') sample = <h2>{word}</h2>
+    else if (tag === 'h3') sample = <h3>{word}</h3>
+    else if (tag === 'h4') sample = <h4>{word}</h4>
+    else if (tag === 'h5') sample = <h5>{word}</h5>
+    else if (tag === 'h6') sample = <h6>{word}</h6>
+    else if (tag === 'code') sample = <p>Inline <code>code</code> in body copy.</p>
+    else if (tag === 'pre') sample = <pre>{`code block\nlines preserved`}</pre>
+    else sample = <span className={row.class.replace(/^\./, '').replace(/^kol-prose /, '')}>{word}</span>
+    return (
+      <div className="flex flex-col gap-2 py-3 border-b border-fg-08">
+        <span className="kol-helper-12 text-meta uppercase tracking-wider">
+          {row.class} · {row.family} · {row.weight}
+        </span>
+        <div className="kol-prose">{sample}</div>
+      </div>
+    )
+  }
+
+  if (sectionId === 'mono') {
+    const cls = row.cls.replace(/^\./, '')
+    return (
+      <div className="flex flex-col gap-2 py-3 border-b border-fg-08">
+        <span className="kol-helper-10 text-meta uppercase tracking-wider">
+          {row.cls} · weight {row.weight} · LH {typeof row.lh === 'number' ? `${row.lh}px` : row.lh} · LS {row.ls}
+        </span>
+        <span className={cls}>The quick brown fox jumps over the lazy dog</span>
+      </div>
+    )
+  }
+
+  if (sectionId === 'opacity' && row.name && row.pct !== undefined) {
+    return (
+      <div className="flex flex-col gap-2 py-3 border-b border-fg-08">
+        <span className="kol-helper-12 text-meta uppercase tracking-wider">
+          .text-{row.name} · {row.pct}% · {row.role}
+        </span>
+        <span className={`text-${row.name}`} style={{ fontSize: 18 }}>
+          The quick brown fox jumps over the lazy dog
+        </span>
+      </div>
+    )
+  }
+
+  return null
+}

package/src/BrandMark.jsx

@@ -0,0 +1,27 @@
+/**
+ * BrandMark — a logo by id, for the brand tool. Two sources, in order:
+ *
+ *   1. `Logo` — the consumer's own mark component (`<Logo variant="wordmark" />`), e.g. an svgr
+ *      loader. It wins when given, so an app that already renders its marks keeps that DOM.
+ *   2. `sources` — `{ [id]: rawSvg }`. The markup is injected so `currentColor` cascades in; the
+ *      same strings feed the Logos table's dimensions and recoloured downloads. The wrapper fills
+ *      its box and the svg fills the wrapper, so a sized parent (a LogoCard layer) fits the mark
+ *      and an unsized one takes its height from the viewBox.
+ *
+ * Neither holds the id → nothing renders (a missing mark is a gap, not a crash).
+ */
+export default function BrandMark({ id, Logo, sources, className = '', style, title }) {
+  if (Logo) return <Logo variant={id} className={className} style={style} title={title} />
+  const raw = sources?.[id]
+  if (!raw) return null
+  return (
+    <span
+      className={`kol-logo block w-full h-full [&>svg]:block [&>svg]:w-full [&>svg]:h-full ${className}`.trim()}
+      style={style}
+      role={title ? 'img' : undefined}
+      aria-label={title || undefined}
+      aria-hidden={title ? undefined : true}
+      dangerouslySetInnerHTML={{ __html: raw }}
+    />
+  )
+}

package/src/Swatch.jsx

@@ -1,25 +1,30 @@
 import { ColorSwatch } from '@kolkrabbi/kol-component'
 
 /**
- * Swatch — the DOCUMENTED swatch: chip + meta row (name, hex), with an
- * optional canonical-anchor dot.
+ * Swatch — the DOCUMENTED swatch: a specimen bar over its meta row (name, hex),
+ * with an optional canonical-anchor dot.
  *
- * `ColorSwatch` (kol-component) is the chip alone — a fixed-size pressable
- * atom for paint bars and inspectors. A colour PAGE needs the chip plus its
- * label and value, which is the form both brand apps had built locally
+ * `ColorSwatch` (kol-component) is the chip alone — a fixed-size pressable atom
+ * for paint bars and inspectors. A colour PAGE needs the specimen plus its label
+ * and value, which is the form both brand apps had built locally
  * (`brand-book-mocks-two-consumers`, 2026-09-03: 23 lines, byte-identical in
  * kol-client-olina and kol-website). This composes the atom rather than
  * redrawing it, per the ticket.
  *
- * ⚠ The forks were rendering `.kol-swatch` / `.kol-swatch-chip` /
- * `.kol-swatch-meta` — classes that exist in NO stylesheet in the estate
- * (checked kol-theme, both apps, the showcase; only `.kol-swatch-none-marker`
- * is real). The chip was a bare div with a background and no dimensions, so it
- * collapsed to zero height and the swatch has been showing its meta row over
- * nothing. The ticket reported the CSS as already shipping in
- * `kol-components-molecules.css`; it does not. So there is no verbatim
- * rendering to carry through here — the chip gets a real box from
- * `ColorSwatch`, and the dead hooks are dropped.
+ * GEOMETRY IS CARRIED THROUGH. The forks wore `.kol-swatch` /
+ * `.kol-swatch-chip` / `.kol-swatch-meta`, and those rules are real — they ship
+ * in **`@kolkrabbi/kol-framework`** (`kol-framework.css`, the "Swatch / Ramp
+ * (color specimens)" block), not in kol-theme: a 6px-gap column, a **96px-tall**
+ * chip at radius 4, and a row-wrapped meta line on the baseline. They are
+ * stragglers — `.kol-mood-tile-*` left that same block for
+ * `kol-theme/kol-components-styleguide.css` on 2026-07-10 and these did not.
+ *
+ * So this component draws that geometry ITSELF rather than wearing the classes.
+ * kol-framework is not a peer of kol-styleguide and must not become one — a
+ * component whose look depends on another package's stylesheet being imported
+ * is the defect `styleguide-barrel-is-unimportable` was filed about. A
+ * consumer swapping its fork onto this gets the same render with no new
+ * install, and `height` is the seam if a page wants a different specimen depth.
  *
  *   <Swatch hex="#131316" name="Ink" anchor />
  *
@@ -27,16 +32,20 @@ import { ColorSwatch } from '@kolkrabbi/kol-component'
  * copy; `name` renders exactly as authored.
  *
  * @param {string} hex - The colour, e.g. '#131316' (required — it is both the paint and the printed value)
- * @param {ReactNode} name - Label above the value; omitted, only the hex renders
+ * @param {ReactNode} name - Label beside the value; omitted, only the hex renders
  * @param {boolean} anchor - Mark this stop as the palette's canonical anchor — a difference-blended dot centred on the chip (default: false)
- * @param {number|'fill'|'stretch'} size - Forwarded to ColorSwatch; 'fill' (default) squares the chip to the column
+ * @param {number|string} height - Specimen depth, the forks' `.kol-swatch-chip` height (default: 96)
  * @param {string} className - Extra classes on the wrapper
  */
-export default function Swatch({ hex, name, anchor = false, size = 'fill', className = '' }) {
+export default function Swatch({ hex, name, anchor = false, height = 96, className = '' }) {
   return (
-    <div className={`flex flex-col gap-2 ${className}`.trim()}>
-      <div className="relative">
-        <ColorSwatch hex={hex} size={size} />
+    /* gap 6 — .kol-swatch */
+    <div className={`flex flex-col ${className}`.trim()} style={{ gap: 6 }}>
+      {/* .kol-swatch-chip: full column width, 96 tall, radius 4. ColorSwatch's
+          'stretch' size fills this box, so the atom owns the paint and the
+          frame while the specimen depth stays the page's decision. */}
+      <div className="relative w-full" style={{ height }}>
+        <ColorSwatch hex={hex} size="stretch" radius="sm" />
         {anchor && (
           <span
             aria-label="Canonical anchor"
@@ -51,7 +60,11 @@ export default function Swatch({ hex, name, anchor = false, size = 'fill', class
           </span>
         )}
       </div>
-      <div className="kol-helper-10 flex flex-col">
+      {/* .kol-swatch-meta: row, space-between, baseline, wrapping */}
+      <div
+        className="kol-helper-10 flex flex-row flex-wrap items-baseline justify-between"
+        style={{ gap: '4px 12px' }}
+      >
         {name && <span className="text-meta">{name}</span>}
         <span className="text-strong font-semibold">{hex.toUpperCase()}</span>
       </div>

package/src/brandBook.js

@@ -0,0 +1,126 @@
+/**
+ * brandBook — the brand tool's section registry and the manifest helpers behind it.
+ *
+ * The brand book as it ran in kol-olina's apps/brand (itself kol-website's apps/brand, copied
+ * 2026-09-02): two scrolling pages — BRAND documents the identity, ASSETS holds what you download
+ * or reproduce — each a stack of sections. The section ids, eyebrows, titles and ledes below are
+ * that app's, verbatim; anything that was the CLIENT's copy (About, Tone, Look, the logo concept,
+ * the colour concept) is not here — it comes from the manifest's `book` field, section by section
+ * (`@kolkrabbi/kol-brand-template` schema). A manifest key overrides the default of the same name.
+ */
+
+/* `nav` is the sidebar / rail label; a section without one (the hero, the overviews) is not indexed.
+ * `copy` marks a section that is ONLY its copy — with none in the manifest it is not rendered. */
+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: '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'] },
+  { key: 'lockups', id: 'logos-types', nav: 'Lockups', label: '05 — logos · types', title: 'Marks and lockups', lede: 'Logomark, wordmark, and two primary lockups.', marks: ['logomark', 'wordmark', 'lockup-hori', 'lockup-vert'] },
+  { key: 'color', id: 'color', nav: 'Color', label: '06 — color', title: 'Palette' },
+  { key: 'typography', id: 'typography', nav: 'Typography', label: '07 — typography', title: 'Type' },
+]
+
+export const ASSET_SECTIONS = [
+  { key: 'assetsOverview', id: 'assets-overview', label: 'Assets', title: 'Downloads and reproduction', lede: 'Everything you download or reproduce. Brand documents the identity; this holds the files and the specs for making them.' },
+  { key: 'logos', id: 'logos', nav: 'Logos', label: '01 — logos', title: 'Logos', lede: 'Every mark in src/brand/logos/svg/. Click a row to open the overlay; toggle the color dot to swap ink vs surface; download recolored on the fly.' },
+  { key: 'branded', id: 'branded-assets', nav: 'Branded', label: '04 — branded', title: 'Branded assets', lede: 'Stationery. Mocks live in src/components/styleguide/StationeryMocks.jsx and render in /styleguide chapter 6.' },
+  { 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: '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.' },
+]
+
+/* the two pages, for a view switch */
+export const BRAND_VIEWS = [
+  { value: 'brand', label: 'Brand' },
+  { value: 'assets', label: 'Assets' },
+]
+
+const hasCopy = (s) => Boolean(s.lede || s.blocks?.length || s.after?.length)
+
+/* Whether a section has anything to show for this manifest. Copy-only sections need copy; the
+ * specimen sections need the data they render. */
+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)
+  if (s.key === 'social') return Boolean(brand?.social?.templates?.length)
+  if (s.key === 'profile') return Boolean(brand?.social?.avatars?.length)
+  return true
+}
+
+/** One page's sections for a manifest — defaults merged with `brand.book`, the empty ones dropped.
+ *  `[{ key, id, nav?, label, title, lede, blocks, after, marks }]` */
+export function brandSections(brand, page = 'brand') {
+  const defaults = page === 'assets' ? ASSET_SECTIONS : BOOK_SECTIONS
+  const name = brand?.meta?.name
+  return defaults
+    .map((d) => {
+      const s = { ...d, ...(brand?.book?.[d.key] ?? {}) }
+      if (d.key === 'hero' && !s.title) s.title = name
+      if (d.key === 'about' && !s.title && name) s.title = `About ${name}`
+      return s
+    })
+    .filter((s) => shows(s, brand))
+}
+
+/** A page's rail / index entries — `[{ id, label }]`. */
+export const brandToc = (brand, page) =>
+  brandSections(brand, page).filter((s) => s.nav).map((s) => ({ id: s.id, label: s.nav }))
+
+/** The manifest's `meta` in the shape the stationery mocks read (`DEFAULT_BRAND_INFO`). A field the
+ *  manifest does not carry is an EMPTY STRING, so the mocks render it blank rather than falling back
+ *  to their placeholder values. */
+export function brandInfo(brand) {
+  const m = brand?.meta ?? {}
+  const loc = m.location ?? {}
+  return {
+    identity: { founder: m.founder ?? '', role: m.role ?? '', established: m.founded ?? '', name: m.name ?? '', nameShort: m.nameShort ?? '' },
+    contact: { email: m.email ?? '', phone: m.phone ?? '', web: (m.url ?? '').replace(/^https?:\/\//, '').replace(/\/$/, '') },
+    social: { instagram: m.socials?.instagram ?? '', youtube: m.socials?.youtube ?? '', tiktok: m.socials?.tiktok ?? '' },
+    studio: { street: loc.street ?? '', postcode: loc.postcode ?? '', country: loc.country ?? '', city: loc.city ?? '', locShort: loc.locShort ?? '' },
+    legal: { entity: m.legalName ?? '', kt: '', vat: '' },
+    labels: { madeIn: '', handmade: '', handBy: '', manifesto: '' },
+  }
+}
+
+/* which logo each stationery mock carries — the variants olina's brandBook.jsx drew */
+export const STATIONERY_MARKS = { card: 'lockup-hori', envelope: 'logomark', letter: 'wordmark', signature: 'logomark', avatar: 'logomark' }
+
+/* The Branded table — the five stationery pieces the mocks draw. */
+export const BRANDED_ASSET_ROWS = [
+  { item: 'Business card · front',  aspect: '85.6 / 53.85 (ID-1)', surface: 'paper',     status: 'mocked',  note: 'StationeryMocks.BusinessCardFront' },
+  { item: 'Business card · back',   aspect: '85.6 / 53.85',         surface: 'ink',       status: 'mocked',  note: 'StationeryMocks.BusinessCardBack' },
+  { item: 'Envelope · DL',           aspect: '220 / 110',           surface: 'paper',     status: 'mocked',  note: 'StationeryMocks.Envelope' },
+  { item: 'Letterhead · A4',         aspect: '210 / 297',           surface: 'paper',     status: 'mocked',  note: 'StationeryMocks.Letterhead' },
+  { item: 'Email signature',         aspect: 'free',                surface: 'paper',     status: 'mocked',  note: 'StationeryMocks.EmailSignature' },
+]
+
+/** An in-page anchor click that scrolls instead of setting the hash — the host may route on the hash
+ *  (media-shell does; apps/brand keeps its page there), so an anchor must not replace it. */
+export function scrollToAnchor(e) {
+  e.preventDefault()
+  const id = e.currentTarget.getAttribute('href')?.slice(1)
+  if (id) document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+}
+
+/* viewBox → "W × H" */
+export const svgDims = (raw) => {
+  const m = /viewBox="[\d.-]+\s+[\d.-]+\s+([\d.]+)\s+([\d.]+)"/.exec(raw ?? '')
+  return m ? `${Math.round(+m[1])} × ${Math.round(+m[2])}` : undefined
+}
+
+/* `currentColor` → the resolved ink the table hands over, into a Blob, so a white mark downloads white. */
+export function downloadRecolored(raw, color, filename) {
+  const blob = new Blob([raw.replace(/currentColor/gi, color)], { type: 'image/svg+xml' })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+  URL.revokeObjectURL(url)
+}

package/src/index.js

@@ -42,3 +42,10 @@ export {
 // that wanted one logo card could not build. Import them from their own homes:
 //   AssetGrid, FeatureSplit, ProsePreview, SpectrumGrid → @kolkrabbi/kol-component
 //   TypeSample, TypeSpecCard                            → @kolkrabbi/kol-foundry
+
+// The brand tool (brand-as-a-tool, 2026-09-27): the brand book's two pages over one manifest —
+// kol-olina's apps/brand, carried in. `Brand` is the tool; the pages render alone too.
+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'

package/src/typeSpecimen.js

@@ -0,0 +1,166 @@
+/**
+ * typeSpecimen — the brand book's Typography chapter as data.
+ *
+ * kol-olina's apps/brand `data/typography.js`, verbatim, minus its two brand-specific tables: the
+ * FAMILIES come from the manifest (`type.families`, `type.note`), and the cuts table was never
+ * rendered by the chapter. Everything else describes the KOL type system — classes, prose, the mono
+ * split, the reading hierarchy — which every brand on the system shares, because its type rides the
+ * family tokens.
+ */
+
+const sansDisplayRows = [
+  { cls: '.kol-sans-display-01', tokenName: '--kol-text-display-01', family: 'sans-narrow', weight: 600 },
+  { cls: '.kol-sans-display-02', tokenName: '--kol-text-display-02', family: 'sans-narrow', weight: 600 },
+]
+
+const sansHeadingRows = [
+  { cls: '.kol-sans-heading-01', tokenName: '--kol-text-heading-01', family: 'sans-narrow',  weight: 500 },
+  { cls: '.kol-sans-heading-02', tokenName: '--kol-text-heading-02', family: 'sans-compact', weight: 500 },
+  { cls: '.kol-sans-heading-03', tokenName: '--kol-text-heading-03', family: 'sans-compact', weight: 500 },
+  { cls: '.kol-sans-heading-04', tokenName: '--kol-text-heading-04', family: 'sans-compact', weight: 500 },
+  { cls: '.kol-sans-heading-05', tokenName: '--kol-text-heading-05', family: 'sans-compact', weight: 500 },
+]
+
+const sansBodyRows = [
+  { cls: '.kol-sans-body-01', tokenName: '--kol-text-body-01', family: 'sans (base)', weight: 400 },
+  { cls: '.kol-sans-body-02', tokenName: '--kol-text-body-02', family: 'sans (base)', weight: 400 },
+  { cls: '.kol-sans-body-03', tokenName: '--kol-text-body-03', family: 'sans (base)', weight: 400 },
+]
+
+const proseRows = [
+  { role: 'Display',     class: '.kol-prose-display',        family: 'sans-narrow',  weight: 500 },
+  { role: 'Display (md)',class: '.kol-prose-display-md',     family: 'sans-narrow',  weight: 500 },
+  { role: 'Title',       class: '.kol-prose-title',          family: 'sans-narrow',  weight: 500 },
+  { role: 'H1',          class: '.kol-prose h1',             family: 'sans-narrow',  weight: 500, tokenName: '--kol-text-heading-01' },
+  { role: 'H2',          class: '.kol-prose h2',             family: 'sans-compact', weight: 400, tokenName: '--kol-text-heading-03' },
+  { role: 'H3',          class: '.kol-prose h3',             family: 'sans-compact', weight: 400, tokenName: '--kol-text-heading-04' },
+  { role: 'H4',          class: '.kol-prose h4',             family: 'sans-compact', weight: 400, tokenName: '--kol-text-heading-05' },
+  { role: 'H5',          class: '.kol-prose h5',             family: 'sans-compact', weight: 500, tokenName: '--kol-text-heading-06' },
+  { role: 'H6',          class: '.kol-prose h6',             family: 'sans-compact', weight: 500, tokenName: '--kol-text-heading-06' },
+  { role: 'Lede',        class: '.kol-prose-lede',           family: 'sans-compact', weight: 400 },
+  { role: 'Tagline',     class: '.kol-prose-tagline',        family: 'sans-narrow',  weight: 500 },
+  { role: 'Body',        class: '.kol-prose p',              family: 'sans (base)',  weight: 300 },
+  { role: 'Quote',       class: '.kol-prose blockquote p',   family: 'sans (base)',  weight: 600 },
+  { role: 'Cite',        class: '.kol-prose blockquote cite',family: 'sans (base)',  weight: 500 },
+  { role: 'Label',       class: '.kol-prose-label',          family: 'mono',         weight: 500 },
+  { role: 'Code (inline)',class: '.kol-prose code',          family: 'mono',         weight: 400 },
+  { role: 'Code (block)', class: '.kol-prose pre',           family: 'mono',         weight: 400 },
+]
+
+const monoRows = [
+  { cls: '.kol-mono-20', size: 20, lh: 26, weight: 400, ls: 'normal' },
+  { cls: '.kol-mono-16', size: 16, lh: 22, weight: 400, ls: 'normal' },
+  { cls: '.kol-mono-14', size: 14, lh: 18, weight: 400, ls: 'normal' },
+  { cls: '.kol-mono-12', size: 12, lh: 16, weight: 400, ls: 'normal' },
+  { cls: '.kol-mono-10', size: 10, lh: 14, weight: 400, ls: 'normal' },
+  { cls: '.kol-mono-8',  size:  8, lh: 12, weight: 400, ls: 'normal' },
+]
+
+const helperRows = [
+  { cls: '.kol-helper-20', size: 20, lh: '1', weight: 500, ls: '0.06em' },
+  { cls: '.kol-helper-16', size: 16, lh: '1', weight: 500, ls: '0.06em' },
+  { cls: '.kol-helper-14', size: 14, lh: '1', weight: 500, ls: '0.06em' },
+  { cls: '.kol-helper-12', size: 12, lh: '1', weight: 500, ls: '0.06em' },
+  { cls: '.kol-helper-10', size: 10, lh: '1', weight: 500, ls: '0.10em' },
+  { cls: '.kol-helper-8',  size:  8, lh: '1', weight: 500, ls: '0.10em' },
+]
+
+const opacityDescriptorRows = [
+  { name: 'subtle',   pct: 24,  token: '--kol-fg-subtle',   role: 'Dividers, disabled hints, faintest visible' },
+  { name: 'meta',     pct: 48,  token: '--kol-fg-meta',     role: 'Labels, eyebrows, captions' },
+  { name: 'body',     pct: 64,  token: '--kol-fg-body',     role: 'Running copy, links' },
+  { name: 'strong',   pct: 80,  token: '--kol-fg-strong',   role: 'Emphasized body, <strong>' },
+  { name: 'emphasis', pct: 100, token: '--kol-fg-emphasis', role: 'Headings, max ink' },
+]
+
+const SYSTEM_SECTIONS = [
+  {
+    id: 'sans-atomic',
+    title: 'Sans atomic classes',
+    intro:
+      "Display, heading, body — explicit per-element classes for chrome / " +
+      "page sections. Distinct from .kol-prose, which cascades into HTML " +
+      "elements for rich-text containers.",
+    reasoning:
+      "Numbered tokens (01–06), not t-shirt sizes. Numbers describe a fixed " +
+      "position in the scale (01 = anchor, ascending = smaller); t-shirt names " +
+      "carry no ordering, you have to remember which is bigger. 01 = largest " +
+      "follows HTML's H1 = biggest convention. Class prefix is family-first " +
+      "(.kol-sans-) to mirror mono naming and read naturally — \"the sans " +
+      "system, display role, stop 01\". H1 uses Narrow (condensed for impact); " +
+      "H2–H5 use Compact (slightly wider, mid-tier); body uses base. Atomic body " +
+      "weight is 400 (regular) for chrome; prose body is 300 (light) for " +
+      "editorial reading copy — different defaults per context.",
+    rows: [...sansDisplayRows, ...sansHeadingRows, ...sansBodyRows],
+  },
+  {
+    id: 'prose',
+    title: 'Prose container',
+    intro:
+      ".kol-prose is a rich-text container that cascades to native HTML " +
+      "elements (h1–h6, p, ul, blockquote, code, pre). Wrap CMS / blog / " +
+      "markdown output in it; the container styles every element via " +
+      "descendant selectors.",
+    reasoning:
+      "H2 intentionally skips heading-02 (40px) and uses heading-03 (32px). " +
+      "48 → 40 reads as \"same family\"; 48 → 32 reads as \"structural break\" " +
+      "— better visual rhythm at H1 → H2. H6 ships uppercase with tracking " +
+      "by default since H6 is rare and benefits from a label-like rendering. " +
+      "Code (inline + block) consumes the mono token so a future swap cascades " +
+      "into prose code automatically.",
+    rows: proseRows,
+  },
+  {
+    id: 'mono',
+    title: 'Mono',
+    intro:
+      "JetBrains Mono. Two scales at the same px stops, distinguished by " +
+      "intent + visual weight. .kol-mono-N for multi-line body / values " +
+      "(weight 400, with leading). .kol-helper-N for single-line labels " +
+      "(weight 500, line-height 1, letter-spaced).",
+    reasoning:
+      "Same px size, different weight = visible hierarchy without size-jumps. " +
+      "Common pattern: a label sits above a control or value at the same stop " +
+      "— label is helper (medium), control text is mono (regular). Both 12px, " +
+      "but the label \"reads first\" by weight. Tight UI grids stay compact " +
+      "without further compressing sizes. Px-literal suffixes (10/12/14/16/20) " +
+      "instead of numbered indices because mono is utility chrome where exact " +
+      "px matters — the number IS the value, no decoder ring. Wider letter-" +
+      "spacing (0.10em) on the smallest two stops is a typographic principle: " +
+      "sub-12px mono needs more tracking to stay legible.",
+    rows: [...monoRows, ...helperRows],
+  },
+  {
+    id: 'opacity',
+    title: 'Reading hierarchy (descriptors)',
+    intro:
+      "Five-stop ink hierarchy: subtle / meta / body / strong / emphasis. " +
+      "Aliases over the numeric --kol-fg-NN ramp (UI Colors / Opacity " +
+      "primitives). Pick descriptors when intent matters; pick numeric stops " +
+      "when exact percentage matters. Text-only — bg / border / ring " +
+      "descriptor families retired 2026-04-30 (consumers used numeric stops).",
+    reasoning:
+      "Five stops anchor the typography reading hierarchy. The retired " +
+      "`mute` (32%) sat awkwardly between subtle (24%, dividers) and meta " +
+      "(48%, labels) and had zero component consumers. Descriptors are now " +
+      "text-only — for surface tints, borders, and rings, reach for the " +
+      "numeric --kol-fg-NN family (bg-fg-08, border-fg-12, etc.).",
+    rows: opacityDescriptorRows,
+  },
+]
+
+/** The chapter's sections for a manifest: its families first (when it declares any), then the
+ *  system's. `[{ id, title, intro, reasoning?, rows }]` */
+export function typeSections(brand) {
+  const families = brand?.type?.families ?? []
+  const head = families.length ? [{
+    id: 'sans-families',
+    title: 'Family tokens',
+    intro:
+      "Three sans cuts and one mono. Edit a family token to swap any cut " +
+      "without touching consumers.",
+    reasoning: brand?.type?.note,
+    rows: families.map(({ token, role, cut }) => ({ token, role, cut })),
+  }] : []
+  return [...head, ...SYSTEM_SECTIONS]
+}