@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/src/Toolbar/Toolbar.spec.md

@@ -0,0 +1,173 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Toolbar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Toolbar/Toolbar.test.tsx,
+    packages/core/src/Section/Section.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:container-padding,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Toolbar component contract
+
+## Intent
+
+Toolbar presents a named contextual action region with one semantic toolbar row
+inside Section-owned outer chrome. This draft records the current consumer
+anatomy and theming ownership without changing layout, keyboard 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: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The named toolbar row, toolbar semantics, start/optional-center/end layout,
+  keyboard movement, size cascade, and current `toolbar` target.
+
+**Does not own / non-goals**
+
+- The painted outer chrome, variant, block padding, and selected divider edges —
+  delegated to `component:Section`.
+- Content supplied through the three layout slots — owned by the caller or its
+  rendered components.
+- A general arbitrary-child layout primitive contract.
+- New runtime behavior, targets, props, or target placement.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, and usage remain
+documented in `Toolbar.doc.mjs`; `family:layout-regions` owns the shared
+structural-region boundary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                              | Basis                                      | Draft review state                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------- |
+| FR1 | The current render contains Section-owned Outer chrome around one named Toolbar carrying `role="toolbar"` and the current `toolbar` target.                      | Current source, docs, tests, and family    | Verified current behavior; no new behavior decided |
+| FR2 | The Toolbar uses its current two-lane layout without center content and its current three-lane layout when center content is supplied.                           | Current source and focused structure tests | Verified current behavior; no layout change        |
+| FR3 | Variant, selected divider edges, and outer padding remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout. | Current source, docs, and family contract  | Verified current ownership; no target change       |
+
+### Allowed variation
+
+- Caller content may be absent or supplied in the start, center, and end slots
+  without changing Outer chrome or Toolbar ownership.
+- Size and orientation may change the current row geometry and keyboard axis
+  without creating separate anatomy parts or targets.
+
+### Representative states
+
+| State             | Required invariant                                      | Allowed variation                                   |
+| ----------------- | ------------------------------------------------------- | --------------------------------------------------- |
+| Empty toolbar     | Outer chrome and named Toolbar remain rendered.         | No caller slot content.                             |
+| Two-lane layout   | Start and/or end content use the current flex layout.   | Either lane may be absent.                          |
+| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent.                 |
+| Vertical toolbar  | Toolbar semantics and target remain unchanged.          | Layout and keyboard movement use the vertical axis. |
+
+### Transformation and precedence order
+
+- No new slot, layout, edge-compensation, padding, or event precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Toolbar's current accessible name,
+orientation, roving-tabindex, keyboard-hint, caret-guard, or event-composition
+behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                               | Representation authority                  | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
+| Outer chrome     | Supplies the painted surface, padding, and selected boundaries around the row.   | `component:Section`                       | Supporting     | FR1, FR3           |
+| Toolbar          | Presents the named toolbar semantics and current two- or three-lane arrangement. | Current source, docs, and family contract | Prominent      | FR1, FR2, FR3      |
+
+The slot contents are caller-owned content inside Toolbar's layout. They do not
+become additional Toolbar-owned anatomy or targets.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Outer chrome": {
+    "delegatesTo": {"owner": "component:Section", "target": "section"}
+  },
+  "Toolbar": {"target": "toolbar"}
+}
+```
+
+## Family and system relationships
+
+- `family:layout-regions` owns the structural-region vocabulary and records
+  Toolbar as a Section-backed contextual action region.
+- `architecture:container-padding` owns the inherited inset and edge-compensation
+  geometry used by the composed Section and Toolbar.
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, and component delegation.
+- `architecture:public-component-api` owns the stable prop and slot surface; this
+  documentation adds no API.
+
+## Verification map
+
+| Contract            | Verification                                                    | Representative states                          | Mutation or failure expectation                                                                                      | Audit section           |
+| ------------------- | --------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `Toolbar.test.tsx` role, name, pass-through, and Section suites | Empty and populated Toolbar                    | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence.     | `audit:Toolbar/anatomy` |
+| FR2                 | `Toolbar.test.tsx` slot and child-count suites                  | Start-only, end-only, two-lane, and three-lane | Changing current slot presence or two-/three-lane structure fails focused assertions.                                | `audit:Toolbar/layout`  |
+| FR3                 | Toolbar and Section source plus their focused tests             | Variant, divider, size, and orientation states | Moving outer chrome ownership into Toolbar or moving toolbar semantics onto Section contradicts source and coverage. | `audit:Toolbar/theming` |
+| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                | Toolbar and delegated Section targets          | Runtime and documented target metadata drift fails target validation.                                                | `audit:Toolbar/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                   | Canonical anatomy and current local target     | Missing, extra, prefixed, or stale mappings fail repository validation.                                              | `audit:Toolbar/theming` |
+
+Existing tests assert the semantic row, slot structure, and Section composition.
+They do not prove computed inset or edge-compensation geometry for every parent
+padding state; this documentation does not claim that coverage.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, container-padding mechanics, keyboard algorithms, implementation steps,
+or system rules. It links to their owners.

