@kolkrabbi/kol-styleguide 0.1.0

package/src/MoodTile.jsx

@@ -0,0 +1,42 @@
+/**
+ * MoodTile — image tile with a centered logo overlay.
+ *
+ * A cover-cropped photo in a 4:3 frame, an optional centered brand-logo
+ * overlay, and an optional caption below. Image and logo are consumer-injected
+ * (no app coupling): pass an image `src` / `alt` and a `logo` node.
+ *
+ * Class contract (chrome lives in @kolkrabbi/kol-theme →
+ * packages/framework/kol-framework.css):
+ *   .kol-mood-tile-frame img              — absolute inset-0, object-cover (crop)
+ *   .kol-mood-tile-overlay .kol-brand-logo — logo box sized to 32% / max 180px
+ *   .kol-mood-tile-overlay svg            — svg fills its wrapper (width 100%)
+ *
+ * Props:
+ *   src     — image URL.
+ *   alt     — image alt text. Default ''.
+ *   logo    — logo node centered over the image (e.g. a brand <svg> or a
+ *             logo component). Wrapped in .kol-brand-logo for overlay sizing.
+ *   overlay — show the logo overlay. Default true (only renders when `logo`
+ *             is also provided).
+ *   caption — optional caption string rendered below the frame. Author its
+ *             casing at the call site (no auto text-transform).
+ */
+export default function MoodTile({ src, alt = '', logo, overlay = true, caption }) {
+  return (
+    <figure className="kol-mood-tile">
+      <div className="kol-mood-tile-frame relative rounded-[4px] overflow-hidden aspect-[4/3]">
+        <img src={src} alt={alt} loading="lazy" />
+        {overlay && logo && (
+          <div className="kol-mood-tile-overlay text-emphasis absolute inset-0 flex items-center justify-center pointer-events-none">
+            <span className="kol-brand-logo">{logo}</span>
+          </div>
+        )}
+      </div>
+      {caption && (
+        <figcaption className="kol-helper-12 tracking-wider text-meta mt-2">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  )
+}

package/src/TypeBlock.jsx

@@ -0,0 +1,89 @@
+import { familyFor } from './typographyCuts'
+
+/**
+ * TypeBlock — typography specimen primitive.
+ *
+ * Renders one sample string with a fully consumer-controlled type treatment:
+ * cut (Right Grotesk width / mono), weight, italic, size, tracking,
+ * line-height, case, alignment, colour, and an optional stroke. A pure,
+ * stateless render — feed it props, it draws the specimen. Defaults land on
+ * Right Grotesk regular so a bare `<TypeBlock />` shows a legible baseline.
+ *
+ * **Position + colour are the consumer's job.** TypeBlock owns no positioned
+ * container, outline, or drag chrome, and inherits colour by default
+ * (`currentColor`) so the surrounding surface / theme drives ink. Wrap it in
+ * whatever tile, row, or frame the specimen page needs.
+ *
+ * The sample is intentionally *style-driven*, not a fixed `kol-*` type class —
+ * previewing arbitrary cuts / sizes is the whole point. It is kept
+ * wrap-capable (`overflow-wrap` + `white-space: pre-wrap`) so multi-line
+ * samples flow, honouring the mono wrap-vs-nowrap fault line for wrapping text.
+ *
+ * Ported from the monorepo apps/brand styleguide TypeBlock (2026-07). The
+ * source's contentEditable inline-edit / drag-select behaviour (Type-Lab editor
+ * chrome) is dropped — a DS specimen is a presentational render. The source's
+ * nested `value` object is flattened to discrete props.
+ *
+ * Props:
+ *   text         sample string (default 'Right Grotesk')
+ *   cut          Right Grotesk cut key or 'mono' — resolved via familyFor
+ *   weight       numeric font-weight (100–900)
+ *   italic       render the italic style
+ *   size         font-size in px
+ *   tracking     letter-spacing in em
+ *   lineHeight   unitless line-height
+ *   case         CSS text-transform keyword the CONSUMER opts into
+ *                ('none' | 'uppercase' | 'lowercase' | 'capitalize').
+ *                Default 'none' — never baked on; the sample is never mutated.
+ *   align        text-align
+ *   color        ink (default 'currentColor' — inherit from surface / theme)
+ *   strokeWidth  outline width in px (0 = none)
+ *   strokeColor  outline colour (required for stroke to render)
+ *   className    extra classes on the sample element
+ *   style        inline-style overrides merged last
+ */
+export default function TypeBlock({
+  text = 'Right Grotesk',
+  cut = 'base',
+  weight = 400,
+  italic = false,
+  size = 48,
+  tracking = 0,
+  lineHeight = 1,
+  case: textCase = 'none',
+  align = 'left',
+  color = 'currentColor',
+  strokeWidth = 0,
+  strokeColor,
+  className = '',
+  style,
+  ...rest
+}) {
+  const hasStroke = strokeWidth > 0 && Boolean(strokeColor)
+  return (
+    <div
+      className={className}
+      style={{
+        fontFamily: `'${familyFor(cut)}', 'Right Grotesk', sans-serif`,
+        fontWeight: weight,
+        fontStyle: italic ? 'italic' : 'normal',
+        fontSize: `${size}px`,
+        letterSpacing: `${tracking}em`,
+        lineHeight,
+        textAlign: align,
+        color,
+        textTransform: textCase,
+        WebkitTextStrokeColor: hasStroke ? strokeColor : undefined,
+        WebkitTextStrokeWidth: hasStroke ? `${strokeWidth}px` : undefined,
+        paintOrder: hasStroke ? 'stroke fill' : undefined,
+        minHeight: '1em',
+        overflowWrap: 'break-word',
+        whiteSpace: 'pre-wrap',
+        ...style,
+      }}
+      {...rest}
+    >
+      {text}
+    </div>
+  )
+}

package/src/comboLayouts.jsx

@@ -0,0 +1,206 @@
+/**
+ * ComboLab — stage layout primitives.
+ *
+ * Each layout takes `{ palette, logo }` and renders its geometry with the
+ * palette's role-colors (primary / secondary / light / dark / accent).
+ * Structural CSS is DS-owned under `.kol-combo-*`
+ * (packages/theme/kol-components-styleguide.css → currently shipped from
+ * packages/framework/kol-framework.css). Inline styles here are strictly
+ * data-driven (background + fg-on color from the palette) — the classes carry
+ * everything else, so nothing is re-invented.
+ *
+ * DECOUPLING NOTE: the monorepo original imported a hard `KolLogo` brand
+ * component. Here `logo` is a consumer-injected React node — <LogoSlot/>
+ * renders whatever the host passes (a logomark, an <img>, an <svg>) and
+ * renders nothing when it's absent. No brand-app coupling.
+ */
+import { fgOn } from './comboMath.js'
+
+/* LogoSlot — renders the injected logo node at a fixed inline width. */
+const LogoSlot = ({ logo, size = 48 }) => {
+  if (!logo) return null
+  return (
+    <span className="kol-combo-logo" style={{ width: size }}>
+      {logo}
+    </span>
+  )
+}
+
+/* ────────── 60 / 30 / 10 ────────── */
+export function RatioBar({ palette, logo }) {
+  const { primary, secondary, light } = palette
+  return (
+    <div className="kol-combo-stage kol-combo-frame kol-combo-stage--fill kol-combo-stage--ratio">
+      <div className="kol-combo-slab" style={{ background: primary, color: fgOn(primary) }}>
+        <span className="kol-combo-label">Primary</span>
+        <LogoSlot logo={logo} size={48} />
+        <span className="kol-combo-number">10</span>
+      </div>
+      <div className="kol-combo-slab" style={{ background: secondary, color: fgOn(secondary) }}>
+        <span className="kol-combo-label">Secondary</span>
+        <span className="kol-combo-number">30</span>
+      </div>
+      <div className="kol-combo-slab" style={{ background: light, color: fgOn(light) }}>
+        <span className="kol-combo-label">Neutral</span>
+        <span className="kol-combo-number">60</span>
+      </div>
+    </div>
+  )
+}
+
+/* ────────── Tower — 4-band vertical ────────── */
+export function Tower({ palette, logo }) {
+  const { primary, secondary, light, dark } = palette
+  const band = (bg, label) => (
+    <div className="kol-combo-slab kol-combo-slab--end" style={{ background: bg, color: fgOn(bg) }}>
+      <span className="kol-combo-label">{label}</span>
+    </div>
+  )
+  return (
+    <div className="kol-combo-stage kol-combo-frame kol-combo-stage--tower">
+      <div className="kol-combo-slab kol-combo-slab--between" style={{ background: primary, color: fgOn(primary) }}>
+        <LogoSlot logo={logo} size={48} />
+        <span className="kol-combo-label">Primary</span>
+      </div>
+      {band(secondary, 'Secondary')}
+      {band(light, 'Light')}
+      {band(dark, 'Dark')}
+    </div>
+  )
+}
+
+/* ────────── Quad split — 50 / 25 / 25 ────────── */
+export function QuadSplit({ palette, logo }) {
+  const { primary, light, dark, accent } = palette
+  return (
+    <div className="kol-combo-stage kol-combo-frame kol-combo-stage--fill kol-combo-stage--quad">
+      <div className="kol-combo-slab kol-combo-slab--between" style={{ background: primary, color: fgOn(primary) }}>
+        <LogoSlot logo={logo} size={64} />
+        <span className="kol-combo-label">Primary · 50</span>
+      </div>
+      <div className="kol-combo-quad-col">
+        <div className="kol-combo-slab kol-combo-slab--end" style={{ background: light, color: fgOn(light) }}>
+          <span className="kol-combo-label">Light · 25</span>
+        </div>
+        <div className="kol-combo-slab kol-combo-slab--between" style={{ background: dark, color: fgOn(dark) }}>
+          <span className="kol-combo-label" style={{ color: accent }}>Accent</span>
+          <span className="kol-combo-label">Dark · 25</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/* ────────── Card row — 4 discrete cards ────────── */
+export function CardRow({ palette, logo }) {
+  const { primary, secondary, light, dark } = palette
+  const card = (bg, label, withLogo = false) => (
+    <div
+      className={`kol-combo-card kol-combo-frame${withLogo ? ' kol-combo-card--between' : ' kol-combo-card--end'}`}
+      style={{ background: bg, color: fgOn(bg) }}
+    >
+      {withLogo && <LogoSlot logo={logo} size={40} />}
+      <span className="kol-combo-label">{label}</span>
+    </div>
+  )
+  return (
+    <div className="kol-combo-stage kol-combo-stage--card-row">
+      {card(primary, 'Primary', true)}
+      {card(secondary, 'Secondary')}
+      {card(light, 'Light')}
+      {card(dark, 'Dark')}
+    </div>
+  )
+}
+
+/* ────────── Stripe row — Method 01 / 02 proportion bars ────────── */
+export function StripeRow({ palette }) {
+  const { primary, secondary, light, dark, accent } = palette
+  /* Rule color = dark at ~12% alpha, passed via CSS custom prop so the
+     .kol-combo-stripe-neutral class owns the border declarations. */
+  const ruleColor = `${dark}20`
+  return (
+    <div
+      className="kol-combo-stage kol-combo-frame kol-combo-stage--stripe-row"
+      style={{
+        '--stripe-rule': ruleColor,
+        '--stripe-accent': accent,
+      }}
+    >
+      {/* Method 01 — single-row proportion bar */}
+      <div className="kol-combo-stripe-row">
+        <div className="kol-combo-stripe-bar">
+          <div className="kol-combo-stripe-seg kol-combo-stripe-seg--6" style={{ background: primary }} />
+          <div className="kol-combo-stripe-seg kol-combo-stripe-seg--3 kol-combo-stripe-neutral" style={{ background: light }} />
+          <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: accent }} />
+          <span className="kol-combo-stripe-method">Method 01</span>
+        </div>
+      </div>
+      {/* Method 02 — split-row */}
+      <div className="kol-combo-stripe-row">
+        <div className="kol-combo-stripe-bar">
+          <div className="kol-combo-stripe-group kol-combo-stripe-group--3">
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: primary }} />
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: secondary }} />
+          </div>
+          <div className="kol-combo-stripe-group kol-combo-stripe-group--3">
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1 kol-combo-stripe-neutral" style={{ background: light }} />
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: light }} />
+          </div>
+          <div className="kol-combo-stripe-group kol-combo-stripe-group--1">
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: accent }} />
+            <div className="kol-combo-stripe-seg kol-combo-stripe-seg--1" style={{ background: dark }} />
+          </div>
+          <span className="kol-combo-stripe-method">Method 02</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/* ────────── Applied card — brand-application "business card" mockup ────────── */
+export function AppliedCard({ palette, logo }) {
+  const { primary, secondary, light, dark, accent } = palette
+  return (
+    <div className="kol-combo-stage kol-combo-frame kol-combo-stage--applied" style={{ background: light }}>
+      {/* Main logo plate — the card front */}
+      <div className="kol-combo-applied-plate" style={{ background: primary, color: fgOn(primary) }}>
+        <LogoSlot logo={logo} size={72} />
+        <span className="kol-combo-label">Front</span>
+      </div>
+      {/* Right swatch column — surface + accent chips + bands */}
+      <div className="kol-combo-applied-col">
+        <div className="kol-combo-slab kol-combo-slab--between kol-combo-applied-surface" style={{ background: light, color: fgOn(light) }}>
+          <span className="kol-combo-label">Surface</span>
+          <div className="kol-combo-applied-accent-strip">
+            <span className="kol-combo-applied-accent-chip" style={{ background: secondary }} />
+            <span className="kol-combo-applied-accent-chip" style={{ background: accent }} />
+          </div>
+        </div>
+        <div className="kol-combo-applied-band kol-combo-applied-band--lg" style={{ background: secondary }} />
+        <div className="kol-combo-applied-band kol-combo-applied-band--sm" style={{ background: dark }} />
+      </div>
+    </div>
+  )
+}
+
+/* Layout registry — id → component. */
+export const LAYOUT_COMPONENTS = {
+  'ratio-603010': RatioBar,
+  'tower':        Tower,
+  'quad-split':   QuadSplit,
+  'card-row':     CardRow,
+  'stripe-row':   StripeRow,
+  'applied-card': AppliedCard,
+}
+
+/* Layout metadata — id + label for pickers. Kept beside the registry so the
+   two can't drift. */
+export const COMBO_LAYOUTS = [
+  { id: 'ratio-603010', label: '60 / 30 / 10' },
+  { id: 'tower',        label: 'Tower' },
+  { id: 'quad-split',   label: 'Quad split' },
+  { id: 'card-row',     label: 'Card row' },
+  { id: 'stripe-row',   label: 'Stripe row' },
+  { id: 'applied-card', label: 'Applied card' },
+]

