@astryxdesign/core 0.5.2-canary.005d975 → 0.5.2-canary.05994f8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.2-canary.005d975",
+  "version": "0.5.2-canary.05994f8",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.2-canary.005d975",
+    "@astryxdesign/cli": "0.5.2-canary.05994f8",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/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.' },

package/src/CommandPalette/CommandPalette.spec.md

@@ -0,0 +1,223 @@
+---
+schema_version: 1
+template_version: 3
+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": "unsettled: No current public target is applied directly to the native query field; future exposure still needs an owner decision"
+    }
+  },
+  "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.

package/src/Layout/Layout.doc.mjs

@@ -1,5 +1,35 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Page shell',
+    required: true,
+    description: 'Outer Layout container that arranges the named page regions.',
+  },
+  {
+    name: 'Header',
+    required: false,
+    description: 'Optional top region for page or application header content.',
+  },
+  {
+    name: 'Panel',
+    required: false,
+    description:
+      'Optional start or end side region; both positions use the same LayoutPanel part.',
+  },
+  {
+    name: 'Content area',
+    required: false,
+    description: 'Optional central region for the page content.',
+  },
+  {
+    name: 'Footer',
+    required: false,
+    description: 'Optional bottom region for page footer content.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -129,6 +159,7 @@ export const docs = {
       { guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },
       { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },
     ],
+    anatomy,
   },
 };
 
@@ -159,5 +190,6 @@ export const docsDense = {
       { guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },
       { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },
     ],
+    anatomy,
   },
 };

package/src/Layout/Layout.spec.md