package/src/Tooltip/Tooltip.doc.mjs

@@ -1,5 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Tooltip surface',
+    required: true,
+    description: 'Painted overlay surface that presents the tooltip.',
+  },
+  {
+    name: 'Tooltip text',
+    required: true,
+    description: 'Tooltip content rendered within the surface.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -110,6 +124,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
@@ -217,6 +232,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [
@@ -233,6 +249,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
   usage: {
+    anatomy,
     description:
       'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
     bestPractices: [

package/src/Tooltip/Tooltip.spec.md

@@ -0,0 +1,141 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Tooltip
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/Tooltip/Tooltip.test.tsx, scripts/check-knowledge.mjs]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:layer-runtime,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Tooltip component contract
+
+## Intent
+
+Tooltip renders supplied tooltip content on an owned overlay surface associated
+with a caller-owned trigger. This draft records current consumer anatomy and
+theming ownership without deciding layer behavior, positioning, or new visual
+parts.
+
+## 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 rendered tooltip surface and content inside that surface.
+
+**Does not own / non-goals**
+
+- The trigger element — supplied by the caller or referenced externally and
+  outside Tooltip's owned anatomy.
+- An arrow element — the current implementation renders none.
+- Layer lifecycle, light dismissal, and anchor-positioning policy — outside this
+  factual anatomy backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Tooltip.doc.mjs` and `useTooltip.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                  | Basis                           | Draft review state                                 |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current rendered tooltip contains one owned surface with the supplied tooltip content inside it. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The surface carries the current `tooltip` target; its content has no separate target.                | Current source and public docs  | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Supplied content may vary without adding a Tooltip-owned child target.
+
+### Representative states
+
+- The owned anatomy is unchanged across wrapped-trigger and external-anchor
+  modes; the trigger remains outside it.
+
+### Transformation and precedence order
+
+- No new ordering or positioning rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Tooltip's existing accessibility behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Tooltip surface  | Presents the current painted overlay surface.       | Current source and public docs | Supporting     | FR1, FR2           |
+| Tooltip text     | Presents supplied content within the owned surface. | Current source and public docs | Prominent      | FR1, FR2           |
+
+The trigger is caller-owned and outside this anatomy. The current implementation
+has no arrow element.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Tooltip surface": {"target": "tooltip"},
+  "Tooltip text": {"inherits": "tooltip"}
+}
+```
+
+## Family and system relationships
+
+This draft references the current shared owners without restating their rules:
+`architecture:component-theming-surface`, `family:overlay-dismissal`,
+`architecture:interaction-modality`, `architecture:layer-runtime`, and
+`architecture:public-component-api`.
+
+## Verification map
+
+| Contract            | Verification                          | Representative states                 | Mutation or failure expectation                                                  | Audit section           |
+| ------------------- | ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`         | Canonical anatomy and current target  | Missing, extra, prefixed, or stale mappings fail repository validation.          | `audit:Tooltip/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or layer-system decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, layer-system rules,
+implementation steps, or system rules. It links to their owners.

package/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: [

package/src/TreeList/TreeList.spec.md

@@ -0,0 +1,220 @@
+---
+schema_version: 1
+template_version: 3
+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": "intentional: Header is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "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": "unsettled: No current public target reaches the stable Item description; future exposure still needs an owner decision"
+    }
+  },
+  "Start content": {
+    "none": {
+      "reason": "intentional: Start content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "End content": {
+    "none": {
+      "reason": "intentional: End content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "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.