@kolkrabbi/kol-styleguide 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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}.",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.181.0",
+    "@kolkrabbi/kol-component": "^0.182.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
     "@kolkrabbi/kol-theme": "^0.139.0"
   },

package/src/AssetCard.jsx

@@ -0,0 +1,46 @@
+/**
+ * AssetCard — frame wrapper for stationery / branded asset mocks.
+ *
+ * Just a backdrop with padding + caption above. The asset child renders at its
+ * natural size, driven by the parent column width and its own aspect-ratio. No
+ * scaling — content stays at intended proportions.
+ *
+ * Group items with similar aspects in the same grid row so heights align.
+ * Extreme-aspect items (very tall or very wide) should go in their own row or
+ * a full-width container.
+ *
+ * Lifted verbatim from the two brand apps (`brand-book-mocks-two-consumers`,
+ * 2026-09-03) — the file was byte-identical in kol-client-olina and
+ * kol-website, 25 lines each. Nothing here was client-specific, which is why
+ * it is a straight carry-through: same elements, same classes, same order.
+ * `backdrop` and `className` are the only additions.
+ *
+ *   <AssetCard caption="Business card">
+ *     <div style={{ aspectRatio: '85 / 55' }}><BusinessCardFront … /></div>
+ *   </AssetCard>
+ *
+ * Caption text is authored in the case it should render — the component applies
+ * no text-transform beyond the `uppercase` the original carried.
+ *
+ * @param {ReactNode} caption - Label above the frame; omitted, no figcaption renders
+ * @param {string} backdrop - CSS colour for the frame ground (default: the fg-04 wash)
+ * @param {string} className - Extra classes on the <figure>
+ * @param {ReactNode} children - The mock
+ */
+export default function AssetCard({ caption, backdrop, className = '', children }) {
+  return (
+    <figure className={className}>
+      {caption && (
+        <figcaption className="kol-helper-12 uppercase tracking-widest text-meta mb-3">
+          {caption}
+        </figcaption>
+      )}
+      <div
+        className={`rounded-sm p-6 ${backdrop ? '' : 'bg-fg-04'}`.trim()}
+        style={backdrop ? { background: backdrop } : undefined}
+      >
+        {children}
+      </div>
+    </figure>
+  )
+}

package/src/AssetTable.jsx

@@ -1,6 +1,16 @@
+import { useState } from 'react'
 import { Table } from '@kolkrabbi/kol-component'
 import { Icon } from '@kolkrabbi/kol-icons'
 
