An open source design system that's fully customizable and agent ready
TypeScript
docsite(landing): home page body refresh (features, about, discover) (#2637)
rubyycheung7fdc19c5fd80
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 3af5a6ab83..bf1a6e6bcd 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -67,6 +67,12 @@ jobs:- run: pnpm install --frozen-lockfile+ # docsite `generate` runs `xds theme build`, which imports the compiled+ # @xds/core/theme entry (dist/theme/index.js). Build core first so that+ # entry exists — otherwise generate fails with "Cannot find module".+ - name: Build core package+ run: pnpm -F @xds/core build+- name: Generate and test docsite datarun: pnpm -F @xds/docsite generate && pnpm -F @xds/docsite testdiff --git a/apps/docsite/public/feature-brand.png b/apps/docsite/public/feature-brand.pngindex acc1e42545..1120d9be22 100644Binary files a/apps/docsite/public/feature-brand.png and b/apps/docsite/public/feature-brand.png differdiff --git a/apps/docsite/public/feature-cli.png b/apps/docsite/public/feature-cli.pngindex b34a241ce1..ec7c0c0fa4 100644Binary files a/apps/docsite/public/feature-cli.png and b/apps/docsite/public/feature-cli.png differdiff --git a/apps/docsite/public/feature-components.png b/apps/docsite/public/feature-components.pngindex 343650c534..0ae920ce23 100644Binary files a/apps/docsite/public/feature-components.png and b/apps/docsite/public/feature-components.png differdiff --git a/apps/docsite/public/feature-templates.png b/apps/docsite/public/feature-templates.pngindex 432325e423..efd4a38664 100644Binary files a/apps/docsite/public/feature-templates.png 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 0846b2863a..407b920958 100644--- a/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx+++ b/apps/docsite/src/app/(site)/_landing/AboutShowcase.tsx@@ -4,146 +4,243 @@import type {ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';-import {XDSCard, XDSVStack} from '@xds/core/Layout';-import {XDSGrid} from '@xds/core/Grid';-import {XDSAspectRatio} from '@xds/core/AspectRatio';+import {XDSVStack} from '@xds/core/Layout';import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSLink} from '@xds/core/Link';+import {spacingVars} from '@xds/core/theme/tokens.stylex';++// Editorial-style "about" section: a left-anchored heading block sits+// alongside three feature columns. Each feature column leads with a+// small pastel decorative shape, then a bold title, body copy, and a+// "→" CTA link. The four blocks share a single CSS grid so they snap+// to a clean 1fr / 1fr / 1fr / 1fr layout at >=720px and reflow into+// a single stacked column below that. We skip an intermediate 2-col+// breakpoint on purpose — with 1 heading + 3 features, a 2-col grid+// produces an awkward orphan column on the last row.+//+// Decorative shape fills — pulled from the categorical+// (non-semantic) background tokens so the shapes pick up each+// theme's pink / purple / yellow ramp automatically and invert+// for dark mode without hand-rolled palettes. These tokens are+// 33% alpha pastel washes by default, which read perfectly as+// soft decorative blobs on the white showcase surface, and any+// theme can retint them centrally without touching this file.+const PINK_PASTEL = 'var(--color-background-pink)';+const LAVENDER_PASTEL = 'var(--color-background-purple)';+const YELLOW_PASTEL = 'var(--color-background-yellow)';++const SHAPE_SIZE = 40;const styles = stylex.create({- headingBlock: {- textAlign: 'center',+ // Cap the section at the same 1200px maxWidth used by sibling+ // showcases (Features, Discover) so all three sections line up+ // vertically inside the showcaseOverlay container.+ sectionLayout: {width: '100%',- maxWidth: 680,+ maxWidth: 1200,},- // Layout glue for the XDSGrid: cap at 1200px. XDSGrid doesn't expose- // maxWidth as a prop, so we pass it through xstyle.- gridLayout: {+ // Responsive grid for the heading + 3 feature columns.+ //+ // Breakpoints (mirrors FeaturesShowcase):+ // < 1024px -> 1 column (everything stacks vertically)+ // >= 1024px -> heading 1fr | 3-feature-grid 2fr side-by-side+ //+ // We skip the intermediate 2-col arrangement because at+ // 720-1023 the 1fr / 2fr split squishes each sub-column to+ // ~150px which makes the body copy unreadable. Going straight+ // from 1-col stack to the full desktop layout keeps the design+ // legible at every width.+ grid: {width: '100%',- maxWidth: 1200,+ display: 'grid',+ gap: spacingVars['--spacing-8'],+ gridTemplateColumns: {+ default: '1fr',+ '@media (min-width: 1024px)': '1fr 2fr',+ },},- iconSlot: {- height: 40,+ // Inner sub-grid for the three feature columns — split evenly+ // inside the 2/3 cell on the right of the parent grid. Same+ // breakpoint as the outer grid so the stack/3-col switch+ // happens together.+ columnsGrid: {+ display: 'grid',+ gap: spacingVars['--spacing-8'],+ gridTemplateColumns: {+ default: '1fr',+ '@media (min-width: 1024px)': 'repeat(3, 1fr)',+ },},- // "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',+ // Each feature column: shape on top, then a small gap, then title,+ // body, and link. Always flush-left at every viewport — at desktop+ // it reads as a side-by-side editorial layout; at mobile the+ // columns stack vertically but stay left-aligned for consistency.+ column: {+ width: '100%',+ alignItems: 'flex-start',+ textAlign: 'start',},- // 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,+ // Mobile centering for the section heading + description block.+ // Same breakpoint as the column stack — when everything is in a+ // single vertical column, the eye expects centered content; the+ // start-aligned look only makes sense in the side-by-side grid.+ headingBlock: {+ width: '100%',+ alignItems: {+ default: 'center',+ '@media (min-width: 1024px)': 'flex-start',+ },+ textAlign: {+ default: 'center',+ '@media (min-width: 1024px)': 'start',+ },+ },+ // Decorative shape slot — fixed 40x40 box so the SVG renders at+ // the expected size and the column header sits at a consistent+ // baseline across all three feature columns.+ //+ // Rendered as a raw <span> in the JSX because XDS has no+ // primitive for "fixed-size inline-block decorative SVG wrapper"+ // (XDSIcon is glyph-only and bound to its registry; XDSThumbnail+ // is chat-attachment chrome). The wrapper exists purely to reserve+ // space and clip the shape — there is no semantic content here.+ shapeSlot: {+ width: SHAPE_SIZE,+ height: SHAPE_SIZE,+ display: 'block',+ flexShrink: 0,+ },+ // "→" arrow trail on the CTA link. Astryx's XDSLink renders inline+ // by default; the arrow lives inside the link label so it inherits+ // the link color + hover state automatically.+ cta: {+ // Bump the CTA away from the body text. The XDSVStack gap holds+ // title↔body at 8px; the CTA wants more breathing room (16px)+ // so the link reads as a separate action zone rather than part+ // of the paragraph.+ marginTop: spacingVars['--spacing-2'],},});-type AboutItem = {+type AboutColumn = {title: string;description: string;- link?: ReactNode;- icon: ReactNode;+ ctaLabel: string;+ ctaHref: string;+ shape: ReactNode;};-function BlobIcon() {+// All three decorative shapes are inherited verbatim from the+// pre-redesign AboutShowcase (origin/main) — the original file+// defined three soft, organic silhouettes (a 16-bump rounded+// flower/blob, a pillow-shaped rounded square with concave sides,+// and a rounded-corner diamond) that already match the "irregular+// pastel splat" treatment in the new design reference. We reuse+// the exact path data here, swap the orange-channel to pink, and+// render each shape at SHAPE_SIZE (40px) — same viewBox the+// original used so the path math stays unchanged.+//+// Mapping (original color -> new categorical token):+// BlobIcon (orange) -> --color-background-pink "Design for speed"+// SquareIcon (purple) -> --color-background-purple "Built by the people who use it"+// DiamondIcon (yellow) -> --color-background-yellow "Ready for what's next"++// Pink "rounded flower" blob — 16 alternating bumps around a circle.+// Reused verbatim from origin/main's BlobIcon (40x40 viewBox), just+// re-tinted from the orange categorical token to the pink one.+function PinkBlobShape() {return (<svg- width={40}- height={40}+ width={SHAPE_SIZE}+ height={SHAPE_SIZE}viewBox="0 0 40 40"fill="none"aria-hidden="true"><path- fill="var(--color-background-orange)"+ fill={PINK_PASTEL}d="M17.081 1.19166C18.7027 -0.397219 21.2973 -0.397219 22.919 1.19166C23.9616 2.21324 25.4625 2.61539 26.8763 2.25201C29.0751 1.68683 31.3221 2.98415 31.9321 5.17099C32.3243 6.57703 33.423 7.67574 34.829 8.06792C37.0159 8.67788 38.3132 10.9249 37.748 13.1237C37.3846 14.5375 37.7868 16.0384 38.8083 17.081C40.3972 18.7027 40.3972 21.2973 38.8083 22.919C37.7868 23.9616 37.3846 25.4625 37.748 26.8763C38.3132 29.0751 37.0159 31.3221 34.829 31.9321C33.423 32.3243 32.3243 33.423 31.9321 34.829C31.3221 37.0159 29.0751 38.3132 26.8763 37.748C25.4625 37.3846 23.9616 37.7868 22.919 38.8083C21.2973 40.3972 18.7027 40.3972 17.081 38.8083C16.0384 37.7868 14.5375 37.3846 13.1237 37.748C10.9249 38.3132 8.67788 37.0159 8.06792 34.829C7.67574 33.423 6.57703 32.3243 5.17099 31.9321C2.98415 31.3221 1.68683 29.0751 2.25201 26.8763C2.61539 25.4625 2.21324 23.9616 1.19166 22.919C-0.397219 21.2973 -0.397219 18.7027 1.19166 17.081C2.21324 16.0384 2.61539 14.5375 2.25201 13.1237C1.68683 10.9249 2.98415 8.67788 5.17099 8.06792C6.57703 7.67574 7.67574 6.57703 8.06792 5.17099C8.67788 2.98415 10.9249 1.68683 13.1237 2.25201C14.5375 2.61539 16.0384 2.21324 17.081 1.19166Z"/></svg>);}-function SquareIcon() {+// Lavender pillow / "soft cloud" — chunky rounded square with concave+// indents on each side. Reused verbatim from origin/main's SquareIcon,+// re-tinted from purple to lavender.+function LavenderCloudShape() {return (<svg- width={40}- height={40}+ width={SHAPE_SIZE}+ height={SHAPE_SIZE}viewBox="0 0 40 40"fill="none"aria-hidden="true"><path- fill="var(--color-background-purple)"+ fill={LAVENDER_PASTEL}d="M33.0469 0C36.8869 0.00014921 39.9999 3.11308 40 6.95312C40 9.9458 38.109 12.4963 35.457 13.4766C38.109 14.4568 39.9999 17.0074 40 20C40 22.9927 38.109 25.5431 35.457 26.5234C38.109 27.5037 39.9999 30.0542 40 33.0469C40 36.887 36.887 39.9998 33.0469 40H6.95312C3.113 39.9999 0 36.887 0 33.0469C9.21712e-05 30.0545 1.89042 27.5039 4.54199 26.5234C1.89043 25.5429 0 22.9924 0 20C9.21712e-05 17.0077 1.89042 14.457 4.54199 13.4766C1.89043 12.496 0 9.94549 0 6.95312C0.000107288 3.11307 3.11307 0.000125546 6.95312 0H33.0469Z"/></svg>);}-function DiamondIcon() {+// Yellow rounded diamond — a rotated rounded square. Reused verbatim+// from origin/main's DiamondIcon (28x28 inner rect, 6px corner+// radius, rotated 45deg around the 40x40 center), just re-tinted+// with a saturated pastel yellow.+function YellowDiamondShape() {return (- <svg width={40} height={40} viewBox="0 0 40 40" aria-hidden="true">+ <svg+ width={SHAPE_SIZE}+ height={SHAPE_SIZE}+ viewBox="0 0 40 40"+ aria-hidden="true"><rectx={6}y={6}width={28}height={28}rx={6}- fill="var(--color-background-yellow)"+ fill={YELLOW_PASTEL}transform="rotate(45 20 20)"/></svg>);}-const items: AboutItem[] = [+const columns: AboutColumn[] = [{- title: 'Designed for speed',+ title: 'Design for speed',description:'Foundations you can trust, speed you can feel. The system is built so teams stop reinventing the basics and start shipping the ideas that matter.',- link: (- <XDSLink- type="body"- color="primary"- href="/docs/getting-started"- hasUnderline>- Get started in minutes- </XDSLink>- ),- icon: <DiamondIcon />,+ ctaLabel: 'Get started in minutes →',+ ctaHref: '/docs/getting-started',+ shape: <PinkBlobShape />,},{title: 'Built by the people who use it',description:'The system gets sharper when we put it to work in the real world. Using it in context strengthens the whole system for everyone.',- link: (- <XDSLink type="body" color="primary" href="/community" hasUnderline>- Learn how to contribute- </XDSLink>- ),- icon: <BlobIcon />,+ ctaLabel: 'Learn how to contribute →',+ ctaHref: '/community',+ shape: <LavenderCloudShape />,},{title: "Ready for what's next",description:'The quality bar is accelerating. Astryx pairs opinionated foundations with flexible patterns so your system keeps pace — no matter how the craft evolves.',- link: (- <XDSLink type="body" color="primary" href="/changelog" hasUnderline>- See what's new- </XDSLink>- ),- icon: <SquareIcon />,+ ctaLabel: "See what's new →",+ ctaHref: '/changelog',+ shape: <YellowDiamondShape />,},];function AboutHeading() {return (- <XDSVStack gap={4} align="center" xstyle={styles.headingBlock}>- <XDSHeading level={4} color="primary" xstyle={styles.eyebrow}>- About us- </XDSHeading>+ <XDSVStack gap={4} xstyle={styles.headingBlock}><XDSHeading level={2} type="display-2" color="primary">Astryx powers over 13,000 apps</XDSHeading>- <XDSText type="body" color="secondary" xstyle={styles.descriptionWidth}>+ <XDSText type="large" weight="normal" color="secondary">Astryx has grown inside Meta over the last eight years, shaped by theengineers, designers, and product teams who depend on it every day.</XDSText>@@ -151,39 +248,49 @@ function AboutHeading() {);}-function AboutColumn({item}: {item: AboutItem}) {+function AboutColumn({column}: {column: AboutColumn}) {return (- <XDSCard padding={5}>- <XDSVStack gap={6}>- <XDSAspectRatio ratio={1} xstyle={styles.iconSlot}>- {item.icon}- </XDSAspectRatio>- <XDSVStack gap={1} align="stretch">- <XDSHeading level={3} color="primary">- {item.title}- </XDSHeading>- <XDSText type="body" color="secondary">- {item.description}- </XDSText>- </XDSVStack>- {item.link}+ <XDSVStack gap={3} xstyle={styles.column}>+ <span {...stylex.props(styles.shapeSlot)}>{column.shape}</span>+ <XDSVStack gap={2}>+ <XDSHeading level={2} color="primary">+ {column.title}+ </XDSHeading>+ <XDSText type="body" color="primary">+ {column.description}+ </XDSText></XDSVStack>- </XDSCard>+ <XDSLink+ type="body"+ color="primary"+ href={column.ctaHref}+ hasUnderline={false}+ xstyle={styles.cta}>+ {column.ctaLabel}+ </XDSLink>+ </XDSVStack>);}export function AboutShowcase() {return (- <XDSVStack as="section" align="center" gap={10} width="100%">- <AboutHeading />- <XDSGrid- columns={{minWidth: 280, repeat: 'fit'}}- gap={4}- xstyle={styles.gridLayout}>- {items.map(item => (- <AboutColumn key={item.title} item={item} />- ))}- </XDSGrid>+ <XDSVStack as="section" align="center" width="100%">+ {/* sectionLayout / grid / columnsGrid are kept as plain <div>s+ because each is a CSS-grid container with responsive+ `grid-template-columns` (see styles below). XDSGrid hardcodes+ a single integer column count and a single gap, so it can't+ express the 1fr-stack → 1fr/2fr → repeat(3, 1fr) responsive+ patterns this section needs. */}+ <div {...stylex.props(styles.sectionLayout)}>+ <div {...stylex.props(styles.grid)}>+ <AboutHeading />+ <div {...stylex.props(styles.columnsGrid)}>+ {columns.map(col => (+ <AboutColumn key={col.title} column={col} />+ ))}+ </div>+ </div>+ </div></XDSVStack>);}diff --git a/apps/docsite/src/app/(site)/_landing/DiscoverShowcase.tsx b/apps/docsite/src/app/(site)/_landing/DiscoverShowcase.tsxindex e396f1705e..0bfea391ba 100644--- a/apps/docsite/src/app/(site)/_landing/DiscoverShowcase.tsx+++ b/apps/docsite/src/app/(site)/_landing/DiscoverShowcase.tsx@@ -27,6 +27,12 @@ const styles = stylex.create({width: '100%',overflowX: 'clip',},+ // The "stage" hosts the absolutely-positioned floating preview+ // images + the centered CTA card. maxWidth: 1200 matches the+ // shared marketing-section cap used by FeaturesShowcase and+ // AboutShowcase so all three sections line up vertically inside+ // showcaseOverlay; the value isn't on the spacing scale, it's a+ // marketing page measure intentionally kept as a literal.stage: {position: 'relative',width: '100%',@@ -38,7 +44,10 @@ const styles = stylex.create({position: 'relative',width: '100%',zIndex: 1,- // 96px / 80px — beyond --spacing-12 (48px), so expressed as 2x token values.+ // 96px / 80px — beyond --spacing-12 (48px), so expressed as+ // calc() over spacing tokens (2× spacing-12, 2× spacing-10)+ // rather than as literals so the rhythm scales with any+ // future spacing-scale theme override.paddingBlock: `calc(${spacingVars['--spacing-12']} * 2)`,paddingInline: `calc(${spacingVars['--spacing-10']} * 2)`,},@@ -46,6 +55,13 @@ const styles = stylex.create({// anchored to one of the four card corners (slightly outside them).// The transform is animated from a centered "clumped" pose to the// resting pose with rotation when the section scrolls into view.+ //+ // width: 260 is a literal preview card size — these are decorative+ // marketing thumbnails tuned for the desktop composition, not a+ // size scale value. The 960px desktop-on breakpoint is a one-off+ // marketing cutoff (the spread-out poses overflow tighter+ // viewports awkwardly), not the standard 1024px breakpoint used+ // by FeaturesShowcase/AboutShowcase.floatingImage: {position: 'absolute',width: 260,@@ -62,9 +78,13 @@ const styles = stylex.create({'@media (min-width: 960px)': 'block',},},- // Starting "clumped" pose — all four images near the center of the card- // but with slight offsets and rotations so they fan out as an overlapping- // rosette (rather than perfectly stacked) before the spread animation.+ // Starting "clumped" pose — all four images near the center of the+ // card but with slight offsets and rotations so they fan out as an+ // overlapping rosette (rather than perfectly stacked) before the+ // spread animation. The translate offsets (60-80px) and small+ // rotations (5-8deg) are visual composition values picked to read+ // as a single tight cluster; literal because they're tied to+ // image dimensions, not to the spacing scale.floatTopLeftStart: {top: '50%',left: '50%',@@ -85,8 +105,14 @@ const styles = stylex.create({left: '50%',transform: 'translate(calc(-50% + 60px), calc(-50% + 32px)) rotate(-5deg)',},- // Resting "spread" poses — each image hugs a corner of the card with- // a slight offset outward so it overlaps just a little.+ // Resting "spread" poses — each image hugs a corner of the card+ // with a slight outward offset so it overlaps just a little. The+ // negative inset values (-64 / -32) are intentional bleed past the+ // stage edge so the floating images read as "popping out of" the+ // central card rather than being fully contained by it; literal+ // because they're spatial overhangs tied to image dimensions, not+ // spacing-scale values. Negative spacing tokens don't exist in+ // the scale, so even non-bleed offsets here would be literals.floatTopLeftEnd: {top: -64,left: -64,@@ -107,22 +133,40 @@ const styles = stylex.create({right: -32,transform: 'rotate(-6deg)',},+ // Inline wordmark glyph baked into the heading text. Sized by+ // `em` (.625em) so the wordmark scales with the heading's font+ // size automatically. marginInline: 16 is a literal because it+ // anchors to the heading glyph metrics, not the spacing scale —+ // the wordmark needs a precise visual gap before and after it+ // (slightly tighter than --spacing-5/20px, slightly wider than+ // --spacing-3/12px) so it reads as a single inline word.inlineWordmark: {display: 'inline-block',verticalAlign: 'baseline',height: '.625em',width: 'auto',- marginInline: 16,+ marginInline: spacingVars['--spacing-4'],},+ // CTA body copy + buttons cap. maxWidth: 560 is a reading+ // measure for the body paragraph, not a spacing-scale value.cardContent: {maxWidth: 560,textAlign: 'center',marginInline: 'auto',},+ // Two-up button row cap. maxWidth: 360 is a thumb-reachable+ // ergonomic value, not a spacing-scale step.buttonGrid: {width: '100%',maxWidth: 360,},+ // Reading-measure cap for the supporting text paragraph. Kept as+ // a stylex rule (instead of inline style) so it composes cleanly+ // with XDSText's xstyle pipeline. 480 is a body-copy reading+ // measure, not a spacing-scale value.+ supportingText: {+ maxWidth: 480,+ },});export function DiscoverShowcase() {@@ -152,7 +196,22 @@ export function DiscoverShowcase() {return (<XDSVStack as="section" gap={10} align="center" xstyle={styles.section}>+ {/* "stage" is kept as a raw <div> because its sole job is to+ act as the position:relative anchor for four+ absolutely-positioned floating preview <img>s + the+ centered XDSCard. XDSVStack / XDSHStack would impose flex+ semantics that fight the absolute positioning model and+ would also stack the floating images instead of layering+ them. */}<div ref={stageRef} {...stylex.props(styles.stage)}>+ {/* Floating decorative preview images. Kept as raw <img>s+ because @xds/core does not export a general-purpose+ image component (XDSThumbnail is chat-attachment chrome+ with built-in remove buttons; XDSIcon is a glyph+ registry). aria-hidden + empty alt keep them out of the+ accessibility tree — they're pure decoration that+ animates from a clumped pose to a spread pose when the+ section scrolls into view. */}<imgsrc="/discover-card-1.png"alt=""@@ -189,11 +248,17 @@ export function DiscoverShowcase() {spread ? styles.floatBottomRightEnd : styles.floatBottomRightStart,)}/>- <XDSCard variant="blue" padding={0} xstyle={styles.card}>- <XDSVStack gap={10} align="center" xstyle={styles.cardContent}>- <XDSVStack gap={4} align="center">+ <XDSCard variant="gray" padding={0} xstyle={styles.card}>+ <XDSVStack gap={6} align="center" xstyle={styles.cardContent}>+ <XDSVStack gap={6} align="center"><XDSHeading level={2} type="display-1" color="primary">Discover the full+ {/* Inline wordmark <img> baked into the heading as+ a visual word substitute. Raw <img> because no+ XDS Image primitive exists, and we need the+ image to inherit the heading's font-size+ cadence (sized in `em` via inlineWordmark+ xstyle) so it scales with the heading. */}<imgsrc="/astryx-logo.svg"alt="Astryx"@@ -201,7 +266,10 @@ export function DiscoverShowcase() {/>design system</XDSHeading>- <XDSText type="body" color="secondary" style={{maxWidth: 480}}>+ <XDSText+ type="body"+ color="secondary"+ xstyle={styles.supportingText}>Browse {CORE_COMPONENT_COUNT_ROUNDED}+ components, exploreproduction-ready templates, and tune themes to match your brand— pick a starting point and go.diff --git a/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx b/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsxindex ac0d6db42a..8ef3f63ba8 100644--- a/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx+++ b/apps/docsite/src/app/(site)/_landing/FeaturesShowcase.tsx@@ -4,10 +4,10 @@import * as stylex from '@stylexjs/stylex';import {XDSCard} from '@xds/core/Card';-import {XDSVStack} from '@xds/core/Layout';-import {XDSGrid} from '@xds/core/Grid';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSLink} from '@xds/core/Link';+import {spacingVars} from '@xds/core/theme/tokens.stylex';import {components} from '../../../generated/componentRegistry';// Count of public @xds/core components (excluding hooks and hidden entries).@@ -22,129 +22,282 @@ const CORE_COMPONENT_COUNT = (components['@xds/core'] ?? []).filter(const CORE_COMPONENT_COUNT_ROUNDED = Math.floor(CORE_COMPONENT_COUNT / 10) * 10;const styles = stylex.create({- headingBlock: {- textAlign: 'center',- width: '100%',- maxWidth: 680,- },- // 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.+ // Bento CSS-grid layout. Each grid cell holds a full-height+ // column wrapper (XDSVStack with height:100%) rather than a+ // single card, so the grid auto-stretches all three columns to+ // the tallest column's natural content height — which is what+ // gives us visually-balanced column heights even when one column+ // has one tall card and another has a tall card plus a short+ // card stacked.+ // 3-column desktop bento, 1-column mobile stack.+ //+ // <1024px: single column — every card stacks vertically.+ // ≥1024px: 3 fixed columns. Each column has a wrapper+ // (XDSVStack with column style) that holds 1-2+ // cards. Grid is align-items:stretch by default,+ // so each column wrapper takes the full row height+ // (set by min-height below). Cards inside with+ // flex:1 (isFlex / isTall) grow to fill column+ // leftover space.+ //+ // The column wrapper style (`column` below) uses display:+ // contents at mobile to dissolve the wrapper so cards become+ // direct children of the grid and the 1-col gridTemplateColumns+ // can lay them all out in source order.+ //+ // Literal pixel values are intentional marketing-section+ // dimensions, not derivable from the spacing scale:+ // • maxWidth 1200 — shared content cap across all three home+ // showcases (Features, About, Discover) so they line up.+ // • minHeight 720 — keeps the bento tall enough on desktop+ // that the dominant "Themes" card has room for its larger+ // image composition; below this height the right column+ // reads as cramped against the left/middle.gridLayout: {width: '100%',maxWidth: 1200,+ display: 'grid',+ gap: spacingVars['--spacing-8'],+ gridTemplateColumns: {+ default: '1fr',+ '@media (min-width: 1024px)': '1fr 1fr 1fr',+ },+ minHeight: {+ default: 0,+ '@media (min-width: 1024px)': 720,+ },},- // 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.+ // Column wrapper. At desktop it's a flex column (rendered as an+ // XDSVStack with gap={8} width="100%" height="100%") that takes+ // the full grid-cell height and stacks its 1-2 child cards. At+ // mobile (<1024) the xstyle below flips display to `contents`,+ // which dissolves the wrapper so its children become direct grid+ // children — combined with the parent's gridTemplateColumns:1fr+ // at mobile, every card gets its own row at full width.//- // overflow:hidden lets bleeding images (negative margin) clip- // cleanly at the rounded corners.+ // The display override is the ONLY thing in this xstyle because+ // XDSVStack already sets `display: flex` + `flex-direction:+ // column` + the gap; xstyle is applied last in XDSStack so the+ // mobile `display: contents` cleanly wins at narrow widths and+ // falls back to flex at desktop without re-declaring anything.+ column: {+ display: {+ default: 'contents',+ '@media (min-width: 1024px)': 'flex',+ },+ },+ // Heading cell — the top-left column starts with plain text on+ // the page background (no card wrapper) per the bento reference.+ // paddingBlockStart matches the cards' internal padding+ // (spacing-5 = 20px) so the heading baseline visually aligns+ // with the heading inside the top-center "Over 150 components"+ // card. NO inline padding: the reference shows the heading text+ // starting flush at the column's left edge (NOT inset to match+ // the cards' internal padding) — keeping the full column width+ // also gives the display heading enough room to break onto+ // natural lines without being clipped by a tighter inner width.+ headingCell: {+ paddingBlockStart: spacingVars['--spacing-5'],+ width: '100%',+ // On desktop the heading block sits in a side-by-side grid+ // with the cards, where flush-left reads as an editorial+ // section header. Under 1024px (single-column stack — same+ // breakpoint as the grid switch) the heading is standalone+ // above the cards and centering reads better — matches the+ // centering treatment used in the AboutShowcase mobile layout.+ alignItems: {+ default: 'center',+ '@media (min-width: 1024px)': 'flex-start',+ },+ textAlign: {+ default: 'center',+ '@media (min-width: 1024px)': 'start',+ },+ },+ // All cards use XDSCard padding={0} and apply their own padding+ // via the innerPadding* styles below. This is intentional: XDSCard's+ // `padding={N}` prop wires its `padding-bottom` through a+ // (0,5,0)-specificity selector (`.xds-card-XXX:not(#\#):not(#\#)+ // :not(#\#):not(#\#)`) which beats any xstyle override at (0,1,0).+ // The CSS variable indirection ALSO doesn't work because the card+ // sets `padding-bottom: var(--spacing-N)` directly (not via the+ // --container-padding-block-end var). So owning the padding via+ // the inner stack is the only reliable way to get 0 bottom padding+ // for image cards while leaving full padding on the text-only card.++ // All four card variants share the same pastel backdrop, pulled+ // from a marketing-only theme token (defined in astryxTheme.ts as+ // `--xds-marketing-feature-card-bg`). Sourcing the color from the+ // theme keeps the bento palette tunable in one place and avoids+ // baking literal hex values into the component. We do NOT use+ // XDSCard's `variant="blue"` here because that token (--color-+ // background-blue, 20%-alpha saturated wash) prints too vivid+ // against the white showcase surface — the marketing token is a+ // soft pastel band hand-tuned for this section.++ // Tall card variant — applied to the right-column "Themes" card.+ // flex:1 grows the card to fill its parent column wrapper, which+ // is stretched by the grid to match the tallest sibling column.cardTall: {- height: '100%',+ flex: 1,+ backgroundColor: 'var(--xds-marketing-feature-card-bg)',overflow: 'hidden',- gridRow: {- default: 'auto',- '@media (min-width: 720px)': 'span 2',- },},+ // Regular image card — natural (content) height. Used for an image+ // card that shares its column with a grow-to-fill (isFlex) sibling:+ // the flex sibling absorbs the column's leftover height while this+ // card stays at its content height. (Must NOT be height:100% — that+ // would make it eat the whole stretched column and collapse the+ // flex sibling.) overflow:hidden because the image is intended to+ // sit flush at the card's bottom edge but NOT bleed past it (the+ // image's bottom aligns with the card's bottom rounded corner).card: {- height: '100%',+ height: 'auto',overflow: 'hidden',+ backgroundColor: 'var(--xds-marketing-feature-card-bg)',},- // "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',+ // Flex variant of `card` — image card that grows to fill its+ // column's leftover height so a column with a short text-only+ // sibling can still match the height of an adjacent column with+ // only one tall card.+ cardFlex: {+ flex: 1,+ overflow: 'hidden',+ backgroundColor: 'var(--xds-marketing-feature-card-bg)',},- // 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,+ // Text-only feature card variant — no image, so overflow hidden+ // keeps the card contour tidy at the rounded corners.+ cardTextOnly: {+ height: 'auto',+ overflow: 'hidden',+ backgroundColor: 'var(--xds-marketing-feature-card-bg)',+ },+ // Padding for image cards: --spacing-10 (40px) on top + sides ++ // 0 on bottom so the image wrapper inside sits flush at the+ // card's bottom edge.+ innerPaddingImage: {+ paddingBlockStart: spacingVars['--spacing-10'],+ paddingInlineStart: spacingVars['--spacing-10'],+ paddingInlineEnd: spacingVars['--spacing-10'],+ paddingBlockEnd: 0,},- // 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%',+ // Padding for an image card whose image stays *inset* (framed) rather+ // than full-bleed — --spacing-10 (40px) on all four sides, including+ // the bottom, so the image keeps left/right/bottom breathing room+ // inside the card instead of touching the edges.+ innerPaddingImageInset: {+ padding: spacingVars['--spacing-10'],+ },+ // Padding for the text-only card: --spacing-10 (40px) on all+ // sides (matches the image cards' top + sides; only difference+ // is the bottom padding which the image cards drop to 0 for+ // their image bleed).+ innerPaddingText: {+ padding: spacingVars['--spacing-10'],},// 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))',+ marginTop: spacingVars['--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.+ // Image wrapper for the 3 feature cards with images. The image is+ // full-bleed: it spans the entire card width and touches the card's+ // left, right, and bottom edges (only the text above keeps the+ // innerPaddingImage inset). To do that, the wrapper cancels the+ // inner stack's 40px inline padding with negative inline margins so+ // it reaches the card edges, even though its parent stack is inset.+ //+ // marginTop:auto pushes the wrapper to the bottom of the card's+ // content stack so the image always sits at the bottom regardless+ // of how much text wraps above.+ //+ // paddingTop creates breathing room between the "Explore" link+ // and the image.+ //+ // overflow:hidden keeps the image contained inside the wrapper+ // (and therefore inside the card, since the card itself uses+ // overflow:hidden too) so the bottom corners stay rounded.imageWrap: {marginTop: 'auto',- paddingTop: 16,- marginBottom: 'calc(var(--spacing-5) * -1 + 16px)',- alignSelf: 'stretch',+ // 40px gap between the text above and the image (matches the tall+ // and inset variants so every card has the same text↔image gap).+ paddingTop: spacingVars['--spacing-10'],+ // Break out of the inner stack's 40px inline padding so the image+ // bleeds to the card's left/right edges. Negative inline margins+ // pull the wrapper past the padding; the width is grown by the same+ // 2×40px so the wrapper's content box actually spans the full card+ // width (a plain width:100% would stay sized to the inset parent).+ marginInline: `calc(-1 * ${spacingVars['--spacing-10']})`,+ width: `calc(100% + 2 * ${spacingVars['--spacing-10']})`,+ minWidth: 0,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.+ // Tall-card image wrapper variant. Same full-bleed treatment; more+ // top padding because the tall card has more vertical room above+ // the image baseline that we want to leave visually open.imageWrapTall: {- marginInlineStart: 'calc(var(--spacing-5) * -1 + 16px)',- marginInlineEnd: 'calc(var(--spacing-5) * -1)',marginTop: 'auto',- marginBottom: 'auto',+ paddingTop: spacingVars['--spacing-10'],+ marginInline: `calc(-1 * ${spacingVars['--spacing-10']})`,+ width: `calc(100% + 2 * ${spacingVars['--spacing-10']})`,+ minWidth: 0,+ overflow: 'hidden',},- // 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)',+ // Vertically-centered full-bleed image wrapper. Same edge-to-edge+ // horizontal bleed as imageWrap, but the image floats in the middle+ // of the card's leftover vertical space instead of being pinned to+ // the bottom: marginBlock:auto puts equal auto-margin above and+ // below. Used by the Themes card so its composition sits centered+ // rather than bottom-anchored with a tall empty gap above.+ imageWrapCentered: {+ marginBlock: 'auto',+ // Keep at least a 40px gap above the image even when centered, so+ // the text↔image spacing matches the other cards.+ paddingTop: spacingVars['--spacing-10'],+ marginInline: `calc(-1 * ${spacingVars['--spacing-10']})`,+ width: `calc(100% + 2 * ${spacingVars['--spacing-10']})`,+ minWidth: 0,+ overflow: 'hidden',+ },+ // Inset (framed) image wrapper — keeps the image within the card's+ // inner padding instead of bleeding to the edges. No negative inline+ // margins and no width expansion, so the wrapper stays inside the+ // 40px inset and the image has left/right/bottom breathing room (the+ // inner stack supplies the bottom padding via innerPaddingImageInset).+ // paddingTop is --spacing-10 (40px) so the gap above the image+ // matches the 40px frame on the other three sides.+ imageWrapInset: {+ marginTop: 'auto',+ paddingTop: spacingVars['--spacing-10'],+ alignSelf: 'stretch',+ minWidth: 0,+ maxWidth: '100%',+ overflow: 'hidden',},- // 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)',+ // Default image: full-bleed to the card width (no max-width cap) so+ // it spans edge-to-edge. height:auto preserves natural aspect ratio.+ // display:block kills the inline baseline gap so there's no mystery+ // whitespace under the image.+ featureImage: {+ width: '100%',+ height: 'auto',+ display: 'block',},- // 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)',+ // Reduced-size image — 3/4 of the wrapper width. Combined with a+ // center-aligned wrapper (hAlign="center") this leaves equal margin+ // on both sides so the composition reads as a smaller, centered+ // element rather than spanning the full card. Used by the Components+ // and CLI cards.+ featureImageSmall: {+ width: '75%',+ height: 'auto',+ display: 'block',},- // Image: full container width, natural aspect-ratio-derived- // height. No maxHeight cap — each composition was sized at design- // time to render correctly inside its card variant (the tall- // card's composition is intentionally taller than the regular- // cards' wide-and-short compositions). A blanket maxHeight cap- // shrinks the tall + bleed images to a tiny strip in the corner- // because object-fit:contain inside the cap can't enlarge a- // smaller image — the wrappers (imageWrap + variants) already- // handle the positioning + bleed at the card edges.- tallImage: {+ // Tall-card image: same full-bleed treatment. Still height:auto so+ // the natural aspect ratio is preserved.+ featureImageTall: {width: '100%',height: 'auto',display: 'block',@@ -156,98 +309,143 @@ type Feature = {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.).+ * Optional supporting image rendered below the description. When+ * present, the image is centered horizontally and bleeds past+ * the card's bottom edge per the bento layout reference. When+ * omitted, the card renders as text-only.*/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[] = [- {- title: 'Measured and tested',- 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',- },- },- {+// Looked up by slot key in the JSX below so each card's position in+// the bento grid is self-documenting. Keyed strings instead of an+// ordered array because the visual order in the grid is not the+// same as any obvious data order — explicit slot mapping is clearer+// than counting indices.+const features: Record<string, Feature> = {+ components: {title: `Over ${CORE_COMPONENT_COUNT_ROUNDED} components`,description:- 'Accessible and themeable React components with built-in spacing, dark mode, and StyleX styling.',+ 'Accessible and themeable React components with built-in spacing, dark mode, and flexible styling.',href: '/components',image: {src: '/feature-components.png',- alt: 'Sample XDS components — Badge, Switch, Secondary button, Primary button, Search input',+ alt: 'Sample XDS components — Badges, radio, checkbox, switch, Secondary and Primary buttons, and a search input',},},- {- title: 'Your design system on the command line',+ themes: {+ 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-cli.png',- alt: 'AI prompt input asking "Can you create me a table page" with a send button',+ src: '/feature-brand.png',+ alt: 'A product landing page styled with the Butter theme, shown alongside the theme\u2019s color swatches and type sample',},},- {+ templates: {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,+ alt: 'A scattered collage of ready-to-use page templates — product gallery, code editor, checkout summary, login, product detail, and AI chat',},},- {- title: 'Themes that fit your brand',+ cli: {+ title: 'A design system that your agent can use',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 or MCP.',+ href: '/docs/cli',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,+ src: '/feature-cli.png',+ alt: 'AI prompt input asking "Can you create me a table page" with a send button',},},-];+};++function FeatureCard({+ feature,+ isTall = false,+ isFlex = false,+ insetImage = false,+ centerImage = false,+ smallImage = false,+}: {+ feature: Feature;+ /**+ * Renders the card with the tall-variant image treatment (larger+ * image cap + more top padding above the image). Used by the+ * right-column "Themes" card which is the only card with a wider+ * vertical canvas for its composition.+ */+ isTall?: boolean;+ /**+ * When true, the card uses flex:1 so it grows to fill any leftover+ * vertical space inside its parent column. Used for the image+ * cards that need to balance against a short text-only sibling in+ * an adjacent column. Has no effect for the tall card (cardTall+ * already includes flex:1) or the text-only card (which is+ * intentionally shrink-to-content).+ */+ isFlex?: boolean;+ /**+ * When true, the image stays inset (framed) with left/right/bottom+ * padding instead of bleeding to the card edges. Used for the+ * "Over 150 components" card whose sample reads better framed than+ * full-bleed. Ignored for the tall card (which always full-bleeds).+ */+ insetImage?: boolean;+ /**+ * When true, the full-bleed image is centered in the card's leftover+ * vertical space instead of pinned to the bottom. Used for the Themes+ * card so its composition floats centered rather than bottom-anchored+ * with a tall empty gap above. Ignored for tall / inset images.+ */+ centerImage?: boolean;+ /**+ * When true, the image renders at 2/3 width and is horizontally+ * centered in its wrapper (equal margin on both sides). Used by the+ * Components and CLI cards so their smaller compositions don't span+ * the full card width.+ */+ smallImage?: boolean;+}) {+ const hasImage = feature.image != null;+ // Style precedence:+ // 1. isTall → cardTall (right-column dominant card)+ // 2. isFlex → cardFlex (grow-to-fill image card)+ // 3. hasImage → card (natural-height image card)+ // 4. else → cardTextOnly (shrink-to-content text-only card)+ // Only one of these applies at a time.+ const cardStyle = isTall+ ? styles.cardTall+ : isFlex+ ? styles.cardFlex+ : hasImage+ ? styles.card+ : styles.cardTextOnly;-function FeatureCard({feature, isTall}: {feature: Feature; isTall?: boolean}) {- const showImage = feature.image != null;return (- <XDSCard- variant="gray"- padding={5}- xstyle={isTall ? styles.cardTall : styles.card}>+ // variant="transparent" suppresses XDSCard's default border + bg+ // so the marketing token painted by `cardStyle` below is the+ // sole surface color (no blend with --color-background-card).+ <XDSCard variant="transparent" padding={0} xstyle={cardStyle}><XDSVStackgap={1}align="start"- xstyle={showImage ? styles.tallStack : undefined}>+ height="100%"+ xstyle={+ hasImage+ ? insetImage+ ? styles.innerPaddingImageInset+ : styles.innerPaddingImage+ : styles.innerPaddingText+ }><XDSHeading level={2} color="primary">{feature.title}</XDSHeading>@@ -262,40 +460,66 @@ function FeatureCard({feature, isTall}: {feature: Feature; isTall?: boolean}) {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,- )}>+ {hasImage && feature.image && (+ // XDSHStack handles the flex+direction+alignment chrome;+ // marginTop/padding/overflow/sizing live in the xstyle.+ // No width prop: the wrapper's width is set in the xstyle to+ // calc(100% + 2×40px) so it can exceed the inset parent and+ // bleed the image to the card edges (a width="100%" prop here+ // would win over the xstyle and clamp it back to the inset).+ <XDSHStack+ hAlign={isTall || smallImage ? 'center' : 'start'}+ xstyle={+ isTall+ ? styles.imageWrapTall+ : insetImage+ ? styles.imageWrapInset+ : centerImage+ ? styles.imageWrapCentered+ : styles.imageWrap+ }>+ {/* Decorative image — kept as a raw <img> because @xds/core+ does not export a dedicated Image primitive (XDSThumbnail+ is a chat/attachment chrome, not a fit-to-container+ marketing image). Sizing + display:block come from the+ featureImage / featureImageTall / featureImageSmall+ xstyles below. */}<imgsrc={feature.image.src}alt={feature.image.alt}- {...stylex.props(styles.tallImage)}+ {...stylex.props(+ isTall+ ? styles.featureImageTall+ : smallImage+ ? styles.featureImageSmall+ : styles.featureImage,+ )}/>- </div>+ </XDSHStack>)}</XDSVStack></XDSCard>);}-function FeaturesHeading() {+// Plain heading block — sits in the top-left grid slot on the page+// background (no card wrapper) per the bento reference. The text is+// flush-left to the grid column edge (no inline padding) so the+// display heading has the full column width to break onto natural+// lines. The block's paddingBlockStart matches the cards' internal+// top padding so the heading and the adjacent card titles sit on+// roughly the same vertical baseline at the top of the row.+function HeadingBlock() {return (- <XDSVStack gap={4} align="center" xstyle={styles.headingBlock}>- <XDSHeading level={4} color="primary" xstyle={styles.eyebrow}>- Key features- </XDSHeading>+ <XDSVStack gap={4} xstyle={styles.headingCell}><XDSHeading level={2} type="display-2" color="primary">- Start anywhere. Change anything. Ship faster.+ Start anywhere.+ <br />+ Change anything.+ <br />+ Ship faster.</XDSHeading>- <XDSText- display="block"- type="body"- color="secondary"- xstyle={styles.descriptionWidth}>+ <XDSText display="block" type="large" weight="normal" color="secondary">A design system that adapts to your workflow, not the other way around.Built for speed, clarity, and creative freedom.</XDSText>@@ -304,17 +528,56 @@ function FeaturesHeading() {}export function FeaturesShowcase() {+ // Each grid cell holds a full-height column wrapper (XDSVStack+ // height:100%) rather than a single card, so the grid stretches+ // all three columns to the height of the tallest column. Cards+ // marked isFlex / isTall use flex:1 to grow into any leftover+ // vertical space inside their column, which is what visually+ // balances the column heights: the "Over 150 components" card in+ // the middle column grows to fill the space its "CLI" sibling+ // leaves behind, matching the heights of the dedicated+ // "Themes" card on the left and the "Templates" card on the+ // right.+ //+ // Layout on desktop (≥720px):+ // col 1: HeadingBlock + Themes (flex)+ // col 2: Components (flex) + CLI (image, natural height)+ // col 3: Templates (tall, flex)+ //+ // Below 720px the grid collapses to 1 column. Each column wrapper+ // renders top-to-bottom in DOM order, so the cards stack as:+ // heading → themes → components → CLI → templates.return (<XDSVStack as="section" align="center" gap={10} width="100%">- <FeaturesHeading />- <XDSGrid- columns={{minWidth: 320, repeat: 'fit'}}- gap={4}- xstyle={styles.gridLayout}>- {features.map((feature, i) => (- <FeatureCard key={feature.title} feature={feature} isTall={i === 0} />- ))}- </XDSGrid>+ {/* CSS-grid container with responsive column count. Kept as a+ plain <div> (rather than XDSGrid) because we depend on grid's+ align-items:stretch + min-height behavior to drive equal+ column heights, and we need to control gap/minHeight via+ @media at the wrapper level. XDSGrid is optimized for fixed+ column counts + a single gap and doesn't expose the+ minHeight responsive variant pattern we need here. */}+ <div {...stylex.props(styles.gridLayout)}>+ {/* Column wrappers use XDSVStack at desktop and dissolve via+ `display: contents` at mobile (see styles.column comment).+ XDSVStack handles flex+direction+gap+sizing; the xstyle+ owns only the responsive display switch. */}+ <XDSVStack gap={8} width="100%" height="100%" xstyle={styles.column}>+ <HeadingBlock />+ <FeatureCard feature={features.themes} isFlex centerImage />+ </XDSVStack>+ <XDSVStack gap={8} width="100%" height="100%" xstyle={styles.column}>+ <FeatureCard+ feature={features.components}+ isFlex+ insetImage+ smallImage+ />+ <FeatureCard feature={features.cli} smallImage />+ </XDSVStack>+ <XDSVStack gap={8} width="100%" height="100%" xstyle={styles.column}>+ <FeatureCard feature={features.templates} isTall />+ </XDSVStack>+ </div></XDSVStack>);}diff --git a/apps/docsite/src/app/(site)/page.tsx b/apps/docsite/src/app/(site)/page.tsxindex 711be2305f..13832c834d 100644--- a/apps/docsite/src/app/(site)/page.tsx+++ b/apps/docsite/src/app/(site)/page.tsx@@ -11,7 +11,6 @@ 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';-import {ThemingShowcase} from './_landing/ThemingShowcase';import {FeaturesShowcase} from './_landing/FeaturesShowcase';import {AboutShowcase} from './_landing/AboutShowcase';import {DiscoverShowcase} from './_landing/DiscoverShowcase';@@ -26,6 +25,13 @@ const styles = stylex.create({position: 'relative',backgroundColor: 'var(--color-background-body)',},+ // Hero content column. maxWidth: 800 is an editorial reading-+ // measure cap (≈ display-1 + body at a comfortable line length);+ // not derivable from the spacing scale, kept as a literal+ // because it's a marketing-section measure, not a system primitive.+ // paddingBlock = --spacing-12 * 3 → 144px top/bottom; expressed+ // as a calc() over the spacing token so the rhythm scales with+ // any future spacing-scale theme override.heroContent: {position: 'sticky',top: 'var(--appshell-header-height, 0px)',@@ -34,7 +40,11 @@ const styles = stylex.create({paddingBlock: `calc(${spacingVars['--spacing-12']} * 3)`,paddingInline: spacingVars['--spacing-6'],textAlign: 'center',- gap: spacingVars['--spacing-12'],+ gap: spacingVars['--spacing-6'],+ // Lock the hero block to a fixed minimum height so the showcase+ // below has a stable starting offset across viewports and the+ // sticky pin-and-cover reveal reads consistently.+ minHeight: 600,},// Wrapper around the wordmark + floating Beta badge. Sized// exactly to the wordmark image (display:inline-block with no@@ -50,8 +60,16 @@ const styles = stylex.create({},heroWordmark: {display: 'block',- height: 42,+ // Responsive: scale down on narrow viewports so the wordmark+ // doesn't overflow the hero column. 80px at desktop is the+ // designed size; 56px keeps the wordmark visible without+ // clipping on phones at ~375px viewport.+ height: {+ default: 80,+ '@media (max-width: 480px)': 56,+ },width: 'auto',+ maxWidth: '100%',},// Floating Beta badge wrapper — positions the XDSBadge above// the wordmark (bottom anchored to the wordmark's top edge)@@ -59,27 +77,58 @@ const styles = stylex.create({// brand mark without overlapping any of the glyphs. The XDS// Badge component carries the pill chrome (background, radius,// typography); only positioning + rotation lives here.+ //+ // right: -24 is a literal pixel offset (not a spacing token)+ // because the badge anchor is tied to the wordmark glyph+ // geometry — the badge needs to clear the rightmost ligature+ // by a precise visual margin that doesn't correspond to any+ // spacing-scale step. Negative spacing tokens don't exist in+ // the scale anyway, so even the symmetric "24px" would be a+ // literal here.heroWordmarkBeta: {position: 'absolute',bottom: '100%',right: -24,- marginBottom: 4,+ marginBottom: spacingVars['--spacing-1'],transform: 'rotate(8deg)',transformOrigin: 'bottom right',},+ // Hero CTA button grid. maxWidth: 420 caps the two-up button+ // row at a comfortable thumb-reachable width so the buttons+ // don't stretch edge-to-edge on wide hero columns; literal+ // because the cap is a button-pair ergonomics value, not a+ // spacing-scale step.heroButtons: {width: '100%',maxWidth: 420,},+ // Lighter display weight for the leading half of the hero+ // headline ("An open source design system that's"). Astryx's+ // theme override pushes display-1 to semibold (600); we want+ // the leading copy to read as a softer editorial setup so the+ // value-prop tail ("fully customizable and agent ready") can+ // land harder. Applied per-span via xstyle, not as a theme+ // token change, so the rest of the site keeps Astryx's display+ // semibold default.+ heroHeadline: {+ fontWeight: 'var(--font-weight-normal)',+ },+ // The showcase overlay paints the surface that scrolls UP over+ // the pinned hero (pin-and-cover reveal). Surface color ++ // top-rounded corners + body padding all sit on tokens, but+ // paddingBlockStart and gap use the marketing-section rhythm+ // token (--xds-marketing-section-gap) — these are marketing-+ // section rhythm, NOT primitives in the spacing scale.showcaseOverlay: {position: 'relative',overflow: 'hidden',borderTopLeftRadius: 'var(--radius-page)',borderTopRightRadius: 'var(--radius-page)',backgroundColor: 'var(--color-background-surface)',- paddingBlock: spacingVars['--spacing-12'],+ paddingBlockStart: 'var(--xds-marketing-section-gap)',+ paddingBlockEnd: spacingVars['--spacing-12'],paddingInline: spacingVars['--spacing-6'],- gap: `calc(${spacingVars['--spacing-12']} * 2)`,+ gap: 'var(--xds-marketing-section-gap)',},});@@ -130,18 +179,48 @@ export default function HomePage() {data-home-page="true"align="stretch"xstyle={styles.heroContent}>+ {/* heroWordmarkWrap is a raw <div> because its sole job is+ to establish a `position: relative` context for the+ absolutely-positioned Beta badge while sizing exactly to+ the inline wordmark image's natural width. XDSVStack /+ XDSHStack would impose flex semantics that fight the+ inline-block sizing; no other XDS primitive represents+ "positioning context that hugs an inline child". */}<div {...stylex.props(styles.heroWordmarkWrap)}>+ {/* Raw <img> — @xds/core does not export a general-purpose+ image component (XDSThumbnail is chat-attachment chrome;+ XDSIcon is a glyph registry). Sizing + responsive+ breakpoints come from the heroWordmark xstyle. */}<imgsrc="/astryx-logo.svg"alt="Astryx"{...stylex.props(styles.heroWordmark)}/>+ {/* heroWordmarkBeta is a raw <span> because we need an+ inline-level element that establishes its own+ position:absolute context for the XDSBadge — a stack+ would force flex children and break the floating+ callout placement. */}<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+ level={1}+ type="display-1"+ color="primary"+ xstyle={styles.heroHeadline}>+ An open source design system that's{' '}+ {/* XDSText emphasis span — type/color="inherit" picks up+ the heading's display-1 size + color so only the+ weight changes, and weight="semibold" provides the+ contrast against the parent heading's normal weight+ (set via styles.heroHeadline above). Using XDSText+ keeps the inline emphasis on a typed XDS primitive+ instead of a raw <span> + xstyle escape. */}+ <XDSText as="span" type="inherit" color="inherit" weight="semibold">+ fully customizable and agent ready+ </XDSText></XDSHeading><XDSVStack gap={4} align="center"><XDSGrid columns={2} gap={3} xstyle={styles.heroButtons}>@@ -168,12 +247,21 @@ export default function HomePage() {rel="noopener noreferrer"hasUnderline>React+ </XDSLink>{' '}+ and{' '}+ <XDSLink+ type="body"+ color="primary"+ href="https://stylexjs.com"+ target="_blank"+ rel="noopener noreferrer"+ hasUnderline>+ StyleX</XDSLink></XDSText></XDSVStack></XDSVStack><XDSVStack ref={showcaseRef} xstyle={styles.showcaseOverlay}>- <ThemingShowcase /><FeaturesShowcase /><AboutShowcase /><DiscoverShowcase />diff --git a/apps/docsite/src/app/globals.css b/apps/docsite/src/app/globals.cssindex 3c69d5ac5f..13849acdfd 100644--- a/apps/docsite/src/app/globals.css+++ b/apps/docsite/src/app/globals.css@@ -12,6 +12,31 @@reset, xds-base, xds-theme so product styles always win. */@stylex;+/* Marketing-only custom properties for the docsite home page. These are+ NOT XDS theming tokens — they're docsite-specific values that back the+ landing page's bento feature cards + section rhythm — so they live here+ in globals.css rather than in the Astryx theme (which should only+ override real XDS semantic tokens). Each is a light-dark() pair so dark+ mode is handled by the value itself, no consumer logic required. */+:root {+ /* Feature card backdrop. Soft pastel blue in light mode, deep navy in+ dark mode. Consumed by FeaturesShowcase's bento cards via+ `backgroundColor: var(--xds-marketing-feature-card-bg)`. Picked+ specifically because the stock --color-background-blue is a+ 20%-alpha saturated wash that prints too vivid against the showcase's+ white surface; this gives the cards a soft pastel band the eye reads+ as a single related group. */+ --xds-marketing-feature-card-bg: light-dark(#e6f0ff, #1a2333);++ /* Marketing-section vertical rhythm. The XDS spacing scale tops out at+ --spacing-12 = 48px, which is fine for in-app density but too tight+ for a landing-page section break. Used for the gap between major+ home-page sections (hero ↔ features ↔ about ↔ discover) and the+ page's first paddingBlockStart so the rhythm reads as deliberate+ marketing pacing rather than a maxed-out spacing step. */+ --xds-marketing-section-gap: 100px;+}+/* AppShell sets a sticky top nav but its main content area sits at the sametop edge — so the first child of any page can end up covered by the nav.On every (docs)-group page (anything with a sticky AppShell header),