@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/src/utils/package-manager.test.mjs

@@ -4,9 +4,16 @@ import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {detectPackageManager} from './package-manager.mjs';
+import {
+  detectPackageManager,
+  getDlxPrefix,
+  isCliOneOff,
+  getCliInvocation,
+  formatCliCommand,
+} from './package-manager.mjs';
 
 let tmpDir;
+const ORIGINAL_ARGV1 = process.argv[1];
 
 afterEach(() => {
   if (tmpDir) {
@@ -15,6 +22,7 @@ afterEach(() => {
   }
   vi.restoreAllMocks();
   delete process.env.npm_config_user_agent;
+  process.argv[1] = ORIGINAL_ARGV1;
 });
 
 function makeTmpDir() {
@@ -111,3 +119,102 @@ describe('detectPackageManager', () => {
     expect(detectPackageManager(dir)).toBe('bun');
   });
 });
+
+describe('getDlxPrefix', () => {
+  it('returns "pnpm dlx" for pnpm projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getDlxPrefix(dir)).toBe('pnpm dlx');
+  });
+
+  it('returns "yarn dlx" for yarn projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+    expect(getDlxPrefix(dir)).toBe('yarn dlx');
+  });
+
+  it('returns "bunx" for bun projects', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+    expect(getDlxPrefix(dir)).toBe('bunx');
+  });
+
+  it('falls back to "npx" with no signals', () => {
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getDlxPrefix(dir)).toBe('npx');
+  });
+});
+
+describe('isCliOneOff', () => {
+  it('detects an npm npx cache entry', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a pnpm dlx cache entry', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('detects a bunx cache entry', () => {
+    process.argv[1] = '/home/u/.bun/install/cache/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(true);
+  });
+
+  it('is false for an installed node_modules entry', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+
+  it('is false for a source checkout (dev) entry', () => {
+    process.argv[1] = '/repo/packages/cli/bin/astryx.mjs';
+    expect(isCliOneOff()).toBe(false);
+  });
+});
+
+describe('getCliInvocation', () => {
+  it('uses the run-prefix + bare bin when installed (not one-off)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm exec astryx');
+  });
+
+  it('uses the dlx runner + scoped package when run one-off', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    delete process.env.npm_config_user_agent;
+    expect(getCliInvocation(dir)).toBe('npx @astryxdesign/cli');
+  });
+
+  it('pairs the dlx runner with the scoped package for pnpm one-off', () => {
+    process.argv[1] = '/home/u/.cache/pnpm/dlx/9f/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(getCliInvocation(dir)).toBe('pnpm dlx @astryxdesign/cli');
+  });
+});
+
+describe('formatCliCommand', () => {
+  it('strips a leading "astryx" token and prepends the invocation stem', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('pnpm exec astryx component Button');
+  });
+
+  it('accepts a bare subcommand (no leading astryx)', () => {
+    process.argv[1] = '/proj/node_modules/@astryxdesign/cli/bin/astryx.mjs';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('docs tokens', dir)).toBe('npx astryx docs tokens');
+  });
+
+  it('rewrites to the scoped package for one-off invocations', () => {
+    process.argv[1] = '/home/u/.npm/_npx/a1b2/node_modules/.bin/astryx';
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), '{}');
+    expect(formatCliCommand('astryx component Button', dir)).toBe('npx @astryxdesign/cli component Button');
+  });
+});

package/src/utils/path-safety.mjs

@@ -165,21 +165,3 @@ export function isFilePathArg(pathArg) {
   const ext = path.extname(base).toLowerCase();
   return ext.length > 0 && FILE_EXTENSIONS.has(ext);
 }
-
-/**
- * True when the process is running non-interactively (no TTY) or when the
- * caller has signaled JSON / scripted use. Commands consult this before
- * prompting for confirmation; in scripted mode they require an explicit
- * `--overwrite` flag instead.
- *
- * @param {object} [options]
- * @param {boolean} [options.json] - Caller's --json flag.
- * @returns {boolean}
- */
-export function isNonInteractive({json = false} = {}) {
-  if (json) return true;
-  // stdin not a TTY means piped input or scripted execution.
-  if (process.stdin && process.stdin.isTTY === false) return true;
-  if (process.stdout && process.stdout.isTTY === false) return true;
-  return false;
-}

package/src/utils/update-check.mjs