+/* Resolve a CSS custom property off the document root. The download seam is
+ * handed a COLOUR, not a token — a consumer swapping `currentColor` in raw SVG
+ * cannot use `var(--x)`, and resolving it at the call site is how two brand
+ * apps ended up with the same four-line helper. SSR-safe: '' when no document. */
+function resolveToken(token) {
+  if (!token || typeof document === 'undefined') return ''
+  return getComputedStyle(document.documentElement).getPropertyValue(token).trim()
+}
+
 /**
  * AssetTable — mark / asset spec table.
  *
@@ -9,35 +19,50 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * download control per row. Rows are consumer-injected; the standard column set
  * is built here so a consumer only supplies data.
  *
- * Ported from the monorepo apps/brand styleguide AssetTable (2026-07). All
- * app-specific wiring is dropped: the `import.meta.glob` SVG harvesting, the
- * KolLogo / Graphic loaders, the ink-token toggle, the fullscreen overlay, and
- * the `Blob` recolour-and-download. Download is now a plain per-row seam —
- * pass `href` (a download link) OR `onDownload` (a callback). Preview is a
- * consumer-supplied node.
+ * Ported from the monorepo apps/brand styleguide AssetTable (2026-07). The
+ * `import.meta.glob` harvesting, the mark loaders and the `Blob` recolour are
+ * app code and stay out. **Three behaviours came back as seams in 0.4.0**
+ * (`assettable-package-dropped-its-wiring`, kol-client-olina): the port had
+ * dropped the ink toggle, the zoom preview and the recolour-aware download and
+ * still read as a replacement, so its one consumer measured it and reverted.
+ * The state is the table's; the `Blob` and the overlay stay the consumer's.
+ *
+ * - **`inkTokens`** — a `{ ink, surface }` token pair turns on the Color column
+ *   and a per-row toggle dot: the row's preview paints in the live token, the
+ *   column shows which one, the dot flips it. Unset, none of that renders.
+ * - **`onPreviewZoom(row, resolvedInk)`** — makes the preview cell a zoom
+ *   button. The consumer opens its own overlay (`FullscreenOverlay` in both
+ *   brand apps) at the ink it is handed.
+ * - **`row.onDownload(row, resolvedInk)`** — the second argument is the
+ *   COMPUTED colour, not the token, so a consumer can swap `currentColor` for
+ *   it and hand back a white mark that downloads white.
  *
- * Columns adapt to the data: the Preview column appears only when a row carries
- * a `preview` node, and the Download column only when a row carries `href` or
- * `onDownload`. Name / format / dimensions always show, falling back to an
- * em-dash (DS Table behaviour) when a field is absent.
+ * Columns adapt to the data: Preview appears only when a row carries a
+ * `preview` node, Path only when a row carries `path`, Color only under
+ * `inkTokens`, and Download only when a row carries `href` or `onDownload`.
+ * Name / format / dimensions always show, falling back to an em-dash (DS Table
+ * behaviour) when a field is absent.
  *
  * Row shape:
- *   { id, name, preview?, format?, dimensions?, href?, filename?, onDownload? }
- *     id          React key (falls back to array index)
- *     name        asset name (string or node)
- *     preview     specimen node rendered in the Preview cell
- *     format      e.g. 'SVG' · 'PNG @2x'
- *     dimensions  e.g. '48 × 48'
- *     href        download URL → renders an <a download>
- *     filename    download filename for the <a download> attribute
- *     onDownload  click handler → renders a <button> (takes precedence over href)
+ *   { id, name, preview?, previewWidth?, path?, format?, dimensions?, href?, filename?, onDownload? }
+ *     id            React key (falls back to array index)
+ *     name          asset name (string or node)
+ *     preview       specimen node rendered in the Preview cell
+ *     previewWidth  px width for the preview box — a wordmark is not a logomark
+ *     path          source path, rendered in a <code> cell
+ *     format        e.g. 'SVG' · 'PNG @2x'
+ *     dimensions    e.g. '48 × 48'
+ *     href          download URL → renders an <a download>
+ *     filename      download filename for the <a download> attribute
+ *     onDownload    click handler → renders a <button> (takes precedence over href)
  *
- * Props:
- *   rows        Array<row>  (required)
- *   caption     sr-only <caption> for the table (a11y)
- *   variant     'default' | 'simple'  → forwarded to DS Table
- *   className   extra classes on the table wrapper
- *   emptyLabel  message shown when rows is empty (default 'No assets.')
+ * @param {Array<Object>} rows - The assets (required)
+ * @param {string} caption - sr-only <caption> for the table (a11y)
+ * @param {'default'|'simple'} variant - Forwarded to DS Table
+ * @param {string} className - Extra classes on the table wrapper
+ * @param {string} emptyLabel - Message shown when rows is empty (default 'No assets.')
+ * @param {{ink: string, surface: string}} inkTokens - CSS custom-property pair the ink toggle swings between; unset disables the Color column and the toggle
+ * @param {Function} onPreviewZoom - `(row, resolvedInk)` — supplied, the preview becomes a zoom button and the consumer owns the overlay
  */
 export default function AssetTable({
   rows = [],
@@ -45,28 +70,51 @@ export default function AssetTable({
   variant = 'default',
   className = '',
   emptyLabel = 'No assets.',
+  inkTokens = null,
+  onPreviewZoom,
 }) {
+  /* Per-row ink, keyed by row id. Hooks run before the empty-rows return so the
+   * order never changes with the data. */
+  const [inks, setInks] = useState({})
+
   if (!rows.length) {
     return <p className="kol-mono-14 text-fg-48">{emptyLabel}</p>
   }
 
   const withId = rows.map((row, i) => ({ ...row, id: row.id ?? i }))
   const hasPreview = withId.some((row) => row.preview != null)
+  const hasPath = withId.some((row) => row.path != null)
   const hasDownload = withId.some((row) => row.href || row.onDownload)
 
+  const tokenFor = (id) => (inkTokens ? inks[id] ?? inkTokens.ink : null)
+  const toggleInk = (id) =>
+    setInks((prev) => ({
+      ...prev,
+      [id]: (prev[id] ?? inkTokens.ink) === inkTokens.ink ? inkTokens.surface : inkTokens.ink,
+    }))
+
   const columns = [
     hasPreview && {
       accessor: 'preview',
       header: 'Preview',
-      className: 'kol-table-cell-text',
+      /* Off-ink rows get a wash so a surface-coloured mark stays visible
+         against the table's own ground — the consumer's behaviour, kept. */
+      className: (row) =>
+        `kol-table-cell-text${inkTokens && tokenFor(row.id) !== inkTokens.ink ? ' bg-fg-04' : ''}`,
       style: { minWidth: 160 },
-      render: (row) => row.preview ?? null,
+      render: (row) => <PreviewCell row={row} token={tokenFor(row.id)} onZoom={onPreviewZoom} />,
     },
     {
       accessor: 'name',
       header: 'Name',
       className: 'kol-table-cell-text',
     },
+    hasPath && {
+      accessor: 'path',
+      header: 'Path',
+      className: 'kol-table-cell-meta',
+      render: (row) => (row.path ? <code>{row.path}</code> : null),
+    },
     {
       accessor: 'format',
       header: 'Format',
@@ -77,50 +125,105 @@ export default function AssetTable({
       header: 'Dimensions',
       className: 'kol-table-cell-meta',
     },
+    inkTokens && {
+      accessor: 'color',
+      header: 'Color',
+      className: 'kol-table-cell-meta',
+      render: (row) => <code>{tokenFor(row.id)}</code>,
+    },
     hasDownload && {
       accessor: 'download',
       header: 'Download',
       style: { width: 96 },
-      render: (row) => <DownloadControl row={row} />,
+      render: (row) => (
+        <DownloadControl
+          row={row}
+          token={tokenFor(row.id)}
+          onToggleInk={inkTokens ? () => toggleInk(row.id) : null}
+        />
+      ),
     },
   ].filter(Boolean)
 
   return <Table caption={caption} columns={columns} rows={withId} variant={variant} className={className} />
 }
 
+/* Preview cell. With `onZoom` it is a zoom button; without, the bare node —
+ * a table that only lists assets should not claim a click. `token` paints the
+ * node through currentColor, which is what makes one SVG serve both inks. */
+function PreviewCell({ row, token, onZoom }) {
+  if (row.preview == null) return null
+
+  const style = {
+    ...(token ? { color: `var(${token})` } : {}),
+    ...(row.previewWidth ? { width: row.previewWidth } : {}),
+  }
+
+  if (!onZoom) {
+    return Object.keys(style).length ? <span className="inline-flex items-center" style={style}>{row.preview}</span> : row.preview
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={() => onZoom(row, resolveToken(token))}
+      className="inline-flex items-center cursor-zoom-in"
+      style={style}
+      aria-label={`Open ${typeof row.name === 'string' ? row.name : 'asset'} overlay`}
+    >
+      {row.preview}
+    </button>
+  )
+}
+
 /* Per-row download affordance. onDownload → button; href → anchor; else nothing.
  * The DS `download` icon inherits currentColor; aria-label composes the asset
- * name for screen readers (an a11y string, not rendered content). */
-function DownloadControl({ row }) {
+ * name for screen readers (an a11y string, not rendered content). Under
+ * `inkTokens` a toggle dot rides beside it — the ink a download will carry is
+ * chosen where the download is, not in a separate control. */
+function DownloadControl({ row, token, onToggleInk }) {
   const label = `Download ${typeof row.name === 'string' ? row.name : 'asset'}`
 
-  if (row.onDownload) {
-    return (
+  const control = row.onDownload ? (
+    <button
+      type="button"
+      onClick={() => row.onDownload(row, resolveToken(token))}
+      className="inline-flex items-center text-fg-64"
+      aria-label={label}
+      title="Download"
+    >
+      <Icon name="download" size={16} />
+    </button>
+  ) : row.href ? (
+    <a
+      href={row.href}
+      download={row.filename ?? true}
+      className="inline-flex items-center text-fg-64"
+      aria-label={label}
+      title="Download"
+    >
+      <Icon name="download" size={16} />
+    </a>
+  ) : null
+
+  if (!control) return null
+  if (!onToggleInk) return control
+
+  return (
+    <span className="inline-flex items-center gap-2">
+      {control}
       <button
         type="button"
-        onClick={() => row.onDownload(row)}
-        className="inline-flex items-center text-fg-64"
-        aria-label={label}
-        title="Download"
+        onClick={onToggleInk}
+        className="inline-flex items-center justify-center w-6 h-6"
+        aria-label={`Toggle download color — current ${token}`}
+        title={`Toggle (currently ${token})`}
       >
-        <Icon name="download" size={16} />
+        <span
+          className="inline-block rounded-full border border-fg-24"
+          style={{ width: 8, height: 8, background: `var(${token})` }}
+        />
       </button>
-    )
-  }
-
-  if (row.href) {
-    return (
-      <a
-        href={row.href}
-        download={row.filename ?? true}
-        className="inline-flex items-center text-fg-64"
-        aria-label={label}
-        title="Download"
-      >
-        <Icon name="download" size={16} />
-      </a>
-    )
-  }
-
-  return null
+    </span>
+  )
 }

package/src/SocialMocks.jsx

@@ -0,0 +1,265 @@
+/**
+ * SocialMocks — a mark in situ on social surfaces: feed posts at 1:1, stories
+ * at 9:16, and the round profile avatar.
+ *
+ * Lifted from the two brand apps (`brand-book-mocks-two-consumers`,
+ * 2026-09-03 — 136 lines in kol-client-olina, 136 in kol-website, four lines
+ * of diff between them). ASSET-AGNOSTIC the way `LogoCard` is: every mark is a
+ * consumer-injected node and every string is a prop. What the forks baked in
+ * and this does not:
+ *
+ * - `KolLogo` imported from the app → the `mark` node.
+ * - A seven-stop client palette (champagne / sand / burgundy / maroon / wine)
+ *   → `palette`, defaulting to the theme's own ink and paper. A brand supplies
+ *   its own; the DS ships no colour.
+ * - `'Bricolage Grotesque'` and `'JetBrains Mono'` by name → `fonts`,
+ *   defaulting to `--kol-font-family-sans-narrow` / `--kol-font-family-mono`.
+ *   A foreign family by name in a package is how a consumer's type silently
+ *   stops being the system's.
+ * - The client's own copy ("Made by hand, made to last.", "Edda Coat",
+ *   "AW 2026", "Quiet, considered.") → text props with neutral placeholders.
+ *
+ * The geometry is carried through class-for-class: the aspect boxes, the mark
+ * fractions (w-1/4 · w-1/5 · w-1/6 · w-1/3 · w-1/2) and the corner insets are
+ * the forks' numbers, not new ones.
+ *
+ *   const brand = { mark: <Asset name="logomark" />, palette: { accent: '#F3F1EC' } }
+ *   <PostPhoto {...brand} />
+ *   <StoryType {...brand} quote={<>Quiet,<br/>considered.</>} />
+ *   <ProfileAvatar {...brand} />
+ *
+ * One object spread into each mock is the intended call shape — no context, no
+ * provider: a brand book renders these in a grid and already holds the object.
+ */
+
+/* Neutral defaults. `accent` is the only stop a brand normally overrides; the
+ * rest track the theme so an un-themed render is still legible. */
+export const DEFAULT_MOCK_PALETTE = {
+  paper: '#FCFBFB',
+  ink: '#131316',
+  accent: '#F3F1EC',
+  photo: '#363639',
+}
+
+export const DEFAULT_MOCK_FONTS = {
+  display: 'var(--kol-font-family-sans-narrow)',
+  mono: 'var(--kol-font-family-mono)',
+}
+
+const capsStyle = (fonts) => ({
+  fontFamily: fonts.mono,
+  fontWeight: 500,
+  letterSpacing: '0.1em',
+  textTransform: 'uppercase',
+})
+
+/* Every mock resolves its palette and fonts the same way, so a consumer can
+ * pass one, both or neither and never get a half-themed frame. */
+const resolve = (palette, fonts) => [
+  { ...DEFAULT_MOCK_PALETTE, ...palette },
+  { ...DEFAULT_MOCK_FONTS, ...fonts },
+]
+
+/**
+ * PostPhoto — feed post, photo ground with the mark in the corner (1:1).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} media - Node behind the mark — an <img>, a video frame; omitted, the `photo` stop fills it
+ * @param {string} className - Extra classes on the frame
+ */
+export function PostPhoto({ mark, palette, fonts, media, className = '' }) {
+  const [pal] = resolve(palette, fonts)
+  return (
+    <div
+      className={`aspect-square relative rounded-sm overflow-hidden ${className}`.trim()}
+      style={{ background: pal.photo, color: pal.paper }}
+    >
+      {media}
+      <span className="absolute bottom-4 right-4 w-1/4">{mark}</span>
+    </div>
+  )
+}
+
+/**
+ * PostType — feed post, type-driven quote on the accent ground (1:1).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} quote - The line; authored with its own <br/> breaks
+ * @param {string} className - Extra classes on the frame
+ */
+export function PostType({ mark, palette, fonts, quote = 'Your line here.', className = '' }) {
+  const [pal, font] = resolve(palette, fonts)
+  return (
+    <div
+      className={`aspect-square relative flex items-center justify-center p-8 rounded-sm ${className}`.trim()}
+      style={{ background: pal.accent, color: pal.ink }}
+    >
+      <p style={{ fontFamily: font.display, fontSize: 20, fontWeight: 500, lineHeight: 1.15, textAlign: 'center', letterSpacing: '-0.01em' }}>
+        {quote}
+      </p>
+      <span className="absolute bottom-4 left-4 w-1/5">{mark}</span>
+    </div>
+  )
+}
+
+/**
+ * PostProduct — feed post, product flat with a caption row (1:1).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} media - Fills the product panel; omitted, the `placeholder` label sits in the accent stop
+ * @param {string} placeholder - Label shown in an empty product panel (default: 'product')
+ * @param {string} eyebrow - Small caps line above the product name (default: 'Style')
+ * @param {ReactNode} name - The product name
+ * @param {string} className - Extra classes on the frame
+ */
+export function PostProduct({
+  mark,
+  palette,
+  fonts,
+  media,
+  placeholder = 'product',
+  eyebrow = 'Style',
+  name = 'Product name',
+  className = '',
+}) {
+  const [pal, font] = resolve(palette, fonts)
+  const caps = capsStyle(font)
+  return (
+    <div
+      className={`aspect-square relative flex flex-col p-6 rounded-sm ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <div
+        className="flex-1 flex items-center justify-center rounded-sm overflow-hidden"
+        style={{ background: pal.accent }}
+      >
+        {media ?? <span style={{ ...caps, fontSize: 8, opacity: 0.35 }}>{placeholder}</span>}
+      </div>
+      <div className="mt-4 flex items-end justify-between">
+        <div>
+          <p style={{ ...caps, fontSize: 7, opacity: 0.5 }}>{eyebrow}</p>
+          <p style={{ fontFamily: font.display, fontSize: 14, fontWeight: 500 }}>{name}</p>
+        </div>
+        <span className="w-1/6">{mark}</span>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * PostEditorial — feed post, half photo / half type (1:1).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} media - Fills the photo half; omitted, the `photo` stop does
+ * @param {string} eyebrow - Small caps line at the top of the type half (default: 'Season')
+ * @param {ReactNode} title - The headline; authored with its own <br/> breaks
+ * @param {string} className - Extra classes on the frame
+ */
+export function PostEditorial({
+  mark,
+  palette,
+  fonts,
+  media,
+  eyebrow = 'Season',
+  title = 'Your headline',
+  className = '',
+}) {
+  const [pal, font] = resolve(palette, fonts)
+  const caps = capsStyle(font)
+  return (
+    <div className={`aspect-square grid grid-cols-2 rounded-sm overflow-hidden ${className}`.trim()}>
+      <div style={{ background: pal.photo }}>{media}</div>
+      <div
+        className="relative flex flex-col justify-between p-5"
+        style={{ background: pal.accent, color: pal.ink }}
+      >
+        <p style={{ ...caps, fontSize: 7, opacity: 0.5 }}>{eyebrow}</p>
+        <div>
+          <p style={{ fontFamily: font.display, fontSize: 16, fontWeight: 500, lineHeight: 1.1 }}>
+            {title}
+          </p>
+          <span className="block w-1/3 mt-3">{mark}</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * StoryPhoto — story frame, full-bleed photo with the mark low-left (9:16).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} media - Fills the frame; omitted, the `photo` stop does
+ * @param {string} className - Extra classes on the frame
+ */
+export function StoryPhoto({ mark, palette, fonts, media, className = '' }) {
+  const [pal] = resolve(palette, fonts)
+  return (
+    <div
+      className={`aspect-[9/16] relative rounded-sm overflow-hidden ${className}`.trim()}
+      style={{ background: pal.photo, color: pal.paper }}
+    >
+      {media}
+      <span className="absolute bottom-6 left-6 w-1/3">{mark}</span>
+    </div>
+  )
+}
+
+/**
+ * StoryType — story frame, type-driven with the mark centred low (9:16).
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE — `ink` is the ground here and `accent` the type
+ * @param {Object} fonts - Partial override of DEFAULT_MOCK_FONTS
+ * @param {ReactNode} quote - The line; authored with its own <br/> breaks
+ * @param {string} className - Extra classes on the frame
+ */
+export function StoryType({ mark, palette, fonts, quote = 'Your line here.', className = '' }) {
+  const [pal, font] = resolve(palette, fonts)
+  return (
+    <div
+      className={`aspect-[9/16] relative flex items-center justify-center p-8 rounded-sm ${className}`.trim()}
+      style={{ background: pal.ink, color: pal.accent }}
+    >
+      <p style={{ fontFamily: font.display, fontSize: 18, fontWeight: 500, lineHeight: 1.2, textAlign: 'center', letterSpacing: '-0.01em' }}>
+        {quote}
+      </p>
+      <span className="absolute bottom-6 left-1/2 -translate-x-1/2 w-1/3">{mark}</span>
+    </div>
+  )
+}
+
+/**
+ * ProfileAvatar — the round profile mark (1:1).
+ *
+ * The forks called it `Avatar`, which is already a kol-component atom (a
+ * PERSON's avatar). Two packages exporting one name is a collision the roster
+ * gate catches; this is the social-profile frame, so it takes the longer name.
+ *
+ * @param {ReactNode} mark - The brand mark
+ * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
+ * @param {string} bg - Ground colour; unset, the `paper` stop
+ * @param {'dark'|'light'} polarity - Which way the mark inks against that ground (default: 'dark')
+ * @param {string} className - Extra classes on the frame
+ */
+export function ProfileAvatar({ mark, palette, bg, polarity = 'dark', className = '' }) {
+  const [pal] = resolve(palette)
+  return (
+    <div
+      className={`aspect-square rounded-full flex items-center justify-center overflow-hidden ${className}`.trim()}
+      style={{ background: bg ?? pal.paper, color: polarity === 'light' ? pal.paper : pal.ink }}
+    >
+      <span className="w-1/2">{mark}</span>
+    </div>
+  )
+}

package/src/StationeryMocks.jsx

@@ -0,0 +1,386 @@
+/**
+ * StationeryMocks — the printed stationery set a brand manual shows: business
+ * card front/back, DL envelope, letterhead (plain and correspondence), and the
+ * email signature.
+ *
+ * Lifted from the two brand apps (`brand-book-mocks-two-consumers`,
+ * 2026-09-03). ASSET-AGNOSTIC like `LogoCard` and `SocialMocks`: the mark is a
+ * consumer-injected node, the brand's own details arrive as `info`, and every
+ * body string is a prop or a child. The geometry — paddings, type sizes, the
+ * rules and the grids — is carried through from the forks unchanged.
+ *
+ * ⚠ **SIX of the fork's TWENTY-SEVEN exports are here.** The other 21 are the
+ * garment / packaging kit (hangtags, swing tags, care · neck · size labels,
+ * edition cards, dust bags, garment bags, gift boxes, and their B variants —
+ * ~500 lines). They are NOT ported yet, deliberately: that file had accreted
+ * three clients' content in one place — a customer's real name and street
+ * address in the letter body, prices in €, another brand's woven-label
+ * references, and a palette its own source comment attributes to *"another
+ * client, carried in with the app"*. Carrying that through verbatim would ship
+ * one client's correspondence inside a shared package; stripping it is not a
+ * port but a new API of 21 components with four to eight text props each. The
+ * remainder is recorded on the ticket for the user's ruling.
+ *
+ *   const brand = { mark: <Asset name="logomark" />, info: BRAND_INFO }
+ *   <AssetCard caption="Business card">
+ *     <div style={{ aspectRatio: '85 / 55' }}><BusinessCardFront {...brand} /></div>
+ *   </AssetCard>
+ *
+ * Every mock fills its container (`w-full h-full`) and takes its proportion
+ * from the wrapper — the forks' contract, so a card is sized by an 85×55 box
+ * and a letterhead by an A4 one, never by the component.
+ */
+
+/* Neutral placeholders. Nothing here is a real brand's data — a consumer
+ * passes its own `info` and the defaults exist so an un-fed mock still shows
+ * the layout rather than collapsing. */
+export const DEFAULT_BRAND_INFO = {
+  identity: { name: 'Brand name', role: 'Role', founder: 'Founder name' },
+  contact: { email: 'hello@example.com', phone: '+00 000 0000', web: 'example.com' },
+  studio: { street: 'Street 1', postcode: '000 City', city: 'City', country: 'Country', locShort: 'City' },
+  legal: { entity: 'Entity name', kt: '000000-0000' },
+  labels: { madeIn: 'Made in' },
+}
+
+export const DEFAULT_STATIONERY_PALETTE = {
+  paper: '#FCFBFB',
+  ink: '#131316',
+  accent: '#F3F1EC',
+}
+
+export const DEFAULT_STATIONERY_FONTS = {
+  display: 'var(--kol-font-family-sans-narrow)',
+  text: 'var(--kol-font-family-sans)',
+  mono: 'var(--kol-font-family-mono)',
+}
+
+/* One resolver for all six so a consumer can pass a partial `info` (just
+ * `contact`, say) without the rest going undefined mid-render. */
+function resolve(info, palette, fonts) {
+  const merged = {
+    identity: { ...DEFAULT_BRAND_INFO.identity, ...info?.identity },
+    contact: { ...DEFAULT_BRAND_INFO.contact, ...info?.contact },
+    studio: { ...DEFAULT_BRAND_INFO.studio, ...info?.studio },
+    legal: { ...DEFAULT_BRAND_INFO.legal, ...info?.legal },
+    labels: { ...DEFAULT_BRAND_INFO.labels, ...info?.labels },
+  }
+  return [
+    merged,
+    { ...DEFAULT_STATIONERY_PALETTE, ...palette },
+    { ...DEFAULT_STATIONERY_FONTS, ...fonts },
+  ]
+}
+
+const capsStyle = (fonts) => ({
+  fontFamily: fonts.mono,
+  fontWeight: 500,
+  letterSpacing: '0.1em',
+  textTransform: 'uppercase',
+})
+
+/**
+ * BusinessCardFront — the mark, centred, on paper.
+ *
+ * @param {ReactNode} mark - The brand mark; sized to 70% of the card height
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {string} className - Extra classes on the card
+ */
+export function BusinessCardFront({ mark, palette, className = '' }) {
+  const [, pal] = resolve(null, palette)
+  return (
+    <div
+      className={`w-full h-full flex items-center justify-center p-8 [&_svg]:w-auto [&_svg]:h-full ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <span className="max-h-[70%] flex items-center">{mark}</span>
+    </div>
+  )
+}
+
+/**
+ * BusinessCardBack — role and name over the contact block, inked.
+ *
+ * @param {Object} info - Partial override of DEFAULT_BRAND_INFO — reads identity.role, identity.founder, contact.email, contact.phone, studio.city, studio.country
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_STATIONERY_FONTS
+ * @param {string} className - Extra classes on the card
+ */
+export function BusinessCardBack({ info, palette, fonts, className = '' }) {
+  const [brand, pal, font] = resolve(info, palette, fonts)
+  return (
+    <div
+      className={`w-full h-full flex flex-col justify-between p-8 border border-fg-08 ${className}`.trim()}
+      style={{ background: pal.ink, color: pal.paper }}
+    >
+      <div>
+        <p style={{ ...capsStyle(font), fontSize: 9, opacity: 0.6 }}>{brand.identity.role}</p>
+        <p style={{ fontFamily: font.display, fontSize: 18, fontWeight: 500, marginTop: 4 }}>
+          {brand.identity.founder}
+        </p>
+      </div>
+      <div style={{ fontFamily: font.mono, fontSize: 9, lineHeight: 1.6, letterSpacing: '0.05em' }}>
+        <p>{brand.contact.email}</p>
+        <p>{brand.contact.phone}</p>
+        <p>{brand.studio.city}, {brand.studio.country}</p>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Envelope — DL, mark top-left, return address bottom-right, fold line.
+ *
+ * @param {ReactNode} mark - The brand mark, in an 8-unit-tall box
+ * @param {Object} info - Partial override of DEFAULT_BRAND_INFO — reads identity.name and the studio block
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_STATIONERY_FONTS
+ * @param {string} className - Extra classes on the envelope
+ */
+export function Envelope({ mark, info, palette, fonts, className = '' }) {
+  const [brand, pal, font] = resolve(info, palette, fonts)
+  return (
+    <div
+      className={`w-full h-full relative p-8 [&_svg]:w-auto [&_svg]:h-full ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <div
+        className="absolute inset-x-0 top-1/2 border-t border-dashed"
+        style={{ borderColor: 'rgba(0,0,0,0.08)' }}
+      />
+      <div className="absolute top-8 left-8 h-8">{mark}</div>
+      <div
+        className="absolute bottom-8 right-8 text-right"
+        style={{ fontFamily: font.text, fontSize: 11, lineHeight: 1.5, color: pal.ink, opacity: 0.8 }}
+      >
+        <p>{brand.identity.name}</p>
+        <p>{brand.studio.street}</p>
+        <p>{brand.studio.postcode}</p>
+        <p>{brand.studio.country}</p>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Letterhead — A4: wordmark, body, contact rule at the foot.
+ *
+ * @param {ReactNode} mark - The brand mark (a wordmark in the forks), in a 10-unit-tall box
+ * @param {Object} info - Partial override of DEFAULT_BRAND_INFO — reads identity.founder, contact.web, contact.phone, studio.city, studio.country
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_STATIONERY_FONTS
+ * @param {ReactNode} children - The letter body; omitted, nothing renders between the mark and the signoff
+ * @param {ReactNode} signoff - Line above the signature (default: 'Warmly,')
+ * @param {string} className - Extra classes on the sheet
+ */
+export function Letterhead({ mark, info, palette, fonts, children, signoff = 'Warmly,', className = '' }) {
+  const [brand, pal, font] = resolve(info, palette, fonts)
+  return (
+    <div
+      className={`w-full h-full flex flex-col p-12 [&_svg]:w-auto [&_svg]:h-auto ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <div className="h-10 mb-12 [&_svg]:h-full [&_svg]:w-auto">{mark}</div>
+      <div
+        style={{
+          fontFamily: font.text,
+          fontSize: 10,
+          lineHeight: 1.7,
+          color: pal.ink,
+          fontWeight: 300,
+          letterSpacing: '0.02em',
+        }}
+      >
+        {children}
+        <p>{signoff}</p>
+        <p style={{ fontFamily: font.display, fontSize: 12, fontWeight: 500, marginTop: 16 }}>
+          {brand.identity.founder}
+        </p>
+      </div>
+      <div
+        className="mt-auto pt-8 border-t"
+        style={{
+          borderColor: 'rgba(0,0,0,0.08)',
+          fontFamily: font.mono,
+          fontSize: 8,
+          letterSpacing: '0.06em',
+          color: pal.ink,
+          opacity: 0.6,
+        }}
+      >
+        <p>{brand.contact.web}  ·  {brand.studio.city}, {brand.studio.country}  ·  {brand.contact.phone}</p>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * LetterheadCorrespondence — the richer sheet: mark + address block, a
+ * date/ref/to grid, the body, a signed signoff, and a legal footer.
+ *
+ * The forks called this `LetterheadB`. Renamed on the way in — a B suffix says
+ * nothing about which sheet to reach for, and this is the correspondence
+ * variant. `LetterheadB` is exported as an alias so a fork can migrate without
+ * touching its call sites.
+ *
+ * @param {ReactNode} mark - The brand mark for the header, 48px tall
+ * @param {ReactNode} signature - Mark or scan above the signed name, 22px tall in the forks
+ * @param {Object} info - Partial override of DEFAULT_BRAND_INFO — reads the studio, contact, identity and legal blocks
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_STATIONERY_FONTS
+ * @param {Array<{label: string, value: ReactNode}>} fields - The date/ref/to grid; each row is a caps label and its value
+ * @param {ReactNode} children - The letter body
+ * @param {ReactNode} signoff - Line above the signature (default: 'With thanks,')
+ * @param {ReactNode} page - Footer page marker (default: 'Page 01 / 01')
+ * @param {string} className - Extra classes on the sheet
+ */
+export function LetterheadCorrespondence({
+  mark,
+  signature,
+  info,
+  palette,
+  fonts,
+  fields = [],
+  children,
+  signoff = 'With thanks,',
+  page = 'Page 01 / 01',
+  className = '',
+}) {
+  const [brand, pal, font] = resolve(info, palette, fonts)
+  const inkAt = (alpha) => `rgba(19,19,22,${alpha})`
+
+  return (
+    <div
+      className={`w-full h-full flex flex-col p-7 [&_svg]:w-auto [&_svg]:h-auto ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <div className="flex justify-between items-start">
+        <span className="[&_svg]:h-12 [&_svg]:w-auto">{mark}</span>
+        <div
+          style={{
+            fontFamily: font.mono,
+            fontSize: 6.5,
+            lineHeight: 1.7,
+            color: inkAt(0.6),
+            letterSpacing: '0.08em',
+            textTransform: 'uppercase',
+            textAlign: 'right',
+          }}
+        >
+          {brand.studio.street}<br />
+          {brand.studio.locShort}<br />
+          {brand.contact.email}<br />
+          {brand.contact.phone}
+        </div>
+      </div>
+
+      {fields.length > 0 && (
+        <div
+          className="grid mt-6"
+          style={{
+            gridTemplateColumns: 'auto 1fr',
+            columnGap: 16,
+            rowGap: 3,
+            fontFamily: font.mono,
+            fontSize: 6.5,
+            letterSpacing: '0.04em',
+            color: inkAt(0.85),
+          }}
+        >
+          {fields.map((field) => (
+            <div key={field.label} className="contents">
+              <span style={{ color: inkAt(0.45), textTransform: 'uppercase', letterSpacing: '0.18em', fontSize: 6 }}>
+                {field.label}
+              </span>
+              <span>{field.value}</span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div
+        className="mt-5 flex-1"
+        style={{ fontFamily: font.text, fontSize: 7.5, lineHeight: 1.6, color: inkAt(0.88), letterSpacing: '0.005em' }}
+      >
+        {children}
+        <p style={{ margin: '0 0 7px 0' }}>{signoff}</p>
+        <div style={{ marginTop: 12 }}>
+          {signature && (
+            <span className="block [&_svg]:h-[22px] [&_svg]:w-auto" style={{ margin: '6px 0 4px' }}>
+              {signature}
+            </span>
+          )}
+          <div style={{ fontFamily: font.display, fontSize: 8, fontWeight: 600, letterSpacing: '0.02em' }}>
+            {brand.identity.founder}
+          </div>
+          <div
+            style={{
+              fontFamily: font.mono,
+              fontSize: 6,
+              letterSpacing: '0.18em',
+              textTransform: 'uppercase',
+              color: inkAt(0.55),
+              marginTop: 2,
+            }}
+          >
+            {brand.identity.role}
+          </div>
+        </div>
+      </div>
+
+      <div
+        className="mt-auto pt-2 flex justify-between"
+        style={{
+          fontFamily: font.mono,
+          fontSize: 5.5,
+          letterSpacing: '0.18em',
+          color: inkAt(0.45),
+          textTransform: 'uppercase',
+          borderTop: '0.5px solid rgba(19,19,22,0.18)',
+        }}
+      >
+        <span>{brand.legal.entity} · Kt. {brand.legal.kt}</span>
+        <span>{brand.contact.web}</span>
+        <span>{page}</span>
+      </div>
+    </div>
+  )
+}
+
+/** Deprecated alias — the forks' name for LetterheadCorrespondence. */
+export const LetterheadB = LetterheadCorrespondence
+
+/**
+ * EmailSignature — mark, rule, name and contact line.
+ *
+ * @param {ReactNode} mark - The brand mark, in a 16-unit square
+ * @param {Object} info - Partial override of DEFAULT_BRAND_INFO — reads identity.founder, identity.name, contact.email, contact.web
+ * @param {Object} palette - Partial override of DEFAULT_STATIONERY_PALETTE
+ * @param {Object} fonts - Partial override of DEFAULT_STATIONERY_FONTS
+ * @param {ReactNode} role - The line under the name; unset, it composes identity.role and identity.name
+ * @param {string} className - Extra classes on the block
+ */
+export function EmailSignature({ mark, info, palette, fonts, role, className = '' }) {
+  const [brand, pal, font] = resolve(info, palette, fonts)
+  return (
+    <div
+      className={`flex items-center gap-6 p-6 rounded-sm ${className}`.trim()}
+      style={{ background: pal.paper, color: pal.ink }}
+    >
+      <div className="h-16 w-16 flex items-center justify-center [&_svg]:w-auto [&_svg]:h-full">{mark}</div>
+      <div className="border-l h-16" style={{ borderColor: 'rgba(0,0,0,0.12)' }} />
+      <div style={{ color: pal.ink }}>
+        <p style={{ fontFamily: font.display, fontSize: 16, fontWeight: 500, lineHeight: 1.2 }}>
+          {brand.identity.founder}
+        </p>
+        <p style={{ ...capsStyle(font), fontSize: 9, opacity: 0.6, marginTop: 2 }}>
+          {role ?? `${brand.identity.role} · ${brand.identity.name}`}
+        </p>
+        <p style={{ fontFamily: font.mono, fontSize: 10, marginTop: 8, lineHeight: 1.5, letterSpacing: '0.04em' }}>
+          <span style={{ opacity: 0.6 }}>{brand.contact.email}</span>
+          <span style={{ margin: '0 8px', opacity: 0.3 }}>·</span>
+          <span style={{ opacity: 0.6 }}>{brand.contact.web}</span>
+        </p>
+      </div>
+    </div>
+  )
+}

package/src/Swatch.jsx

@@ -0,0 +1,73 @@
+import { ColorSwatch } from '@kolkrabbi/kol-component'
+
+/**
+ * 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 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.
+ *
+ * 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 />
+ *
+ * The hex is uppercased — that is value formatting, not a text-transform on
+ * 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 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|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, height = 96, className = '' }) {
+  return (
+    /* 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"
+            className="absolute inset-0 flex items-center justify-center pointer-events-none"
+          >
+            {/* difference blend so the dot reads on any stop, light or dark —
+                the forks' trick, kept verbatim */}
+            <span
+              className="block rounded-full"
+              style={{ width: 10, height: 10, background: 'white', mixBlendMode: 'difference' }}
+            />
+          </span>
+        )}
+      </div>
+      {/* .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>
+    </div>
+  )
+}

package/src/index.js

@@ -22,6 +22,20 @@ export {
 } from './comboLayouts.jsx'
 export { generatePalette, fgOn, hexToHsl, hslToHex, GENERATION_MODES } from './comboMath.js'
 
+// The brand-book set the two brand apps were both maintaining locally
+// (brand-book-mocks-two-consumers, 2026-09-03).
+export { default as AssetCard } from './AssetCard.jsx'
+export { default as Swatch } from './Swatch.jsx'
+export {
+  PostPhoto, PostType, PostProduct, PostEditorial, StoryPhoto, StoryType, ProfileAvatar,
+  DEFAULT_MOCK_PALETTE, DEFAULT_MOCK_FONTS,
+} from './SocialMocks.jsx'
+export {
+  BusinessCardFront, BusinessCardBack, Envelope, Letterhead,
+  LetterheadCorrespondence, LetterheadB, EmailSignature,
+  DEFAULT_BRAND_INFO, DEFAULT_STATIONERY_PALETTE, DEFAULT_STATIONERY_FONTS,
+} from './StationeryMocks.jsx'
+
 // This barrel exports THIS package only. The convenience re-exports were
 // dropped in 0.3.0: `export … from '@kolkrabbi/kol-foundry'` made every import
 // of this package pull foundry + opentype.js + framer-motion, so a consumer