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.pngnew file mode 100644index 0000000000..acc1e42545Binary files /dev/null and b/apps/docsite/public/feature-brand.png differdiff --git a/apps/docsite/public/feature-bug.png b/apps/docsite/public/feature-bug.pngnew file mode 100644index 0000000000..9904d66ed2Binary files /dev/null and b/apps/docsite/public/feature-bug.png differdiff --git a/apps/docsite/public/feature-cli.png b/apps/docsite/public/feature-cli.pngnew file mode 100644index 0000000000..b34a241ce1Binary files /dev/null and b/apps/docsite/public/feature-cli.png differdiff --git a/apps/docsite/public/feature-components.png b/apps/docsite/public/feature-components.pngnew file mode 100644index 0000000000..343650c534Binary files /dev/null and b/apps/docsite/public/feature-components.png differdiff --git a/apps/docsite/public/feature-docs.png b/apps/docsite/public/feature-docs.pngnew file mode 100644index 0000000000..f2becd6545Binary files /dev/null and b/apps/docsite/public/feature-docs.png differdiff --git a/apps/docsite/public/feature-measured-and-tested.png b/apps/docsite/public/feature-measured-and-tested.pngnew file mode 100644index 0000000000..1afa32a0e7Binary files /dev/null and b/apps/docsite/public/feature-measured-and-tested.png differdiff --git a/apps/docsite/public/feature-templates.png b/apps/docsite/public/feature-templates.pngnew file mode 100644index 0000000000..432325e423Binary files /dev/null and b/apps/docsite/public/feature-templates.png differdiff --git a/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx b/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsxindex 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 theengineers, 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.tsxindex 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><XDSLinktype="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 anywhere. Change anything. Ship 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.tsxindex 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}><XDSHeadinglevel={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 (<XDSVStackas="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.tsxindex 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"+ hasUnderlinexstyle={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 (<XDSClickableCardlabel={`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 (<XDSListItemkey={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.tsxindex 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}><XDSButtonvariant="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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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"><XDSVStackgap={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><XDSTexttype="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"><XDSNumberInputlabel="Quantity"isLabelHiddendiff --git a/apps/docsite/src/components/ThemeShowcaseTile.tsx b/apps/docsite/src/components/ThemeShowcaseTile.tsxindex 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.tsxindex 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 = (<imgsrc="/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.tsindex 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)',