@kolkrabbi/kol-styleguide 0.5.2 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 The KOL **style-guide / brand-guide** component set — the visual specimens a brand manual is built from. Raided from the monorepo `apps/brand` styleguide and assembled here because a brand guide is a shared capability with its own cadence, distinct from the core UI atoms.
 
-Colour anatomy + the **combination lab** (60/30/10 palette × layout × logo, incl. applied-brand mockups), **logo** construction / clearspace / scaling, **mood tiles**, **type blocks**, and **asset spec tables** — plus the colour/type specimen primitives (`ColorRamp`, `ColorSwatch`, `SpectrumGrid`, `TypeSample`, `TypeSpecCard`, `ProsePreview`, `AssetGrid`, `FeatureSplit`) gathered from the core packages.
+Color anatomy + the **combination lab** (60/30/10 palette × layout × logo, incl. applied-brand mockups), **logo** construction / clearspace / scaling, **mood tiles**, **type blocks**, and **asset spec tables** — plus the color/type specimen primitives (`ColorRamp`, `ColorSwatch`, `SpectrumGrid`, `TypeSample`, `TypeSpecCard`, `ProsePreview`, `AssetGrid`, `FeatureSplit`) gathered from the core packages.
 
 ```js
 import { ComboLab, MoodTile, LogoCard, TypeBlock } from '@kolkrabbi/kol-styleguide'

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.5.2",
+  "version": "0.6.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. 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}.",
+  "description": "Brand guide components and the brand tool",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -19,10 +19,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-framework": "^0.44.0",
-    "@kolkrabbi/kol-component": "^0.226.0",
-    "@kolkrabbi/kol-icons": "^0.28.0",
-    "@kolkrabbi/kol-theme": "^0.153.0"
+    "@kolkrabbi/kol-component": "^0.237.0",
+    "@kolkrabbi/kol-icons": "^0.33.0",
+    "@kolkrabbi/kol-framework": "^0.48.0",
+    "@kolkrabbi/kol-theme": "^0.163.0"
   },
   "files": [
     "src",

package/src/AssetCard.jsx

@@ -23,7 +23,7 @@
  * 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} backdrop - CSS color for the frame ground (default: the fg-04 wash)
  * @param {string} className - Extra classes on the <figure>
  * @param {ReactNode} children - The mock
  */

package/src/AssetTable.jsx

@@ -3,7 +3,7 @@ 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
+ * handed a COLOR, 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) {
@@ -34,7 +34,7 @@ function resolveToken(token) {
  *   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
+ *   COMPUTED color, 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: Preview appears only when a row carries a

package/src/Brand.jsx

@@ -7,10 +7,10 @@ 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)
+ * Brand — The whole brand tool. 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.
+ * media-hub'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

package/src/BrandAssets.jsx

@@ -3,7 +3,7 @@ import { ContentCollection, FullscreenOverlay, Table } from '@kolkrabbi/kol-comp
 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 { BrandAvatar } from './SocialMocks.jsx'
 import { BusinessCardBack, BusinessCardFront, EmailSignature, Envelope, Letterhead } from './StationeryMocks.jsx'
 import BrandMark from './BrandMark.jsx'
 import { Prose, SectionIndex } from './BrandBook.jsx'
@@ -29,7 +29,7 @@ const brandedAssetCols = [
 ]
 
 /**
- * BrandAssets — the ASSETS page of the brand tool: what you download or reproduce. Logos (the
+ * BrandAssets — The brand book's assets page. 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.
  *
@@ -134,7 +134,7 @@ export default function BrandAssets({ brand, Logo, logoSources }) {
             <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>
+                  <AssetCard key={i}><BrandAvatar mark={mark(marks.avatar, { className: 'w-1/2' })} bg={bg} polarity={polarity} /></AssetCard>
                 ))}
               </div>
             </PageSection>

package/src/BrandBook.jsx

@@ -11,7 +11,7 @@ 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
+ * BrandBook — The brand book's identity page. 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
@@ -114,7 +114,7 @@ export function SectionIndex({ sections }) {
   )
 }
 
-/* Colour — the copy, then one swatch row per ramp under its label and note. The first ramp's
+/* Color — 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 }) {

package/src/LogoCard.jsx

@@ -3,7 +3,7 @@ import ClearspaceDiagram, { hasFramework } from './ClearspaceDiagram.jsx'
 import { ToggleSwitch } from '@kolkrabbi/kol-component'
 
 /**
- * LogoCard — framed logo specimen tile with a clearspace / grid toggle.
+ * LogoCard — A logo specimen tile. framed logo specimen tile with a clearspace / grid toggle.
  *
  * A brand-manual logo plate: the mark centered in a padded frame, an optional
  * caption, and — when construction overlays are supplied — a toggle that reveals

package/src/SocialMocks.jsx

@@ -11,7 +11,7 @@
  * - `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.
