Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docsite: landing refresh + community page polish (#2487)

rubyycheung63ede8fc8feb
diff --git a/apps/docsite/public/feature-brand.png b/apps/docsite/public/feature-brand.png
new file mode 100644
index 0000000000..acc1e42545
Binary files /dev/null and b/apps/docsite/public/feature-brand.png differ
diff --git a/apps/docsite/public/feature-bug.png b/apps/docsite/public/feature-bug.png
new file mode 100644
index 0000000000..9904d66ed2
Binary files /dev/null and b/apps/docsite/public/feature-bug.png differ
diff --git a/apps/docsite/public/feature-cli.png b/apps/docsite/public/feature-cli.png
new file mode 100644
index 0000000000..b34a241ce1
Binary files /dev/null and b/apps/docsite/public/feature-cli.png differ
diff --git a/apps/docsite/public/feature-components.png b/apps/docsite/public/feature-components.png
new file mode 100644
index 0000000000..343650c534
Binary files /dev/null and b/apps/docsite/public/feature-components.png differ
diff --git a/apps/docsite/public/feature-docs.png b/apps/docsite/public/feature-docs.png
new file mode 100644
index 0000000000..f2becd6545
Binary files /dev/null and b/apps/docsite/public/feature-docs.png differ
diff --git a/apps/docsite/public/feature-measured-and-tested.png b/apps/docsite/public/feature-measured-and-tested.png
new file mode 100644
index 0000000000..1afa32a0e7
Binary files /dev/null and b/apps/docsite/public/feature-measured-and-tested.png differ
diff --git a/apps/docsite/public/feature-templates.png b/apps/docsite/public/feature-templates.png
new file mode 100644
index 0000000000..432325e423
Binary files /dev/null and b/apps/docsite/public/feature-templates.png differ
diff --git a/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx b/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx
index 7bf721c34b..0846b2863a 100644
--- a/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx
+++ b/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx
@@ -9,7 +9,6 @@ import {XDSGrid} from '@xds/core/Grid';
import {XDSAspectRatio} from '@xds/core/AspectRatio';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSLink} from '@xds/core/Link';
-import {XDSBadge} from '@xds/core/Badge';
const styles = stylex.create({
headingBlock: {
@@ -26,6 +25,18 @@ const styles = stylex.create({
iconSlot: {
height: 40,
},
+ // "ABOUT US" eyebrow heading above the section title. Uppercase +
+ // tracked, matching the editorial treatment on the Features
+ // section above.
+ eyebrow: {
+ textTransform: 'uppercase',
+ letterSpacing: '0.08em',
+ },
+ // Constrain the description copy under the section heading so it
+ // doesn't run too wide; 560px reads as ~70 characters per line.
+ descriptionWidth: {
+ maxWidth: 560,
+ },
});
type AboutItem = {
@@ -126,11 +137,13 @@ const items: AboutItem[] = [
function AboutHeading() {
return (
<XDSVStack gap={4} align="center" xstyle={styles.headingBlock}>
- <XDSBadge variant="orange" label="About us" />
+ <XDSHeading level={4} color="primary" xstyle={styles.eyebrow}>
+ About us
+ </XDSHeading>
<XDSHeading level={2} type="display-2" color="primary">
Astryx powers over 13,000 apps
</XDSHeading>
- <XDSText type="body" color="secondary" style={{maxWidth: 560}}>
+ <XDSText type="body" color="secondary" xstyle={styles.descriptionWidth}>
Astryx has grown inside Meta over the last eight years, shaped by the
engineers, designers, and product teams who depend on it every day.
</XDSText>
diff --git a/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx b/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx
index 5c9ec461df..309305c1b7 100644
--- a/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx
+++ b/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx
@@ -8,7 +8,6 @@ import {XDSVStack} from '@xds/core/Layout';
import {XDSGrid} from '@xds/core/Grid';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSLink} from '@xds/core/Link';
-import {XDSBadge} from '@xds/core/Badge';
import {components} from '../../../generated/componentRegistry';
// Count of public @xds/core components (excluding hooks and hidden entries).
@@ -28,17 +27,26 @@ const styles = stylex.create({
width: '100%',
maxWidth: 680,
},
- // Layout glue for the XDSGrid: cap at 1200px and force every row to the
- // same height so the tall first card and the regular cards line up.
- // XDSGrid doesn't expose gridAutoRows or maxWidth as props, so we pass
- // them through xstyle.
+ // Layout glue for the XDSGrid: cap at 1200px. gridAutoRows: 1fr is
+ // intentionally NOT set here — it would force the tall first card
+ // (which spans 2 rows) to make every row at LEAST half its height,
+ // ballooning the regular cards out. With auto rows each row sizes
+ // to its actual content, and the tall card stretches naturally to
+ // fill both rows of whatever the regular row heights end up being.
gridLayout: {
width: '100%',
maxWidth: 1200,
- gridAutoRows: '1fr',
},
+ // Feature cards use the categorical "gray" variant, which Astryx
+ // re-tints to a warm beige via --color-background-gray (see
+ // astryxTheme.ts) so the cards sit as a recessed beige surface
+ // on the cream body background.
+ //
+ // overflow:hidden lets bleeding images (negative margin) clip
+ // cleanly at the rounded corners.
cardTall: {
height: '100%',
+ overflow: 'hidden',
gridRow: {
default: 'auto',
'@media (min-width: 720px)': 'span 2',
@@ -46,6 +54,100 @@ const styles = stylex.create({
},
card: {
height: '100%',
+ overflow: 'hidden',
+ },
+ // "KEY FEATURES" eyebrow heading above the section title. Uppercase
+ // + tracked, replacing the previous XDSBadge for a flatter editorial
+ // treatment that doesn't compete visually with the cards' own
+ // badge-like accents.
+ eyebrow: {
+ textTransform: 'uppercase',
+ letterSpacing: '0.08em',
+ },
+ // Constrain the description copy under the section heading so it
+ // doesn't run too wide. 420px reads as ~55 characters per line —
+ // a tighter cap than the other sections because the Features
+ // heading is short and a narrow description column visually
+ // balances it.
+ descriptionWidth: {
+ maxWidth: 420,
+ },
+ // Inner stack of the tall card — pushes the heading/text block to
+ // the top and lets the image grow into the leftover vertical space.
+ // height:100% so the stack itself fills the card body (cards are
+ // gridAutoRows: 1fr, so the row has a known height it can stretch
+ // into).
+ tallStack: {
+ height: '100%',
+ },
+ // Explore link spacing — VStack gap holds heading↔description at
+ // 4px, but the link below the description wants more breathing room
+ // (16px). Adding a top margin on the link gives the +12px extra
+ // beyond the 4px stack gap to reach the 16px total.
+ exploreLink: {
+ marginTop: 'calc(var(--spacing-3))',
+ },
+ // Shared image wrapper styles for any feature card with an image.
+ // marginTop:auto pushes the wrapper to the bottom of the card so
+ // every card's image sits on the same baseline regardless of how
+ // much text wraps above it. paddingTop:16 guarantees a 16px gap
+ // between the "Explore →" link and the image even on short cards.
+ // No fixed height — the inner <img> uses height:auto + width:100%
+ // so the wrapper grows to exactly the image's natural rendered
+ // height (preserves each composition's aspect ratio without
+ // distortion or empty padding). The negative marginBottom bleeds
+ // the image toward the card's bottom edge with a 16px gutter.
+ imageWrap: {
+ marginTop: 'auto',
+ paddingTop: 16,
+ marginBottom: 'calc(var(--spacing-5) * -1 + 16px)',
+ alignSelf: 'stretch',
+ overflow: 'hidden',
+ },
+ // Tall-card variant: image bleeds flush to the right edge of the
+ // card (full bleed right) but keeps a 16px inset on the left so
+ // the composition reads as anchored to the left padding rim.
+ // marginTop:auto + marginBottom:auto vertically centers the image
+ // in the leftover space below the heading/link content, so the
+ // tall card's empty space splits equally above and below the
+ // composition instead of all collecting at top or bottom.
+ imageWrapTall: {
+ marginInlineStart: 'calc(var(--spacing-5) * -1 + 16px)',
+ marginInlineEnd: 'calc(var(--spacing-5) * -1)',
+ marginTop: 'auto',
+ marginBottom: 'auto',
+ },
+ // Regular-card variant: 16px inset on BOTH sides so the image
+ // sits inside the card text padding minus the outer rim.
+ imageWrapRegular: {
+ marginInlineStart: 'calc(var(--spacing-5) * -1 + 16px)',
+ marginInlineEnd: 'calc(var(--spacing-5) * -1 + 16px)',
+ },
+ // Bleed-to-corner variant: drops the 16px right + bottom insets
+ // so the image runs flush to the card's right and bottom edges.
+ imageWrapBleedCorner: {
+ marginInlineEnd: 'calc(var(--spacing-5) * -1)',
+ marginBottom: 'calc(var(--spacing-5) * -1)',
+ },
+ // Bleed-bottom variant: drops only the 16px bottom inset so the
+ // image runs flush to the bottom edge while keeping the right
+ // inset.
+ imageWrapBleedBottom: {
+ marginBottom: 'calc(var(--spacing-5) * -1)',
+ },
+ // Image: full container width, natural height capped at 120px so
+ // regular cards stay compact. Wide compositions (CLI / Components)
+ // would otherwise render at their full aspect-ratio-derived
+ // height (~280px+ at desktop card widths) and pad the cards out
+ // taller than they need to be. object-fit:contain inside the
+ // capped height keeps each composition undistorted.
+ tallImage: {
+ width: '100%',
+ height: 'auto',
+ maxHeight: 120,
+ objectFit: 'contain',
+ objectPosition: 'bottom left',
+ display: 'block',
},
});
@@ -53,6 +155,31 @@ type Feature = {
title: string;
description: string;
href: string;
+ /**
+ * Optional supporting image rendered below the description. Used to
+ * give each card a visual anchor (code samples, component swatches,
+ * a cascading template stack, etc.).
+ */
+ image?: {
+ src: string;
+ alt: string;
+ /**
+ * When true, the image bleeds flush to the card's right and
+ * bottom edges (no 16px breathing room). Used by image
+ * compositions that are designed as "running off the corner"
+ * artwork — e.g. the cascading template stack — where the
+ * visual intent depends on having the corner clip.
+ */
+ bleedToCorner?: boolean;
+ /**
+ * When true, the image bleeds flush to the card's bottom edge
+ * only. Used for compositions that should keep their right-
+ * side breathing room but feel "rooted" at the bottom of the
+ * card — e.g. a full themed page mockup that reads as
+ * extending below the visible card frame.
+ */
+ bleedBottom?: boolean;
+ };
};
const features: Feature[] = [
@@ -61,55 +188,95 @@ const features: Feature[] = [
description:
'Every API choice is measured against real usage by people and LLMs before it ships.',
href: '/docs',
+ image: {
+ src: '/feature-measured-and-tested.png',
+ alt: 'A typescript code sample alongside a card preview and People / AI agents checks',
+ },
},
{
title: `Over ${CORE_COMPONENT_COUNT_ROUNDED} components`,
description:
'Accessible and themeable React components with built-in spacing, dark mode, and StyleX styling.',
href: '/components',
+ image: {
+ src: '/feature-components.png',
+ alt: 'Sample XDS components — Badge, Switch, Secondary button, Primary button, Search input',
+ },
},
{
- title: 'Themes that fit your brand',
+ title: 'Your design system on the command line',
description:
- 'Fully customizable themes ready for use. Make it yours without starting from scratch.',
- href: '/themes',
+ 'Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.',
+ href: '/docs/cli',
+ image: {
+ src: '/feature-cli.png',
+ alt: 'AI prompt input asking "Can you create me a table page" with a send button',
+ },
},
{
title: 'Ready to ship templates',
description:
'Production-ready templates for common pages, just plug in your content.',
href: '/templates',
+ image: {
+ src: '/feature-templates.png',
+ alt: 'Stacked theme preview pages cascading toward a fully designed Butter theme example',
+ bleedToCorner: true,
+ },
},
{
- title: 'Your design system on the command line',
+ title: 'Themes that fit your brand',
description:
- 'Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.',
- href: '/docs/cli',
+ 'Fully customizable themes ready for use. Make it yours without starting from scratch.',
+ href: '/themes',
+ image: {
+ src: '/feature-brand.png',
+ alt: 'Butter theme applied to a full product landing page with display script, primary CTA, and three product cards',
+ bleedBottom: true,
+ },
},
];
function FeatureCard({feature, isTall}: {feature: Feature; isTall?: boolean}) {
+ const showImage = feature.image != null;
return (
<XDSCard
- variant="default"
+ variant="gray"
padding={5}
xstyle={isTall ? styles.cardTall : styles.card}>
- <XDSVStack gap={6}>
- <XDSVStack gap={1} align="start">
- <XDSHeading level={3} color="primary">
- {feature.title}
- </XDSHeading>
- <XDSText type="body" color="secondary">
- {feature.description}
- </XDSText>
- </XDSVStack>
+ <XDSVStack
+ gap={1}
+ align="start"
+ xstyle={showImage ? styles.tallStack : undefined}>
+ <XDSHeading level={2} color="primary">
+ {feature.title}
+ </XDSHeading>
+ <XDSText type="body" color="primary">
+ {feature.description}
+ </XDSText>
<XDSLink
type="body"
color="primary"
href={feature.href}
- hasUnderline={true}>
- Explore
+ hasUnderline={false}
+ xstyle={styles.exploreLink}>
+ Explore →
</XDSLink>
+ {showImage && feature.image && (
+ <div
+ {...stylex.props(
+ styles.imageWrap,
+ isTall ? styles.imageWrapTall : styles.imageWrapRegular,
+ feature.image.bleedToCorner && styles.imageWrapBleedCorner,
+ feature.image.bleedBottom && styles.imageWrapBleedBottom,
+ )}>
+ <img
+ src={feature.image.src}
+ alt={feature.image.alt}
+ {...stylex.props(styles.tallImage)}
+ />
+ </div>
+ )}
</XDSVStack>
</XDSCard>
);
@@ -118,7 +285,9 @@ function FeatureCard({feature, isTall}: {feature: Feature; isTall?: boolean}) {
function FeaturesHeading() {
return (
<XDSVStack gap={4} align="center" xstyle={styles.headingBlock}>
- <XDSBadge variant="blue" label="Key features" />
+ <XDSHeading level={4} color="primary" xstyle={styles.eyebrow}>
+ Key features
+ </XDSHeading>
<XDSHeading level={2} type="display-2" color="primary">
Start&nbsp;anywhere. Change&nbsp;anything.&nbsp;Ship&nbsp;faster.
</XDSHeading>
@@ -126,7 +295,7 @@ function FeaturesHeading() {
display="block"
type="body"
color="secondary"
- style={{maxWidth: 420}}>
+ xstyle={styles.descriptionWidth}>
A design system that adapts to your workflow, not the other way around.
Built for speed, clarity, and creative freedom.
</XDSText>
diff --git a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
index 895aebcd92..23fe3ba3fe 100644
--- a/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
+++ b/apps/docsite/src/app/(site)/_landing/ThemingShowcase.tsx
@@ -4,132 +4,247 @@
import * as stylex from '@stylexjs/stylex';
import {XDSText, XDSHeading} from '@xds/core/Text';
-import {XDSLink} from '@xds/core/Link';
-import {XDSDivider} from '@xds/core/Divider';
import {XDSHStack, XDSVStack} from '@xds/core/Stack';
-import {XDSGrid} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
+import {XDSCarousel} from '@xds/core/Carousel';
import {XDSButton} from '@xds/core/Button';
-import {XDSBadge} from '@xds/core/Badge';
-import {XDSProgressBar} from '@xds/core/ProgressBar';
-import {XDSTextInput} from '@xds/core/TextInput';
-import {XDSPagination} from '@xds/core/Pagination';
-import {XDSSwitch} from '@xds/core/Switch';
-import {XDSBanner} from '@xds/core/Banner';
-import {XDSItem} from '@xds/core/Item';
-import {XDSStatusDot} from '@xds/core/StatusDot';
-import {XDSIcon} from '@xds/core/Icon';
import {XDSTheme} from '@xds/core/theme';
-import {neutralTheme} from '@xds/theme-neutral/built';
+import {
+ spacingDefaults,
+ radiusDefaults,
+ textSizeDefaults,
+} from '@xds/core/theme/tokens.stylex';
+import {packages} from '../../../generated/packageRegistry';
+import {themeObjects} from '../../../generated/themeRegistry';
+import {ThemeShowcaseTile} from '../../../components/ThemeShowcaseTile';
+
+// Gallery order — mirrors the dedicated /themes page (most restrained
+// → most expressive). Keeps the landing showcase consistent with the
+// deeper gallery so users encounter the same identity ordering. Any
+// theme not in this list falls to the end (alphabetical) so a newly
+// added theme always shows up rather than silently disappearing.
+const THEME_ORDER: ReadonlyArray<string> = [
+ '@xds/theme-neutral',
+ '@xds/theme-stone',
+ '@xds/theme-gothic',
+ '@xds/theme-matcha',
+ '@xds/theme-y2k',
+ '@xds/theme-butter',
+];
-const noop = () => {};
+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);
+ if (ai === -1 && bi === -1) {
+ return a.name.localeCompare(b.name);
+ }
+ if (ai === -1) {
+ return 1;
+ }
+ if (bi === -1) {
+ return -1;
+ }
+ return ai - bi;
+ });
+
+// 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 tiles visually inconsistent (different button heights, badge
+// sizes, banner padding). Resetting only the structural tokens — while
+// leaving --color-* and --font-family-* alone — keeps the layout uniform
+// but lets each tile showcase its true palette and typography.
+const STRUCTURAL_TOKEN_OVERRIDES: React.CSSProperties = {
+ ...spacingDefaults,
+ ...radiusDefaults,
+ ...textSizeDefaults,
+ height: '100%',
+};
+
+// Per-slide width inside the carousel. Each tile renders its
+// internal 2-column composition (image + identity + swatches on the
+// left; input + table + controls + banners on the right), which
+// needs ~700px+ to read well — below 800px the tile collapses to a
+// single internal column via its own TILE_STACK_BREAKPOINT, which
+// makes content render too tall and look squished. 800 sits right
+// at that breakpoint so every tile renders in its desktop 2-up
+// internal layout, and on a typical 1280–1440px desktop you get
+// the active tile + a clean peek of the next one on the right.
+const CARD_WIDTH = 800;
+
+// Per-slide height. XDSCarousel uses `align-items: center` on its
+// scroller, so without an explicit height each slide sizes to its
+// content and tiles render at visibly different heights based on
+// which theme is showing. 620px chosen empirically as the smallest
+// height that fits all themes' right-column content without clipping
+// at base XDS sizing.
+const CARD_HEIGHT = 620;
+
+// Horizontal gutter that defines the page's content rim. The
+// header row's content (title + links) starts at this offset from
+// the viewport edge, and the carousel scroller is padded by this
+// same value on the leading side so the first tile lines up with
+// the heading text above it. Used via the --theming-gutter CSS
+// variable set on the showcase root below, so the header row and
+// the carousel's nested scroller dom both read the same value.
+// Aligns the carousel's content rail (heading + buttons + first
+// tile leading edge) with the standard 1200px-wide section
+// column used by every other landing-page section (Features,
+// About, Discover) and the community page. PAGE_GUTTER matches
+// the showcaseOverlay's paddingInline (--spacing-6 = 24px), so
+// at viewports narrower than the 1200px column the carousel
+// content sits flush with the same 24px page rim as the other
+// sections.
+const PAGE_GUTTER = 24;
+const CONTENT_MAX_WIDTH = 1200;
+// At wide viewports, the gutter resolves to the empty space
+// between the viewport edge and the centered 1200px content
+// column — same horizontal start as the other 1200px-centered
+// sections on the page (FeaturesShowcase, AboutShowcase, etc.).
+// At narrower viewports, the max() clamp kicks in and pads the
+// content by PAGE_GUTTER from the viewport edge so things don't
+// touch the screen rim.
+const CONTENT_GUTTER_FORMULA = `max(${PAGE_GUTTER}px, calc((100vw - ${CONTENT_MAX_WIDTH}px) / 2))`;
const styles = stylex.create({
+ // Section root — adds breathing room above the heading so the
+ // showcase doesn't feel cramped against whatever sits above it
+ // (on the docsite landing that's the sticky hero block).
+ section: {
+ paddingBlockStart: 'var(--spacing-12)',
+ },
+
+ // Header row — title on the left, "Explore all themes" /
+ // "Create a custom theme" links on the right. Full-bleed so it
+ // sits on the same horizontal axis as the carousel; inline
+ // padding-start matches the carousel scroller's padding-start
+ // (CONTENT_GUTTER_FORMULA) so the heading text's leading edge
+ // sits on the same vertical line as the first carousel tile's
+ // leading edge below.
+ //
+ // marginInline trick bleeds the row past whatever parent
+ // padding the showcase is mounted under (the docsite landing's
+ // `showcaseOverlay` adds padding-inline: var(--spacing-6) which
+ // would otherwise indent the row).
+ //
+ // padding-inline-end uses the same formula so the links cluster
+ // sits at the symmetric inset from the right viewport edge.
+ //
+ // Below 720px viewport the row collapses to a vertical stack so
+ // the buttons drop below the description instead of getting
+ // squeezed beside it.
+ headerRow: {
+ width: '100vw',
+ marginInline: 'calc(50% - 50vw)',
+ paddingInlineStart: CONTENT_GUTTER_FORMULA,
+ paddingInlineEnd: CONTENT_GUTTER_FORMULA,
+ boxSizing: 'border-box',
+ flexDirection: {
+ default: 'row',
+ '@media (max-width: 720px)': 'column',
+ },
+ alignItems: {
+ default: 'stretch',
+ '@media (max-width: 720px)': 'flex-start',
+ },
+ },
headingBlock: {
- width: '100%',
+ flex: 1,
+ minWidth: 0,
maxWidth: 680,
- textAlign: 'center',
+ // Explicit start alignment so the heading + description anchor
+ // to the column's left edge regardless of any inherited
+ // text-align cascade from ancestor surfaces (the docsite hero
+ // chrome above this section sets text-align:center on its own
+ // sticky block, which has been observed to inherit into sibling
+ // trees in some browsers). Lives on the heading column container
+ // rather than as an !important wildcard descendant rule so the
+ // override is locally scoped and doesn't fight the buttons in
+ // the sibling HeaderLinks column.
+ textAlign: 'start',
},
fillWidth: {
width: '100%',
},
- outerCard: {
- width: '100%',
- maxWidth: 1200,
- },
- subTile: {
- width: '100%',
- },
- captionDivider: {
- height: '1.125em',
- },
- swatchRow: {
- flexWrap: 'wrap',
+ // Caps the section description's line length to ~70 characters
+ // (560px) so it doesn't run uncomfortably wide on desktop. Used
+ // by the description paragraph below the heading.
+ descriptionWidth: {
+ maxWidth: 560,
},
- swatch: {
- width: 40,
- height: 40,
- borderRadius: '50%',
- boxShadow: 'inset 0 0 0 1px rgba(0,0,0,0.06)',
+ // Cluster on the right of the header row — "Create a custom theme"
+ // ghost button + "Explore all themes" secondary button. Strictly
+ // the XDSButton docs discourage button-for-navigation, but the
+ // same docsite uses this pattern on the hero CTAs (`Get started`
+ // / `Browse components`) so the visual treatment is consistent
+ // with the rest of the landing.
+ //
+ // Default (row mode): alignSelf:end pins the cluster to the
+ // bottom of the row so the buttons sit on the same baseline as
+ // the last line of the description text. Below the 720px
+ // breakpoint the row collapses to a column (see headerRow) and
+ // the cluster shifts to the start so the buttons sit naturally
+ // under the description.
+ headerLinks: {
flexShrink: 0,
+ alignSelf: {
+ default: 'end',
+ '@media (max-width: 720px)': 'flex-start',
+ },
},
- paletteCol: {
- alignItems: 'center',
- minWidth: 48,
- },
- hexLabel: {
- fontSize: 10,
- letterSpacing: '0.02em',
- },
- swatchPairWrap: {
- aspectRatio: '1 / 1',
- borderRadius: 'var(--radius-container)',
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- overflow: 'hidden',
- },
- swatchPairInner: {
- width: '62%',
- height: '62%',
- borderRadius: 'var(--radius-element)',
- },
- bigAaWrap: {
- aspectRatio: '1 / 1',
- borderRadius: 'var(--radius-container)',
- backgroundColor: 'var(--color-background-muted)',
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- fontSize: 64,
- lineHeight: 1,
- fontWeight: 600,
- color: 'var(--color-text-primary)',
- },
- // Both Aa tiles read their font from the active theme's typography
- // tokens so the sample stays accurate as themes are swapped instead
- // of hardcoding a specific font name.
- bigAaHeading: {
- fontFamily: 'var(--font-family-heading)',
- },
- bigAaBody: {
- fontFamily: 'var(--font-family-body)',
- },
- radiusBlock: {
- width: 44,
- height: 44,
- backgroundColor: 'var(--color-text-primary)',
+
+ // Full-bleed carousel wrapper — bleeds past parent padding so the
+ // carousel viewport spans the full screen width. No leading inset
+ // here; the leading gutter that aligns the first tile to the
+ // heading text is applied via padding-inline-start on the
+ // carousel's INNER scroller (see the inline <style> rule below).
+ // That way the gutter is part of the scrollable area, so when the
+ // user scrolls right and then back left, the leading edge of
+ // the previously-scrolled-off tiles can re-enter the viewport
+ // fully (vs being permanently clipped behind a wrapper inset).
+ carouselWrap: {
+ position: 'relative',
+ width: '100vw',
+ marginInline: 'calc(50% - 50vw)',
},
- photoCell: {
- aspectRatio: '4 / 5',
- borderRadius: 'var(--radius-element)',
- overflow: 'hidden',
- backgroundColor: 'var(--color-background-muted)',
+
+ // Each slide is sized to CARD_WIDTH on desktop; clamps to fit
+ // the viewport (with a comfortable gutter) on narrower screens.
+ // Height is fixed at CARD_HEIGHT on wider viewports so all tiles
+ // match. Below the tile's stack breakpoint (800px), the inner
+ // ThemeShowcaseTile collapses from 2 columns to 1 column, which
+ // makes its natural height roughly double — so we use a taller
+ // fixed height (CARD_HEIGHT_STACKED) that fits the tallest
+ // stacked theme, keeping every slide the same height so the
+ // carousel reads as a clean uniform row at every breakpoint.
+ slide: {
+ width: `min(${CARD_WIDTH}px, 100vw - var(--spacing-6, 24px) * 2)`,
+ height: {
+ default: CARD_HEIGHT,
+ // 1180px chosen empirically to fit Matcha (the tallest stacked
+ // theme) with a comfortable bottom rim. Inlined here because
+ // StyleX's compile-time evaluator can't resolve named constants
+ // inside an @media object value.
+ '@media (max-width: 800px)': 1180,
+ },
},
- photoImg: {
+ // The XDSCard host inside each slide. Fills the slide width and
+ // height so the inner ThemeShowcaseTile stretches to match.
+ cardFill: {
width: '100%',
height: '100%',
- objectFit: 'cover',
- display: 'block',
},
- stoneWord: {
- fontFamily:
- 'Fraunces, "PT Serif", Georgia, "Times New Roman", Times, serif',
- fontWeight: 600,
- letterSpacing: '0.02em',
- fontSize: 40,
- lineHeight: 1,
- color: 'var(--color-text-primary)',
+ previewFrame: {
+ height: '100%',
+ overflow: 'hidden',
},
});
-// =============================================================================
-// Heading
-// =============================================================================
-
function ShowcaseHeading() {
return (
- <XDSVStack gap={4} align="center" xstyle={styles.headingBlock}>
+ <XDSVStack gap={4} xstyle={styles.headingBlock}>
<XDSHeading
level={2}
type="display-2"
@@ -137,411 +252,155 @@ function ShowcaseHeading() {
xstyle={styles.fillWidth}>
Custom styles as unique as your app
</XDSHeading>
- <XDSVStack gap={4} align="center" xstyle={styles.fillWidth}>
- <XDSText
- display="block"
- type="body"
- color="secondary"
- style={{maxWidth: 560}}>
- Astryx makes it effortless to apply your brand — no rewrites needed.
- Customize your theme at the token level: color, typography, radius,
- and motion.
- </XDSText>
- <XDSHStack gap={4} align="center">
- <XDSLink type="body" href="/themes" color="primary" hasUnderline>
- Explore all themes
- </XDSLink>
- <XDSDivider orientation="vertical" xstyle={styles.captionDivider} />
- <XDSLink type="body" href="/docs/theme" color="primary" hasUnderline>
- Create a custom theme
- </XDSLink>
- </XDSHStack>
- </XDSVStack>
+ <XDSText
+ display="block"
+ type="body"
+ color="secondary"
+ xstyle={styles.descriptionWidth}>
+ Astryx makes it effortless to apply your brand — no rewrites needed.
+ Customize your theme at the token level: color, typography, radius, and
+ motion.
+ </XDSText>
</XDSVStack>
);
}
-// =============================================================================
-// Column 1
-// =============================================================================
-
-const PALETTE_GRAYS = [
- '#28282A',
- '#84848B',
- '#D8D8DB',
- '#F5F5F3',
- '#FFFFFF',
-] as const;
-
-const PALETTE_ACCENTS = [
- {hex: '#009936', label: '#009936'},
- {hex: '#FFB600', label: '#FFB600'},
- {hex: '#FD0000', label: '#FD0000'},
-] as const;
-
-function StoneSampleTile() {
- return (
- <XDSCard variant="muted" padding={5}>
- <XDSVStack gap={4}>
- <XDSVStack gap={1}>
- <div {...stylex.props(styles.stoneWord)}>STONE</div>
- <XDSLink
- type="supporting"
- color="secondary"
- href="/themes"
- hasUnderline>
- Try Theme
- </XDSLink>
- </XDSVStack>
-
- <XDSHStack gap={2} wrap="wrap">
- <XDSButton variant="primary" size="sm" label="Primary" />
- <XDSButton variant="secondary" size="sm" label="Secondary" />
- <XDSButton
- variant="ghost"
- size="sm"
- label="Ghost"
- icon={<XDSIcon icon="wrench" size="sm" />}
- />
- </XDSHStack>
-
- <XDSProgressBar
- value={75}
- label="Progress"
- hasValueLabel
- variant="accent"
- />
-
- <XDSTextInput
- label="Example"
- description="Description text"
- placeholder="Type something..."
- value=""
- onChange={noop}
- />
-
- <XDSHStack gap={1} wrap="wrap" xstyle={styles.swatchRow}>
- <XDSBadge variant="info" label="Badge" />
- <XDSBadge variant="success" label="Badge" />
- <XDSBadge variant="warning" label="Badge" />
- <XDSBadge variant="error" label="Badge" />
- <XDSBadge variant="purple" label="Badge" />
- </XDSHStack>
-
- <XDSPagination
- page={3}
- onChange={noop}
- totalPages={10}
- size="sm"
- siblingCount={0}
- />
- </XDSVStack>
- </XDSCard>
- );
-}
-
-function PaletteTile() {
+function HeaderLinks() {
return (
- <XDSCard variant="muted" padding={5}>
- <XDSVStack gap={4}>
- <XDSHStack gap={3} justify="between" wrap="wrap">
- {PALETTE_GRAYS.map(hex => (
- <XDSVStack
- key={hex}
- gap={1}
- xstyle={styles.paletteCol}
- align="center">
- <div
- {...stylex.props(styles.swatch)}
- style={{backgroundColor: hex}}
- />
- <XDSText
- type="supporting"
- color="secondary"
- xstyle={styles.hexLabel}>
- {hex}
- </XDSText>
- </XDSVStack>
- ))}
- </XDSHStack>
- <XDSHStack gap={3} justify="start" wrap="wrap">
- {PALETTE_ACCENTS.map(({hex, label}) => (
- <XDSVStack
- key={hex}
- gap={1}
- xstyle={styles.paletteCol}
- align="center">
- <div
- {...stylex.props(styles.swatch)}
- style={{backgroundColor: hex}}
- />
- <XDSText
- type="supporting"
- color="secondary"
- xstyle={styles.hexLabel}>
- {label}
- </XDSText>
- </XDSVStack>
- ))}
- </XDSHStack>
- </XDSVStack>
- </XDSCard>
+ <XDSHStack gap={2} align="center" xstyle={styles.headerLinks}>
+ <XDSButton
+ variant="ghost"
+ label="Create a custom theme"
+ href="/docs/theme"
+ />
+ <XDSButton
+ variant="secondary"
+ label="Explore all themes"
+ href="/themes"
+ />
+ </XDSHStack>
);
}
-// =============================================================================
-// Column 2
-// =============================================================================
-
-function SettingsTogglesTile() {
- return (
- <XDSCard variant="muted" padding={5}>
- <XDSVStack gap={3}>
- <XDSSwitch
- label="Light mode"
- value={true}
- onChange={noop}
- labelSpacing="spread"
- />
- <XDSSwitch
- label="Animations"
- value={true}
- onChange={noop}
- labelSpacing="spread"
- />
- <XDSSwitch
- label="Compact"
- value={false}
- onChange={noop}
- labelSpacing="spread"
- />
- </XDSVStack>
- </XDSCard>
- );
-}
-
-function CardActionsTile() {
- return (
- <XDSCard variant="muted" padding={5}>
- <XDSCard variant="default" padding={4}>
- <XDSVStack gap={3}>
- <XDSHeading level={4}>Card Title</XDSHeading>
- <XDSText type="body" color="secondary">
- A flexible surface for grouping related content and actions.
- </XDSText>
- <XDSHStack gap={2}>
- <XDSButton variant="primary" size="sm" label="Primary" />
- <XDSButton variant="secondary" size="sm" label="Secondary" />
- </XDSHStack>
- </XDSVStack>
- </XDSCard>
- </XDSCard>
- );
-}
-
-function SearchFilterBannersTile() {
- return (
- <XDSCard variant="muted" padding={5}>
- <XDSVStack gap={3}>
- <XDSTextInput
- label="Search"
- isLabelHidden
- placeholder="Search..."
- value=""
- onChange={noop}
- startIcon={<XDSIcon icon="search" size="sm" />}
- hasClear
- />
-
- <XDSVStack gap={1}>
- <XDSItem
- media={<XDSStatusDot variant="accent" label="Status" />}
- label="Status"
- description="Filter by status"
- />
- <XDSItem
- media={<XDSStatusDot variant="neutral" label="Type" />}
- label="Type"
- description="Filter by type"
- />
- </XDSVStack>
-
- <XDSVStack gap={2}>
- <XDSBanner status="success" title="Banner Title" />
- <XDSBanner status="warning" title="Banner Title" />
- <XDSBanner status="error" title="Banner Title" />
- </XDSVStack>
- </XDSVStack>
- </XDSCard>
- );
-}
-
-// =============================================================================
-// Column 3
-// =============================================================================
-
-const SWATCH_PAIRS: ReadonlyArray<{bg: string; fg: string}> = [
- {bg: '#D9E8E2', fg: '#2F5D52'}, // teal-on-mint
- {bg: '#F4D9C4', fg: '#5A3A28'}, // brown-on-peach
- {bg: '#EFEAD4', fg: '#5C5A30'}, // olive-on-cream
- {bg: '#F4C77A', fg: '#7A4B12'}, // mustard-on-orange
-];
-
-function PaletteGridTile() {
- return (
- <XDSCard variant="muted" padding={4}>
- <XDSGrid columns={2} gap={3}>
- {SWATCH_PAIRS.map(({bg, fg}, i) => (
- <div
- key={i}
- {...stylex.props(styles.swatchPairWrap)}
- style={{backgroundColor: bg}}>
- <div
- {...stylex.props(styles.swatchPairInner)}
- style={{backgroundColor: fg}}
- />
- </div>
- ))}
- </XDSGrid>
- </XDSCard>
- );
-}
-
-// Sample swatches for the radius row — each one references an XDS radius
-// token so the rendered shapes track the active theme (Astryx overrides
-// the default scale by +4, so what's labelled `--radius-element` here
-// resolves to 12px under Astryx vs 8px under the default theme).
-const RADIUS_SAMPLES: ReadonlyArray<{label: string; radiusVar: string}> = [
- {label: '--radius-inner', radiusVar: 'var(--radius-inner)'},
- {label: '--radius-element', radiusVar: 'var(--radius-element)'},
- {label: '--radius-container', radiusVar: 'var(--radius-container)'},
- {label: '--radius-page', radiusVar: 'var(--radius-page)'},
- {label: '--radius-full', radiusVar: 'var(--radius-full)'},
-];
-
-function TypographyRadiusTile() {
- return (
- <XDSCard variant="muted" padding={5}>
- <XDSVStack gap={4}>
- <XDSGrid columns={2} gap={3}>
- <XDSVStack gap={2} align="center">
- <div {...stylex.props(styles.bigAaWrap, styles.bigAaHeading)}>
- Aa
- </div>
- <XDSText type="supporting" color="secondary">
- --font-family-heading
- </XDSText>
- </XDSVStack>
- <XDSVStack gap={2} align="center">
- <div {...stylex.props(styles.bigAaWrap, styles.bigAaBody)}>Aa</div>
- <XDSText type="supporting" color="secondary">
- --font-family-body
- </XDSText>
- </XDSVStack>
- </XDSGrid>
-
- <XDSHStack gap={2} justify="between" align="center">
- {RADIUS_SAMPLES.map(({label, radiusVar}) => (
- <XDSVStack key={label} gap={1} align="center">
- <div
- {...stylex.props(styles.radiusBlock)}
- style={{borderRadius: radiusVar}}
- />
- <XDSText type="supporting" color="secondary">
- {label}
- </XDSText>
- </XDSVStack>
- ))}
- </XDSHStack>
- </XDSVStack>
- </XDSCard>
- );
-}
-
-function LifestylePhotoTile() {
- return (
- <XDSCard variant="muted" padding={4}>
- <XDSGrid columns={2} gap={3}>
- <div {...stylex.props(styles.photoCell)}>
- {/* Plain <img> to avoid next/image remote host configuration changes. */}
- <img
- src="https://images.unsplash.com/photo-1505691938895-1758d7feb511?w=600&q=70"
- alt="A cream-toned minimal living room"
- {...stylex.props(styles.photoImg)}
- loading="lazy"
- />
- </div>
- <div {...stylex.props(styles.photoCell)}>
- <img
- src="https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&q=70"
- alt="A potted plant still life"
- {...stylex.props(styles.photoImg)}
- loading="lazy"
- />
- </div>
- </XDSGrid>
- </XDSCard>
- );
-}
-
-// =============================================================================
-// Pagination dots
-// =============================================================================
-
-function ShowcaseDots() {
- return (
- <XDSPagination
- page={2}
- onChange={noop}
- totalPages={4}
- variant="dots"
- size="sm"
- />
- );
-}
-
-// =============================================================================
-// Showcase root
-// =============================================================================
-
export function ThemingShowcase() {
return (
<XDSVStack
as="section"
gap={10}
- align="center"
+ align="stretch"
+ xstyle={styles.section}
data-theming-showcase="true">
- <ShowcaseHeading />
-
- <XDSTheme theme={neutralTheme} mode="light">
- <XDSVStack gap={5} align="center" xstyle={styles.outerCard}>
- <div {...stylex.props(styles.outerCard)}>
- <XDSGrid columns={{minWidth: 320, repeat: 'fit'}} gap={3}>
- {/* Column 1 */}
- <XDSVStack gap={3} xstyle={styles.subTile}>
- <StoneSampleTile />
- <PaletteTile />
- </XDSVStack>
-
- {/* Column 2 */}
- <XDSVStack gap={3} xstyle={styles.subTile}>
- <SettingsTogglesTile />
- <CardActionsTile />
- <SearchFilterBannersTile />
- </XDSVStack>
-
- {/* Column 3 */}
- <XDSVStack gap={3} xstyle={styles.subTile}>
- <PaletteGridTile />
- <TypographyRadiusTile />
- <LifestylePhotoTile />
- </XDSVStack>
- </XDSGrid>
- </div>
-
- <ShowcaseDots />
- </XDSVStack>
- </XDSTheme>
+ {/* Header row — heading on the left, "Explore all themes" /
+ "Create a custom theme" links on the right. Both clusters
+ share the same outer page gutter (PAGE_GUTTER) so they
+ align to the page's content rim. The carousel below bleeds
+ past this gutter to fill 100vw. */}
+ <XDSHStack
+ gap={6}
+ align="stretch"
+ hAlign="between"
+ xstyle={styles.headerRow}>
+ <ShowcaseHeading />
+ <HeaderLinks />
+ </XDSHStack>
+
+ {/* Carousel customisations that aren't expressible through
+ XDSCarousel's prop surface. Scoped via the aria-label of
+ *this* carousel so other XDSCarousel elsewhere in the
+ docsite are unaffected. Rules only exist while
+ ThemingShowcase is mounted (landing route only).
+
+ TODO(xds#2509): Remove this block once XDSCarousel ships
+ `hasEdgeFade` / `hasScaleAnimation` props and a reliable
+ `hasButtons={false}`. Tracking issue:
+ https://github.com/facebookexperimental/xds/issues/2509
+
+ 1. Hide XDSCarousel's built-in prev/next pills — our own
+ controls render in the header row. `hasButtons={false}`
+ prop is intermittently flaky across HMR/popover states,
+ so we belt-and-suspender with CSS targeting the
+ popover-portal'd buttons by their aria-label.
+
+ 2. Strip XDSCarousel's mask-image edge fade. The default
+ reads as a smudgy band; full-bleed filmstrip uses the
+ clean viewport clip instead.
+
+ 3. Disable the scroll-driven 0.85→1.0→0.85 scale animation
+ on each item — reads as inconsistent sizing rather than
+ a helpful focus cue when each tile has its own theme.
+
+ 4. Add left-padding equal to the page gutter so the FIRST
+ tile aligns with the heading column's left edge instead
+ of sitting flush against the viewport (the right end
+ stays flush so the last tile clips at the viewport edge,
+ signalling "more").
+ */}
+ <style>{`
+ [popover]:has([aria-label="Scroll left"]),
+ [popover]:has([aria-label="Scroll right"]) {
+ display: none !important;
+ }
+ [aria-label="Available themes"] > div:first-child {
+ mask-image: none !important;
+ /* Gutter that aligns the first tile to the heading text
+ leading edge. Applied as padding on the scroller (not
+ a margin on the wrapper) so the gutter is INSIDE the
+ scrollable area — scrolling right then back left can
+ return tiles fully to their starting position without
+ clipping them behind the gutter. scroll-padding-inline-
+ start mirrors it so the scroll-snap engine snaps tile
+ leading edges to the gutter, not the viewport edge. */
+ padding-inline-start: ${CONTENT_GUTTER_FORMULA} !important;
+ scroll-padding-inline-start: ${CONTENT_GUTTER_FORMULA} !important;
+ /* Matching trailing padding so the last tile doesn't sit
+ flush against the viewport's right edge when fully
+ scrolled — gives the gallery a symmetric inset that
+ frames the row of tiles inside the page rim. */
+ padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;
+ scroll-padding-inline-end: ${CONTENT_GUTTER_FORMULA} !important;
+ }
+ [aria-label="Available themes"] > div > div {
+ animation: none !important;
+ }
+ `}</style>
+
+ <div {...stylex.props(styles.carouselWrap)}>
+ <XDSCarousel
+ aria-label="Available themes"
+ gap={4}
+ hasSnap
+ hasButtons={false}>
+ {themePackages.map(pkg => {
+ const theme = themeObjects[pkg.name];
+ if (!theme) {
+ return null;
+ }
+ const label = pkg.displayName
+ .replace(/^Theme:\s*/, '')
+ .replace(/\s*Theme$/, '');
+ return (
+ <div key={pkg.name} {...stylex.props(styles.slide)}>
+ <XDSCard
+ padding={0}
+ variant="transparent"
+ xstyle={styles.cardFill}>
+ <div {...stylex.props(styles.previewFrame)}>
+ <XDSTheme theme={theme} mode="light">
+ <div style={STRUCTURAL_TOKEN_OVERRIDES}>
+ <ThemeShowcaseTile
+ label={label}
+ themeName={pkg.name}
+ description={pkg.description}
+ />
+ </div>
+ </XDSTheme>
+ </div>
+ </XDSCard>
+ </div>
+ );
+ })}
+ </XDSCarousel>
+ </div>
</XDSVStack>
);
}
diff --git a/apps/docsite/src/app/(site)/community/page.tsx b/apps/docsite/src/app/(site)/community/page.tsx
index 951b36b592..7438eec116 100644
--- a/apps/docsite/src/app/(site)/community/page.tsx
+++ b/apps/docsite/src/app/(site)/community/page.tsx
@@ -77,8 +77,10 @@ const styles = stylex.create({
// so every section (Hero, Wall, How we build, Engage,
// Resources) shares one consistent visual column down the
// middle of the page instead of each section finding its
- // own width.
- maxWidth: 920,
+ // own width. Matches the 1200px max-width used by the home
+ // page's section grids (FeaturesShowcase, AboutShowcase,
+ // DiscoverShowcase) so the two pages feel visually aligned.
+ maxWidth: 1200,
width: '100%',
marginInline: 'auto',
// Add the same section gap as bottom padding so the
@@ -174,17 +176,15 @@ const styles = stylex.create({
gap: 'var(--spacing-3)',
alignItems: 'flex-start',
},
- // Big monospace step number ("01", "02", …) — sized large
- // enough to anchor the row visually, but kept in the secondary
- // text color so it reads as metadata, not as a primary number.
+ // Step number column ("01", "02", …) — kept in the secondary
+ // text color via XDSText props; tabular-nums keeps the
+ // two-digit numbers vertically aligned across rows. Min-width
+ // reserves space for two digits + a hairline of breathing room
+ // so the column doesn't shift between "01" and "10".
processStepNumber: {
fontVariantNumeric: 'tabular-nums',
- color: 'var(--color-text-secondary)',
- fontSize: 'var(--text-body-size, 14px)',
- fontWeight: 'var(--font-weight-semibold, 600)',
flexShrink: 0,
minWidth: 28,
- paddingTop: 2,
},
// -------------------------------------------------------------------------
@@ -203,6 +203,14 @@ const styles = stylex.create({
// ancestor and the avatars scatter across the whole page
// instead of staying inside the wall card. XDSCard's root
// doesn't set position by default, so we set it here.
+ //
+ // isolation:isolate establishes a NEW stacking context here
+ // so the inner z-indexed children (wordmark, avatars, link)
+ // stack ONLY against each other inside this card, never
+ // against ancestors. Without it the children compete with
+ // the AppShell's sticky top nav (also at zIndex:1) when
+ // scrolled, causing the wordmark to render above the nav.
+ isolation: 'isolate',
position: 'relative',
backgroundColor: 'var(--color-background-body)',
borderColor: 'transparent',
@@ -247,15 +255,12 @@ const styles = stylex.create({
zIndex: 1,
},
// The "See contributors" anchor link below the wordmark.
- // Plain text styling so the wordmark stays dominant; sits
- // above the scattered avatars in z-order via zIndex 1.
+ // Only positioning lives here (zIndex:1 keeps the link above
+ // the scattered avatar layer); typography + color come from
+ // the XDSLink type="supporting" + color="secondary" props.
wallSeeContributors: {
position: 'relative',
zIndex: 1,
- color: 'var(--color-text-secondary)',
- textDecoration: 'underline',
- textUnderlineOffset: '4px',
- fontSize: 'var(--text-supporting-size, 13px)',
},
// Description line between the wordmark and the "See
// contributors" link. Capped at ~440px so the line wraps to
@@ -291,7 +296,7 @@ const styles = stylex.create({
position: 'absolute',
width: 48,
height: 48,
- borderRadius: 12,
+ borderRadius: 'var(--radius-element)',
objectFit: 'cover' as const,
// Rotation is applied per-tile inline (see AVATAR_SLOTS
// below) so each face has its own slight tilt. Combine
@@ -324,168 +329,157 @@ const styles = stylex.create({
// Top editorial row — headline + paragraph on the left,
// brand-shape composition on the right. 1:1 split at wide
// widths; stacks vertically at <760px.
- // Editorial header — centered headline + description on top
- // (spans full width); the 3-column channel-card grid sits
- // below it. Centered text contrasts with the rest of the page's
- // left-aligned section headings and frames the channel grid
- // like the reference's "Newest Collection" product layout.
- endBlockHeader: {
- display: 'flex',
- flexDirection: 'column',
- alignItems: 'center',
- gap: 'var(--spacing-8)',
- },
+ // Editorial header text styles — applied to the heading + intro
+ // paragraph stack at the top of the Resources block.
endBlockHeaderText: {
- textAlign: 'center' as const,
maxWidth: 680,
},
-
- // 3-column channel grid below the centered editorial header.
- // Auto-fit with a generous minWidth so columns stay readable
- // and reflow gracefully to 2 / 1 columns on narrower viewports.
- channelGrid: {
- display: 'grid',
- gridTemplateColumns: 'repeat(3, 1fr)',
- gap: 'var(--spacing-6)',
- width: '100%',
- '@media (max-width: 760px)': {
- gridTemplateColumns: '1fr',
- },
- },
-
- // Single channel card — tall pastel-filled block with title
- // anchored to the top-left and description anchored to the
- // bottom-left, leaving a generous open middle. The whole card
- // is the click target via XDSClickableCard with its default
- // border zeroed (the pastel fill carries the visual identity).
- channelCard: {
- overflow: 'hidden',
- borderColor: 'transparent',
- // Each card gets its color via inline style based on the
- // channel data (see CHANNELS.bgColor). Done inline so the
- // shared style here stays color-agnostic.
- },
- // Tall portrait inner stack — XDSVStack handles direction +
- // gap + vAlign:between (so title pins to top and description
- // pins to bottom). aspectRatio drives the portrait shape.
- channelCardInner: {
- aspectRatio: '4 / 5',
- },
- // Resources section below the editorial header — two XDSList
- // groups (Documentation + Legal) side-by-side under one shared
- // section heading. Sub-stacks reflow to a single column under
- // 760px.
+ // Resources block — editorial header + categorized resource
+ // grid, stacked vertically.
endBlockResources: {
display: 'flex',
flexDirection: 'column',
- gap: 'var(--spacing-6)',
- // Match the parent sectionStack's calc(var(--spacing-12) * 2)
- // = 96px so the Engage → Resources gap inside the end block
- // reads the same as the gaps between all the other top-level
- // sections on the page.
- paddingBlockStart: 'calc(var(--spacing-12) * 2)',
+ gap: 'var(--spacing-8)',
},
- endBlockResourcesGrid: {
+ // Each resource category wraps its eyebrow label + items in a
+ // small vertical stack so the label optically aligns with the
+ // list's leading icon glyph below.
+ resourceColumn: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 'var(--spacing-3)',
+ minWidth: 0,
+ },
+ // XDSList wrapper inside each category — turned into a 3-column
+ // grid so items render as a balanced row instead of a tall
+ // vertical strip. <ul> + <li> grid directly (the <li> children
+ // become grid cells). Collapses to 2 cols on tablet, 1 on mobile.
+ // The optical alignment shift pulls items left by the XDSListItem's
+ // internal start padding (≈ 12px = --spacing-3) so the row icons
+ // sit flush with the page's left reading rail and the category
+ // eyebrow label above.
+ resourceList: {
display: 'grid',
- // minmax(0, 1fr) is load-bearing — without it, columns
- // refuse to shrink below their content's min-content width
- // (long resource titles like "How we settle design
- // disagreements..."), which forces the whole grid to
- // overflow its parent. minmax(0, 1fr) lets columns shrink
- // to whatever the parent allows, so the grid stays within
- // the parent's bounds and descriptions wrap normally.
gridTemplateColumns: {
default: 'repeat(3, minmax(0, 1fr))',
'@media (max-width: 900px)': 'repeat(2, minmax(0, 1fr))',
'@media (max-width: 600px)': '1fr',
},
- gap: 'var(--spacing-2)',
- alignItems: 'flex-start',
- // Optical alignment shift: pull the grid left by the
- // XDSListItem's internal start padding (~12px = --spacing-3)
- // so the leading icon glyph of each row optically aligns
- // with the "Resources" section heading's left edge above.
- // Same width compensation as the wall-card alignment trick
- // earlier — content shifts left, total grid width grows by
- // the same amount on the right so the rightmost column
- // doesn't lose space.
+ gap: 'var(--spacing-2) var(--spacing-6)',
marginInlineStart: 'calc(-1 * var(--spacing-3))',
width: 'calc(100% + var(--spacing-3))',
},
+ // Icon tile — wraps each resource row's leading glyph in a
+ // square rounded background so the icon reads as a deliberately
+ // anchored element rather than a floating glyph next to the
+ // text. Uses the subtle "muted" surface so the tile recedes
+ // and the icon itself stays the focal point. Sized to match the
+ // height of a 2-line description so the tile vertically centers
+ // against the label/description block.
+ iconTile: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 36,
+ height: 36,
+ borderRadius: 'var(--radius-element)',
+ backgroundColor: 'var(--color-background-muted)',
+ color: 'var(--color-text-primary)',
+ flexShrink: 0,
+ },
+ // Resource description text — clamped to 2 lines so short
+ // descriptions render naturally on 1 line and longer ones wrap
+ // to 2 lines (anything beyond gets a "…" ellipsis). Prevents
+ // both the mid-character single-line truncation that XDSItem
+ // defaults to on string descriptions AND prevents long
+ // descriptions from running 4+ lines and breaking the visual
+ // rhythm of the grid.
+ resourceDescription: {
+ display: '-webkit-box',
+ WebkitBoxOrient: 'vertical',
+ WebkitLineClamp: 2,
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ },
+ // Vertical stack of resource categories. Each category fills
+ // the full reading column width with its eyebrow label + list
+ // of items, and categories stack one after the other so the
+ // reading order is unambiguous (instead of wrapping into 3 grid
+ // columns that left awkward empty cells when categories had
+ // different item counts). The XDSList inside still gets the
+ // optical-alignment shift so list items sit flush with the
+ // page's left reading rail.
+ endBlockResourcesGrid: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 'var(--spacing-8)',
+ width: '100%',
+ },
// -------------------------------------------------------------------------
- // BlockCard — color-blocked contribution-type cards
+ // BlockCard — feature-card-style contribution paths
// -------------------------------------------------------------------------
- // 4 quadrants of a single grouped block (see blockGrid below).
- // Each quadrant has a soft pastel fill, a big heading anchored
- // to bottom-left, an effort badge under the heading, and a
- // small arrow chip anchored to bottom-right. Each quadrant is
- // still its own click target via XDSClickableCard, but visually
- // they read as one grouped object because the outer blockGrid
- // clips to a single rounded shape with no gap between cells.
+ // Mirrors the home page's FeaturesShowcase cards (see
+ // apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx).
+ // Each card is independent (no fused quadrant block), with
+ // text + Explore link at the top and an optional image
+ // bottom-anchored with bleed margins so the artwork renders
+ // at natural aspect ratio without cropping.
- // Outer grid wrapper — fuses the 4 quadrants into one visual
- // block. radius + overflow:hidden on the wrapper means each
- // quadrant's individual sharp corners get clipped to the
- // wrapper's rounded outer shape. No gap so the 4 pastel fills
- // touch directly at the inner seams.
+ // 2-column grid. Independent cards size to their own content;
+ // grid uses auto rows so cards never get stretched to absurd
+ // heights to match a tall neighbor.
blockGrid: {
display: 'grid',
- gridTemplateColumns: '1fr 1fr',
- gridTemplateRows: '1fr 1fr',
- gap: 0,
- borderRadius: 'var(--radius-container)',
- overflow: 'hidden',
+ gridTemplateColumns: {
+ default: 'repeat(2, 1fr)',
+ '@media (max-width: 720px)': '1fr',
+ },
+ gap: 'var(--spacing-4)',
+ width: '100%',
},
- // Outer card — no padding (the inner zones manage their own
- // spacing). overflow:hidden so the white placeholder's rounded
- // corners (set via inset spacing on blockCardImage instead of
- // a radius) clip cleanly to the card's quadrant edge.
+ // Individual card chrome — overflow:hidden lets the bleeding
+ // image (negative margin) clip cleanly at the rounded corners.
+ // height:100% so cards in the same grid row stretch to the
+ // tallest one (grid default), keeping the row visually aligned.
blockCard: {
- position: 'relative',
+ height: '100%',
overflow: 'hidden',
- borderColor: 'transparent',
- borderRadius: 0,
- color: 'var(--color-text-primary)',
- minHeight: 280,
- display: 'flex',
- flexDirection: 'column',
},
- // White placeholder image area above the title. Uses
- // --color-background-card (theme-aware lifted tone, usually
- // white) so it reads as a distinct content slot against the
- // card's body-tone fill. Inset slightly from the card edges
- // (via margin) so it reads as a contained content slot rather
- // than touching the quadrant seams.
- blockCardImage: {
- flex: '1 1 auto',
- minHeight: 100,
- backgroundColor: 'var(--color-background-card)',
- borderRadius: 'var(--radius-container)',
- margin: 'var(--spacing-5)',
- marginBottom: 0,
+ // Inner VStack of the card — height:100% so the auto margins
+ // on the image wrapper below have a known parent height to
+ // push against, anchoring images to the card's bottom.
+ blockCardStack: {
+ height: '100%',
},
- // Bottom-anchored title + effort badge cluster. Padding lives
- // here (not on the outer card) so the placeholder image above
- // can be inset independently from the card edges.
- blockCardBottom: {
- display: 'flex',
- flexDirection: 'column',
- gap: 'var(--spacing-1)',
- padding: 'var(--spacing-5)',
+ // Explore link spacing — adds the extra +12px past the 4px
+ // stack gap to land at 16px between the description and the
+ // link (same treatment as the home page feature cards).
+ blockCardExplore: {
+ marginTop: 'calc(var(--spacing-3))',
},
- // Heading uses --color-text-primary — the card backgrounds
- // are alpha-tinted pastels (--color-background-{hue} resolves
- // to the hue at ~20% opacity), so the underlying body color
- // shows through enough that the standard dark text color
- // reads cleanly.
- blockCardTitle: {
- color: 'var(--color-text-primary)',
+ // Image wrapper — bottom-anchored via marginTop:auto so text
+ // stays at the top of the card and the image floats to the
+ // bottom. paddingTop:16 guarantees a 16px gap between the
+ // Explore link and the image content above. Negative margins
+ // (start/end/bottom) bleed the image to within 16px of the
+ // card's outer edges, matching the home page's bleed treatment.
+ blockCardImage: {
+ marginTop: 'auto',
+ paddingTop: 16,
+ marginBottom: 'calc(var(--spacing-5) * -1)',
+ marginInlineStart: 'calc(var(--spacing-5) * -1)',
+ marginInlineEnd: 'calc(var(--spacing-5) * -1)',
+ alignSelf: 'stretch',
+ overflow: 'hidden',
},
- // Effort badge — a quiet inline pill under the heading.
- blockCardEffort: {
- color: 'var(--color-text-secondary)',
- fontSize: 'var(--text-supporting-size, 13px)',
+ // Image element — full container width, natural height so each
+ // composition renders at its own proportions (no cropping, no
+ // distortion). Same approach the home page uses.
+ blockCardImageImg: {
+ width: '100%',
+ height: 'auto',
+ display: 'block',
},
});
@@ -603,7 +597,7 @@ function WallCard({contributors}: {contributors: ReadonlyArray<Contributor>}) {
alt="Astryx"
{...stylex.props(styles.wallWordmark)}
/>
- <XDSText type="body" color="secondary" xstyle={styles.wallDescription}>
+ <XDSText type="body" color="primary" xstyle={styles.wallDescription}>
A growing community of designers and engineers ship Astryx together.
<br />
Your name could be next.
@@ -612,6 +606,9 @@ function WallCard({contributors}: {contributors: ReadonlyArray<Contributor>}) {
label="See contributors"
href={`${GITHUB_REPO}/graphs/contributors`}
target="_blank"
+ type="supporting"
+ color="secondary"
+ hasUnderline
xstyle={styles.wallSeeContributors}>
See contributors
</XDSLink>
@@ -628,36 +625,45 @@ interface BlockCardProps {
label: string;
description: string;
href: string;
- /** Soft pastel background (--color-background-{hue}). */
- bgColor: string;
badge?: string;
+ /** Optional preview image rendered in the image slot. */
+ image?: {src: string; alt: string};
}
-function BlockCard({label, description, href, bgColor, badge}: BlockCardProps) {
+function BlockCard({label, description, href, badge, image}: BlockCardProps) {
+ const showImage = image != null;
return (
<XDSClickableCard
label={`Open ${label}`}
href={href}
- padding={0}
- xstyle={styles.blockCard}
- style={{backgroundColor: bgColor}}>
- {/* White placeholder image slot above the title — empty for
- now; later this can hold a real preview image, an
- illustration, or a contextual screenshot per card. */}
- <div {...stylex.props(styles.blockCardImage)} aria-hidden="true" />
- <div {...stylex.props(styles.blockCardBottom)}>
- <XDSHeading level={3} xstyle={styles.blockCardTitle}>
+ variant="gray"
+ padding={5}
+ xstyle={styles.blockCard}>
+ <XDSVStack
+ gap={1}
+ align="start"
+ xstyle={showImage ? styles.blockCardStack : undefined}>
+ <XDSHeading level={3} color="primary">
{label}
</XDSHeading>
- <XDSText type="supporting" xstyle={styles.blockCardEffort}>
+ <XDSText type="body" color="primary">
{description}
</XDSText>
{badge && (
- <XDSText type="supporting" xstyle={styles.blockCardEffort}>
+ <XDSText type="supporting" color="secondary">
{badge}
</XDSText>
)}
- </div>
+ {showImage && image && (
+ <div {...stylex.props(styles.blockCardImage)}>
+ <img
+ src={image.src}
+ alt={image.alt}
+ {...stylex.props(styles.blockCardImageImg)}
+ />
+ </div>
+ )}
+ </XDSVStack>
</XDSClickableCard>
);
}
@@ -666,43 +672,93 @@ function BlockCard({label, description, href, bgColor, badge}: BlockCardProps) {
// Data
// =============================================================================
-// Channels — where the community talks. Each entry renders as one
-// rich card in the channels grid. Tint is hand-assigned per card
-// so the row has visual variety; keep this list short (3–5 max)
-// so each option feels like a deliberate path, not a link dump.
-interface Channel {
- name: string;
+// Brand glyphs for the Communications section's channel rows.
+// Each icon matches the XDSListItem startContent slot's expected
+// size (~20px). Inline SVGs keep the bundle lean and avoid
+// pulling in a brand-icon package for just three glyphs.
+
+const GitHubGlyph = ({width = 20, height = 20}) => (
+ <svg
+ width={width}
+ height={height}
+ viewBox="0 0 24 24"
+ fill="currentColor"
+ xmlns="http://www.w3.org/2000/svg"
+ aria-hidden="true">
+ <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12Z" />
+ </svg>
+);
+
+// X (formerly Twitter) glyph — the post-2023 wordmark/logo.
+const TwitterGlyph = ({width = 20, height = 20}) => (
+ <svg
+ width={width}
+ height={height}
+ viewBox="0 0 24 24"
+ fill="currentColor"
+ xmlns="http://www.w3.org/2000/svg"
+ aria-hidden="true">
+ <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z" />
+ </svg>
+);
+
+const DiscordGlyph = ({width = 20, height = 20}) => (
+ <svg
+ width={width}
+ height={height}
+ viewBox="0 0 24 24"
+ fill="currentColor"
+ xmlns="http://www.w3.org/2000/svg"
+ aria-hidden="true">
+ <path d="M20.317 4.37a19.79 19.79 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.74 19.74 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057a.082.082 0 0 0 .031.057 19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.548-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z" />
+ </svg>
+);
+
+// Shared shape for any titled link rendered in the bottom-of-page
+// Resources grid (long-form guides, legal pages, and community
+// channels all use this). title/description/href feed the
+// XDSListItem chrome; icon renders in the startContent slot at
+// ~20px (Heroicons + the brand glyphs above are interchangeable
+// since both accept the same width/height prop shape).
+interface Resource {
+ title: string;
description: string;
href: string;
- /** XDSClickableCard color variant — uses XDS's built-in
- * categorical color variants (the XDS-correct way to color a
- * card; inline `style={{backgroundColor}}` is silently
- * dropped by XDSClickableCard, which only honors its own
- * `variant` prop for backgrounds). */
- variant: 'yellow' | 'green' | 'blue';
+ icon: React.ComponentType<{width?: number; height?: number}>;
}
-const CHANNELS: ReadonlyArray<Channel> = [
+// Communications channels — where the community talks. Same
+// Resource shape as the documentation/legal lists below so the
+// whole bottom-of-page area renders with one consistent
+// list-item treatment (small icon + title + description) instead
+// of competing visual languages. Channels carry brand glyphs
+// (GitHub, X, Discord) so they're instantly recognizable in the
+// list.
+const CHANNELS: ReadonlyArray<Resource> = [
{
- name: 'GitHub Discussions',
+ title: 'GitHub Issues',
description:
- 'Ask questions, share what you built, and talk through ideas with the maintainers.',
- href: `${GITHUB_REPO}/discussions`,
- variant: 'yellow',
+ 'File bugs and feature requests. Triaged weekly with response within a few days.',
+ href: `${GITHUB_REPO}/issues`,
+ icon: GitHubGlyph,
},
{
- name: 'GitHub Issues',
+ title: 'Twitter',
description:
- 'File bugs and feature requests. Triaged weekly with response within a few days.',
- href: `${GITHUB_REPO}/issues`,
- variant: 'green',
+ 'Follow along for release notes, design notes, and behind-the-scenes from the team.',
+ // TODO: replace with the real Astryx Twitter URL once the
+ // account is live.
+ href: '#',
+ icon: TwitterGlyph,
},
{
- name: 'Wiki & Decisions',
+ title: 'Discord',
description:
- 'Architecture decisions, API conventions, and research notes from how Astryx gets built.',
- href: WIKI_BASE,
- variant: 'blue',
+ 'Hang out with the community in real time. Ask questions, share work, and trade ideas.',
+ // TODO: replace with the real Astryx Discord invite URL once
+ // the server is live.
+ href: '#',
+ icon: DiscordGlyph,
},
];
@@ -751,10 +807,10 @@ interface StartHerePath {
description: string;
href: string;
effort: string;
- /** Card fill color — the soft pastel --color-background-{hue}
- * (categorical badge backdrop). Resolves to the hue at ~20%
- * alpha, so the body color shows through. */
- bgColor: string;
+ /** Optional preview image rendered in the card's image slot.
+ * When omitted, the card renders with text only — no image
+ * placeholder, so empty cards stay visually clean. */
+ image?: {src: string; alt: string};
}
const START_HERE: ReadonlyArray<StartHerePath> = [
@@ -764,15 +820,21 @@ const START_HERE: ReadonlyArray<StartHerePath> = [
'Spot something broken? File an issue to confirm it, then submit a change with a clear reproduction.',
href: `${GITHUB_REPO}/issues/new?template=bug.yml`,
effort: '~2 hours',
- bgColor: 'var(--color-background-body)',
+ image: {
+ src: '/feature-bug.png',
+ alt: 'Bug report illustration with issue tracker and code snippet',
+ },
},
{
title: 'Improve the docs',
description:
- 'Fix typos, improve examples, fill gaps. Reviewed for correctness — precision over comprehensiveness.',
+ 'Fix typos, improve examples, and fill gaps. Reviewed for correctness and clarity.',
href: '/docs',
effort: '~30 min',
- bgColor: 'var(--color-background-body)',
+ image: {
+ src: '/feature-docs.png',
+ alt: 'Docs page preview showing the Astryx documentation site',
+ },
},
{
title: 'Add a template',
@@ -780,84 +842,95 @@ const START_HERE: ReadonlyArray<StartHerePath> = [
'Show components in realistic context. Templates are training signal for both humans and LLMs.',
href: `${WIKI_BASE}/Contributing-Templates`,
effort: '~half day',
- bgColor: 'var(--color-background-body)',
+ image: {
+ src: '/feature-templates.png',
+ alt: 'Stacked theme preview pages cascading toward a fully designed Butter theme example',
+ },
},
{
title: 'Build a theme',
description:
- 'Full visual control through defineTheme() — tokens, component overrides, and mode switching.',
+ 'Full visual control through defineTheme(). Tokens, component overrides, and mode switching.',
href: '/docs/theme',
effort: '~1 day',
- bgColor: 'var(--color-background-body)',
+ image: {
+ src: '/feature-brand.png',
+ alt: 'Butter theme applied to a full product landing page with display script, primary CTA, and three product cards',
+ },
},
];
-// Long-form references — guides, conventions, dev setup. Rendered
-// as a compact link list (not cards) because they're references,
-// not action paths. Visual weight matches their navigational role.
-interface Resource {
- title: string;
- description: string;
- href: string;
- /** Heroicon component rendered in each resource row's
- * startContent slot. Docs entries use DocumentTextIcon;
- * legal/policy entries use ScaleIcon. */
- icon: React.ComponentType<{width?: number; height?: number}>;
+// Categorized resource groups — each renders as one column under
+// the shared "Resources" section heading, with its own small
+// uppercase eyebrow label so readers can scan by topic before
+// drilling into individual items.
+interface ResourceCategory {
+ /** Eyebrow label shown above the column (uppercase, tracked). */
+ label: string;
+ items: ReadonlyArray<Resource>;
}
-const RESOURCES: ReadonlyArray<Resource> = [
+const RESOURCE_CATEGORIES: ReadonlyArray<ResourceCategory> = [
{
- title: 'Contributing Guide',
- description:
- 'The full process, what we accept, and how proposals get reviewed.',
- href: `${WIKI_BASE}/Contributing`,
- icon: DocumentTextIcon,
+ label: 'Communications',
+ items: CHANNELS,
},
{
- title: 'Contributing with AI',
- description:
- 'Using AI assistants effectively within Astryx conventions — safe zones and common pitfalls.',
- href: `${WIKI_BASE}/Contributing-with-AI-Assistants`,
- icon: DocumentTextIcon,
+ label: 'Contributing',
+ items: [
+ {
+ title: 'Contributing Guide',
+ description:
+ 'The full process, what we accept, and how proposals get reviewed.',
+ href: `${WIKI_BASE}/Contributing`,
+ icon: DocumentTextIcon,
+ },
+ {
+ title: 'Contributing with AI',
+ description:
+ 'How to use AI assistants effectively within Astryx conventions.',
+ href: `${WIKI_BASE}/Contributing-with-AI-Assistants`,
+ icon: DocumentTextIcon,
+ },
+ {
+ title: 'Dev Setup',
+ description: 'Clone, install, build, and run Storybook locally.',
+ href: `${GITHUB_REPO}/blob/main/CONTRIBUTING.md`,
+ icon: DocumentTextIcon,
+ },
+ {
+ title: 'API Conventions',
+ description:
+ 'How components in Astryx are named, shaped, and composed.',
+ href: `${WIKI_BASE}/API-Conventions`,
+ icon: DocumentTextIcon,
+ },
+ {
+ title: 'API Arbitration',
+ description: 'How we settle design disagreements using vibe testing.',
+ href: `${WIKI_BASE}/API-Arbitration`,
+ icon: DocumentTextIcon,
+ },
+ ],
},
{
- title: 'API Conventions',
- description:
- 'How components in Astryx are named, shaped, and composed. Worth a skim before sharing a proposal.',
- href: `${WIKI_BASE}/API-Conventions`,
- icon: DocumentTextIcon,
- },
- {
- title: 'API Arbitration',
- description:
- 'How we settle design disagreements using vibe testing. Includes a sample prompt you can borrow.',
- href: `${WIKI_BASE}/API-Arbitration`,
- icon: DocumentTextIcon,
- },
- {
- title: 'Dev Setup',
- description: 'Clone, install, build, and run Storybook locally.',
- href: `${GITHUB_REPO}/blob/main/CONTRIBUTING.md`,
- icon: DocumentTextIcon,
- },
-];
-
-// Legal resources — same Resource shape as documentation above,
-// just with a different icon to visually distinguish policy
-// entries from long-form guides.
-const LEGAL_RESOURCES: ReadonlyArray<Resource> = [
- {
- title: 'Code of Conduct',
- description:
- 'Our standards for respectful collaboration and how we handle reports.',
- href: `${GITHUB_REPO}/blob/main/CODE_OF_CONDUCT.md`,
- icon: ScaleIcon,
- },
- {
- title: 'MIT License',
- description: 'Astryx is open source under the MIT License — free to use.',
- href: `${GITHUB_REPO}/blob/main/LICENSE`,
- icon: ScaleIcon,
+ label: 'Legal',
+ items: [
+ {
+ title: 'Code of Conduct',
+ description:
+ 'Our standards for respectful collaboration and how we handle reports.',
+ href: `${GITHUB_REPO}/blob/main/CODE_OF_CONDUCT.md`,
+ icon: ScaleIcon,
+ },
+ {
+ title: 'MIT License',
+ description:
+ 'Astryx is open source under the MIT License. Free to use.',
+ href: `${GITHUB_REPO}/blob/main/LICENSE`,
+ icon: ScaleIcon,
+ },
+ ],
},
];
@@ -977,9 +1050,13 @@ export default async function CommunityPage() {
</XDSVStack>
{RFC_STEPS.map(step => (
<div key={step.number} {...stylex.props(styles.processStep)}>
- <span {...stylex.props(styles.processStepNumber)}>
+ <XDSText
+ type="body"
+ weight="semibold"
+ color="secondary"
+ xstyle={styles.processStepNumber}>
{step.number}
- </span>
+ </XDSText>
<XDSVStack gap={1}>
<XDSHeading level={3}>{step.title}</XDSHeading>
<XDSText type="supporting" color="secondary">
@@ -989,13 +1066,12 @@ export default async function CommunityPage() {
</div>
))}
</div>
- {/* Right column: contribution-type cards as one fused
- 2×2 quadrant block. Each quadrant is still its own
- click target via XDSClickableCard, but the colors
- touch directly at the inner seams (no gap, no
- divider) and the outer wrapper clips them to a
- single rounded shape so the four quadrants read as
- one grouped object. */}
+ {/* Right column: contribution-type cards as a 2-col
+ grid of independent feature-style cards (mirrors
+ the home page's FeaturesShowcase pattern). Each
+ card has a heading, description, effort badge, an
+ Explore link, and an optional bottom-anchored
+ image with bleed margins. */}
<div {...stylex.props(styles.contribTypes)}>
<div {...stylex.props(styles.blockGrid)}>
{START_HERE.map(path => (
@@ -1004,117 +1080,73 @@ export default async function CommunityPage() {
label={path.title}
description={path.description}
href={path.href}
- bgColor={path.bgColor}
badge={path.effort}
+ image={path.image}
/>
))}
</div>
</div>
</div>
- {/* End-of-page block — Poliform-style unified treatment
- that fuses Channels + References + Legal into one
- cohesive bottom-of-page chapter. Editorial header
- on top (headline + paragraph + brand-shape art);
- 3-column link list below; giant "astryx" wordmark
- anchors the bottom-right corner. */}
+ {/* End-of-page Resources block — unifies Communications
+ (Issues, Twitter, Discord) + Contributing + Design +
+ Legal into one categorized list grid. Editorial
+ header sets the intent; the grid below scans by
+ category. */}
<div {...stylex.props(styles.endBlock)}>
- <div {...stylex.props(styles.endBlockHeader)}>
- <XDSVStack gap={3} xstyle={styles.endBlockHeaderText}>
- <XDSHeading level={2} type="display-2">
- Engage with us in conversation
- </XDSHeading>
- <XDSText type="body" color="secondary">
- In a global community built on shared craft, a system gets
- better when its users open up to new perspectives. The
- brightest minds shape Astryx together — pick a channel, read
- the references, or just say hi.
- </XDSText>
- </XDSVStack>
-
- {/* 3-column channel grid — tall portrait cards with
- a pastel categorical fill, title anchored top-
- left, description anchored bottom-left, and a
- generous open middle. Whole card is the click
- target via XDSClickableCard. */}
- <div {...stylex.props(styles.channelGrid)}>
- {CHANNELS.map(channel => (
- <XDSClickableCard
- key={channel.name}
- label={`Open ${channel.name}`}
- href={channel.href}
- target="_blank"
- padding={6}
- variant={channel.variant}
- xstyle={styles.channelCard}>
- <XDSVStack
- gap={2}
- vAlign="end"
- height="100%"
- xstyle={styles.channelCardInner}>
- <XDSHeading level={3}>{channel.name}</XDSHeading>
- <XDSText type="supporting" color="secondary">
- {channel.description}
- </XDSText>
- </XDSVStack>
- </XDSClickableCard>
- ))}
- </div>
- </div>
-
- {/* Resources — Documentation + Legal as two Pill
- sub-stacks under one shared section heading. Each
- pill is the same XDSClickableCard chrome the
- channels above use, so the whole bottom of the
- page shares one visual language. Documentation
- takes the wider column (it has 5 items); Legal
- sits to the right (2 items). */}
<div {...stylex.props(styles.endBlockResources)}>
- <XDSVStack gap={1}>
- <XDSHeading level={2} type="display-2">
- Resources
- </XDSHeading>
- <XDSText type="body" color="secondary">
- Long-form guides, conventions, and policies. Skim what's
- relevant before sharing a proposal, or come back when you need
- to look something up.
- </XDSText>
- </XDSVStack>
- {/* All resources (docs + legal) flattened into one
- list, then chunked into 3 column-groups so the
- 7 items flow as a 3 / 3 / 1 layout across the
- 3-column grid. Each chunk is its own XDSList so
- items in a column stack vertically as one
- logical list (rather than CSS-columns breaking
- description text mid-item). */}
+ <XDSHeading
+ level={2}
+ type="display-2"
+ xstyle={styles.endBlockHeaderText}>
+ Resources
+ </XDSHeading>
+ {/* Categorized resource columns — each category
+ (Contributing, Design, Legal) gets its own
+ column with a small uppercase eyebrow label
+ above its XDSList. Readers can scan by topic
+ before drilling into individual items. */}
<div {...stylex.props(styles.endBlockResourcesGrid)}>
- {(() => {
- const allResources = [...RESOURCES, ...LEGAL_RESOURCES];
- // Split into 3 chunks as evenly as possible.
- // ceil(N/3) per chunk fills columns left-to-right.
- const chunkSize = Math.ceil(allResources.length / 3);
- const chunks: Resource[][] = [];
- for (let i = 0; i < allResources.length; i += chunkSize) {
- chunks.push(allResources.slice(i, i + chunkSize));
- }
- return chunks.map((chunk, columnIndex) => (
- <XDSList key={columnIndex}>
- {chunk.map(resource => {
+ {RESOURCE_CATEGORIES.map(category => (
+ <div
+ key={category.label}
+ {...stylex.props(styles.resourceColumn)}>
+ <XDSHeading level={4} color="primary">
+ {category.label}
+ </XDSHeading>
+ <XDSList xstyle={styles.resourceList}>
+ {category.items.map(resource => {
const Icon = resource.icon;
return (
<XDSListItem
key={resource.title}
label={resource.title}
- description={resource.description}
+ // Wrap the description string in a span
+ // (ReactNode, not plain string) so XDSItem
+ // skips its automatic single-line truncation
+ // and the description wraps to 2 lines
+ // naturally — the resourceDescription style
+ // below clamps at 2 lines so it never grows
+ // unbounded across short columns.
+ description={
+ <span
+ {...stylex.props(styles.resourceDescription)}>
+ {resource.description}
+ </span>
+ }
href={resource.href}
target="_blank"
- startContent={<Icon width={20} height={20} />}
+ startContent={
+ <span {...stylex.props(styles.iconTile)}>
+ <Icon width={18} height={18} />
+ </span>
+ }
/>
);
})}
</XDSList>
- ));
- })()}
+ </div>
+ ))}
</div>
</div>
</div>
diff --git a/apps/docsite/src/app/(site)/page.tsx b/apps/docsite/src/app/(site)/page.tsx
index 631dc50447..711be2305f 100644
--- a/apps/docsite/src/app/(site)/page.tsx
+++ b/apps/docsite/src/app/(site)/page.tsx
@@ -6,8 +6,8 @@ import {useEffect, useRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSLink} from '@xds/core/Link';
-import {XDSDivider} from '@xds/core/Divider';
-import {XDSHStack, XDSVStack} from '@xds/core/Layout';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSVStack} from '@xds/core/Layout';
import {XDSGrid} from '@xds/core/Grid';
import {XDSButton} from '@xds/core/Button';
import {spacingVars} from '@xds/core/theme/tokens.stylex';
@@ -36,11 +36,37 @@ const styles = stylex.create({
textAlign: 'center',
gap: spacingVars['--spacing-12'],
},
+ // Wrapper around the wordmark + floating Beta badge. Sized
+ // exactly to the wordmark image (display:inline-block with no
+ // explicit width, so the inline element shrinks to the image's
+ // natural rendered width) and centered horizontally by the
+ // parent VStack's align:stretch + the wrapper's marginInline:
+ // auto. position:relative establishes the positioning context
+ // for the absolutely-positioned Beta badge.
+ heroWordmarkWrap: {
+ position: 'relative',
+ display: 'inline-block',
+ alignSelf: 'center',
+ },
heroWordmark: {
display: 'block',
height: 42,
width: 'auto',
},
+ // Floating Beta badge wrapper — positions the XDSBadge above
+ // the wordmark (bottom anchored to the wordmark's top edge)
+ // and offset right so it reads as a callout attached to the
+ // brand mark without overlapping any of the glyphs. The XDS
+ // Badge component carries the pill chrome (background, radius,
+ // typography); only positioning + rotation lives here.
+ heroWordmarkBeta: {
+ position: 'absolute',
+ bottom: '100%',
+ right: -24,
+ marginBottom: 4,
+ transform: 'rotate(8deg)',
+ transformOrigin: 'bottom right',
+ },
heroButtons: {
width: '100%',
maxWidth: 420,
@@ -104,15 +130,20 @@ export default function HomePage() {
data-home-page="true"
align="stretch"
xstyle={styles.heroContent}>
- <img
- src="/astryx-logo.svg"
- alt="Astryx"
- {...stylex.props(styles.heroWordmark)}
- />
+ <div {...stylex.props(styles.heroWordmarkWrap)}>
+ <img
+ src="/astryx-logo.svg"
+ alt="Astryx"
+ {...stylex.props(styles.heroWordmark)}
+ />
+ <span {...stylex.props(styles.heroWordmarkBeta)}>
+ <XDSBadge label="Beta" variant="blue" />
+ </span>
+ </div>
<XDSHeading level={1} type="display-1" color="primary">
An open source design system that's fully customizable and agent ready
</XDSHeading>
- <XDSVStack gap={8} align="center">
+ <XDSVStack gap={4} align="center">
<XDSGrid columns={2} gap={3} xstyle={styles.heroButtons}>
<XDSButton
variant="primary"
@@ -127,29 +158,18 @@ export default function HomePage() {
href="/components"
/>
</XDSGrid>
- <XDSHStack gap={2} align="center">
- <XDSText display="block" type="supporting">
- Currently in{' '}
- <XDSText type="inherit" weight="bold">
- Beta
- </XDSText>
- </XDSText>
- <XDSDivider
- orientation="vertical"
- variant="strong"
- style={{height: '0.75em'}}
- />
- <XDSText display="block" type="supporting">
- Built on{' '}
- <XDSLink
- type="inherit"
- color="inherit"
- href="https://react.dev/"
- hasUnderline>
- React
- </XDSLink>
- </XDSText>
- </XDSHStack>
+ <XDSText display="block">
+ Built on{' '}
+ <XDSLink
+ type="body"
+ color="primary"
+ href="https://react.dev"
+ target="_blank"
+ rel="noopener noreferrer"
+ hasUnderline>
+ React
+ </XDSLink>
+ </XDSText>
</XDSVStack>
</XDSVStack>
<XDSVStack ref={showcaseRef} xstyle={styles.showcaseOverlay}>
diff --git a/apps/docsite/src/app/layout.tsx b/apps/docsite/src/app/layout.tsx
index c31e1c152a..d3fbcbfedc 100644
--- a/apps/docsite/src/app/layout.tsx
+++ b/apps/docsite/src/app/layout.tsx
@@ -12,7 +12,7 @@ import {Providers} from './providers';
// "Good" path from the theming wiki §Font Declarations.
export const metadata: Metadata = {
- title: 'XDS — Design System',
+ title: 'Astryx — Design System',
description:
'Open-source design system for building internal tools and products.',
icons: {
diff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsx
index 0f5f7ca902..600c69faba 100644
--- a/apps/docsite/src/app/playground/PlaygroundClient.tsx
+++ b/apps/docsite/src/app/playground/PlaygroundClient.tsx
@@ -122,7 +122,7 @@ export default function Demo() {
<XDSVStack gap={4}>
<XDSVStack>
<XDSHeading level={3}>
- XDS Playground
+ Astryx Playground
</XDSHeading>
<XDSText color="secondary">
Edit the code and see live changes.
diff --git a/apps/docsite/src/app/playground/page.tsx b/apps/docsite/src/app/playground/page.tsx
index 030a877821..691039ee04 100644
--- a/apps/docsite/src/app/playground/page.tsx
+++ b/apps/docsite/src/app/playground/page.tsx
@@ -4,8 +4,8 @@ import type {Metadata} from 'next';
import {PlaygroundClient} from './PlaygroundClient';
export const metadata: Metadata = {
- title: 'XDS Playground',
- description: 'Interactive code playground for XDS components',
+ title: 'Astryx Playground',
+ description: 'Interactive code playground for Astryx components',
};
export default function PlaygroundPage() {
diff --git a/apps/docsite/src/components/SharedTopNav.tsx b/apps/docsite/src/components/SharedTopNav.tsx
index 5d19954571..616981cc3a 100644
--- a/apps/docsite/src/components/SharedTopNav.tsx
+++ b/apps/docsite/src/components/SharedTopNav.tsx
@@ -72,7 +72,7 @@ export function SharedTopNav() {
return (
<>
<XDSTopNav
- label="XDS navigation"
+ label="Astryx navigation"
heading={<XDSTopNavHeading logo={XDS_BRAND_ICON} headingHref="/" />}
centerContent={
<>
diff --git a/apps/docsite/src/components/ThemePackagePage.tsx b/apps/docsite/src/components/ThemePackagePage.tsx
index fb49e5c91e..8c9e2cc4d1 100644
--- a/apps/docsite/src/components/ThemePackagePage.tsx
+++ b/apps/docsite/src/components/ThemePackagePage.tsx
@@ -23,6 +23,21 @@ import {ThemeShowcasePreview} from './ThemeShowcasePreview';
import {ThemeCardShowcase} from './ThemeCardShowcase';
import {getThemeImages} from './themeImages';
+// 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)',
+ },
+});
+
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
@@ -57,6 +72,13 @@ const styles = stylex.create({
// 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)',
@@ -64,14 +86,29 @@ const styles = stylex.create({
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: 960,
+ maxWidth: 1280,
marginInline: 'auto',
borderRadius: 'var(--radius-full)',
boxShadow: 'var(--shadow-high)',
diff --git a/apps/docsite/src/components/ThemeShowcasePreview.tsx b/apps/docsite/src/components/ThemeShowcasePreview.tsx
index f92606868b..96260042f5 100644
--- a/apps/docsite/src/components/ThemeShowcasePreview.tsx
+++ b/apps/docsite/src/components/ThemeShowcasePreview.tsx
@@ -68,11 +68,24 @@ const styles = stylex.create({
maxWidth: 960,
marginInline: 'auto',
},
- // Fill the full available width instead of capping at 960. Used by the
- // theme playground where the preview pane is wider than the /themes/<name>
- // detail card and the grid should stretch edge-to-edge.
+ // Fluid mode used by the theme playground. Caps the showcase at
+ // a sensible max-width so the product grid (3 cards at 240px min +
+ // 16px gap) fills the container naturally — wider caps left a
+ // gutter of unused space on the trailing edge because XDSGrid's
+ // auto-fill column algorithm pads tracks to the start of the row.
+ // Stays centered via the base `content` rule's marginInline:auto.
contentFluid: {
- maxWidth: 'none',
+ maxWidth: 880,
+ },
+ // Center-align the text inside each product card. The parent VStack
+ // pinches block-level children to the centre via hAlign="center",
+ // but heading/description text still anchors to the start of its
+ // own block unless `text-align: center` is applied. We use a
+ // stylex rule instead of the XDSHeading/XDSText `justify` prop
+ // because the docsite consumes the published @xds/core build,
+ // which doesn't expose `justify` yet.
+ centerText: {
+ textAlign: 'center',
},
});
@@ -171,7 +184,9 @@ export function ThemeShowcasePreview({
<XDSSection padding={8} variant="transparent">
<XDSVStack
gap={10}
- xstyle={fluid ? [styles.content, styles.contentFluid] : styles.content}>
+ xstyle={
+ fluid ? [styles.content, styles.contentFluid] : styles.content
+ }>
<XDSCenter>
<XDSVStack gap={4} hAlign="center" xstyle={styles.heroText}>
<XDSText type="display-3">
@@ -198,18 +213,23 @@ export function ThemeShowcasePreview({
/>
</XDSAspectRatio>
<div {...stylex.props(styles.cardBody)}>
- <XDSVStack gap={2} xstyle={styles.cardStack}>
+ <XDSVStack
+ gap={2}
+ hAlign="center"
+ xstyle={styles.cardStack}>
<XDSHStack>
<XDSBadge label={p.badge} variant={p.badgeVariant} />
</XDSHStack>
- <XDSHeading level={2}>{p.name}</XDSHeading>
+ <XDSHeading level={2} xstyle={styles.centerText}>
+ {p.name}
+ </XDSHeading>
<XDSText
type="supporting"
color="secondary"
- xstyle={styles.cardDescription}>
+ xstyle={[styles.cardDescription, styles.centerText]}>
{p.description}
</XDSText>
- <XDSHStack gap={2} vAlign="center">
+ <XDSHStack gap={2} vAlign="center" hAlign="center">
<XDSNumberInput
label="Quantity"
isLabelHidden
diff --git a/apps/docsite/src/components/ThemeShowcaseTile.tsx b/apps/docsite/src/components/ThemeShowcaseTile.tsx
index 9b469f30e2..6f857bdca3 100644
--- a/apps/docsite/src/components/ThemeShowcaseTile.tsx
+++ b/apps/docsite/src/components/ThemeShowcaseTile.tsx
@@ -434,10 +434,14 @@ export function ThemeShowcaseTile({
}, [themeName]);
const imageSrc = candidates[candidateIndex];
const showImage = imageSrc !== undefined;
- // Theme detail page URL. Strip the @xds/ scope from the package
- // name to match the [name] segment of /packages/[name].
+ // 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
- ? `/packages/${themeName.replace('@xds/', '')}`
+ ? `/themes/${themeName.replace(/^@xds\/theme-/, '')}`
: undefined;
return (
diff --git a/apps/docsite/src/components/XDSWordmark.tsx b/apps/docsite/src/components/XDSWordmark.tsx
index a37985ea83..0b550e665c 100644
--- a/apps/docsite/src/components/XDSWordmark.tsx
+++ b/apps/docsite/src/components/XDSWordmark.tsx
@@ -5,7 +5,7 @@
export const XDS_BRAND_ICON = (
<img
src="/brand-icon.svg"
- alt="XDS"
+ alt="Astryx"
width={24}
height={24}
style={{display: 'block'}}
diff --git a/apps/docsite/src/themes/astryxTheme.ts b/apps/docsite/src/themes/astryxTheme.ts
index d2aa22db74..71dbd89b43 100644
--- a/apps/docsite/src/themes/astryxTheme.ts
+++ b/apps/docsite/src/themes/astryxTheme.ts
@@ -36,6 +36,13 @@ export const astryxTheme = defineTheme({
// warm Astryx cream; dark falls back to the XDS default body color
// (a flat static value here would freeze the page in light mode).
'--color-background-body': 'light-dark(#F8F4ED, #111112)',
+ // Re-tint the categorical "gray" surface to match the page body
+ // background. Cards rendered with `variant="gray"` (e.g. landing
+ // feature cards) blend into the body, reading as content groups
+ // shaped by padding + corners rather than as a coloured surface.
+ // Dark mode keeps the default --color-background-gray tint so
+ // recessed surfaces stay readable against the dark body.
+ '--color-background-gray': 'light-dark(#F8F4ED, rgba(102, 106, 114, 0.30))',
// Astryx display headings render semibold (XDS default is normal weight).
'--text-display-1-weight': 'var(--font-weight-semibold)',
'--text-display-2-weight': 'var(--font-weight-semibold)',