package/src/comboMath.js

@@ -0,0 +1,281 @@
+/**
+ * comboMath — palette engine for <ComboLab/> (plain JS, framework-agnostic).
+ *
+ * Raided from apps/generator palette mode (colorMath.js + the `fgOn` chooser
+ * from palettes.js). Two generation paths:
+ *   - Pool-based  — sample a caller-supplied array of hex, OR pick a random
+ *                   base from it and derive the other slots via HSL math.
+ *   - Seed-based  — slot 0 = a base color, slots 1–4 derived via the mode.
+ *
+ * DECOUPLING NOTE: the monorepo original resolved its color pools live from
+ * CSS custom properties (`resolveCssVar` in pools.js). That resolver is
+ * dropped here — it duplicates the DS token layer and forces a DOM dependency
+ * on a plain helper. <ComboLab/> is fully data-injected instead: the caller
+ * passes literal palettes and/or a `pool` array of hex, so this module never
+ * reads the CSS-var cascade.
+ */
+
+/* ────────── HSL <-> hex ────────── */
+
+export function hexToHsl(hex) {
+  const r = parseInt(hex.slice(1, 3), 16) / 255
+  const g = parseInt(hex.slice(3, 5), 16) / 255
+  const b = parseInt(hex.slice(5, 7), 16) / 255
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  let h = 0, s = 0
+  const l = (max + min) / 2
+  if (max !== min) {
+    const d = max - min
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+    switch (max) {
+      case r: h = (g - b) / d + (g < b ? 6 : 0); break
+      case g: h = (b - r) / d + 2; break
+      case b: h = (r - g) / d + 4; break
+    }
+    h *= 60
+  }
+  return { h, s: s * 100, l: l * 100 }
+}
+
+export function hslToHex(h, s, l) {
+  s = Math.max(0, Math.min(100, s)) / 100
+  l = Math.max(0, Math.min(100, l)) / 100
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = l - c / 2
+  let r = 0, g = 0, b = 0
+  if      (h <  60) { r = c; g = x; b = 0 }
+  else if (h < 120) { r = x; g = c; b = 0 }
+  else if (h < 180) { r = 0; g = c; b = x }
+  else if (h < 240) { r = 0; g = x; b = c }
+  else if (h < 300) { r = x; g = 0; b = c }
+  else              { r = c; g = 0; b = x }
+  const toHex = (v) => Math.round((v + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase()
+}
+
+/* ────────── Foreground chooser (WCAG-ish luminance flip) ────────── */
+
+/**
+ * Pick the text color with the best contrast against a background hex.
+ * Used by every layout primitive to keep labels legible on any slot color.
+ */
+export function fgOn(bg) {
+  const hex = bg.replace('#', '')
+  const r = parseInt(hex.slice(0, 2), 16)
+  const g = parseInt(hex.slice(2, 4), 16)
+  const b = parseInt(hex.slice(4, 6), 16)
+  const L = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+  return L > 0.55 ? '#0E0E11' : '#FAFAFA'
+}
+
+/* ────────── sampling helpers ────────── */
+
+const pickRandom = (arr) => arr[Math.floor(Math.random() * arr.length)]
+const shuffle    = (arr) => [...arr].sort(() => Math.random() - 0.5)
+const fillTo = (arr, n) => {
+  if (arr.length >= n) return arr.slice(0, n)
+  const out = [...arr]
+  while (out.length < n) out.push(pickRandom(arr))
+  return out
+}
+
+/* ────────── Pool-based modes — pick a random base from pool, derive 6 ────────── */
+
+const MODES = {
+  random: (pool) => fillTo(shuffle(pool), 6),
+
+  monochromatic: (pool) => {
+    const { h, s } = hexToHsl(pickRandom(pool))
+    return [10, 25, 40, 55, 70, 85].map((l) => hslToHex(h, s, l))
+  },
+
+  analogous: (pool) => {
+    const { h, s, l } = hexToHsl(pickRandom(pool))
+    return [-45, -25, -10, 10, 25, 45].map((o) => hslToHex((h + o + 360) % 360, s, l))
+  },
+
+  complementary: (pool) => {
+    const { h, s, l } = hexToHsl(pickRandom(pool))
+    return [
+      hslToHex(h, s, Math.max(15, l - 25)),
+      hslToHex(h, s, l),
+      hslToHex(h, s, Math.min(85, l + 25)),
+      hslToHex((h + 180) % 360, s, Math.max(15, l - 15)),
+      hslToHex((h + 180) % 360, s, l),
+      hslToHex((h + 180) % 360, s, Math.min(85, l + 15)),
+    ]
+  },
+
+  triadic: (pool) => {
+    const { h, s, l } = hexToHsl(pickRandom(pool))
+    return [
+      hslToHex(h, s, l),
+      hslToHex((h + 120) % 360, s, l),
+      hslToHex((h + 240) % 360, s, l),
+      hslToHex(h, s, Math.min(85, l + 20)),
+      hslToHex((h + 120) % 360, s, Math.max(15, l - 20)),
+      hslToHex((h + 240) % 360, s, Math.min(85, l + 20)),
+    ]
+  },
+
+  doubleComplementary: (pool) => {
+    const { h, s, l } = hexToHsl(pickRandom(pool))
+    return [
+      hslToHex(h, s, l),
+      hslToHex((h + 90) % 360, s, l),
+      hslToHex((h + 180) % 360, s, l),
+      hslToHex((h + 270) % 360, s, l),
+      hslToHex(h, s, Math.min(85, l + 20)),
+      hslToHex((h + 180) % 360, s, Math.max(15, l - 20)),
+    ]
+  },
+}
+
+/* ────────── Seed-based modes — slot 0 = base, slots 1-5 jittered derivations ────────── */
+
+const jitter = (range) => (Math.random() - 0.5) * 2 * range
+
+const SEED_MODES = {
+  random: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    return [
+      base,
+      hslToHex((h + Math.random() * 360) % 360, s, l),
+      hslToHex((h + Math.random() * 360) % 360, s, l),
+      hslToHex(h, s, Math.max(10, l - 25 + jitter(10))),
+      hslToHex(h, s, Math.min(90, l + 25 + jitter(10))),
+      hslToHex(h, s * (0.4 + Math.random() * 0.4), l),
+    ]
+  },
+
+  monochromatic: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    const j = 8
+    return [
+      base,
+      hslToHex(h, s, Math.max(10, l - 30 + jitter(j))),
+      hslToHex(h, s, Math.max(20, l - 15 + jitter(j))),
+      hslToHex(h, s, Math.min(85, l + 15 + jitter(j))),
+      hslToHex(h, s, Math.min(95, l + 30 + jitter(j))),
+      hslToHex(h, s, Math.min(98, l + 45 + jitter(j))),
+    ]
+  },
+
+  analogous: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    return [
+      base,
+      hslToHex((h - 30 + jitter(8) + 360) % 360, s, l),
+      hslToHex((h - 15 + jitter(8) + 360) % 360, s, l),
+      hslToHex((h + 15 + jitter(8)) % 360, s, l),
+      hslToHex((h + 30 + jitter(8)) % 360, s, l),
+      hslToHex((h + 45 + jitter(8)) % 360, s, l),
+    ]
+  },
+
+  complementary: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    return [
+      base,
+      hslToHex(h, s, Math.max(15, l - 25 + jitter(8))),
+      hslToHex(h, s, Math.min(85, l + 25 + jitter(8))),
+      hslToHex((h + 180 + jitter(10)) % 360, s, l),
+      hslToHex((h + 180 + jitter(10)) % 360, s, Math.max(15, l - 15 + jitter(8))),
+      hslToHex((h + 180 + jitter(10)) % 360, s, Math.min(85, l + 15 + jitter(8))),
+    ]
+  },
+
+  triadic: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    return [
+      base,
+      hslToHex((h + 120 + jitter(10)) % 360, s, l),
+      hslToHex((h + 240 + jitter(10)) % 360, s, l),
+      hslToHex(h, s, Math.min(85, l + 20 + jitter(8))),
+      hslToHex((h + 120 + jitter(10)) % 360, s, Math.max(15, l - 20 + jitter(8))),
+      hslToHex((h + 240 + jitter(10)) % 360, s, Math.min(85, l + 20 + jitter(8))),
+    ]
+  },
+
+  doubleComplementary: (base) => {
+    const { h, s, l } = hexToHsl(base)
+    return [
+      base,
+      hslToHex((h + 90 + jitter(10)) % 360, s, l),
+      hslToHex((h + 180 + jitter(10)) % 360, s, l),
+      hslToHex((h + 270 + jitter(10)) % 360, s, l),
+      hslToHex(h, s, Math.min(85, l + 20 + jitter(8))),
+      hslToHex((h + 180 + jitter(10)) % 360, s, Math.max(15, l - 20 + jitter(8))),
+    ]
+  },
+}
+
+/* Mode metadata for a caller-supplied mode picker (pure data, no CSS). */
+export const GENERATION_MODES = [
+  { id: 'random',              label: 'Random'      },
+  { id: 'monochromatic',       label: 'Mono'        },
+  { id: 'analogous',           label: 'Analogous'   },
+  { id: 'complementary',       label: 'Complement'  },
+  { id: 'triadic',             label: 'Triadic'     },
+  { id: 'doubleComplementary', label: 'Double comp' },
+]
+
+/**
+ * Pick a 6th (background) color unused by the 5 layout slots. Falls back to an
+ * HSL lightness shift when the pool is exhausted.
+ */
+function pickBgColor(layoutColors, pool) {
+  const used = new Set(layoutColors.map((c) => c.toUpperCase()))
+  const candidates = pool.filter((c) => !used.has(c.toUpperCase()))
+  if (candidates.length > 0) return pickRandom(candidates)
+
+  const base = pickRandom(pool)
+  const { h, s, l } = hexToHsl(base)
+  for (const shift of [-20, 20, -35, 35, -50, 50]) {
+    const candidate = hslToHex(h, s, Math.max(5, Math.min(95, l + shift))).toUpperCase()
+    if (!used.has(candidate)) return candidate
+  }
+  return hslToHex(h, s, l > 50 ? 5 : 95)
+}
+
+/** Background for a seed-derived palette — a lightness shift off the seed. */
+function pickBgFromSeed(layoutColors, baseColor) {
+  const used = new Set(layoutColors.map((c) => c.toUpperCase()))
+  const { h, s, l } = hexToHsl(baseColor)
+  for (const shift of [-50, 50, -35, 35, -20, 20]) {
+    const candidate = hslToHex(h, s, Math.max(5, Math.min(95, l + shift))).toUpperCase()
+    if (!used.has(candidate)) return candidate
+  }
+  return hslToHex(h, s, l > 50 ? 5 : 95)
+}
+
+/**
+ * Generate 6 colors `[primary, secondary, light, dark, accent, bg]`,
+ * preserving any locked slots.
+ *
+ * - `baseColor` set  → seed path: slots derived from the base via SEED_MODES.
+ * - `baseColor` null → pool path: sample `pool` via MODES.
+ *
+ * @param {string[]} pool           Hex array to sample (pool path).
+ * @param {string}   mode           Mode id (see GENERATION_MODES).
+ * @param {string[]} currentColors  Current 6 colors (used for locked slots).
+ * @param {boolean[]} locks         Per-slot lock flags.
+ * @param {string}  [baseColor]     Seed hex — switches to the seed path.
+ */
+export function generatePalette(pool, mode, currentColors, locks, baseColor) {
+  let layoutColors
+  let bgColor
+  if (baseColor) {
+    const gen = SEED_MODES[mode] ?? SEED_MODES.random
+    layoutColors = gen(baseColor).slice(0, 5)
+    bgColor = pickBgFromSeed(layoutColors, baseColor)
+  } else {
+    const gen = MODES[mode] ?? MODES.random
+    layoutColors = gen(pool).slice(0, 5)
+    bgColor = pickBgColor(layoutColors, pool)
+  }
+  const final = [...layoutColors, bgColor]
+  return final.map((c, i) => (locks && locks[i] ? currentColors[i] : c))
+}

