@kolkrabbi/kol-component 0.102.2 → 0.103.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.102.2",
+  "version": "0.103.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/molecules/ContentText.jsx

@@ -81,7 +81,10 @@ const RAMP = {
      * caption disappeared. */
     /* the drawer is an INVERSE surface, so the roles do not apply — but the
      * ladder does: one full ink, the rest stepped. */
-    card: { title: 'kol-sans-display-03 text-fg-inverse', meta: 'kol-mono-12 text-fg-inverse-64', body: 'kol-mono-14 text-fg-inverse-64', date: 'kol-mono-12 text-fg-inverse-48', tags: 'flex flex-wrap gap-2' },
+    /* RULED ON /work GRID + shelf (WorkCardAndShelf, 2026-08-27): the title is one
+     * line (the site passes its face as titleClass; the truncation is the card's),
+     * the meta is the helper voice, uppercase, at inverse 80 */
+    card: { title: 'kol-sans-display-03 text-fg-inverse truncate', meta: 'kol-helper-12 uppercase text-fg-inverse-80', body: 'kol-mono-14 text-fg-inverse-64', date: 'kol-mono-12 text-fg-inverse-48', tags: 'flex flex-wrap gap-2' },
     /* verbatim from WorkListItem: title `kol-mono-14` truncated · type
      * `kol-mono-12 md:kol-mono-14` at FULL ink, no opacity step · year
      * `kol-mono-12 text-fg-64` · description `kol-sans-heading-03 text-auto`.

package/src/organisms/SectionCards.jsx

@@ -1,4 +1,5 @@
 import SectionCardItem from '../molecules/SectionCardItem.jsx'
+import { surfaceClass } from './sectionSurface.js'
 import SectionText, { HEADLINE_ROLE } from '../molecules/SectionText.jsx'
 import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
@@ -29,9 +30,12 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {object|Function} itemStyle       inline style per card, or `(index) => style`
  * @param {object}    slotClass · slotStyle  per-slot class / style on the header text
  * @param {string}    sectionClassName · wrapperClassName · cardsWrapperClassName · actionsClassName · headerClassName · headerTextWidthClass  layout seams
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 export default function SectionCards({
   theme,
+  background,
   height = '60',
   features = [],
   eyebrow,
@@ -60,7 +64,7 @@ export default function SectionCards({
   const eb = eyebrow ?? label
   const [themeRef, themeStamp] = useSectionTheme(theme)
   return (
-    <section ref={themeRef} data-theme={themeStamp} className={`w-full flex flex-col justify-center ${minHeightClass(height)} ${theme ? 'bg-surface-primary' : ''} ${sectionClassName}`.replace(/\s+/g, ' ').trim()}>
+    <section ref={themeRef} data-theme={themeStamp} className={`w-full flex flex-col justify-center ${minHeightClass(height)} ${surfaceClass(background, theme ? 'primary' : 'none')} ${sectionClassName}`.replace(/\s+/g, ' ').trim()}>
       <div className={wrapperClassName}>
         {(eb || headline || body) && (
           <SectionText

package/src/organisms/SectionCta.jsx

@@ -1,4 +1,5 @@
 import Button from '../atoms/Button.jsx'
+import { surfaceClass } from './sectionSurface.js'
 import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
 
@@ -26,9 +27,12 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {string}    email         contact-row value + `mailto:` target; omit to drop the row
  * @param {{label: ReactNode, value: ReactNode, href?: string}[]} secondaryRows  extra rows between prompt and contact
  * @param {string}    className     extra classes on the section
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 export default function SectionCta({
   variant = 'editorial',
+  background,
   height = '60',
   headline,
   body,
@@ -45,7 +49,7 @@ export default function SectionCta({
 }) {
   if (variant === 'centered') {
     return (
-      <section className={`w-full flex flex-col justify-center py-24 ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}>
+      <section className={`w-full flex flex-col justify-center py-24 ${surfaceClass(background, 'auto')} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}>
         <div className="w-full max-w-[var(--kol-container-max,var(--kol-content-shell,1800px))] mx-auto">
           <div className="w-32 h-px bg-fg-24 mx-auto mb-8" />
           <SectionText
@@ -72,7 +76,7 @@ export default function SectionCta({
     ...(email ? [{ label: contactLabel, value: email, href: `mailto:${email}` }] : []),
   ]
   return (
-    <section className={`w-full bg-auto flex flex-col justify-center ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}>
+    <section className={`w-full ${surfaceClass(background, 'auto')} flex flex-col justify-center ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}>
       {/* the family's ONE cap — the shell's --kol-container-max ladder (user
         * ruling 2026-08-26; the 1600 SectionCtaEditorial asked for was a third
         * number beside split's 1200 and cards' 1400) — the surface stays full

package/src/organisms/SectionFaq.jsx

@@ -1,4 +1,5 @@
 import { useState } from 'react'
+import { surfaceClass } from './sectionSurface.js'
 import { Accordion, AccordionPanel } from '../molecules/Accordion.jsx'
 import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
@@ -17,6 +18,8 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}   [singleOpen=false]  opening one panel closes the others
  * @param {number}    [defaultOpen]       index open on mount (singleOpen) — omit for all closed
  * @param {string}    className · innerClassName  layout seams
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 export default function SectionFaq({
   eyebrow,
@@ -29,6 +32,7 @@ export default function SectionFaq({
   singleOpen = false,
   defaultOpen,
   height = '60',
+  background,
   slotClass,
   slotStyle,
   className = '',
@@ -40,7 +44,7 @@ export default function SectionFaq({
   const eb = eyebrow ?? label
   const [open, setOpen] = useState(defaultOpen ?? null)
   return (
-    <section className={`kol-section-faq w-full flex flex-col justify-center px-5 py-16 md:px-8 md:py-24 lg:px-14 ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}>
+    <section className={`kol-section-faq w-full flex flex-col justify-center px-5 py-16 md:px-8 md:py-24 lg:px-14 ${minHeightClass(height)} ${surfaceClass(background, 'none')} ${className}`.replace(/\s+/g, ' ').trim()}>
       <div className="w-full max-w-[var(--kol-container-max,var(--kol-content-shell,1800px))] mx-auto">
       <div className={innerClassName}>
         {(eb || headline || body || actions) && (

package/src/organisms/SectionHero.jsx

@@ -1,4 +1,5 @@
 import { isValidElement } from 'react'
+import { surfaceClass } from './sectionSurface.js'
 import HlsVideo from '../atoms/HlsVideo.jsx'
 import Image from '../atoms/Image.jsx'
 import OverlayGlassPanel from '../utilities/OverlayGlassPanel.jsx'
@@ -143,10 +144,13 @@ function MediaLayer({ media }) {
  *                                   split: 'left' | 'right' — the media side
  * @param {boolean}   fullBleed      span the full viewport width (100vw breakout) — split
  * @param {string}    className      extra classes on the section
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 export default function SectionHero({
   variant = 'media',
   theme,
+  background,
   fullBleed = false,
   media,
   overlayOpacity = 0,
@@ -189,7 +193,7 @@ export default function SectionHero({
   /* `label` = alias of `eyebrow` (2026-08-27) */
   const eb = eyebrow ?? label
   const [themeRef, themeStamp] = useSectionTheme(theme)
-  const themed = theme ? 'bg-surface-primary' : ''
+  const themed = surfaceClass(background, theme ? 'primary' : 'none')
 
   if (variant === 'split') {
     const mediaFirst = align !== 'right'

package/src/organisms/SectionNewsletter.jsx

@@ -1,4 +1,5 @@
 import { useId, useState } from 'react'
+import { surfaceClass } from './sectionSurface.js'
 import Input from '../atoms/Input.jsx'
 import Button from '../atoms/Button.jsx'
 import SectionText from '../molecules/SectionText.jsx'
@@ -44,10 +45,13 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {string}    inputId      id override for the email input (default useId-generated)
  * @param {object}    slotClass · slotStyle   per-slot class / style on the SectionText (reveal seam)
  * @param {string}    className    extra classes on the section
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 export default function SectionNewsletter({
   height = '60',
   theme,
+  background,
   eyebrow,
   label,
   headline,
@@ -99,7 +103,7 @@ export default function SectionNewsletter({
       id={id}
       ref={themeRef}
       data-theme={themeStamp}
-      className={`kol-section-newsletter w-full flex flex-col justify-center py-24 ${theme ? 'bg-surface-primary text-auto' : ''} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}
+      className={`kol-section-newsletter w-full flex flex-col justify-center py-24 ${surfaceClass(background, theme ? 'primary' : 'none')} ${theme ? 'text-auto' : ''} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}
     >
       {/* the family's ONE cap — the shell's --kol-container-max ladder — and
         * inside it the lede's MEASURE on a wrapper (SectionNewsletterForm,

package/src/organisms/SectionSplit.jsx

@@ -1,4 +1,5 @@
 import SectionText from '../molecules/SectionText.jsx'
+import { surfaceClass } from './sectionSurface.js'
 import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
@@ -50,10 +51,13 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}   fullBleed    span the full viewport width
  * @param {object}    slotClass · slotStyle  per-slot class / style on the text block (reveal seam)
  * @param {string}    className · innerClassName · columnClassName  layout seams
+ * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
+ *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
  */
 
 export default function SectionSplit({
   theme,
+  background,
   eyebrow,
   label,
   headline,
@@ -93,7 +97,7 @@ export default function SectionSplit({
     <section
       ref={themeRef}
       data-theme={themeStamp}
-      className={`kol-section-split flex flex-col justify-center px-5 py-16 md:px-8 md:py-24 lg:px-14 lg:py-32 [--kol-section-py:4rem] md:[--kol-section-py:6rem] lg:[--kol-section-py:8rem] ${minHeightClass(height)} ${bleed} ${className}`.replace(/\s+/g, ' ').trim()}
+      className={`kol-section-split flex flex-col justify-center px-5 py-16 md:px-8 md:py-24 lg:px-14 lg:py-32 [--kol-section-py:4rem] md:[--kol-section-py:6rem] lg:[--kol-section-py:8rem] ${minHeightClass(height)} ${surfaceClass(background, 'none')} ${bleed} ${className}`.replace(/\s+/g, ' ').trim()}
       style={sectionStyle}
     >
       {/* ONE cap for the whole section family (user ruling 2026-08-26): the shell's

package/src/organisms/sectionSurface.js

@@ -0,0 +1,17 @@
+/* ONE surface prop across the section family (SectionBackgroundProp, kol-website
+ * 2026-08-27 — user: "ALL section family should pass bg as props"). A named
+ * surface, `none`, or a raw utility / token string for the odd case
+ * (`'bg-fg-absolute-16'`). Each section's default is what it painted before,
+ * so nothing moves on the bump. `theme` keeps scoping ink; this is the paint. */
+export const SURFACES = {
+  primary: 'bg-surface-primary',
+  secondary: 'bg-surface-secondary',
+  tertiary: 'bg-surface-tertiary',
+  inverse: 'bg-surface-inverse',
+  auto: 'bg-auto',
+  none: '',
+}
+export const surfaceClass = (background, fallback = 'none') => {
+  const key = background ?? fallback
+  return key in SURFACES ? SURFACES[key] : key
+}