Skip to content

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

TypeScript

fix(docsite): improve theme page mobile UX (#2673)

Cindy Zhang4aff9e40a881
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index 47400c71c5..c8278134bd 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -2,7 +2,7 @@
'use client';
-import {useCallback, useMemo, useState} from 'react';
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {usePathname, useRouter} from 'next/navigation';
@@ -10,6 +10,7 @@ import {Sun, Moon} from 'lucide-react';
import {XDSHStack, XDSVStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSCard} from '@xds/core/Card';
+import {XDSCarousel} from '@xds/core/Carousel';
import {XDSTheme} from '@xds/core/theme';
import type {XDSDefinedTheme} from '@xds/core/theme';
import {XDSButton} from '@xds/core/Button';
@@ -145,6 +146,7 @@ const styles = stylex.create({
rightColumn: {
flex: '1 1 0',
minWidth: 0,
+ width: '100%',
display: 'flex',
flexDirection: 'column' as const,
gap: 'var(--spacing-8)',
@@ -341,20 +343,18 @@ const styles = stylex.create({
position: 'relative' as const,
zIndex: 1,
},
+ mobileThemeCardLabel: {
+ fontSize: 24,
+ },
// Mobile-only floating toolbar that replaces the sidebar at
// narrow viewports. position:fixed so it stays pinned to the
// bottom of the viewport as the user scrolls the right pane;
- // horizontally centered via left:50% + translateX(-50%). Holds
- // the theme dropdown + mode toggle in a single horizontal row.
- // Visual chrome (pill border, card background, --shadow-high)
- // matches a floating action toolbar, since it's no longer
- // inline with the page surface — it needs to read as a
- // detached control sitting above the content.
- // width:fit-content so the pill hugs its contents rather than
- // stretching across the viewport. zIndex:100 keeps it above
- // page content; PreviewStage's full-screen overlay uses 50,
- // so this still loses to that (intentional — when the
- // playground takes over, the toolbar shouldn't poke through).
+ // horizontally centered with inset + auto margins instead of
+ // transform so CSS-anchor-positioned popovers inside it (like
+ // XDSSelector's menu) anchor to the visible trigger location.
+ // Floating toolbar — appears when the theme carousel scrolls out of
+ // view. Hidden by default (opacity:0, pointer-events:none) and becomes
+ // visible when the `data-visible` attribute is set.
mobileBar: {
display: 'none',
[SIDEBAR_BREAKPOINT]: {
@@ -371,11 +371,22 @@ const styles = stylex.create({
boxShadow: 'var(--shadow-high)',
position: 'fixed' as const,
bottom: 'var(--spacing-4)',
- left: '50%',
- transform: 'translateX(-50%)',
+ left: 0,
+ right: 0,
+ marginInline: 'auto',
zIndex: 100,
width: 'fit-content',
maxWidth: `calc(100vw - var(--spacing-4) * 2)`,
+ opacity: 0,
+ pointerEvents: 'none' as const,
+ transition: 'opacity 0.2s ease',
+ },
+ },
+ // Visible state for the floating toolbar.
+ mobileBarVisible: {
+ [SIDEBAR_BREAKPOINT]: {
+ opacity: 1,
+ pointerEvents: 'auto' as const,
},
},
// Mobile selector — fixed minimum so the dropdown trigger has
@@ -385,6 +396,22 @@ const styles = stylex.create({
mobileSelector: {
minWidth: 160,
},
+ // Mobile theme carousel — horizontal row of theme cards. XDSCarousel
+ // owns scrolling, snapping, overflow affordances, and scrollbar behavior;
+ // this wrapper style only controls breakpoint visibility.
+ mobileCarousel: {
+ display: 'none',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'flex',
+ width: '100%',
+ },
+ },
+ // Individual card in the mobile carousel — fixed width so cards
+ // are uniformly sized and scroll-snappable.
+ mobileCarouselCard: {
+ flexShrink: 0,
+ width: 140,
+ },
// Showcase card — clips the theme-showcase template's own
// backgrounds (top nav, sections) to the card's rounded corners.
// The card's default variant supplies the border + radius; the
@@ -395,10 +422,25 @@ const styles = stylex.create({
// Caps the showcase at the site's "wide content" max-width (1200px,
// matching home-page showcases / docs index) and centers it so it
// doesn't run viewport-edge to viewport-edge on very wide screens.
+ // overflow:hidden clips any template content that exceeds the
+ // available width on mobile (e.g. inventory filter rows, tables).
showcaseBlock: {
width: '100%',
maxWidth: 1200,
marginInline: 'auto',
+ overflow: 'hidden',
+ borderRadius: 'var(--radius-container)',
+ },
+ // Mobile-only context heading — shown above the preview at narrow
+ // viewports. Includes the heading, description, and action row
+ // (Open in Playground + mode toggle) mirroring the sidebar's hero.
+ mobileContext: {
+ display: 'none',
+ [SIDEBAR_BREAKPOINT]: {
+ display: 'flex',
+ flexDirection: 'column' as const,
+ gap: 'var(--spacing-3)',
+ },
},
});
@@ -435,6 +477,29 @@ const PICKER_OVERRIDES: Record<
},
};
+function ThemeHeading({align = 'start'}: {align?: 'start' | 'center'}) {
+ const isCentered = align === 'center';
+
+ return (
+ <XDSVStack gap={2} hAlign={isCentered ? 'center' : undefined}>
+ <XDSHeading level={1} type="display-3" justify={align}>
+ Themes
+ </XDSHeading>
+ <XDSText
+ type="body"
+ color="secondary"
+ display={isCentered ? 'block' : 'inline'}
+ justify={align}>
+ Preview each theme, then start from one and make it your own.{' '}
+ <XDSLink type="body" color="secondary" href="/docs/theme" hasUnderline>
+ Learn how theming works
+ </XDSLink>
+ .
+ </XDSText>
+ </XDSVStack>
+ );
+}
+
interface ThemePackagePageProps {
/** Full npm package name — seeds the initial selected theme. */
packageName: string;
@@ -455,6 +520,27 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
const router = useRouter();
const pathname = usePathname();
+ // Ref for the mobile theme carousel — observed by IntersectionObserver
+ // to toggle the floating toolbar visibility.
+ const carouselRef = useRef<HTMLDivElement>(null);
+ const [showMobileBar, setShowMobileBar] = useState(false);
+
+ // Show the floating toolbar when the carousel scrolls out of view.
+ useEffect(() => {
+ const el = carouselRef.current;
+ if (!el) {
+ return;
+ }
+ const observer = new IntersectionObserver(
+ ([entry]) => {
+ setShowMobileBar(!entry.isIntersecting);
+ },
+ {threshold: 0},
+ );
+ observer.observe(el);
+ return () => observer.disconnect();
+ }, []);
+
// Sync the URL with the active picker selection so it can be
// copied, bookmarked, reloaded, or shared. The default theme
// (DEFAULT_THEME_PACKAGE) renders as the bare `/themes` URL —
@@ -567,22 +653,7 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
word; CTAs stack vertically + full-width because the
side-by-side hero treatment doesn't fit in 260px. */}
<XDSVStack gap={3}>
- <XDSVStack gap={2}>
- <XDSHeading level={1} type="display-3">
- Themes
- </XDSHeading>
- <XDSText type="body" color="secondary">
- Preview each theme, then start from one and make it your own.{' '}
- <XDSLink
- type="body"
- color="secondary"
- href="/docs/theme"
- hasUnderline>
- Learn how theming works
- </XDSLink>
- .
- </XDSText>
- </XDSVStack>
+ <ThemeHeading />
{/* 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
@@ -702,14 +773,15 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
bar lives at the top of this column and takes over for the
hidden sidebar at narrow viewports. */}
<div {...stylex.props(styles.rightColumn)}>
- {/* Mobile bar — replaces the sidebar at narrow viewports.
- Renders as a floating pill pinned to the bottom of the
- viewport (position:fixed) so the theme switcher stays
- reachable while the user scrolls the long preview pane.
- Stays in the DOM here (rather than at <body> root) so
- it co-locates with the state it controls; position:fixed
- takes it out of the right column's flex flow regardless. */}
- <div {...stylex.props(styles.mobileBar)}>
+ {/* Mobile floating toolbar — hidden until the carousel scrolls
+ out of view, then animates in from below. Contains the theme
+ selector dropdown + mode toggle so users always have access
+ to theme switching as they scroll the long preview. */}
+ <div
+ {...stylex.props(
+ styles.mobileBar,
+ showMobileBar && styles.mobileBarVisible,
+ )}>
<div {...stylex.props(styles.mobileSelector)}>
<XDSSelector
label="Theme"
@@ -731,6 +803,108 @@ export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {
/>
</div>
+ {/* Mobile context heading — visible only at narrow viewports.
+ Mirrors the sidebar's hero: heading, description, and
+ action buttons (Open in Playground + mode toggle). */}
+ <div {...stylex.props(styles.mobileContext)}>
+ <ThemeHeading align="center" />
+ <XDSHStack gap={2} vAlign="center">
+ <XDSButton
+ variant="primary"
+ size="lg"
+ label="Open in Playground"
+ href={customizeHref}
+ xstyle={styles.heroPrimaryButton}
+ onClick={() => {
+ trackOpenPlayground({
+ page: 'themes',
+ item: selectedPkgName,
+ source: 'theme-showcase',
+ });
+ }}
+ />
+ <XDSButton
+ variant="ghost"
+ size="lg"
+ isIconOnly
+ label={modeToggleLabel}
+ tooltip={modeToggleLabel}
+ icon={modeToggleIcon}
+ onClick={() => {
+ const next = mode === 'light' ? 'dark' : 'light';
+ trackToggle({
+ page: 'themes',
+ target: 'mode',
+ item: selectedPkgName,
+ value: next,
+ });
+ setMode(next);
+ }}
+ />
+ </XDSHStack>
+ </div>
+
+ {/* Mobile theme carousel — horizontal row of theme cards.
+ When this scrolls out of view, the floating toolbar appears.
+ XDSCarousel owns scroll behavior and snap affordances. */}
+ <XDSCarousel
+ ref={carouselRef}
+ gap={3}
+ hasButtons={false}
+ hasSnap
+ aria-label="Themes"
+ xstyle={styles.mobileCarousel}>
+ {themePackages.map(pkg => {
+ const cardTheme = themeObjects[pkg.name];
+ const isActive = pkg.name === selectedPkgName;
+ const label = themeLabel(pkg.displayName) || pkg.displayName;
+ const override = PICKER_OVERRIDES[pkg.name];
+ return (
+ <div key={pkg.name} {...stylex.props(styles.mobileCarouselCard)}>
+ <XDSSelectableCard
+ label={`Preview ${label} theme`}
+ isSelected={isActive}
+ onChange={() => handleSelectPkg(pkg.name)}
+ padding={0}
+ variant="transparent">
+ {cardTheme ? (
+ <XDSTheme theme={cardTheme} mode="light">
+ <div
+ {...stylex.props(
+ styles.themedSurface,
+ override?.surface ?? false,
+ )}>
+ <XDSText
+ type="display-3"
+ weight="bold"
+ xstyle={[
+ styles.themeCardLabel,
+ styles.mobileThemeCardLabel,
+ override?.label ?? false,
+ ]}>
+ {label}
+ </XDSText>
+ </div>
+ </XDSTheme>
+ ) : (
+ <div {...stylex.props(styles.themedSurface)}>
+ <XDSText
+ type="display-3"
+ weight="bold"
+ xstyle={[
+ styles.themeCardLabel,
+ styles.mobileThemeCardLabel,
+ ]}>
+ {label}
+ </XDSText>
+ </div>
+ )}
+ </XDSSelectableCard>
+ </div>
+ );
+ })}
+ </XDSCarousel>
+
{/* Themed preview — the theme-showcase template rendered with
the selected theme, wrapped in a bordered, rounded card so
it reads as a contained app surface against the docsite
diff --git a/packages/cli/templates/pages/theme-showcase/page.tsx b/packages/cli/templates/pages/theme-showcase/page.tsx
index 7fd50e92f8..0fe8afb1b8 100644
--- a/packages/cli/templates/pages/theme-showcase/page.tsx
+++ b/packages/cli/templates/pages/theme-showcase/page.tsx
@@ -25,6 +25,7 @@ import {
} from 'lucide-react';
import {XDSText, XDSHeading} from '@xds/core/Text';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {useXDSAppShellMobile} from '@xds/core/AppShell';
import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSButton} from '@xds/core/Button';
@@ -44,6 +45,7 @@ import {XDSCenter} from '@xds/core/Center';
import {XDSSection} from '@xds/core/Section';
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSNumberInput} from '@xds/core/NumberInput';
+import {XDSOverflowList} from '@xds/core/OverflowList';
import {XDSTopNav, XDSTopNavHeading, XDSTopNavItem} from '@xds/core/TopNav';
import {
XDSChatComposer,
@@ -73,12 +75,6 @@ const styles = stylex.create({
textAlign: 'center',
wordBreak: 'break-word',
},
- fullSpanAtNarrow: {
- gridColumn: {
- default: null,
- '@media (max-width: 1024px)': '1 / -1',
- },
- },
inventoryCard: {
backgroundColor: 'var(--color-background-surface)',
color: 'var(--color-text-primary)',
@@ -92,6 +88,7 @@ const styles = stylex.create({
paddingBlock: 'var(--spacing-4)',
paddingInline: 'var(--spacing-6)',
width: '100%',
+ overflowX: 'auto' as const,
},
searchInput: {
flex: 1,
@@ -132,6 +129,7 @@ const styles = stylex.create({
content: {
maxWidth: 960,
marginInline: 'auto',
+ minWidth: 0,
},
contentFluid: {
maxWidth: 880,
@@ -294,48 +292,63 @@ const PREVIEW_IMAGES: Record<string, string> = {
export default function ThemeShowcase() {
const images: Record<string, string> = PREVIEW_IMAGES;
+ const {isMobile} = useXDSAppShellMobile();
return (
<div
style={{
minHeight: '100%',
backgroundColor: 'var(--color-background-body)',
}}>
- <StorePreview images={images} />
+ <StorePreview images={images} isMobile={isMobile} />
<div
style={{
padding: 'var(--spacing-6)',
backgroundColor: 'var(--color-background-surface)',
}}>
- <CardShowcase images={images} />
+ <CardShowcase images={images} isMobile={isMobile} />
</div>
</div>
);
}
-function CardShowcase({images}: {images: Record<string, string>}) {
+function CardShowcase({
+ images,
+ isMobile,
+}: {
+ images: Record<string, string>;
+ isMobile: boolean;
+}) {
+ const columns = isMobile ? 1 : ({minWidth: 200, repeat: 'fit'} as const);
+
return (
<XDSVStack gap={8}>
- <XDSGrid columns={{minWidth: 200, repeat: 'fit'}} gap={4}>
- <XDSGridSpan columns={1} xstyle={styles.fullSpanAtNarrow}>
- <CheckoutCard />
+ <XDSGrid columns={columns} gap={4}>
+ <XDSGridSpan columns={1}>
+ <CheckoutCard isMobile={isMobile} />
</XDSGridSpan>
- <XDSGridSpan columns={2} xstyle={styles.fullSpanAtNarrow}>
+ <XDSGridSpan columns={isMobile ? 1 : 2}>
<ChatCard />
</XDSGridSpan>
</XDSGrid>
- <XDSGrid columns={{minWidth: 200, repeat: 'fit'}} gap={4}>
- <XDSGridSpan columns={3} xstyle={styles.fullSpanAtNarrow}>
+ <XDSGrid columns={columns} gap={4}>
+ <XDSGridSpan columns={isMobile ? 1 : 3}>
<InventoryCard images={images} />
</XDSGridSpan>
- <XDSGridSpan columns={1} xstyle={styles.fullSpanAtNarrow}>
- <LatestActivityCard />
+ <XDSGridSpan columns={1}>
+ <LatestActivityCard isMobile={isMobile} />
</XDSGridSpan>
</XDSGrid>
</XDSVStack>
);
}
-function StorePreview({images}: {images: Record<string, string>}) {
+function StorePreview({
+ images,
+ isMobile,
+}: {
+ images: Record<string, string>;
+ isMobile: boolean;
+}) {
return (
<div data-theme-preview="true">
<XDSVStack gap={0}>
@@ -343,12 +356,14 @@ function StorePreview({images}: {images: Record<string, string>}) {
label="Theme preview navigation"
heading={<XDSTopNavHeading heading="Studio" />}
centerContent={
- <>
- <XDSTopNavItem label="Shop" href="#" isSelected />
- <XDSTopNavItem label="New In" href="#" />
- <XDSTopNavItem label="Stories" href="#" />
- <XDSTopNavItem label="Help" href="#" />
- </>
+ isMobile ? undefined : (
+ <>
+ <XDSTopNavItem label="Shop" href="#" isSelected />
+ <XDSTopNavItem label="New In" href="#" />
+ <XDSTopNavItem label="Stories" href="#" />
+ <XDSTopNavItem label="Help" href="#" />
+ </>
+ )
}
endContent={
<XDSHStack gap={2} vAlign="center">
@@ -383,7 +398,7 @@ function StorePreview({images}: {images: Record<string, string>}) {
}
/>
- <XDSSection padding={8} variant="transparent">
+ <XDSSection padding={6} variant="transparent">
<XDSVStack gap={10} xstyle={[styles.content, styles.contentFluid]}>
<XDSCenter>
<XDSVStack gap={4} hAlign="center" xstyle={styles.heroText}>
@@ -399,7 +414,7 @@ function StorePreview({images}: {images: Record<string, string>}) {
</XDSVStack>
</XDSCenter>
- <XDSGrid columns={{minWidth: 240}} gap={4}>
+ <XDSGrid columns={isMobile ? 1 : {minWidth: 200}} gap={4}>
{PRODUCTS.map((p, i) => (
<XDSCard key={p.name} padding={0} height="100%">
<XDSVStack gap={0} xstyle={styles.cardStack}>
@@ -458,7 +473,7 @@ function StorePreview({images}: {images: Record<string, string>}) {
);
}
-function CheckoutCard() {
+function CheckoutCard({isMobile}: {isMobile: boolean}) {
return (
<XDSCard padding={5} xstyle={styles.card}>
<XDSVStack gap={4} xstyle={styles.checkoutStack}>
@@ -514,7 +529,7 @@ function CheckoutCard() {
<XDSText type="supporting" weight="bold">
Payment method
</XDSText>
- <XDSGrid columns={{minWidth: 70, max: 3}} gap={2}>
+ <XDSGrid columns={isMobile ? 1 : {minWidth: 70, max: 3}} gap={2}>
<XDSSelectableCard
label="Pay with card"
isSelected={true}
@@ -572,7 +587,7 @@ function CheckoutCard() {
size="lg"
/>
- <XDSGrid columns={{minWidth: 90, max: 2}} gap={2}>
+ <XDSGrid columns={isMobile ? 1 : {minWidth: 90, max: 2}} gap={2}>
<XDSTextInput
label="Expiry"
placeholder="MM / YY"
@@ -839,7 +854,7 @@ function formatAmount(amount: number): string {
return sign + '$' + Math.abs(amount).toLocaleString();
}
-function LatestActivityCard() {
+function LatestActivityCard({isMobile}: {isMobile: boolean}) {
return (
<XDSCard padding={5} xstyle={styles.activityCard}>
<XDSVStack gap={4} xstyle={styles.activityCardStack}>
@@ -858,7 +873,7 @@ function LatestActivityCard() {
</div>
</XDSVStack>
- <XDSGrid columns={2} gap={3}>
+ <XDSGrid columns={isMobile ? 1 : 2} gap={3}>
<XDSVStack gap={0}>
<span style={inlineStyles.kpiValue}>18K</span>
<XDSText type="supporting" color="secondary">
@@ -1094,50 +1109,61 @@ function InventoryCard({images}: {images: Record<string, string>}) {
startIcon={<Search size={16} />}
xstyle={styles.searchInput}
/>
- <XDSSelector
- label="Categories"
- isLabelHidden
- placeholder="Categories"
- size="sm"
- startIcon={<Folder size={16} />}
- value={undefined}
- onChange={() => {}}
- options={['Wearables', 'Audio', 'Bags', 'Drinkware', 'Home']}
- />
- <XDSSelector
- label="Locations"
- isLabelHidden
- placeholder="Locations"
- size="sm"
- startIcon={<MapPin size={16} />}
- value={undefined}
- onChange={() => {}}
- options={[
- 'Aisle 1',
- 'Aisle 2',
- 'Aisle 3',
- 'Aisle 4',
- 'Aisle 5',
- 'Aisle 6',
- ]}
- />
- <XDSSelector
- label="Tags"
- isLabelHidden
- placeholder="Tags"
- size="sm"
- startIcon={<Tag size={16} />}
- value={undefined}
- onChange={() => {}}
- options={[
- 'New',
- 'Popular',
- 'Limited',
- 'Leather',
- 'Drinkware',
- 'Home',
- ]}
- />
+ <XDSOverflowList
+ gap={2}
+ overflowRenderer={() => (
+ <XDSButton
+ label="Filters"
+ variant="ghost"
+ size="sm"
+ icon={<Tag size={16} />}
+ />
+ )}>
+ <XDSSelector
+ label="Categories"
+ isLabelHidden
+ placeholder="Categories"
+ size="sm"
+ startIcon={<Folder size={16} />}
+ value={undefined}
+ onChange={() => {}}
+ options={['Wearables', 'Audio', 'Bags', 'Drinkware', 'Home']}
+ />
+ <XDSSelector
+ label="Locations"
+ isLabelHidden
+ placeholder="Locations"
+ size="sm"
+ startIcon={<MapPin size={16} />}
+ value={undefined}
+ onChange={() => {}}
+ options={[
+ 'Aisle 1',
+ 'Aisle 2',
+ 'Aisle 3',
+ 'Aisle 4',
+ 'Aisle 5',
+ 'Aisle 6',
+ ]}
+ />
+ <XDSSelector
+ label="Tags"
+ isLabelHidden
+ placeholder="Tags"
+ size="sm"
+ startIcon={<Tag size={16} />}
+ value={undefined}
+ onChange={() => {}}
+ options={[
+ 'New',
+ 'Popular',
+ 'Limited',
+ 'Leather',
+ 'Drinkware',
+ 'Home',
+ ]}
+ />
+ </XDSOverflowList>
</XDSHStack>
<XDSHStack gap={1} vAlign="center">
<XDSButton