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.tsxindex 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 theside-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 flexspace, mode toggle (icon-only) sits on the trailingedge. 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 thehidden 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)}><XDSSelectorlabel="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 withthe selected theme, wrapped in a bordered, rounded card soit reads as a contained app surface against the docsitediff --git a/packages/cli/templates/pages/theme-showcase/page.tsx b/packages/cli/templates/pages/theme-showcase/page.tsxindex 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 (<divstyle={{minHeight: '100%',backgroundColor: 'var(--color-background-body)',}}>- <StorePreview images={images} />+ <StorePreview images={images} isMobile={isMobile} /><divstyle={{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}><XDSSelectableCardlabel="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}><XDSTextInputlabel="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