An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): decouple Astryx primary/accent and make hero respect dark mode (#2855)
rubyycheungfdd92ce02114
diff --git a/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx b/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsxindex a7de7a6224..0b5b632dbb 100644--- a/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx+++ b/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx@@ -28,6 +28,7 @@ import {XDSTheme} from '@xds/core/theme';import {XDSText} from '@xds/core/Text';import {XDSPagination} from '@xds/core/Pagination';import {useMediaQuery} from '@xds/core/hooks';+import {useThemeMode} from '../../../providers';import {HERO_THEME_SLIDES, type HeroThemeSlide} from './heroThemeContent';import {AstryxWordmark} from './AstryxWordmark';import {HeroFloatingCards} from './HeroFloatingCards';@@ -45,6 +46,8 @@ interface HeroReelState {/** Whether entrance/cycle animation should run (false under reduced-motion). */animate: boolean;setPaused: (paused: boolean) => void;+ /** The docsite's active color mode (from the global theme toggle / OS). */+ userMode: 'light' | 'dark';}const HeroReelContext = createContext<HeroReelState | null>(null);@@ -54,16 +57,32 @@ function useHeroReel(): HeroReelState | null {}/**- * Whether the active reel slide is a dark-first theme. The hero text + nav use- * this to switch to light colors on dark slides (e.g. Gothic) so they stay- * readable on the dark per-slide background.+ * The color mode a slide should render in: dark-first themes (e.g. Gothic) are+ * always dark; every other theme follows the docsite's color mode so the hero+ * respects the user's light/dark toggle.+ */+function effectiveMode(+ slide: HeroThemeSlide,+ userMode: 'light' | 'dark',+): 'light' | 'dark' {+ return slide.isDark ? 'dark' : userMode;+}++/**+ * Whether the active hero slide should render with light text/nav. True when+ * the slide is a dark-first theme (e.g. Gothic) OR the docsite is in dark mode —+ * in both cases the hero sits on a dark body and its text/nav must go light.*/export function useHeroReelIsDark(): boolean {const reel = useContext(HeroReelContext);if (!reel || reel.slides.length === 0) {return false;}- return reel.slides[reel.index]?.isDark ?? false;+ const active = reel.slides[reel.index];+ if (!active) {+ return false;+ }+ return effectiveMode(active, reel.userMode) === 'dark';}const styles = stylex.create({@@ -185,6 +204,7 @@ export function HeroReelProvider({children}: {children: ReactNode}) {const [index, setIndex] = useState(0);const [paused, setPaused] = useState(false);const reduceMotion = useMediaQuery('(prefers-reduced-motion: reduce)');+ const {mode: userMode} = useThemeMode();const goTo = useCallback((next: number) => {@@ -214,8 +234,8 @@ export function HeroReelProvider({children}: {children: ReactNode}) {}, []);const value = useMemo<HeroReelState>(- () => ({slides, index, goTo, animate: !reduceMotion, setPaused}),- [slides, index, goTo, reduceMotion],+ () => ({slides, index, goTo, animate: !reduceMotion, setPaused, userMode}),+ [slides, index, goTo, reduceMotion, userMode],);return (@@ -251,7 +271,7 @@ export function HeroReelWordmark() {const active = reel.slides[reel.index];return (- <XDSTheme theme={active.theme} mode={active.mode}>+ <XDSTheme theme={active.theme} mode={effectiveMode(active, reel.userMode)}><div{...stylex.props(styles.wordmarkWrap,@@ -281,7 +301,7 @@ export function HeroReelCards() {const shown = reel.animate ? mounted : true;return (- <XDSTheme theme={active.theme} mode={active.mode}>+ <XDSTheme theme={active.theme} mode={effectiveMode(active, reel.userMode)}><div {...stylex.props(styles.themeFill)} aria-hidden="true" /><div {...stylex.props(styles.navBackdrop)} aria-hidden="true" /><div@@ -314,7 +334,7 @@ export function HeroReelStack() {}const active = reel.slides[reel.index];return (- <XDSTheme theme={active.theme} mode={active.mode}>+ <XDSTheme theme={active.theme} mode={effectiveMode(active, reel.userMode)}><HeroFloatingCards content={active.content} mounted layout="stack" /></XDSTheme>);diff --git a/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts b/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.tsindex cd8c9d06f6..9ccdbb10ce 100644--- a/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts+++ b/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts@@ -13,7 +13,7 @@import type {XDSDefinedTheme} from '@xds/core/theme';import {packages} from '../../../../generated/packageRegistry';import {themeObjects} from '../../../../generated/themeRegistry';-import {astryxTheme} from '../../../../themes/astryxTheme';+import {astryxTheme, BRAND_BLUE} from '../../../../themes/astryxTheme';// Sentinel for the docsite's local brand theme (not an @xds/theme-* package).const ASTRYX = 'astryx';@@ -294,14 +294,24 @@ function themeFor(name: string): XDSDefinedTheme | null {return themeObjects[name] ?? null;}-// Default wordmark color (theme accent — a dark ink on light themes).-const DEFAULT_WORDMARK_COLOR = 'var(--color-text-accent)';+// Wordmark color — by default the theme's accent text token. Each theme's+// --color-text-accent is already mode-correct (a dark ink on light themes,+// a light ink on dark-only themes like Gothic where accent === #E8F1F6).+const WORDMARK_COLOR = 'var(--color-text-accent)';-// Per-theme wordmark overrides (dark themes need a light ink on their dark fill).+// Per-theme wordmark overrides. Astryx is special: its theme repoints every+// accent token to the warm primary ink (the brand blue is reserved for the+// logo), so --color-text-accent is now near-black. The wordmark therefore+// uses the brand blue directly so the Astryx logo stays blue while the rest of+// the slide's UI reads as primary. Other themes fall back to WORDMARK_COLOR.const WORDMARK_COLOR_BY_THEME: Record<string, string> = {- '@xds/theme-gothic': 'var(--color-text-primary)',+ [ASTRYX]: BRAND_BLUE,};+function wordmarkColorFor(name: string): string {+ return WORDMARK_COLOR_BY_THEME[name] ?? WORDMARK_COLOR;+}+// Dark-first themes (rendered in dark mode; hero text/nav go light).const DARK_THEMES: ReadonlySet<string> = new Set<string>(['@xds/theme-gothic']);@@ -359,8 +369,7 @@ export const HERO_THEME_SLIDES: ReadonlyArray<HeroThemeSlide> = REEL_THEMES.map(theme,content: CONTENT_BY_THEME[name] ?? fallbackContent(name),aurora: AURORA_BY_THEME[name] ?? DEFAULT_AURORA,- wordmarkColor:- WORDMARK_COLOR_BY_THEME[name] ?? DEFAULT_WORDMARK_COLOR,+ wordmarkColor: wordmarkColorFor(name),isDark: DARK_THEMES.has(name),mode: DARK_THEMES.has(name) ? 'dark' : 'light',}diff --git a/apps/docsite/src/themes/astryxTheme.ts b/apps/docsite/src/themes/astryxTheme.tsindex 71dbd89b43..bb4d8e15ac 100644--- a/apps/docsite/src/themes/astryxTheme.ts+++ b/apps/docsite/src/themes/astryxTheme.ts@@ -3,17 +3,49 @@/*** Astryx Theme*- * Minimal — only two brand decisions:- * 1. Accent color: #292724 (warm near-black)- * 2. Typography: Figtree+ * The Astryx brand uses its blue ONLY for the logo/wordmark. Everything else+ * in the UI — buttons, links, focus rings, the Switch "on" track, accent+ * icons, and tints — is driven by the high-emphasis PRIMARY ink (warm+ * near-black). So the theme makes the accent tokens resolve to PRIMARY, and+ * the brand blue lives in its own BRAND_BLUE constant reserved for the logo+ * (applied by the hero, not by any semantic token here).*- * Everything else (surfaces, text, borders, status, radius, motion) is- * inherited from the default XDS theme behavior so the design system- * stays the source of truth and Astryx is a thin brand layer on top.+ * 1. PRIMARY — the high-emphasis foreground ink (warm near-black). Drives+ * primary text/icons AND the accent tokens, so all interactive UI reads+ * as near-black rather than blue. See `PRIMARY` below.+ * 2. BRAND_BLUE — the Astryx brand blue, reserved for the logo only. Not+ * wired to any semantic accent token; the hero paints the wordmark with+ * it directly. See `BRAND_BLUE` below.+ *+ * The only other overrides are the cream body color, Figtree typography, a+ * +4px radius bump, semibold display headings, and pill buttons. The neutral+ * gray ramp (surfaces, borders, secondary/disabled text, skeleton/track,+ * categorical gray) is intentionally left at the XDS defaults — Astryx is a+ * thin brand layer of primary + accent + body on top of the design system.*/import {defineTheme} from '@xds/core/theme';+// === PRIMARY (high-emphasis foreground ink — drives accent too) ==============+// Warm near-black that harmonizes with the cream body (light) and a warm+// off-white (dark). This is the primary text/icon color, and it ALSO drives+// the accent tokens (see below) so buttons/links/focus read as near-black.+const PRIMARY = 'light-dark(#15110C, #DFE2E5)';++// A warm near-black tint for the accent-muted surface (subtle hover/selected+// backgrounds). Mirrors PRIMARY's hue so muted accent fills match the primary-+// driven UI instead of staying blue. Dark mode uses a light warm tint.+const PRIMARY_MUTED =+ 'light-dark(rgba(21, 17, 12, 0.08), rgba(223, 226, 229, 0.14))';++// === BRAND_BLUE (logo only) ==================================================+// Brand blue (#225BFF) — the same blue baked into the Astryx logo/favicon.+// Reserved for the wordmark; the hero applies it directly (this theme does not+// point any accent token at it). Dark mode uses a lighter blue (#3D87FF) so the+// logo stays legible on the dark body. Exported so the hero can reference the+// exact brand value instead of hardcoding it.+export const BRAND_BLUE = 'light-dark(#225BFF, #3D87FF)';+export const astryxTheme = defineTheme({name: 'astryx',@@ -23,26 +55,36 @@ export const astryxTheme = defineTheme({// surfaces come out brown). Setting --color-accent directly leaves every// other token at the XDS default.tokens: {- '--color-accent': '#292724',- // Setting --color-accent alone leaves the *derived* accent tokens- // (text/icon/muted) at the XDS default blue, so links and accent icons- // across the docsite stayed blue. Point them at the brand accent too.- // light-dark() keeps dark mode legible (near-black is invisible on dark).- '--color-text-accent': 'light-dark(#292724, #E8E3DA)',- '--color-icon-accent': 'light-dark(#292724, #E8E3DA)',- '--color-accent-muted':- 'light-dark(rgba(41, 39, 36, 0.12), rgba(232, 227, 218, 0.16))',+ // --- ACCENT tokens → PRIMARY ---+ // The brand blue is reserved for the logo, so every accent token resolves+ // to the warm PRIMARY ink instead. This makes all interactive UI (buttons,+ // links, focus rings, the Switch "on" track, accent icons, tints) read as+ // near-black rather than blue. The on-accent ink is set below so the+ // contrast holds in both modes (the accent flips light↔dark with PRIMARY).+ '--color-accent': PRIMARY,+ '--color-text-accent': PRIMARY,+ '--color-icon-accent': PRIMARY,+ '--color-accent-muted': PRIMARY_MUTED,+ // On-accent (the label/icon ON a filled accent surface, e.g. primary+ // button text) must invert with the accent: PRIMARY is near-black in light+ // and near-white in dark, so the on-accent ink is white in light and+ // near-black in dark. Without this it stays the XDS default white and+ // becomes unreadable on the light dark-mode accent fill.+ '--color-on-accent': 'light-dark(#FFFFFF, #15110C)',// Mode-aware so the page background flips with dark mode. Light keeps the// warm Astryx cream; dark falls back to the XDS default body color// (a flat static value here would freeze the page in light mode).'--color-background-body': 'light-dark(#F8F4ED, #111112)',- // Re-tint the categorical "gray" surface to match the page body- // background. Cards rendered with `variant="gray"` (e.g. landing- // feature cards) blend into the body, reading as content groups- // shaped by padding + corners rather than as a coloured surface.- // Dark mode keeps the default --color-background-gray tint so- // recessed surfaces stay readable against the dark body.- '--color-background-gray': 'light-dark(#F8F4ED, rgba(102, 106, 114, 0.30))',++ // --- PRIMARY (high-emphasis foreground ink) ---+ // Both primary foreground tokens point at the single PRIMARY decision+ // above (which also drives the accent tokens). Secondary, disabled, and the+ // rest of the neutral gray ramp (surfaces, borders, skeleton/track,+ // categorical gray) are intentionally left at the XDS defaults — only the+ // primary ink is a brand decision.+ '--color-text-primary': PRIMARY,+ '--color-icon-primary': PRIMARY,+// Astryx display headings render semibold (XDS default is normal weight).'--text-display-1-weight': 'var(--font-weight-semibold)','--text-display-2-weight': 'var(--font-weight-semibold)',