@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/Slider/Slider.spec.md

@@ -0,0 +1,223 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Slider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/Slider/Slider.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Slider component contract
+
+## Intent
+
+Slider presents a labeled control for selecting one numeric value or a bounded
+range. This draft records its current consumer anatomy and theming ownership
+without changing runtime behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged; Slider remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The current slider row, background track, filled range, tick marks and labels,
+  thumbs, and adjacent text value presentation.
+- The existing `slider`, `slider-track`, and `slider-thumb` public targets.
+
+**Does not own / non-goals**
+
+- Label and validation-message presentation — owned by `component:Field` and
+  `component:FieldStatus`.
+- Value-tooltip presentation — owned by `component:Tooltip`.
+- New public targets for the filled range, tick marks, mark labels, description,
+  or adjacent text value display.
+- A decision that the current target asymmetry should be preserved or removed.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, modes, states, and usage
+remain documented in `Slider.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                       | Basis                                   | Draft review state                                 |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track.                           | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Track`, and `Thumb` carry the existing `slider`, `slider-track`, and `slider-thumb` targets respectively.                      | Current source and public docs          | Verified current behavior; no target change        |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs          | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip.                              | Current source and focused tests        | Verified composition boundary                      |
+
+### Observed current target asymmetry
+
+ProgressBar currently exposes targets for its fill and marks, while Slider
+exposes targets for its root row, background track, and thumbs but not its
+filled range, tick marks, mark labels, or adjacent text value display. This is
+implementation evidence for a joint audit, not approval of either target shape.
+
+### Allowed variation
+
+- Orientation, single or range mode, disabled state, value-display mode, and the
+  number or labels of supplied marks remain current capabilities rather than
+  separate target names.
+- A description, status message, mark label, text value, or value tooltip may be
+  absent without changing the remaining anatomy.
+
+### Representative states
+
+| State                    | Required invariant                                                      | Allowed variation                                  |
+| ------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| Single value             | One thumb and a filled range render over the track.                     | Orientation, value, disabled state, value display  |
+| Range value              | Two thumbs bound the filled range.                                      | Values and minimum step separation                 |
+| With marks               | Tick marks and optional mark labels align to the same range geometry.   | Mark count, values, and label presence             |
+| With shared field output | Field or Tooltip renders the requested label, feedback, or value layer. | Description, status, disabled reason, tooltip mode |
+
+### Transformation and precedence order
+
+- No new value, snapping, geometry, interaction, or styling precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Slider's existing accessible name, value,
+range-thumb naming, description/status association, keyboard behavior, disabled
+behavior, or value-tooltip behavior.
+
+## Design relationships
+
+| Anatomy or state        | Design requirement                                            | Representation authority        | Hierarchy role | Component contract |
+| ----------------------- | ------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Label and description   | Identify and explain the numeric setting.                     | Current shared-component source | Supporting     | FR4                |
+| Slider and track        | Arrange the current interactive range control and rail.       | Current source and public docs  | Prominent      | FR1, FR2           |
+| Filled range and thumbs | Show the selected value or interval over the available range. | Current source and public docs  | Prominent      | FR1, FR2, FR3      |
+| Tick marks and labels   | Show optional supplied positions and their text.              | Current source and public docs  | Supporting     | FR1, FR3           |
+| Value presentation      | Shows the formatted value as text or a shared Tooltip.        | Current source and public docs  | Supporting     | FR3, FR4           |
+| Status message          | Presents shared validation feedback below the slider.         | Current shared-component source | Supporting     | FR4                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches this part; future target ownership is undecided."
+    }
+  },
+  "Slider": {"target": "slider"},
+  "Track": {"target": "slider-track"},
+  "Filled range": {
+    "none": {
+      "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+    }
+  },
+  "Tick mark": {
+    "none": {
+      "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+    }
+  },
+  "Mark label": {
+    "none": {
+      "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+    }
+  },
+  "Thumb": {"target": "slider-thumb"},
+  "Value display": {
+    "none": {
+      "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."
+    }
+  },
+  "Value tooltip": {
+    "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+`Filled range`, `Tick mark`, `Mark label`, and `Value display` remain stable
+consumer anatomy, but no current Slider target reaches them. The map records
+those gaps without making their absence intentional. `Value display` names the
+adjacent text mode; the separately listed value tooltip retains Tooltip's target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+  `none` dispositions, and composition-preserving target ownership.
+- Field, FieldStatus, and Tooltip retain their existing public target contracts
+  when composed by Slider.
+- Slider and ProgressBar both render a track, a filled segment, positioned
+  indicators, and optional value presentation, while their current target
+  coverage differs. That evidence requires a future joint family/audit pass; it
+  does not declare a current family, require a new target, or authorize runtime
+  behavior changes.
+
+## Verification map
+
+| Contract            | Verification                                                                           | Representative states                             | Mutation or failure expectation                                                                                      | Audit section          |
+| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1                 | `Slider.test.tsx` structure, range, and marks suites                                   | Single, range, horizontal, vertical, marks        | Removing or misaligning stable parts breaks existing role, position, or mark assertions.                             | `audit:Slider/anatomy` |
+| FR2                 | `themingTargets.test.ts`                                                               | Root, track, and thumb target call sites          | Source and public target metadata drift fails the target guard.                                                      | `audit:Slider/theming` |
+| FR3                 | Source and consumer-doc review                                                         | Filled range, marks, labels, adjacent text value  | A missing target is inaccurately documented as present or intentionally permanent.                                   | `audit:Slider/theming` |
+| FR4                 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason     | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                          | Canonical anatomy and three current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation.                                   | `audit:Slider/theming` |
+
+The focused Slider suite does not separately assert the exact `slider`,
+`slider-track`, or `slider-thumb` class placement. The source/metadata target
+guard covers those declarations. It also covers only the disabled-reason
+Tooltip path, not the `valueDisplay="tooltip"` composition; that anatomy is
+source-inspected and remains missing focused test coverage.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+family, theming, or API decision.
+
+## Open questions
+
+- **OQ1 — After a joint ProgressBar and Slider family audit, should any shared
+  painted parts have aligned target coverage?** (`human-api`)
+
+This question records the audit need only. It does not presume that either
+component should add, remove, or rename a target.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, audit outcomes, or shared-component contracts. It links to their owners.

package/src/Stack/Stack.doc.mjs

@@ -1,5 +1,24 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Stack container',
+    required: true,
+    description: 'Layout container that arranges content along one flex axis.',
+  },
+  {
+    name: 'Item',
+    required: false,
+    description: 'Optional StackItem wrapper that controls one item in the stack.',
+  },
+  {
+    name: 'Content',
+    required: false,
+    description: 'Caller-supplied content rendered by a Stack or StackItem.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -440,6 +459,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
     bestPractices: [
@@ -629,6 +649,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
     bestPractices: [
@@ -643,6 +664,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Stack layout primitives for horizontal/vertical sequences using flexbox w/ themed spacing tokens.',
   usage: {
+    anatomy,
     description:
       'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
     bestPractices: [

package/src/Stack/Stack.spec.md

@@ -0,0 +1,154 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Stack
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming]
+verified_by:
+  [
+    packages/core/src/Stack/Stack.test.tsx,
+    packages/core/src/Stack/StackItem.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:layout-primitives]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:container-padding]
+contributing: []
+system_specs: []
+---
+
+# Stack component contract
+
+## Intent
+
+Stack arranges caller-supplied content along one flex axis. StackItem optionally
+wraps one item to control its participation in that layout. This draft records
+the current consumer anatomy and theming ownership without changing layout,
+padding, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Stack container and its current `stack` theming target.
+- The optional StackItem wrapper and its current `stack-item` theming target.
+
+**Does not own / non-goals**
+
+- Content supplied to Stack or StackItem — owned by the caller.
+- Container-inset publication or descendant bleed behavior; Stack padding is
+  currently local and does not participate in the container-padding protocol.
+- New layout, padding, or responsive behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Stack.doc.mjs`; `family:layout-primitives` owns the shared layout vocabulary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                            | Basis                                   | Draft review state                                 |
+| --- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | Stack, HStack, and VStack render caller content in a container carrying the current `stack` target.            | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |
+| FR2 | StackItem renders caller content in its own wrapper carrying the current `stack-item` target.                  | Current source, docs, and tests         | Verified current behavior; no new behavior decided |
+| FR3 | Stack and StackItem render caller-supplied content directly without applying a content-specific public target. | Current source and tests                | Verified current behavior; no target change        |
+| FR4 | Stack's existing padding remains local and does not publish container-padding geometry to descendants.         | Current source and architecture record  | Verified current behavior; no protocol change      |
+
+### Allowed variation
+
+- Caller content may render directly in Stack or inside optional StackItem
+  wrappers without changing target ownership.
+
+### Representative states
+
+- Horizontal and vertical Stack forms use the same container target. StackItem
+  uses its item target across static, fill, and scrollable behavior.
+
+### Transformation and precedence order
+
+- No new direction, alignment, spacing, sizing, or padding precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Stack's polymorphic element, forwarded DOM
+props, or caller-owned content semantics.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                         | Representation authority                  | Hierarchy role    | Component contract |
+| ---------------- | ---------------------------------------------------------- | ----------------------------------------- | ----------------- | ------------------ |
+| Stack container  | Presents the one-dimensional layout container.             | Current source, docs, and family contract | Supporting        | FR1, FR4           |
+| Item             | Optionally controls one child's participation in Stack.    | Current source, docs, and family contract | Supporting        | FR2                |
+| Content          | Presents caller-supplied content in either public wrapper. | Caller-supplied content                   | Context-dependent | FR1, FR2, FR3      |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Stack container": {"target": "stack"},
+  "Item": {"target": "stack-item"},
+  "Content": {
+    "none": {
+      "reason": "intentional: Caller-supplied content retains its own theming ownership; Stack and StackItem apply no content target."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `family:layout-primitives` owns Stack's shared direction, alignment, spacing,
+  sizing, padding, and item-participation vocabulary.
+- `architecture:container-padding` records that Stack padding is local and does
+  not publish descendant bleed geometry.
+- `architecture:component-theming-surface` owns anatomy qualification and target
+  mapping rules.
+
+## Verification map
+
+| Contract            | Verification                                       | Representative states                          | Mutation or failure expectation                                                        | Audit section             |
+| ------------------- | -------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR3, FR4       | `Stack.test.tsx` render, props, and padding suites | Horizontal/vertical, direct content, padding   | Removing the container/content or changing shipped local padding fails existing tests. | `audit:Stack/anatomy`     |
+| FR2, FR3            | `StackItem.test.tsx` render and behavior suites    | Static, fill, polymorphic, and scrollable item | Removing the wrapper/content or changing current item behavior fails existing tests.   | `audit:StackItem/anatomy` |
+| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`   | Stack and StackItem targets                    | Runtime and documented target metadata drift fails target validation.                  | `audit:Stack/theming`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                      | Canonical anatomy and both current targets     | Missing, extra, prefixed, or stale mappings fail repository validation.                | `audit:Stack/theming`     |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, container-padding mechanics, implementation steps, or system rules. It
+links to their owners.

package/src/StatusDot/StatusDot.doc.mjs

@@ -1,5 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Dot',
+    required: true,
+    description: 'Painted status dot that carries the selected semantic variant.',
+  },
+  {
+    name: 'Status icon',
+    required: false,
+    description: 'Optional caller-supplied icon rendered inside the dot.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -55,6 +69,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
@@ -115,6 +130,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
@@ -133,6 +149,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Small colored dot indicator for status display (online/offline, severity, etc).',
   usage: {
+    anatomy,
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [

package/src/StatusDot/StatusDot.spec.md

@@ -0,0 +1,137 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:StatusDot
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/StatusDot/StatusDot.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# StatusDot component contract
+
+## Intent
+
+StatusDot renders a compact painted status signal with an optional status icon.
+This draft records the current consumer anatomy and theming ownership without
+changing runtime behavior, target compatibility, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The painted dot and its current `status-dot` theming target.
+- The wrapper that positions optional status-icon content inside the dot.
+
+**Does not own / non-goals**
+
+- The artwork supplied through `icon` — owned by the caller.
+- The tooltip surface or trigger behavior when `tooltip` is supplied — owned by
+  Tooltip.
+- A built-in icon for each variant — the default dot remains childless.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `StatusDot.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                | Basis                           | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current render always contains one painted dot carrying the `status-dot` target.                               | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | When renderable icon content is supplied, it appears in an assistive-technology-hidden wrapper inside the dot.     | Current source and tests        | Verified current behavior; no new behavior decided |
+| FR3 | The deprecated `statusdot` class remains emitted beside `status-dot` for compatibility but is not current anatomy. | Current source, docs, and tests | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Caller-supplied icon artwork may vary without creating a separate public
+  target.
+
+### Representative states
+
+- The anatomy and target ownership are unchanged across semantic variants and
+  pulsing state. The optional status icon is absent when its content is not
+  renderable.
+
+### Transformation and precedence order
+
+- No new rendering, styling, or target precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend StatusDot's existing role, accessible-name,
+reduced-motion, or decorative-icon behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                        | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Dot              | Presents the current painted semantic-status signal.      | Current source and public docs | Supporting     | FR1, FR3           |
+| Status icon      | Presents optional caller-supplied artwork inside the dot. | Current source and tests       | Supporting     | FR2                |
+
+The deprecated `statusdot` alias is compatibility metadata, not a separate
+anatomy part or current target.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Dot": {"target": "status-dot"},
+  "Status icon": {"inherits": "status-dot"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification,
+  inheritance, and deprecated-alias exclusion.
+
+## Verification map
+
+| Contract            | Verification                                       | Representative states                 | Mutation or failure expectation                                                       | Audit section             |
+| ------------------- | -------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR2            | `StatusDot.test.tsx` render and custom-icon suites | Plain dot and dot with supplied icon  | Removing the dot or changing optional icon rendering fails existing DOM assertions.   | `audit:StatusDot/anatomy` |
+| FR3                 | `StatusDot.test.tsx` theme-target-name suite       | Current and deprecated target classes | Removing either emitted compatibility class fails the existing target assertion.      | `audit:StatusDot/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                      | Canonical anatomy and current target  | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:StatusDot/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or system rules. It links to their owners.

package/src/Switch/Switch.doc.mjs

@@ -1,5 +1,44 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Field',
+    required: true,
+    description: 'Container arranging the switch, label, and feedback.',
+  },
+  {
+    name: 'Track',
+    required: true,
+    description: 'Pill-shaped surface that shows the off or on state.',
+  },
+  {
+    name: 'Thumb',
+    required: true,
+    description: 'Indicator that moves across the track when state changes.',
+  },
+  {
+    name: 'Label',
+    required: true,
+    description: 'Text identifying the setting controlled by the switch.',
+  },
+  {
+    name: 'Description',
+    required: false,
+    description: 'Helper text below the label.',
+  },
+  {
+    name: 'Spinner',
+    required: false,
+    description: 'Loading indicator shown inside the thumb while busy.',
+  },
+  {
+    name: 'Status message',
+    required: false,
+    description: 'Error, warning, or success message below the switch.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -171,6 +210,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
     bestPractices: [