Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): dark-mode CTA legibility, mobile hero height, themes page polish (#2938)

Cindy Zhang50c8eeca972e
diff --git a/apps/docsite/src/app/(site)/page.tsx b/apps/docsite/src/app/(site)/page.tsx
index 10cf332141..e6bbf1b1bf 100644
--- a/apps/docsite/src/app/(site)/page.tsx
+++ b/apps/docsite/src/app/(site)/page.tsx
@@ -80,11 +80,12 @@ const styles = stylex.create({
},
// Reserves the hero's height in flow (heroContent is fixed/out of flow).
// Narrow: the measured --hero-content-height (per-tier constants are the
- // fallback). Desktop: the fixed band.
+ // fallback), capped at 100lvh so the pinned band never reserves more than one
+ // viewport of scroll on phones/tablets. Desktop (≥1024px): the fixed band.
heroSpacer: {
height: {
- default: `var(--hero-content-height, ${HERO_BAND_HEIGHT_2COL}px)`,
- '@media (min-width: 768px)': `var(--hero-content-height, ${HERO_BAND_HEIGHT_NARROW}px)`,
+ default: `min(var(--hero-content-height, ${HERO_BAND_HEIGHT_2COL}px), 100lvh)`,
+ '@media (min-width: 768px)': `min(var(--hero-content-height, ${HERO_BAND_HEIGHT_NARROW}px), 100lvh)`,
'@media (min-width: 1024px)': HERO_BAND_HEIGHT,
},
},
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.css
index 736af7a181..af88a3b4b0 100644
--- a/apps/docsite/src/app/globals.css
+++ b/apps/docsite/src/app/globals.css
@@ -130,6 +130,15 @@ body[data-hero-dark]:not([data-nav-mode='surface'])
color: var(--hero-on-dark);
}
+/* The primary "Get started" CTA paints its own accent fill, so its label must
+ track the fill's on-accent ink (a light-dark() token) rather than the hero's
+ static light nav ink — otherwise it's light-on-light and vanishes in dark
+ mode. Higher specificity than the blanket a/button rule above. */
+body[data-hero-dark]:not([data-nav-mode='surface'])
+ .xds-top-nav:where(:not(.xds-app-shell .xds-app-shell *)) [data-variant='primary'] {
+ color: var(--color-on-accent);
+}
+
/* Hide the prev/next chevron buttons inside the home page's hero theme
switcher pagination so only the dot indicators show. XDSPagination's
variant="dots" ships with chevrons by default; the hero wants a minimal
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index 861627ad0e..8441a8ade8 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -18,6 +18,7 @@ import {Link} from '@xds/core/Link';
import {SelectableCard} from '@xds/core/SelectableCard';
import {Selector} from '@xds/core/Selector';
import {Divider} from '@xds/core/Divider';
+import {useMediaQuery} from '@xds/core/hooks';
import {ThemeShowcaseStore} from '../../../../packages/cli/templates/pages/theme-showcase/page';
import {getThemeShowcaseContent} from './themeShowcaseContent';
import {buildPlaygroundHref} from './playgroundLink';
@@ -25,6 +26,7 @@ import {packages} from '../generated/packageRegistry';
import {themeObjects} from '../generated/themeRegistry';
import {templates} from '../generated/templateRegistry';
import {trackOpenPlayground, trackToggle} from '../lib/analytics';
+import {useThemeMode} from '../app/providers';
// Raw source of the theme-showcase page template (embedded as a string in
// the generated template registry). Used to prepopulate the playground's
@@ -81,7 +83,8 @@ function packageNameToSlug(packageName: string): string {
// sidebar is hidden via @media at the same breakpoint so the two
// surfaces don't double-render. Picked so the right pane keeps
// enough horizontal room for the themed preview's product grid.
-const SIDEBAR_BREAKPOINT = '@media (max-width: 900px)';
+const SIDEBAR_QUERY = '(max-width: 900px)';
+const SIDEBAR_BREAKPOINT = `@media ${SIDEBAR_QUERY}`;
// Fixed sidebar width — compact enough that the right pane gets the
// lion's share of horizontal space, wide enough to fit the longest
@@ -477,12 +480,25 @@ const PICKER_OVERRIDES: Record<
},
};
-function ThemeHeading({align = 'start'}: {align?: 'start' | 'center'}) {
+function ThemeHeading({
+ align = 'start',
+ isMobile = false,
+}: {
+ align?: 'start' | 'center';
+ isMobile?: boolean;
+}) {
const isCentered = align === 'center';
return (
<VStack gap={2} hAlign={isCentered ? 'center' : undefined}>
- <Heading level={1} type="display-3" justify={align}>
+ {/* display-3 in the desktop sidebar (display-2 wraps in the 260px
+ column); display-2 in the narrow layout to match /templates and
+ /components. Driven by the same SIDEBAR_QUERY mobile check the rest
+ of the component uses, not a separate CSS breakpoint. */}
+ <Heading
+ level={1}
+ type={isMobile ? 'display-2' : 'display-3'}
+ justify={align}>
Themes
</Heading>
<Text
@@ -507,7 +523,19 @@ interface ThemePackagePageProps {
}
export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
- const [mode, setMode] = useState<'light' | 'dark'>('light');
+ // Preview color mode. `siteMode` is the docsite's already-resolved concrete
+ // light/dark — the provider maps its default `system` to the OS preference
+ // (falling back to light on the first paint), so the preview never sees
+ // `system`. `localMode` is null until the user toggles the preview's own
+ // control; the effective mode falls through to `siteMode` until then, so
+ // opening /themes in dark mode shows the demos in dark mode without an effect.
+ const {mode: siteMode} = useThemeMode();
+ const [localMode, setLocalMode] = useState<'light' | 'dark' | null>(null);
+ const mode: 'light' | 'dark' = localMode ?? siteMode;
+
+ const handleToggleMode = useCallback(() => {
+ setLocalMode(mode === 'light' ? 'dark' : 'light');
+ }, [mode]);
// Selected theme — seeded once from the parent's `packageName`
// prop (the /themes page resolves it from the `?theme=<slug>`
// query param, or Neutral if absent), then user-mutable via the
@@ -525,6 +553,12 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
const carouselRef = useRef<HTMLDivElement>(null);
const [showMobileBar, setShowMobileBar] = useState(false);
+ // Narrow-viewport check — the same SIDEBAR_QUERY breakpoint that hides the
+ // sidebar and shows the mobile context block. Drives the heading's type so
+ // the JS render matches the layout swap (no parallel CSS breakpoint). Server
+ // default is desktop (false), matching the sidebar shown on first paint.
+ const isMobile = useMediaQuery(SIDEBAR_QUERY);
+
// Show the floating toolbar when the carousel scrolls out of view.
useEffect(() => {
const el = carouselRef.current;
@@ -651,12 +685,11 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
<Card variant="default" padding={0} xstyle={styles.sidebarCard}>
<VStack gap={4}>
{/* Hero block — page-level heading + description + CTAs.
- Heading uses display-3 instead of display-2 because
- the narrow sidebar column would wrap display-2 mid-
- word; CTAs stack vertically + full-width because the
- side-by-side hero treatment doesn't fit in 260px. */}
+ Heading is display-3 in this sidebar (display-2 wraps in the
+ 260px column); the narrow layout uses display-2 (see isMobile).
+ CTAs stack full-width. */}
<VStack gap={3}>
- <ThemeHeading />
+ <ThemeHeading isMobile={isMobile} />
{/* Action row — primary CTA takes the leading flex
space, mode toggle (icon-only) sits on the trailing
edge. Both belong here because they're page-level
@@ -692,7 +725,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
item: selectedPkgName,
value: next,
});
- setMode(next);
+ setLocalMode(next);
}}
/>
</HStack>
@@ -803,7 +836,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
label={modeToggleLabel}
tooltip={modeToggleLabel}
icon={modeToggleIcon}
- onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}
+ onClick={handleToggleMode}
/>
</div>
@@ -811,7 +844,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
Mirrors the sidebar's hero: heading, description, and
action buttons (Open in Playground + mode toggle). */}
<div {...stylex.props(styles.mobileContext)}>
- <ThemeHeading align="center" />
+ <ThemeHeading align="center" isMobile={isMobile} />
<HStack gap={2} vAlign="center">
<Button
variant="primary"
@@ -842,7 +875,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
item: selectedPkgName,
value: next,
});
- setMode(next);
+ setLocalMode(next);
}}
/>
</HStack>
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index 8f07caf8f3..06b7f90611 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -11,7 +11,7 @@ import {
Component,
type ReactNode,
} from 'react';
-import {getXDSComponent, resolveValue} from './resolveElements';
+import {getComponent, resolveValue} from './resolveElements';
import {Button} from '@xds/core/Button';
import {Card} from '@xds/core/Card';
import {Center} from '@xds/core/Center';
@@ -203,7 +203,7 @@ export function InteractivePreviewStage({
canControlOpenState?: boolean;
}) {
const [showCode, setShowCode] = useState(false);
- const Component = getXDSComponent(name);
+ const Component = getComponent(name);
const runtimeState = useMemo(
() =>
resolveValue(
@@ -218,7 +218,7 @@ export function InteractivePreviewStage({
// Sub-components that need a parent context provider declare it via
// `playground.wrapper`; wrap the previewed component in that parent.
const wrapper = playground?.wrapper ?? null;
- const WrapperComponent = wrapper ? getXDSComponent(wrapper.component) : null;
+ const WrapperComponent = wrapper ? getComponent(wrapper.component) : null;
const wrapperProps = useMemo(() => {
const resolved = wrapper?.props
? (resolveValue(wrapper.props) as Record<string, unknown>)