Skip to content

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

TypeScript

docs(core): record anatomy for Kbd Divider and Outline (#5746)

Cindy Zhangd93c5479fa5e
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
index ebd4c8cf3e..8e2adf5473 100644
--- a/packages/core/src/Divider/Divider.doc.mjs
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -1,5 +1,26 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Divider group',
+ required: true,
+ description:
+ 'Separator group that arranges one or two rules around an optional label.',
+ },
+ {
+ name: 'Rule',
+ required: true,
+ description:
+ 'Painted line segment; a second segment renders when a label is present.',
+ },
+ {
+ name: 'Label',
+ required: false,
+ description: 'Optional content displayed between two rule segments.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
@@ -47,6 +68,7 @@ export const docs = {
],
},
usage: {
+ anatomy,
description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
bestPractices: [
{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
@@ -97,6 +119,7 @@ export const docsZh = {
],
},
usage: {
+ anatomy,
description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
bestPractices: [
{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
@@ -110,6 +133,7 @@ export const docsZh = {
export const docsDense = {
description: 'visual separator w/ optional label, using Astryx design tokens',
usage: {
+ anatomy,
description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
bestPractices: [
{ guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
diff --git a/packages/core/src/Divider/Divider.spec.md b/packages/core/src/Divider/Divider.spec.md
new file mode 100644
index 0000000000..1f310f0453
--- /dev/null
+++ b/packages/core/src/Divider/Divider.spec.md
@@ -0,0 +1,150 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Divider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+ [packages/core/src/Divider/Divider.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Divider component contract
+
+## Intent
+
+Divider presents a separator group as one rule, or as two rules around an
+optional label. This draft records current consumer anatomy and theming
+reachability 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, 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 separator group, its current `divider` target, the painted rule segments,
+ and the optional label placement.
+
+**Does not own / non-goals**
+
+- The meaning of the content regions separated by the divider — owned by the
+ product callsite.
+- Whether Rule or Label should gain public targets — unresolved by this factual
+ backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Divider.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one rule without a label and two rules with the optional label between them. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The divider group carries the current `divider` target; Rule and Label currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+
+### Allowed variation
+
+- Orientation, visual weight, full-bleed layout, and label content may vary
+ without changing the three-part anatomy recorded here.
+
+### Representative states
+
+- Unlabelled horizontal and vertical dividers render one Rule.
+- Labelled horizontal and vertical dividers render Label between two instances
+ of Rule.
+
+### Transformation and precedence order
+
+- No new 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 Divider's existing separator naming or
+orientation behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Divider group | Arranges the separator's rule segments and optional label. | Current source and public docs | Supporting | FR1, FR2 |
+| Rule | Paints the separator line in the selected orientation and weight. | Current source and public docs | Supporting | FR1, FR2 |
+| Label | Presents optional content between two rule segments. | Current source and public docs | Prominent | FR1, FR2 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Divider group": {"target": "divider"},
+ "Rule": {
+ "none": {
+ "reason": "unsettled: No current public target reaches this part"
+ }
+ },
+ "Label": {
+ "none": {
+ "reason": "unsettled: No current public target reaches this part"
+ }
+ }
+}
+```
+
+The two `none` dispositions record current reachability while target exposure
+remains unsettled. They do not decide that Rule or Label should remain without
+public targets.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, and the difference between factual reachability and intended public
+ theming API.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1 | `Divider.test.tsx` structure and label suites | Labelled and unlabelled; both axes | Removing or reordering Rule or Label instances fails existing child-count and content assertions. | `audit:Divider/anatomy` |
+| FR2 | Source inspection and current target inventories | Group, Rule, and Label | Adding or documenting a current target without updating the anatomy map fails repository checks. | `audit:Divider/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:Divider/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Rule or Label gain stable public theming targets?** (`human-api`)
+ Their target exposure is unsettled; the current lack of reachability does not
+ decide the answer.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.
diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjs
index 992e7cdbcd..b3492bad23 100644
--- a/packages/core/src/Kbd/Kbd.doc.mjs
+++ b/packages/core/src/Kbd/Kbd.doc.mjs
@@ -1,5 +1,20 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Shortcut',
+ required: true,
+ description:
+ 'Group that presents the complete keyboard shortcut and its accessible name.',
+ },
+ {
+ name: 'Key badge',
+ required: true,
+ description: 'Painted key badge rendered once for each key in the shortcut.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -38,6 +53,7 @@ export const docs = {
targets: [{className: 'astryx-kbd'}],
},
usage: {
+ anatomy,
description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
{ guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },
@@ -82,6 +98,7 @@ export const docsZh = {
targets: [{className: 'astryx-kbd'}],
},
usage: {
+ anatomy,
description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
{ guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },
@@ -96,6 +113,7 @@ export const docsDense = {
description:
'Renders keyboard shortcut as styled key badges. Use in tooltips, menus + help text to show key combinations.',
usage: {
+ anatomy,
description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
bestPractices: [
{ guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },
diff --git a/packages/core/src/Kbd/Kbd.spec.md b/packages/core/src/Kbd/Kbd.spec.md
new file mode 100644
index 0000000000..fd7692dd35
--- /dev/null
+++ b/packages/core/src/Kbd/Kbd.spec.md
@@ -0,0 +1,141 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Kbd
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by: [packages/core/src/Kbd/Kbd.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Kbd component contract
+
+## Intent
+
+Kbd presents a keyboard shortcut as one or more painted key badges. This draft
+records current consumer anatomy and theming reachability 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, 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 shortcut group, its current `kbd` target, and the painted key badges it
+ renders from the supplied shortcut string.
+
+**Does not own / non-goals**
+
+- The action associated with the shortcut or how the shortcut is discovered —
+ owned by the product callsite.
+- Whether an individual key badge should gain a public target — unresolved by
+ this factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Kbd.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+
+### Allowed variation
+
+- Platform-specific key text and caller-supplied shortcut combinations may vary
+ without changing the two-part anatomy recorded here.
+
+### Representative states
+
+- The same anatomy applies to single-key, multi-key, modifier, and
+ platform-resolved shortcuts.
+
+### Transformation and precedence order
+
+- No new parsing, 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 Kbd's existing accessible-name behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
+| Shortcut | Groups the complete shortcut and carries its accessible name. | Current source and public docs | Supporting | FR1, FR2 |
+| Key badge | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent | FR1, FR2 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Shortcut": {"target": "kbd"},
+ "Key badge": {
+ "none": {
+ "reason": "unsettled: No current public target reaches this part"
+ }
+ }
+}
+```
+
+The `none` disposition records current reachability while target exposure remains
+unsettled. It does not decide that key badges should remain without a public
+target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, and the difference between factual reachability and intended public
+ theming API.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------- |
+| FR1 | `Kbd.test.tsx` key rendering suites | Single-key and multi-key output | Removing the group or a parsed badge fails existing role, element, or text assertions. | `audit:Kbd/anatomy` |
+| FR2 | Source inspection and current target inventories | Root target and child badges | Adding or documenting a current target without updating the anatomy map fails repository checks. | `audit:Kbd/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:Kbd/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should each Key badge gain a stable public theming target?**
+ (`human-api`) Target exposure is unsettled; the current lack of reachability
+ does not decide the answer.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.
diff --git a/packages/core/src/Outline/Outline.doc.mjs b/packages/core/src/Outline/Outline.doc.mjs
index 96c59ac80e..af78622cf5 100644
--- a/packages/core/src/Outline/Outline.doc.mjs
+++ b/packages/core/src/Outline/Outline.doc.mjs
@@ -1,5 +1,37 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Outline',
+ required: true,
+ description:
+ 'Navigation container for the same-page heading links and indicator.',
+ },
+ {
+ name: 'Heading link',
+ required: true,
+ description:
+ 'Anchor for one heading, indented by level and marked when active.',
+ },
+ {
+ name: 'Label',
+ required: true,
+ description: 'Heading text displayed inside its heading link.',
+ },
+ {
+ name: 'Indicator track',
+ required: true,
+ description: 'Painted vertical rule behind the active indicator.',
+ },
+ {
+ name: 'Active indicator',
+ required: true,
+ description:
+ 'Sliding bar positioned beside the currently active heading link.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -222,6 +254,7 @@ function FlashOnArrival() {
},
],
usage: {
+ anatomy,
description:
'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes. Features a sliding indicator track that animates to the active heading. The list is a single tab stop: arrow keys move between headings, Home/End jump to the ends, and Enter/Space activate.',
bestPractices: [
@@ -323,6 +356,7 @@ export const docsZh = {
},
],
usage: {
+ anatomy,
description:
'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
bestPractices: [
@@ -341,6 +375,7 @@ export const docsDense = {
description:
'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',
usage: {
+ anatomy,
description:
'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
bestPractices: [
diff --git a/packages/core/src/Outline/Outline.spec.md b/packages/core/src/Outline/Outline.spec.md
new file mode 100644
index 0000000000..864e20fb3f
--- /dev/null
+++ b/packages/core/src/Outline/Outline.spec.md
@@ -0,0 +1,161 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Outline
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+ [packages/core/src/Outline/Outline.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Outline component contract
+
+## Intent
+
+Outline presents same-page heading navigation with heading links, labels, a
+vertical indicator track, and a sliding active indicator. This draft records
+current consumer anatomy and theming reachability 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, aliases, 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 outline navigation container and its current `outline` target.
+- The heading links and their current `outline-item` target.
+- The active indicator and its current `outline-indicator` target.
+- The label and indicator-track elements rendered inside that structure.
+
+**Does not own / non-goals**
+
+- The destination headings or their content — owned by the document or product
+ callsite.
+- Whether the Indicator track should gain a public target — unresolved by this
+ factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Outline.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| FR1 | The current render contains one Outline, one Heading link and Label per item, one Indicator track, and one Active indicator. | Current source and docs; existing link/marker tests | Verified by source; Label-wrapper and Indicator-track identity lack exact assertions |
+| FR2 | Outline, Heading link, and Active indicator carry `outline`, `outline-item`, and `outline-indicator`; Label inherits from `outline-item`. | Current source and target docs; current target tests | Current target facts verified; Label inheritance remains source-inspected |
+| FR3 | Indicator track currently carries no public target. | Current source and target docs | Verified current behavior; theming intent unsettled |
+
+### Allowed variation
+
+- Heading count, labels, levels, density, and active item may vary without
+ changing the five-part anatomy recorded here.
+
+### Representative states
+
+- Controlled and uncontrolled active state use the same anatomy and current
+ targets.
+- Default and compact density use the same anatomy and current targets.
+- An empty items array still renders Outline, Indicator track, and Active
+ indicator; it renders no Heading link or Label instances.
+
+### Transformation and precedence order
+
+- No new navigation, active-state, 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 Outline's existing navigation, link,
+current-item, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Outline | Groups same-page heading navigation and the indicator presentation. | Current source and public docs | Supporting | FR1, FR2 |
+| Heading link | Navigates to one heading and carries level and active state. | Current source and public docs | Prominent | FR1, FR2 |
+| Label | Presents heading text inside its Heading link. | Current source and public docs | Prominent | FR1, FR2 |
+| Indicator track | Paints the vertical rule behind the active marker. | Current source and public docs | Supporting | FR1, FR3 |
+| Active indicator | Paints the marker aligned to the current Heading link. | Current source and public docs | Supporting | FR1, FR2 |
+
+The Label sits inside the `outline-item` target and receives the link's
+inherited text treatment. Its own StyleX rules only manage truncation. The
+Indicator track's target exposure remains unsettled; its current lack of a
+target does not decide that the part must remain unthemeable.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Outline": {"target": "outline"},
+ "Heading link": {"target": "outline-item"},
+ "Label": {"inherits": "outline-item"},
+ "Indicator track": {
+ "none": {
+ "reason": "unsettled: No current public target reaches this part"
+ }
+ },
+ "Active indicator": {"target": "outline-indicator"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, inherited-part treatment, and explicit unsettled dispositions.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1 | Source inspection plus existing link/indicator suites | Populated and active outlines | Heading links and the active indicator have regression assertions; Label-wrapper and Indicator-track identity remain source-inspected without exact regression assertions. | `audit:Outline/anatomy` |
+| FR2 | `Outline.test.tsx` stable-target and active-state suites | Root, heading link, active indicator | Removing or renaming a current target fails existing class assertions or target inventories. | `audit:Outline/theming` |
+| FR3 | Source inspection and current target inventories | Indicator track | Adding or documenting a current track target without updating the map fails repository checks. | `audit:Outline/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:Outline/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Indicator track gain a stable public theming target?**
+ (`human-api`) Target exposure is unsettled; the current lack of reachability
+ does not decide the answer.
+- **OQ2 — Add exact regression assertions for the Label wrapper and Indicator
+ track identity.** (`checkable`) Current evidence for those two parts is source
+ inspection rather than a uniquely identifying test assertion.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.