@@ -14,6 +14,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {semverGt} from './semver.mjs';
+import {getCliInvocation} from './package-manager.mjs';
 
 /**
  * Read the latest available version from local signals.
@@ -75,7 +76,7 @@ export function checkForUpdate(cwd = process.cwd()) {
   // Use semver-aware comparison so '0.0.20' is correctly treated as greater
   // than '0.0.5' (lexicographic compare gets that backwards).
   if (semverGt(latest, installed)) {
-    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: astryx upgrade --from <old-version> --apply`;
+    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: ${getCliInvocation()} upgrade --from <old-version> --apply`;
   }
 
   return null;

package/templates/blocks/components/Avatar/AvatarGroup.tsx

@@ -7,28 +7,26 @@ import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
 import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
 
-const CDN = 'https://lookaside.facebook.com/assets/astryx';
-
 const USERS = [
   {
     name: 'Ami Pena',
-    src: `${CDN}/DATA-Ami-Pena.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png',
   },
   {
     name: 'Drew Young',
-    src: `${CDN}/DATA-Drew-Young.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png',
   },
   {
     name: 'Gabriela Fernandez',
-    src: `${CDN}/DATA-Gabriela-Fernandez.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png',
   },
   {
     name: 'Jihoo Song',
-    src: `${CDN}/DATA-Jihoo-Song.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png',
   },
   {
     name: 'Nam Tran',
-    src: `${CDN}/DATA-Nam-Tran.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png',
   },
 ];
 

package/templates/blocks/components/Avatar/AvatarShowcase.tsx

@@ -5,29 +5,27 @@
 import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
-const CDN = 'https://lookaside.facebook.com/assets/astryx';
-
 export default function AvatarShowcase() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
       <Avatar
-        src={`${CDN}/DATA-Ana-Thomas.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
         size="large"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
-        src={`${CDN}/DATA-Drew-Young.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Drew-Young.png"
         name="Drew Young"
         size="large"
       />
       <Avatar
-        src={`${CDN}/DATA-Jihoo-Song.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Jihoo-Song.png"
         name="Jihoo Song"
         size="large"
       />
       <Avatar
-        src={`${CDN}/DATA-Nam-Tran.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png"
         name="Nam Tran"
         size="large"
         status={<AvatarStatusDot variant="error" label="Online" />}

package/templates/blocks/components/Avatar/AvatarUserCard.tsx

@@ -6,24 +6,22 @@ import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
 
-const CDN = 'https://lookaside.facebook.com/assets/astryx';
-
 const USERS = [
   {
     name: 'Itai Jordaan',
-    src: `${CDN}/DATA-Itai-Jordaan.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png',
     role: 'Engineering Lead',
     variant: 'success' as const,
   },
   {
     name: 'Margot Schroder',
-    src: `${CDN}/DATA-Margot-Schroder.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png',
     role: 'Product Designer',
     variant: 'neutral' as const,
   },
   {
     name: 'Daniela Gimenez',
-    src: `${CDN}/DATA-Daniela-Gimenez.png`,
+    src: 'https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png',
     role: 'Engineering Manager',
     variant: 'error' as const,
   },

package/templates/blocks/components/Avatar/AvatarWithImage.tsx

@@ -5,24 +5,26 @@
 import {Avatar} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
-const CDN = 'https://lookaside.facebook.com/assets/astryx';
-
 export default function AvatarWithImage() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
-      <Avatar src={`${CDN}/DATA-Ami-Pena.png`} name="Ami Pena" size="tiny" />
       <Avatar
-        src={`${CDN}/DATA-Ana-Thomas.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Ami-Pena.png"
+        name="Ami Pena"
+        size="tiny"
+      />
+      <Avatar
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Ana-Thomas.png"
         name="Ana Thomas"
         size="small"
       />
       <Avatar
-        src={`${CDN}/DATA-Daniela-Gimenez.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Daniela-Gimenez.png"
         name="Daniela Gimenez"
         size="medium"
       />
       <Avatar
-        src={`${CDN}/DATA-Gabriela-Fernandez.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Gabriela-Fernandez.png"
         name="Gabriela Fernandez"
         size="large"
       />

package/templates/blocks/components/Avatar/AvatarWithStatus.tsx

@@ -5,25 +5,23 @@
 import {Avatar, AvatarStatusDot} from '@astryxdesign/core/Avatar';
 import {Stack} from '@astryxdesign/core/Layout';
 
-const CDN = 'https://lookaside.facebook.com/assets/astryx';
-
 export default function AvatarWithStatus() {
   return (
     <Stack direction="horizontal" gap={4} vAlign="center">
       <Avatar
-        src={`${CDN}/DATA-Itai-Jordaan.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Itai-Jordaan.png"
         name="Itai Jordaan"
         size="large"
         status={<AvatarStatusDot variant="success" label="Online" />}
       />
       <Avatar
-        src={`${CDN}/DATA-Margot-Schroder.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Margot-Schroder.png"
         name="Margot Schroder"
         size="large"
         status={<AvatarStatusDot variant="neutral" label="Offline" />}
       />
       <Avatar
-        src={`${CDN}/DATA-Pablo-Morales.png`}
+        src="https://lookaside.facebook.com/assets/astryx/DATA-Pablo-Morales.png"
         name="Pablo Morales"
         size="large"
         status={<AvatarStatusDot variant="error" label="Busy" />}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputControlledInput.tsx

@@ -10,7 +10,7 @@ import {Text} from '@astryxdesign/core/Text';
 export default function ChatComposerInputControlledInput() {
   const [value, setValue] = useState('');
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         value={value}

package/templates/blocks/components/ChatComposerInput/ChatComposerInputDisabled.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputDisabled() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         isDisabled

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMentionTrigger.tsx

@@ -43,7 +43,7 @@ export default function ChatComposerInputMentionTrigger() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => setValue('')}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputMultipleTriggers.tsx

@@ -54,7 +54,7 @@ export default function ChatComposerInputMultipleTriggers() {
   };
 
   return (
-    <Stack direction="vertical" gap={3} style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" gap={3} style={{width: 450, maxWidth: '100%'}}>
       <Text type="supporting" color="secondary">
         Type @ for mentions (blue) or / for commands (yellow)
       </Text>

package/templates/blocks/components/ChatComposerInput/ChatComposerInputShowcase.tsx

@@ -7,7 +7,7 @@ import {Stack} from '@astryxdesign/core/Layout';
 
 export default function ChatComposerInputShowcase() {
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/blocks/components/ChatComposerInput/ChatComposerInputSlashCommands.tsx

@@ -40,7 +40,7 @@ export default function ChatComposerInputSlashCommands() {
   };
 
   return (
-    <Stack direction="vertical" style={{width: '100%', maxWidth: 450}}>
+    <Stack direction="vertical" style={{width: 450, maxWidth: '100%'}}>
       <ChatComposer
         onSubmit={() => {}}
         input={

package/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'TabList — With Actions',
   displayName: 'TabList — With Actions',
   description:
-    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, pair with a smaller button size (sm) so actions don\'t overpower the tab row.',
+    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, match the Button size to the TabList size so the tabs and actions align to a shared baseline above the divider.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['TabList', 'Tab', 'Button'],

package/templates/blocks/components/TabList/TabListTabsWithActions.tsx

@@ -55,16 +55,11 @@ export default function TabListTabsWithActions() {
         <Button
           label="Filter"
           variant="ghost"
-          size="sm"
+          size="lg"
           icon={FilterIcon}
           isIconOnly
         />
-        <Button
-          label="New item"
-          variant="primary"
-          size="sm"
-          icon={PlusIcon}
-        />
+        <Button label="New item" variant="primary" size="lg" icon={PlusIcon} />
       </div>
     </TabList>
   );

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'VisuallyHidden',
+  name: 'VisuallyHidden — Live Region',
+  displayName: 'VisuallyHidden — Live Region',
+  description:
+    'A polite aria-live region announces visual-only state changes to assistive technology.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['VisuallyHidden', 'Button', 'HStack', 'VStack', 'Text'],
+};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenLiveRegion.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {Button} from '@astryxdesign/core/Button';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const columns = ['Backlog', 'In progress', 'Done'] as const;
+
+export default function VisuallyHiddenLiveRegion() {
+  const [column, setColumn] = useState(0);
+  const current = columns[column];
+
+  function move() {
+    setColumn(c => (c + 1) % columns.length);
+  }
+
+  return (
+    <VStack gap={4} hAlign="start">
+      <Text type="supporting" color="secondary">
+        Drag-and-drop and other visual-only changes are silent to screen
+        readers. A live region narrates them.
+      </Text>
+      <HStack gap={3} vAlign="center">
+        <Button label="Move task" variant="secondary" onClick={move} />
+        <Text type="body">
+          Task is in{' '}
+          <Text as="span" weight="bold">
+            {current}
+          </Text>
+        </Text>
+      </HStack>
+      <VisuallyHidden as="div" aria-live="polite">
+        {`Task moved to ${current}`}
+      </VisuallyHidden>
+    </VStack>
+  );
+}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.doc.mjs

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'VisuallyHidden',
+  name: 'VisuallyHidden',
+  displayName: 'VisuallyHidden',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  isShowcase: true,
+  componentsUsed: ['VisuallyHidden', 'IconButton', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],
+};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenShowcase.tsx

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {IconButton} from '@astryxdesign/core/IconButton';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+import {
+  ArrowDownTrayIcon,
+  ShareIcon,
+  TrashIcon,
+} from '@heroicons/react/24/outline';
+import {SpeakerWaveIcon} from '@heroicons/react/24/solid';
+
+const actions = [
+  {label: 'Download', icon: ArrowDownTrayIcon},
+  {label: 'Share', icon: ShareIcon},
+  {label: 'Delete', icon: TrashIcon},
+] as const;
+
+/**
+ * VisuallyHidden is invisible by design, so this hero teaches the concept by
+ * contrast: the icon-only buttons are all a sighted user sees, while the
+ * caption spells out the accessible name each one exposes. A live
+ * <VisuallyHidden> region below announces the same names to assistive tech,
+ * so the demo genuinely exercises the component it documents.
+ */
+export default function VisuallyHiddenShowcase() {
+  return (
+    <VStack gap={5} hAlign="center">
+      <HStack gap={6} vAlign="stretch" wrap="wrap" hAlign="center">
+        <Card variant="muted">
+          <VStack gap={4} hAlign="center">
+            <Text type="supporting" color="secondary">
+              What you see
+            </Text>
+            <HStack gap={2}>
+              {actions.map(({label, icon}) => (
+                <IconButton
+                  key={label}
+                  label={label}
+                  icon={<Icon icon={icon} />}
+                  variant="ghost"
+                />
+              ))}
+            </HStack>
+          </VStack>
+        </Card>
+
+        <Card variant="muted">
+          <VStack gap={4} hAlign="start">
+            <HStack gap={2} vAlign="center">
+              <Icon icon={SpeakerWaveIcon} size="sm" />
+              <Text type="supporting" color="secondary">
+                What a screen reader hears
+              </Text>
+            </HStack>
+            <VStack gap={2}>
+              {actions.map(({label}) => (
+                <Text key={label} type="body">
+                  {label}, button
+                </Text>
+              ))}
+            </VStack>
+          </VStack>
+        </Card>
+      </HStack>
+
+      {/* A real live region: silent to sighted users, announced by AT. */}
+      <VisuallyHidden as="div" aria-live="polite">
+        Actions available: Download, Share, Delete.
+      </VisuallyHidden>
+    </VStack>
+  );
+}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'VisuallyHidden',
+  name: 'VisuallyHidden — Structural Heading',
+  displayName: 'VisuallyHidden — Structural Heading',
+  description:
+    'Give a visually implicit section an accessible name so screen-reader users can navigate to it.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Badge'],
+};

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenStructuralHeading.tsx

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {Badge} from '@astryxdesign/core/Badge';
+
+const items = [
+  {name: 'astryx-core', status: 'Passing', variant: 'success'},
+  {name: 'astryx-charts', status: 'Failing', variant: 'error'},
+  {name: 'astryx-cli', status: 'Passing', variant: 'success'},
+] as const;
+
+export default function VisuallyHiddenStructuralHeading() {
+  return (
+    <VStack gap={3} hAlign="start">
+      <Text type="supporting" color="secondary">
+        The layout makes this group obvious to sighted users. A hidden heading
+        gives screen-reader users the same landmark to jump to.
+      </Text>
+      {/* No visible heading is needed here, but AT users navigate by heading. */}
+      <VisuallyHidden as="h2">Build status</VisuallyHidden>
+      <VStack gap={2}>
+        {items.map(({name, status, variant}) => (
+          <Card key={name} variant="muted" padding={3}>
+            <HStack gap={3} vAlign="center">
+              <Text type="body">{name}</Text>
+              <Badge label={status} variant={variant} />
+            </HStack>
+          </Card>
+        ))}
+      </VStack>
+    </VStack>
+  );
+}

package/templates/blocks/components/VisuallyHidden/VisuallyHiddenSupplementaryContext.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'VisuallyHidden',
+  name: 'VisuallyHidden — Supplementary Context',
+  displayName: 'VisuallyHidden — Supplementary Context',
+  description:
+    'Add screen-reader-only context to terse visual data, like spelling out what a trend arrow means.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['VisuallyHidden', 'Card', 'HStack', 'VStack', 'Text', 'Icon'],
+};