@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/assets/docs/working-with-ai.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'guide',
   description:
     'How to set up AI coding tools to generate correct component code.',
+  keywords: ['claude', 'cursor', 'codex', 'copilot', 'agents', 'mcp'],
 
   sections: [
     {
@@ -24,7 +25,8 @@ export const docs = {
       ],
     },
     {
-      title: 'Quick Start',
+      id: 'quick-start',
+      title: 'Set up agent docs',
       content: [
         {
           type: 'prose',
@@ -38,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade` reports a stale block and `astryx upgrade --apply` refreshes it.",
+          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade --from <old version>` reports a stale block and adding `--apply` refreshes it.",
         },
         {
           type: 'prose',
@@ -48,10 +50,12 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx @astryxdesign/cli init --features agents --agent claude    # .claude/CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
+          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
 npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
-npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)`,
+npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
+npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
+npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
         },
       ],
     },
@@ -66,14 +70,14 @@ npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse
           type: 'list',
           style: 'ordered',
           items: [
-            '`astryx template --list`: find a related page pattern to use as reference',
-            '`astryx template <name> --skeleton`: study the layout structure',
+            '`astryx build "<idea>"`: get the page template to start from (always one: the closest match, or the app shell), two other templates, and the blocks and components for the parts it lacks',
+            '`astryx template <name> <path>`: scaffold that template into the project, keep its frame and spacing, and replace its content',
             '`astryx component <Name>`: read props and examples for every component used',
           ],
         },
         {
           type: 'prose',
-          text: "It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values), a CLI quick reference, and package-labeled integration guidance when a configured manifest declares `agentDocs`. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.",
+          text: "It also includes rules that prevent common mistakes (start every page from a template, no raw divs, no style={{}}, use tokens not magic values), a CLI quick reference, and package-labeled integration guidance when a configured manifest declares `agentDocs`. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.",
         },
       ],
     },
@@ -82,14 +86,17 @@ npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse
       content: [
         {
           type: 'prose',
-          text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+          text: 'Cursor reads project rules from `.cursor/rules/`. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as `.cursor/rules/astryx.mdc`; an absolute path is refused.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install as a Cursor user rule',
-          code: `mkdir -p ~/.cursor/rules
-npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+          label: 'Install as a Cursor project rule',
+          code: `npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
+        },
+        {
+          type: 'prose',
+          text: 'Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as `alwaysApply: true`) stays.',
         },
       ],
     },
@@ -98,7 +105,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
       content: [
         {
           type: 'prose',
-          text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+          text: 'Paste this into your AI before writing any component code. If your AI can\'t answer these questions, it\'ll know to install the agent docs first.',
         },
         {
           type: 'code',
@@ -107,7 +114,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
           code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
-2. How do you make an Dialog non-dismissible?
+2. How do you make a Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
 If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
@@ -131,33 +138,34 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
         },
         {
           type: 'prose',
-          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents run `npm run astryx -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `astryx component --list
-astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          code: `npm run astryx -- component --list
+npm run astryx -- component Dialog --dense
+npm run astryx -- docs styling --full --detail brief
+npm run astryx -- docs tokens --dense`,
         },
       ],
     },
     {
-      title: 'The --dense Flag',
+      id: 'the-dense-flag',
+      title: 'Shorter output: --detail and --dense',
       content: [
         {
           type: 'prose',
-          text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+          text: 'For a shorter read, add `--detail brief` (one line per section) or `--detail compact`. `--dense` swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Dense output for pasting into AI conversations',
-          code: `astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          label: 'Short output for pasting into AI conversations',
+          code: `astryx docs styling --full --detail brief
+astryx component Dialog --detail compact
+astryx docs principles --dense`,
         },
       ],
     },
