Use Primer Brand color tokens on Brand-migrated surfaces (Docs 2026) (#63177)

Co-authored-by: Claude <noreply@anthropic.com>

Author: Ebonsignori

src/color-schemes/components/BrandThemeProvider.tsx

@@ -1,4 +1,4 @@
-import type { PropsWithChildren } from 'react'
+import { useEffect, useState, type PropsWithChildren } from 'react'
 import { useTheme as usePrimerTheme } from '@primer/react'
 import { ThemeProvider } from '@primer/react-brand'
 
@@ -9,7 +9,31 @@ export const BrandThemeProvider = ({ children }: PropsWithChildren) => {
   // otherwise many unhandled edge cases.
   // E.g. auto mode + dark mode + light scheme.
   const { resolvedColorScheme } = usePrimerTheme()
-  const colorMode = getBrandColorMode(resolvedColorScheme)
+
+  // Brand's ThemeProvider renders a real `<div data-color-mode>`, and brand
+  // declares its ENTIRE palette on the bare `[data-color-mode="light"]` /
+  // `[data-color-mode="dark"]` attribute. So a nested wrapper re-declares every
+  // brand token for its own subtree — canvas, text, borders, links, the lot.
+  //
+  // `resolvedColorScheme` is only correct after PRC's cookie-reading effect has
+  // run. On the server it resolves to light, and the first client render has to
+  // match the server markup, so it is light there too. Emitting `light` would
+  // override the correct mode colorModeScript has already stamped on `<html>`
+  // before first paint, and every brand token on the page would resolve to its
+  // light value until React hydrates — a white flash on every dark-mode load.
+  //
+  // We cannot server-render the real mode: that HTML is shared-cacheable in the
+  // CDN and must be identical for every request, which is why the pre-paint
+  // script exists at all.
+  //
+  // `auto` matches none of brand's blocks, so the wrapper declares nothing and
+  // brand's tokens inherit from `<html>`. Verified in-browser: with `<html>` at
+  // dark, a wrapper at `auto` resolves byte-identical token values to the root,
+  // whereas a wrapper at `light` flips all 16 tokens this app uses.
+  const [hydrated, setHydrated] = useState(false)
+  useEffect(() => setHydrated(true), [])
+
+  const colorMode = hydrated ? getBrandColorMode(resolvedColorScheme) : 'auto'
 
   return <ThemeProvider colorMode={colorMode}>{children}</ThemeProvider>
 }

src/content-render/stylesheets/accessibility.scss

@@ -48,7 +48,13 @@
   .tooltipped {
     &:focus-visible::before,
     &:focus-visible::after {
-      outline: 2px solid var(--color-focus-outset);
+      // --color-focus-outset is defined nowhere in this app, which made the whole
+      // `outline` shorthand invalid at computed-value time — so the longhands reset
+      // and `outline-style: none` won, leaving high-contrast users with NO focus
+      // ring at all, in either colour mode. Brand's focus token, matching the same
+      // repair already made in annotate.scss.
+      outline: var(--brand-borderWidth-thick, 2px) solid
+        var(--brand-color-focus, #0377ff);
       outline-offset: 2px;
     }
   }

src/content-render/stylesheets/syntax-highlighting.scss

@@ -8,7 +8,11 @@ from https://unpkg.com/highlight.js@9.15.8/styles/github.css
 .hljs {
   display: block;
   padding: 0.5em;
-  color: var(--color-fg-default);
+  // The block's BASE text colour — the tokens below are prettylights, which has
+  // no Brand equivalent and stays on Primer deliberately, but this one is just
+  // "default text" and was painting Primer's #e6edf3 inside a Brand-framed code
+  // block. The `background` is inert here (markdown-overrides paints the `pre`).
+  color: var(--brand-color-text-default);
   background: var(--color-canvas-subtle);
 }
 

src/fixtures/tests/playwright-rendering.spec.ts

@@ -1,7 +1,11 @@
 import dotenv from 'dotenv'
 import { test, expect } from '@playwright/test'
 import { turnOffExperimentsInPage } from '../helpers/turn-off-experiments'
-import { HOVERCARDS_ENABLED, ANALYTICS_ENABLED } from '../../frame/lib/constants'
+import {
+  HOVERCARDS_ENABLED,
+  ANALYTICS_ENABLED,
+  COLOR_MODE_COOKIE_NAME,
+} from '../../frame/lib/constants'
 
 // This exists for the benefit of local testing.
 // In GitHub Actions, we rely on setting the environment variable directly
@@ -19,6 +23,52 @@ test('view home page', async ({ page }) => {
   await expect(page).toHaveTitle(/GitHub Docs/)
 })
 
+test.describe('Brand document canvas', () => {
+  test('follows system color scheme changes in auto mode without a cookie', async ({ page }) => {
+    await page.emulateMedia({ colorScheme: 'dark' })
+    await page.goto('/get-started/foo/bar')
+    await expect(page.locator('html')).toHaveAttribute('data-color-mode', 'auto')
+
+    // Check both the initial dark paint and live preference changes without reloading.
+    for (const colorScheme of ['dark', 'light', 'dark'] as const) {
+      await page.emulateMedia({ colorScheme })
+      const backgroundColor = colorScheme === 'dark' ? 'rgb(0, 0, 0)' : 'rgb(255, 255, 255)'
+      const textColor = colorScheme === 'dark' ? 'rgb(255, 255, 255)' : 'rgb(0, 0, 0)'
+
+      for (const selector of ['html', 'body']) {
+        await expect(page.locator(selector)).toHaveCSS('background-color', backgroundColor)
+        await expect(page.locator(selector)).toHaveCSS('color', textColor)
+      }
+    }
+  })
+
+  for (const colorMode of ['light', 'dark'] as const) {
+    test(`preserves explicit ${colorMode} mode against the opposite system preference`, async ({
+      page,
+      context,
+      baseURL,
+    }) => {
+      await page.emulateMedia({ colorScheme: colorMode === 'light' ? 'dark' : 'light' })
+      await context.addCookies([
+        {
+          name: COLOR_MODE_COOKIE_NAME,
+          value: encodeURIComponent(JSON.stringify({ color_mode: colorMode })),
+          url: new URL('/', baseURL).href,
+        },
+      ])
+      await page.goto('/get-started/foo/bar')
+      await expect(page.locator('html')).toHaveAttribute('data-color-mode', colorMode)
+
+      const backgroundColor = colorMode === 'dark' ? 'rgb(0, 0, 0)' : 'rgb(255, 255, 255)'
+      const textColor = colorMode === 'dark' ? 'rgb(255, 255, 255)' : 'rgb(0, 0, 0)'
+      for (const selector of ['html', 'body']) {
+        await expect(page.locator(selector)).toHaveCSS('background-color', backgroundColor)
+        await expect(page.locator(selector)).toHaveCSS('color', textColor)
+      }
+    })
+  }
+})
+
 test('logo link keeps current version', async ({ page }) => {
   await page.goto('/enterprise-cloud@latest')
   await turnOffExperimentsInPage(page)

src/frame/components/DefaultLayout.module.scss

@@ -61,3 +61,13 @@
     display: flex;
   }
 }
+
+// The a11y skip link is a filled accent chip. Was primer/css
+// `color-bg-accent-emphasis color-fg-on-emphasis`, which paints the chip from
+// the PRC palette on a Brand surface. The Brand accent fill inverts between
+// modes (dark green in light, light green in dark), so onEmphasis text is
+// correct here.
+.skipButton {
+  background-color: var(--brand-color-accent-primary);
+  color: var(--brand-color-text-onEmphasis);
+}

src/frame/components/DefaultLayout.tsx

@@ -223,7 +223,7 @@ export const DefaultLayout = (props: Props) => {
       {/* a11y */}
       <a
         href="#main-content"
-        className="visually-hidden skip-button color-bg-accent-emphasis color-fg-on-emphasis"
+        className={cx('visually-hidden skip-button', styles.skipButton)}
         inert={isNarrowMenuOpen}
         aria-hidden={isNarrowMenuOpen || undefined}
       >

src/frame/components/GenericError.module.scss

@@ -1,3 +1,20 @@
 .logoContainer {
   z-index: 3;
 }
+
+// Header rule under the simple error-page banner. Was primer/css
+// `border-bottom color-border-muted`; the utility emits the whole shorthand
+// with !important, so the replacement has to own the shorthand too.
+.headerBorder {
+  border-bottom: 1px solid var(--brand-color-border-muted);
+}
+
+// Wordmark logo + "GitHub Docs" link. Was primer/css `color-fg-default`.
+.fgDefault {
+  color: var(--brand-color-text-default);
+}
+
+// Footer copyright line. Was primer/css `color-fg-muted`.
+.fgMuted {
+  color: var(--brand-color-text-muted);
+}

src/frame/components/GenericError.tsx

@@ -40,20 +40,20 @@ export function GenericError() {
 export const SimpleHeader = () => {
   const router = useRouter()
   return (
-    <div className="border-bottom color-border-muted no-print">
+    <div className={`no-print ${styles.headerBorder}`}>
       <header
         className="container-xl p-responsive py-3 position-relative d-flex width-full"
         role="banner"
         aria-label="Main"
       >
         <div className={`d-flex flex-items-center ${styles.logoContainer}`} id="github-logo-mobile">
           <Link href={`/${router.locale}`} aria-hidden="true" tabIndex={-1}>
-            <MarkGithubIcon size={32} className="color-fg-default" />
+            <MarkGithubIcon size={32} className={styles.fgDefault} />
           </Link>
 
           <Link
             href={`/${router.locale}`}
-            className="no-underline h4 color-fg-default no-wrap pl-2"
+            className={`no-underline h4 no-wrap pl-2 ${styles.fgDefault}`}
           >
             GitHub Docs
           </Link>
@@ -68,7 +68,7 @@ export const SimpleFooter = () => {
     <footer className="py-6">
       <div className="container-xl px-3 px-md-6">
         <ul role="list" className="d-flex flex-wrap list-style-none">
-          <li role="listitem" className="d-flex mr-xl-3 color-fg-muted">
+          <li role="listitem" className={`d-flex mr-xl-3 ${styles.fgMuted}`}>
             <span>&copy; {new Date().getFullYear()} GitHub, Inc.</span>
           </li>
           <li role="listitem" className="ml-3">

src/frame/components/article/ArticleGridLayout.module.scss

@@ -214,13 +214,11 @@
     // rules' right overshoot; those now stop at the body column's edge.)
     position: relative;
     z-index: 1;
-    // HOLDBACK: stays on Primer's canvas token deliberately. Brand's
-    // --brand-color-canvas-default is pure #000 in dark mode, but the page behind
-    // it is still painted #0d1117 by @primer/css's `body` rule — so adopting the
-    // brand canvas here makes this surface a visibly darker panel floating on a
-    // lighter page. The canvas can only move once the page canvas does; those
-    // should change together in one commit.
-    background-color: var(--color-canvas-default);
+    // Brand's canvas, matching the page. This was held back on Primer's token
+    // while `body` was still painted #0d1117 by @primer/css; that moved to
+    // --brand-color-canvas-default in src/frame/stylesheets/index.scss, so the
+    // holdback's own release condition ("change together in one commit") is met.
+    background-color: var(--brand-color-canvas-default);
     // Extend the border up to the bottom of the secondary bar (like the left
     // rail's divider). The grid's 24px padding-top + the article wrapper's 24px
     // top margin (`my-4`) otherwise leave the border starting ~48px below the

src/frame/components/page-footer/DocsFooter.module.scss

@@ -1,25 +1,10 @@
-// In dark mode the footer sits on the repo's canvas (#0d1117) while brand's
-// canvas-subtle comes from brand's own palette (#0f1511). Those are near-identical,
-// so the controls would lose their fill and read as bare outlines. Use Primer's
-// surfaces there instead: they're built to contrast with this background. Selector
-// pattern follows octicon-table-optimization.scss.
-@mixin footer-control-surfaces-dark {
-  --color-btn-bg: var(--color-canvas-subtle);
-  --color-btn-border: var(--color-border-default);
-  --color-btn-text: var(--color-fg-default);
-  --brand-footer-backToTop-bgColor-rest: var(--color-canvas-subtle);
-  // Brand's own dark border token is a different grey from Primer's, which would
-  // leave Back to top outlined differently from the three buttons beside it.
-  --brand-footer-backToTop-borderColor-rest: var(--color-border-default);
-}
-
 .docsFooter {
   // Brand defaults the footer to canvas-subtle (a grey panel); the design puts it on
   // the page canvas so it reads as continuous with the article and the band above.
-  // Deliberately the *repo's* canvas, not brand's: brand's canvas-default is pure
-  // black in dark mode while these pages sit on #0d1117, which would make the footer
-  // a visibly darker slab.
-  --brand-footer-bg-color: var(--bgColor-default, var(--color-canvas-default));
+  // Brand's canvas, not Primer's: every other painted element in here is brand, and
+  // `--bgColor-default` is undefined in this app so the old value fell through to
+  // Primer's blue-tinted #0d1117 in dark mode.
+  --brand-footer-bg-color: var(--brand-color-canvas-default);
 
   // The design draws all four footer controls (Yes, No, Make a contribution and
   // Back to top) on brand's subtle canvas with a subtle border (#f2f5f3 on #d2d9d4,
@@ -29,6 +14,18 @@
   // read rather than overriding the rules: the survey's selected states apply
   // `color-bg-success-emphasis` / `color-bg-danger-emphasis`, which set
   // background-color directly and must keep winning over the rest state.
+  //
+  // BOTH spellings are required. @primer/css declares the button like this:
+  //   border-color: var(--button-default-borderColor-rest, var(--color-btn-border));
+  // The legacy `--color-btn-*` names are only the FALLBACK. They used to win because
+  // the `--button-default-*` names were undefined in this app, but index.scss now
+  // imports the Primer Primitives functional themes, which define them — so setting
+  // only the legacy names would silently lose to Primer's palette (#3d444d borders
+  // in dark). Setting the modern names is what actually takes effect; the legacy
+  // ones are kept so this still works if the functional themes are ever dropped.
+  --button-default-bgColor-rest: var(--brand-color-canvas-subtle);
+  --button-default-borderColor-rest: var(--brand-color-border-subtle);
+  --button-default-fgColor-rest: var(--brand-color-text-default);
   --color-btn-bg: var(--brand-color-canvas-subtle);
   --color-btn-border: var(--brand-color-border-subtle);
   --color-btn-text: var(--brand-color-text-default);
@@ -37,16 +34,6 @@
   // the same treatment as the other three. Its border already matches.
   --brand-footer-backToTop-bgColor-rest: var(--brand-color-canvas-subtle);
 
-  :global([data-color-mode="dark"]) & {
-    @include footer-control-surfaces-dark;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    :global([data-color-mode="auto"][data-dark-theme*="dark"]) & {
-      @include footer-control-surfaces-dark;
-    }
-  }
-
   // The band above supplies the visual break, and the design puts a 2px emphasized
   // rule directly beneath it, on the footer's own top edge. Brand's default here is
   // a much brighter green (scale-green-3), so this stays an explicit override.
@@ -132,8 +119,7 @@
   .copyrightText {
     order: 2;
     padding: var(--base-size-20);
-    border-top: 1px solid
-      var(--borderColor-muted, var(--color-border-muted, #d2d9d4));
+    border-top: 1px solid var(--brand-color-border-subtle);
   }
 }
 
@@ -174,7 +160,10 @@
 
   // KO law requires the privacy statement link to be conspicuous.
   &[data-conspicuous="true"] {
-    color: var(--fgColor-attention, var(--color-fg-attention, #9a6700));
+    // Brand ships no attention token, so this chains to Primer's — but the old name
+    // is `--color-attention-fg`; spelled `--color-fg-attention` nothing in the chain
+    // resolved and the hardcoded light amber won in dark mode too.
+    color: var(--fgColor-attention, var(--color-attention-fg));
     font-weight: 600;
   }
 }