Replace Primer React Flash with a house Banner component (#63722)

Author: V-halfaro

src/color-schemes/README.md

@@ -53,6 +53,27 @@ The resolved mode comes from the **effective theme**, not the raw `color_mode`,
 
 This is a workaround for a gap in Brand and belongs upstream; until it lands, every consumer has to hand Brand a concrete mode.
 
+### Color contrast requirements
+
+Colors must meet WCAG 2.1 AA in every supported mode. Primer documents the requirements in [ADR-010: Color contrast requirements](https://github.com/primer/primitives/blob/main/contributor-docs/adrs/adr-010-color-contrast.md). The ones that come up most often are:
+
+| Pair | Minimum ratio |
+|---|---|
+| Text vs. any background it can sit on | 4.5:1 |
+| Large text, icons, and other non-text UI vs. background | 3:1 |
+| Link vs. surrounding text | 3:1, unless the link is underlined. Links also need 4.5:1 against the background. |
+| Focus indicator vs. adjacent colors | 3:1 |
+| Border of a control that contains text, or a decorative border | None |
+
+Check both light and dark mode. Brand's base color scales (`--base-color-scale-*`) don't invert in dark mode, so a step that passes in light mode can fail in dark mode.
+
+Also check the no-JavaScript fallback, where `<html>` keeps `data-color-mode="auto"`. Brand stays on its light palette there, so a component that darkens its own background still gets light-mode link blue. Scope fallback selectors to `html`, because the `@primer/react` `ThemeProvider` wrapper also starts as `auto`.
+
+On colored surfaces, such as the `Banner` component in `src/frame/components/ui/Banner/`, we enforce these rules:
+
+* Always underline links. Don't rely on link color to separate links from surrounding text.
+* If the link color can't be guaranteed to reach 4.5:1 against the surface, set links to the surface's text color.
+
 ## Setup & Usage
 
 To access the current theme in a component:

src/frame/components/ui/Banner/Banner.module.scss

@@ -0,0 +1,65 @@
+// Colors follow the Docs 2026 Figma warning banner: Brand yellow-9 text with a yellow-7 accent.
+// Default and danger reuse the same scale steps in blue and red.
+// Brand's base scales do not invert in dark mode, so dark mode mirrors the steps explicitly,
+// the same way Brand's own component tokens pair a light step with a dark step.
+@mixin banner-colors($hue, $mode) {
+  @if $mode == light {
+    --banner-bg: var(--base-color-scale-#{$hue}-0);
+    --banner-border: var(--base-color-scale-#{$hue}-7);
+    --banner-fg: var(--base-color-scale-#{$hue}-9);
+  } @else {
+    --banner-bg: var(--base-color-scale-#{$hue}-9);
+    --banner-border: var(--base-color-scale-#{$hue}-2);
+    --banner-fg: var(--base-color-scale-#{$hue}-0);
+  }
+}
+
+@mixin banner-variant($hue) {
+  @include banner-colors($hue, light);
+
+  :global([data-color-mode="dark"]) & {
+    @include banner-colors($hue, dark);
+  }
+
+  // No-JS fallback; see the note in src/frame/stylesheets/index.scss. Scoped to html because
+  // the @primer/react ThemeProvider wrapper also starts as auto, even when html is light.
+  // Brand keeps its light link blue here, so links use the banner text color for contrast.
+  @media (prefers-color-scheme: dark) {
+    :global(html[data-color-mode="auto"][data-dark-theme*="dark"]) & {
+      @include banner-colors($hue, dark);
+
+      a {
+        color: var(--banner-fg);
+      }
+    }
+  }
+}
+
+.banner {
+  padding: var(--base-size-16, 1rem);
+  color: var(--banner-fg);
+  background-color: var(--banner-bg);
+  border: var(--brand-borderWidth-thin, 1px) solid var(--banner-border);
+  border-radius: var(--brand-borderRadius-medium, 0.5rem);
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+
+  // Link color alone is not distinct enough from banner text, especially in dark mode.
+  a {
+    text-decoration: underline;
+  }
+}
+
+.default {
+  @include banner-variant(blue);
+}
+
+.warning {
+  @include banner-variant(yellow);
+}
+
+.danger {
+  @include banner-variant(red);
+}

src/frame/components/ui/Banner/Banner.tsx

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react'
+import cx from 'clsx'
+
+import styles from './Banner.module.scss'
+
+export type BannerPropsT = {
+  variant?: 'default' | 'warning' | 'danger'
+  className?: string
+  children: ReactNode
+}
+
+// No live region role: every banner renders with the page and never updates in place.
+export function Banner({ variant = 'default', className, children }: BannerPropsT) {
+  return <div className={cx(styles.banner, styles[variant], className)}>{children}</div>
+}

src/frame/components/ui/Banner/index.ts

@@ -0,0 +1,2 @@
+export { Banner } from './Banner'
+export type { BannerPropsT } from './Banner'

src/rest/components/RestBanner.tsx

@@ -1,9 +1,9 @@
 import React from 'react'
-import { Flash } from '@primer/react'
 import { useRouter } from 'next/router'
 
 import { DEFAULT_VERSION, useVersion } from '@/versions/components/useVersion'
 import { Link } from '@/frame/components/Link'
+import { Banner } from '@/frame/components/ui/Banner'
 import { useMainContext } from '@/frame/components/context/MainContext'
 import { useTranslation } from '@/languages/components/useTranslation'
 import { RenderedHTML } from '@/frame/components/ui/RenderedHTML/RenderedHTML'
@@ -76,7 +76,7 @@ export const RestBanner = () => {
         data-testid="rest-api-versioning-temporary-banner"
         className="container-xl mt-3 mx-auto p-responsive"
       >
-        <Flash>
+        <Banner>
           <RenderedHTML as="span" html={bannerText} />{' '}
           <RenderedHTML
             as="span"
@@ -85,7 +85,7 @@ export const RestBanner = () => {
               versionWithApiVersion === DEFAULT_VERSION ? '' : `/${versionWithApiVersion}`,
             )}
           />
-        </Flash>
+        </Banner>
       </div>
     )
   }
@@ -130,15 +130,15 @@ export const RestBanner = () => {
 
   return (
     <div data-testid="rest-api-repos-banner" className="container-xl mt-3 mx-auto p-responsive">
-      <Flash variant="warning">
+      <Banner variant="warning">
         <p>
           <b className="text-bold">
             <span>
               {t('rest.banner.redirect_notice')} {noticeString}
             </span>
           </b>{' '}
         </p>
-      </Flash>
+      </Banner>
     </div>
   )
 }

src/search/components/results/NoQuery.module.scss

@@ -5,6 +5,6 @@
   line-height: 1.2;
 }
 
-.flash {
+.banner {
   margin: 2rem;
 }

src/search/components/results/NoQuery.tsx

@@ -1,13 +1,11 @@
-import { Flash } from '@primer/react'
 import { Heading } from '@primer/react-brand'
 
 import { useMainContext } from '@/frame/components/context/MainContext'
+import { Banner } from '@/frame/components/ui/Banner'
 import { useTranslation } from '@/languages/components/useTranslation'
 
 import styles from './NoQuery.module.scss'
 
-// NoQuery keeps the callout on Primer React because Brand lacks Flash, Banner, or Alert.
-// The Docs 2026 callout system is the planned replacement.
 export function NoQuery() {
   const { t } = useTranslation('old_search')
   const mainContext = useMainContext()
@@ -20,9 +18,9 @@ export function NoQuery() {
         {page.title}
       </Heading>
 
-      <Flash variant="danger" className={styles.flash}>
+      <Banner variant="danger" className={styles.banner}>
         {t('description')}
-      </Flash>
+      </Banner>
     </>
   )
 }

src/search/components/results/ValidationErrors.module.scss

@@ -1,3 +1,3 @@
-.flash {
+.banner {
   margin: 3rem;
 }

src/search/components/results/ValidationErrors.tsx

@@ -1,5 +1,4 @@
-import { Flash } from '@primer/react'
-
+import { Banner } from '@/frame/components/ui/Banner'
 import { useTranslation } from '@/languages/components/useTranslation'
 import type { SearchValidationErrorEntry } from '../../types'
 
@@ -16,11 +15,11 @@ export function ValidationErrors({ errors }: Props) {
     <div>
       {errors.map((error) => {
         return (
-          <Flash key={error.error} variant="warning" className={styles.flash}>
+          <Banner key={error.error} variant="warning" className={styles.banner}>
             {t('search_validation_error')}
             <br />
             <code>{error.error}</code>
-          </Flash>
+          </Banner>
         )
       })}
     </div>

src/versions/components/DeprecationBanner.tsx

@@ -1,10 +1,10 @@
 import type { EnterpriseDeprecation } from '@/frame/components/context/MainContext'
 import { useMainContext } from '@/frame/components/context/MainContext'
 import { useVersion } from '@/versions/components/useVersion'
-import { Flash } from '@primer/react'
 import cx from 'clsx'
 
 import styles from './DeprecationBanner.module.scss'
+import { Banner } from '@/frame/components/ui/Banner'
 import { RenderedHTML } from '@/frame/components/ui/RenderedHTML/RenderedHTML'
 
 export const DeprecationBanner = () => {
@@ -27,7 +27,7 @@ export const DeprecationBanner = () => {
       data-testid="deprecation-banner"
       className={cx('container-xl mt-3 mx-auto p-responsive', styles.DeprecationBanner)}
     >
-      <Flash variant="warning">
+      <Banner variant="warning">
         <p>
           <b className="text-bold">
             <RenderedHTML as="span" html={message} />{' '}
@@ -38,7 +38,7 @@ export const DeprecationBanner = () => {
           </b>{' '}
           <RenderedHTML as="span" html={enterpriseDeprecation.deprecation_details} />
         </p>
-      </Flash>
+      </Banner>
     </div>
   )
 }