Skip to content

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.png
new file mode 100644
index 0000000000..486e6788c1
Binary files /dev/null and b/apps/docsite/public/theme-butter-picker.png differ
diff --git a/apps/docsite/public/theme-gothic-picker.png b/apps/docsite/public/theme-gothic-picker.png
new file mode 100644
index 0000000000..826253a43e
Binary files /dev/null and b/apps/docsite/public/theme-gothic-picker.png differ
diff --git a/apps/docsite/public/theme-matcha-picker.png b/apps/docsite/public/theme-matcha-picker.png
new file mode 100644
index 0000000000..51b011c1e2
Binary files /dev/null and b/apps/docsite/public/theme-matcha-picker.png differ
diff --git a/apps/docsite/public/theme-neutral-picker.png b/apps/docsite/public/theme-neutral-picker.png
new file mode 100644
index 0000000000..b88cddfa74
Binary files /dev/null and b/apps/docsite/public/theme-neutral-picker.png differ
diff --git a/apps/docsite/public/theme-stone-picker.png b/apps/docsite/public/theme-stone-picker.png
new file mode 100644
index 0000000000..8d5f6cb117
Binary files /dev/null and b/apps/docsite/public/theme-stone-picker.png differ
diff --git a/apps/docsite/public/theme-y2k-picker.png b/apps/docsite/public/theme-y2k-picker.png
new file mode 100644
index 0000000000..21153ae063
Binary files /dev/null and b/apps/docsite/public/theme-y2k-picker.png differ
diff --git a/apps/docsite/src/app/(site)/themes/[name]/page.tsx b/apps/docsite/src/app/(site)/themes/[name]/page.tsx
index 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.tsx
index 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.css
index 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-sh
background: var(--color-background-body);
backdrop-filter: none;
}
+
diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsx
index 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}) {
/>
<link
rel="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.tsx
index 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.tsx
index 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">
<XDSButton
variant="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.tsx
index 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.ts
index 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,