@@ -182,7 +190,7 @@ astryx docs tokens --dense`,
           label: 'MCP config (same for all tools)',
           code: `{
   "mcpServers": {
-    "xds": {
+    "astryx": {
       "type": "url",
       "url": "https://astryx.atmeta.com/mcp"
     }

package/assets/templates/blocks/components/CheckboxList/CheckboxListSelectAllPattern.doc.mjs

@@ -10,5 +10,5 @@ export const doc = {
     'A "select all" toggle at the top of a checkbox list that switches to an indeterminate dash when only some items are checked, useful for bulk actions like exporting documents or assigning permissions where users often want everything at once.',
   isReady: true,
   aspectRatio: 16 / 9,
-  componentsUsed: ['CheckboxList', 'Divider'],
+  componentsUsed: ['CheckboxList'],
 };

package/assets/templates/blocks/components/CheckboxList/CheckboxListSelectAllPattern.tsx

@@ -4,7 +4,6 @@
 
 import {useState} from 'react';
 import {CheckboxList, CheckboxListItem} from '@astryxdesign/core/CheckboxList';
-import {Divider} from '@astryxdesign/core/Divider';
 
 const DOCUMENTS = [
   {id: 'transactions', label: 'Transaction history'},
@@ -27,7 +26,7 @@ export default function CheckboxListSelectAllPattern() {
       : ('indeterminate' as const);
 
   return (
-    <CheckboxList label="Include in export">
+    <CheckboxList label="Include in export" hasDividers>
       <CheckboxListItem
         label="Select all"
         isChecked={selectAllState}
@@ -35,7 +34,6 @@ export default function CheckboxListSelectAllPattern() {
           setSelected(checked ? [...ALL_IDS] : []);
         }}
       />
-      <Divider />
       {DOCUMENTS.map(doc => (
         <CheckboxListItem
           key={doc.id}

package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx

@@ -41,7 +41,7 @@ export default function DateInputDateRange() {
         max={max}
         description={description}
         placeholder="Select a booking date"
-        nativePicker="never"
+        presentation="adaptive-bottom-sheet"
         value={value}
         onChange={setValue}
       />

package/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx

@@ -4,7 +4,7 @@
 
 import {useState} from 'react';
 import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import frFR from '@astryxdesign/core/locales/fr-FR.json';
+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
 import {Stack} from '@astryxdesign/core/Layout';
 import {
   SegmentedControl,

package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Item',
+  name: 'Item — Document Tabs',
+  displayName: 'Item — Document Tabs',
+  description:
+    'Single-row, horizontally scrollable document switcher with compact selected rows, leading file icons, instant reveal-on-hover close actions with reserved geometry, stable separators, and an add control outside the scroll area. Use for editor tabs, workspace tabs, open documents, files, canvases, or panels.',
+  isReady: true,
+  aspectRatio: 16 / 4,
+  componentsUsed: ['Item', 'Divider', 'Icon', 'IconButton', 'Layout'],
+};

package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Fragment} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {Divider} from '@astryxdesign/core/Divider';
+import {useContainerReveal} from '@astryxdesign/core/hooks';
+import {Icon} from '@astryxdesign/core/Icon';
+import {IconButton} from '@astryxdesign/core/IconButton';
+import {Item} from '@astryxdesign/core/Item';
+import {HStack} from '@astryxdesign/core/Layout';
+import {mergeProps} from '@astryxdesign/core/utils';
+import {DocumentIcon, PlusIcon, XMarkIcon} from '@heroicons/react/24/outline';
+
+const TABS = [
+  {name: 'Project brief', isActive: true},
+  {name: 'Research notes', isActive: false},
+  {name: 'Interaction prototype', isActive: false},
+];
+
+const styles = stylex.create({
+  strip: {minWidth: 0, flexShrink: 1, scrollbarWidth: 'none'},
+  rule: {height: 16},
+  hidden: {visibility: 'hidden'},
+  tab: {flexShrink: 1, width: 164, minWidth: 96},
+  action: {margin: 'calc(-1 * var(--spacing-1))', transitionProperty: 'none'},
+});
+function DocumentTab({name, isActive}: (typeof TABS)[number]) {
+  const {getContainerProps, getContentRevealProps} = useContainerReveal();
+  const revealProps = getContentRevealProps({
+    forceVisibility: isActive ? 'shown' : undefined,
+    isLayoutPreserved: true,
+  });
+  return (
+    <Item
+      label={name}
+      density="compact"
+      isSelected={isActive}
+      onClick={() => {}}
+      aria-current={isActive ? 'true' : undefined}
+      {...getContainerProps()}
+      startContent={
+        <Icon
+          icon={DocumentIcon}
+          size="sm"
+          color={isActive ? 'primary' : 'secondary'}
+        />
+      }
+      endContent={
+        <IconButton
+          label={`Close ${name}`}
+          variant="ghost"
+          size="sm"
+          icon={<Icon icon={XMarkIcon} size="sm" />}
+          {...mergeProps(revealProps, stylex.props(styles.action))}
+        />
+      }
+      xstyle={styles.tab}
+    />
+  );
+}
+
+export default function ItemDocumentTabs() {
+  return (
+    <HStack width="100%" maxWidth={600} gap={0.5} vAlign="center">
+      <HStack
+        role="group"
+        aria-label="Open documents"
+        vAlign="center"
+        paddingInline={2}
+        paddingBlock={1}
+        isScrollable
+        xstyle={styles.strip}>
+        {TABS.map((tab, index) => (
+          <Fragment key={tab.name}>
+            {index > 0 ? (
+              <Divider
+                orientation="vertical"
+                xstyle={[
+                  styles.rule,
+                  (TABS[index - 1]?.isActive || tab.isActive) && styles.hidden,
+                ]}
+              />
+            ) : null}
+            <DocumentTab {...tab} />
+          </Fragment>
+        ))}
+      </HStack>
+      <IconButton
+        label="New document"
+        tooltip="New document"
+        variant="ghost"
+        size="sm"
+        icon={<Icon icon={PlusIcon} size="sm" color="secondary" />}
+      />
+    </HStack>
+  );
+}

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ScrollableArea',
+  name: 'ScrollableArea — Inline Rail',
+  displayName: 'Scrollable Area — Inline Rail',
+  description:
+    'axis="inline" scrolls the same cards sideways; isFullBleed lets the rail run to the panel edges while the content padding keeps the first card aligned with the heading.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['ScrollableArea', 'Card', 'Link'],
+};

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {Link} from '@astryxdesign/core/Link';
+
+const FILES = [
+  {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+  {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+  {id: 'onboarding', title: 'Onboarding flow v4', meta: 'Edited 4 days ago'},
+  {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+  {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+  {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+  {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+];
+
+export default function ScrollableAreaInlineRail() {
+  return (
+    <Card width={460} padding={4}>
+      <VStack gap={3}>
+        <HStack hAlign="between" vAlign="center">
+          <VStack gap={0.5}>
+            <Heading level={3}>Workspace files</Heading>
+            <Text type="supporting">Recently opened</Text>
+          </VStack>
+          <Link href="#files">View all</Link>
+        </HStack>
+        {/* isFullBleed lets the rail reach the card's edges, while the content
+            padding keeps the first card aligned with the heading above it and
+            leaves room under the cards for the scrollbar. */}
+        <ScrollableArea
+          axis="inline"
+          role="region"
+          label="Recently opened files"
+          isFullBleed
+          paddingInline={4}
+          paddingBlockStart={0.5}
+          paddingBlockEnd={4}>
+          <HStack gap={2}>
+            {FILES.map(file => (
+              <Card key={file.id} variant="muted" padding={3} width={170}>
+                <VStack gap={1}>
+                  <Text weight="medium" maxLines={1}>
+                    {file.title}
+                  </Text>
+                  <Text type="supporting" maxLines={1}>
+                    {file.meta}
+                  </Text>
+                </VStack>
+              </Card>
+            ))}
+          </HStack>
+        </ScrollableArea>
+      </VStack>
+    </Card>
+  );
+}

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ScrollableArea',
+  name: 'ScrollableArea — Overscroll',
+  displayName: 'Scrollable Area — Overscroll',
+  description:
+    'The same section, two edge policies: the default overscroll="allow" hands a gesture that reaches the end to the panel behind it, while overscroll="contain" stops it at the section edge.',
+  isReady: true,
+  aspectRatio: 1,
+  componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+  borderVars,
+  colorVars,
+  radiusVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+  // A hairline frame so the nested viewport's edge — the edge the gesture
+  // meets — is visible.
+  sectionFrame: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: radiusVars['--radius-element'],
+  },
+});
+
+const SHARED = [
+  {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+  {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+  {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+  {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+  {id: 'tax', title: 'Tax region notes', meta: 'Hugo Bernard'},
+  {id: 'sso', title: 'SSO rollout plan', meta: 'Sofia Marchetti'},
+];
+
+const ARCHIVED = [
+  {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+  {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+  {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+  {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+  {id: 'survey', title: 'Q4 survey results', meta: 'Archived in January'},
+  {id: 'offsite', title: 'Offsite agenda', meta: 'Archived last year'},
+];
+
+function FileGrid({
+  files,
+}: {
+  files: Array<{id: string; title: string; meta: string}>;
+}) {
+  return (
+    <Grid columns={2} gap={2}>
+      {files.map(file => (
+        <Card key={file.id} variant="muted" padding={3}>
+          <VStack gap={1}>
+            <Text weight="medium" maxLines={1}>
+              {file.title}
+            </Text>
+            <Text type="supporting" maxLines={1}>
+              {file.meta}
+            </Text>
+          </VStack>
+        </Card>
+      ))}
+    </Grid>
+  );
+}
+
+export default function ScrollableAreaOverscrollChaining() {
+  return (
+    <Card width={400} padding={0}>
+      <ScrollableArea
+        axis="block"
+        role="region"
+        label="Workspace files"
+        height={300}
+        padding={4}>
+        <VStack gap={4}>
+          <VStack gap={0.5}>
+            <Heading level={3}>Workspace files</Heading>
+            <Text type="supporting">Two sections, two edge policies</Text>
+          </VStack>
+
+          <VStack gap={2}>
+            <Text type="label" color="secondary">
+              Shared with you
+            </Text>
+            {/* Default overscroll="allow": a gesture that reaches this
+                section's end carries on scrolling the panel behind it. */}
+            <ScrollableArea
+              axis="block"
+              label="Shared with you"
+              height={150}
+              padding={2}
+              xstyle={styles.sectionFrame}>
+              <FileGrid files={SHARED} />
+            </ScrollableArea>
+            <Text type="supporting">
+              Scroll past the end and the panel keeps going.
+            </Text>
+          </VStack>
+
+          <VStack gap={2}>
+            <Text type="label" color="secondary">
+              Archived
+            </Text>
+            {/* overscroll="contain" stops the gesture at this section's
+                edge, so the panel behind it stays put. */}
+            <ScrollableArea
+              axis="block"
+              label="Archived"
+              overscroll="contain"
+              height={150}
+              padding={2}
+              xstyle={styles.sectionFrame}>
+              <FileGrid files={ARCHIVED} />
+            </ScrollableArea>
+            <Text type="supporting">
+              Scroll past the end and the panel stays where it is.
+            </Text>
+          </VStack>
+        </VStack>
+      </ScrollableArea>
+    </Card>
+  );
+}

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ScrollableArea',
+  name: 'ScrollableArea',
+  displayName: 'Scrollable Area',
+  description:
+    'A fixed-height file panel that scrolls on the block axis; the heading sits inside the viewport, so it scrolls away with the content.',
+  isReady: true,
+  aspectRatio: 1,
+  isShowcase: true,
+  componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {ScrollableArea} from '@astryxdesign/core/ScrollableArea';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const SECTIONS = [
+  {
+    label: 'Recently opened',
+    files: [
+      {id: 'brief', title: 'Q3 launch brief', meta: 'Edited 2 days ago'},
+      {id: 'pricing', title: 'Pricing rework', meta: 'Edited 3 days ago'},
+      {
+        id: 'onboarding',
+        title: 'Onboarding flow v4',
+        meta: 'Edited 4 days ago',
+      },
+      {id: 'macros', title: 'Support macros', meta: 'Edited last week'},
+    ],
+  },
+  {
+    label: 'Shared with you',
+    files: [
+      {id: 'brand', title: 'Brand refresh', meta: 'Priya Raman'},
+      {id: 'checkout', title: 'Checkout audit', meta: 'Tomas Lindqvist'},
+      {id: 'partner', title: 'Partner deck', meta: 'Ines Okafor'},
+      {id: 'research', title: 'Research synthesis', meta: 'Mei Watanabe'},
+    ],
+  },
+  {
+    label: 'Archived',
+    files: [
+      {id: 'roadmap', title: '2025 roadmap', meta: 'Archived in March'},
+      {id: 'legacy', title: 'Legacy pricing', meta: 'Archived in March'},
+      {id: 'kit', title: 'Old brand kit', meta: 'Archived in January'},
+      {id: 'beta', title: 'Beta feedback', meta: 'Archived in January'},
+    ],
+  },
+];
+
+export default function ScrollableAreaShowcase() {
+  return (
+    <Card width={380} padding={0}>
+      {/* The heading sits inside the viewport, so it scrolls away with the
+          content instead of staying pinned above it. */}
+      <ScrollableArea
+        axis="block"
+        role="region"
+        label="Workspace files"
+        height={300}
+        padding={4}>
+        <VStack gap={4}>
+          <VStack gap={0.5}>
+            <Heading level={3}>Workspace files</Heading>
+            <Text type="supporting">12 files across 3 sections</Text>
+          </VStack>
+          {SECTIONS.map(section => (
+            <VStack key={section.label} gap={2}>
+              <Text type="label" color="secondary">
+                {section.label}
+              </Text>
+              <Grid columns={2} gap={2}>
+                {section.files.map(file => (
+                  <Card key={file.id} variant="muted" padding={3}>
+                    <VStack gap={1}>
+                      <Text weight="medium" maxLines={1}>
+                        {file.title}
+                      </Text>
+                      <Text type="supporting" maxLines={1}>
+                        {file.meta}
+                      </Text>
+                    </VStack>
+                  </Card>
+                ))}
+              </Grid>
+            </VStack>
+          ))}
+        </VStack>
+      </ScrollableArea>
+    </Card>
+  );
+}

package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ScrollableArea',
+  name: 'ScrollableArea — Sticky Section Labels',
+  displayName: 'Scrollable Area — Sticky Section Labels',
+  description:
+    'A scrollable viewport is the containing block for position: sticky, so section labels pin to the top edge of the list instead of the page.',
+  isReady: true,
+  aspectRatio: 1,
+  componentsUsed: ['ScrollableArea', 'Card', 'Grid'],
+};