Skip to content

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.tsx
index 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.ts
index 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.ts
index 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)',