package/src/index.js

@@ -0,0 +1,28 @@
+// @kolkrabbi/kol-styleguide — the brand style-guide component set.
+//
+// Visual specimens a brand manual is built from — colour anatomy + the
+// combination lab, logo construction / clearspace / scaling, mood tiles,
+// type blocks, asset spec tables. Raided from the monorepo apps/brand
+// styleguide (2026-07). Styling ships in @kolkrabbi/kol-theme
+// (kol-components-styleguide.css, layer components); data is consumer-injected.
+//
+// Exports are appended as each component lands.
+export { default as MoodTile } from './MoodTile.jsx'
+export { default as ColorAnatomy } from './ColorAnatomy.jsx'
+export { default as TypeBlock } from './TypeBlock.jsx'
+export { default as AssetTable } from './AssetTable.jsx'
+export { WEIGHTS, CUTS, CASES, familyFor } from './typographyCuts.js'
+export { default as LogoCard } from './LogoCard.jsx'
+export { default as ClearspaceDiagram, hasFramework } from './ClearspaceDiagram.jsx'
+export { default as LogoScaling } from './LogoScaling.jsx'
+export { default as ComboLab, DEFAULT_PALETTE } from './ComboLab.jsx'
+export {
+  RatioBar, Tower, QuadSplit, CardRow, StripeRow, AppliedCard,
+  LAYOUT_COMPONENTS, COMBO_LAYOUTS,
+} from './comboLayouts.jsx'
+export { generatePalette, fgOn, hexToHsl, hslToHex, GENERATION_MODES } from './comboMath.js'
+
+// Re-exported styleguide primitives — live in the core packages, surfaced here
+// so a brand guide imports from one place. Not duplicated: same modules.
+export { AssetGrid, FeatureSplit, ProsePreview, SpectrumGrid } from '@kolkrabbi/kol-component'
+export { TypeSample, TypeSpecCard } from '@kolkrabbi/kol-foundry'