@designcrowd/library.brand-page 6.1.10 → 6.1.11

package/src/brand-page/models/footer-icon-color.test.ts

@@ -1,142 +1,78 @@
 import { describe, test, expect } from 'vitest';
-import {
-  BrandPageModel,
-  PageFooterDesktop,
-  PageFooterMobile,
-  type Theme,
-} from './index';
+import { BrandPageModel, PageFooterDesktop, PageFooterMobile } from './index';
 import {
   migrateBrandPageModel,
   GetLatestModelVersion,
 } from '../utils/migration.util';
-import { STYLE_THEME_KEYS } from '../constants';
-
-// BP-5886 (colour-v2): the footer social-icon colour must be wired to the same
-// logo/global colour source as every other surface. It is seeded from the theme
-// at construction (like the header's nav hamburger icon), then resolved /
-// referencified downstream. See docs/plans/feat-bp-5886-*.
-describe('footer icon colour is wired to the theme', () => {
-  // The footer background is transparent, so the icons sit on the page
-  // background (logo-background / secondaryColor); they must therefore take the
-  // contrasting logo-text colour (primaryColor) to stay legible.
-  const theme: Theme = {
-    primaryColor: STYLE_THEME_KEYS.LogoTextColor,
-    secondaryColor: STYLE_THEME_KEYS.LogoBackgroundColor,
-  };
 
-  describe('PageFooter* constructor seeding', () => {
-    test('seeds iconStyle.fill from theme.primaryColor (logo text) when a theme is passed', () => {
-      expect(new PageFooterDesktop({}, theme).iconStyle).toEqual({
-        fill: STYLE_THEME_KEYS.LogoTextColor,
-      });
-      expect(new PageFooterMobile({}, theme).iconStyle).toEqual({
-        fill: STYLE_THEME_KEYS.LogoTextColor,
-      });
-    });
-
-    test('stays empty when no theme is passed (non-theme call sites unchanged)', () => {
+// The footer social icons carry no fill in their SVGs, so an unstyled footer must not
+// inherit a site text colour (which need not read on the footer band). The constructor
+// leaves the icon unset; the fallback is decided downstream — migration-21 bakes an
+// explicit black, and a not-yet-migrated model renders the SVG default. An explicit
+// persisted colour always wins.
+describe('footer icon colour fallback', () => {
+  describe('PageFooter* constructor', () => {
+    test('leaves iconStyle unset (no colour seed)', () => {
       expect(new PageFooterDesktop().iconStyle).toEqual({});
       expect(new PageFooterMobile().iconStyle).toEqual({});
     });
 
-    test('repaints an empty persisted iconStyle', () => {
-      const footer = new PageFooterDesktop({ iconStyle: {} }, theme);
-
-      expect(footer.iconStyle).toEqual({
-        fill: STYLE_THEME_KEYS.LogoTextColor,
-      });
-    });
-
     test('preserves an explicit persisted icon colour', () => {
-      const footer = new PageFooterDesktop(
-        { iconStyle: { fill: '#abcdef' } },
-        theme,
-      );
-
-      expect(footer.iconStyle.fill).toBe('#abcdef');
+      expect(
+        new PageFooterDesktop({ iconStyle: { fill: '#abcdef' } }).iconStyle
+          .fill,
+      ).toBe('#abcdef');
     });
   });
 
-  describe('BrandPageModel wiring', () => {
-    test('a fresh model seeds both footer viewports with the logo-text colour', () => {
-      // theme.primaryColor is derived from styles.textStyles.style.color, which
-      // defaults to LogoTextColor (TextStyles.GetDefaultTextStyle).
-      const model = new BrandPageModel({});
-
-      expect(model.pageFooterDesktop.iconStyle.fill).toBe(
-        STYLE_THEME_KEYS.LogoTextColor,
-      );
-      expect(model.pageFooterMobile.iconStyle.fill).toBe(
-        STYLE_THEME_KEYS.LogoTextColor,
-      );
-    });
-  });
-
-  describe('end-to-end through migration', () => {
-    test('the seeded footer icon token is referencified to a palette reference', async () => {
+  describe('through migration', () => {
+    test('an unset footer icon is baked to a literal black fallback', async () => {
       // Fresh model is v=0, so it runs the full migration chain incl. migration-21.
       const { brandPageModel } = await migrateBrandPageModel(
         new BrandPageModel({}),
         { isUserDraft: false, isServerRender: false },
       );
 
-      const fill = brandPageModel.pageFooterDesktop.iconStyle.fill;
-
-      // It was seeded (not empty) and got referencified off the raw token to a
-      // well-formed palette reference.
-      expect(fill).not.toBe(STYLE_THEME_KEYS.LogoBackgroundColor);
-      expect(fill).toMatch(/^var\(--palette-\d+\)$/);
+      expect(brandPageModel.pageFooterDesktop.iconStyle.fill).toBe('#000000');
+      expect(brandPageModel.pageFooterMobile.iconStyle.fill).toBe('#000000');
     });
 
-    test('an already-migrated page seeds a render-ready value and needs no re-migration', async () => {
-      // An existing colour-v2 page is at the latest version with an already-
-      // referencified text colour. The footer icon inherits that value via
-      // theme.primaryColor, so it is render-ready without migration-21 re-running.
+    test('an explicit footer icon colour is preserved (referencified, not blacked out)', async () => {
       const persisted = {
-        v: GetLatestModelVersion(),
-        styles: {
-          textStyles: { style: { color: 'var(--palette-0)' } },
-        },
-        pageFooterDesktop: { iconStyle: {} },
+        styles: {},
+        pages: [],
+        pageFooterDesktop: { iconStyle: { fill: '#abcdef' } },
         pageFooterMobile: { iconStyle: {} },
       };
 
-      const model = new BrandPageModel(persisted);
-
-      expect(model.pageFooterDesktop.iconStyle.fill).toBe('var(--palette-0)');
-
-      const { brandPageModel } = await migrateBrandPageModel(model, {
-        isUserDraft: false,
-        isServerRender: false,
-      });
+      const { brandPageModel } = await migrateBrandPageModel(
+        new BrandPageModel(persisted),
+        { isUserDraft: false, isServerRender: false },
+      );
 
-      // Version gate skips migration-21, so the seeded palette ref is untouched.
-      expect(brandPageModel.pageFooterDesktop.iconStyle.fill).toBe(
-        'var(--palette-0)',
+      // The explicit colour rode pass B into a palette reference; the empty one took black.
+      expect(brandPageModel.pageFooterDesktop.iconStyle.fill).toMatch(
+        /^var\(--palette-/,
       );
+      expect(brandPageModel.pageFooterMobile.iconStyle.fill).toBe('#000000');
     });
 
-    test('a legacy footerStyles model seeds the icon before migration-01 re-wraps it', async () => {
-      // Pre-split models carry deprecated headerStyles/footerStyles; migration-01
-      // converts footerStyles → pageFooter*. The legacy footer must also be
-      // theme-seeded (like the legacy header nav) so the seed rides the re-wrap
-      // and migration-21 referencifies it — otherwise legacy sites keep empty
-      // footer icons after full migration.
-      const legacy = {
+    test('an already-migrated page is left untouched (version gate skips the bake)', async () => {
+      const persisted = {
+        v: GetLatestModelVersion(),
         styles: {},
-        pages: [],
-        headerStyles: { navigationStyles: { displayType: 'tabs' } },
-        footerStyles: { iconStyle: {} },
+        pageFooterDesktop: { iconStyle: {} },
+        pageFooterMobile: { iconStyle: {} },
       };
 
       const { brandPageModel } = await migrateBrandPageModel(
-        new BrandPageModel(legacy),
+        new BrandPageModel(persisted),
         { isUserDraft: false, isServerRender: false },
       );
 
-      expect(brandPageModel.pageFooterDesktop.iconStyle.fill).toMatch(
-        /^var\(--palette-\d+\)$/,
-      );
+      // migration-21 does not re-run, so the empty icon is left for the SVG default.
+      expect(brandPageModel.pageFooterDesktop.iconStyle).toEqual({});
+      expect(brandPageModel.pageFooterMobile.iconStyle).toEqual({});
     });
   });
 });

package/src/brand-page/models/index.ts

@@ -849,7 +849,7 @@ export abstract class AbstractPageFooterStyles {
 
   protected constructor(
     options: AbstractPageFooterStylesType = {},
-    theme?: Theme,
+    _theme?: Theme,
   ) {
     if (typeof options.viewport === 'undefined') {
       throw new Error('"viewport" is required');
@@ -920,14 +920,11 @@ export abstract class AbstractPageFooterStyles {
         imageLink: '',
       },
     ];
-    // Seed the social-icon colour from the theme's PRIMARY (logo text) colour: the
-    // footer background is transparent, so icons sit on the page background — the
-    // logo-background colour — and need the contrasting one to stay legible.
-    // Object.assign so an explicit persisted colour still wins.
-    this.iconStyle = Object.assign(
-      theme?.primaryColor ? { fill: theme.primaryColor } : {},
-      options.iconStyle || {},
-    );
+    // No colour seed: the social icons carry no fill of their own, so an unstyled footer
+    // leaves them unset and the fallback is decided downstream — migration-21 bakes an
+    // explicit black, a not-yet-migrated model renders the SVG default. Seeding a site
+    // text colour here need not read against the footer band.
+    this.iconStyle = options.iconStyle ? { ...options.iconStyle } : {};
     this.textFontFamily = options.textFontFamily;
   }
 }

package/src/brand-page/utils/__snapshots__/migration.util.test.ts.snap

@@ -41,7 +41,7 @@ exports[`migration.util > Banner Contents - text Align and Font Family should no
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,
@@ -101,7 +101,7 @@ exports[`migration.util > Banner Contents - text Align and Font Family should no
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,
@@ -534,7 +534,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,
@@ -594,7 +594,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,
@@ -1011,7 +1011,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,
@@ -1071,7 +1071,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
       "iconStyle": {
-        "fill": "var(--palette-0)",
+        "fill": "#000000",
       },
       "isLogoOptional": true,
       "isLogoVisible": true,

package/src/brand-page/utils/__snapshots__/migration2.util.test.ts.snap

@@ -26,9 +26,7 @@ exports[`migration02.ts > migration02 should return converted letterspacing 1`]
       },
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
-      "iconStyle": {
-        "fill": "logo-text-color",
-      },
+      "iconStyle": {},
       "isLogoOptional": true,
       "isLogoVisible": true,
       "logoDraftToken": "",
@@ -87,9 +85,7 @@ exports[`migration02.ts > migration02 should return converted letterspacing 1`]
       },
       "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
       "displayStyle": "centered-menu",
-      "iconStyle": {
-        "fill": "logo-text-color",
-      },
+      "iconStyle": {},
       "isLogoOptional": true,
       "isLogoVisible": true,
       "logoDraftToken": "",

package/src/brand-page/utils/__snapshots__/model.util.test.ts.snap

@@ -25,9 +25,7 @@ BrandPageModel {
     },
     "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
     "displayStyle": "centered-menu",
-    "iconStyle": {
-      "fill": "logo-text-color",
-    },
+    "iconStyle": {},
     "isLogoOptional": true,
     "isLogoVisible": true,
     "logoDraftToken": "",
@@ -86,9 +84,7 @@ BrandPageModel {
     },
     "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
     "displayStyle": "centered-menu",
-    "iconStyle": {
-      "fill": "logo-text-color",
-    },
+    "iconStyle": {},
     "isLogoOptional": true,
     "isLogoVisible": true,
     "logoDraftToken": "",
@@ -486,9 +482,7 @@ BrandPageModel {
     },
     "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
     "displayStyle": "centered-menu",
-    "iconStyle": {
-      "fill": "logo-text-color",
-    },
+    "iconStyle": {},
     "isLogoOptional": true,
     "isLogoVisible": true,
     "logoDraftToken": "",
@@ -547,9 +541,7 @@ BrandPageModel {
     },
     "copyrightText": "© 2026 by [Company Name]. All Rights Reserved.",
     "displayStyle": "centered-menu",
-    "iconStyle": {
-      "fill": "logo-text-color",
-    },
+    "iconStyle": {},
     "isLogoOptional": true,
     "isLogoVisible": true,
     "logoDraftToken": "",

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

@@ -323,6 +323,22 @@ describe('rteFrameFallbackColour', () => {
     ).toBeUndefined();
   });
 
+  // The maker's default text/profile background is the literal `'transparent'`, which the
+  // PRE-V2 renderer framed (its gate was `!isHexTransparent`, and that only excludes an
+  // alpha-00 hex) — so the RTE inherited the button colour. The bake must reproduce it, or
+  // those sites silently recolour from the button colour to the root paint.
+  test.each(['text', 'profile'] as const)(
+    'returns the button text colour for a %s section with a literal `transparent` background',
+    (type) => {
+      expect(
+        rteFrameFallbackColour(
+          framed(type, { backgroundColor: 'transparent' }),
+          stylesWith({ backgroundColor: BUTTON_FILL, color: BUTTON_TEXT }),
+        ),
+      ).toBe(BUTTON_TEXT);
+    },
+  );
+
   // --- container-bound blocks: always framed, whatever the card colour ---
   test('mailing-list on a CUSTOM (non-button-fill) card: still the button text colour', () => {
     expect(

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

@@ -17,7 +17,11 @@ import type {
 } from '../models';
 import { BRAND_PAGE_TYPES } from '../models';
 import type { ContentTextStylePropertyKey } from '../constants';
-import { backgroundColorFromStyle, isTransparentColour } from './color.util';
+import {
+  backgroundColorFromStyle,
+  isTransparentColour,
+  isHexTransparent,
+} from './color.util';
 import {
   resolveColorReference,
   bestContrastBrandRole,
@@ -253,10 +257,13 @@ const OWN_BACKGROUND_FRAME_TYPES: ReadonlySet<Content['type']> = new Set([
  * than silently recolouring published sites to the linked global — the exact trap ADR 0014
  * names, here applied to the migration bake (ADR 0015).
  *
- * Two frame families, mirroring the renderer:
- *  - **text / profile** — framed when the content has its own SOLID background (gate mirrors
- *    the view-model's container gate: a `background`/`backgroundColor` present and not an
- *    alpha-`00` hex).
+ * Two frame families:
+ *  - **text / profile** — framed when the content has its own painted background. The gate
+ *    deliberately mirrors the PRE-V2 renderer (`!isHexTransparent`), NOT the current
+ *    view-model gate (`!isTransparentColour`): the legacy renderer framed the literal
+ *    `'transparent'` (the maker's default background) too — only an alpha-`00` hex was
+ *    unframed — so its empty-mark RTE inherited the button colour. This bake must reproduce
+ *    that, or every default text/profile section silently recolours to the root paint.
  *  - **the container-bound blocks** (mailing-list, request-payment, support-me, non-brandSite
  *    contact-form) — always framed; `containerSurfaceForContent` is the existing oracle for
  *    "does this block paint a frame" (and encodes the brandSite contact-form carve-out), and
@@ -286,7 +293,9 @@ export const rteFrameFallbackColour = (
     ).backgroundColor;
     const reference = background?.background || background?.backgroundColor;
 
-    return reference && !isTransparentColour(reference)
+    // `isHexTransparent`, not `isTransparentColour`: the pre-V2 renderer framed the literal
+    // `'transparent'` (only an alpha-00 hex was unframed), so the bake must too — see docblock.
+    return reference && !isHexTransparent(reference)
       ? buttonTextColour
       : undefined;
   }

package/src/brand-page/utils/migration/migration-21.test.ts

@@ -2206,6 +2206,107 @@ describe('migration21 — step FINAL+1: bake resolved colour into inherit-only R
     );
   });
 
+  // The maker's DEFAULT text/profile background is the literal `'transparent'`. The pre-V2
+  // renderer framed it (its gate was `!isHexTransparent`, which excludes only an alpha-00
+  // hex), so the empty-mark RTE inherited the button colour — not the root paint. The bake
+  // must reproduce that or every default text section silently recolours (BP-5886 regression).
+  test('brandPage text section with a LITERAL `transparent` background: bakes to the frame button-text colour, not the paragraph global', async () => {
+    const model = {
+      styles: bakeStyles(),
+      brandPageType: 'default',
+      pages: [
+        {
+          contents: [
+            {
+              type: 'text',
+              backgroundColor: { backgroundColor: 'transparent' },
+              text: rteDoc(''),
+              textStyle: { textStyleType: 'paragraphs' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS_NO_LOGO,
+    );
+
+    const content = brandPageModel.pages[0].contents[0] as any;
+
+    expect(rteMarks(content.text)[0].attrs.color).toBe(
+      brandPageModel.styles.buttonStyles.style.color,
+    );
+    expect(rteMarks(content.text)[0].attrs.color).not.toBe(
+      paragraphColour(brandPageModel),
+    );
+  });
+
+  // The exact user-reported shape: an UNLINKED text style (no `textStyleType`) whose mark is
+  // `color: ''`, on the default `transparent` section. Without the frame it drops to the root
+  // paint; with it, the empty mark bakes to the button colour it showed pre-V2.
+  test('brandContact text section, UNLINKED style + empty `transparent` background: empty mark bakes to the button colour', async () => {
+    const model = {
+      styles: bakeStyles(),
+      brandPageType: 'brandContact',
+      pages: [
+        {
+          contents: [
+            {
+              type: 'text',
+              backgroundColor: { backgroundColor: 'transparent' },
+              text: rteDoc(''),
+              textStyle: { fontFamily: 'Lato' }, // no textStyleType, no color
+            },
+          ],
+        },
+      ],
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS_NO_LOGO,
+    );
+
+    const content = brandPageModel.pages[0].contents[0] as any;
+
+    expect(rteMarks(content.text)[0].attrs.color).toBe(
+      brandPageModel.styles.buttonStyles.style.color,
+    );
+  });
+
+  test('profile with a LITERAL `transparent` background: uncoloured title bakes to the frame button-text colour', async () => {
+    const model = {
+      styles: bakeStyles(),
+      brandPageType: 'default',
+      pages: [
+        {
+          contents: [
+            {
+              type: 'profile',
+              backgroundColor: { backgroundColor: 'transparent' },
+              title: rteDoc(''),
+              titleStyle: { textStyleType: 'headings' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS_NO_LOGO,
+    );
+
+    const content = brandPageModel.pages[0].contents[0] as any;
+
+    expect(titleMarkColour(content)).toBe(
+      brandPageModel.styles.buttonStyles.style.color,
+    );
+    expect(titleMarkColour(content)).not.toBe(headingColour(brandPageModel));
+  });
+
   test('profile on a SOLID background: uncoloured title/description bake to the frame button-text colour', async () => {
     const model = {
       styles: bakeStyles(),
@@ -2594,3 +2695,71 @@ describe('migration21 — step FINAL+1: bake resolved colour into inherit-only R
     );
   });
 });
+
+describe('migration21 — icon fills (social-links + footer)', () => {
+  test('social-links: an unset iconFillStyles.fill is baked from the referencified root text colour', async () => {
+    const model = {
+      styles: { textStyles: { style: { color: '#123456' } }, colors: [] },
+      pages: [{ contents: [{ type: 'social-links', iconFillStyles: {} }] }],
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS,
+    );
+
+    const rootRef = refFor(brandPageModel, '#123456');
+
+    expect(rootRef).toMatch(/^var\(--palette-/);
+    expect(
+      (brandPageModel.pages[0].contents[0] as any).iconFillStyles.fill,
+    ).toBe(rootRef);
+  });
+
+  test('social-links: an explicit iconFillStyles.fill is preserved, not overwritten', async () => {
+    const model = {
+      styles: { textStyles: { style: { color: '#123456' } }, colors: [] },
+      pages: [
+        {
+          contents: [
+            { type: 'social-links', iconFillStyles: { fill: '#abcdef' } },
+          ],
+        },
+      ],
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS,
+    );
+
+    // Its own colour rode pass B into a reference; the root ref did not replace it.
+    expect(
+      (brandPageModel.pages[0].contents[0] as any).iconFillStyles.fill,
+    ).toBe(refFor(brandPageModel, '#abcdef'));
+  });
+
+  test('footer: an unset iconStyle.fill is baked to a literal black; an explicit one is kept', async () => {
+    const model = {
+      styles: { textStyles: { style: { color: '#123456' } }, colors: [] },
+      pages: [],
+      pageFooterDesktop: { iconStyle: {} },
+      pageFooterMobile: { iconStyle: { fill: '#654321' } },
+    };
+
+    const { brandPageModel } = await migration21(
+      createMigrationData(model),
+      OPTIONS,
+    );
+
+    // Literal, not a palette ref: painted after pass B, so it mints no custom.
+    expect(brandPageModel.pageFooterDesktop.iconStyle.fill).toBe('#000000');
+    expect(
+      brandPageModel.styles.colors.some((c: any) => c.value === '#000000'),
+    ).toBe(false);
+    // The explicit footer colour was referencified, not blacked out.
+    expect(brandPageModel.pageFooterMobile.iconStyle.fill).toBe(
+      refFor(brandPageModel, '#654321'),
+    );
+  });
+});

package/src/brand-page/utils/migration/migration-21.ts

@@ -491,6 +491,75 @@ export const moveRootTextColourIntoGlobalStyles = (
   delete (textStyles as unknown as Record<string, unknown>)['style'];
 };
 
+/* -------------------------------------------------------------------------- *
+ * Step FINAL−: bake the social-icon fills the palette walk leaves unset
+ * -------------------------------------------------------------------------- */
+
+/**
+ * The footer social icons carry no `fill` in their SVGs, so an unset footer icon painted
+ * the SVG default (black). Baked as a LITERAL, not a palette ref — a fixed fallback for
+ * that previously-implicit default, so it does not mint a palette custom or follow palette
+ * edits. Painted after pass B, so referencify never sees it.
+ */
+const FOOTER_ICON_FALLBACK_COLOUR = '#000000';
+
+/**
+ * Bake the two social-icon fills that neither the palette walk nor a resolver sets, so
+ * each persists an explicit colour instead of a render-time seed that changed under V2:
+ *
+ * - **social-links content** (`iconFillStyles.fill`) → the site's ROOT text colour, the
+ *   colour the icon followed before the palette split (`styles.textStyles.style.color`).
+ *   Read here — already referencified by pass B — BEFORE
+ *   `moveRootTextColourIntoGlobalStyles` retires it, which is why this runs at Step FINAL−.
+ * - **footer** (`pageFooter{Desktop,Mobile}.iconStyle.fill`) → a literal black
+ *   (`FOOTER_ICON_FALLBACK_COLOUR`).
+ *
+ * Blank-only: an explicit persisted colour is never touched (`Object`-spread with the fill
+ * appended only when absent). A re-run finds every fill set, so it is a no-op.
+ */
+const bakeIconColours = (brandPageModel: BrandPageModel): void => {
+  const rootTextColour = legacyRootTextColour(brandPageModel);
+
+  if (!isBlankColorValue(rootTextColour)) {
+    for (const page of brandPageModel.pages ?? []) {
+      for (const content of page.contents ?? []) {
+        if (content.type !== 'social-links') {
+          continue;
+        }
+
+        const fields = content as unknown as Record<string, unknown>;
+        const iconFillStyles = (fields.iconFillStyles ?? {}) as Record<
+          string,
+          unknown
+        >;
+
+        if (isBlankColorValue(iconFillStyles.fill as string | undefined)) {
+          fields.iconFillStyles = { ...iconFillStyles, fill: rootTextColour };
+        }
+      }
+    }
+  }
+
+  for (const footer of [
+    brandPageModel.pageFooterDesktop,
+    brandPageModel.pageFooterMobile,
+  ]) {
+    if (!footer) {
+      continue;
+    }
+
+    const footerRecord = footer as unknown as Record<string, unknown>;
+    const iconStyle = (footerRecord.iconStyle ?? {}) as Record<string, unknown>;
+
+    if (isBlankColorValue(iconStyle.fill as string | undefined)) {
+      footerRecord.iconStyle = {
+        ...iconStyle,
+        fill: FOOTER_ICON_FALLBACK_COLOUR,
+      };
+    }
+  }
+};
+
 /* -------------------------------------------------------------------------- *
  * Step 0.1: retire styles.logoStyles.backgroundStyle onto the logo content
  * -------------------------------------------------------------------------- */
@@ -974,6 +1043,12 @@ export const migration21 = async (
 
   brandPageModel.styles.colors = builder.toColorItems();
 
+  // ---- Step FINAL−: bake icon fills before the root colour is retired ----
+  // Social-links icons take the now-referencified root text colour they followed before
+  // the palette split; footer icons take a literal black fallback. Reads the root ref, so
+  // it MUST precede its retirement below.
+  bakeIconColours(brandPageModel);
+
   // ---- Step FINAL: retire the root text colour (order matters — see docblock) ----
   moveRootTextColourIntoGlobalStyles(brandPageModel);