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