@designcrowd/library.brand-page 6.2.11-builder-v2-1 → 6.2.12

package/lib/src/brand-page/utils/color.util.js

@@ -1,8 +1,13 @@
+/**
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: its colour bake reaches `backgroundColorFromStyle`,
+ * `isTransparentColour` and `isHexTransparent` through `container-text-color.util.ts`. After
+ * migration-22 releases, pin their v22 behaviour in the migration before changing them.
+ */
 import isHexColor from 'validator/lib/isHexColor';
 import { hexToRGBA, RGBAtoHex } from '@src/utils/helpers';
 // Leaf module, not the `@brand-page/utils` barrel — the barrel's larger graph races
 // module init and these come back undefined under some import orders.
-import { bestContrastBrandRole, resolveColorReference, toColorVarReference, } from './color-palette.util';
+import { bestContrastBrandRole, resolveColorReference, toColorVarReference, PALETTE_COLOR_IDS, STRATEGY_COPY_MIN_CONTRAST, } from './color-palette.util';
 import Color, {} from 'color';
 // function from https://stackoverflow.com/a/9733420/3695983
 export const luminance = (r, g, b) => {
@@ -183,23 +188,59 @@ export const mutedTextForBackground = (bgColor, { targetContrast = 3.5, start =
 // both. The value may be a gradient/shorthand; callers that need a solid colour
 // pass it through mutedTextForBackground, which rejects anything unparseable.
 export const backgroundColorFromStyle = (style) => style?.backgroundColor || style?.background;
+// A solid, fully-opaque hex from any parseable colour, else undefined (transparent,
+// gradient, image, `var(--…)`, unparseable) — so a contrast check only runs against a real
+// surface.
+const solidHex = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        const parsed = Color(value);
+        return parsed.alpha() === 1 ? parsed.hex() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
- * The nav "theme" for a display-type switch: the base colour the caller passes (kept
- * verbatim, incl. its palette `var(--id)` reference) plus the contrasting palette-role
- * reference to pair with it — e.g. a TAB_2 selected button paints its background with
- * `primaryColor` and its label with `secondaryColor`.
+ * The nav "theme" for a header nav display-type switch. Nav themes off the LOGO, independently
+ * of the page's button styling (ADR-0022): `primaryColor` — the dominant nav colour used for
+ * default text, border and the selected button's fill — is the first brand role that stays
+ * legible (>= `STRATEGY_COPY_MIN_CONTRAST`) on the header background: logo text colour
+ * (`palette-0`), else logo background colour (`palette-1`), else a generated neutral.
+ * `secondaryColor` — the selected button's label — is the brand role that best contrasts
+ * `primaryColor` (`bestContrastBrandRole`), so the label reads on the filled pill
+ * ("encapsulated contrast").
  *
- * `secondaryColor` is a palette-role reference, not a resolved literal, so the label
- * keeps tracking palette edits. It is the brand role that reads best (WCAG) against the
- * base's resolved value; when the palette can't supply one (empty/blank palette) it
- * falls back to the base so we never mint an off-palette colour.
+ * Brand picks are returned as palette `var(--id)` references so the nav keeps tracking palette
+ * edits; only the neutral fallback is a literal. `headerBackgroundColor` is the preferred surface
+ * the nav sits on. When it does not paint, `pageBackgroundColor` is the surface visible behind the
+ * header; white is the final fallback when neither resolves to a solid colour.
  */
-export const getNavThemeByTextStyle = (textStyle, colors = []) => {
-    const primaryColor = textStyle.color;
-    const baseValue = resolveColorReference(primaryColor, colors, {
-        withRoleDefaults: true,
-    });
-    const contrastRole = bestContrastBrandRole(baseValue, colors);
+export const getNavThemeByTextStyle = (headerBackgroundColor, colors = [], pageBackgroundColor) => {
+    const logoTextColor = toColorVarReference(PALETTE_COLOR_IDS.primary);
+    const logoBackgroundColor = toColorVarReference(PALETTE_COLOR_IDS.secondary);
+    const resolvedSurface = (color) => solidHex(resolveColorReference(color ?? '', colors, { withRoleDefaults: true }));
+    // A transparent/unset header reveals the page surface. Image and gradient backgrounds have no
+    // single contrast anchor, so only then does the historic light fallback apply.
+    const surface = resolvedSurface(headerBackgroundColor) ??
+        resolvedSurface(pageBackgroundColor) ??
+        '#ffffff';
+    const clearsOnSurface = (roleRef) => {
+        const resolved = solidHex(resolveColorReference(roleRef, colors, { withRoleDefaults: true }));
+        return (!!resolved &&
+            contrastRatio(Color(resolved), Color(surface)) >=
+                STRATEGY_COPY_MIN_CONTRAST);
+    };
+    const primaryColor = clearsOnSurface(logoTextColor)
+        ? logoTextColor
+        : clearsOnSurface(logoBackgroundColor)
+            ? logoBackgroundColor
+            : (mutedTextForBackground(surface, {
+                targetContrast: STRATEGY_COPY_MIN_CONTRAST,
+            }) ?? logoTextColor);
+    const contrastRole = bestContrastBrandRole(resolveColorReference(primaryColor, colors, { withRoleDefaults: true }), colors);
     return {
         primaryColor,
         secondaryColor: contrastRole

package/lib/src/brand-page/utils/container-text-color.util.d.ts

@@ -7,9 +7,13 @@
  * surface they sit on, and what colour they default to, so the renderer
  * (`view-model.util.ts`) and the maker's Text Style panel cannot disagree — the same
  * reason `resolveTextColor` lives in one place (`text-style.util.ts`).
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: the v21 -> v22 colour bake calls
+ * `containerTextColorDefaults` and `titleSurfaceContrastFill`. Pin that migration's behaviour
+ * before changing either helper after it releases.
  */
-import type { Content, PageStyles, BrandPageType } from '../models';
-import type { ContentTextStylePropertyKey } from '../constants';
+import type { Content, PageStyles, BrandPageType, ColorItem } from '../models';
+import { type ContentTextStylePropertyKey } from '../constants';
 /**
  * The text-style fields that sit on the block's filled surface. `buttonTextStyle` is
  * excluded — it paints the button, which owns its own fill/text pairing.
@@ -29,6 +33,15 @@ export declare const CONTAINER_BOUND_TEXT_STYLE_KEYS: Partial<Record<Content['ty
  * scope here).
  */
 export declare const containerSurfaceForContent: (content: Content, styles: PageStyles, brandPageType?: BrandPageType) => BrandPageCssStyle | undefined;
+/**
+ * The colour the maker's Text Style swatch shows for a STANDALONE button's LABEL. The label is left
+ * uncoloured on the element (`isButtonLabelField` exempts it from the birth-time bake) and inherits
+ * the button's on-fill colour at render via CSS (`buttonStyles.style.color`). The panel has no
+ * inherited value to read off the element, so it derives the SAME colour here — the swatch matches
+ * the canvas, both from one helper, exactly as `containerTextColorDefaults` feeds the swatch for
+ * container-bound fields. `undefined` for a non-label field or a button with no text colour.
+ */
+export declare const buttonLabelColorDefault: (content: Content, styles: PageStyles, key: string) => string | undefined;
 /**
  * The container-aware default colour for each container-bound text field: the button
  * text colour (`styles.buttonStyles.style.color`), the theme-authored on-fill colour,
@@ -76,18 +89,38 @@ export declare const containerTextColorDefaults: (content: Content, styles: Page
  */
 export declare const rteFrameFallbackColour: (content: Content, styles: PageStyles, brandPageType?: BrandPageType) => string | undefined;
 /**
- * Bakes a readable colour into a container-bound block's text so the renderer just paints
- * what's stored (no render-time contrast logic). Run when the block is created and whenever
- * its text style changes.
+ * The contrast colour for whatever sits on the title's own surface — the one the title itself
+ * gets. Two callers: a social-links section's icons (baked once onto `iconFillStyles.fill` at
+ * migration or birth, so they never follow a title recolour) and a shop section's "no products"
+ * label (read live in the view model, so it does follow one — there's no stored field to freeze).
+ */
+export declare const titleSurfaceContrastFill: (content: Content, styles: PageStyles, brandPageType?: BrandPageType) => string | undefined;
+/**
+ * Bakes a readable colour into a SECTION's text at BIRTH so the renderer just paints what's
+ * stored (no render-time contrast logic). Run when a block is created and whenever its text
+ * style changes.
+ *
+ * Every text field (and every `textItems[]` entry) contrasts the topmost solid thing beneath it —
+ * its own field surface, else the section's painted surface, else the PAGE background
+ * (`effectiveFieldSurface`) — taking the brand hierarchy on a solid surface and `pageContrastColour`
+ * on the bare page (the replacement for the retired base coat, ADR-0020). The exempt fields never
+ * bake — the section CTA button label (`buttonTextStyle`) and copyright by key, and a standalone
+ * button's own label (`titleStyle` on an `isButtonContent`) by type; all own their fill/text
+ * pairing rather than a section surface. A field sitting on the button fill likewise defers to the
+ * render-time pairing. A social-links section's icons get their own stored fill
+ * (`titleSurfaceContrastFill`).
  *
- * For each container-bound text field with no colour of its own, on a solid surface that is
- * NOT the button fill, it writes whichever BRAND role contrasts THAT field's surface most —
- * the card for card fields, the option-button fill for `itemTextStyle`
- * (`surfaceForTextStyleKey`). A button-fill surface is skipped: its render-time pairing
- * (`containerTextColorDefaults`) supplies the button's own text colour, so `itemTextStyle`
- * on the default option fill needs no bake. Explicitly-coloured fields are left alone; so is
- * a palette with no usable brand role.
+ * Explicitly-coloured fields are left alone; so is a palette with no usable role.
  *
  * Mutates and returns `content`.
  */
-export declare const applyCardTextContrast: (content: Content, styles: PageStyles, brandPageType?: BrandPageType) => Content;
+export declare const applyTextContrast: (content: Content, styles: PageStyles, brandPageType?: BrandPageType) => Content;
+/**
+ * The topmost solid surface painted behind a section's text — the highest-stacked surface
+ * field that resolves to a visible solid — or `undefined` when the section paints nothing solid
+ * (the text then sits on the page background, `applyTextContrast`'s page branch). A field the
+ * section does not actually paint in its current layout is skipped (`isSurfaceFieldPainted`).
+ * Palette refs are resolved first (via `isSolidSurface`), so a `var(--palette-N)` fill counts as
+ * the solid it resolves to.
+ */
+export declare const topmostSolidSurface: (content: Content, colors?: ColorItem[]) => BrandPageCssStyle | undefined;

package/lib/src/brand-page/utils/container-text-color.util.js

@@ -1,6 +1,8 @@
 import { BRAND_PAGE_TYPES } from '../models';
+import { CONTENT_TEXT_STYLE_PROPERTY_KEYS, ALIGN_CARD_CENTER_IMAGE, ALIGN_CARD_LEFT_IMAGE, } from '../constants';
 import { backgroundColorFromStyle, isTransparentColour, isHexTransparent, } from './color.util';
-import { resolveColorReference, bestContrastBrandRole, toColorVarReference, roleValueOrDefault, } from './color-palette.util';
+import { isButtonContent } from './model.util';
+import { resolveColorReference, bestContrastBrandRole, bestContrastNeutralRole, firstViableContrastRole, toColorVarReference, roleValueOrDefault, isBlankColorValue, PALETTE_COLOR_IDS, STRATEGY_COPY_MIN_CONTRAST, } from './color-palette.util';
 /**
  * The text-style fields that sit on the block's filled surface. `buttonTextStyle` is
  * excluded — it paints the button, which owns its own fill/text pairing.
@@ -12,11 +14,17 @@ import { resolveColorReference, bestContrastBrandRole, toColorVarReference, role
  */
 export const CONTAINER_BOUND_TEXT_STYLE_KEYS = {
     'mailing-list': ['titleStyle'],
-    'request-payment': ['titleStyle', 'descriptionStyle', 'itemTextStyle'],
+    'request-payment': [
+        'titleStyle',
+        'descriptionStyle',
+        'successMessageStyle',
+        'itemTextStyle',
+    ],
     'support-me': [
         'titleStyle',
         'headingStyle',
         'descriptionStyle',
+        'successMessageStyle',
         'itemTextStyle',
     ],
     'contact-form': ['titleStyle', 'descriptionStyle', 'successMessageStyle'],
@@ -33,6 +41,17 @@ const BUTTON_BOUND_TEXT_STYLE_KEYS = {
     'request-payment': ['itemTextStyle'],
     'support-me': ['itemTextStyle'],
 };
+/**
+ * Shop's title and description sit on the band (`backgroundStyle`), never the product
+ * tile (`fillColor`) — a sibling surface stacked below them, not behind them. Routed here
+ * rather than through `topmostSolidSurface`'s generic top-of-stack scan, which would pick
+ * the tile fill first and MIScolour the title against a surface it doesn't sit on.
+ */
+const SHOP_BAND_ROUTED_KEYS = new Set([
+    'titleStyle',
+    'descriptionStyle',
+]);
+const isShopBandRoutedField = (content, key) => content.type === 'shop-section' && SHOP_BAND_ROUTED_KEYS.has(key);
 /**
  * The filled surface the block's text sits on: the block's OWN container colour
  * (`backgroundStyle`, or `cardStyle` for contact-form) when set, else the global
@@ -69,15 +88,59 @@ const optionButtonSurfaceForContent = (content, styles) => {
     const own = content.fillColor;
     return backgroundColorFromStyle(own) ? own : styles.buttonStyles?.style;
 };
+// The button label owns its own fill/text pairing and copyright is page-level — neither
+// contrasts a SECTION surface, so they get no birth-time contrast bake. This is keyed on the
+// FIELD name: `buttonTextStyle` is the CTA button embedded in a section (banner/about/…). A
+// STANDALONE button (general-link + its variants) instead keeps its label in `titleStyle` — a
+// key shared with ordinary headings — so that case is handled per content type, not here
+// (`isButtonLabelField`).
+const NON_SECTION_SURFACE_KEYS = new Set([
+    'buttonTextStyle',
+    'copyrightStyle',
+]);
+/**
+ * A standalone button's LABEL (`isButtonContent` → general-link, website, email, phone, and the
+ * social buttons — all store the label in `titleStyle`). Like `buttonTextStyle`, the label sits on
+ * the button fill, not a section surface: the button owns its own fill/text pairing, so it must not
+ * bake. With no baked colour the label inherits the button's on-fill text colour at render
+ * (`buttonStyles.style.color`), which is guaranteed to contrast the fill — whereas baking would
+ * contrast the PAGE instead and collide with the fill (the default theme paints both from the same
+ * brand role, hiding the text).
+ */
+const isButtonLabelField = (content, key) => key === 'titleStyle' && isButtonContent(content);
 /**
- * The surface a single container-bound text field contrasts: the option-button fill for
- * a button-bound field (`itemTextStyle`), else the block's card. THE per-field router
- * shared by the render default and the creation-time bake, so they cannot disagree on
- * which surface a field sits on.
+ * The colour the maker's Text Style swatch shows for a STANDALONE button's LABEL. The label is left
+ * uncoloured on the element (`isButtonLabelField` exempts it from the birth-time bake) and inherits
+ * the button's on-fill colour at render via CSS (`buttonStyles.style.color`). The panel has no
+ * inherited value to read off the element, so it derives the SAME colour here — the swatch matches
+ * the canvas, both from one helper, exactly as `containerTextColorDefaults` feeds the swatch for
+ * container-bound fields. `undefined` for a non-label field or a button with no text colour.
  */
-const surfaceForTextStyleKey = (content, styles, key, brandPageType) => BUTTON_BOUND_TEXT_STYLE_KEYS[content.type]?.includes(key)
-    ? optionButtonSurfaceForContent(content, styles)
-    : containerSurfaceForContent(content, styles, brandPageType);
+export const buttonLabelColorDefault = (content, styles, key) => isButtonLabelField(content, key)
+    ? styles.buttonStyles?.style?.color || undefined
+    : undefined;
+/**
+ * The surface a single text field contrasts — THE per-field router shared by the render
+ * default and the creation-time bake, so they cannot disagree on which surface a field sits
+ * on: the option-button fill for a button-bound field (`itemTextStyle`), the block's card
+ * for a container-bound field (with the brandSite contact-form carve-out), the section's own
+ * topmost solid surface for any other text field, and nothing for the button label /
+ * copyright (they don't sit on a section surface).
+ */
+const surfaceForTextStyleKey = (content, styles, key, brandPageType) => {
+    if (NON_SECTION_SURFACE_KEYS.has(key)) {
+        return undefined;
+    }
+    if (BUTTON_BOUND_TEXT_STYLE_KEYS[content.type]?.includes(key)) {
+        return optionButtonSurfaceForContent(content, styles);
+    }
+    if (isShopBandRoutedField(content, key)) {
+        return content.backgroundStyle;
+    }
+    return CONTAINER_BOUND_TEXT_STYLE_KEYS[content.type]?.includes(key)
+        ? containerSurfaceForContent(content, styles, brandPageType)
+        : topmostSolidSurface(content, styles.colors);
+};
 // A surface is worth contrasting only when it paints a visible solid. `transparent`
 // means the text really sits on whatever is behind, so defer to the global colour.
 // Palette refs are resolved to their value first (matching the render pass) so a
@@ -213,54 +276,271 @@ export const rteFrameFallbackColour = (content, styles, brandPageType) => {
  * resolved (`withRoleDefaults`); `bestContrastBrandRole` itself reads raw values because
  * its other callers pair it with their own blank-role fallbacks.
  */
-const cardContrastColour = (surface, styles) => {
+const contrastRoleColour = (surface, styles, best) => {
     const surfaceColour = resolveColorReference(backgroundColorFromStyle(surface) ?? '', styles.colors ?? [], { withRoleDefaults: true });
     if (!surfaceColour) {
         return undefined;
     }
-    const role = bestContrastBrandRole(surfaceColour, (styles.colors ?? []).map((c) => ({
+    const role = best(surfaceColour, (styles.colors ?? []).map((c) => ({
         ...c,
         value: roleValueOrDefault(c.id, c.value) ?? c.value,
-    })), 0);
+    })));
     return role ? toColorVarReference(role) : undefined;
 };
+// Brand roles in preference order: logo-text (`palette-0`) leads, logo-background (`palette-1`)
+// second — the site-identity hierarchy every text field follows before contrast is even compared.
+const BRAND_ROLE_HIERARCHY = [
+    PALETTE_COLOR_IDS.primary,
+    PALETTE_COLOR_IDS.secondary,
+];
+// The first brand role (by the hierarchy) that clears the minimum viable contrast on `against`.
+const viableBrandRole = (against, colors) => firstViableContrastRole(against, colors, BRAND_ROLE_HIERARCHY, STRATEGY_COPY_MIN_CONTRAST);
 /**
- * Bakes a readable colour into a container-bound block's text so the renderer just paints
- * what's stored (no render-time contrast logic). Run when the block is created and whenever
- * its text style changes.
- *
- * For each container-bound text field with no colour of its own, on a solid surface that is
- * NOT the button fill, it writes whichever BRAND role contrasts THAT field's surface most —
- * the card for card fields, the option-button fill for `itemTextStyle`
- * (`surfaceForTextStyleKey`). A button-fill surface is skipped: its render-time pairing
- * (`containerTextColorDefaults`) supplies the button's own text colour, so `itemTextStyle`
- * on the default option fill needs no bake. Explicitly-coloured fields are left alone; so is
- * a palette with no usable brand role.
- *
- * Mutates and returns `content`.
+ * Brand text on a SOLID surface (a card, or a section's own band). Follows the same logo-text-first
+ * hierarchy the page uses — `palette-0` while it clears the contrast floor, else `palette-1` — so a
+ * section leads with the brand identity rather than whichever brand merely contrasts most. A card
+ * always ends on a brand (never a neutral), so if neither role clears the floor it falls back to the
+ * best-contrast brand.
  */
-export const applyCardTextContrast = (content, styles, brandPageType) => {
-    const keys = CONTAINER_BOUND_TEXT_STYLE_KEYS[content.type];
-    if (!keys?.length) {
-        return content;
-    }
-    keys.forEach((key) => {
-        const field = content[key];
-        // Never overwrite an explicit element colour.
-        if (!field || field.color) {
-            return;
-        }
-        const surface = surfaceForTextStyleKey(content, styles, key, brandPageType);
-        // A button-fill surface is contrasted by the button's own text colour at render, so it
-        // needs no baked colour — skip it, exactly as a button-fill card is skipped.
-        if (!isSolidSurface(surface, styles.colors) ||
-            surfaceMatchesButtonFill(surface, styles)) {
+const cardContrastColour = (surface, styles) => contrastRoleColour(surface, styles, (against, colors) => viableBrandRole(against, colors) ??
+    bestContrastBrandRole(against, colors));
+/**
+ * The colour for text that sits on the PAGE background (a section that paints nothing solid),
+ * replacing the retired base coat. Same brand hierarchy as `cardContrastColour` — logo-text
+ * (`palette-0`) leads while it clears the floor, else `palette-1` — but where a card falls back to a
+ * brand, the page falls to the best-contrast NEUTRAL (legibility on a plain surface), and for an
+ * unresolvable page (image/gradient) to `neutral-dark`.
+ */
+const pageContrastColour = (styles) => {
+    const surface = styles.backgroundStyles?.style;
+    return (contrastRoleColour(surface, styles, viableBrandRole) ??
+        contrastRoleColour(surface, styles, bestContrastNeutralRole) ??
+        toColorVarReference(PALETTE_COLOR_IDS.neutralDark));
+};
+/**
+ * Assigns the birth-time colour for ONE text field, given the surface it sits on:
+ *  - a solid surface that is NOT the button fill → the brand hierarchy for it (`cardContrastColour`);
+ *  - a solid surface that IS the button fill → nothing (the render-time pairing supplies the
+ *    button's own text colour — the `itemTextStyle`-on-option-button case);
+ *  - no solid surface → the page background (`pageContrastColour`).
+ * Mutates `field`.
+ */
+const bakeFieldColour = (field, surface, styles) => {
+    if (isSolidSurface(surface, styles.colors)) {
+        if (surfaceMatchesButtonFill(surface, styles)) {
             return;
         }
         const colour = cardContrastColour(surface, styles);
         if (colour) {
             field.color = colour;
         }
+        return;
+    }
+    const colour = pageContrastColour(styles);
+    if (colour) {
+        field.color = colour;
+    }
+};
+/**
+ * The surface ANY text field ends up contrasting — a cascade so no field ever dead-ends
+ * uncoloured: the field's OWN surface (`surfaceForTextStyleKey`) if it paints a solid, else the
+ * SECTION's own painted surface (`topmostSolidSurface`) — which catches a container whose router
+ * yields nothing, e.g. the brandSite contact-form card — else `undefined`, meaning the page.
+ */
+const effectiveFieldSurface = (content, styles, key, brandPageType) => {
+    const own = surfaceForTextStyleKey(content, styles, key, brandPageType);
+    if (isSolidSurface(own, styles.colors)) {
+        return own;
+    }
+    // A shop title/description stops at the band: the section-wide fallback below would
+    // otherwise pick up the tile fill, the same surface `isShopBandRoutedField` steers
+    // around above.
+    return isShopBandRoutedField(content, key)
+        ? undefined
+        : topmostSolidSurface(content, styles.colors);
+};
+/**
+ * The contrast colour for whatever sits on the title's own surface — the one the title itself
+ * gets. Two callers: a social-links section's icons (baked once onto `iconFillStyles.fill` at
+ * migration or birth, so they never follow a title recolour) and a shop section's "no products"
+ * label (read live in the view model, so it does follow one — there's no stored field to freeze).
+ */
+export const titleSurfaceContrastFill = (content, styles, brandPageType) => {
+    const probe = {};
+    bakeFieldColour(probe, effectiveFieldSurface(content, styles, 'titleStyle', brandPageType), styles);
+    return probe.color;
+};
+// The colour on the first text run of an RTE doc (`item.text`), where the birth bake moves a
+// field's colour. Read-only depth-first walk; `undefined` for a plain string or an uncoloured run.
+const firstRunColour = (value) => {
+    const walk = (node) => {
+        if (node.type === 'text') {
+            return node.marks?.find((mark) => mark.type === 'textStyle')?.attrs
+                ?.color;
+        }
+        for (const child of node.content ?? []) {
+            const found = walk(child);
+            if (found) {
+                return found;
+            }
+        }
+        return undefined;
+    };
+    return typeof value === 'object' && value !== null
+        ? walk(value)
+        : undefined;
+};
+// Whether every VISIBLE run (non-whitespace text) in a doc carries a colour mark — used to decide
+// whether applyTextContrast's bake is redundant. A doc with some coloured runs and some not (an
+// accent word, or a hyperlink, which setRteTextColor always colours) still needs the bake, or its
+// uncoloured runs fall back to the inherited colour.
+const everyRunColoured = (value) => {
+    let sawVisibleRun = false;
+    let allColoured = true;
+    const walk = (node) => {
+        if (node.type === 'text') {
+            if (!node.text?.trim())
+                return;
+            sawVisibleRun = true;
+            if (!node.marks?.find((mark) => mark.type === 'textStyle')?.attrs?.color) {
+                allColoured = false;
+            }
+            return;
+        }
+        (node.content ?? []).forEach(walk);
+    };
+    if (typeof value === 'object' && value !== null)
+        walk(value);
+    return sawVisibleRun && allColoured;
+};
+// A text item's effective (rendered) colour. The RTE run MARK is authoritative and read FIRST: a
+// recolour writes the mark but does NOT clear a stale `textStyle.color` left by an earlier bake, so
+// preferring the style would return the old colour, not what the item shows. `textStyle.color` is
+// the fallback for an item that has no run yet (e.g. a freshly inherited, still-empty item).
+const textItemColour = (item) => firstRunColour(item.text) || item.textStyle?.color;
+// A top-level field's own doc, paired by name (`titleStyle` ↔ `title`, `descriptionStyle` ↔
+// `description`, …) — the same convention every Content model follows.
+const textFieldKey = (key) => key.replace(/Style$/, '');
+/**
+ * Bakes a readable colour into a SECTION's text at BIRTH so the renderer just paints what's
+ * stored (no render-time contrast logic). Run when a block is created and whenever its text
+ * style changes.
+ *
+ * Every text field (and every `textItems[]` entry) contrasts the topmost solid thing beneath it —
+ * its own field surface, else the section's painted surface, else the PAGE background
+ * (`effectiveFieldSurface`) — taking the brand hierarchy on a solid surface and `pageContrastColour`
+ * on the bare page (the replacement for the retired base coat, ADR-0020). The exempt fields never
+ * bake — the section CTA button label (`buttonTextStyle`) and copyright by key, and a standalone
+ * button's own label (`titleStyle` on an `isButtonContent`) by type; all own their fill/text
+ * pairing rather than a section surface. A field sitting on the button fill likewise defers to the
+ * render-time pairing. A social-links section's icons get their own stored fill
+ * (`titleSurfaceContrastFill`).
+ *
+ * Explicitly-coloured fields are left alone; so is a palette with no usable role.
+ *
+ * Mutates and returns `content`.
+ */
+export const applyTextContrast = (content, styles, brandPageType) => {
+    const record = content;
+    const rawContent = content;
+    Object.keys(CONTENT_TEXT_STYLE_PROPERTY_KEYS).forEach((key) => {
+        const field = record[key];
+        // Absent, already coloured — via its style OR every visible run of its paired doc (a recolour
+        // moves colour to the marks without clearing a stale `field.color`, same as textItemColour) —
+        // an exempt key (section button / copyright), or a standalone button's own label → leave it alone.
+        if (!field ||
+            field.color ||
+            everyRunColoured(rawContent[textFieldKey(key)]) ||
+            NON_SECTION_SURFACE_KEYS.has(key) ||
+            isButtonLabelField(content, key)) {
+            return;
+        }
+        bakeFieldColour(field, effectiveFieldSurface(content, styles, key, brandPageType), styles);
     });
+    // Per-item text styles (`textItems[]` — the brand-site text section) are not top-level keys, so
+    // the loop above misses them. Items stack vertically, so a new (bottom) item INHERITS the colour
+    // of the item directly ABOVE it — the copy reads as one block and a newly-added item continues
+    // the last item's colour. Only the first item (nothing above) contrasts the surface; the inherit
+    // chains down the stack, so a fresh section still resolves to one contrast colour throughout.
+    const items = content.textItems;
+    if (Array.isArray(items)) {
+        const surface = topmostSolidSurface(content, styles.colors);
+        items.forEach((item, index) => {
+            // Already coloured — via its style OR its run mark (birth authoring moves colour to the mark
+            // and clears the style). Skipping the mark case is what stops a recoloured item being
+            // re-contrasted, and keeps it usable as the colour the item below inherits.
+            if (!item.textStyle || textItemColour(item)) {
+                return;
+            }
+            const above = index > 0 ? textItemColour(items[index - 1]) : undefined;
+            if (above) {
+                item.textStyle.color = above;
+                return;
+            }
+            bakeFieldColour(item.textStyle, surface, styles);
+        });
+    }
+    if (content.type === 'social-links') {
+        const socialLinks = content;
+        const iconFillStyles = socialLinks.iconFillStyles ?? {};
+        if (isBlankColorValue(iconFillStyles.fill)) {
+            const fill = titleSurfaceContrastFill(content, styles, brandPageType);
+            if (fill) {
+                socialLinks.iconFillStyles = { ...iconFillStyles, fill };
+            }
+        }
+    }
     return content;
 };
+/**
+ * Phase 2 (ADR-0020): the surface fields a section can paint behind its text, TOP of the
+ * stack first (the closest painted layer is what the text sits on). A render-local mirror
+ * of the raised/backdrop split in `SURFACE_STACK_RANK` (`section-color-matches.ts`) — kept
+ * here so the renderer's contrast bake doesn't depend on the settings-panel module. Only
+ * the single-solid-surface fields are walked; array/overlay/tint layers are out of v1 scope.
+ * Extract to a shared leaf if a third consumer appears.
+ */
+const SURFACE_FIELDS_TOP_FIRST = [
+    'cardStyle',
+    'fillColor',
+    'backgroundStyle',
+    'backgroundColor',
+];
+/**
+ * A banner paints its `cardStyle` ONLY in the two card layouts (`isCard` in `BANNER_LAYOUTS`,
+ * `BannerSection.vue`); every other layout — including the default `centered` — renders the
+ * content directly on the band, so the transparent `backgroundStyle` lets the site background
+ * show through. The factory seeds `cardStyle` white regardless, so counting it as the surface in
+ * a non-card layout would contrast a card the banner never paints (dark title on a dark page).
+ */
+const BANNER_CARD_DISPLAY_STYLES = new Set([
+    ALIGN_CARD_CENTER_IMAGE,
+    ALIGN_CARD_LEFT_IMAGE,
+]);
+const isSurfaceFieldPainted = (content, field) => {
+    if (field === 'cardStyle' && content.type === 'banner-section') {
+        return BANNER_CARD_DISPLAY_STYLES.has(content.displayStyle ?? '');
+    }
+    return true;
+};
+/**
+ * The topmost solid surface painted behind a section's text — the highest-stacked surface
+ * field that resolves to a visible solid — or `undefined` when the section paints nothing solid
+ * (the text then sits on the page background, `applyTextContrast`'s page branch). A field the
+ * section does not actually paint in its current layout is skipped (`isSurfaceFieldPainted`).
+ * Palette refs are resolved first (via `isSolidSurface`), so a `var(--palette-N)` fill counts as
+ * the solid it resolves to.
+ */
+export const topmostSolidSurface = (content, colors = []) => {
+    const record = content;
+    for (const field of SURFACE_FIELDS_TOP_FIRST) {
+        if (!isSurfaceFieldPainted(content, field)) {
+            continue;
+        }
+        const style = record[field];
+        if (isSolidSurface(style, colors)) {
+            return style;
+        }
+    }
+    return undefined;
+};

package/lib/src/brand-page/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './style.util';
+export * from './text-role-css.util';
 export * from './color-palette.util';
 export * from './shape-color-match.util';
 export * from './shape-color-apply.util';

package/lib/src/brand-page/utils/index.js

@@ -1,4 +1,5 @@
 export * from './style.util';
+export * from './text-role-css.util';
 export * from './color-palette.util';
 export * from './shape-color-match.util';
 export * from './shape-color-apply.util';

package/lib/src/brand-page/utils/migration/migration-20.js

@@ -1,4 +1,5 @@
-import { isRteHtmlString, toRteJson, resolveHtmlParser, } from '../../../brand-page-maker/utils';
+import { toRteJson, resolveHtmlParser, } from '@shared/rte-render.util';
+import { isRteHtmlString } from '@shared/rte-shape.util';
 /**
  * BP-5787 — migrate existing inline-HTML RTE content to Tiptap JSON.
  *
@@ -40,7 +41,10 @@ const convertRteStringsToJson = (value, parser) => {
         const field = record[key];
         if (isRteHtmlString(field)) {
             try {
-                const json = toRteJson(field, parser);
+                // Pin the parse to the v20 schema this migration shipped with (pre-TextEffects). Parsing
+                // legacy HTML with the live schema would drift a released migration's output — a later
+                // schema addition (e.g. TextEffects) would bake attrs it never produced. See docs/decisions.
+                const json = toRteJson(field, parser, 20);
                 if (json)
                     record[key] = json;
             }