An open source design system that's fully customizable and agent ready
TypeScript
docsite(themes): mirror templates overview structure with hover overlay (#2489)
rubyycheung95d0d464a46e
diff --git a/apps/docsite/src/app/(site)/themes/page.tsx b/apps/docsite/src/app/(site)/themes/page.tsxindex ef04fbb7c7..f72906fcc7 100644--- a/apps/docsite/src/app/(site)/themes/page.tsx+++ b/apps/docsite/src/app/(site)/themes/page.tsx@@ -12,6 +12,7 @@ import {XDSHStack, XDSVStack} from '@xds/core/Layout';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,@@ -37,7 +38,7 @@ const STRUCTURAL_TOKEN_OVERRIDES: React.CSSProperties = {...radiusDefaults,...textSizeDefaults,height: '100%',-} as React.CSSProperties;+};// Gallery order — themes are sorted by visual closeness, starting// from the most restrained / brand-neutral and ending at the most@@ -137,15 +138,89 @@ const styles = stylex.create({overflow: 'hidden',},- // The outer XDSCard sized to fill its grid cell at full height- // so every card in a row matches the tallest. Without this, the- // XDSCard sizes to content and the grid stretch doesn't reach- // the inner tile.+ // 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)',+ },});+// 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-/, '');+}++// 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)',+};+export default function ThemesPage() {const {mode} = useThemeMode();return (@@ -193,31 +268,94 @@ export default function ThemesPage() {const label = pkg.displayName.replace(/^Theme:\s*/, '').replace(/\s*Theme$/, '');+ const slug = themeSlug(pkg.name);return (<XDSCardkey={pkg.name}padding={0}variant="transparent"xstyle={styles.cardFill}>- <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}- />+ {/* Tile is fully presentational. Navigation is+ handled exclusively by the two XDSButtons inside+ the hover overlay ("Preview" → /themes/<slug>;+ "Open in Playground" → /themes/playground/<slug>).+ 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={`/themes/playground/${slug}`}+ />+ </XDSHStack>+ </XDSVStack></div>- </XDSTheme>- ) : (- <div {...stylex.props(styles.cardImage)} />- )}+ }>+ <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>);diff --git a/apps/docsite/src/components/ThemeShowcaseTile.tsx b/apps/docsite/src/components/ThemeShowcaseTile.tsxindex c214d46420..016c32eb76 100644--- a/apps/docsite/src/components/ThemeShowcaseTile.tsx+++ b/apps/docsite/src/components/ThemeShowcaseTile.tsx@@ -30,7 +30,6 @@ import {import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSTextInput} from '@xds/core/TextInput';import {XDSBadge} from '@xds/core/Badge';-import {XDSClickableCard} from '@xds/core/ClickableCard';// Below 800px viewport, the tile's left card + right column stack// vertically (instead of side-by-side). The 2-column tile layout@@ -111,28 +110,28 @@ const styles = stylex.create({[TILE_STACK_BREAKPOINT]: {flexDirection: 'column',},- // Hover/active/focus chrome (5% ::after on :hover, 10% on- // :active, focus-visible outline) is provided by the outer- // XDSClickableCard — no need to reimplement here. But we- // still override two pieces of its visual treatment:+ // The tile is purely presentational — no card-wide click target,+ // no hover/active overlay. Navigation is handled by the two+ // XDSButtons inside the hover overlay rendered above this tile+ // (see /themes/page.tsx). We still override two pieces of the+ // XDSCard chrome://- // 1. backgroundColor: XDSClickableCard's default variant- // paints --color-background-card (lifted surface tone).- // Theme tiles need to sit on the theme's body color so- // the hero image, banners, and form controls inside the- // tile read as a continuous themed surface (matches what- // a real themed app looks like, where everything sits on- // --color-background-body).+ // 1. backgroundColor: XDSCard's default variant paints+ // --color-background-card (lifted surface tone). Theme tiles+ // need to sit on the theme's body color so the hero image,+ // banners, and form controls inside the tile read as a+ // continuous themed surface (matches what a real themed app+ // looks like, where everything sits on --color-background-body).// 2. overflow: hidden: without this, the hero image and the// right-column banners at the card edges paint past the- // rounded corners XDSClickableCard sets via its radius.+ // rounded corners XDSCard sets via its radius.backgroundColor: colorVars['--color-background-body'],overflow: 'hidden',// Drop the XDSCard default variant's --color-border-emphasized// border so the tile reads as a continuous themed surface- // rather than a bordered card-on-card. The hover/focus- // affordance comes from XDSClickableCard's ::after overlay- // and focus-visible outline, not from a static border.+ // rather than a bordered card-on-card. The dark hover scrim+ // from XDSOverlay (rendered around this tile) is the only+ // hover affordance — no static border needed.borderColor: 'transparent',width: '100%',height: '100%',@@ -255,8 +254,9 @@ const styles = stylex.create({// checkbox) row and the banner stack in the right column.// Holds the Primary / Secondary / Ghost button samples — demos// the theme's button chrome. Buttons are passive samples (the- // right column carries `inert`), not interactive CTAs: the- // entire tile is itself a single link to the theme page.+ // right column carries `inert`), not interactive CTAs — the+ // real navigation lives in the hover overlay's Preview / Open+ // in Playground buttons rendered around this tile.actionRow: {display: 'flex',alignItems: 'center',@@ -434,22 +434,9 @@ export function ThemeShowcaseTile({}, [themeName]);const imageSrc = candidates[candidateIndex];const showImage = imageSrc !== undefined;- // Theme detail page URL. Strip the `@xds/theme-` prefix from the- // package name to match the [name] segment of /themes/[name],- // which is the canonical destination. Linking directly here- // avoids a client-side redirect from the old /packages/theme-*- // route (which redirects to /themes/*) — that redirect was- // surfacing as a visible layout shift on click.- const themeHref = themeName- ? `/themes/${themeName.replace(/^@xds\/theme-/, '')}`- : undefined;return (- <XDSClickableCard- label={`Open ${label} theme`}- href={themeHref}- padding={0}- xstyle={styles.tile}>+ <XDSCard padding={0} xstyle={styles.tile}>{/* Left column: theme card wrapped in XDSCard for a self-contained surface (border, background, radius). */}<div {...stylex.props(styles.leftColumn)}>@@ -597,9 +584,9 @@ export function ThemeShowcaseTile({gap between groups for clear visual hierarchy. Inert soevery showcase component (input, progress, table, formcontrols, banners, Primary/Secondary button samples)- reads as a passive demo — the whole tile is itself a- link to the theme page, which is the only interactive- surface. */}+ reads as a passive demo — the only interactive surfaces+ are the two XDSButtons inside the hover overlay+ rendered around this tile (see /themes/page.tsx). */}<div {...stylex.props(styles.rightColumn)} inert>{/* Group 1 — form-input components (text input + progressbar). Both are data-input/feedback elements so they@@ -703,6 +690,6 @@ export function ThemeShowcaseTile({<XDSBanner status="error" title="Banner Title" /></XDSVStack></div>- </XDSClickableCard>+ </XDSCard>);}