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

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

@@ -2,10 +2,12 @@ import type { Content, ColorItem } from '../models';
 import { BRAND_PAGE_TYPES, PageStyles } from '../models';
 import {
   containerTextColorDefaults,
-  applyCardTextContrast,
+  applyTextContrast,
   rteFrameFallbackColour,
+  buttonLabelColorDefault,
 } from './container-text-color.util';
 import { DEFAULT_CARD_SURFACE_REFERENCE } from './color-palette.util';
+import { ALIGN_CENTERED, ALIGN_CARD_CENTER_IMAGE } from '../constants';
 
 const BUTTON_FILL = 'var(--palette-1)';
 const BUTTON_TEXT = 'var(--palette-2)';
@@ -162,6 +164,7 @@ describe('containerTextColorDefaults', () => {
     ).toEqual({
       titleStyle: BUTTON_TEXT,
       descriptionStyle: BUTTON_TEXT,
+      successMessageStyle: BUTTON_TEXT,
       itemTextStyle: BUTTON_TEXT,
     });
   });
@@ -186,7 +189,7 @@ describe('containerTextColorDefaults', () => {
 
   test('request-payment with a custom option fill: item text defers to the bake, not the render default', () => {
     // A custom option fill that is not the button fill is handled by the creation-time bake
-    // (applyCardTextContrast), so the render rung supplies nothing.
+    // (applyTextContrast), so the render rung supplies nothing.
     const content = {
       id: 'rp',
       type: 'request-payment',
@@ -406,7 +409,7 @@ describe('rteFrameFallbackColour', () => {
   });
 });
 
-describe('applyCardTextContrast — card-text colour bake', () => {
+describe('applyTextContrast — birth-time colour bake (container blocks)', () => {
   const NEUTRAL_LIGHT: ColorItem[] = [
     { id: 'palette-0', value: '#101010', type: 'palette' }, // dark brand role
     { id: 'palette-1', value: '#ededed', type: 'palette' }, // light brand role
@@ -431,33 +434,30 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    const result = applyCardTextContrast(content, styles);
+    const result = applyTextContrast(content, styles);
 
     // palette-0 (dark) reads on the light card; palette-1 (light) does not.
     expect(titleColour(result)).toBe('var(--palette-0)');
     expect(result).toBe(content); // mutated in place
   });
 
-  test('takes the better brand role even when the current colour already reads', () => {
-    // The reported case: the linked colour is readable but not the best — the OTHER brand
-    // colour contrasts more, so we use that (no "only if failing" gate).
+  test('keeps the logo-text role on a card when it clears the floor, even though palette-1 contrasts more', () => {
+    // BP-5969 supersedes the earlier "always take the higher-contrast brand" rule: the site
+    // identity (logo-text, palette-0) leads on a card too, as long as it stays legible.
     const content = newMailingList();
     const styles = stylesWith(
       { backgroundColor: '#767676', color: '#ffffff' },
       [
-        { id: 'palette-0', value: '#767676', type: 'palette' }, // ~4:1 on the light card — reads
-        { id: 'palette-1', value: '#1a1a1a', type: 'palette' }, // ~16:1 — much better
+        { id: 'palette-0', value: '#767676', type: 'palette' }, // ~4:1 on the light card — clears the floor
+        { id: 'palette-1', value: '#1a1a1a', type: 'palette' }, // ~16:1 — contrasts more, must NOT win
         { id: 'palette-2', value: '#f5f5f5', type: 'palette' }, // the card
       ],
     );
 
-    // The title already links a readable brand colour…
-    styles.textStyles.textStyleOptions.titles.style.color = 'var(--palette-0)';
-
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
-    // …but the other brand role contrasts more, so it wins.
-    expect(titleColour(content)).toBe('var(--palette-1)');
+    // logo-text clears the floor on the card → it leads, even though palette-1 contrasts more.
+    expect(titleColour(content)).toBe('var(--palette-0)');
   });
 
   test('bakes card fields against the card, but leaves the button-bound item text', () => {
@@ -477,7 +477,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     const fields = content as unknown as Record<string, { color?: string }>;
 
@@ -502,7 +502,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     const fields = content as unknown as Record<string, { color?: string }>;
 
@@ -520,7 +520,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     expect(titleColour(content)).toBe('var(--palette-1)');
   });
@@ -537,12 +537,15 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     expect(titleColour(content)).toBeUndefined();
   });
 
-  test('is a no-op for a content type that is not container-bound', () => {
+  test('a non-container type gets no container button-text default (takes the page neutral)', () => {
+    // The container button-text pairing (var(--palette-2) here) must not apply to a non-container
+    // type. With no solid section surface, its plain field falls to the page background instead —
+    // unresolvable in this fixture, so the neutral-dark stand-in — never the button-text colour.
     const content = {
       id: 't',
       type: 'text',
@@ -553,9 +556,10 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       NEUTRAL_LIGHT,
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
-    expect(titleColour(content)).toBeUndefined();
+    expect(titleColour(content)).not.toBe('var(--palette-2)');
+    expect(titleColour(content)).toBe('var(--palette-3)');
   });
 
   test('picks the higher-contrast brand role even in a low-contrast palette', () => {
@@ -573,7 +577,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       ],
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     expect(titleColour(content)).toBe('var(--palette-0)');
   });
@@ -595,7 +599,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       ],
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     const baked = titleColour(content);
 
@@ -619,7 +623,7 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       [{ id: 'palette-2', value: '#f5f5f5', type: 'palette' }],
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     expect(titleColour(content)).toBeUndefined();
   });
@@ -639,8 +643,650 @@ describe('applyCardTextContrast — card-text colour bake', () => {
       ],
     );
 
-    applyCardTextContrast(content, styles);
+    applyTextContrast(content, styles);
 
     expect(titleColour(content)).toBe('var(--palette-1)');
   });
 });
+
+describe('applyTextContrast — non-container sections (per-field)', () => {
+  // A brand palette split hard so the best-contrast pick is unambiguous.
+  const PALETTE: ColorItem[] = [
+    { id: 'palette-0', value: '#000000', type: 'palette' }, // dark brand
+    { id: 'palette-1', value: '#ffffff', type: 'palette' }, // light brand
+  ];
+
+  const stylesWithColors = (colors: ColorItem[] = PALETTE): PageStyles => {
+    const styles = new PageStyles();
+
+    styles.colors = colors;
+
+    return styles;
+  };
+
+  const colourOf = (content: Content, key: string): string | undefined =>
+    (content as unknown as Record<string, { color?: string }>)[key]?.color;
+
+  test('bakes a contrast colour into a section text field on a solid band', () => {
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'var(--palette-0)' }, // dark band
+      textStyle: { textStyleType: 'paragraph1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-1)'); // light on dark
+  });
+
+  test('each field contrasts its own surface: the title sits on the card, not the band', () => {
+    const content = {
+      id: 's',
+      type: 'shapes-section',
+      cardStyle: { backgroundColor: 'var(--palette-1)' }, // light card (topmost)
+      backgroundColor: { backgroundColor: 'var(--palette-0)' }, // dark band
+      titleStyle: { textStyleType: 'heading1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    // Sits on the card (light) → the dark brand role.
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-0)');
+  });
+
+  // Distinct brand vs neutral so "brand preferred, neutral only on breach" is provable.
+  const BRAND_AND_NEUTRALS: ColorItem[] = [
+    { id: 'palette-0', value: '#2f9e44', type: 'palette' }, // green brand (logo text)
+    { id: 'palette-1', value: '#0a2540', type: 'palette' }, // navy brand (logo bg)
+    { id: 'palette-2', value: '#f5f5f5', type: 'palette' }, // neutral-light
+    { id: 'palette-3', value: '#1a1a1a', type: 'palette' }, // neutral-dark
+  ];
+
+  const pageText = () =>
+    ({
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' }, // sits on the page
+      textStyle: { textStyleType: 'paragraph1' },
+    }) as unknown as Content;
+
+  test('uses the logo-text role (palette-0) on a dark page when it clears the floor', () => {
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // dark navy page
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    // the logo-text (green) brand role clears the floor on navy → the site identity colour wins
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-0)');
+  });
+
+  test('keeps the logo-text role on a light page even when palette-1 contrasts more', () => {
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: '#ffffff' }; // light page
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    // green (palette-0) clears the floor on white; navy (palette-1) contrasts more but must NOT
+    // win — logo-text leads by hierarchy, not by best contrast.
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-0)');
+  });
+
+  test('keeps a bright logo-text green on white (2.3:1 — below WCAG AA, above the 2:1 floor)', () => {
+    // The reported case: the brand's own logo-text green (#7abd2d) reads 2.3:1 on white — legible
+    // for a large heading and the chosen identity colour, so it must lead. It clears the 2:1 floor
+    // but not the old 3:1 one; the floor was lowered (BP-5969) precisely so brand identity wins here
+    // rather than deferring to the higher-contrast navy.
+    const styles = stylesWithColors([
+      { id: 'palette-0', value: '#7abd2d', type: 'palette' }, // logo-text green — 2.3:1 on white
+      { id: 'palette-1', value: '#130e34', type: 'palette' }, // logo-bg navy — 18:1, must NOT win
+      { id: 'palette-2', value: '#455538', type: 'palette' },
+      { id: 'palette-3', value: '#ecedff', type: 'palette' },
+    ]);
+
+    styles.backgroundStyles.style = { background: '#ffffff' };
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-0)');
+  });
+
+  test('drops to palette-1 only when the logo-text role breaches the floor', () => {
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    // A green-ish page: the green logo-text role is illegible on it, but navy still clears.
+    styles.backgroundStyles.style = { background: '#5aa02e' };
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-1)');
+  });
+
+  test('falls back to a neutral when neither brand role clears the contrast floor', () => {
+    // Mid-grey page with two mid-grey brand roles: neither reaches the minimum viable contrast,
+    // so legibility wins over identity and a neutral is used.
+    const styles = stylesWithColors([
+      { id: 'palette-0', value: '#8a8a8a', type: 'palette' }, // brand, low contrast on grey
+      { id: 'palette-1', value: '#6e6e6e', type: 'palette' }, // brand, low contrast on grey
+      { id: 'palette-2', value: '#ffffff', type: 'palette' }, // neutral-light
+      { id: 'palette-3', value: '#000000', type: 'palette' }, // neutral-dark
+    ]);
+
+    styles.backgroundStyles.style = { background: '#808080' }; // mid-grey page
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-3)'); // the neutral that contrasts
+  });
+
+  test('falls back to the dark neutral when the page background is not a resolvable solid', () => {
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = {
+      background: 'linear-gradient(#fff, #000)',
+    }; // image/gradient
+
+    const content = pageText();
+
+    applyTextContrast(content, styles);
+
+    expect(colourOf(content, 'textStyle')).toBe('var(--palette-3)');
+  });
+
+  test('a centered banner contrasts the site background, not its unpainted white card', () => {
+    // Regression: the banner factory seeds cardStyle white, but the centered layout never paints
+    // it — the title sits on the (transparent) band → the site background. Contrast must target
+    // the site bg, or a dark title lands on a dark page (invisible).
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // dark navy site bg
+
+    const content = {
+      id: 'b',
+      type: 'banner-section',
+      displayStyle: ALIGN_CENTERED,
+      cardStyle: { backgroundColor: 'rgb(255,255,255)' }, // white default, NOT painted here
+      backgroundStyle: {},
+      titleStyle: { textStyleType: 'heading2' },
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    // dark site bg → the green brand role (visible), not a dark colour for the phantom white card
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-0)');
+  });
+
+  test('a card-layout banner still contrasts its painted card', () => {
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // dark navy site bg
+
+    const content = {
+      id: 'b',
+      type: 'banner-section',
+      displayStyle: ALIGN_CARD_CENTER_IMAGE,
+      cardStyle: { backgroundColor: 'rgb(255,255,255)' }, // white card, painted in this layout
+      backgroundStyle: {},
+      titleStyle: { textStyleType: 'heading2' },
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    // white card → the logo-text brand role (green) leads via the card path: green clears the floor
+    // on white (~3.4:1), so it wins even though navy contrasts more.
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-0)');
+  });
+
+  test('brandSite contact-form still bakes: cascades from the carved-out container surface to its card', () => {
+    // Regression: containerSurfaceForContent returns undefined for a brandSite contact-form
+    // (the render-default carve-out), so the field used to fall through and stay uncoloured.
+    // The cascade now routes it to the section's own painted card.
+    const styles = stylesWithColors([
+      { id: 'palette-0', value: '#7abd2d', type: 'palette' }, // bright logo-text green — 2.3:1 on white
+      { id: 'palette-1', value: '#0a2540', type: 'palette' }, // navy — higher contrast on white
+      { id: 'palette-2', value: '#ffffff', type: 'palette' },
+      { id: 'palette-3', value: '#000000', type: 'palette' },
+    ]);
+
+    const content = {
+      id: 'cf',
+      type: 'contact-form',
+      cardStyle: { backgroundColor: '#ffffff' }, // the painted white card
+      titleStyle: { textStyleType: 'heading2' },
+    } as unknown as Content;
+
+    applyTextContrast(content, styles, BRAND_PAGE_TYPES.brandSite);
+
+    // The cascade routes the field to the card, and the logo-text green clears the 2:1 floor on the
+    // white card → it leads (palette-0), even though navy contrasts more. The point is the field is
+    // baked from the carved-out container's card surface at all, not left uncoloured.
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-0)');
+  });
+
+  test('bakes every textItems[] entry (the brand-site text section) against the page', () => {
+    // Regression: textItems is not a top-level style key, so it was skipped — the brand-site text
+    // section rendered its items uncoloured (browser-default black on a dark page).
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // dark navy page
+
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' },
+      textItems: [
+        { id: 'a', textStyle: { textStyleType: 'paragraph1' } },
+        { id: 'b', textStyle: { textStyleType: 'paragraph1' } },
+      ],
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    const items = (
+      content as unknown as { textItems: { textStyle: { color?: string } }[] }
+    ).textItems;
+
+    expect(items[0].textStyle.color).toBe('var(--palette-0)'); // logo-text green on the dark page
+    expect(items[1].textStyle.color).toBe('var(--palette-0)');
+  });
+
+  test('a new textItems entry inherits the item above it instead of re-contrasting', () => {
+    // The item above is recoloured (palette-3); a new uncoloured item must MATCH it, not fall to
+    // the page-contrast default (palette-0), so the section stays one colour.
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // dark page → contrast = green
+
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' },
+      textItems: [
+        {
+          id: 'a',
+          textStyle: { textStyleType: 'paragraph1', color: 'var(--palette-3)' },
+        },
+        { id: 'b', textStyle: { textStyleType: 'paragraph1' } }, // new, uncoloured
+      ],
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    const items = (
+      content as unknown as { textItems: { textStyle: { color?: string } }[] }
+    ).textItems;
+
+    expect(items[0].textStyle.color).toBe('var(--palette-3)'); // untouched
+    expect(items[1].textStyle.color).toBe('var(--palette-3)'); // inherited, NOT the green contrast
+  });
+
+  test('a new item follows the item directly above (the last), not the first', () => {
+    // Stacked items: first recoloured, second recoloured differently. A third (new) item takes the
+    // SECOND item's colour — the one above it in the stack — not the first, and not a re-contrast.
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' };
+
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' },
+      textItems: [
+        {
+          id: 'a',
+          textStyle: { textStyleType: 'paragraph1', color: 'var(--palette-0)' }, // 1st: green
+        },
+        {
+          id: 'b',
+          textStyle: { textStyleType: 'paragraph1', color: 'var(--palette-3)' }, // 2nd: dark neutral
+        },
+        { id: 'c', textStyle: { textStyleType: 'paragraph1' } }, // 3rd: new, uncoloured
+      ],
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    const items = (
+      content as unknown as { textItems: { textStyle: { color?: string } }[] }
+    ).textItems;
+
+    expect(items[2].textStyle.color).toBe('var(--palette-3)'); // the item above (2nd), not the 1st
+  });
+
+  test('inherits the RENDERED mark colour, not a stale style colour left by an earlier bake', () => {
+    // The real repro: item 2 was inherited green (textStyle.color), then recoloured white — the RTE
+    // writes the MARK but leaves textStyle.color=green. A new item 3 must inherit the rendered white
+    // (the mark), not the stale green.
+    const markDoc = (color: string) => ({
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'x',
+              marks: [{ type: 'textStyle', attrs: { color } }],
+            },
+          ],
+        },
+      ],
+    });
+
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' };
+
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' },
+      textItems: [
+        {
+          id: 'a',
+          text: markDoc('var(--palette-3)'), // rendered white
+          textStyle: { textStyleType: 'paragraph1', color: 'var(--palette-0)' }, // STALE green
+        },
+        { id: 'b', textStyle: { textStyleType: 'paragraph1' } }, // new, uncoloured
+      ],
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    const items = (
+      content as unknown as { textItems: { textStyle: { color?: string } }[] }
+    ).textItems;
+
+    expect(items[1].textStyle.color).toBe('var(--palette-3)'); // the mark, not the stale style
+  });
+
+  test('inherits the above item colour from its RTE run mark when the style colour was cleared', () => {
+    // After birth authoring, an item carries its colour in the run mark (style colour cleared).
+    // A new item below must still inherit it.
+    const styles = stylesWithColors(BRAND_AND_NEUTRALS);
+
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' };
+
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'transparent' },
+      textItems: [
+        {
+          id: 'a',
+          text: {
+            type: 'doc',
+            content: [
+              {
+                type: 'paragraph',
+                content: [
+                  {
+                    type: 'text',
+                    text: 'x',
+                    marks: [
+                      {
+                        type: 'textStyle',
+                        attrs: { color: 'var(--palette-3)' },
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+          textStyle: { textStyleType: 'paragraph1' }, // style colour cleared; lives in the mark
+        },
+        { id: 'b', textStyle: { textStyleType: 'paragraph1' } },
+      ],
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    const items = (
+      content as unknown as { textItems: { textStyle: { color?: string } }[] }
+    ).textItems;
+
+    expect(items[1].textStyle.color).toBe('var(--palette-3)'); // inherited from item[0]'s mark
+  });
+
+  test('never overwrites an explicit element colour', () => {
+    const content = {
+      id: 't',
+      type: 'text',
+      backgroundColor: { backgroundColor: 'var(--palette-0)' },
+      textStyle: { textStyleType: 'paragraph1', color: '#abcabc' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    expect(colourOf(content, 'textStyle')).toBe('#abcabc');
+  });
+
+  test('never bakes the button label — it owns its own fill/text pairing', () => {
+    const content = {
+      id: 's',
+      type: 'shapes-section',
+      backgroundColor: { backgroundColor: 'var(--palette-0)' }, // dark band
+      buttonTextStyle: { textStyleType: 'button' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    expect(colourOf(content, 'buttonTextStyle')).toBeUndefined();
+  });
+
+  // BP-6144 S2: shop's title/description sit on the band, not the product tile — a
+  // sibling surface below them, not behind them. `topmostSolidSurface`'s generic
+  // top-of-stack scan would pick the tile (`fillColor` outranks `backgroundStyle`) and
+  // MIScolour the title against a surface it doesn't render on.
+  test('shop title contrasts the band, not a painted product tile', () => {
+    const content = {
+      id: 'sh',
+      type: 'shop-section',
+      fillColor: { backgroundColor: '#ffffff' }, // light tile
+      backgroundStyle: { backgroundColor: 'var(--palette-0)' }, // dark band
+      titleStyle: { textStyleType: 'heading1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    // Light on the dark band — a tile-routed fallback would give the dark-on-dark brand role.
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-1)');
+  });
+
+  test('shop description contrasts the band on the same rule as the title', () => {
+    const content = {
+      id: 'sh',
+      type: 'shop-section',
+      fillColor: { backgroundColor: '#ffffff' }, // light tile
+      backgroundStyle: { backgroundColor: 'var(--palette-0)' }, // dark band
+      descriptionStyle: { textStyleType: 'paragraph1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, stylesWithColors());
+
+    expect(colourOf(content, 'descriptionStyle')).toBe('var(--palette-1)');
+  });
+
+  test('shop title defers to the page when the band paints nothing solid, not the tile', () => {
+    const styles = stylesWithColors(); // palette-0 #000000 (dark), palette-1 #ffffff (light)
+
+    styles.backgroundStyles.style = { background: 'var(--palette-0)' }; // dark page
+
+    const content = {
+      id: 'sh',
+      type: 'shop-section',
+      fillColor: { backgroundColor: 'var(--palette-1)' }, // light tile, would win a tile fallback
+      backgroundStyle: {}, // transparent band
+      titleStyle: { textStyleType: 'heading1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    // Falls through to the dark page → light text; a tile fallback would give dark-on-light.
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-1)');
+  });
+});
+
+describe('applyTextContrast — standalone button labels (BP-5969)', () => {
+  // Every standalone button keeps its label in `titleStyle`. The label sits on the button fill,
+  // so the button owns its own fill/text pairing and the label must NOT be baked against the page.
+  // Source of truth for this set is `isButtonContent` (model.util.ts) — keep the two in sync.
+  const BUTTON_CONTENT_TYPES = [
+    'general-link',
+    'website',
+    'email',
+    'phone',
+    'facebook',
+    'x',
+    'instagram',
+    'youtube',
+    'linkedin',
+    'pinterest',
+    'twitch',
+    'tiktok',
+  ] as const;
+
+  const colourOf = (content: Content, key: string): string | undefined =>
+    (content as unknown as Record<string, { color?: string }>)[key]?.color;
+
+  // Reproduces the default theme's collision: the button fill and the page-contrast pick are the
+  // SAME brand role (palette-0 is both the fill and the dark role that contrasts a white page).
+  // If the label were baked it would take that role and vanish into the fill.
+  const collidingStyles = (): PageStyles => {
+    const styles = new PageStyles();
+
+    styles.colors = [
+      { id: 'palette-0', value: '#000000', type: 'palette' }, // dark brand — the button fill
+      { id: 'palette-1', value: '#ffffff', type: 'palette' }, // light brand
+    ];
+    styles.backgroundStyles.style = { background: 'var(--palette-1)' }; // white page
+    styles.buttonStyles.style = {
+      backgroundColor: 'var(--palette-0)', // dark fill
+      color: 'var(--palette-1)', // light on-fill label — what the unbaked label inherits at render
+    };
+
+    return styles;
+  };
+
+  test.each(BUTTON_CONTENT_TYPES)(
+    'leaves the %s label uncoloured so it inherits the button on-fill colour',
+    (type) => {
+      const content = {
+        id: 'b',
+        type,
+        title: 'Link',
+        titleStyle: { textStyleType: 'button', textAlign: 'center' },
+      } as unknown as Content;
+
+      applyTextContrast(content, collidingStyles());
+
+      // Baked here it would become var(--palette-0) — the fill — and disappear.
+      expect(colourOf(content, 'titleStyle')).toBeUndefined();
+    },
+  );
+
+  test('buttonLabelColorDefault gives the label the button on-fill colour for the swatch', () => {
+    const styles = collidingStyles(); // button on-fill colour is var(--palette-1)
+
+    const button = { id: 'b', type: 'general-link' } as unknown as Content;
+
+    // The label field takes the on-fill colour so the maker swatch matches the canvas.
+    expect(buttonLabelColorDefault(button, styles, 'titleStyle')).toBe(
+      'var(--palette-1)',
+    );
+
+    // Not a label field, and not a button → nothing to default.
+    expect(
+      buttonLabelColorDefault(button, styles, 'descriptionStyle'),
+    ).toBeUndefined();
+    expect(
+      buttonLabelColorDefault(
+        { id: 's', type: 'shapes-section' } as unknown as Content,
+        styles,
+        'titleStyle',
+      ),
+    ).toBeUndefined();
+  });
+
+  test('the exemption is scoped to button content, not the titleStyle key globally', () => {
+    // A section heading uses the same `titleStyle` key and MUST still bake against its band.
+    const styles = new PageStyles();
+
+    styles.colors = [
+      { id: 'palette-0', value: '#000000', type: 'palette' },
+      { id: 'palette-1', value: '#ffffff', type: 'palette' },
+    ];
+    styles.buttonStyles.style = { backgroundColor: 'var(--palette-1)' }; // white fill ≠ the band
+
+    const content = {
+      id: 's',
+      type: 'shapes-section',
+      backgroundColor: { backgroundColor: 'var(--palette-0)' }, // dark band
+      titleStyle: { textStyleType: 'heading1' },
+    } as unknown as Content;
+
+    applyTextContrast(content, styles);
+
+    expect(colourOf(content, 'titleStyle')).toBe('var(--palette-1)'); // light on the dark band
+  });
+});
+
+describe('applyTextContrast — social-links icon fill', () => {
+  const styles = (): PageStyles => {
+    const pageStyles = new PageStyles();
+
+    pageStyles.colors = [
+      { id: 'palette-0', value: '#000000', type: 'palette' },
+      { id: 'palette-1', value: '#ffffff', type: 'palette' },
+    ];
+
+    return pageStyles;
+  };
+
+  const socialLinks = (iconFillStyles: BrandPageCssStyle): Content =>
+    ({
+      id: 's',
+      type: 'social-links',
+      titleStyle: { textStyleType: 'heading4' },
+      iconFillStyles,
+      backgroundStyles: {},
+    }) as unknown as Content;
+
+  const iconFill = (content: Content): string | undefined =>
+    (content as unknown as { iconFillStyles: BrandPageCssStyle }).iconFillStyles
+      .fill;
+
+  test('a new section stores the colour its title gets on the icons', () => {
+    const content = socialLinks({});
+
+    applyTextContrast(content, styles());
+
+    const titleColour = (
+      content as unknown as { titleStyle: { color?: string } }
+    ).titleStyle.color;
+
+    expect(titleColour).toBeTruthy();
+    expect(iconFill(content)).toBe(titleColour);
+  });
+
+  test('an explicit icon fill is left alone', () => {
+    const content = socialLinks({ fill: '#abcdef' });
+
+    applyTextContrast(content, styles());
+
+    expect(iconFill(content)).toBe('#abcdef');
+  });
+});