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.mjsindex 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.mdnew file mode 100644index 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.mjsindex 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.mdnew file mode 100644index 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.mjsindex 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.mdnew file mode 100644index 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.mjsindex 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.mdnew file mode 100644index 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.