@@ -0,0 +1,199 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Layout
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Layout/Layout.test.tsx,
+    packages/core/src/Layout/LayoutSlots.test.tsx,
+    packages/core/src/Layout/__tests__/childrenAsContent.test.tsx,
+    packages/core/src/Layout/__tests__/contentWidth.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:container-padding,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Layout component contract
+
+## Intent
+
+Layout provides the page shell that arranges optional Header, Panel, Content
+area, and Footer regions. This draft records the current aggregate consumer
+anatomy and theming ownership without changing runtime behavior, DOM, 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 Page shell and its current `layout` target.
+- The aggregate Header, Panel, Content area, and Footer anatomy and their current
+  `layout-header`, `layout-panel`, `layout-content`, and `layout-footer` targets.
+- One Panel concept for both logical start and end positions.
+
+**Does not own / non-goals**
+
+- Product meaning or content supplied to any region — owned by the caller.
+- Automatic responsive substitution of regions — owned by the caller, AppShell,
+  or another higher-level composition.
+- Resize interaction — owned by useResizable and ResizeHandle.
+- Correcting current container-padding publication mismatches or preventing two
+  adjacent divider owners from both painting; those remain current gaps and
+  caller obligations recorded below.
+- New runtime behavior, API, target, alias, or region wrapper.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, defaults, and usage
+remain documented in `Layout.doc.mjs` and the region subcomponent docs.
+`family:layout-regions` owns the shared region vocabulary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                               | Basis                                     | Draft review state                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------- |
+| FR1 | Layout renders one Page shell carrying the current `layout` target and places each supplied named region according to the existing shell topology.                                                                                | Current source, docs, tests, and family   | Verified current behavior; no new behavior decided |
+| FR2 | Header, Content area, and Footer use their current `layout-header`, `layout-content`, and `layout-footer` targets on the corresponding Layout region components.                                                                  | Current source and target metadata        | Verified current inventory; no target change       |
+| FR3 | A Panel in either logical start or end position is the same aggregate Panel part and uses the current `layout-panel` target; position does not create a second anatomy row or target.                                             | Current source, docs, tests, and family   | Verified current ownership; no API change          |
+| FR4 | `Layout.doc.mjs` is the canonical aggregate consumer document for all five current `layout*` targets; region subcomponent docs continue to document their own props and usage without duplicating the aggregate target inventory. | Current documentation organization        | Verified current ownership                         |
+| FR5 | LayoutContent and LayoutPanel retain their shipped automatic container-padding publication behavior, including the mismatches recorded by `architecture:container-padding`; this documentation does not claim exact parity.       | Current source and architecture record    | Current conformance gap; not fixed here            |
+| FR6 | When an adjacent ResizeHandle owns a panel divider, the caller must keep `LayoutPanel hasDivider={false}`; current composition does not prevent both components from painting the same boundary.                                  | Current source, docs, and family contract | Current caller obligation; not fixed here          |
+
+### Current evidence and gaps
+
+- LayoutContent does not republish a matching inline-end container-padding value
+  on its automatic no-end path, and its no-start path writes the outer inline
+  value to both inline geometry variables. LayoutPanel applies automatic outer
+  shell-edge padding while retaining baseline inner geometry variables. A
+  full-bleed descendant can therefore compensate against a published value that
+  differs from the region's applied padding. This is shipped evidence and a
+  runtime conformance gap, not behavior corrected or approved by this draft.
+- LayoutPanel and an adjacent ResizeHandle can both draw the same content-facing
+  divider. The current caller obligation is to set
+  `LayoutPanel hasDivider={false}` when ResizeHandle owns that line. This draft
+  does not add coordination or duplicate-divider prevention.
+
+### Allowed variation
+
+- **AV1 — Slot presence.** Header, start Panel, Content area, end Panel, and Footer
+  may be independently present or absent within the existing shell topology.
+- **AV2 — Panel position.** A Panel may occupy logical start or end, or Panels may
+  occupy both positions; all use the same conceptual part and target owner.
+- **AV3 — Region content.** Caller-provided region content retains its own
+  semantics and theming ownership.
+
+### Representative states
+
+| State                 | Required invariant                                                         | Allowed variation                                      |
+| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Content-only shell    | Page shell and Content area use their current targets.                     | Caller content and current height/width configuration. |
+| Header/content/footer | Each supplied region uses its corresponding aggregate part and target.     | Divider selection, size, padding, and caller content.  |
+| Start or end Panel    | Either logical position uses the one Panel part and `layout-panel` target. | Position, width, scrolling, padding, and caller role.  |
+| Two Panels            | Both instances remain one repeated conceptual Panel part.                  | Independent content, width, and local configuration.   |
+| ResizeHandle-adjacent | Divider ownership follows the current caller obligation in FR6.            | Resize state remains owned by the resize components.   |
+
+### Transformation and precedence order
+
+- No new slot, padding, content-width, divider, scrolling, sizing, or styling
+  precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not add inferred landmark semantics. LayoutHeader,
+LayoutContent, LayoutFooter, and LayoutPanel retain their current explicit
+caller-supplied role and label behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                             | Representation authority                  | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
+| Page shell       | Arranges the named page regions.                               | Current source, docs, and family contract | Supporting     | FR1                |
+| Header           | Presents optional top-region content.                          | Current source, docs, and family contract | Supporting     | FR1, FR2           |
+| Panel            | Presents optional side-region content at logical start or end. | Current source, docs, and family contract | Supporting     | FR1, FR3, FR6      |
+| Content area     | Presents optional central page content.                        | Current source, docs, and family contract | Prominent      | FR1, FR2, FR5      |
+| Footer           | Presents optional bottom-region content.                       | Current source, docs, and family contract | Supporting     | FR1, FR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Page shell": {"target": "layout"},
+  "Header": {"target": "layout-header"},
+  "Panel": {"target": "layout-panel"},
+  "Content area": {"target": "layout-content"},
+  "Footer": {"target": "layout-footer"}
+}
+```
+
+The exact map records the five current public targets. Start and end Panels are
+instances of the same stable conceptual part and therefore share one map row.
+
+## Family and system relationships
+
+- `family:layout-regions` owns the shared shell-region topology, logical
+  direction, boundaries, scrolling, and component ownership.
+- `architecture:container-padding` owns Layout inset publication and the current
+  LayoutContent/LayoutPanel conformance gap.
+- `architecture:component-theming-surface` owns anatomy qualification and exact
+  target mapping rules.
+- `architecture:public-component-api` owns the stable slots, props, exports, and
+  compatibility boundary; this documentation adds no API.
+
+## Verification map
+
+| Contract      | Verification                                                                  | Representative states                               | Mutation or failure expectation                                                                     | Audit section                |
+| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1–FR3       | Layout render, slot, children-as-content, and target inventory tests          | Content-only, all regions, logical start/end Panels | Removing a region or target fails existing structure, context, or target inventory assertions.      | `audit:Layout/anatomy`       |
+| FR4           | `scripts/check-knowledge.mjs`                                                 | Canonical aggregate doc and exact five-target map   | Duplicated, missing, extra, prefixed, or stale target mappings fail repository validation.          | `audit:Layout/theming`       |
+| FR5           | Source inspection plus `architecture:container-padding` verification evidence | Automatic outer-edge Content area and Panel paths   | This draft adds no parity assertion; a runtime correction requires separate compatibility evidence. | `audit:Layout/layout`        |
+| FR6           | LayoutPanel source/docs plus `family:layout-regions` verification evidence    | Panel beside a divider-owning ResizeHandle          | This draft adds no prevention assertion; changing ownership requires separate runtime coverage.     | `audit:Layout/layout`        |
+| Accessibility | `LayoutSlots.test.tsx` landmark assertions                                    | Header, Content area, Footer, and Panel roles       | Supplied role or label no longer reaches the region element.                                        | `audit:Layout/accessibility` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, API, target, or behavior decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, family region
+rules, container-padding mechanics, resize interaction, implementation steps,
+or system rules. It links to their owners.