An open source design system that's fully customizable and agent ready
TypeScript
refactor(documentation): rewrite template for XDS purity (#1485)
rubyycheungde82229332f4
diff --git a/packages/cli/templates/pages/documentation/page.tsx b/packages/cli/templates/pages/documentation/page.tsxindex c197beb90c..37b9af8354 100644--- a/packages/cli/templates/pages/documentation/page.tsx+++ b/packages/cli/templates/pages/documentation/page.tsx@@ -1,9 +1,17 @@'use client';-import {useState} from 'react';+import {useState, useMemo} from 'react';import * as stylex from '@stylexjs/stylex';+import {XDSAppShell} from '@xds/core/AppShell';+import {+ XDSSideNav,+ XDSSideNavHeading,+ XDSSideNavItem,+ XDSSideNavSection,+} from '@xds/core/SideNav';import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSButton} from '@xds/core/Button';+import {XDSIconButton} from '@xds/core/IconButton';import {XDSCard} from '@xds/core/Card';import {XDSDropdownMenu} from '@xds/core/DropdownMenu';import {XDSAvatar} from '@xds/core/Avatar';@@ -13,215 +21,31 @@ import {XDSList, XDSListItem} from '@xds/core/List';import {XDSBanner} from '@xds/core/Banner';import {XDSCodeBlock} from '@xds/core/CodeBlock';import {XDSTabList, XDSTab} from '@xds/core/TabList';-import {XDSHStack} from '@xds/core/Stack';+import {XDSHStack, XDSVStack, XDSStackItem} from '@xds/core/Stack';import {XDSDialog, XDSDialogHeader} from '@xds/core/Dialog';import {XDSDivider} from '@xds/core/Divider';import {XDSTooltip} from '@xds/core/Tooltip';import {XDSTable, pixel} from '@xds/core/Table';+import {XDSIcon} from '@xds/core/Icon';+import {XDSSection} from '@xds/core/Section';+import {XDSCenter} from '@xds/core/Center';+import {XDSGrid} from '@xds/core/Grid';import {- borderVars,- colorVars,- spacingVars,-} from '@xds/core/theme/tokens.stylex';+ ArrowTopRightOnSquareIcon,+ ArrowsPointingOutIcon,+ SparklesIcon,+ ClipboardDocumentIcon,+ PlusIcon,+ ChevronDownIcon,+} from '@heroicons/react/24/outline';-const cellStyles = stylex.create({- wrap: {- whiteSpace: 'normal',- },- tabListFlush: {- marginLeft: `calc(-1 * ${spacingVars['--spacing-3']})`,- },- mutedCardBorder: {- borderWidth: borderVars['--border-width'],- borderStyle: 'solid',- borderColor: colorVars['--color-border-emphasized'],- },- dividerSpacing: {- paddingBottom: spacingVars['--spacing-12'],- },- sectionSpacing: {- marginBottom: spacingVars['--spacing-12'],- },- tabsContainer: {- backgroundColor: colorVars['--color-background-muted'],- borderTopWidth: borderVars['--border-width'],- borderTopStyle: 'solid',- borderTopColor: colorVars['--color-border'],- paddingInline: spacingVars['--spacing-4'],- paddingTop: spacingVars['--spacing-2'],- paddingBottom: spacingVars['--spacing-4'],- },- tabContent: {- paddingTop: spacingVars['--spacing-3'],- },- previewArea: {- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- minHeight: '280px',- paddingBlock: spacingVars['--spacing-8'],- paddingInline: spacingVars['--spacing-8'],- },- heroPreview: {- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- minHeight: '360px',- },- cardHeader: {- paddingInline: spacingVars['--spacing-4'],- paddingBlock: spacingVars['--spacing-3'],- },- narrowContent: {- maxWidth: '640px',- marginInline: 'auto',- },- wideContent: {- maxWidth: '960px',- marginInline: 'auto',- },- headerSpacing: {- marginBottom: spacingVars['--spacing-2'],- },- subheaderSpacing: {- marginBottom: spacingVars['--spacing-8'],- },- usageTextSpacing: {- marginTop: spacingVars['--spacing-3'],- },- bestPracticesSpacing: {- marginTop: spacingVars['--spacing-6'],- },- tableSpacing: {- marginTop: spacingVars['--spacing-4'],- },- examplesTextSpacing: {- marginTop: spacingVars['--spacing-2'],- },- exampleCardsContainer: {- display: 'flex',- flexDirection: 'column',- gap: spacingVars['--spacing-8'],- marginTop: spacingVars['--spacing-6'],- },- flexGrow: {- flexGrow: 1,- },+const styles = stylex.create({+ whiteSpaceNormal: {whiteSpace: 'normal'},+ tabListFlush: {marginInlineStart: '-12px'},+ narrowContent: {maxWidth: 640},+ fullWidth: {width: '100%'},});-// ----------------------------------------------------------------------------// Icons (Lucide-style inline SVGs)-// -----------------------------------------------------------------------------const ExternalLinkIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />- <polyline points="15 3 21 3 21 9" />- <line x1="10" y1="14" x2="21" y2="3" />- </svg>-);--const MaximizeIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <path d="M8 3H5a2 2 0 0 0-2 2v3" />- <path d="M21 8V5a2 2 0 0 0-2-2h-3" />- <path d="M3 16v3a2 2 0 0 0 2 2h3" />- <path d="M16 21h3a2 2 0 0 0 2-2v-3" />- </svg>-);--const SparklesIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <path d="m12 3-1.912 5.813a2 2 0 0 1-1.275 1.275L3 12l5.813 1.912a2 2 0 0 1 1.275 1.275L12 21l1.912-5.813a2 2 0 0 1 1.275-1.275L21 12l-5.813-1.912a2 2 0 0 1-1.275-1.275L12 3Z" />- <path d="M5 3v4" />- <path d="M19 17v4" />- <path d="M3 5h4" />- <path d="M17 19h4" />- </svg>-);--const CopyIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />- <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />- </svg>-);--const PlusIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <path d="M12 5v14" />- <path d="M5 12h14" />- </svg>-);--const ChevronDownIcon = (props: React.SVGProps<SVGSVGElement>) => (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth={2}- strokeLinecap="round"- strokeLinejoin="round"- {...props}>- <path d="m6 9 6 6 6-6" />- </svg>-);--// ----------------------------------------------------------------------------// SectionLabel — sidebar category header-// -----------------------------------------------------------------------------function SectionLabel({label}: {label: string}) {- return (- <div- style={{- textTransform: 'uppercase' as const,- letterSpacing: '0.05em',- padding: '12px 8px 4px',- margin: 0,- }}>- <XDSText type="supporting" weight="semibold" color="secondary">- {label}- </XDSText>- </div>- );-}-// ---------------------------------------------------------------------------// DialogPreview — stateful dialog preview for component previews// ---------------------------------------------------------------------------@@ -229,10 +53,8 @@ function SectionLabel({label}: {label: string}) {function DialogPreview() {const [isOpen, setIsOpen] = useState(false);return (- <div>- <div style={{marginBottom: 16}}>- <XDSHeading level={3}>Dialog</XDSHeading>- </div>+ <XDSVStack gap={3}>+ <XDSHeading level={3}>Dialog</XDSHeading><XDSButtonlabel="Open Dialog"variant="primary"@@ -240,14 +62,14 @@ function DialogPreview() {/><XDSDialog isOpen={isOpen} onOpenChange={setIsOpen}><XDSDialogHeader title="Example Dialog" onOpenChange={setIsOpen} />- <div style={{padding: 16}}>+ <XDSSection padding={4}><XDSText type="body">This is an example dialog. Dialogs are used to require user actionor display important information that needs acknowledgment.</XDSText>- </div>+ </XDSSection></XDSDialog>- </div>+ </XDSVStack>);}@@ -752,26 +574,266 @@ function getComponentDocs(key: string) {}// ----------------------------------------------------------------------------// Main component+// Sub-views// ----------------------------------------------------------------------------export default function DocumentationPage() {- const [activeNav, setActiveNav] = useState('button');- const [selectedComponent, setSelectedComponent] = useState<string | null>(- null,+function OverviewView({+ onSelectComponent,+}: {+ onSelectComponent: (key: string) => void;+}) {+ return (+ <XDSSection padding={8} maxWidth={1200} xstyle={styles.fullWidth}>+ <XDSVStack gap={10}>+ {/* Hero banner */}+ <XDSCard variant="blue" padding={10}>+ <XDSHStack gap={8} vAlign="center">+ <XDSStackItem size="fill">+ <XDSVStack gap={4}>+ <XDSText type="supporting" color="secondary">+ Product Name Design System+ </XDSText>+ <XDSText type="display-1">Web overview</XDSText>+ <XDSText type="large" color="secondary">+ An open-source UI library to help developers quickly build+ beautiful, accessible products.+ </XDSText>+ <XDSHStack>+ <XDSButton+ label="Get started"+ variant="primary"+ size="lg"+ onClick={() => onSelectComponent('getting-started')}+ />+ </XDSHStack>+ </XDSVStack>+ </XDSStackItem>+ <XDSStackItem size="fill" />+ </XDSHStack>+ </XDSCard>++ {/* Category sections */}+ {COMPONENT_CATEGORIES.map(category => (+ <XDSVStack key={category.label} gap={4}>+ <XDSText type="display-2">{category.label}</XDSText>+ <XDSGrid columns={{minWidth: 260}} gap={8}>+ {category.items.map(item => (+ <XDSCard+ key={item.key}+ padding={0}+ onClick={() => onSelectComponent(item.key)}>+ <XDSVStack gap={2}>+ <XDSSection variant="wash" padding={0} minHeight={160} />+ <XDSSection padding={3} variant="transparent">+ <XDSVStack gap={0.5}>+ <XDSText type="body" weight="bold">+ {item.name}+ </XDSText>+ <XDSText type="body" color="secondary">+ {item.desc}+ </XDSText>+ </XDSVStack>+ </XDSSection>+ </XDSVStack>+ </XDSCard>+ ))}+ </XDSGrid>+ </XDSVStack>+ ))}+ </XDSVStack>+ </XDSSection>);+}++function GettingStartedView() {+ return (+ <XDSSection padding={8} maxWidth={740}>+ <XDSVStack gap={8}>+ {/* Header */}+ <XDSVStack gap={2}>+ <XDSText type="display-1">+ Getting started with Product Name+ </XDSText>+ <XDSText type="supporting" color="secondary">+ Last updated March 30, 2026+ </XDSText>+ <XDSText type="body">+ Install the package, configure your theme, and build your first+ component in three steps.+ </XDSText>+ </XDSVStack>++ {/* AI Assistance prompt card */}+ <XDSCard>+ <XDSVStack gap={3}>+ <XDSHStack gap={2} vAlign="center">+ <XDSStackItem size="fill">+ <XDSHStack gap={2} vAlign="center">+ <XDSIcon icon={SparklesIcon} size="sm" color="secondary" />+ <XDSText type="body" weight="semibold">+ AI Assistance+ </XDSText>+ </XDSHStack>+ </XDSStackItem>+ <XDSButton+ label="Copy prompt"+ variant="ghost"+ size="sm"+ icon={<XDSIcon icon={ClipboardDocumentIcon} />}+ onClick={() => {+ void navigator.clipboard.writeText(+ 'Help me get set up with Product Name. Based on my project, do the following: 1. Install @xds/core and the StyleX compiler. 2. Wrap my app in XDSThemeProvider. 3. Replace one existing component with an XDS equivalent. After setup, suggest relevant next steps based on my project.',+ );+ }}+ />+ <XDSDropdownMenu+ button={{+ label: 'More options',+ variant: 'ghost',+ size: 'sm',+ isIconOnly: true,+ icon: <XDSIcon icon={ChevronDownIcon} />,+ }}+ items={[+ {label: 'Open in v0', onClick: () => {}},+ {label: 'Open in Claude', onClick: () => {}},+ {label: 'Open in ChatGPT', onClick: () => {}},+ {label: 'Open in Cursor', onClick: () => {}},+ ]}+ />+ </XDSHStack>+ <XDSText type="body" color="secondary">+ Help me get set up with Product Name. Based on my project, do the+ following: 1. Install @xds/core and the StyleX compiler. 2. Wrap+ my app in XDSThemeProvider. 3. Replace one existing component with+ an XDS equivalent.+ </XDSText>+ </XDSVStack>+ </XDSCard>++ {/* Prerequisites */}+ <XDSVStack gap={4}>+ <XDSHeading level={2}>Prerequisites</XDSHeading>+ <XDSList density="compact" listStyle="disc">+ <XDSListItem label="Node.js 18+" />+ <XDSListItem label="React 18 or 19" />+ <XDSListItem label="A package manager (npm, yarn, or pnpm)" />+ </XDSList>+ </XDSVStack>++ <XDSDivider />++ {/* Install the package */}+ <XDSVStack gap={4}>+ <XDSHeading level={2}>Install the package</XDSHeading>+ <XDSText type="body">+ Every project starts with installing the core package. This gives+ you access to all components, tokens, and utilities.+ </XDSText>++ {/* Step 1 */}+ <XDSVStack gap={2}>+ <XDSText type="body" weight="bold">+ Step 1: Install the core package+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock code="npm install @xds/core" language="bash" />+ </XDSCard>+ </XDSVStack>++ {/* Step 2 */}+ <XDSVStack gap={2}>+ <XDSText type="body" weight="bold">+ Step 2: Add the StyleX compiler+ </XDSText>+ <XDSText type="body" color="secondary">+ XDS uses StyleX for styling. Add the compiler plugin to your build+ configuration.+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock+ code="npm install @stylexjs/babel-plugin"+ language="bash"+ />+ </XDSCard>+ </XDSVStack>++ {/* Step 3 */}+ <XDSVStack gap={2}>+ <XDSText type="body" weight="bold">+ Step 3: Import your first component+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock+ code={`import { XDSButton } from '@xds/core/Button';++export default function App() {+ return <XDSButton label="Hello XDS" variant="primary" />;+}`}+ language="tsx"+ />+ </XDSCard>+ </XDSVStack>+ </XDSVStack>++ <XDSDivider />++ {/* Configure theming */}+ <XDSVStack gap={4}>+ <XDSHeading level={2}>Configure theming</XDSHeading>+ <XDSText type="body">+ XDS ships with a default theme that works out of the box. To+ customize colors, typography, and spacing, wrap your app in a theme+ provider.+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock+ code={`import { XDSThemeProvider } from '@xds/core/Theme';++export default function App({ children }) {+ return (+ <XDSThemeProvider theme="default">+ {children}+ </XDSThemeProvider>+ );+}`}+ language="tsx"+ />+ </XDSCard>+ <XDSText type="body" color="secondary">+ See the theming guide for the full list of customizable tokens.+ </XDSText>+ </XDSVStack>++ <XDSDivider />++ {/* Next steps */}+ <XDSVStack gap={4}>+ <XDSHeading level={2}>Next steps</XDSHeading>+ <XDSList density="compact" listStyle="disc">+ <XDSListItem label="Fundamental concepts — How theming, layout, and composition work" />+ <XDSListItem label="Component API reference — Props, variants, and examples for every component" />+ <XDSListItem label="Accessibility — Built-in a11y features and ARIA patterns" />+ <XDSListItem label="CLI tools — Scaffold projects and manage templates" />+ <XDSListItem label="Design tokens — Colors, spacing, typography, and sizing" />+ </XDSList>+ </XDSVStack>+ </XDSVStack>+ </XDSSection>+ );+}++function ComponentDetailView({activeNav}: {activeNav: string}) {const [exampleTabs, setExampleTabs] = useState<Record<string, string>>({});const EXAMPLE_PREVIEWS: Record<string, React.ReactNode[]> = {button: [- // Semantics<XDSHStack key="semantics" gap={3} vAlign="center"><XDSButton label="Flat" variant="ghost" /><XDSButton label="Default" variant="secondary" /><XDSButton label="Primary" variant="primary" /><XDSButton label="Destructive" variant="destructive" /></XDSHStack>,- // Default button with badge<XDSButton key="badge" label="Button" variant="secondary" />,],};@@ -781,7 +843,7 @@ export default function DocumentationPage() {<XDSButtonlabel="Button"variant="secondary"- icon={<PlusIcon />}+ icon={<XDSIcon icon={PlusIcon} />}endContent={<XDSBadge label="New" variant="info" />}/>),@@ -789,14 +851,12 @@ export default function DocumentationPage() {badge: <XDSBadge label="Success" variant="success" />,card: (<XDSCard>- <div style={{padding: 16}}>+ <XDSVStack gap={2}><XDSHeading level={4}>Card Title</XDSHeading>- <div style={{marginTop: 8}}>- <XDSText type="body" color="secondary">- Cards group related content and actions.- </XDSText>- </div>- </div>+ <XDSText type="body" color="secondary">+ Cards group related content and actions.+ </XDSText>+ </XDSVStack></XDSCard>),banner: (@@ -815,778 +875,211 @@ export default function DocumentationPage() {),};- return (- <>- <style>{`.code-block-full-width > pre { width: 100% !important; }`}</style>- <div- style={{- display: 'flex',- height: '100%',- backgroundColor: 'var(--color-background-surface, #ffffff)',- fontFamily: 'system-ui, -apple-system, sans-serif',- }}>- {/* LEFT SIDEBAR */}- <aside- style={{- width: 240,- minWidth: 240,- height: '100%',- display: 'flex',- flexDirection: 'column' as const,- backgroundColor: 'var(--color-background-surface, #ffffff)',- overflow: 'hidden',- }}>- {/* Header */}- <div- style={{- display: 'flex',- alignItems: 'center',- padding: '16px 24px 8px',- flexShrink: 0,- }}>- <XDSHeading level={1}>Product Name</XDSHeading>- </div>+ const docs = useMemo(() => getComponentDocs(activeNav), [activeNav]);+ const previews = EXAMPLE_PREVIEWS[activeNav] ?? [];- {/* Nav */}- <nav- style={{- flex: 1,- overflowY: 'auto' as const,- padding: '0 16px 16px 16px',- }}>- <XDSList density="balanced">- <XDSListItem- label="Overview"- isSelected={selectedComponent === null}- onClick={() => {- setSelectedComponent(null);- }}- />- <XDSListItem- label="Getting started"- isSelected={- activeNav === 'getting-started' && selectedComponent !== null- }- onClick={() => {- setSelectedComponent('getting-started');- setActiveNav('getting-started');- }}- />- </XDSList>+ return (+ <XDSSection padding={8} maxWidth={960}>+ <XDSVStack gap={8}>+ {/* Header */}+ <XDSVStack gap={2}>+ <XDSText type="display-1">{getComponentName(activeNav)}</XDSText>+ <XDSText type="supporting" color="secondary">+ March 30, 2026 · Updated 5:40 p.m. PST+ </XDSText>+ </XDSVStack>- {COMPONENT_CATEGORIES.map(category => (- <div key={category.label}>- <SectionLabel label={category.label.toUpperCase()} />- <XDSList density="balanced">- {category.items.map(item => (- <XDSListItem- key={item.key}- label={item.name}- isSelected={- selectedComponent !== null && activeNav === item.key- }- onClick={() => {- setSelectedComponent(item.key);- setActiveNav(item.key);- }}- />- ))}- </XDSList>- </div>- ))}- </nav>- </aside>+ <XDSDivider />- {/* MAIN CONTENT */}- <main- style={{- flex: 1,- overflowY: 'auto' as const,- padding: '32px 40px',- }}>- {selectedComponent === null ? (- /* ============ OVERVIEW ============ */- <div style={{maxWidth: 1200, margin: '0 auto'}}>- {/* Hero banner */}- <div- style={{- marginBottom: 48,- backgroundColor:- 'var(--color-background-accent-muted, #e3f2fd)',- borderRadius: 24,- padding: 60,- display: 'flex',- alignItems: 'center',- gap: 48,- overflow: 'hidden',- minHeight: 320,- }}>- <div style={{flex: 1, minWidth: 0}}>- <XDSText type="supporting" color="secondary">- Product Name Design System- </XDSText>- <div style={{marginTop: 8}}>- <XDSText type="display-1">Web overview</XDSText>- </div>- <div style={{marginTop: 16}}>- <XDSText type="large" color="secondary">- An open-source UI library to help developers quickly build- beautiful, accessible products.- </XDSText>- </div>- <div style={{marginTop: 24}}>- <XDSButton- label="Get started"- variant="primary"- size="lg"- onClick={() => {- setSelectedComponent('button');- setActiveNav('button');- }}- />- </div>- </div>- <div style={{flex: 1}} />- </div>+ {/* Live Preview Card */}+ <XDSCard variant="muted" padding={0}>+ <XDSCenter height={360}>+ {COMPONENT_PREVIEWS[activeNav] ?? (+ <XDSText type="supporting" color="secondary">+ Preview coming soon+ </XDSText>+ )}+ </XDSCenter>+ </XDSCard>- {/* Category sections */}- {COMPONENT_CATEGORIES.map(category => (- <div key={category.label} style={{marginBottom: 64}}>- <div style={{marginBottom: 16}}>- <XDSText type="display-2">{category.label}</XDSText>- </div>- <div- style={{- display: 'grid',- gridTemplateColumns:- 'repeat(auto-fill, minmax(260px, 1fr))',- gap: 32,- }}>- {category.items.map(item => (- <div- key={item.key}- onClick={() => {- setSelectedComponent(item.key);- setActiveNav(item.key);- }}- style={{cursor: 'pointer'}}>- <XDSCard- padding={0}- style={{- border: 'none',- boxShadow: 'none',- outline: 'none',- }}>- {/* Preview area */}- <div- style={{- height: 160,- backgroundColor:- 'var(--color-background-muted, #c4cdd5)',- borderRadius: 12,- }}- />- {/* Card body */}- <div style={{padding: '12px 0 0'}}>- <XDSText type="body" style={{fontWeight: 700}}>- {item.name}- </XDSText>- <div style={{marginTop: 0}}>- <XDSText type="body" color="secondary">- {item.desc}- </XDSText>- </div>- </div>- </XDSCard>- </div>- ))}- </div>- </div>- ))}- </div>- ) : activeNav === 'getting-started' ? (- /* ============ GETTING STARTED ============ */- <div- style={{- display: 'flex',- gap: 48,- maxWidth: 740,- margin: '0 auto',- }}>- {/* Article content */}- <div style={{flex: 1, minWidth: 0}}>- {/* Header */}- <div style={{marginBottom: 8}}>- <XDSText type="display-1">- Getting started with Product Name- </XDSText>- </div>- <div style={{marginBottom: 16}}>- <XDSText type="supporting" color="secondary">- Last updated March 30, 2026- </XDSText>- </div>- <div style={{marginBottom: 32}}>- <XDSText type="body">- Install the package, configure your theme, and build your- first component in three steps.+ {/* Usage & Best Practices */}+ <XDSVStack gap={4} xstyle={styles.narrowContent}>+ <XDSHeading level={2}>Usage</XDSHeading>+ <XDSText type="large" weight="normal">+ {docs.usage}+ </XDSText>+ <XDSHeading level={3}>Best practices</XDSHeading>+ <XDSTable+ data={docs.bestPractices as Record<string, unknown>[]}+ columns={[+ {+ key: 'type',+ header: 'Guidance',+ width: pixel(125),+ renderCell: (item: Record<string, unknown>) => (+ <XDSBadge+ label={item.type === 'do' ? 'Do' : 'Dont'}+ variant={item.type === 'do' ? 'success' : 'error'}+ />+ ),+ },+ {+ key: 'text',+ header: 'Practices',+ renderCell: (item: Record<string, unknown>) => (+ <XDSText type="body" xstyle={styles.whiteSpaceNormal}>+ {item.text as string}</XDSText>- </div>-- {/* AI Assistance prompt card */}- <div style={{marginBottom: 48}}>- <XDSCard>- <div>- <div- style={{- display: 'flex',- alignItems: 'center',- justifyContent: 'space-between',- marginBottom: 12,- }}>- <div- style={{- display: 'flex',- alignItems: 'center',- gap: 8,- }}>- <SparklesIcon- width={16}- height={16}- style={{- color: 'var(--color-text-secondary, #666)',- }}- />- <XDSText type="body" weight="semibold">- AI Assistance- </XDSText>- </div>- <div- style={{- display: 'flex',- alignItems: 'center',- gap: 4,- }}>- <XDSButton- label="Copy prompt"- variant="ghost"- size="sm"- icon={<CopyIcon />}- onClick={() => {- void navigator.clipboard.writeText(- 'Help me get set up with Product Name. Based on my project, do the following: 1. Install @xds/core and the StyleX compiler. 2. Wrap my app in XDSThemeProvider. 3. Replace one existing component with an XDS equivalent. After setup, suggest relevant next steps based on my project.',- );- }}- />- <XDSDropdownMenu- button={{- label: '',- variant: 'ghost',- size: 'sm',- isIconOnly: true,- icon: <ChevronDownIcon />,- }}- items={[- {label: 'Open in v0', onClick: () => {}},- {label: 'Open in Claude', onClick: () => {}},- {label: 'Open in ChatGPT', onClick: () => {}},- {label: 'Open in Cursor', onClick: () => {}},- ]}- />- </div>- </div>- <div- style={{- overflow: 'hidden',- maxHeight: '2.8em',- lineHeight: '1.4em',- }}>- <XDSText type="body" color="secondary">- Help me get set up with Product Name. Based on my- project, do the following: 1. Install @xds/core and- the StyleX compiler. 2. Wrap my app in- XDSThemeProvider. 3. Replace one existing component- with an XDS equivalent. After setup, suggest relevant- next steps based on my project.- </XDSText>- </div>- </div>- </XDSCard>- </div>-- {/* Prerequisites */}- <div id="prerequisites" style={{marginBottom: 48}}>- <XDSHeading level={2}>Prerequisites</XDSHeading>- <div style={{marginTop: 16}}>- <XDSList density="compact" listStyle="disc">- <XDSListItem label="Node.js 18+" />- <XDSListItem label="React 18 or 19" />- <XDSListItem label="A package manager (npm, yarn, or pnpm)" />- </XDSList>- </div>- </div>-- <XDSDivider />-- {/* Install the package */}- <div- id="install-the-package"- style={{marginBottom: 48, marginTop: 48}}>- <XDSHeading level={2}>Install the package</XDSHeading>- <div style={{marginTop: 12}}>- <XDSText type="body">- Every project starts with installing the core package.- This gives you access to all components, tokens, and- utilities.- </XDSText>- </div>+ ),+ },+ ]}+ density="spacious"+ dividers="rows"+ />+ </XDSVStack>- {/* Step 1 */}- <div style={{marginTop: 32, display: 'flex', gap: 16}}>- <div- style={{- width: 24,- height: 24,- borderRadius: '50%',- border:- '1.5px solid var(--color-divider, rgba(0,0,0,0.2))',- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- fontSize: 12,- fontWeight: 600,- flexShrink: 0,- marginTop: 2,- }}>- 1- </div>- <div style={{flex: 1, minWidth: 0}}>- <XDSText type="body" weight="bold">- Install the core package- </XDSText>- <XDSCard- padding={0}- style={{marginTop: 12, overflow: 'hidden'}}>- <div style={{width: '100%'}}>- <XDSCodeBlock- code="npm install @xds/core"- language="bash"- />- </div>- </XDSCard>- </div>- </div>-- {/* Step 2 */}- <div style={{marginTop: 28, display: 'flex', gap: 16}}>- <div- style={{- width: 24,- height: 24,- borderRadius: '50%',- border:- '1.5px solid var(--color-divider, rgba(0,0,0,0.2))',- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- fontSize: 12,- fontWeight: 600,- flexShrink: 0,- marginTop: 2,- }}>- 2- </div>- <div style={{flex: 1, minWidth: 0}}>- <XDSText type="body" weight="bold">- Add the StyleX compiler- </XDSText>- <div style={{marginTop: 8}}>- <XDSText type="body" color="secondary">- XDS uses StyleX for styling. Add the compiler plugin- to your build configuration.- </XDSText>- </div>- <XDSCard- padding={0}- style={{marginTop: 12, overflow: 'hidden'}}>- <div style={{width: '100%'}}>- <XDSCodeBlock- code="npm install @stylexjs/babel-plugin"- language="bash"- />- </div>- </XDSCard>- </div>- </div>+ <XDSDivider />- {/* Step 3 */}- <div style={{marginTop: 28, display: 'flex', gap: 16}}>- <div- style={{- width: 24,- height: 24,- borderRadius: '50%',- border:- '1.5px solid var(--color-divider, rgba(0,0,0,0.2))',- display: 'flex',- alignItems: 'center',- justifyContent: 'center',- fontSize: 12,- fontWeight: 600,- flexShrink: 0,- marginTop: 2,- }}>- 3- </div>- <div style={{flex: 1, minWidth: 0}}>- <XDSText type="body" weight="bold">- Import your first component+ {/* Examples */}+ <XDSVStack gap={4} xstyle={styles.narrowContent}>+ <XDSHeading level={2}>Examples</XDSHeading>+ <XDSText type="large" weight="normal">+ Explore common configurations, variations, and states for this+ component.+ </XDSText>+ </XDSVStack>+ <XDSVStack gap={8}>+ {docs.examples.map((example, i) => {+ const tabKey = `${activeNav}-${i}`;+ const activeTab = exampleTabs[tabKey] ?? 'description';+ return (+ <XDSCard key={i} padding={0}>+ {/* Header */}+ <XDSSection padding={3} variant="transparent">+ <XDSHStack gap={3} vAlign="center">+ <XDSStackItem size="fill">+ <XDSText type="body" weight="medium">+ {example.title}</XDSText>- <XDSCard- padding={0}- style={{marginTop: 12, overflow: 'hidden'}}>- <div style={{width: '100%'}}>- <XDSCodeBlock- code={`import { XDSButton } from '@xds/core/Button';--export default function App() {- return <XDSButton label="Hello XDS" variant="primary" />;-}`}- language="tsx"- />- </div>- </XDSCard>- </div>- </div>- </div>-- <XDSDivider />-- {/* Configure theming */}- <div- id="configure-theming"- style={{marginBottom: 48, marginTop: 48}}>- <XDSHeading level={2}>Configure theming</XDSHeading>- <div style={{marginTop: 12}}>- <XDSText type="body">- XDS ships with a default theme that works out of the box.- To customize colors, typography, and spacing, wrap your- app in a theme provider.- </XDSText>- </div>- <XDSCard- padding={0}- style={{marginTop: 16, overflow: 'hidden'}}>- <div style={{width: '100%'}}>- <XDSCodeBlock- code={`import { XDSThemeProvider } from '@xds/core/Theme';--export default function App({ children }) {- return (- <XDSThemeProvider theme="default">- {children}- </XDSThemeProvider>- );-}`}- language="tsx"- />- </div>- </XDSCard>- <div style={{marginTop: 16}}>- <XDSText type="body" color="secondary">- See the theming guide for the full list of customizable- tokens.- </XDSText>- </div>- </div>-- <XDSDivider />-- {/* Next steps */}- <div id="next-steps" style={{marginBottom: 48}}>- <XDSHeading level={2}>Next steps</XDSHeading>- <div style={{marginTop: 16}}>- <XDSList density="compact" listStyle="disc">- <XDSListItem- label={- <span>- <span- style={{- color: 'var(--color-text-link, #0070f3)',- fontWeight: 600,- }}>- Fundamental concepts- </span>- {' — How theming, layout, and composition work'}- </span>- }- />- <XDSListItem- label={- <span>- <span- style={{- color: 'var(--color-text-link, #0070f3)',- fontWeight: 600,- }}>- Component API reference- </span>- {- ' — Props, variants, and examples for every component'- }- </span>- }- />- <XDSListItem- label={- <span>- <span- style={{- color: 'var(--color-text-link, #0070f3)',- fontWeight: 600,- }}>- Accessibility- </span>- {' — Built-in a11y features and ARIA patterns'}- </span>- }+ </XDSStackItem>+ <XDSHStack gap={1} vAlign="center">+ <XDSButton+ label="Open in Craft"+ variant="ghost"+ size="sm"+ icon={<XDSIcon icon={ArrowTopRightOnSquareIcon} />}/>- <XDSListItem- label={- <span>- <span- style={{- color: 'var(--color-text-link, #0070f3)',- fontWeight: 600,- }}>- CLI tools- </span>- {' — Scaffold projects and manage templates'}- </span>- }+ <XDSButton+ label="Send to CLI"+ variant="ghost"+ size="sm"/>- <XDSListItem- label={- <span>- <span- style={{- color: 'var(--color-text-link, #0070f3)',- fontWeight: 600,- }}>- Design tokens- </span>- {' — Colors, spacing, typography, and sizing'}- </span>- }+ <XDSIconButton+ label="Fullscreen"+ variant="ghost"+ size="sm"+ icon={<XDSIcon icon={ArrowsPointingOutIcon} />}/>- </XDSList>- </div>- </div>- </div>- </div>- ) : (- /* ============ COMPONENT DETAIL ============ */- <div {...stylex.props(cellStyles.wideContent)}>- {/* Header */}- <div- {...stylex.props(- cellStyles.narrowContent,- cellStyles.headerSpacing,- )}>- <XDSText type="display-1">- {getComponentName(activeNav)}- </XDSText>- </div>- <div- {...stylex.props(- cellStyles.narrowContent,- cellStyles.subheaderSpacing,- )}>- <XDSText type="supporting" color="secondary">- March 30, 2026 · Updated 5:40 p.m. PST- </XDSText>- </div>-- <div {...stylex.props(cellStyles.dividerSpacing)}>- <XDSDivider />- </div>-- {/* Live Preview Card */}- <XDSCard- variant="muted"- padding={0}- xstyle={cellStyles.mutedCardBorder}>+ </XDSHStack>+ </XDSHStack>+ </XDSSection>{/* Preview */}- <div {...stylex.props(cellStyles.heroPreview)}>- {COMPONENT_PREVIEWS[activeNav] ?? (+ <XDSCenter height={280}>+ {previews[i] ?? (<XDSText type="supporting" color="secondary">Preview coming soon</XDSText>)}- </div>+ </XDSCenter>+ {/* Tabs + content */}+ <XDSSection variant="wash" padding={3} dividers={['top']}>+ <XDSVStack gap={3}>+ <XDSTabList+ value={activeTab}+ onChange={value =>+ setExampleTabs(prev => ({+ ...prev,+ [tabKey]: value,+ }))+ }+ size="sm"+ xstyle={styles.tabListFlush}>+ <XDSTab value="description" label="Description" />+ <XDSTab value="code" label="Code" />+ </XDSTabList>+ {activeTab === 'description' ? (+ <XDSText type="body">{example.description}</XDSText>+ ) : (+ <XDSCodeBlock code={example.code} language="tsx" />+ )}+ </XDSVStack>+ </XDSSection></XDSCard>- <div {...stylex.props(cellStyles.sectionSpacing)} />+ );+ })}+ </XDSVStack>+ </XDSVStack>+ </XDSSection>+ );+}- {/* Usage & Best Practices */}- {(() => {- const docs = getComponentDocs(activeNav);- return (- <>- <div- {...stylex.props(- cellStyles.narrowContent,- cellStyles.sectionSpacing,- )}>- <XDSHeading level={2}>Usage</XDSHeading>- <div {...stylex.props(cellStyles.usageTextSpacing)}>- <XDSText type="large" weight="normal">- {docs.usage}- </XDSText>- </div>- <div {...stylex.props(cellStyles.bestPracticesSpacing)}>- <XDSHeading level={3}>Best practices</XDSHeading>- </div>- <div {...stylex.props(cellStyles.tableSpacing)}>- <XDSTable- data={docs.bestPractices as Record<string, unknown>[]}- columns={[- {- key: 'type',- header: 'Guidance',- width: pixel(125),- renderCell: (item: Record<string, unknown>) => (- <XDSBadge- label={item.type === 'do' ? 'Do' : 'Dont'}- variant={- item.type === 'do' ? 'success' : 'error'- }- />- ),- },- {- key: 'text',- header: 'Practices',- renderCell: (item: Record<string, unknown>) => (- <XDSText type="body" xstyle={cellStyles.wrap}>- {item.text as string}- </XDSText>- ),- },- ]}- density="spacious"- dividers="rows"- />- </div>- </div>- </>- );- })()}+// ---------------------------------------------------------------------------+// Main component+// ---------------------------------------------------------------------------- <div {...stylex.props(cellStyles.dividerSpacing)}>- <XDSDivider />- </div>+export default function DocumentationPage() {+ const [activeNav, setActiveNav] = useState('button');+ const [selectedComponent, setSelectedComponent] = useState<string | null>(+ null,+ );- {/* Examples */}- {(() => {- const docs = getComponentDocs(activeNav);- const previews = EXAMPLE_PREVIEWS[activeNav] ?? [];- return (- <div {...stylex.props(cellStyles.sectionSpacing)}>- <div {...stylex.props(cellStyles.narrowContent)}>- <XDSHeading level={2}>Examples</XDSHeading>- <div {...stylex.props(cellStyles.examplesTextSpacing)}>- <XDSText type="large" weight="normal">- Explore common configurations, variations, and states- for this component.- </XDSText>- </div>- </div>- <div {...stylex.props(cellStyles.exampleCardsContainer)}>- {docs.examples.map((example, i) => {- const tabKey = `${activeNav}-${i}`;- const activeTab = exampleTabs[tabKey] ?? 'description';- return (- <XDSCard key={i} padding={0}>- {/* Header */}- <div {...stylex.props(cellStyles.cardHeader)}>- <XDSHStack gap={3} vAlign="center">- <div {...stylex.props(cellStyles.flexGrow)}>- <XDSText type="body" weight="medium">- {example.title}- </XDSText>- </div>- <XDSHStack gap={1} vAlign="center">- <XDSButton- label="Open in Craft"- variant="ghost"- size="sm"- icon={<ExternalLinkIcon />}- />- <XDSButton- label="Send to CLI"- variant="ghost"- size="sm"- />- <XDSButton- label="Fullscreen"- variant="ghost"- size="sm"- isIconOnly- icon={<MaximizeIcon />}- />- </XDSHStack>- </XDSHStack>- </div>- {/* Preview */}- <div {...stylex.props(cellStyles.previewArea)}>- {previews[i] ?? (- <XDSText type="supporting" color="secondary">- Preview coming soon- </XDSText>- )}- </div>- {/* Tabs + content */}- <div {...stylex.props(cellStyles.tabsContainer)}>- <XDSTabList- value={activeTab}- onChange={value =>- setExampleTabs(prev => ({- ...prev,- [tabKey]: value,- }))- }- size="sm"- xstyle={cellStyles.tabListFlush}>- <XDSTab- value="description"- label="Description"- />- <XDSTab value="code" label="Code" />- </XDSTabList>- <div {...stylex.props(cellStyles.tabContent)}>- {activeTab === 'description' ? (- <XDSText type="body">- {example.description}- </XDSText>- ) : (- <XDSCodeBlock- code={example.code}- language="tsx"- />- )}- </div>- </div>- </XDSCard>- );- })}- </div>- </div>- );- })()}- </div>- )}- </main>- </div>- </>+ const handleSelectComponent = (key: string) => {+ setSelectedComponent(key);+ setActiveNav(key);+ };++ return (+ <XDSAppShell+ variant="section"+ height="fill"+ sideNav={+ <XDSSideNav+ header={+ <XDSSideNavHeading heading="Product Name" />+ }>+ <XDSSideNavItem+ label="Overview"+ isSelected={selectedComponent === null}+ onClick={() => setSelectedComponent(null)}+ />+ <XDSSideNavItem+ label="Getting started"+ isSelected={activeNav === 'getting-started'}+ onClick={() => handleSelectComponent('getting-started')}+ />+ {COMPONENT_CATEGORIES.map(category => (+ <XDSSideNavSection key={category.label} title={category.label}>+ {category.items.map(item => (+ <XDSSideNavItem+ key={item.key}+ label={item.name}+ isSelected={+ selectedComponent !== null && activeNav === item.key+ }+ onClick={() => handleSelectComponent(item.key)}+ />+ ))}+ </XDSSideNavSection>+ ))}+ </XDSSideNav>+ }>+ {selectedComponent === null ? (+ <OverviewView onSelectComponent={handleSelectComponent} />+ ) : activeNav === 'getting-started' ? (+ <GettingStartedView />+ ) : (+ <ComponentDetailView activeNav={activeNav} />+ )}+ </XDSAppShell>);}