Skip to content

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

TypeScript

docs(core): record CommandPalette and TreeList anatomy (#5748)

Cindy Zhang1e29ea2d4775
diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
index 4285798419..36328f3bef 100644
--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
@@ -1,5 +1,74 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Dialog',
+ required: true,
+ description: 'Modal surface that contains the command palette.',
+ },
+ {
+ name: 'Input',
+ required: true,
+ description:
+ 'Search region containing the query field and its supporting visuals.',
+ },
+ {
+ name: 'Search glyph',
+ required: true,
+ description: 'Search symbol rendered by Icon in the default Input.',
+ },
+ {
+ name: 'Query field',
+ required: true,
+ description: 'Native text field used to enter a search query.',
+ },
+ {
+ name: 'Loading spinner',
+ required: false,
+ description:
+ 'Spinner shown in the default Input while a search is pending.',
+ },
+ {
+ name: 'List',
+ required: true,
+ description:
+ 'Scrollable listbox containing the current results or Empty state.',
+ },
+ {
+ name: 'Item',
+ required: false,
+ description: 'Selectable command result rendered inside the List.',
+ },
+ {
+ name: 'Group',
+ required: false,
+ description: 'Optional collection of Items that share a heading.',
+ },
+ {
+ name: 'Group heading',
+ required: false,
+ description: 'Visible heading rendered for a Group.',
+ },
+ {
+ name: 'Empty',
+ required: false,
+ description: 'Message shown when the current result set is empty.',
+ },
+ {
+ name: 'Footer',
+ required: false,
+ description:
+ 'Footer region for default keyboard guidance or caller-provided content.',
+ },
+ {
+ name: 'Keyboard shortcut',
+ required: false,
+ description:
+ 'Painted key badges rendered by Kbd in the default Footer guidance.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'CommandPalette',
@@ -152,6 +221,7 @@ export const docs = {
],
},
usage: {
+ anatomy,
description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
bestPractices: [
{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
@@ -165,6 +235,7 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsZh = {
usage: {
+ anatomy,
description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
bestPractices: [
{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
@@ -180,6 +251,7 @@ export const docsDense = {
description:
'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',
usage: {
+ anatomy,
description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
bestPractices: [
{ guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
diff --git a/packages/core/src/CommandPalette/CommandPalette.spec.md b/packages/core/src/CommandPalette/CommandPalette.spec.md
new file mode 100644
index 0000000000..f4cdcd8906
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPalette.spec.md
@@ -0,0 +1,223 @@
+---
+schema_version: 1
+template_version: 2
+kind: component
+id: component:CommandPalette
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/CommandPalette/CommandPalette.test.tsx,
+ packages/core/src/CommandPalette/CommandPaletteInput.test.tsx,
+ packages/core/src/CommandPalette/CommandPaletteList.test.tsx,
+ packages/core/src/CommandPalette/CommandPaletteItem.test.tsx,
+ packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx,
+ packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# CommandPalette component contract
+
+## Intent
+
+CommandPalette presents searchable commands inside a Dialog. This draft records
+its current aggregate consumer anatomy, target ownership, and delegated stable
+parts 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**
+
+- Search orchestration and the current Input, List, Item, Group, Group heading,
+ Empty, and Footer parts and targets.
+- The native Query field rendered inside the default Input.
+
+**Does not own / non-goals**
+
+- Dialog's surface, Icon's glyph, Spinner's loading indicator, or Kbd's shortcut
+ badges — owned by their respective components.
+- Caller-provided replacement Input, Footer, item content, or trailing input
+ content — owned by the product callsite.
+- A `command-palette` root target — no such current target exists, and this
+ factual backfill does not invent one.
+- Shared layer hosting, positioning, or lifecycle rules beyond the current
+ records linked below.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, and usage remain
+documented in `CommandPalette.doc.mjs` and its subcomponent docs.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current default render places Input and Footer around a List inside a delegated Dialog; the List contains Items, optional Groups and Group headings, or Empty according to the current results. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists. | Current source and target docs | Verified current inventory; focused placement coverage is partial |
+| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog. | Current source and component docs | Verified current composition; no ownership change |
+| FR4 | Query field is a distinct native text field inside Input and currently has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs | Verified current reachability; long-term theming intent remains unsettled |
+
+### Allowed variation
+
+- **AV1 — Results.** Item count, grouping, selected content, and empty state may
+ vary without changing the aggregate anatomy.
+- **AV2 — Slots.** Caller-provided Input and Footer content may replace the
+ defaults without becoming CommandPalette-owned subparts.
+- **AV3 — Delegated rendering.** Dialog, Icon, Spinner, and Kbd may change their
+ internal element shape while preserving their own public contracts.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------------- | ------------------------------------------------------- | ----------------------------------------------- |
+| Ungrouped results | List contains Item instances. | Item count and caller-rendered content. |
+| Grouped results | List contains Group, Group heading, and Item instances. | Group names, count, ordering, and item content. |
+| Empty bootstrap/search | List contains Empty instead of Items. | Caller-provided empty content. |
+| Pending search | Default Input may contain Loading spinner. | Spinner is absent when no search is pending. |
+| Default slots | Input and Footer render their documented defaults. | Footer shortcut text and translated labels. |
+| Caller-replaced slots | The slot content replaces the corresponding default. | Replacement structure remains caller-owned. |
+
+### Transformation and precedence order
+
+- No new search, selection, 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 CommandPalette's current Dialog, combobox,
+listbox, option, announcement, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ----------------- | ----------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Dialog | Presents the containing modal surface. | `component:Dialog` | Supporting | FR1, FR3 |
+| Input | Paints the search region around the query field and supporting visuals. | Current source and public docs | Prominent | FR1, FR2, FR4 |
+| Search glyph | Presents the search symbol in the default Input. | `component:Icon` | Supporting | FR3 |
+| Query field | Accepts the native text query inside Input. | Current source and public docs | Prominent | FR1, FR4 |
+| Loading spinner | Indicates a pending search in the default Input. | `component:Spinner` | Supporting | FR3 |
+| List | Presents the current result collection or Empty state. | Current source and public docs | Supporting | FR1, FR2 |
+| Item | Presents one selectable command result. | Current source and public docs | Prominent | FR1, FR2 |
+| Group | Arranges related Items together. | Current source and public docs | Supporting | FR1, FR2 |
+| Group heading | Labels one Group visually. | Current source and public docs | Supporting | FR1, FR2 |
+| Empty | Presents the no-results or no-query message. | Current source and public docs | Prominent | FR1, FR2 |
+| Footer | Presents default guidance or caller-provided footer content. | Current source and public docs | Supporting | FR1, FR2 |
+| Keyboard shortcut | Presents one shortcut as painted key badges in the default Footer. | `component:Kbd` | Supporting | FR3 |
+
+The native Query field is separate from the Input region that carries
+`command-palette-input`. Its current lack of a direct target is observed
+reachability, not a decision that it must remain unthemeable.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Dialog": {
+ "delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
+ },
+ "Input": {"target": "command-palette-input"},
+ "Search glyph": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Query field": {
+ "none": {
+ "reason": "No current public target is applied directly to the native query field"
+ }
+ },
+ "Loading spinner": {
+ "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+ },
+ "List": {"target": "command-palette-list"},
+ "Item": {"target": "command-palette-item"},
+ "Group": {"target": "command-palette-group"},
+ "Group heading": {"target": "command-palette-group-heading"},
+ "Empty": {"target": "command-palette-empty"},
+ "Footer": {"target": "command-palette-footer"},
+ "Keyboard shortcut": {
+ "delegatesTo": {"owner": "component:Kbd", "target": "kbd"}
+ }
+}
+```
+
+The seven local targets are current public seams. The delegated parts retain
+their existing component owners. The Query field `none` disposition records a
+current audit gap and does not authorize a new target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, delegation, and factual `none` dispositions.
+- `architecture:public-component-api` owns the stable props and composition
+ surface; this documentation adds no API.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+ this draft does not redefine focus ownership or input behavior.
+- `family:overlay-dismissal` identifies CommandPalette as a current member and
+ records its component-local Escape handling as an adoption gap.
+- No layer-runtime record is linked because no current record with that scope is
+ present in this checkout.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1 | CommandPalette root and subcomponent render suites plus source inspection | Default, grouped, empty, pending, and replaced slots | Removing the asserted Dialog, Query field, List, Item, Group, Group heading, Empty, or Footer content fails existing role, content, or slot assertions; Search glyph, Loading spinner, and Keyboard shortcut presence remain source-inspected only. | `audit:CommandPalette/anatomy` |
+| FR2 | Source inspection, `themingTargets.test.ts`, and `CommandPaletteGroup.test.tsx` | Seven local targets; Group and Group heading placement | Removing a current target fails the global inventory; moving Group or Group heading fails focused class assertions. | `audit:CommandPalette/theming` |
+| FR3 | Source inspection plus Dialog, Icon, Spinner, and Kbd public target metadata | Default surface, Input visuals, and Footer shortcuts | Existing focused tests do not assert the composed Icon, Spinner, or Kbd instances; changing delegated ownership requires this map and the delegated component metadata to change. | `audit:CommandPalette/theming` |
+| FR4 | `CommandPaletteInput.test.tsx` and source inspection | Native query field with idle and pending Input | Removing the field fails combobox tests; adding a field target requires an explicit map update. | `audit:CommandPalette/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and seven current local targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:CommandPalette/theming` |
+
+Focused target-placement assertions currently cover Group and Group heading.
+Input, List, Item, Empty, and Footer placement rely on source inspection plus the
+global target inventory. Existing tests assert default Footer text and pending
+announcements, but do not assert that Icon, Spinner, or Kbd renders.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layer, API, or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Query field gain a stable public theming target?** (`human-api`)
+ Its current lack of direct reachability is an audit gap, not settled intent.
+- **OQ2 — Should focused tests pin the default Search glyph, pending Loading
+ spinner, and default Footer Keyboard shortcuts?** (`checkable`) Their presence
+ is currently source-inspected rather than asserted.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, shared layer or
+modality rules, current audit results, or implementation steps. It links to
+their owners.
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index ad62615b91..dd6c91c835 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -1,5 +1,60 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Tree list',
+ required: true,
+ description: 'Container that presents the hierarchical tree.',
+ },
+ {
+ name: 'Header',
+ required: false,
+ description: 'Caller-provided content that visibly names the tree.',
+ },
+ {
+ name: 'Item',
+ required: true,
+ description: 'Painted row for one node in the hierarchy.',
+ },
+ {
+ name: 'Chevron',
+ required: false,
+ description:
+ 'Expand and collapse control rendered for an Item with children.',
+ },
+ {
+ name: 'Chevron glyph',
+ required: false,
+ description: 'Directional symbol rendered by Icon inside a Chevron.',
+ },
+ {
+ name: 'Item label',
+ required: true,
+ description: 'Primary content that identifies an Item.',
+ },
+ {
+ name: 'Item description',
+ required: false,
+ description: 'Secondary text rendered below an Item label.',
+ },
+ {
+ name: 'Start content',
+ required: false,
+ description: 'Caller-provided content rendered before an Item label.',
+ },
+ {
+ name: 'End content',
+ required: false,
+ description: 'Caller-provided content rendered after an Item label.',
+ },
+ {
+ name: 'Guide',
+ required: false,
+ description: 'Connector line that shows parent-child relationships.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -79,6 +134,7 @@ export const docs = {
},
],
usage: {
+ anatomy,
description:
'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
bestPractices: [
@@ -158,6 +214,7 @@ export const docsZh = {
},
],
usage: {
+ anatomy,
description:
'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
bestPractices: [
@@ -175,6 +232,7 @@ export const docsDense = {
description:
'Data-driven tree list for hierarchical data w/ expand/collapse, branch lines, interactive items. Flat items array w/ recursive children, no composition, no cloneElement.',
usage: {
+ anatomy,
description:
'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
bestPractices: [
diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.md
new file mode 100644
index 0000000000..92e83d32c1
--- /dev/null
+++ b/packages/core/src/TreeList/TreeList.spec.md
@@ -0,0 +1,220 @@
+---
+schema_version: 1
+template_version: 2
+kind: component
+id: component:TreeList
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/TreeList/TreeList.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# TreeList component contract
+
+## Intent
+
+TreeList presents hierarchical data as expandable tree rows. This draft records
+its current consumer anatomy, target ownership, delegated Icon glyph, and
+unreached stable parts 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 Tree list, Item, Chevron, Item label, and Guide parts and their five current
+ targets.
+- The stable Item description rendered below an Item label.
+- Hierarchical placement, indentation, expansion, selection, and tree semantics.
+
+**Does not own / non-goals**
+
+- The Chevron glyph artwork and Icon target — owned by `component:Icon`.
+- Header, Start content, and End content supplied through consumer slots — owned
+ by the product callsite.
+- New targets for Item description or caller-provided slots — unresolved by this
+ factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer data, props, slots, and usage
+remain documented in `TreeList.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below. | Current source and target docs | Verified current inventory; focused placement coverage is partial |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target. | Current source and component docs | Verified current ownership; no target change |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content. | Current source and target docs | Verified current reachability; long-term theming intent remains unsettled |
+
+### Allowed variation
+
+- **AV1 — Hierarchy.** Item count, depth, expansion, selection, density, and guide
+ visibility may vary without changing the anatomy ownership recorded here.
+- **AV2 — Consumer content.** Header, Start content, End content, Item label
+ values, and descriptions may vary without making caller-owned slot content a
+ TreeList target.
+- **AV3 — Delegated glyph.** Icon may change the Chevron glyph's internal element
+ shape while preserving its own public contract.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------ | ----------------------------------------------------- | --------------------------------------------- |
+| Empty tree | Tree list remains; no Item instances render. | Optional Header content. |
+| Flat items | Each Item contains an Item label. | Description and consumer slots may be absent. |
+| Expandable item | Item may contain Chevron and delegated Chevron glyph. | Expanded or collapsed state. |
+| Nested `lineGuides` tree | Guide instances show parent-child relationships. | Count and position follow hierarchy. |
+| `noGuides` tree | Guide instances are absent; indentation remains. | All other anatomy remains unchanged. |
+| Described item | Item description renders below Item label. | Caller-provided description text. |
+
+### Transformation and precedence order
+
+- No new hierarchy, focus, expansion, 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 TreeList's current tree, treeitem, group,
+roving-focus, expansion, selection, disabled, or activation behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Tree list | Groups the hierarchical tree and owns its density and guide variant. | Current source and public docs | Supporting | FR1, FR2 |
+| Header | Visibly names the tree with caller-provided content. | Caller-supplied content | Prominent | FR1, FR3 |
+| Item | Paints one row and reflects density, selection, and disabled state. | Current source and public docs | Prominent | FR1, FR2 |
+| Chevron | Provides the expand and collapse control for an Item with children. | Current source and public docs | Supporting | FR1, FR2 |
+| Chevron glyph | Presents the current directional symbol inside Chevron. | `component:Icon` | Supporting | FR1, FR3 |
+| Item label | Presents the primary content that identifies an Item. | Current source and public docs | Prominent | FR1, FR2 |
+| Item description | Presents stable secondary text below Item label. | Current source and public docs | Supporting | FR1, FR4 |
+| Start content | Presents caller-provided content before Item label. | Caller-supplied content | Context-dependent | FR1, FR3 |
+| End content | Presents caller-provided content after Item label. | Caller-supplied content | Context-dependent | FR1, FR3 |
+| Guide | Paints a connector between related hierarchy levels. | Current source and public docs | Supporting | FR1, FR2 |
+
+Item description is stable TreeList-rendered anatomy, not consumer-owned slot
+structure. Its current lack of a target is observed reachability, not a decision
+that it must remain unthemeable. Header, Start content, and End content remain
+caller-owned even though TreeList positions their slot wrappers.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Tree list": {"target": "tree-list"},
+ "Header": {
+ "none": {
+ "reason": "TreeList applies no public target to caller-provided Header content"
+ }
+ },
+ "Item": {"target": "tree-list-item"},
+ "Chevron": {"target": "tree-list-chevron"},
+ "Chevron glyph": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Item label": {"target": "tree-list-item-label"},
+ "Item description": {
+ "none": {
+ "reason": "No current public target is applied to the stable Item description"
+ }
+ },
+ "Start content": {
+ "none": {
+ "reason": "TreeList applies no public target to caller-provided Start content"
+ }
+ },
+ "End content": {
+ "none": {
+ "reason": "TreeList applies no public target to caller-provided End content"
+ }
+ },
+ "Guide": {"target": "tree-list-guide"}
+}
+```
+
+The five local targets are current public seams. The Chevron glyph retains Icon
+ownership. Consumer-slot `none` dispositions are ownership boundaries; Item
+description's `none` disposition records a current audit gap and does not
+authorize a new target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, delegation, and factual `none` dispositions.
+- `architecture:public-component-api` owns the stable data, props, and slot
+ surface; this documentation adds no API.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+ TreeList continues to own its existing tree focus and activation behavior.
+- TreeList has no current family contract, and no unresolved family or runtime
+ record identifier is included.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
+| FR2 | `TreeList.test.tsx` and `themingTargets.test.ts` | Five local targets and their documented states | Removing or moving any current local target fails focused class assertions or the global inventory. | `audit:TreeList/theming` |
+| FR3 | Source inspection plus Icon public target metadata | Expandable rows and caller-provided slots | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change. | `audit:TreeList/theming` |
+| FR4 | `TreeList.test.tsx` description rendering test and source inspection | Item with description | Removing description fails content coverage; adding a target requires an explicit map update. | `audit:TreeList/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and five current local targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:TreeList/theming` |
+
+Focused target-placement assertions cover all five local targets: Tree list,
+Item, Chevron, Item label, and Guide. Existing tests do not assert the Icon
+instance that renders Chevron glyph.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, behavior, or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Item description gain a stable public theming target?**
+ (`human-api`) Its current lack of reachability is an audit gap, not settled
+ intent.
+- **OQ2 — Should a focused test pin the delegated Chevron glyph's Icon
+ instance?** (`checkable`) Its presence is currently source-inspected rather
+ than asserted.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, shared modality
+rules, current audit results, or implementation steps. It links to their owners.