An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): add live theme preview pages (#1958)
Cindy Zhangc07e9952e2ee
diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.cssindex 49a3c812e3..209aa5ba79 100644--- a/apps/docsite/src/app/globals.css+++ b/apps/docsite/src/app/globals.css@@ -1,6 +1,9 @@@import "@xds/core/reset.css";@import "@xds/core/xds.css";@import "@xds/theme-default/theme.css";+@import "@xds/theme-neutral/theme.css";+@import "@xds/theme-daily/theme.css";+@import "@xds/theme-matcha/theme.css";/* StyleX app styles injected here. useCSSLayers.before declaresreset, xds-base, xds-theme so product styles always win. */diff --git a/apps/docsite/src/app/packages/[name]/page.tsx b/apps/docsite/src/app/packages/[name]/page.tsxindex de80bff1c5..76b0604a9a 100644--- a/apps/docsite/src/app/packages/[name]/page.tsx+++ b/apps/docsite/src/app/packages/[name]/page.tsx@@ -2,7 +2,7 @@* Page type: package* Adapts based on the package type:* - component-pkg (@xds/core): component grid from componentRegistry- * - theme-pkg (@xds/theme-*): theme preview + token info (stub)+ * - theme-pkg (@xds/theme-*): live theme preview with light/dark toggle* - generic (@xds/cli, etc.): README rendered via XDSMarkdown*/@@ -20,11 +20,55 @@ import {components,type ComponentEntry,} from '../../../generated/componentRegistry';+import {+ ThemePackagePage,+ type InstallStep,+} from '../../../components/ThemePackagePage';+import {defaultTheme} from '@xds/theme-default/built';+import {neutralTheme} from '@xds/theme-neutral/built';+import {dailyTheme} from '@xds/theme-daily/built';+import {matchaTheme} from '@xds/theme-matcha/built';+import type {XDSDefinedTheme} from '@xds/core/theme';function slugToPackageName(slug: string): string {return `@xds/${slug}`;}+const THEME_MAP: Record<string, XDSDefinedTheme> = {+ '@xds/theme-default': defaultTheme,+ '@xds/theme-neutral': neutralTheme,+ '@xds/theme-daily': dailyTheme,+ '@xds/theme-matcha': matchaTheme,+};++function getInstallSteps(pkgName: string): InstallStep[] {+ if (pkgName.includes('theme-')) {+ const shortName = pkgName.replace('@xds/theme-', '');+ const varName = shortName + 'Theme';+ return [+ {label: 'Install the theme', code: `npm install ${pkgName}`},+ {+ label: 'Import the built theme',+ code: `import {${varName}} from '${pkgName}/built';`,+ language: 'typescript',+ },+ {+ label: 'Wrap your app',+ code: `<XDSTheme theme={${varName}}>{children}</XDSTheme>`,+ language: 'tsx',+ },+ ];+ }+ return [+ {label: 'Install the package', code: `npm install ${pkgName}`},+ {+ label: 'Import a component',+ code: `import {...} from '${pkgName}/ComponentName';`,+ language: 'typescript',+ },+ ];+}+export function generateStaticParams() {return packages.map(p => ({name: p.name.replace('@xds/', '')}));}@@ -43,6 +87,24 @@ export default async function PackagePage({const isComponentPkg = pkg.name === '@xds/core';const pkgComponents = components[pkg.name] || [];+ if (isTheme) {+ const theme = THEME_MAP[pkg.name];+ if (theme) {+ return (+ <XDSSection maxWidth="lg" padding={6}>+ <ThemePackagePage+ name={pkg.name}+ description={pkg.description}+ version={pkg.version}+ readme={pkg.readme}+ installSteps={getInstallSteps(pkg.name)}+ theme={theme}+ />+ </XDSSection>+ );+ }+ }+return (<XDSSection maxWidth="lg" padding={6}><XDSVStack gap={6}>@@ -65,8 +127,6 @@ export default async function PackagePage({{/* Content — adapts by package type */}{isComponentPkg ? (<ComponentPackageContent components={pkgComponents} />- ) : isTheme ? (- <ThemePackageContent />) : (<GenericPackageContent readme={pkg.readme} />)}@@ -117,17 +177,6 @@ function ComponentPackageContent({);}-function ThemePackageContent() {- return (- <XDSVStack gap={4}>- {/* TODO: theme preview, token values, setup code from pipeline */}- <XDSText type="body" color="secondary">- Theme details coming soon.- </XDSText>- </XDSVStack>- );-}-function GenericPackageContent({readme}: {readme: string | null}) {if (!readme) {return (diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsxnew file mode 100644index 0000000000..dbb9707994--- /dev/null+++ b/apps/docsite/src/components/ThemePackagePage.tsx@@ -0,0 +1,112 @@+'use client';++import {useState} from 'react';+import stylex from '@stylexjs/stylex';+import {XDSText} from '@xds/core/Text';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSCard} from '@xds/core/Card';+import {XDSTheme} from '@xds/core/theme';+import type {XDSDefinedTheme} from '@xds/core/theme';+import {XDSMarkdown} from '@xds/core/Markdown';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSButton} from '@xds/core/Button';+import {XDSPopover} from '@xds/core/Popover';+import {ThemeShowcasePreview} from './ThemeShowcasePreview';++const styles = stylex.create({+ prose: {+ maxWidth: 800,+ marginInline: 'auto',+ width: '100%',+ },+ previewCard: {+ overflow: 'hidden',+ },+});++export interface InstallStep {+ label: string;+ code: string;+ language?: string;+}++interface ThemePackagePageProps {+ name: string;+ description?: string;+ version?: string;+ readme: string | null;+ installSteps: InstallStep[];+ theme: XDSDefinedTheme;+}++export function ThemePackagePage({+ name,+ description,+ version,+ readme,+ installSteps,+ theme,+}: ThemePackagePageProps) {+ const body = readme ? readme.replace(/^# .+\n+/, '') : null;+ const [mode, setMode] = useState<'light' | 'dark'>('light');++ return (+ <XDSVStack gap={8}>+ <XDSVStack gap={2} xstyle={styles.prose}>+ <XDSVStack gap={1}>+ <XDSHStack vAlign="center" hAlign="between">+ <XDSHStack gap={3} vAlign="end">+ <XDSText type="display-3">{name}</XDSText>+ {version && (+ <XDSText type="supporting" color="secondary">+ {version}+ </XDSText>+ )}+ </XDSHStack>+ <XDSPopover+ width={360}+ content={+ <XDSVStack gap={3}>+ {installSteps.map((step, i) => (+ <XDSVStack key={i} gap={1}>+ <XDSText type="body" weight="bold">+ {i + 1}. {step.label}+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock+ code={step.code}+ language={step.language ?? 'bash'}+ hasCopyButton+ />+ </XDSCard>+ </XDSVStack>+ ))}+ </XDSVStack>+ }>+ <XDSButton label="Install" variant="primary" />+ </XDSPopover>+ </XDSHStack>+ {description && (+ <XDSText type="body" color="secondary">+ {description}+ </XDSText>+ )}+ </XDSVStack>+ </XDSVStack>++ <XDSTheme theme={theme} mode={mode}>+ <XDSCard padding={0} variant="muted" xstyle={styles.previewCard}>+ <ThemeShowcasePreview mode={mode} onModeChange={setMode} />+ </XDSCard>+ </XDSTheme>++ {body && (+ <div {...stylex.props(styles.prose)}>+ <XDSMarkdown headingLevelStart={3} contentWidth={800}>+ {body}+ </XDSMarkdown>+ </div>+ )}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/components/ThemeShowcasePreview.tsx b/apps/docsite/src/components/ThemeShowcasePreview.tsxnew file mode 100644index 0000000000..2b6376a113--- /dev/null+++ b/apps/docsite/src/components/ThemeShowcasePreview.tsx@@ -0,0 +1,402 @@+'use client';++import {useState, useEffect, useRef} from 'react';+import stylex from '@stylexjs/stylex';+import {XDSText, XDSHeading} from '@xds/core/Text';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSButton} from '@xds/core/Button';+import {XDSCard} from '@xds/core/Card';+import {XDSCenter} from '@xds/core/Center';+import {XDSSection} from '@xds/core/Section';+import {XDSGrid} from '@xds/core/Grid';+import {XDSBadge} from '@xds/core/Badge';+import {XDSTable} from '@xds/core/Table';+import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSTopNav, XDSTopNavHeading} from '@xds/core/TopNav';+import {XDSRadioList, XDSRadioListItem} from '@xds/core/RadioList';+import {XDSList, XDSListItem} from '@xds/core/List';+import {XDSIcon} from '@xds/core/Icon';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSProgressBar} from '@xds/core/ProgressBar';+import {XDSSwitch} from '@xds/core/Switch';+import {XDSBanner} from '@xds/core/Banner';++const styles = stylex.create({+ productImage: {+ width: '100%',+ height: '100%',+ objectFit: 'cover' as const,+ },+ cardBody: {+ padding: 'var(--spacing-4)',+ },+ heroText: {+ textAlign: 'center' as const,+ maxWidth: 560,+ },+ content: {+ maxWidth: 960,+ marginInline: 'auto',+ },+ swatch: {+ width: 32,+ height: 32,+ borderRadius: 'var(--radius-element)',+ flexShrink: 0,+ },+ fontCard: {+ borderColor: 'transparent',+ },+ fontSample: {+ height: '100%',+ },+ fontSampleInner: {+ flex: 1,+ },+ componentCard: {+ borderColor: 'transparent',+ },+});++const PRODUCT_IMAGES = [+ 'https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=400&h=300&fit=crop',+ 'https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=400&h=300&fit=crop',+ 'https://images.unsplash.com/photo-1553062407-98eeb64c6a62?w=400&h=300&fit=crop',+];++const PRODUCTS = [+ {+ name: 'Minimalist Watch',+ description: 'Clean design meets everyday durability.',+ badge: 'New',+ badgeVariant: 'info' as const,+ },+ {+ name: 'Wireless Headphones',+ description: 'Immersive sound, all-day comfort.',+ badge: 'Popular',+ badgeVariant: 'success' as const,+ },+ {+ name: 'Leather Wallet',+ description: 'Handcrafted from full-grain leather.',+ badge: 'Limited',+ badgeVariant: 'warning' as const,+ },+];++const TABLE_DATA = [+ {+ name: 'Minimalist Watch',+ description: 'Stainless steel, sapphire crystal',+ price: '$189',+ stock: '42',+ },+ {+ name: 'Wireless Headphones',+ description: 'ANC, 30hr battery',+ price: '$249',+ stock: '128',+ },+ {+ name: 'Leather Wallet',+ description: 'Full-grain, RFID blocking',+ price: '$79',+ stock: '15',+ },+ {+ name: 'Canvas Backpack',+ description: 'Water-resistant, 25L',+ price: '$119',+ stock: '63',+ },+] as Record<string, unknown>[];++const COLOR_ROWS = [+ [+ 'var(--color-accent)',+ 'var(--color-accent-muted)',+ 'var(--color-neutral)',+ 'var(--color-background-surface)',+ 'var(--color-background-body)',+ ],+ [+ 'var(--color-success)',+ 'var(--color-error)',+ 'var(--color-warning)',+ 'var(--color-text-primary)',+ 'var(--color-text-secondary)',+ ],+];++function ColorSwatches({swatches}: {swatches: string[]}) {+ return (+ <XDSHStack gap={1}>+ {swatches.map(color => (+ <div+ key={color}+ {...stylex.props(styles.swatch)}+ style={{backgroundColor: color}}+ />+ ))}+ </XDSHStack>+ );+}++function FontLabel({cssVar, fallback}: {cssVar: string; fallback: string}) {+ const ref = useRef<HTMLSpanElement>(null);+ const [label, setLabel] = useState(fallback);++ useEffect(() => {+ if (!ref.current) return;+ const computed = getComputedStyle(ref.current)+ .getPropertyValue(cssVar)+ .trim();+ if (computed) {+ setLabel(computed.split(',')[0].replace(/['"]/g, '').trim());+ }+ }, [cssVar]);++ return (+ <span ref={ref}>+ <XDSText type="supporting" color="secondary">+ {label}+ </XDSText>+ </span>+ );+}++interface ThemeShowcasePreviewProps {+ mode: 'light' | 'dark';+ onModeChange: (mode: 'light' | 'dark') => void;+}++export function ThemeShowcasePreview({+ mode,+ onModeChange,+}: ThemeShowcasePreviewProps) {+ return (+ <XDSVStack gap={0}>+ <XDSTopNav+ label="Theme Preview"+ heading={<XDSTopNavHeading heading="Theme Preview" />}+ endContent={+ <XDSSwitch+ label={mode === 'dark' ? 'Dark' : 'Light'}+ value={mode === 'dark'}+ onChange={v => onModeChange(v ? 'dark' : 'light')}+ />+ }+ />++ <XDSSection padding={8}>+ <XDSVStack gap={10} xstyle={styles.content}>+ <XDSCenter>+ <XDSVStack gap={4} hAlign="center" xstyle={styles.heroText}>+ <XDSText type="display-3">+ Little joys,+ <br />+ everywhere you go+ </XDSText>+ <XDSText type="body" color="secondary">+ We believe the smallest details are the ones that matter most.+ Turn an ordinary day into something worth remembering.+ </XDSText>+ <XDSHStack gap={3} hAlign="center">+ <XDSButton label="Get started" variant="primary" href="#" />+ <XDSButton label="Learn more" variant="secondary" href="#" />+ </XDSHStack>+ </XDSVStack>+ </XDSCenter>++ <XDSGrid columns={3} gap={4}>+ {PRODUCTS.map((p, i) => (+ <XDSCard key={p.name} padding={0}>+ <XDSVStack gap={0}>+ <XDSAspectRatio ratio={4 / 3}>+ <img+ src={PRODUCT_IMAGES[i]}+ alt={p.name}+ {...stylex.props(styles.productImage)}+ />+ </XDSAspectRatio>+ <div {...stylex.props(styles.cardBody)}>+ <XDSVStack gap={2}>+ <XDSHStack>+ <XDSBadge label={p.badge} variant={p.badgeVariant} />+ </XDSHStack>+ <XDSHeading level={4}>{p.name}</XDSHeading>+ <XDSText type="supporting" color="secondary">+ {p.description}+ </XDSText>+ <XDSButton+ label="Learn more"+ variant="secondary"+ href="#"+ />+ </XDSVStack>+ </div>+ </XDSVStack>+ </XDSCard>+ ))}+ </XDSGrid>++ <XDSTable+ data={TABLE_DATA}+ columns={[+ {key: 'name', header: 'Name'},+ {key: 'description', header: 'Description'},+ {key: 'price', header: 'Price'},+ {key: 'stock', header: 'Stock'},+ ]}+ density="spacious"+ dividers="rows"+ hasHover+ />++ <ThemeShowcaseDetails />+ </XDSVStack>+ </XDSSection>+ </XDSVStack>+ );+}++function ThemeShowcaseDetails() {+ const [radioValue, setRadioValue] = useState('a');++ return (+ <XDSVStack gap={4}>+ <XDSGrid columns={2} gap={4}>+ <XDSCard padding={6} xstyle={styles.fontCard}>+ <XDSVStack gap={4}>+ <XDSText type="label" weight="bold">+ Colors+ </XDSText>+ {COLOR_ROWS.map((row, i) => (+ <ColorSwatches key={i} swatches={row} />+ ))}+ </XDSVStack>+ </XDSCard>++ <XDSCard padding={6} xstyle={styles.fontCard}>+ <XDSVStack gap={0} xstyle={styles.fontSample}>+ <XDSText type="label" weight="bold">+ Fonts+ </XDSText>+ <XDSHStack+ gap={8}+ hAlign="center"+ vAlign="center"+ xstyle={styles.fontSampleInner}>+ <XDSVStack gap={2} hAlign="center">+ <XDSText+ type="display-1"+ style={{fontFamily: 'var(--font-family-body, system-ui)'}}>+ Aa+ </XDSText>+ <FontLabel cssVar="--font-family-body" fallback="Body" />+ </XDSVStack>+ <XDSVStack gap={2} hAlign="center">+ <XDSText+ type="display-1"+ style={{fontFamily: 'var(--font-family-code, monospace)'}}>+ Aa+ </XDSText>+ <FontLabel cssVar="--font-family-code" fallback="Code" />+ </XDSVStack>+ </XDSHStack>+ </XDSVStack>+ </XDSCard>+ </XDSGrid>++ <XDSCard padding={6} xstyle={styles.componentCard}>+ <XDSGrid columns={2} gap={8}>+ <XDSVStack gap={4}>+ <XDSText type="label" weight="bold">+ Components+ </XDSText>+ <XDSHStack gap={2}>+ <XDSButton label="Primary" variant="primary" size="sm" href="#" />+ <XDSButton+ label="Secondary"+ variant="secondary"+ size="sm"+ href="#"+ />+ <XDSButton label="Ghost" variant="ghost" size="sm" href="#" />+ </XDSHStack>+ <XDSHStack gap={2}>+ <XDSBadge label="Badge" />+ <XDSBadge label="Info" variant="info" />+ <XDSBadge label="Success" variant="success" />+ <XDSBadge label="Warning" variant="warning" />+ <XDSBadge label="Error" variant="error" />+ </XDSHStack>+ <XDSGrid columns={2} gap={4}>+ <XDSVStack gap={2}>+ <XDSText type="supporting" weight="bold">+ Label+ </XDSText>+ <XDSRadioList+ label="Options"+ value={radioValue}+ onChange={setRadioValue}>+ <XDSRadioListItem value="a" label="Option A" />+ <XDSRadioListItem value="b" label="Option B" />+ <XDSRadioListItem value="c" label="Option C" />+ </XDSRadioList>+ </XDSVStack>+ <XDSVStack gap={2}>+ <XDSText type="supporting" weight="bold">+ List Header+ </XDSText>+ <XDSList density="compact">+ <XDSListItem+ label="Notifications"+ startContent={<XDSIcon icon="info" size="sm" />}+ />+ <XDSListItem+ label="Privacy"+ startContent={<XDSIcon icon="warning" size="sm" />}+ />+ <XDSListItem+ label="Security"+ startContent={<XDSIcon icon="check" size="sm" />}+ />+ </XDSList>+ </XDSVStack>+ </XDSGrid>+ <XDSCard padding={4}>+ <XDSVStack gap={2}>+ <XDSHeading level={4}>Card Title</XDSHeading>+ <XDSText type="body" color="secondary">+ A flexible surface for grouping related content and actions.+ </XDSText>+ <XDSButton+ label="Action"+ variant="secondary"+ size="sm"+ href="#"+ />+ </XDSVStack>+ </XDSCard>+ </XDSVStack>++ <XDSVStack gap={4}>+ <XDSTextInput+ label="Example"+ placeholder="Type something..."+ value=""+ onChange={() => {}}+ />+ <XDSProgressBar value={75} label="Progress" />+ <XDSSwitch label="Toggle" value={true} onChange={() => {}} />+ <XDSBanner status="success" title="Banner Title" />+ <XDSBanner status="warning" title="Banner Title" />+ <XDSBanner status="error" title="Banner Title" />+ </XDSVStack>+ </XDSGrid>+ </XDSCard>+ </XDSVStack>+ );+}