An open source design system that's fully customizable and agent ready
TypeScript
docsite(themes): single-route explorer with sidebar picker + animated playground transition (#2515)
rubyycheung9901b3a4a239
diff --git a/apps/docsite/public/theme-butter-picker.png b/apps/docsite/public/theme-butter-picker.pngnew file mode 100644index 0000000000..486e6788c1Binary files /dev/null and b/apps/docsite/public/theme-butter-picker.png differdiff --git a/apps/docsite/public/theme-gothic-picker.png b/apps/docsite/public/theme-gothic-picker.pngnew file mode 100644index 0000000000..826253a43eBinary files /dev/null and b/apps/docsite/public/theme-gothic-picker.png differdiff --git a/apps/docsite/public/theme-matcha-picker.png b/apps/docsite/public/theme-matcha-picker.pngnew file mode 100644index 0000000000..51b011c1e2Binary files /dev/null and b/apps/docsite/public/theme-matcha-picker.png differdiff --git a/apps/docsite/public/theme-neutral-picker.png b/apps/docsite/public/theme-neutral-picker.pngnew file mode 100644index 0000000000..b88cddfa74Binary files /dev/null and b/apps/docsite/public/theme-neutral-picker.png differdiff --git a/apps/docsite/public/theme-stone-picker.png b/apps/docsite/public/theme-stone-picker.pngnew file mode 100644index 0000000000..8d5f6cb117Binary files /dev/null and b/apps/docsite/public/theme-stone-picker.png differdiff --git a/apps/docsite/public/theme-y2k-picker.png b/apps/docsite/public/theme-y2k-picker.pngnew file mode 100644index 0000000000..21153ae063Binary files /dev/null and b/apps/docsite/public/theme-y2k-picker.png differdiff --git a/apps/docsite/src/app/(site)/themes/[name]/page.tsx b/apps/docsite/src/app/(site)/themes/[name]/page.tsxindex ce5f99b0f6..a31e99ee38 100644--- a/apps/docsite/src/app/(site)/themes/[name]/page.tsx+++ b/apps/docsite/src/app/(site)/themes/[name]/page.tsx@@ -1,29 +1,22 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Dedicated theme page — /themes/<name>+ * Deep-link redirect — /themes/<name> → /themes?theme=<name>*- * Each XDS theme (@xds/theme-*) gets a canonical page on the themes- * side of the site that hosts the full live ThemeShowcasePreview- * (top nav + hero + product grid + table + components). The- * light/dark mode toggle lives in the page header beside the- * Install button so the preview surface stays uncluttered. This is- * the destination for the "Preview" affordance on the /themes- * gallery cards.+ * The themes surface was consolidated into a single state-driven+ * explorer at /themes (see ./page.tsx). To keep existing deep links+ * working (docs cross-links, shared URLs, search bookmarks), this+ * route accepts the original `/themes/<slug>` shape and redirects to+ * the canonical query-param form `/themes?theme=<slug>`, which the+ * explorer reads on mount to preselect the right theme in its+ * sidebar picker.*- * This is the canonical URL per theme. Theme entry points (gallery- * cards, sidebar, search) link here directly.+ * Only known theme slugs are statically generated; any other slug+ * falls through Next's default routing and returns a 404, matching+ * the pre-consolidation behavior of the deleted per-theme page.*/--import {notFound} from 'next/navigation';-import {XDSSection} from '@xds/core/Section';+import {redirect} from 'next/navigation';import {packages} from '../../../../generated/packageRegistry';-import {themeObjects} from '../../../../generated/themeRegistry';-import {ThemePackagePage} from '../../../../components/ThemePackagePage';--function slugToPackageName(slug: string): string {- return `@xds/theme-${slug}`;-}export function generateStaticParams() {return packages@@ -31,36 +24,11 @@ export function generateStaticParams() {.map(p => ({name: p.name.replace('@xds/theme-', '')}));}-export default async function ThemePage({+export default async function ThemeRedirectPage({params,}: {params: Promise<{name: string}>;}) {const {name: slug} = await params;- const pkgName = slugToPackageName(slug);- const pkg = packages.find(p => p.name === pkgName);- const theme = themeObjects[pkgName];- if (!pkg || !theme) {- notFound();- }-- // Vanity title: strip the trailing " Theme" suffix from displayName- // so the title reads as a brand-style wordmark ("Neutral", "Butter",- // "Y2K") rather than the redundant "Neutral Theme" on a page that's- // already, by definition, about a theme. Falls back to displayName- // verbatim if the suffix isn't present (e.g. legacy entries).- const vanityTitle = pkg.displayName.replace(/\s*Theme$/i, '').trim();-- return (- <XDSSection maxWidth="lg" padding={6}>- <ThemePackagePage- title={vanityTitle || pkg.displayName}- packageName={pkg.name}- description={pkg.description}- version={pkg.version}- readme={pkg.readme}- theme={theme}- />- </XDSSection>- );+ redirect(`/themes?theme=${encodeURIComponent(slug)}`);}diff --git a/apps/docsite/src/app/(site)/themes/page.tsx b/apps/docsite/src/app/(site)/themes/page.tsxindex e51ee704f2..522867bcba 100644--- a/apps/docsite/src/app/(site)/themes/page.tsx+++ b/apps/docsite/src/app/(site)/themes/page.tsx@@ -1,370 +1,79 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * Themes gallery — extracted from craft.+ * Themes page — /themes+ *+ * Single canonical surface for browsing every XDS theme. Renders the+ * full live ThemePackagePage (sidebar picker + themed preview+ * mockup + card showcase), seeded with the Neutral theme as the+ * default selection.+ *+ * The legacy per-theme route at /themes/<name> still resolves —+ * it now redirects here with ?theme=<slug>, which this page reads+ * to preselect the right theme in the sidebar so deep links from+ * docs, search, and shared URLs land on the requested theme rather+ * than the default seed.*/-'use client';--import * as stylex from '@stylexjs/stylex';-import {XDSText} from '@xds/core/Text';-import {XDSHStack, XDSVStack} from '@xds/core/Layout';+import {notFound} from 'next/navigation';import {XDSSection} from '@xds/core/Section';-import {XDSCard} from '@xds/core/Card';-import {XDSButton} from '@xds/core/Button';-import {XDSOverlay} from '@xds/core/Overlay';-import {XDSTheme} from '@xds/core/theme';-import {- spacingDefaults,- radiusDefaults,- textSizeDefaults,-} from '@xds/core/theme/tokens.stylex';-import {useThemeMode} from '../../providers';import {packages} from '../../../generated/packageRegistry';import {themeObjects} from '../../../generated/themeRegistry';-import {ThemeShowcaseTile} from '../../../components/ThemeShowcaseTile';--// Re-set XDS's structural tokens (spacing, radii, font sizes) back to-// the defaults exported from @xds/core. Each <XDSTheme> wrapper sets a-// full token bundle including these structural slots, which would make-// gallery cards visually inconsistent (different button heights, badge-// sizes, banner padding, etc.). Resetting only the structural tokens —-// while leaving --color-* and --font-family-* alone — keeps the-// layout uniform but lets each card showcase its true palette and-// typography. Values flow from tokens.stylex.ts so this stays in sync-// with the XDS scale automatically.-const STRUCTURAL_TOKEN_OVERRIDES: React.CSSProperties = {- ...spacingDefaults,- ...radiusDefaults,- ...textSizeDefaults,- height: '100%',-};--// Gallery order — themes are sorted by visual closeness, starting-// from the most restrained / brand-neutral and ending at the most-// expressive / brand-distinct. Any theme not in this list falls to-// the end (alphabetical) so the gallery never silently drops a-// newly-added theme.-const THEME_ORDER: ReadonlyArray<string> = [- '@xds/theme-neutral',- '@xds/theme-stone',- '@xds/theme-gothic',- '@xds/theme-matcha',- '@xds/theme-y2k',- '@xds/theme-butter',-];--const themePackages = packages- .filter(p => p.name.includes('theme-') && p.name !== '@xds/theme-default')- .sort((a, b) => {- const ai = THEME_ORDER.indexOf(a.name);- const bi = THEME_ORDER.indexOf(b.name);- // Unknown themes go to the end, sorted alphabetically among themselves.- if (ai === -1 && bi === -1) {- return a.name.localeCompare(b.name);- }- if (ai === -1) {- return 1;- }- if (bi === -1) {- return -1;- }- return ai - bi;- });+import {ThemePackagePage} from '../../../components/ThemePackagePage';-// Max viewport-px the gallery centers in. Sized for the 2-column grid:-// at full width that gives ~785px per card after the gap, fitting the-// rich theme preview composition.-const GALLERY_MAX_WIDTH = 1600;+// Default seed for the page — the picker opens with this theme+// selected on first visit. Neutral is the most restrained / brand-+// neutral theme in the gallery, so it sets a calm baseline before+// users browse into the more expressive themes (Y2K, Butter, etc.).+const DEFAULT_THEME_PACKAGE = '@xds/theme-neutral';-// Minimum px-width a single card needs to render side-by-side internally-// (image + heading + type samples + swatches + actions on the left,-// input + table + controls + banners on the right). Drives the grid's-// auto-fill breakpoint: below ~2 × this value (viewport) the grid drops-// from 2 cards to 1. The tile itself stacks to a single column below-// TILE_STACK_BREAKPOINT (defined in ThemeShowcaseTile.tsx).-const CARD_MIN_WIDTH = 760;+function slugToPackageName(slug: string): string {+ return `@xds/theme-${slug}`;+}-const styles = stylex.create({- // Wraps the gallery so it caps at a sane max width and centers in- // the viewport. We do this on a plain wrapper instead of via- // XDSSection's maxWidth prop because the section's negative-inline-- // margin styles (used to break out of container padding elsewhere)- // beat any margin-inline:auto we try to set on the section itself.- //- // 1600px is sized for the 2-column grid: at full width that gives- // ~785px per card after the gap, which fits the rich theme preview- // composition (image, type samples, swatches, actions on the left- // + input, progress, controls, table, banners on the right).- galleryWrap: {- maxWidth: GALLERY_MAX_WIDTH,- marginInline: 'auto',- width: '100%',- },- // Custom CSS Grid in place of XDSGrid so we control the column- // template directly. The minmax() uses min(760px, 100%) for the- // minimum so cells shrink to fit the viewport on mobile instead- // of forcing horizontal overflow at <760px viewport (which is- // what XDSGrid's plain minmax(760px, ...) does).- //- // Max column count of 2 enforced via the calc() upper bound:- // (100% - gap) / 2 prevents tracks from being narrower than half.- grid: {- display: 'grid',- gap: 'var(--spacing-4)',- justifyContent: 'center',- gridTemplateColumns: `repeat(auto-fill, minmax(min(${CARD_MIN_WIDTH}px, 100%), calc((100% - var(--spacing-4)) / 2)))`,- },- heroTitle: {- textAlign: 'center' as const,- },- cardImage: {- display: 'block',- width: '100%',- aspectRatio: '4/3',- backgroundColor: 'var(--color-background-muted)',- borderRadius: 'var(--radius-container)',- },- // Fills the gallery card cell at 100% height so the inner tile- // (and its two columns) can stretch to match the tallest card- // in the row. CSS Grid auto-stretches cells in the same row to- // the tallest cell; this rule + the parent chain having- // `height: 100%` lets the stretch propagate all the way down.- // overflow:hidden protects against any descendant component- // (long text, wide table cells) bleeding past the gallery card's- // rounded edges at narrow viewports.- previewFrame: {- height: '100%',- overflow: 'hidden',- },+export default async function ThemesPage({+ searchParams,+}: {+ searchParams: Promise<{theme?: string | string[]}>;+}) {+ // ?theme=<slug> preselects the picker. Falls back to the Neutral+ // seed if the param is missing, malformed, or names a theme that+ // isn't in the registry (so a stale link doesn't 404 on us — the+ // user still lands on the explorer with a sensible default).+ const params = await searchParams;+ const rawSlug = params.theme;+ const slug = Array.isArray(rawSlug) ? rawSlug[0] : rawSlug;- // The outer XDSCard sized to fill its grid cell at full height so- // every card in a row matches the tallest. The whole tile is- // presentational — navigation happens only through the two- // XDSButtons in the hover overlay ("Preview" / "Open in Playground").- cardFill: {- height: '100%',- },- // Wrapper around the XDSOverlay that fills the gallery card cell- // at full height so the overlay's scrim covers the entire tile.- // The --color-overlay scrim deepening lives as an inline style on- // the rendered element (matching the templates page) since- // stylex.create rejects raw CSS custom property declarations.- overlayHost: {- height: '100%',- // The clickable card wrapper renders a flex/block parent that- // doesn't preserve `height:100%` for nested grandchildren without- // an explicit display:flex relay. flex column lets the overlay- // child below stretch to fill the host.- display: 'flex',- flexDirection: 'column' as const,- },- // XDSOverlay's own container is a plain div with no explicit- // height, so without this rule the overlay sizes to its content- // and the underlying ThemeShowcaseTile's image flex-grow ends up- // producing inconsistent card heights across the row. flex:1 in- // the column overlayHost above stretches it to fill, height:100%- // makes the relay explicit for any browser that doesn't honor- // implicit flex-stretch on this element.- overlayFill: {- flex: 1,- height: '100%',- },- // Inner overlay content — caption + actions cluster pinned to the- // bottom-left of the tile. The scrim background itself is NOT a- // click target (no cursor: pointer, no onClick); navigation is- // routed exclusively through the two XDSButtons below.- overlayInner: {- display: 'flex',- flexDirection: 'column' as const,- justifyContent: 'flex-end',- alignItems: 'flex-start',- height: '100%',- width: '100%',- padding: 16,- },- // White-on-scrim text inside the overlay. The scrim is dark enough- // (78% on-light mix) that the standard --color-text-primary token- // would be hard to read; explicit white pairs with the scrim.- // Text colors on the dark scrim use the canonical --color-on-dark- // token (resolves to white in both modes) so the on-scrim treatment- // tracks any future redefinition of the on-dark palette token.- // color-mix gives us the 70% opacity variant for the description- // line without hardcoding an rgba literal.- overlayTitle: {- color: 'var(--color-on-dark)',- },- overlayDescription: {- color: 'color-mix(in srgb, var(--color-on-dark) 70%, transparent)',- },-});+ const requestedPkgName = slug ? slugToPackageName(slug) : null;+ const requestedPkg = requestedPkgName+ ? packages.find(p => p.name === requestedPkgName)+ : undefined;+ const requestedTheme = requestedPkgName+ ? themeObjects[requestedPkgName]+ : undefined;-// Strip the `@xds/theme-` prefix from a package name to get the-// /themes/<slug> + /themes/playground/<slug> route segment.-// Example: `@xds/theme-stone` → `stone`.-function themeSlug(packageName: string): string {- return packageName.replace(/^@xds\/theme-/, '');-}+ // Use the requested theme if it resolved to a real package + theme+ // object; otherwise fall back to the default seed so stale links+ // still land on a usable page rather than a 404.+ const seedPkg =+ requestedPkg && requestedTheme+ ? requestedPkg+ : packages.find(p => p.name === DEFAULT_THEME_PACKAGE);+ const seedTheme =+ requestedPkg && requestedTheme+ ? requestedTheme+ : themeObjects[DEFAULT_THEME_PACKAGE];-// Deepens XDSOverlay's --color-overlay scrim so white action chrome-// stays legible against light theme previews like Butter or Stone.-// Set as an inline style because stylex.create() doesn't accept raw-// CSS custom-property declarations; hoisted to a typed const so the-// inline style satisfies @typescript-eslint/consistent-type-assertions-// (no `as React.CSSProperties` cast at the JSX call site).-const OVERLAY_SCRIM_OVERRIDE: React.CSSProperties = {- // @ts-expect-error — React.CSSProperties doesn't type custom CSS- // variables; the cast above is what consumers normally use to- // bypass it. Using an inline ts-expect-error keeps the lint rule- // happy while still letting us set the variable.- '--color-overlay':- 'color-mix(in srgb, var(--color-on-light) 78%, transparent)',-};+ if (!seedPkg || !seedTheme) {+ // Defensive: only fires if the @xds/theme-neutral package is+ // ever removed from the workspace, which would break the entire+ // themes section anyway.+ notFound();+ }-export default function ThemesPage() {- const {mode} = useThemeMode();return (- <div {...stylex.props(styles.galleryWrap)}>- <XDSSection padding={6}>- <XDSVStack gap={10}>- <XDSVStack gap={4} hAlign="center">- <XDSVStack gap={2} hAlign="center">- <XDSText type="display-2" xstyle={styles.heroTitle}>- Themes built for different apps- </XDSText>- <XDSText type="body" color="secondary" xstyle={styles.heroTitle}>- Browse pre-built themes — each a complete look spanning colors,- typography, motion, and spacing.- <br />- Install one as-is, or use it as a starting point for your own.- </XDSText>- </XDSVStack>- {/* Hero CTAs — two paths into theming. The primary- "Build a custom theme" opens the theme playground- seeded with the neutral theme so users can fork it- and tweak tokens with instant visual feedback;- the secondary "How theming works" sends users to- the docs for the defineTheme + CLI wizard- walkthrough. */}- <XDSHStack gap={2} hAlign="center" wrap="wrap">- <XDSButton- variant="primary"- size="lg"- label="Build a custom theme"- href="/themes/playground/neutral"- />- <XDSButton- variant="secondary"- size="lg"- label="How theming works"- href="/docs/theme"- />- </XDSHStack>- </XDSVStack>-- <div {...stylex.props(styles.grid)}>- {themePackages.map(pkg => {- const theme = themeObjects[pkg.name];- const label = pkg.displayName- .replace(/^Theme:\s*/, '')- .replace(/\s*Theme$/, '');- const slug = themeSlug(pkg.name);- return (- <XDSCard- key={pkg.name}- padding={0}- variant="transparent"- xstyle={styles.cardFill}>- {/* Tile is fully presentational. Navigation is- handled exclusively by the two XDSButtons inside- the hover overlay ("Preview" → /themes/<slug>;- "Open in Playground" → /playground?theme=<slug>,- which opens the main playground with the theme- seeded into the Theme editor).- No card-wide click target — earlier iterations- wrapped this in XDSClickableCard, but the- overlay scrim's pointer-events: auto combined- with the inner tile's then-clickable card- created nested clickable containers and clicks- ended up navigating nowhere.-- Hover overlay mirrors the templates gallery: a- dark scrim fades in on hover with a label,- short description, and the two CTA buttons. The- OVERLAY_SCRIM_OVERRIDE inline style deepens- --color-overlay so white action chrome stays- legible on light theme previews. */}- <div- {...stylex.props(styles.overlayHost)}- style={OVERLAY_SCRIM_OVERRIDE}>- <XDSOverlay- showOn="hover"- scrim="dark"- xstyle={styles.overlayFill}- content={- <div {...stylex.props(styles.overlayInner)}>- <XDSVStack gap={2}>- <XDSVStack gap={0.5}>- <XDSText- type="body"- weight="bold"- xstyle={styles.overlayTitle}>- {label}- </XDSText>- {pkg.description && (- <XDSText- type="supporting"- xstyle={styles.overlayDescription}>- {pkg.description.slice(0, 120)}- {pkg.description.length > 120 ? '\u2026' : ''}- </XDSText>- )}- </XDSVStack>- <XDSHStack gap={2}>- <XDSButton- label="Preview"- variant="secondary"- size="sm"- href={`/themes/${slug}`}- />- <XDSButton- label="Open in Playground"- variant="secondary"- size="sm"- href={`/playground?theme=${slug}`}- />- </XDSHStack>- </XDSVStack>- </div>- }>- <div {...stylex.props(styles.previewFrame)}>- {theme ? (- <XDSTheme theme={theme} mode={mode}>- {/* Re-set structural tokens to XDS defaults- (see STRUCTURAL_TOKEN_OVERRIDES above) so- every card has identical layout / control- sizes. Colors and font-family slots stay- theme-driven. */}- <div style={STRUCTURAL_TOKEN_OVERRIDES}>- <ThemeShowcaseTile- label={label}- themeName={pkg.name}- description={pkg.description}- />- </div>- </XDSTheme>- ) : (- <div {...stylex.props(styles.cardImage)} />- )}- </div>- </XDSOverlay>- </div>- </XDSCard>- );- })}- </div>- </XDSVStack>- </XDSSection>- </div>+ <XDSSection maxWidth="lg" padding={6}>+ <ThemePackagePage packageName={seedPkg.name} theme={seedTheme} />+ </XDSSection>);}diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.cssindex 6c4987f7eb..3c69d5ac5f 100644--- a/apps/docsite/src/app/globals.css+++ b/apps/docsite/src/app/globals.css@@ -86,3 +86,4 @@ body[data-nav-mode='surface'] .xds-top-nav:where(:not(.xds-app-shell .xds-app-shbackground: var(--color-background-body);backdrop-filter: none;}+diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsxindex 1049b9a8a6..5adefd060f 100644--- a/apps/docsite/src/app/layout.tsx+++ b/apps/docsite/src/app/layout.tsx@@ -32,7 +32,7 @@ export default function RootLayout({children}: {children: React.ReactNode}) {/><linkrel="stylesheet"- href="https://fonts.googleapis.com/css2?family=Albert+Sans:wght@400;500;600;700&family=DM+Sans:wght@400;500;600;700&family=Figtree:wght@400;500;600;700&family=Fraunces:opsz,[email protected],400;9..144,500;9..144,600;9..144,700&family=Fustat:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Manufacturing+Consent&family=Montserrat:wght@400;500;600;700&family=Outfit:wght@400;500;600;700&family=PT+Serif:wght@400;700&family=Playwrite+US+Trad:[email protected]&family=Poppins:wght@400;500;600;700&family=UnifrakturMaguntia&display=swap"+ href="https://fonts.googleapis.com/css2?family=Albert+Sans:wght@400;500;600;700&family=DM+Sans:wght@400;500;600;700&family=Figtree:wght@400;500;600;700&family=Fraunces:opsz,[email protected],400;9..144,500;9..144,600;9..144,700&family=Fustat:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Manufacturing+Consent&family=Montserrat:wght@400;500;600;700&family=Outfit:wght@400;500;600;700&family=PT+Serif:wght@400;700&family=Playwrite+US+Trad:[email protected]&family=Poppins:wght@400;500;600;700&family=Sarina&family=UnifrakturMaguntia&display=swap"/></head><body>diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsxindex 9baf9b7b23..a59e7746f9 100644--- a/apps/docsite/src/components/SearchPalette.tsx+++ b/apps/docsite/src/components/SearchPalette.tsx@@ -56,10 +56,13 @@ export function SearchPalette({for (const pkg of packages) {const isTheme = pkg.name.includes('theme-');+ // All themes share the single /themes surface — the per-theme+ // dynamic route was removed in favor of state-driven selection.+ // Search results for theme packages all land on /themes with+ // Neutral as the default seed; users browse to the specific+ // theme they want via the sidebar picker.items.push({- id: isTheme- ? `/themes/${pkg.name.replace('@xds/theme-', '')}`- : `/docs/${pkg.name.replace('@xds/', '')}`,+ id: isTheme ? '/themes' : `/docs/${pkg.name.replace('@xds/', '')}`,label: pkg.displayName,auxiliaryData: {group: 'Package'},});diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsxindex 8b77863989..3e7254fb4a 100644--- a/apps/docsite/src/components/ThemePackagePage.tsx+++ b/apps/docsite/src/components/ThemePackagePage.tsx@@ -2,63 +2,422 @@'use client';-import {useState} from 'react';-import stylex from '@stylexjs/stylex';-import {ArrowLeft, Sun, Moon} from 'lucide-react';-import {XDSText} from '@xds/core/Text';-import {- XDSVStack,- XDSHStack,- XDSLayout,- XDSLayoutContent,-} from '@xds/core/Layout';+import {useCallback, useMemo, useState} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {usePathname, useRouter} from 'next/navigation';+import {Sun, Moon} from 'lucide-react';+import {durationVars, easeVars} from '@xds/core/theme/tokens.stylex';+import {XDSHStack, XDSVStack} from '@xds/core/Layout';+import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSCard} from '@xds/core/Card';-import {XDSToolbar} from '@xds/core/Toolbar';import {XDSTheme} from '@xds/core/theme';import type {XDSDefinedTheme} from '@xds/core/theme';-import {XDSMarkdown} from '@xds/core/Markdown';import {XDSButton} from '@xds/core/Button';-import {XDSDialog, XDSDialogHeader} from '@xds/core/Dialog';+import {XDSLink} from '@xds/core/Link';+import {XDSSelectableCard} from '@xds/core/SelectableCard';+import {XDSSelector} from '@xds/core/Selector';+import {XDSDivider} from '@xds/core/Divider';import {ThemeShowcasePreview} from './ThemeShowcasePreview';import {ThemeCardShowcase} from './ThemeCardShowcase';import {getThemeImages} from './themeImages';+import {packages} from '../generated/packageRegistry';+import {themeObjects} from '../generated/themeRegistry';-// Entrance keyframes for the floating footer pill — translates up-// from below its resting position into place. Starts fully off--// screen (translateY(100% + bottom inset) so the entire pill is-// hidden during the pre-animation delay) and slides into its-// final resting position. No opacity transition — the toolbar-// reads as opaque chrome rising into view rather than fading.-const floatingFooterEntrance = stylex.keyframes({- from: {- transform: 'translateY(calc(100% + var(--spacing-4)))',- },- to: {- transform: 'translateY(0)',- },+// Gallery order — themes are listed in the same canonical visual-+// closeness order used elsewhere (most restrained → most expressive).+// Lives here so the sidebar's theme list reads in the same order as+// /themes (Neutral → Stone → Gothic → Matcha → Y2K → Butter). Any+// theme not in this list falls to the end alphabetically.+const THEME_ORDER: ReadonlyArray<string> = [+ '@xds/theme-neutral',+ '@xds/theme-stone',+ '@xds/theme-gothic',+ '@xds/theme-matcha',+ '@xds/theme-y2k',+ '@xds/theme-butter',+];++// The package whose selection corresponds to the canonical bare+// `/themes` URL (no `?theme=` query string). Must agree with the+// `DEFAULT_THEME_PACKAGE` constant in `app/(site)/themes/page.tsx`,+// which uses the same value to seed the page when no query param+// is present — if these drift, the picker will round-trip the URL+// (selecting the "default" theme would write a query that the+// server then strips on reload, etc.).+const DEFAULT_THEME_PACKAGE = '@xds/theme-neutral';++// Strip "Theme: " prefix and " Theme" suffix from the registered+// displayName so the switcher labels read as the brand wordmark+// ("Neutral", "Butter") rather than the redundant decorations.+// Mirrors the same helper used on the /themes overview page.+function themeLabel(displayName: string): string {+ return displayName.replace(/^Theme:\s*/, '').replace(/\s*Theme$/, '');+}++// Strip the `@xds/theme-` prefix so the slug matches the URL form+// used by both the dynamic redirect route (`/themes/<slug>`) and+// the explorer's `?theme=<slug>` query param. Mirrored from the+// helper on the server-side page.tsx so the encode/decode stays in+// sync at a single import boundary.+function packageNameToSlug(packageName: string): string {+ return packageName.replace(/^@xds\/theme-/, '');+}++// Below this viewport width the sidebar collapses to a compact+// XDSSelector dropdown + inline action row above the preview. The+// 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)';++// Fixed sidebar width — compact enough that the right pane gets the+// lion's share of horizontal space, wide enough to fit the longest+// theme name, the hero heading + description, and the full-width+// "Build a custom theme" / "How theming works" CTAs at size="md".+const SIDEBAR_WIDTH = 260;++// Sticky-top offset for the sidebar. Clears the docsite's sticky+// XDSAppShell top nav (which uses --appshell-header-height,+// populated post-hydration) plus a touch of breathing room so the+// sidebar pill doesn't look glued to the nav's bottom edge.+const SIDEBAR_STICKY_TOP =+ 'calc(var(--appshell-header-height, 64px) + var(--spacing-4))';++// Sidebar-leave animation — slides the sidebar off the left edge+// and fades it out. Triggered when the user clicks Customize: the+// keyframe runs for one --duration-medium tick, then the click+// handler navigates to the playground. The right preview stays+// visually anchored during the leave, so the transition reads as+// "swap the left panel for the editor" rather than a generic page+// change — the playground page renders its own editor controls in+// roughly the same column when it mounts.+const sidebarLeaveKeyframes = stylex.keyframes({+ from: {transform: 'translateX(0)', opacity: 1},+ to: {transform: 'translateX(-100%)', opacity: 0},});const styles = stylex.create({- // Reserves bottom space equal to the floating footer's height +- // surrounding margin so the last card row can scroll clear of the- // pinned footer rather than disappearing behind it.- page: {- paddingBottom: 'calc(72px + var(--spacing-6))',+ // Outer two-column container. Sidebar (fixed width) sits left,+ // right pane (flex:1) holds the existing preview + showcase. The+ // gap keeps the two surfaces from butting against each other.+ // alignItems:flex-start so the sticky sidebar's vertical reference+ // is the column top, not the (potentially shorter) sidebar height.+ twoColumn: {+ display: 'flex',+ flexDirection: 'row' as const,+ alignItems: 'flex-start',+ gap: 'var(--spacing-6)',+ [SIDEBAR_BREAKPOINT]: {+ flexDirection: 'column' as const,+ },},- // Matches the preview card's 1200px max-width so the card- // showcase visually aligns with the preview above it.- showcaseBlock: {+ // Applied to the sidebar while the leave animation is playing.+ // Slides the sidebar off the left edge + fades it out so the+ // right preview stays put visually until the playground replaces+ // it. Forward fill-mode holds the end state so there's no flash+ // of the sidebar reverting before the navigation swaps the route.+ // Honors prefers-reduced-motion by collapsing to a zero-duration+ // animation so the leave is instant for users who'd find the+ // slide motion distracting.+ sidebarLeaving: {+ animationName: sidebarLeaveKeyframes,+ animationDuration: durationVars['--duration-medium'],+ animationTimingFunction: easeVars['--ease-standard'],+ animationFillMode: 'forwards',+ pointerEvents: 'none' as const,+ '@media (prefers-reduced-motion: reduce)': {+ animationDuration: '0s',+ },+ },+ // Sticky sidebar wrapper. position:sticky keeps the panel in view+ // while the right pane scrolls past; top offset clears the docsite+ // top nav so the sidebar doesn't disappear behind it. flex:0 0 auto+ // pins the width to SIDEBAR_WIDTH; the right pane (flex:1) absorbs+ // any leftover horizontal space. Hidden at narrow viewports — the+ // mobile selector + actions row takes its place above the preview.+ //+ // Caps the sidebar at the viewport height (minus the top nav and+ // matching bottom breathing room) and gives it its own scroll+ // container via overflowY:auto. Without that, the sticky panel+ // tracks the viewport but its own contents extend off the bottom+ // edge — users have to scroll the whole page to the bottom before+ // the rest of the sidebar comes into view. With the cap + inner+ // overflow, the sidebar scrolls independently of the page.+ sidebar: {+ flex: '0 0 auto',+ width: SIDEBAR_WIDTH,+ position: 'sticky' as const,+ top: SIDEBAR_STICKY_TOP,+ maxHeight: `calc(100dvh - var(--appshell-header-height, 64px) - var(--spacing-4) * 2)`,+ overflowY: 'auto' as const,+ [SIDEBAR_BREAKPOINT]: {+ display: 'none',+ },+ },+ // Sidebar card — surface chrome (background, border, radius).+ // Padding is generous-but-compact so the inner action stack ++ // theme list breathe without burning horizontal space the right+ // pane needs.+ sidebarCard: {+ padding: 'var(--spacing-4)',+ },+ // Right column — takes the rest of the horizontal space. The+ // inner preview + showcase blocks keep their own 1200px caps so+ // the right pane just hosts them; it doesn't impose its own+ // width constraint. minWidth:0 lets flex shrink it correctly+ // when the viewport is narrow.+ rightColumn: {+ flex: '1 1 0',+ minWidth: 0,+ display: 'flex',+ flexDirection: 'column' as const,+ gap: 'var(--spacing-8)',+ },+ // Theme list — vertical stack of themed cards, one per theme.+ // gap separates each card so the inset accent border of the+ // selected card has breathing room around it (rather than+ // bumping into neighboring cards).+ themeList: {+ display: 'flex',+ flexDirection: 'column' as const,+ gap: 'var(--spacing-2)',+ },+ // Make every action button (hero CTAs, mode toggle, Customize)+ // stretch to the sidebar width and left-align its label+ // (XDSButton's default is centered, which looks off in a vertical+ // nav-style list).+ themeListButton: {width: '100%',- maxWidth: 1200,- marginInline: 'auto',+ justifyContent: 'flex-start',+ },+ // Hero primary CTA — sits on a flex row beside the icon-only+ // mode toggle. flex:1 + minWidth:0 lets it absorb the leading+ // horizontal space so the icon button stays pinned to the+ // trailing edge regardless of label length.+ heroPrimaryButton: {+ flex: 1,+ minWidth: 0,+ },+ // Themed theme-row card. The XDSSelectableCard wrapper itself+ // stays variant="transparent" + padding=0 so it doesn't paint a+ // surface from the OUTER docsite theme; the inner themedSurface+ // div (rendered inside its own <XDSTheme>) does the painting using+ // the theme being represented. That way each card reads as a+ // miniature brand preview rather than a docsite-Astryx card with+ // theme-colored text on top.+ themeCard: {+ width: '100%',+ },+ // Inner card surface — lives inside the per-card <XDSTheme>+ // wrapper so the theme's heading typography (used by the+ // wordmark) + brand color tokens (used by the gradient) all+ // resolve to the represented theme's values. Each card becomes+ // a mood tile: soft multi-radial gradient backdrop made from+ // the theme's accent + categorical hues, with the wordmark+ // centered on top in the theme's heading font.+ //+ // Fixed height so every card lines up identically regardless of+ // the theme's heading font (cursive themes render glyphs taller+ // than sans-serif themes). 120px reads as a hero tile rather+ // than a list row.+ //+ // Gradient is a stack of 5 radial gradients placed at the+ // corners + center, using semi-transparent theme colors so they+ // blend into each other (rather than stacking as discrete+ // blobs). Mixed with surface as the base so light + dark themes+ // both get a soft, painterly look.+ themedSurface: {+ height: 120,+ padding: 'var(--spacing-4)',+ // Hardcoded radius rather than var(--radius-container) so each+ // card matches the others regardless of the represented theme's+ // own container radius. (Matcha uses a smaller container+ // radius than Neutral, which would otherwise visibly differ+ // when its card lives in the picker beside the others.) The+ // outer XDSSelectableCard's selected-state inset shadow uses+ // the same radius implicitly via its own borderRadius, so this+ // value should stay in sync with the docsite's container+ // radius (12px in Astryx).+ borderRadius: 12,+ display: 'flex',+ flexDirection: 'row' as const,+ alignItems: 'center',+ justifyContent: 'center',+ position: 'relative' as const,+ overflow: 'hidden',+ backgroundColor: 'var(--color-background-surface)',+ backgroundImage: [+ // Top-left: accent+ 'radial-gradient(circle at 0% 0%, color-mix(in srgb, var(--color-accent) 65%, transparent), transparent 60%)',+ // Top-right: orange categorical+ 'radial-gradient(circle at 100% 0%, color-mix(in srgb, var(--color-background-orange) 70%, transparent), transparent 60%)',+ // Bottom-left: green categorical+ 'radial-gradient(circle at 0% 100%, color-mix(in srgb, var(--color-background-green) 70%, transparent), transparent 60%)',+ // Bottom-right: blue categorical+ 'radial-gradient(circle at 100% 100%, color-mix(in srgb, var(--color-background-blue) 70%, transparent), transparent 60%)',+ // Center: accent-muted bloom that softens everything else+ 'radial-gradient(circle at 50% 50%, color-mix(in srgb, var(--color-accent-muted) 50%, transparent), transparent 70%)',+ ].join(', '),+ },+ // Per-theme bespoke picker artwork — one rule per theme that+ // has a custom photo (vs. the multi-radial-gradient default).+ // Each rule sets the picker card's background to a dedicated+ // /theme-<slug>-picker.png image. These are SEPARATE files from+ // the /theme-<slug>-preview.png images used on the /themes+ // overview + detail page hero — these picker assets are sized+ // and art-directed for the small 120px-tall picker card.+ // background-size:cover so each image always fills the card+ // regardless of the source's intrinsic dimensions.+ surfaceButter: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-butter-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',+ },+ surfaceGothic: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-gothic-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',+ },+ surfaceY2k: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-y2k-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',+ },+ surfaceStone: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-stone-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',+ },+ surfaceNeutral: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-neutral-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',+ },+ surfaceMatcha: {+ backgroundColor: 'transparent',+ backgroundImage: 'url(/theme-matcha-picker.png)',+ backgroundSize: 'cover',+ backgroundPosition: 'center',+ backgroundRepeat: 'no-repeat',},+ // Per-theme wordmark color override. Most image-backed cards use+ // --color-accent for the wordmark so the brand signature reads+ // as the dominant text element on top of the photo backdrop+ // (the default --color-text-primary often disappears into a+ // busy image, whereas the theme's accent provides natural+ // contrast against the rest of the brand-colored artwork).+ // The token resolves inside each card's own <XDSTheme> wrapper,+ // so each card picks up its theme's accent — Butter's brand+ // blue, Gothic's accent, etc.+ labelAccent: {+ color: 'var(--color-accent)',+ },+ // White wordmark override for cards whose photo backdrop is too+ // dark / busy for the theme accent to read against (e.g. Stone's+ // dark thistle photo). Uses --color-on-dark which resolves to+ // white in both modes.+ labelOnDark: {+ color: 'var(--color-on-dark)',+ },+ // Theme name on top of the gradient — rendered in the theme's+ // heading font so the wordmark previews the brand at a glance.+ // Color uses --color-text-primary so it reads against the soft+ // gradient backdrop in both light and dark themes.+ //+ // Fixed fontSize (24px) overrides each theme's own heading type-+ // scale so the picker reads at a uniform size across all 6 cards.+ // Without this, themes with larger heading defaults (e.g. Gothic's+ // Manufacturing Consent display family) render noticeably bigger+ // than themes with smaller defaults. Wide-glyph cursive fonts+ // (e.g. Matcha's script) still render visually wider than sans-+ // serif fonts at the same nominal size — that's a function of+ // the font's character widths, not the size — so we add ellipsis+ // truncation as a defensive measure for the longest wordmarks.+ //+ // position:relative + zIndex:1 keeps the wordmark sitting cleanly+ // on top of the multi-gradient stack underneath.+ themeCardLabel: {+ // Don't pin fontFamily — let each theme's type:display-3+ // component override drive the typography. That way Butter+ // renders in Sarina (cursive), Gothic in Manufacturing Consent+ // (distressed display), and themes without a display family+ // override fall back to their heading font (Outfit, system,+ // etc.). The XDSText below uses type="display-3" so the+ // .xds-text.display-3 selector in each theme's @scope'd CSS+ // applies the right family per card.+ fontSize: 32,+ lineHeight: 1.2,+ color: 'var(--color-text-primary)',+ maxWidth: '100%',+ whiteSpace: 'nowrap' as const,+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ position: 'relative' as const,+ zIndex: 1,+ },+ // 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).+ mobileBar: {+ display: 'none',+ [SIDEBAR_BREAKPOINT]: {+ display: 'flex',+ flexDirection: 'row' as const,+ alignItems: 'center',+ gap: 'var(--spacing-2)',+ padding: 'var(--spacing-2)',+ borderRadius: 'var(--radius-full)',+ borderWidth: 'var(--border-width)',+ borderStyle: 'solid',+ borderColor: 'var(--color-border)',+ backgroundColor: 'var(--color-background-card)',+ boxShadow: 'var(--shadow-high)',+ position: 'fixed' as const,+ bottom: 'var(--spacing-4)',+ left: '50%',+ transform: 'translateX(-50%)',+ zIndex: 100,+ width: 'fit-content',+ maxWidth: `calc(100vw - var(--spacing-4) * 2)`,+ },+ },+ // Mobile selector — fixed minimum so the dropdown trigger has+ // room for the longest theme label without forcing the floating+ // pill to span the entire viewport. No flex:1 here (the parent+ // is fit-content sized, not a stretched row).+ mobileSelector: {+ minWidth: 160,+ },+ // Preview card — unchanged from the floating-toolbar version.+ // Matches the "wide content" max-width used across the site+ // (home page showcases, docs index). Keeps the showcase from+ // running viewport-edge to viewport-edge on very wide screens+ // while staying noticeably wider than the 800px prose column+ // above it so the showcase grid still has room to breathe.previewCard: {overflow: 'hidden',- // Match the "wide content" max-width used across the site- // (home page showcases, docs index). Keeps the showcase from- // running viewport-edge to viewport-edge on very wide screens- // while staying noticeably wider than the 800px prose column- // above it so the showcase grid still has room to breathe.maxWidth: 1200,width: '100%',marginInline: 'auto',@@ -68,240 +427,382 @@ const styles = stylex.create({// color, which is what users would see in their own app.backgroundColor: 'var(--color-background-body)',},- // Floating footer wrapper — fixed-positioned strip across the- // viewport bottom. `pointerEvents: 'none'` lets clicks pass- // through the empty space on either side of the centered pill;- // the pill itself overrides this back to 'auto'.- //- // Subtle "rise from below + fade in" entrance plays once on- // mount with a ~300ms delay so the toolbar reads as deliberately- // arriving after the page content settles, instead of being part- // of the initial paint. animation-fill-mode: both holds the- // pre-animation state (translateY(8px) + opacity 0) during the- // delay so the toolbar isn't visible-but-static before it slides.- floatingFooter: {- position: 'fixed',- bottom: 'var(--spacing-4)',- left: 'var(--spacing-4)',- right: 'var(--spacing-4)',- zIndex: 100,- pointerEvents: 'none',- animationName: floatingFooterEntrance,- animationDuration: '520ms',- animationDelay: '800ms',- animationTimingFunction: 'cubic-bezier(0.16, 1, 0.3, 1)',- animationFillMode: 'both',- '@media (prefers-reduced-motion: reduce)': {- animationName: 'none',- },- },- // Pill chrome — uses XDSCard default variant (which already- // applies --color-background-card + --color-border) wrapped in- // an XDSToolbar for layout + a11y. We layer max-width, centering,- // pill radius, and shadow on top via xstyle.- //- // max-width is intentionally wider than the page's content cap- // (~960px) so the footer extends past the column of theme content- // above it — making the floating chrome obvious rather than- // appearing to "belong" to the content column above. User- // feedback noted the footer was easy to miss when it matched- // the content width.- floatingFooterCard: {- pointerEvents: 'auto',- maxWidth: 1280,+ // Matches the preview card's 1200px max-width so the card+ // showcase visually aligns with the preview above it.+ showcaseBlock: {+ width: '100%',+ maxWidth: 1200,marginInline: 'auto',- borderRadius: 'var(--radius-full)',- boxShadow: 'var(--shadow-high)',},- // Take the remaining horizontal space between the back button- // and the action cluster so title/description align nicely.- floatingFooterTitle: {- flex: 1,- minWidth: 0,+});++// Per-theme override registry for the picker cards. Themes without+// an entry here render with the default radial-gradient backdrop+// + default --color-text-primary wordmark. Themes WITH an entry+// can swap the card's `surface` (background image) and the `label`+// color (most use labelAccent so the wordmark reads as a brand+// signature on top of the photo). Adding artwork for a new theme+// is a two-step addition: drop a public/theme-<slug>-picker.png+// file + a `surface<Name>` rule into the styles block above, then+// reference both here.+const PICKER_OVERRIDES: Record<+ string,+ {surface: StyleXStyles; label?: StyleXStyles}+> = {+ '@xds/theme-butter': {+ surface: styles.surfaceButter,+ label: styles.labelAccent,},- // Single-line truncation keeps the pill compact; on narrow- // viewports the description hides entirely so the action- // cluster stays reachable.- floatingFooterDescription: {- overflow: 'hidden',- textOverflow: 'ellipsis',- whiteSpace: 'nowrap',- display: {- default: 'block',- '@media (max-width: 640px)': 'none',- },+ '@xds/theme-gothic': {+ surface: styles.surfaceGothic,+ label: styles.labelAccent,},-});+ '@xds/theme-y2k': {surface: styles.surfaceY2k, label: styles.labelAccent},+ '@xds/theme-stone': {surface: styles.surfaceStone, label: styles.labelOnDark},+ '@xds/theme-neutral': {+ surface: styles.surfaceNeutral,+ label: styles.labelAccent,+ },+ '@xds/theme-matcha': {+ surface: styles.surfaceMatcha,+ label: styles.labelAccent,+ },+};interface ThemePackagePageProps {- /** Vanity display title shown as the page heading (e.g. "Neutral"). */- title: string;- /** Full npm package name shown as small metadata below the title. */+ /** Full npm package name — seeds the initial selected theme. */packageName: string;- description?: string;- version?: string;- /**- * Raw README markdown for the package. Rendered inside the Install- * dialog (verbatim minus the top-level H1) — the dedicated page- * itself doesn't surface README content inline, so the brand- * experience (title + description + live themed preview) isn't- * crowded by setup docs.- */- readme: string | null;theme: XDSDefinedTheme;}-export function ThemePackagePage({- title,- packageName,- description,- version,- readme,- theme,-}: ThemePackagePageProps) {- // Strip the leading "# <title>" since the dialog header already- // shows the title — avoids a redundant heading at the top of the- // rendered markdown body.- const readmeBody = readme ? readme.replace(/^# .+\n+/, '') : null;+export function ThemePackagePage({packageName, theme}: ThemePackagePageProps) {const [mode, setMode] = useState<'light' | 'dark'>('light');- const [isInstallOpen, setIsInstallOpen] = useState(false);- const versionSuffix = version ? ` · ${version}` : '';- // Resolve the product image set for this theme (falls back to- // neutral if the theme doesn't have its own set yet).- const images = getThemeImages(theme.name);+ // 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+ // sidebar / mobile dropdown. State is locally owned; the URL is+ // an OUTPUT that we update imperatively in `handleSelectPkg`+ // below — we intentionally do NOT subscribe to `useSearchParams`+ // here, since that would create a feedback loop (URL change →+ // state sync → URL change → ...).+ const [selectedPkgName, setSelectedPkgName] = useState<string>(packageName);+ const router = useRouter();+ const pathname = usePathname();- return (- <XDSVStack gap={8} xstyle={styles.page}>- <XDSTheme theme={theme} mode={mode}>- <XDSCard padding={0} variant="transparent" xstyle={styles.previewCard}>- <ThemeShowcasePreview images={images} />- </XDSCard>- </XDSTheme>+ // 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 —+ // the seed the server uses when no query param is present — and+ // every other theme renders as `/themes?theme=<slug>`. Matches+ // the canonical URL the deep-link redirect at /themes/[name]+ // sends users to, so internal links, share URLs, and the+ // picker-driven URL all agree.+ //+ // `replace` (not `push`): theme selection reads as a filter on+ // the explorer, not a navigation step. Rapid clicks shouldn't+ // pollute the back stack — one Back press should exit the+ // explorer entirely (matching how Vercel / Linear / Sentry+ // handle in-page filters), not rewind through every preview+ // the user skimmed.+ //+ // `scroll: false`: the sidebar is sticky and the right pane is+ // tall, so we don't want a picker click to yank the user back+ // to the top of the page.+ const handleSelectPkg = useCallback(+ (nextPkgName: string) => {+ setSelectedPkgName(nextPkgName);+ const url =+ nextPkgName === DEFAULT_THEME_PACKAGE+ ? pathname+ : `${pathname}?theme=${encodeURIComponent(packageNameToSlug(nextPkgName))}`;+ router.replace(url, {scroll: false});+ },+ [router, pathname],+ );- {/* Real-world card showcase — sits OUTSIDE the live preview- card so it renders on the docsite's own astryx chrome- rather than nested inside the theme's body color.- Inventory + Checkout + Top customers cards flip light/- dark in sync with the preview above via the mode prop. */}- <div {...stylex.props(styles.showcaseBlock)}>- <ThemeCardShowcase theme={theme} images={images} mode={mode} />- </div>+ // Sorted list of all theme packages — feeds the sidebar list and+ // the mobile dropdown. Order matches the /themes overview gallery.+ const themePackages = useMemo(() => {+ return packages+ .filter(+ p =>+ p.name.startsWith('@xds/theme-') && p.name !== '@xds/theme-default',+ )+ .sort((a, b) => {+ const ai = THEME_ORDER.indexOf(a.name);+ const bi = THEME_ORDER.indexOf(b.name);+ if (ai === -1 && bi === -1) {+ return a.name.localeCompare(b.name);+ }+ if (ai === -1) {+ return 1;+ }+ if (bi === -1) {+ return -1;+ }+ return ai - bi;+ });+ }, []);- {/* Install dialog — the single canonical surface for setup- info. Renders the full README inline so the dedicated- page stays focused on the brand/preview experience and- all install + advanced setup docs live behind the- explicit "Install" CTA. */}- <XDSDialog- isOpen={isInstallOpen}- onOpenChange={setIsInstallOpen}- width={720}>- <XDSLayout- header={- <XDSDialogHeader- title={`Install ${title}`}- subtitle={`${packageName}${versionSuffix}`}- onOpenChange={setIsInstallOpen}- />- }- content={- <XDSLayoutContent>- {readmeBody ? (- <XDSMarkdown headingLevelStart={3} contentWidth={680}>- {readmeBody}- </XDSMarkdown>- ) : (+ // Resolve the currently-selected theme object. Falls back to the+ // SSR-seeded prop if the lookup ever misses (shouldn't happen —+ // the selector only offers options sourced from the same packages+ // list — but the guard keeps the page from crashing if the+ // registry drifts).+ const selectedTheme = themeObjects[selectedPkgName] ?? theme;+ // Resolve the product image set for the selected theme (falls back+ // to neutral if the theme doesn't have its own set yet).+ const images = getThemeImages(selectedTheme.name);++ // Mobile dropdown options — mirror the sidebar list. Value is the+ // full @xds/theme-<slug> package name (matches state), label is+ // the friendly brand wordmark ("Neutral", "Butter").+ const switcherOptions = useMemo(+ () =>+ themePackages.map(p => ({+ value: p.name,+ label: themeLabel(p.displayName) || p.displayName,+ })),+ [themePackages],+ );++ // Shared action cluster reused by both the sidebar (vertical+ // stack) and the mobile bar (inline row). Hoisted so the two+ // placements stay byte-identical — adding a button updates both.+ const modeToggleLabel =+ mode === 'light'+ ? 'Switch preview to dark mode'+ : 'Switch preview to light mode';+ const modeToggleIcon =+ mode === 'light' ? <Moon size={20} /> : <Sun size={20} />;++ // Plays a slide-left + fade-out animation on the whole page when+ // the user clicks Customize, then navigates to the playground+ // after the animation duration. Reads as 'launching into the+ // playground' rather than an abrupt route change.+ //+ // CSS-only; the animation uses XDS motion tokens+ // (--duration-medium + --ease-standard) so it stays in sync with+ // the rest of the app's motion. Modifier-clicks (cmd/middle)+ // skip the animation and open in a new tab normally.+ const [isLeaving, setIsLeaving] = useState(false);+ const customizeHref = `/themes/playground/${selectedTheme.name}`;+ const handleCustomizeClick = useCallback(+ (event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => {+ if (+ event.metaKey ||+ event.ctrlKey ||+ event.shiftKey ||+ event.altKey ||+ event.button !== 0+ ) {+ return;+ }+ event.preventDefault();+ setIsLeaving(true);+ // Wait for the leave animation to play, then navigate. Length+ // matches --duration-medium (~410ms); we use a slight buffer+ // so the navigation kicks in just as the animation ends. The+ // destination playground page handles its own entry animation+ // declaratively via CSS @starting-style (no cross-page state+ // signaling needed — first paint of the editor + preview+ // panels animates in unconditionally).+ window.setTimeout(() => {+ router.push(customizeHref);+ }, 420);+ },+ [router, customizeHref],+ );++ return (+ <div {...stylex.props(styles.twoColumn)}>+ {/* Sidebar — sticky on desktop, hidden on narrow viewports+ (the mobile bar in the right column takes over). Holds:+ hero block (heading + description + Customize CTA + mode+ toggle), divider, and the theme picker (one card per+ theme). */}+ <aside+ {...stylex.props(styles.sidebar, isLeaving && styles.sidebarLeaving)}+ aria-label="Theme picker">+ <XDSCard variant="default" padding={0} xstyle={styles.sidebarCard}>+ <XDSVStack 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. */}+ <XDSVStack gap={3}>+ <XDSVStack gap={2}>+ <XDSHeading level={1} type="display-3">+ Themes+ </XDSHeading><XDSText type="body" color="secondary">- No setup documentation is available for this theme yet.+ 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>- )}- </XDSLayoutContent>- }- />- </XDSDialog>-- {/* Floating footer — pinned to the bottom of the viewport with- the page's title, description, mode toggle, and Install- CTA. Uses XDSToolbar (for layout slots + roving tabindex- a11y) nested inside an XDSCard (for the pill chrome —- card surface, border, and shadow tokens). Bottom padding- on the outer page wrapper (styles.page) ensures the last- card row can scroll clear of the footer. */}- <div {...stylex.props(styles.floatingFooter)}>- <XDSCard- padding={3}- variant="default"- xstyle={styles.floatingFooterCard}>- <XDSToolbar- label="Theme actions"- gap={3}- startContent={- // Back button + title cluster. Lives together in- // startContent so the title stays left-aligned with- // the back button rather than centered between the- // slots (XDSToolbar's centerContent uses an auto-- // width center column, which would shrink the title- // instead of letting it fill the space).- <XDSHStack gap={3} vAlign="center">+ </XDSVStack>+ {/* 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+ preview controls; the theme list below stays a+ pure picker. */}+ <XDSHStack gap={2} vAlign="center"><XDSButton- variant="ghost"- size="md"- label="Back to all themes"- tooltip="Back to all themes"- isIconOnly- icon={<ArrowLeft />}- href="/themes"+ variant="primary"+ size="lg"+ label="Customize"+ href={customizeHref}+ onClick={handleCustomizeClick}+ xstyle={styles.heroPrimaryButton}/>- <XDSVStack gap={0} xstyle={styles.floatingFooterTitle}>- <XDSText type="body" weight="bold">- {title}- </XDSText>- {description && (- <XDSText- type="supporting"- color="secondary"- xstyle={styles.floatingFooterDescription}>- {description}- </XDSText>- )}- </XDSVStack>- </XDSHStack>- }- endContent={- <XDSHStack gap={2} vAlign="center"><XDSButtonvariant="ghost"+ size="lg"isIconOnly- label={- mode === 'light'- ? 'Switch preview to dark mode'- : 'Switch preview to light mode'- }- tooltip={- mode === 'light'- ? 'Switch preview to dark mode'- : 'Switch preview to light mode'- }- icon={- mode === 'light' ? <Moon size={20} /> : <Sun size={20} />- }+ label={modeToggleLabel}+ tooltip={modeToggleLabel}+ icon={modeToggleIcon}onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}/>- <XDSButton- label="Customize"- variant="secondary"- href={`/themes/playground/${theme.name}`}- />- <XDSButton- label="Install"- variant="primary"- onClick={() => setIsInstallOpen(true)}- /></XDSHStack>- }- />+ </XDSVStack>++ <XDSDivider />++ {/* Theme list — one XDSSelectableCard per theme. Each+ card's inner content is wrapped in <XDSTheme> so the+ background color + heading typography reflect the+ theme it represents, giving users a miniature brand+ preview right in the picker. XDSSelectableCard+ handles selection state (inset accent border),+ aria-selected, and focus chrome. */}+ <div {...stylex.props(styles.themeList)}>+ {themePackages.map(pkg => {+ const cardTheme = themeObjects[pkg.name];+ const isActive = pkg.name === selectedPkgName;+ const label = themeLabel(pkg.displayName) || pkg.displayName;+ // Per-theme bespoke artwork lookup. Themes without an+ // entry render with the default radial-gradient+ // backdrop + default wordmark color; themes WITH an+ // entry get a custom photo background + brand-accent+ // wordmark.+ const override = PICKER_OVERRIDES[pkg.name];+ return (+ <XDSSelectableCard+ key={pkg.name}+ label={`Preview ${label} theme`}+ isSelected={isActive}+ onChange={() => handleSelectPkg(pkg.name)}+ padding={0}+ variant="transparent"+ xstyle={styles.themeCard}>+ {cardTheme ? (+ // Always render mini cards in light mode so the+ // picker reads as a stable swatch palette,+ // even when the user has flipped the preview+ // mode toggle to dark. (The dark-mode brand+ // colors for some themes are much darker,+ // which would make the picker look gloomy.)+ <XDSTheme theme={cardTheme} mode="light">+ <div+ {...stylex.props(+ styles.themedSurface,+ // StyleX's props() walks rest args strictly;+ // pass `false` (not `undefined`) when there's+ // no override so the call doesn't choke.+ override?.surface ?? false,+ )}>+ <XDSText+ type="display-3"+ weight="bold"+ xstyle={[+ styles.themeCardLabel,+ override?.label ?? false,+ ]}>+ {label}+ </XDSText>+ </div>+ </XDSTheme>+ ) : (+ <div {...stylex.props(styles.themedSurface)}>+ <XDSText+ type="display-3"+ weight="bold"+ xstyle={styles.themeCardLabel}>+ {label}+ </XDSText>+ </div>+ )}+ </XDSSelectableCard>+ );+ })}+ </div>+ </XDSVStack></XDSCard>+ </aside>++ {/* Right column — themed preview + card showcase. The mobile+ 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)}>+ <div {...stylex.props(styles.mobileSelector)}>+ <XDSSelector+ label="Theme"+ isLabelHidden+ size="sm"+ options={switcherOptions}+ value={selectedPkgName}+ onChange={handleSelectPkg}+ />+ </div>+ <XDSButton+ variant="ghost"+ size="sm"+ isIconOnly+ label={modeToggleLabel}+ tooltip={modeToggleLabel}+ icon={modeToggleIcon}+ onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}+ />+ </div>++ <XDSTheme theme={selectedTheme} mode={mode}>+ <XDSCard+ padding={0}+ variant="transparent"+ xstyle={styles.previewCard}>+ <ThemeShowcasePreview images={images} />+ </XDSCard>+ </XDSTheme>++ {/* Real-world card showcase — sits OUTSIDE the live preview+ card so it renders on the docsite's own astryx chrome+ rather than nested inside the theme's body color.+ Inventory + Checkout + Top customers cards flip light/+ dark in sync with the preview above via the mode prop. */}+ <div {...stylex.props(styles.showcaseBlock)}>+ <ThemeCardShowcase+ theme={selectedTheme}+ images={images}+ mode={mode}+ />+ </div></div>- </XDSVStack>+ </div>);}diff --git a/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx b/apps/docsite/src/components/themePlayground/ThemeEditorView.tsxindex 6a7905168d..39dbd8a23d 100644--- a/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx+++ b/apps/docsite/src/components/themePlayground/ThemeEditorView.tsx@@ -3,7 +3,9 @@'use client';import * as React from 'react';+import * as stylex from '@stylexjs/stylex';import {useRouter} from 'next/navigation';+import {durationVars, easeVars} from '@xds/core/theme/tokens.stylex';import {XDSButton} from '@xds/core/Button';import {XDSCard} from '@xds/core/Card';import {XDSHStack, XDSVStack} from '@xds/core/Stack';@@ -79,6 +81,59 @@ interface ThemeEditorViewProps {initialTheme: XDSDefinedTheme;}+// First-paint entry animations. Each rule sits in its resting "to"+// state on the element; the `@starting-style` block declares the+// "from" state, and a `transition` interpolates between them. The+// browser runs the transition exactly once — on first paint, the+// element's initial computed style comes from @starting-style; on+// the very next frame it resolves to the rule's normal style and+// the transition plays. No JS coordination, no cross-page flag,+// no race conditions: each mount of this view animates in, period.+//+// Motion tokens (--duration-medium + --ease-standard) keep the+// entry in sync with the rest of XDS. prefers-reduced-motion+// shortens the transition to ~0 so reduced-motion users get an+// instant resolve instead of a noticeable slide / scale.+const entryStyles = stylex.create({+ // Editor panel slides in from the left. Mirrors the leave-side+ // sidebar animation on /themes so the two halves chain into a+ // single "panel swap" rather than reading as a hard cut.+ editor: {+ transform: 'translateX(0)',+ opacity: 1,+ transitionProperty: 'transform, opacity',+ transitionDuration: {+ default: durationVars['--duration-medium'],+ '@media (prefers-reduced-motion: reduce)': '0.01ms',+ },+ transitionTimingFunction: easeVars['--ease-standard'],+ '@starting-style': {+ transform: 'translateX(-100%)',+ opacity: 0,+ },+ },+ // Preview entry — scale + fade. Starts at 95% scale to mirror the+ // canonical XDS layerAnimations pattern (used for popovers, dropdown+ // menus, hover cards, tooltips). Reads as the preview "settling+ // into place" rather than just fading in flat. transform-origin+ // stays at the default 50% 50% so the scale-up reads as growing+ // outward from the preview's visual center.+ preview: {+ transform: 'scale(1)',+ opacity: 1,+ transitionProperty: 'transform, opacity',+ transitionDuration: {+ default: durationVars['--duration-medium'],+ '@media (prefers-reduced-motion: reduce)': '0.01ms',+ },+ transitionTimingFunction: easeVars['--ease-standard'],+ '@starting-style': {+ transform: 'scale(0.95)',+ opacity: 0,+ },+ },+});+export function ThemeEditorView({themeId,themeLabel,@@ -414,6 +469,7 @@ export function ThemeEditorView({{/* Left Panel — Editor */}<div+ {...stylex.props(entryStyles.editor)}style={{width: editor.size || 400,minWidth: 348,@@ -498,6 +554,7 @@ export function ThemeEditorView({{/* Right Panel — Preview */}<div+ {...stylex.props(entryStyles.preview)}style={{flex: 1,display: 'flex',diff --git a/packages/themes/butter/src/butterTheme.ts b/packages/themes/butter/src/butterTheme.tsindex 26e45d2fda..e4d49ef76a 100644--- a/packages/themes/butter/src/butterTheme.ts+++ b/packages/themes/butter/src/butterTheme.ts@@ -520,6 +520,23 @@ export const butterTheme = defineTheme({'status:warning': {'--color-warning': '#ffc502'},'status:error': {'--color-error': '#fc473b'},},++ // Display sizes use Sarina — the signature buttery display+ // cursive, reserved for hero/marketing-scale text only.+ // Headings (h1–h6) and body still use Outfit (configured above+ // under typography.heading / typography.body). Same pattern+ // Gothic uses for its Manufacturing Consent display family.+ text: {+ 'type:display-1': {+ fontFamily: 'Sarina, "Brush Script MT", "Snell Roundhand", cursive',+ },+ 'type:display-2': {+ fontFamily: 'Sarina, "Brush Script MT", "Snell Roundhand", cursive',+ },+ 'type:display-3': {+ fontFamily: 'Sarina, "Brush Script MT", "Snell Roundhand", cursive',+ },+ },},icons: butterIconRegistry,