Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(core): record factual anatomy batch 3 (#5745)

Cindy Zhang89dbbf7c6420
diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjs
index ceb0c897a1..6765a647fc 100644
--- a/packages/core/src/OverflowList/OverflowList.doc.mjs
+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs
@@ -1,5 +1,26 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'List',
+ required: true,
+ description: 'Visible horizontal list container for the currently shown content.',
+ },
+ {
+ name: 'Items',
+ required: true,
+ description:
+ 'Caller-supplied items selected for visible display by the current width and count limits.',
+ },
+ {
+ name: 'Overflow indicator',
+ required: false,
+ description:
+ 'Optional caller-rendered indicator for items collapsed by width or count limits.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -106,6 +127,7 @@ export const docs = {
targets: [{className: 'astryx-overflow-list'}],
},
usage: {
+ anatomy,
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
@@ -209,6 +231,7 @@ export const docsZh = {
},
],
usage: {
+ anatomy,
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
@@ -246,6 +269,7 @@ export const docsDense = {
description:
'horizontal list w/ overflow indicator: hides items beyond container width',
usage: {
+ anatomy,
description:
'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
bestPractices: [
diff --git a/packages/core/src/OverflowList/OverflowList.spec.md b/packages/core/src/OverflowList/OverflowList.spec.md
new file mode 100644
index 0000000000..196677d31e
--- /dev/null
+++ b/packages/core/src/OverflowList/OverflowList.spec.md
@@ -0,0 +1,156 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:OverflowList
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+ [
+ packages/core/src/OverflowList/OverflowList.test.tsx,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# OverflowList component contract
+
+## Intent
+
+OverflowList renders a selected subset of caller-supplied items in a visible
+horizontal list and may render a caller-supplied indicator for collapsed items.
+Items may collapse because they exceed the measured space or a configured count
+limit. This draft records the current consumer anatomy and theming ownership
+without changing measurement, collapse behavior, 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
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The visible list container and its current `overflow-list` theming target.
+- Measuring available space, applying configured count limits, and choosing
+ which supplied items remain visible.
+
+**Does not own / non-goals**
+
+- The items supplied through `children` — owned by the caller.
+- The overflow indicator returned by `overflowRenderer` — owned by the caller.
+- The hidden inert measurement container as consumer-facing anatomy or a public
+ target.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `OverflowList.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The visible list container carries the `overflow-list` target and renders the caller-supplied items selected by current width and count limits. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | When the current overflow calculation collapses items and a renderer is supplied, its returned indicator appears at the configured collapse edge. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR3 | The hidden inert measurement copy carries no public theming target and is not consumer-facing anatomy. | Current source and tests | Verified current behavior; no target change |
+
+### Allowed variation
+
+- Item and overflow-indicator content may vary without becoming
+ OverflowList-owned theming targets.
+
+### Representative states
+
+- With no configured count cap, a sufficiently wide list shows every item and
+ no indicator. Width pressure or `maxVisibleItems` may instead collapse a
+ subset; the remaining items and optional indicator stay inside the same
+ targeted list container.
+
+### Transformation and precedence order
+
+- No new measurement, collapse, or rendering order is introduced.
+
+### Performance and resources
+
+- This draft records the existing hidden measurement structure but introduces no
+ new measurement or observer requirement.
+
+## Accessibility contract
+
+This draft does not change or extend the existing hidden measurement container,
+DOM forwarding, or caller-content accessibility behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------ | --------------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| List | Presents the current visible list container. | Current source and public docs | Supporting | FR1 |
+| Items | Present caller-supplied content selected for visible display by width and count limits. | Caller-supplied content | Context-dependent | FR1 |
+| Overflow indicator | Presents caller-rendered access to or a count of collapsed items. | Caller-supplied content | Context-dependent | FR2 |
+
+The hidden measurement copy is implementation plumbing rather than
+consumer-facing anatomy.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "List": {"target": "overflow-list"},
+ "Items": {
+ "none": {
+ "reason": "intentional: Caller-supplied items retain their own theming ownership; OverflowList applies no target to them."
+ }
+ },
+ "Overflow indicator": {
+ "none": {
+ "reason": "intentional: The caller-rendered overflow indicator retains its own theming ownership; OverflowList applies no target to it."
+ }
+ }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification and factual
+ `none` dispositions for caller-owned content.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, FR2 | `OverflowList.test.tsx` fit, cap, and overflow suites | All items visible; count-capped; start/end overflow | Removing visible items or changing capped/width-driven indicator placement fails existing content assertions. | `audit:OverflowList/anatomy` |
+| FR1, FR3 | `OverflowList.test.tsx` rendering-contract suites | Visible and hidden measurement containers | Moving the target from the visible list or exposing measurement content fails assertions. | `audit:OverflowList/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:OverflowList/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, overflow
+measurement mechanics, implementation steps, or system rules. It links to their
+owners.
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 7308a445ef..dbea79cecc 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -1,5 +1,29 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Control',
+ required: true,
+ description: 'Container for the mutually exclusive segment choices.',
+ },
+ {
+ name: 'Segment',
+ required: true,
+ description: 'Individual choice within the control.',
+ },
+ {
+ name: 'Label',
+ required: false,
+ description: 'Visible text identifying a segment when its label is not hidden.',
+ },
+ {
+ name: 'Icon',
+ required: false,
+ description: 'Optional caller-supplied icon shown inside a segment.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -96,6 +120,7 @@ export const docs = {
{name: 'SegmentedControlItem'},
],
usage: {
+ anatomy,
description:
'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
accessibility: [
@@ -167,6 +192,7 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsZh = {
usage: {
+ anatomy,
description:
'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
bestPractices: [
@@ -182,6 +208,7 @@ export const docsZh = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
usage: {
+ anatomy,
description:
'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
bestPractices: [
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.spec.md b/packages/core/src/SegmentedControl/SegmentedControl.spec.md
new file mode 100644
index 0000000000..0f23d0bc83
--- /dev/null
+++ b/packages/core/src/SegmentedControl/SegmentedControl.spec.md
@@ -0,0 +1,151 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:SegmentedControl
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming, accessibility]
+verified_by:
+ [
+ packages/core/src/SegmentedControl/SegmentedControl.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# SegmentedControl component contract
+
+## Intent
+
+SegmentedControl presents a group of mutually exclusive choices through
+SegmentedControlItem children. This draft records the current consumer anatomy
+and theming ownership without changing selection behavior, 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; selection remains controlled by
+ `value` and `onChange`
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The radiogroup control and its current `segmented-control` theming target.
+- SegmentedControlItem's segment button and its current
+ `segmented-control-item` theming target.
+- Rendering optional icon content and a visible label inside a segment.
+
+**Does not own / non-goals**
+
+- The artwork supplied through an item's `icon` prop — owned by the caller.
+- A separate anatomy part or target for selected state; selection is state on the
+ segment target.
+- A visible control-level label; the control's required `label` is its accessible
+ name and is not rendered as visual anatomy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `SegmentedControl.doc.mjs` and `SegmentedControlItem.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The radiogroup container carries the current `segmented-control` target and renders its supplied children. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Each SegmentedControlItem renders one radio button carrying the current `segmented-control-item` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR3 | A visible item label and optional icon render inside the item without separate public targets. | Current source and tests | Verified current behavior; no target change |
+| FR4 | Selected and disabled remain reflected states on `segmented-control-item`, not standalone anatomy or targets. | Current source, docs, and tests | Verified current behavior; no target change |
+
+### Allowed variation
+
+- A segment may render its visible label, an icon and label, or an icon while the
+ required label supplies the accessible name.
+
+### Representative states
+
+- Selected, unselected, disabled, and enabled items retain the same anatomy.
+ Selection and disabled styling vary on the segment target.
+
+### Transformation and precedence order
+
+- No new selection, focus, layout, 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 the existing radiogroup, radio, accessible
+name, roving focus, disabled-message, or selection behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Control | Presents the current grouped choice container. | Current source and public docs | Supporting | FR1 |
+| Segment | Presents one mutually exclusive choice and its item states. | Current source and public docs | Prominent | FR2, FR4 |
+| Label | Identifies a segment visually when not hidden. | Current source and public docs | Prominent | FR3 |
+| Icon | Presents optional caller-supplied artwork within a segment. | Caller-supplied content | Supporting | FR3 |
+
+Selection is a state of Segment, not a separate anatomy part.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Control": {"target": "segmented-control"},
+ "Segment": {"target": "segmented-control-item"},
+ "Label": {"inherits": "segmented-control-item"},
+ "Icon": {"inherits": "segmented-control-item"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, inherited
+ parts, and state-on-target rules.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, FR2 | `SegmentedControl.test.tsx` radiogroup and rendering suites | Control with multiple segment items | Removing the group or item semantics fails existing role and content assertions. | `audit:SegmentedControl/anatomy` |
+| FR3 | `SegmentedControl.test.tsx` label and icon suites | Visible label, icon with label, icon-only item | Removing or changing current label/icon rendering fails existing DOM assertions. | `audit:SegmentedControl/anatomy` |
+| FR4 | `SegmentedControl.test.tsx` selection and disabled suites | Selected, unselected, and disabled items | Breaking reflected item state fails current ARIA, class, or data-attribute assertions. | `audit:SegmentedControl/theming` |
+| Target inventory | `packages/core/src/theme/themingTargets.test.ts` | Control and item targets | Runtime and documented target metadata drift fails target validation. | `audit:SegmentedControl/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:SegmentedControl/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+selection, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, selection or focus
+mechanics, implementation steps, or system rules. It links to their owners.
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index bd140d60b7..a15db3b097 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/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: [
diff --git a/packages/core/src/Stack/Stack.spec.md b/packages/core/src/Stack/Stack.spec.md
new file mode 100644
index 0000000000..7106bdc6a7
--- /dev/null
+++ b/packages/core/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.
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index 6b924b1af0..e300ede1f3 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/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: [
diff --git a/packages/core/src/StatusDot/StatusDot.spec.md b/packages/core/src/StatusDot/StatusDot.spec.md
new file mode 100644
index 0000000000..2fedd84419
--- /dev/null
+++ b/packages/core/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.