Add support for derived color modes

.changeset/lazy-wolves-win.md

@@ -0,0 +1,6 @@
+---
+'@primer/react-brand': minor
+'@primer/brand-primitives': patch
+---
+
+`ThemeProvider` now supports derived color modes. You can pass modes like `"dark_dimmed"` or `"light_high_contrast"` and the right light or dark color tokens will apply. No new themes are added; derived modes inherit from the existing `light` and `dark` token sets.

packages/design-tokens/src/formats/color-mode-attributes.js

@@ -32,7 +32,8 @@ function colorModeAttributes({dictionary, file, options}) {
 
   const renderLightMode = () =>
     `:root, 
-    [data-color-mode=${defaultMode}]  { 
+    [data-color-mode="${defaultMode}"],
+    [data-color-scheme="light"] { 
       ${allTokens
         .map(createPropertyFormatter({outputReferences, dictionary, format: 'css', formatter: {}, themeable: false}))
         .filter(function (strVal) {
@@ -64,8 +65,14 @@ function colorModeAttributes({dictionary, file, options}) {
 
     const {allTokens: newAllTokens} = newDictionary
 
+    let selector = `[data-color-mode="${mode}"]`
+
+    if (mode === 'dark') {
+      selector = `[data-color-mode="${mode}"], [data-color-scheme="dark"]`
+    }
+
     return `
-    [data-color-mode="${mode}"]  {
+    ${selector}  {
 
     ${newAllTokens
       .map(replaceWithAlternateModeValue)
@@ -86,6 +93,7 @@ function colorModeAttributes({dictionary, file, options}) {
 
     }\n`
   }
+
   const template = `
       ${fileHeader({file})}
 

packages/design-tokens/src/formats/color-mode-attributes.test.js

@@ -133,15 +133,17 @@ describe('Design tokens', () => {
 
     const expectedOutput = `
 :root,
-[data-color-mode="light"] {
+[data-color-mode="light"],
+[data-color-scheme="light"] {
   --brand-text-color-example: gray;
 }
 
 [data-color-mode="light_high_contrast"] {
   --brand-text-color-example: black;
 }
 
-[data-color-mode="dark"] {
+[data-color-mode="dark"],
+[data-color-scheme="dark"] {
   --brand-text-color-example: white;
 }
 `.trim()
@@ -460,13 +462,15 @@ describe('Design tokens', () => {
 
     const expectedOutput = `
 :root,
-[data-color-mode="light"] {
+[data-color-mode="light"],
+[data-color-scheme="light"] {
   --base-color-scale-gray-0: #f6f8fa;
   --base-color-scale-gray-1: #eaeef2;
   --base-color-scale-gray-2: #b1bac4;
 }
 
-[data-color-mode="dark"] {
+[data-color-mode="dark"],
+[data-color-scheme="dark"] {
   --base-color-scale-gray-0: #f0f6fc;
   --base-color-scale-gray-1: #c9d1d9;
   --base-color-scale-gray-2: #b1bac4;
@@ -476,7 +480,7 @@ describe('Design tokens', () => {
   --base-color-scale-gray-0: #f0f6fc;
   --base-color-scale-gray-1: #c9d1d9;
   --base-color-scale-gray-2: #b1bac4;
-}    
+}
 `.trim()
 
     // remove timestamp and trim

packages/react/src/Accordion/Accordion.module.css

@@ -299,7 +299,7 @@ details[open] > .Accordion__summary .Accordion__summary-toggleIcon {
   display: block;
 }
 
-[data-color-mode='dark'] .Accordion__content {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .Accordion__content {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: auto;
 }

packages/react/src/Card/Card.stories.shared.module.css

@@ -34,7 +34,7 @@
     var(--brand-color-canvas-default);
 }
 
-[data-color-mode='dark'] .gridColumnArrowHover .gridItem:is(:hover, :focus-within) {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .gridColumnArrowHover .gridItem:is(:hover, :focus-within) {
   background: linear-gradient(180deg, rgba(242, 245, 243, 0.1) 0%, rgba(242, 245, 243, 0) 100%),
     var(--brand-color-canvas-default);
 }

packages/react/src/Card/CardSkewEffect.tsx

@@ -1,7 +1,7 @@
 import React, {useRef, useEffect, PropsWithChildren} from 'react'
 import {clsx} from 'clsx'
 
-import {useTheme} from '../'
+import {getColorScheme, useTheme} from '../'
 import {BaseProps} from '../component-helpers'
 
 import styles from './Card.module.css'
@@ -21,11 +21,12 @@ export const CardSkewEffect = ({
   ...rest
 }: PropsWithChildren<CardSkewEffectProps>) => {
   const {colorMode} = useTheme()
+  const colorScheme = getColorScheme(colorMode)
   const boundingRef = useRef<HTMLDivElement | null>(null)
   const torchRef = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => {
-    if (colorMode === 'light' || disableSkew) return
+    if (colorScheme === 'light' || disableSkew) return
 
     const motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)')
 
@@ -70,7 +71,7 @@ export const CardSkewEffect = ({
       torchElement?.removeEventListener('mousemove', handleMouseMove)
       motionQuery.removeEventListener('change', handleReducedMotionChange)
     }
-  }, [disableSkew, perspective, colorMode])
+  }, [disableSkew, perspective, colorScheme])
 
   return (
     <div ref={boundingRef} className={clsx(styles['Card--skew'], className)} {...rest}>

packages/react/src/Heading/Heading.module.css

@@ -15,7 +15,7 @@
   --condensed-stretch: 90%;
 }
 
-[data-color-mode='dark'] .Heading {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .Heading {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }

packages/react/src/Hero/Hero.stories.module.css

@@ -4,6 +4,22 @@
   aspect-ratio: 16 / 9;
 }
 
+/**
+* Examples
+* TODO: Replace with functional token when final color is confirmed
+*/
+
+.heroWithCardsExample {
+  --customCardsBackgroundColor: transparent;
+}
+:is([data-color-mode='light'], [data-color-scheme='light']) .heroWithCardsExample {
+  --customCardsBackgroundColor: var(--base-color-scale-gray-1);
+}
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .heroWithCardsExample {
+  --customCardsBackgroundColor: var(--base-color-scale-gray-9);
+}
+
+
 /* Custom input with ActionMenu and code copying */
 
 .customInputExample {

packages/react/src/InlineLink/InlineLink.module.css

@@ -24,7 +24,7 @@
   color: var(--brand-InlineLink-color-pressed);
 }
 
-[data-color-mode='dark'] .InlineLink {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .InlineLink {
   -webkit-font-smoothing: subpixel-antialiased;
   -moz-osx-font-smoothing: auto;
 }

packages/react/src/Label/Label.module.css

@@ -32,7 +32,7 @@
   text-align: center;
 }
 
-[data-color-mode='dark'] .Label {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .Label {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: auto;
 }

packages/react/src/MinimalFooter/MinimalFooter.module.css

@@ -82,7 +82,7 @@
   height: auto;
 }
 
-[data-color-mode='light'] .Footer__social-icon {
+:is([data-color-mode='light'], [data-color-scheme='light']) .Footer__social-icon {
   filter: brightness(95%) saturate(100%);
 }
 

packages/react/src/MinimalFooter/MinimalFooter.test.tsx

@@ -298,6 +298,18 @@ describe('MinimalFooter', () => {
     )
   })
 
+  it('uses dark logo fill for derived dark color modes', () => {
+    const {container} = render(
+      <ThemeProvider colorMode="dark_dimmed">
+        <MinimalFooter />
+      </ThemeProvider>,
+    )
+
+    const logo = container.querySelector('a[aria-label="GitHub"] svg')
+
+    expect(logo).toHaveAttribute('fill', 'white')
+  })
+
   it('renders social links with visually hidden text', () => {
     const {getByText} = render(<MinimalFooter socialLinks={['x']} />)
     const hiddenText = getByText('GitHub on X')

packages/react/src/MinimalFooter/MinimalFooter.tsx

@@ -2,7 +2,7 @@ import React, {PropsWithChildren} from 'react'
 import {clsx} from 'clsx'
 import {LogoGithubIcon} from '@primer/octicons-react'
 
-import {ColorModesEnum, Stack, Text, useTheme} from '../'
+import {getColorScheme, Stack, Text, useTheme} from '../'
 import {BaseProps} from '../component-helpers'
 
 /**
@@ -235,6 +235,7 @@ type SocialLogomarksProps = {
 
 function SocialLogomarks({socialLinks = socialLinkNames, logoHref}: SocialLogomarksProps) {
   const {colorMode} = useTheme()
+  const colorScheme = getColorScheme(colorMode)
 
   return (
     <section className={clsx(styles['Footer__logomarks'])}>
@@ -252,7 +253,7 @@ function SocialLogomarks({socialLinks = socialLinkNames, logoHref}: SocialLogoma
               data-analytics-event='{"category":"Footer","action":"go to home","label":"text:home"}'
               aria-label="GitHub"
             >
-              <LogoGithubIcon fill={colorMode === ColorModesEnum.DARK ? 'white' : 'black'} size="medium" />
+              <LogoGithubIcon fill={colorScheme === 'dark' ? 'white' : 'black'} size="medium" />
             </a>
           </div>
           {socialLinks ? (

packages/react/src/SubNav/SubNav.module.css

@@ -21,7 +21,7 @@
   background-color: var(--brand-SubNav-bgColor);
 }
 
-[data-color-mode='dark'] .SubNav {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .SubNav {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }

packages/react/src/Text/Text.module.css

@@ -2,7 +2,7 @@
   font-family: var(--brand-body-fontFamily);
 }
 
-[data-color-mode='dark'] .Text--antialiased {
+:is([data-color-mode='dark'], [data-color-scheme='dark']) .Text--antialiased {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: auto;
 }

packages/react/src/ThemeProvider/ThemeProvider.stories.tsx

@@ -1,32 +1,54 @@
 import React from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
 import {SunIcon, MoonIcon} from '@primer/octicons-react'
-import {ThemeProvider} from '.'
-import {useTheme} from '..'
-import {Text} from '../Text'
-
+import {ThemeProvider, type ThemeProviderProps} from '.'
+import {Box, Text, Stack, useTheme} from '..'
 import styles from './ThemeProvider.stories.module.css'
 
 function ActiveColorMode() {
   const {colorMode} = useTheme()
   return <Text>Active global color mode: {colorMode}</Text>
 }
 
+const providerBoxProps = {
+  backgroundColor: 'default',
+  borderColor: 'default',
+  borderRadius: 'xlarge',
+  borderStyle: 'solid',
+  borderWidth: 'thin',
+  padding: 24,
+} as const
+
 function Container({children}: {children: React.ReactNode}) {
   return <section className={styles['active-color-scheme']}>{children}</section>
 }
 
 function ControlsHint() {
   return (
-    <Text as="p" className={styles.hint}>
+    <Text as="p" variant="muted">
       Hint: Use Storybook Controls to alternate between color modes.
     </Text>
   )
 }
 
+const StorybookColorModes = [
+  'light',
+  'dark',
+  'dark_dimmed',
+  'light_high_contrast',
+  'dark_high_contrast',
+  'auto',
+] satisfies ThemeProviderProps['colorMode'][]
+
 const meta = {
   title: 'Components/ThemeProvider',
   component: ThemeProvider,
+  argTypes: {
+    colorMode: {
+      control: 'select',
+      options: StorybookColorModes,
+    },
+  },
 } satisfies Meta<typeof ThemeProvider>
 
 export default meta
@@ -73,3 +95,44 @@ export const Nested: Story = {
     </div>
   ),
 }
+
+export const DerivedColorModes: Story = {
+  args: {
+    colorMode: 'auto',
+  },
+  render: args => (
+    <Stack gap="normal">
+      <ThemeProvider colorMode={args.colorMode}>
+        <Box {...providerBoxProps}>
+          <Stack gap="normal">
+            <Text>{`Parent provider: ${args.colorMode}`}</Text>
+            <ThemeProvider colorMode="dark_dimmed">
+              <Box {...providerBoxProps}>
+                <Stack gap="normal">
+                  <Text font="hubot-sans">Nested provider: dark_dimmed</Text>
+                  <Stack direction={{narrow: 'vertical', regular: 'horizontal'}} gap="normal">
+                    <ThemeProvider colorMode="light_high_contrast" style={{flex: '1 1 0', display: 'flex'}}>
+                      <Box {...providerBoxProps} style={{minHeight: '12rem', width: '100%'}}>
+                        <Text font="hubot-sans">Sibling provider: light_high_contrast</Text>
+                      </Box>
+                    </ThemeProvider>
+                    <ThemeProvider colorMode="dark_high_contrast" style={{flex: '1 1 0', display: 'flex'}}>
+                      <Box {...providerBoxProps} style={{minHeight: '12rem', width: '100%'}}>
+                        <Text font="hubot-sans">Sibling provider: dark_high_contrast</Text>
+                      </Box>
+                    </ThemeProvider>
+                    <ThemeProvider colorMode="auto" style={{flex: '1 1 0', display: 'flex'}}>
+                      <Box {...providerBoxProps} style={{minHeight: '12rem', width: '100%'}}>
+                        <Text font="hubot-sans">Sibling provider: auto</Text>
+                      </Box>
+                    </ThemeProvider>
+                  </Stack>
+                </Stack>
+              </Box>
+            </ThemeProvider>
+          </Stack>
+        </Box>
+      </ThemeProvider>
+    </Stack>
+  ),
+}