Skip to content

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.tsx
index 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 (
<XDSCard
key={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.tsx
index 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 so
every showcase component (input, progress, table, form
controls, 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 + progress
bar). 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>
);
}