+ *   its own; the DS ships no color.
  * - `'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
@@ -26,7 +26,7 @@
  *   const brand = { mark: <Asset name="logomark" />, palette: { accent: '#F3F1EC' } }
  *   <PostPhoto {...brand} />
  *   <StoryType {...brand} quote={<>Quiet,<br/>considered.</>} />
- *   <ProfileAvatar {...brand} />
+ *   <BrandAvatar {...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.
@@ -61,7 +61,7 @@ const resolve = (palette, fonts) => [
 ]
 
 /**
- * PostPhoto — feed post, photo ground with the mark in the corner (1:1).
+ * PostPhoto — A photo feed post. 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
@@ -83,7 +83,7 @@ export function PostPhoto({ mark, palette, fonts, media, className = '' }) {
 }
 
 /**
- * PostType — feed post, type-driven quote on the accent ground (1:1).
+ * PostType — A type-driven feed post. 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
@@ -107,7 +107,7 @@ export function PostType({ mark, palette, fonts, quote = 'Your line here.', clas
 }
 
 /**
- * PostProduct — feed post, product flat with a caption row (1:1).
+ * PostProduct — A product feed post. 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
@@ -153,7 +153,7 @@ export function PostProduct({
 }
 
 /**
- * PostEditorial — feed post, half photo / half type (1:1).
+ * PostEditorial — A half photo and half type post. feed post, half photo / half type (1:1).
  *
  * @param {ReactNode} mark - The brand mark
  * @param {Object} palette - Partial override of DEFAULT_MOCK_PALETTE
@@ -194,7 +194,7 @@ export function PostEditorial({
 }
 
 /**
- * StoryPhoto — story frame, full-bleed photo with the mark low-left (9:16).
+ * StoryPhoto — A full-bleed photo story. 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
@@ -216,7 +216,7 @@ export function StoryPhoto({ mark, palette, fonts, media, className = '' }) {
 }
 
 /**
- * StoryType — story frame, type-driven with the mark centred low (9:16).
+ * StoryType — A type-driven story. 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
@@ -240,7 +240,9 @@ export function StoryType({ mark, palette, fonts, quote = 'Your line here.', cla
 }
 
 /**
- * ProfileAvatar — the round profile mark (1:1).
+ * BrandAvatar — The brand's round profile mark. the round profile mark (1:1). Renamed from
+ * `ProfileAvatar` 2026-10-01 (user ruling): it is a brand-book mock of the brand's mark in a social
+ * profile frame, not a second `Avatar` — that one is a person. `ProfileAvatar` is the alias.
  *
  * 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
@@ -248,11 +250,11 @@ export function StoryType({ mark, palette, fonts, quote = 'Your line here.', cla
  *
  * @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 {string} bg - Ground color; 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 = '' }) {
+export function BrandAvatar({ mark, palette, bg, polarity = 'dark', className = '' }) {
   const [pal] = resolve(palette)
   return (
     <div
@@ -263,3 +265,6 @@ export function ProfileAvatar({ mark, palette, bg, polarity = 'dark', className
     </div>
   )
 }
+
+/** @deprecated 2026-10-01 — use BrandAvatar. Drops when nobody imports it (04-retirements.md). */
+export const ProfileAvatar = BrandAvatar

package/src/StationeryMocks.jsx

@@ -79,7 +79,7 @@ const capsStyle = (fonts) => ({
 })
 
 /**
- * BusinessCardFront — the mark, centred, on paper.
+ * BusinessCardFront — The front of a business card. 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
@@ -128,7 +128,7 @@ export function BusinessCardBack({ info, palette, fonts, className = '' }) {
 }
 
 /**
- * Envelope — DL, mark top-left, return address bottom-right, fold line.
+ * Envelope — A DL 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
@@ -162,7 +162,7 @@ export function Envelope({ mark, info, palette, fonts, className = '' }) {
 }
 
 /**
- * Letterhead — A4: wordmark, body, contact rule at the foot.
+ * Letterhead — An A4 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
@@ -214,7 +214,7 @@ export function Letterhead({ mark, info, palette, fonts, children, signoff = 'Wa
 }
 
 /**
- * LetterheadCorrespondence — the richer sheet: mark + address block, a
+ * LetterheadCorrespondence — A letterhead for correspondence. 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
@@ -350,7 +350,7 @@ export function LetterheadCorrespondence({
 export const LetterheadB = LetterheadCorrespondence
 
 /**
- * EmailSignature — mark, rule, name and contact line.
+ * EmailSignature — An email signature. 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

package/src/Swatch.jsx

@@ -1,11 +1,11 @@
 import { ColorSwatch } from '@kolkrabbi/kol-component'
 
 /**
- * Swatch — the DOCUMENTED swatch: a specimen bar over its meta row (name, hex),
+ * Swatch — A documented color 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
+ * for paint bars and inspectors. A color 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
@@ -31,7 +31,7 @@ import { ColorSwatch } from '@kolkrabbi/kol-component'
  * 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 {string} hex - The color, 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)

package/src/TypeBlock.jsx

@@ -5,12 +5,12 @@ import { familyFor } from './typographyCuts'
  *
  * 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,
+ * line-height, case, alignment, color, 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
+ * **Position + color are the consumer's job.** TypeBlock owns no positioned
+ * container, outline, or drag chrome, and inherits color by default
  * (`currentColor`) so the surrounding surface / theme drives ink. Wrap it in
  * whatever tile, row, or frame the specimen page needs.
  *
@@ -38,7 +38,7 @@ import { familyFor } from './typographyCuts'
  *   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)
+ *   strokeColor  outline color (required for stroke to render)
  *   className    extra classes on the sample element
  *   style        inline-style overrides merged last
  */

package/src/brandBook.js

@@ -6,7 +6,7 @@
  * or reproduce — each a stack of sections. The section ids, eyebrows, titles and ledes below are
  * that app's, verbatim — except the Logos and Branded ledes, which named files in that repo and are
  * left for its manifest to set; 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
+ * the color 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.
  */
 
@@ -100,7 +100,7 @@ export const BRANDED_ASSET_ROWS = [
 ]
 
 /** 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. */
+ *  (media-hub 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)

package/src/index.js

@@ -1,6 +1,6 @@
 // @kolkrabbi/kol-styleguide — the brand style-guide component set.
 //
-// Visual specimens a brand manual is built from — colour anatomy + the
+// Visual specimens a brand manual is built from — color 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
@@ -27,7 +27,7 @@ export { generatePalette, fgOn, hexToHsl, hslToHex, GENERATION_MODES } from './c
 export { default as AssetCard } from './AssetCard.jsx'
 export { default as Swatch } from './Swatch.jsx'
 export {
-  PostPhoto, PostType, PostProduct, PostEditorial, StoryPhoto, StoryType, ProfileAvatar,
+  PostPhoto, PostType, PostProduct, PostEditorial, StoryPhoto, StoryType, BrandAvatar, ProfileAvatar,
   DEFAULT_MOCK_PALETTE, DEFAULT_MOCK_FONTS,
 } from './SocialMocks.jsx'
 export {