@astryxdesign/cli 0.4.6 → 0.4.7-canary.20bae6c

package/api/theme/themeTemplate.doc.mjs

@@ -15,9 +15,9 @@ export const doc = {
   displayName: 'themeTemplate()',
   summary: 'Write the annotated theme template into a project.',
   description:
-    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'Writes theme.template.ts: the annotated reference for the whole theme surface, covering every ' +
     'defineTheme field, the token families, the component override syntax, and how a theme is ' +
-    'consumed — with the CLI command that prints the authoritative reference for each section. ' +
+    'consumed, with the CLI command that prints the authoritative reference for each section. ' +
     'Read it, copy what you need into your own theme file, delete it. Where `theme add` starts ' +
     'you from a theme we ship, this starts you from a blank one. Refuses to overwrite without ' +
     '`overwrite`, so it is safe to re-run.',
@@ -48,7 +48,7 @@ export const doc = {
     {
       type: 'theme.template',
       description:
-        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success, not a failure.',
+        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success, not a failure.',
     },
   ],
   throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],

package/assets/docs/README.md

@@ -0,0 +1,50 @@
+# /packages/cli/assets/docs
+
+Reference topics for people **building with** Astryx. Not docs about building Astryx itself.
+
+One `{topic}.doc.mjs` per topic, plus optional `{topic}.doc.dense.mjs` / `{topic}.doc.zh.mjs` prose overlays. `foundation/discovery/docs-discovery.mjs` picks up any `{topic}.doc.mjs` here with no registration; `api/docs/_adapter.mjs` merges the overlays.
+
+What you add reaches `astryx docs <topic>`, `astryx search`, the `--json` API, the agent-docs block and the doc site — and ships on npm.
+
+## Who you are writing for
+
+Someone building a product with Astryx. Their questions:
+
+- what a component is for, and when to reach for something else
+- the props, their defaults, and what each does to what they see
+- how to compose it, and the pattern to copy
+- what it costs — bundle size, the a11y obligations they inherit
+- how to theme it, and which targets are stable
+
+**The test for anything you add: does a caller act on it?** They are not reviewing a PR, promoting a component out of lab, or attaching evidence to a checklist.
+
+## Tells that you are writing for us instead
+
+- second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
+- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- a table of things to verify rather than things to use
+- anything about lab → core, which is our lifecycle, not theirs
+- Storybook, Playwright, CI or the Simulator named as tools the reader runs
+
+One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
+
+## Where the rest goes
+
+The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
+
+| what you wrote                                      | where it goes                                                                                                                                                                                |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| how a component is graded — checks, scoring         | [Component-Audit-Rubric](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric)                                                                                                     |
+| lab → core promotion, what a component must satisfy | [Component-Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)                                                                                                           |
+| how to build a new component                        | [Component-Authoring-Guide](https://github.com/facebook/astryx/wiki/Component-Authoring-Guide), [Creating-New-Components](https://github.com/facebook/astryx/wiki/Creating-New-Components)   |
+| what a component must be hardened against           | [Component-Hardening-Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol), [Hardening-Audit-Guide](https://github.com/facebook/astryx/wiki/Hardening-Audit-Guide) |
+| a11y requirements as checks we run                  | [Accessibility-Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist)                                                                                                   |
+| how the system is put together                      | [System-Architecture](https://github.com/facebook/astryx/wiki/System-Architecture), [Theming-Infrastructure](https://github.com/facebook/astryx/wiki/Theming-Infrastructure)                 |
+| API naming and shape decisions                      | [API-Conventions](https://github.com/facebook/astryx/wiki/API-Conventions), [API-Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)                                       |
+| contributor workflow, PR process                    | [Contributing](https://github.com/facebook/astryx/wiki/Contributing), [Contributing-with-AI-Assistants](https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants)             |
+| release mechanics                                   | [Release-Process](https://github.com/facebook/astryx/wiki/Release-Process)                                                                                                                   |
+| what a nightly agent role does                      | the Night-Watch pages, from [Night-Watch-Overview](https://github.com/facebook/astryx/wiki/Night-Watch-Overview)                                                                             |
+
+**Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
+
+Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.

package/assets/docs/cli-integrations.doc.mjs

@@ -115,7 +115,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves — `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
+          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'`, the same shape core's own topics use.",
         },
         {
           type: 'code',
@@ -124,7 +124,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x — core's, or another integration's — so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
+          text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x (core's, or another integration's) so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
         },
         {
           type: 'code',
@@ -133,14 +133,14 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork — a fork of someone else's guide stops receiving their fixes the day you write it.",
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section whose title matches one in the base replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
             'A topic name is a CLI argument and a docsite path, so it may hold only letters, digits, `_` and `-`.',
-            "A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override — the CLI will not guess which one you meant.",
+            "A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override; the CLI will not guess which one you meant.",
             '`replaces` and `extends` are exclusive: a topic either takes another\'s place or merges onto it.',
             'Two integrations replacing one topic is a warning, and the one configured later in `astryx.config` wins.',
           ],

package/assets/docs/theme.doc.dense.mjs

@@ -10,7 +10,7 @@ export const docsDense = {
     { section: 'Theme Props', title: 'Props', content: [null] },
     { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: '`theme list` + `theme add <slug>` to start from a shipped theme, or defineTheme from scratch. only override tokens that differ.' }, null, { type: 'prose', text: '`astryx theme template` writes theme.template.ts: every defineTheme field + token families + override syntax, annotated, with the CLI command that prints each reference.' }] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent via HCT; accent = hex or [light, dark] tuple (per-scheme palettes). tokens overrides win token-by-token; --color-on-accent stays baked from color.accent, so prefer a tuple accent over overriding --color-accent.' }, null, null] },
-    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
     { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },

package/assets/docs/theme.doc.mjs

@@ -300,7 +300,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+          text: 'Run `astryx theme targets` for every themeable key in the system (`astryx theme targets <Name>` to scope it, `--json` to lint a theme against it), and `astryx component <Name>` for one component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
         },
         {
           type: 'list',

package/assets/docs/typography.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family — naming a webfont (Fraunces, JetBrains Mono, …) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',
+          text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family: naming a webfont (Fraunces, JetBrains Mono, and so on) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',
         },
         {
           type: 'code',
@@ -77,7 +77,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Always pair a webfont with a real fallback stack — metric-similar system fonts plus a generic — so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",
+          text: "Always pair a webfont with a real fallback stack (metric-similar system fonts plus a generic) so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",
         },
       ],
     },

package/assets/templates/blocks/components/Dialog/DialogAdaptivePresentation.doc.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Dialog',
+  alsoExampleFor: ['BottomSheet', 'useMediaQuery'],
+  name: 'Dialog — Adaptive presentation',
+  displayName: 'Dialog — Adaptive presentation',
+  description:
+    'Opt-in recipe for an AdaptiveDialog wrapper: Dialog remains the default everywhere, while touchPresentation="bottom-sheet" switches only at lg and below when pointer is coarse and hover is unavailable. Includes a deterministic presentation override for tests/unusual environments and notes that BottomSheet purpose controls swipe and scrim dismissal. Usage examples: touchPresentation="dialog" keeps Dialog, "fullscreen" chooses fullscreen Dialog, and "bottom-sheet" chooses BottomSheet only for the touch-oriented range. Keep presentation as the deterministic override. Do not use this by default for AlertDialog or destructive confirmations.',
+  isReady: true,
+  aspectRatio: 3 / 4,
+  componentsUsed: [
+    'Dialog',
+    'DialogHeader',
+    'BottomSheet',
+    'Layout',
+    'Button',
+    'Text',
+    'TextInput',
+    'TextArea',
+    'useMediaQuery',
+  ],
+};

package/assets/templates/blocks/components/Dialog/DialogAdaptivePresentation.tsx

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState, type ReactNode} from 'react';
+import {BottomSheet} from '@astryxdesign/core/BottomSheet';
+import {Button} from '@astryxdesign/core/Button';
+import {
+  Dialog,
+  DialogHeader,
+  type DialogPurpose,
+} from '@astryxdesign/core/Dialog';
+import {Heading} from '@astryxdesign/core/Heading';
+import {
+  HStack,
+  Layout,
+  LayoutContent,
+  LayoutFooter,
+  VStack,
+} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {useMediaQuery} from '@astryxdesign/core/hooks';
+
+const TOUCH_ORIENTED_LG_QUERY =
+  '(max-width: 1024px) and (pointer: coarse) and (hover: none)';
+
+type AdaptivePresentation = 'dialog' | 'fullscreen' | 'bottom-sheet';
+
+type AdaptiveDialogProps = {
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+  title: string;
+  children: ReactNode;
+  footer?: ReactNode;
+  purpose?: DialogPurpose;
+  width?: number | string;
+  maxHeight?: number | string;
+  touchPresentation?: AdaptivePresentation;
+  presentation?: AdaptivePresentation;
+  bottomSheetHeight?: 'hug' | 'capped' | 'tall' | number | string;
+};
+
+function AdaptiveDialog({
+  isOpen,
+  onOpenChange,
+  title,
+  children,
+  footer,
+  purpose = 'info',
+  width = 480,
+  maxHeight = '75dvh',
+  touchPresentation = 'dialog',
+  presentation,
+  bottomSheetHeight = 'capped',
+}: AdaptiveDialogProps) {
+  const isTouchOrientedLargeOrBelow = useMediaQuery(TOUCH_ORIENTED_LG_QUERY);
+  const resolvedPresentation =
+    presentation ??
+    (isTouchOrientedLargeOrBelow ? touchPresentation : 'dialog');
+
+  if (resolvedPresentation === 'bottom-sheet') {
+    return (
+      <BottomSheet
+        isOpen={isOpen}
+        onOpenChange={onOpenChange}
+        label={title}
+        purpose={purpose}
+        height={bottomSheetHeight}>
+        <VStack gap={4} style={{padding: 'var(--spacing-4)'}}>
+          <Heading level={3}>{title}</Heading>
+          {children}
+          {footer}
+        </VStack>
+      </BottomSheet>
+    );
+  }
+
+  const dialogContent = (
+    <Layout
+      header={<DialogHeader title={title} onOpenChange={onOpenChange} />}
+      content={<LayoutContent>{children}</LayoutContent>}
+      footer={footer ? <LayoutFooter>{footer}</LayoutFooter> : undefined}
+    />
+  );
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onOpenChange={onOpenChange}
+      purpose={purpose}
+      width={width}
+      maxHeight={maxHeight}
+      variant={
+        resolvedPresentation === 'fullscreen' ? 'fullscreen' : 'standard'
+      }>
+      {dialogContent}
+    </Dialog>
+  );
+}
+
+export default function DialogAdaptivePresentation() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [name, setName] = useState('Ruby Cheung');
+  const [email, setEmail] = useState('ruby@example.com');
+  const [notes, setNotes] = useState('');
+
+  return (
+    <>
+      <Button label="Edit profile" onClick={() => setIsOpen(true)} />
+      {/*
+        touchPresentation examples:
+        - "dialog" keeps Dialog even in touch-oriented <=lg contexts.
+        - "fullscreen" uses fullscreen Dialog there.
+        - "bottom-sheet" uses BottomSheet there.
+        presentation="dialog" | "fullscreen" | "bottom-sheet" overrides
+        the media query for tests and unusual environments.
+      */}
+      <AdaptiveDialog
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+        title="Edit profile"
+        purpose="form"
+        touchPresentation="bottom-sheet"
+        bottomSheetHeight="tall"
+        footer={
+          <HStack gap={2} hAlign="end" wrap="wrap">
+            <Button
+              label="Cancel"
+              variant="secondary"
+              onClick={() => setIsOpen(false)}
+            />
+            <Button
+              label="Save profile"
+              variant="primary"
+              onClick={() => setIsOpen(false)}
+            />
+          </HStack>
+        }>
+        <VStack gap={4}>
+          <Text type="supporting" color="secondary">
+            Dialog remains the default presentation. This example explicitly
+            opts into a Bottom Sheet only at lg and below when the device has a
+            coarse pointer and no hover. Pass the presentation prop to make
+            tests or unusual environments deterministic.
+          </Text>
+          <Text type="supporting" color="secondary">
+            In Bottom Sheet presentation, purpose="form" blocks scrim clicks and
+            swipe dismissal while preserving Escape. Use this opt-in only when
+            that contract is acceptable; keep AlertDialog/destructive
+            confirmations on Dialog unless a product deliberately chooses
+            otherwise.
+          </Text>
+          <TextInput label="Name" value={name} onChange={setName} />
+          <TextInput
+            label="Email"
+            type="email"
+            value={email}
+            onChange={setEmail}
+          />
+          <TextArea label="Notes" rows={6} value={notes} onChange={setNotes} />
+        </VStack>
+      </AdaptiveDialog>
+    </>
+  );
+}

