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

package/lib/src/brand-page/models/navigation-styles.model.js

@@ -1,7 +1,10 @@
 import { DEFAULT_FONT_FAMILY_KEY, DEFAULT_FONT_STYLE, DEFAULT_TEXT_ALIGN, DEFAULT_TEXT_DECORATION, FONT_FAMILY_CONFIGS, FONT_SIZE_BODY, FONT_WEIGHT_NORMAL, STYLE_THEME_KEYS, defaultHamburgerNavigation, NAVIGATION_DISPLAY, } from '../constants';
 import { VIEWPORTS } from './index';
-import { TEXT_STYLE_TYPES } from './index';
+import { CANONICAL_TEXT_STYLE_TYPES, } from './styles.model';
 import cloneDeep from 'lodash.clonedeep';
+// A typography default sits under the saved style, and a style's own value beats its role, so
+// only text on none of the ten roles may get one. Released migrations read the unlinked output.
+const isRoleLinked = (style) => CANONICAL_TEXT_STYLE_TYPES.includes(style?.textStyleType);
 export class NavigationMenuStyles {
     defaultButtonStyle;
     selectedButtonStyle;
@@ -75,11 +78,15 @@ class NavigationStyles {
             borderRightWidth: '0px',
             borderTopWidth: '0px',
             color: theme?.primaryColor,
-            fontSize: FONT_SIZE_BODY,
-            fontFamily: FONT_FAMILY_CONFIGS[DEFAULT_FONT_FAMILY_KEY].name,
-            textDecoration: DEFAULT_TEXT_DECORATION,
-            fontWeight: FONT_WEIGHT_NORMAL,
-            fontStyle: DEFAULT_FONT_STYLE,
+            ...(isRoleLinked(option?.defaultButtonStyle)
+                ? {}
+                : {
+                    fontSize: FONT_SIZE_BODY,
+                    fontFamily: FONT_FAMILY_CONFIGS[DEFAULT_FONT_FAMILY_KEY].name,
+                    textDecoration: DEFAULT_TEXT_DECORATION,
+                    fontWeight: FONT_WEIGHT_NORMAL,
+                    fontStyle: DEFAULT_FONT_STYLE,
+                }),
             textAlign: DEFAULT_TEXT_ALIGN,
         }, option?.defaultButtonStyle || {});
         this.selectedButtonStyle = Object.assign({}, {
@@ -95,12 +102,14 @@ class NavigationStyles {
         this.iconStyle = Object.assign({}, option?.iconStyle || {});
         this.subNavBackgroundColor = option?.subNavBackgroundColor;
         this.isLogoVisible = option?.isLogoVisible || true;
+        const { fontFamily: _hamburgerFontFamily, ...linkedHamburgerDefaults } = defaultHamburgerNavigation.defaultButtonStyle;
         this.hamburgerMenuStyle = new NavigationMenuStyles(option?.hamburgerMenuStyle || {}, {
             defaultButtonStyle: {
-                ...defaultHamburgerNavigation.defaultButtonStyle,
+                ...(isRoleLinked(option?.hamburgerMenuStyle?.defaultButtonStyle)
+                    ? linkedHamburgerDefaults
+                    : defaultHamburgerNavigation.defaultButtonStyle),
                 backgroundColor: theme?.secondaryColor,
                 color: theme?.primaryColor,
-                textStyleType: option ? undefined : TEXT_STYLE_TYPES.buttons,
                 textAlign: option?.defaultButtonStyle?.textAlign || 'left',
             },
             selectedButtonStyle: {

package/lib/src/brand-page/models/payment.model.d.ts

@@ -1,6 +1,8 @@
 import type { Content } from './content.model';
 import type { ProductModel } from './shop.model';
 import type { TextStyleDeclaration } from './styles.model';
+import type { JSONContent } from '@tiptap/vue-3';
+type RteText = string | JSONContent;
 export declare const STRIPE_ADDRESS_LIMITS: {
     readonly name: {
         readonly min: 1;
@@ -118,11 +120,11 @@ export interface RequestPaymentConfig extends PaymentConfig {
 }
 export interface RequestPaymentContent extends Content {
     type: 'request-payment';
-    description: string;
+    description: RteText;
     displayStyle: string;
     requestPaymentConfig: RequestPaymentConfig;
     successMessage: string;
-    title: string;
+    title: RteText;
     fillColor: BrandPageCssStyle;
     defaultBorderColor: BrandPageCssStyle;
     selectedBorderColor: BrandPageCssStyle;
@@ -132,6 +134,7 @@ export interface RequestPaymentContent extends Content {
     textColor?: BrandPageCssStyle;
     titleStyle?: TextStyleDeclaration;
     descriptionStyle?: TextStyleDeclaration;
+    successMessageStyle?: TextStyleDeclaration;
     itemTextStyle: TextStyleDeclaration;
     buttonTextStyle?: TextStyleDeclaration;
     backgroundStyle?: BrandPageCssStyle;
@@ -144,17 +147,18 @@ export interface ShopContentConfig extends PaymentConfig {
 }
 export interface ShopContent extends Content {
     type: 'shop-section';
-    description: string;
+    description: RteText;
     successMessage: string;
     products: ProductModel[];
     displayStyle: string;
     aspectRatio: string;
-    title: string;
+    title: RteText;
     fillColor: BrandPageCssStyle;
     defaultBorderColor: BrandPageCssStyle;
     textColor?: BrandPageCssStyle;
     titleStyle?: TextStyleDeclaration;
     descriptionStyle?: TextStyleDeclaration;
+    successMessageStyle?: TextStyleDeclaration;
     itemTextStyle: TextStyleDeclaration;
     buttonTextStyle?: TextStyleDeclaration;
     backgroundStyle: BrandPageCssStyle;
@@ -165,14 +169,15 @@ export interface SupportMeConfig extends PaymentConfig {
 }
 export interface SupportMeContent extends Content {
     type: 'support-me';
-    title: string;
-    description: string;
+    title: RteText;
+    description: RteText;
     displayStyle: string;
     successMessage: string;
     supportMeConfig: SupportMeConfig;
     titleStyle: TextStyleDeclaration;
     headingStyle: TextStyleDeclaration;
     descriptionStyle: TextStyleDeclaration;
+    successMessageStyle?: TextStyleDeclaration;
     buttonTextStyle: TextStyleDeclaration;
     itemTextStyle: TextStyleDeclaration;
     backgroundStyle?: BrandPageCssStyle;

package/lib/src/brand-page/models/styles.model.d.ts

@@ -1,25 +1,69 @@
-import type { FontFamilyKey } from '../constants';
+/**
+ * The 10 canonical global text roles (BP-5969) plus the 4 legacy roles.
+ *
+ * Legacy keys (`titles`/`headings`/`paragraphs`/`buttons`) are retained ONLY so
+ * pre-migration content keeps resolving until migration-22 converts it; they are
+ * hidden from the panel/picker (see `CANONICAL_TEXT_STYLE_TYPES`) and no new code
+ * should write them. See `0019-retire-rte-object-style-sync.md` and `global-text-style.md`.
+ */
 export declare const TEXT_STYLE_TYPES: {
+    readonly heading1: "heading1";
+    readonly heading2: "heading2";
+    readonly heading3: "heading3";
+    readonly heading4: "heading4";
+    readonly heading5: "heading5";
+    readonly heading6: "heading6";
+    readonly paragraph1: "paragraph1";
+    readonly paragraph2: "paragraph2";
+    readonly paragraph3: "paragraph3";
+    readonly button: "button";
     readonly titles: "titles";
     readonly headings: "headings";
     readonly paragraphs: "paragraphs";
     readonly buttons: "buttons";
 };
 export type TextStyleType = keyof typeof TEXT_STYLE_TYPES;
+/** The 10 roles shown in the panel/picker, in display order. */
+export declare const CANONICAL_TEXT_STYLE_TYPES: readonly ["heading1", "heading2", "heading3", "heading4", "heading5", "heading6", "paragraph1", "paragraph2", "paragraph3", "button"];
+export type CanonicalTextStyleType = (typeof CANONICAL_TEXT_STYLE_TYPES)[number];
+/** Legacy roles, retained for resolution of un-migrated content only. */
+export declare const LEGACY_TEXT_STYLE_TYPES: readonly ["titles", "headings", "paragraphs", "buttons"];
+export type LegacyTextStyleType = (typeof LEGACY_TEXT_STYLE_TYPES)[number];
+export declare const isLegacyTextStyleType: (type: string | undefined) => type is LegacyTextStyleType;
+export declare const isCanonicalTextStyleType: (type: unknown) => type is CanonicalTextStyleType;
 export declare const TEXT_STYLE_TYPES_DISPLAY_NAME_MAP: () => {
+    heading1: any;
+    heading2: any;
+    heading3: any;
+    heading4: any;
+    heading5: any;
+    heading6: any;
+    paragraph1: any;
+    paragraph2: any;
+    paragraph3: any;
+    button: any;
     titles: any;
     headings: any;
     paragraphs: any;
     buttons: any;
-    none: any;
 };
 export type TextStyleDeclaration = BrandPageCssStyle & {
     textStyleType?: TextStyleType;
     applyAutoScale?: boolean;
 };
 export type TextStyleDeclarationWithoutTextAlign = Omit<TextStyleDeclaration, 'textAlign'>;
+/**
+ * BP-5969 (ADR-0020): an RTE-paired section field's style, with **colour decoupled**. Colour
+ * is the ONE thing removed from the style object — it lives in the RTE mark now (baked
+ * contrast at birth / by migration-22), so this type has no `color` and nothing can read a
+ * stale one off an RTE field. Everything else stays: typography here is a genuine per-block
+ * OVERRIDE (a title set to a non-role font/size) that the renderer resolves against the role
+ * (`roleTypographyStyle`, `fillRteRunTypography`), and dropping it would lose that override
+ * through migration — so only `color` goes. Non-RTE per-item styles keep the full
+ * `TextStyleDeclaration`.
+ */
+export type RteTextRole = Omit<TextStyleDeclaration, 'color'>;
 export interface GlobalTextStyleDeclaration {
-    color: string | undefined;
     fontFamily: string | undefined;
     fontSize: string | undefined;
     fontStyle: string | undefined;
@@ -39,15 +83,17 @@ export declare class TextStyleOption {
 }
 export type TextStyleOptions = Record<TextStyleType, TextStyleOption>;
 /**
- * `style` (the retired site-wide default text colour) is untyped on `TextStyles`,
- * so nothing outside migrations can reach it — but it still arrives in pre-gate
- * JSON, so the constructor carries it through for `migration-21` to consume.
+ * `style` (the retired site-wide default text colour) and `textFontFamily` (the retired site
+ * text font) are untyped on `TextStyles`, so nothing outside migrations can reach them — but
+ * they still arrive in pre-gate JSON, so the constructor carries them through for `migration-21`
+ * and `migration-22` to consume. Never default `textFontFamily`: the maker store's `$patch` never
+ * deletes a key, so a default would be saved back (`0036-retire-text-font-family.md`).
  */
 export type LegacyTextStylesInput = Partial<TextStyles> & {
     style?: BrandPageCssStyle;
+    textFontFamily?: unknown;
 };
 export declare class TextStyles {
-    textFontFamily: FontFamilyKey;
     textStyleOptions: TextStyleOptions;
     static GetDefaultTextStyle(): TextStyles;
     constructor(option?: LegacyTextStylesInput);

package/lib/src/brand-page/models/styles.model.js

@@ -1,20 +1,76 @@
-import { FONT_SIZE_HEADINGS, FONT_SIZE_TITLE, LINE_HEIGHT_HEADINGS, LINE_HEIGHT_TITLE, FONT_SIZE_BODY, LINE_HEIGHT_BODY, DISPLAY_TEXT_TITLE, DISPLAY_TEXT_HEADINGS, DISPLAY_TEXT_BODY, STYLE_THEME_KEYS, FONT_FAMILY_CONFIGS, DEFAULT_FONT_FAMILY_KEY, DISPlAY_TEXT_BUTTONS, } from '../constants';
-import { commonTr, styleSettingsTr } from '@src/composables/useTranslate';
+import { FONT_SIZE_HEADINGS, FONT_SIZE_TITLE, LINE_HEIGHT_HEADINGS, LINE_HEIGHT_TITLE, FONT_SIZE_BODY, LINE_HEIGHT_BODY, DISPLAY_TEXT_TITLE, DISPLAY_TEXT_HEADINGS, DISPLAY_TEXT_BODY, STYLE_THEME_KEYS, FONT_FAMILY_CONFIGS, DEFAULT_FONT_FAMILY_KEY, DISPlAY_TEXT_BUTTONS, DISPLAY_TEXT_HEADING_1, DISPLAY_TEXT_HEADING_2, DISPLAY_TEXT_HEADING_3, DISPLAY_TEXT_HEADING_4, DISPLAY_TEXT_HEADING_5, DISPLAY_TEXT_HEADING_6, DISPLAY_TEXT_PARAGRAPH_1, DISPLAY_TEXT_PARAGRAPH_2, DISPLAY_TEXT_PARAGRAPH_3, DISPLAY_TEXT_BUTTON, TEXT_ROLE_STYLE_DEFAULTS, } from '../constants';
+import { styleSettingsTr } from '@src/composables/useTranslate';
+/**
+ * The 10 canonical global text roles (BP-5969) plus the 4 legacy roles.
+ *
+ * Legacy keys (`titles`/`headings`/`paragraphs`/`buttons`) are retained ONLY so
+ * pre-migration content keeps resolving until migration-22 converts it; they are
+ * hidden from the panel/picker (see `CANONICAL_TEXT_STYLE_TYPES`) and no new code
+ * should write them. See `0019-retire-rte-object-style-sync.md` and `global-text-style.md`.
+ */
 export const TEXT_STYLE_TYPES = {
+    heading1: 'heading1',
+    heading2: 'heading2',
+    heading3: 'heading3',
+    heading4: 'heading4',
+    heading5: 'heading5',
+    heading6: 'heading6',
+    paragraph1: 'paragraph1',
+    paragraph2: 'paragraph2',
+    paragraph3: 'paragraph3',
+    button: 'button',
+    // --- legacy (resolution-only, hidden, do not write) ---
     titles: 'titles',
     headings: 'headings',
     paragraphs: 'paragraphs',
     buttons: 'buttons',
 };
+/** The 10 roles shown in the panel/picker, in display order. */
+export const CANONICAL_TEXT_STYLE_TYPES = [
+    'heading1',
+    'heading2',
+    'heading3',
+    'heading4',
+    'heading5',
+    'heading6',
+    'paragraph1',
+    'paragraph2',
+    'paragraph3',
+    'button',
+];
+/** Legacy roles, retained for resolution of un-migrated content only. */
+export const LEGACY_TEXT_STYLE_TYPES = [
+    'titles',
+    'headings',
+    'paragraphs',
+    'buttons',
+];
+export const isLegacyTextStyleType = (type) => LEGACY_TEXT_STYLE_TYPES.includes(type ?? '');
+// Models-level so both the render path (`text-role-css.util.ts`) and the migration path
+// (`text-role-reconnect.util.ts`, which re-exports this) share one guard, rather than a render
+// component reaching into the migration-side file for it.
+export const isCanonicalTextStyleType = (type) => CANONICAL_TEXT_STYLE_TYPES.includes(type);
+const ALL_TEXT_STYLE_TYPES = [
+    ...CANONICAL_TEXT_STYLE_TYPES,
+    ...LEGACY_TEXT_STYLE_TYPES,
+];
 export const TEXT_STYLE_TYPES_DISPLAY_NAME_MAP = () => ({
+    heading1: styleSettingsTr('heading1'),
+    heading2: styleSettingsTr('heading2'),
+    heading3: styleSettingsTr('heading3'),
+    heading4: styleSettingsTr('heading4'),
+    heading5: styleSettingsTr('heading5'),
+    heading6: styleSettingsTr('heading6'),
+    paragraph1: styleSettingsTr('paragraph1'),
+    paragraph2: styleSettingsTr('paragraph2'),
+    paragraph3: styleSettingsTr('paragraph3'),
+    button: styleSettingsTr('button'),
     titles: styleSettingsTr('titles'),
     headings: styleSettingsTr('headings'),
     paragraphs: styleSettingsTr('paragraphs'),
     buttons: styleSettingsTr('buttons'),
-    none: commonTr('none'),
 });
 export const emptyGlobalTextStyleDeclaration = Object.freeze({
-    color: undefined,
     fontFamily: undefined,
     fontSize: undefined,
     fontStyle: undefined,
@@ -36,9 +92,10 @@ export class TextStyleOption {
         this.isModified = options.isModified || false;
     }
 }
-// No `color` here on purpose: these run pre-gate and back-fill options missing
-// from ancient metadata, so a colour minted here would pre-empt migration-21's
-// copy of the model's own root colour.
+// No `color` on defaults, on purpose: these run pre-gate and back-fill options
+// missing from ancient metadata, so a colour minted here would pre-empt
+// migration-21's copy of the model's own root colour. (BP-5969: the same holds
+// for the 10 new roles — colour comes from the root cascade / migration.)
 const createDefaultTitlesTextStyleOption = () => new TextStyleOption(TEXT_STYLE_TYPES.titles, DISPLAY_TEXT_TITLE, {
     style: {
         ...emptyGlobalTextStyleDeclaration,
@@ -71,37 +128,68 @@ const createDefaultButtonTextStyleOption = () => new TextStyleOption(TEXT_STYLE_
         fontFamily: FONT_FAMILY_CONFIGS[DEFAULT_FONT_FAMILY_KEY].name,
     },
 });
-const createDefaultTextStyleOptions = () => ({
-    [TEXT_STYLE_TYPES.titles]: createDefaultTitlesTextStyleOption(),
-    [TEXT_STYLE_TYPES.headings]: createDefaultHeadingsTextStyleOption(),
-    [TEXT_STYLE_TYPES.paragraphs]: createDefaultParagraphTextStyleOption(),
-    [TEXT_STYLE_TYPES.buttons]: createDefaultButtonTextStyleOption(),
-});
+const CANONICAL_DISPLAY_NAMES = {
+    heading1: DISPLAY_TEXT_HEADING_1,
+    heading2: DISPLAY_TEXT_HEADING_2,
+    heading3: DISPLAY_TEXT_HEADING_3,
+    heading4: DISPLAY_TEXT_HEADING_4,
+    heading5: DISPLAY_TEXT_HEADING_5,
+    heading6: DISPLAY_TEXT_HEADING_6,
+    paragraph1: DISPLAY_TEXT_PARAGRAPH_1,
+    paragraph2: DISPLAY_TEXT_PARAGRAPH_2,
+    paragraph3: DISPLAY_TEXT_PARAGRAPH_3,
+    button: DISPLAY_TEXT_BUTTON,
+};
+const createCanonicalTextStyleOption = (type) => {
+    const defaults = TEXT_ROLE_STYLE_DEFAULTS[type];
+    return new TextStyleOption(type, CANONICAL_DISPLAY_NAMES[type], {
+        style: {
+            ...emptyGlobalTextStyleDeclaration,
+            fontSize: defaults.fontSize,
+            fontWeight: defaults.fontWeight,
+            lineHeight: defaults.lineHeight,
+            fontFamily: FONT_FAMILY_CONFIGS[DEFAULT_FONT_FAMILY_KEY].name,
+        },
+    });
+};
+const LEGACY_FACTORIES = {
+    titles: createDefaultTitlesTextStyleOption,
+    headings: createDefaultHeadingsTextStyleOption,
+    paragraphs: createDefaultParagraphTextStyleOption,
+    buttons: createDefaultButtonTextStyleOption,
+};
+const createDefaultTextStyleOption = (type) => isLegacyTextStyleType(type)
+    ? LEGACY_FACTORIES[type]()
+    : createCanonicalTextStyleOption(type);
+const createDefaultTextStyleOptions = () => Object.fromEntries(ALL_TEXT_STYLE_TYPES.map((type) => [
+    type,
+    createDefaultTextStyleOption(type),
+]));
 export class TextStyles {
-    textFontFamily;
     textStyleOptions;
     static GetDefaultTextStyle() {
         return new TextStyles({
             style: { color: STYLE_THEME_KEYS.LogoTextColor },
-            textFontFamily: DEFAULT_FONT_FAMILY_KEY,
         });
     }
     constructor(option = {}) {
         if (option.style !== undefined) {
             this['style'] = option.style;
         }
-        this.textFontFamily = option.textFontFamily || DEFAULT_FONT_FAMILY_KEY;
-        this.textStyleOptions = option.textStyleOptions
-            ? {
-                [TEXT_STYLE_TYPES.titles]: new TextStyleOption(TEXT_STYLE_TYPES.titles, styleSettingsTr('titles'), option.textStyleOptions.titles ||
-                    createDefaultTitlesTextStyleOption()),
-                [TEXT_STYLE_TYPES.headings]: new TextStyleOption(TEXT_STYLE_TYPES.headings, styleSettingsTr('headings'), option.textStyleOptions.headings ||
-                    createDefaultHeadingsTextStyleOption()),
-                [TEXT_STYLE_TYPES.paragraphs]: new TextStyleOption(TEXT_STYLE_TYPES.paragraphs, styleSettingsTr('paragraphs'), option.textStyleOptions.paragraphs ||
-                    createDefaultParagraphTextStyleOption()),
-                [TEXT_STYLE_TYPES.buttons]: new TextStyleOption(TEXT_STYLE_TYPES.buttons, styleSettingsTr('buttons'), option.textStyleOptions.buttons ||
-                    createDefaultButtonTextStyleOption()),
-            }
+        if (option.textFontFamily !== undefined) {
+            this['textFontFamily'] =
+                option.textFontFamily;
+        }
+        const loaded = option.textStyleOptions;
+        // Data-driven build over all 14 roles: use the persisted option where present,
+        // else the role's default. Existing sites (4 legacy roles only) thus keep their
+        // stored definitions and gain the 10 new tiers at their defaults; new sites get
+        // every role's default. Titles are re-derived from i18n (`styleSettingsTr`).
+        this.textStyleOptions = loaded
+            ? Object.fromEntries(ALL_TEXT_STYLE_TYPES.map((type) => [
+                type,
+                new TextStyleOption(type, styleSettingsTr(type), loaded[type] || createDefaultTextStyleOption(type)),
+            ]))
             : createDefaultTextStyleOptions();
     }
 }

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

@@ -206,37 +206,57 @@ export interface NeutralPalette {
  */
 export declare const generateNeutralPalette: (primary?: string, secondary?: string) => NeutralPalette;
 /**
- * The contrast a colour-strategy copy colour must clear against the layer it sits on, or
- * the strategy falls back to a neutral.
+ * The minimum contrast a BRAND text colour must clear against the surface it sits on for the
+ * birth-time bake to use it; below this the bake falls back (to the other brand role, then a
+ * neutral for the page). One colour covers *all* copy on a surface, so no threshold guarantees
+ * every size — this is a floor for large brand copy.
  *
- * **WCAG AA for LARGE text (3:1), not 4.5:1, deliberately.** One colour covers *all* copy
- * on a layer, so no threshold is a guarantee at every size; 3:1 keeps brand colours that
- * are still legible (a mid-blue primary on the dark neutral is 3.77:1, which 4.5 would
- * throw away for a near-white neutral) while catching the broken end (~1.1:1, invisible
- * text). Raising it to 4.5 is a one-line change.
+ * **2:1 — deliberately BELOW WCAG AA large-text (3:1).** The brand's own logo-text colour is the
+ * site identity and should lead its headings even when it's a bright mid-tone that lands ~2.3:1
+ * on white (a large bold heading still reads there — the BP-5969 call, ADR-0020). 2:1 keeps that
+ * while still rejecting the genuinely invisible end (~1:1, e.g. a near-white role on white). A
+ * brand-identity-over-strict-contrast trade; raising it back toward 3 is a one-line change.
  *
- * > NOTE: **dormant** — its only caller was the retired `light`/`dark` `contrast`
- * > resolver (BP-5886, ADR 0017). `bestContrastBrandRole`'s remaining callers use the
- * > default `minRatio` of 0. Retire alongside the other theme-pair leftovers.
+ * Live consumer: `viableBrandRole` (`container-text-color.util.ts`), the contrast bake's floor.
  */
-export declare const STRATEGY_COPY_MIN_CONTRAST = 3;
+export declare const STRATEGY_COPY_MIN_CONTRAST = 2;
 /**
- * The brand role (`palette-0` / `palette-1`) whose colour reads best against `against` —
- * WCAG 2.1 contrast ratio. `undefined` when neither role holds a usable solid colour,
- * when `against` itself is not one, or when no role clears `minRatio`.
+ * The palette role from `candidateIds` whose colour reads best against `against` — WCAG 2.1
+ * contrast ratio. `undefined` when `against` is not a solid, no candidate holds a usable solid
+ * colour, or none clears `minRatio`. Candidates are ranked in the order given, so an exact tie
+ * resolves to the earlier id.
  *
- * The ratio, rather than a lightness comparison, answers the degenerate palettes with no
- * second rule: two dark brand colours against the dark neutral yield the less dark one.
- * Alpha is ignored (`chroma.contrast` composites nothing).
+ * The ratio, rather than a lightness comparison, answers the degenerate palettes with no second
+ * rule: two dark candidates against the dark neutral yield the less dark one. Alpha is ignored
+ * (`chroma.contrast` composites nothing).
  *
- * **`minRatio` is the legibility floor, and without it this ranks without judging** — it
- * returns the *best available* role even when unreadable (a mono dark logo puts near-black
- * copy on the dark neutral at 1.12:1). `undefined` then routes the caller to its neutral
- * fallback, which is right because the neutrals are *brand-hue tinted*, so the hue
- * survives; a lightness-adjusted brand colour could not be a palette **role**, so it would
- * be a literal and stop following palette edits.
+ * **`minRatio` is the legibility floor, and without it this ranks without judging** — it returns
+ * the *best available* role even when unreadable. `undefined` then routes the caller to its own
+ * fallback.
+ */
+export declare const bestContrastRole: (against: string, colors: ColorItem[] | undefined, candidateIds: string[], minRatio?: number) => string | undefined;
+/**
+ * The BRAND role (`palette-0` / `palette-1`) that reads best against `against`; primary wins
+ * ties. The neutrals are excluded on purpose — a section title on a coloured surface takes a
+ * brand accent. See `bestContrastRole` for the ranking and the `minRatio` floor (without it, an
+ * `undefined` return routes the caller to its neutral fallback, which is right because the
+ * neutrals are brand-hue tinted, so the hue survives).
  */
 export declare const bestContrastBrandRole: (against: string, colors?: ColorItem[], minRatio?: number) => string | undefined;
+/**
+ * The NEUTRAL role (`palette-2` light / `palette-3` dark) that reads best against `against` — the
+ * readable, brand-hue-tinted text colour for copy on a plain surface (the page background),
+ * replacing the retired base coat. Light role wins ties.
+ */
+export declare const bestContrastNeutralRole: (against: string, colors?: ColorItem[]) => string | undefined;
+/**
+ * The FIRST role in `orderedIds` whose colour clears `minRatio` against `against` — a PRIORITY
+ * pick, not a best-contrast pick: an earlier id wins even when a later one contrasts more. Honours
+ * a brand hierarchy (e.g. logo-text before logo-background) while still guaranteeing legibility via
+ * the floor. `undefined` when `against` is not a solid or no listed role clears `minRatio`, so the
+ * caller can route on to its own fallback.
+ */
+export declare const firstViableContrastRole: (against: string, colors: ColorItem[] | undefined, orderedIds: string[], minRatio: number) => string | undefined;
 export declare const DEFAULT_PRIMARY = "#2b6cff";
 export declare const DEFAULT_SECONDARY = "#0a2540";
 /** The four default palette-role entries (used when nothing can be derived). */

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

@@ -8,6 +8,9 @@ import { isColorLinearGradient } from '@src/utils/helpers';
  * colour value, mint a deterministic palette id for it, and translate between an id
  * and its `var(--id)` reference. Side-effect and framework free so migration, maker
  * and renderer can all share them.
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: its colour bake uses `isBlankColorValue`. Pin the v22
+ * interpretation before changing that helper after the migration releases.
  */
 const CUSTOM_ID_PREFIX = 'palette-custom-';
 /**
@@ -500,37 +503,35 @@ export const generateNeutralPalette = (primary, secondary) => ({
     dark: utilityNeutral(secondary),
 });
 /**
- * The contrast a colour-strategy copy colour must clear against the layer it sits on, or
- * the strategy falls back to a neutral.
+ * The minimum contrast a BRAND text colour must clear against the surface it sits on for the
+ * birth-time bake to use it; below this the bake falls back (to the other brand role, then a
+ * neutral for the page). One colour covers *all* copy on a surface, so no threshold guarantees
+ * every size — this is a floor for large brand copy.
  *
- * **WCAG AA for LARGE text (3:1), not 4.5:1, deliberately.** One colour covers *all* copy
- * on a layer, so no threshold is a guarantee at every size; 3:1 keeps brand colours that
- * are still legible (a mid-blue primary on the dark neutral is 3.77:1, which 4.5 would
- * throw away for a near-white neutral) while catching the broken end (~1.1:1, invisible
- * text). Raising it to 4.5 is a one-line change.
+ * **2:1 — deliberately BELOW WCAG AA large-text (3:1).** The brand's own logo-text colour is the
+ * site identity and should lead its headings even when it's a bright mid-tone that lands ~2.3:1
+ * on white (a large bold heading still reads there — the BP-5969 call, ADR-0020). 2:1 keeps that
+ * while still rejecting the genuinely invisible end (~1:1, e.g. a near-white role on white). A
+ * brand-identity-over-strict-contrast trade; raising it back toward 3 is a one-line change.
  *
- * > NOTE: **dormant** — its only caller was the retired `light`/`dark` `contrast`
- * > resolver (BP-5886, ADR 0017). `bestContrastBrandRole`'s remaining callers use the
- * > default `minRatio` of 0. Retire alongside the other theme-pair leftovers.
+ * Live consumer: `viableBrandRole` (`container-text-color.util.ts`), the contrast bake's floor.
  */
-export const STRATEGY_COPY_MIN_CONTRAST = 3;
+export const STRATEGY_COPY_MIN_CONTRAST = 2;
 /**
- * The brand role (`palette-0` / `palette-1`) whose colour reads best against `against` —
- * WCAG 2.1 contrast ratio. `undefined` when neither role holds a usable solid colour,
- * when `against` itself is not one, or when no role clears `minRatio`.
+ * The palette role from `candidateIds` whose colour reads best against `against` — WCAG 2.1
+ * contrast ratio. `undefined` when `against` is not a solid, no candidate holds a usable solid
+ * colour, or none clears `minRatio`. Candidates are ranked in the order given, so an exact tie
+ * resolves to the earlier id.
  *
- * The ratio, rather than a lightness comparison, answers the degenerate palettes with no
- * second rule: two dark brand colours against the dark neutral yield the less dark one.
- * Alpha is ignored (`chroma.contrast` composites nothing).
+ * The ratio, rather than a lightness comparison, answers the degenerate palettes with no second
+ * rule: two dark candidates against the dark neutral yield the less dark one. Alpha is ignored
+ * (`chroma.contrast` composites nothing).
  *
- * **`minRatio` is the legibility floor, and without it this ranks without judging** — it
- * returns the *best available* role even when unreadable (a mono dark logo puts near-black
- * copy on the dark neutral at 1.12:1). `undefined` then routes the caller to its neutral
- * fallback, which is right because the neutrals are *brand-hue tinted*, so the hue
- * survives; a lightness-adjusted brand colour could not be a palette **role**, so it would
- * be a literal and stop following palette edits.
- */
-export const bestContrastBrandRole = (against, colors = [], minRatio = 0) => {
+ * **`minRatio` is the legibility floor, and without it this ranks without judging** — it returns
+ * the *best available* role even when unreadable. `undefined` then routes the caller to its own
+ * fallback.
+ */
+export const bestContrastRole = (against, colors = [], candidateIds, minRatio = 0) => {
     // `canonicalSolidHex` rather than `chroma.valid`: a gradient, an unresolved `var()`
     // and `transparent` (which chroma WOULD accept, as black) are all excluded.
     const baseHex = canonicalSolidHex(against);
@@ -538,8 +539,7 @@ export const bestContrastBrandRole = (against, colors = [], minRatio = 0) => {
         return undefined;
     }
     const byId = new Map(colors.map((c) => [c.id, c.value]));
-    // Primary first, so an exact tie resolves to it deterministically (`>` below).
-    const candidates = [PALETTE_COLOR_IDS.primary, PALETTE_COLOR_IDS.secondary]
+    const candidates = candidateIds
         .map((id) => ({
         id,
         hex: canonicalSolidHex(byId.get(id) ?? ''),
@@ -551,6 +551,44 @@ export const bestContrastBrandRole = (against, colors = [], minRatio = 0) => {
     }, undefined);
     return best && best.ratio >= minRatio ? best.id : undefined;
 };
+/**
+ * The BRAND role (`palette-0` / `palette-1`) that reads best against `against`; primary wins
+ * ties. The neutrals are excluded on purpose — a section title on a coloured surface takes a
+ * brand accent. See `bestContrastRole` for the ranking and the `minRatio` floor (without it, an
+ * `undefined` return routes the caller to its neutral fallback, which is right because the
+ * neutrals are brand-hue tinted, so the hue survives).
+ */
+export const bestContrastBrandRole = (against, colors = [], minRatio = 0) => bestContrastRole(against, colors, [PALETTE_COLOR_IDS.primary, PALETTE_COLOR_IDS.secondary], minRatio);
+/**
+ * The NEUTRAL role (`palette-2` light / `palette-3` dark) that reads best against `against` — the
+ * readable, brand-hue-tinted text colour for copy on a plain surface (the page background),
+ * replacing the retired base coat. Light role wins ties.
+ */
+export const bestContrastNeutralRole = (against, colors = []) => bestContrastRole(against, colors, [
+    PALETTE_COLOR_IDS.neutralLight,
+    PALETTE_COLOR_IDS.neutralDark,
+]);
+/**
+ * The FIRST role in `orderedIds` whose colour clears `minRatio` against `against` — a PRIORITY
+ * pick, not a best-contrast pick: an earlier id wins even when a later one contrasts more. Honours
+ * a brand hierarchy (e.g. logo-text before logo-background) while still guaranteeing legibility via
+ * the floor. `undefined` when `against` is not a solid or no listed role clears `minRatio`, so the
+ * caller can route on to its own fallback.
+ */
+export const firstViableContrastRole = (against, colors = [], orderedIds, minRatio) => {
+    const baseHex = canonicalSolidHex(against);
+    if (!baseHex) {
+        return undefined;
+    }
+    const byId = new Map(colors.map((c) => [c.id, c.value]));
+    for (const id of orderedIds) {
+        const hex = canonicalSolidHex(byId.get(id) ?? '');
+        if (hex && chroma.contrast(baseHex, hex) >= minRatio) {
+            return id;
+        }
+    }
+    return undefined;
+};
 // The fallback palette. The neutrals are generated from the two blues (one code path) so
 // it stays self-consistent with real logos.
 export const DEFAULT_PRIMARY = '#2b6cff';

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

@@ -46,15 +46,19 @@ export declare const mutedTextForBackground: (bgColor: string | undefined, { tar
 }) => string | undefined;
 export declare const backgroundColorFromStyle: (style: BrandPageCssStyle | undefined) => string | 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 declare const getNavThemeByTextStyle: (textStyle: BrandPageCssStyle, colors?: ColorItem[]) => Theme;
+export declare const getNavThemeByTextStyle: (headerBackgroundColor: string | undefined, colors?: ColorItem[], pageBackgroundColor?: string) => Theme;
 export declare const getNewColorBasedOnTargetColorTheme: (originalColor: string, targetColor: string) => ColorInstance | undefined;