package/assets/templates/blocks/components/Dialog/DialogScrollingContent.tsx

@@ -69,7 +69,7 @@ function Content({onClose}: {onClose: () => void}) {
 
 // Remove isInline for production — dialogs should be modal.
 export default function DialogScrollingContent() {
-  const dialog = useImperativeDialog({maxHeight: '50vh'});
+  const dialog = useImperativeDialog({maxHeight: '50dvh'});
 
   return (
     <>

package/assets/templates/blocks/components/Step/StepContent.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: 'Step',
+  name: 'Step — Content Slot',
+  displayName: 'Step — Content Slot',
+  description:
+    'Children passed to a Step render below its description, indented to line up with the label rather than the indicator, and stay outside the clickable label area so buttons inside remain their own targets. In a full flow you gate the slot on the step being active — that is what turns a vertical stepper into an expanding one.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'Step', 'TextInput', 'Button'],
+};

package/assets/templates/blocks/components/Step/StepContent.tsx

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+
+export default function StepContent() {
+  // Anything passed as children renders below the description, indented to line
+  // up with the label rather than the indicator. In a full flow you would gate
+  // this on the step being active; here it is a single Step so the slot is
+  // always shown.
+  return (
+    <div style={{width: 400}}>
+      <Stepper activeStep={1} orientation="vertical">
+        <Step
+          step={1}
+          label="Billing address"
+          description="Used for invoices and tax calculation">
+          <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+            <TextInput label="Street" placeholder="1 Hacker Way" value="" />
+            <TextInput label="City" placeholder="Menlo Park" value="" />
+            <div>
+              <Button label="Save address" variant="primary" />
+            </div>
+          </div>
+        </Step>
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Step/StepIndicator.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: 'Step',
+  name: 'Step — Indicator',
+  displayName: 'Step — Indicator',
+  description:
+    'Everything the indicator prop accepts: the auto default, an always-number badge, a custom ReactNode, and none — each on its own completed Step so the prop is the only difference between them. Every variant occupies the same 16px box, so a step swapping its number for a check as it completes never shifts the label beside it. The last cell shows that a custom node can be live rather than static: a Spinner on a step that is in progress, shaded `inherit` so it picks up the step\u2019s own tint like any other glyph.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'Step', 'Icon', 'Spinner', 'Text'],
+};

package/assets/templates/blocks/components/Step/StepIndicator.tsx

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+import {Spinner} from '@astryxdesign/core/Spinner';
+
+export default function StepIndicator() {
+  // The first four steps are all completed — same progress, so the indicator
+  // prop is the only difference between them. `auto` is the one that reacts to
+  // progress: a numbered badge until the step is reached, then a check. The
+  // last step is in progress instead, because the node it passes to `indicator`
+  // is a spinner and a spinner only makes sense on work that is running.
+  return (
+    <div style={{display: 'flex', flexWrap: 'wrap', gap: 24}}>
+      <div style={{width: 190}}>
+        <Text type="label">auto (default)</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step step={0} label="Verify email" />
+        </Stepper>
+      </div>
+      <div style={{width: 190}}>
+        <Text type="label">number</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step step={0} label="Verify email" indicator="number" />
+        </Stepper>
+      </div>
+      <div style={{width: 190}}>
+        <Text type="label">Custom node</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step
+            step={0}
+            label="Verify email"
+            indicator={<Icon icon="wrench" size="sm" />}
+          />
+        </Stepper>
+      </div>
+      <div style={{width: 190}}>
+        <Text type="label">none</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step step={0} label="Verify email" indicator="none" />
+        </Stepper>
+      </div>
+      <div style={{width: 190}}>
+        <Text type="label">Spinner (in progress)</Text>
+        <Stepper activeStep={0} orientation="vertical">
+          <Step
+            step={0}
+            label="Verify email"
+            // `inherit` picks up the indicator's own tint, so the spinner is
+            // colored by the step's progress and status like any other glyph.
+            indicator={<Spinner size="md" shade="inherit" />}
+          />
+        </Stepper>
+      </div>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Step/StepShowcase.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: 'Step',
+  name: 'Step',
+  displayName: 'Step',
+  description:
+    'A single Step, with every part it can render: the indicator, the label with its optional marker and trailing endContent, and the description beneath. A Step never sets its own completed/current state — it declares its index and derives the rest from the parent Stepper, so one Step in one Stepper is a complete example.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Stepper', 'Step', 'Text'],
+};

package/assets/templates/blocks/components/Step/StepShowcase.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StepShowcase() {
+  // One Step, and every part it renders: the indicator, the label with its
+  // optional marker and trailing slot, and the description beneath. A Step is
+  // always wrapped in a Stepper — that is where it reads its progress from —
+  // so a single Step in a single Stepper is the smallest complete example.
+  return (
+    <div style={{width: 380}}>
+      <Stepper activeStep={1} orientation="vertical">
+        <Step
+          step={1}
+          label="Connect a repository"
+          description="Astryx reads your build settings from the default branch"
+          endContent={<Text type="supporting">2 min</Text>}
+          isOptional
+        />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Step/StepStates.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: 'Step',
+  name: 'Step — States',
+  displayName: 'Step — States',
+  description:
+    'Every state a single Step can land in, each shown as one Step in its own Stepper. Completed, current, and upcoming are derived by comparing the step index against the parent activeStep, so they are never set directly; isDisabled and status are the two a step declares itself. Status is a separate axis from progress, which is why a completed step can still carry a warning.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'Step', 'Text'],
+};

package/assets/templates/blocks/components/Step/StepStates.tsx

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Stepper, Step} from '@astryxdesign/core/Stepper';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StepStates() {
+  // A Step holds no state of its own — it compares its `step` index against the
+  // Stepper's `activeStep`. Each state below is therefore one Step in its own
+  // Stepper, with activeStep placed on one side of it or the other.
+  return (
+    <div style={{display: 'flex', flexWrap: 'wrap', gap: 32}}>
+      <div style={{width: 220}}>
+        <Text type="label">Completed</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step step={0} label="Verify email" />
+        </Stepper>
+      </div>
+      <div style={{width: 220}}>
+        <Text type="label">Current</Text>
+        <Stepper activeStep={0} orientation="vertical">
+          <Step step={0} label="Verify email" />
+        </Stepper>
+      </div>
+      <div style={{width: 220}}>
+        <Text type="label">Upcoming</Text>
+        <Stepper activeStep={0} orientation="vertical">
+          <Step step={1} label="Add a payment method" />
+        </Stepper>
+      </div>
+      <div style={{width: 220}}>
+        <Text type="label">Disabled</Text>
+        <Stepper activeStep={0} orientation="vertical" onStepClick={() => {}}>
+          <Step step={1} label="Add a payment method" isDisabled />
+        </Stepper>
+      </div>
+      <div style={{width: 220}}>
+        <Text type="label">Completed, with a status</Text>
+        <Stepper activeStep={1} orientation="vertical">
+          <Step step={0} label="Verify email" status="warning" />
+        </Stepper>
+      </div>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperCustomContent.doc.mjs

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Custom Content',
+  displayName: 'Stepper — Custom Content',
+  description:
+    'A vertical stepper where each step owns a slice of the page. The content slot takes any node — form fields, a summary panel, a banner — so a stepper is not limited to multi-step forms. Rendering the slot only for the active step is what makes the flow expand one step at a time.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: [
+    'Stepper',
+    'TextInput',
+    'Button',
+    'Text',
+    'Card',
+    'Badge',
+    'Banner',
+  ],
+};