Skip to content

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

TypeScript

docs(core): record factual anatomy batch 8 (#5751)

Cindy Zhangf994ddba0780
diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjs
index aa21aa1dfa..44e9cc55bc 100644
--- a/packages/core/src/Lightbox/Lightbox.doc.mjs
+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs
@@ -1,12 +1,63 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Viewer overlay',
+ required: true,
+ description:
+ 'Full-viewport dialog overlay that contains the active media and controls.',
+ },
+ {
+ name: 'Media',
+ required: true,
+ description: 'Active image or video presented inside the viewer.',
+ },
+ {
+ name: 'Close button',
+ required: true,
+ description: 'Button that closes the viewer.',
+ },
+ {
+ name: 'Previous button',
+ required: false,
+ description: 'Gallery button that moves to the previous media item.',
+ },
+ {
+ name: 'Next button',
+ required: false,
+ description: 'Gallery button that moves to the next media item.',
+ },
+ {
+ name: 'Caption',
+ required: false,
+ description: 'Caller-provided caption displayed below the active media.',
+ },
+ {
+ name: 'Counter',
+ required: false,
+ description: 'Current position and total shown in gallery mode.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'Lightbox',
displayName: 'Lightbox',
category: 'Overlay',
- keywords: ["lightbox","image","video","viewer","gallery","zoom","fullscreen","media","photo","preview"],
+ keywords: [
+ 'lightbox',
+ 'image',
+ 'video',
+ 'viewer',
+ 'gallery',
+ 'zoom',
+ 'fullscreen',
+ 'media',
+ 'photo',
+ 'preview',
+ ],
props: [
{
name: 'isOpen',
@@ -28,7 +79,8 @@ export const docs = {
// where a media object belongs. The shape and its legal values live in
// the description instead (#1645).
type: 'LightboxMedia | LightboxMedia[]',
- description: "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
+ description:
+ "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
required: true,
},
{
@@ -39,46 +91,70 @@ export const docs = {
{
name: 'onIndexChange',
type: '(index: number) => void',
- description: 'Callback when the gallery index changes via prev/next navigation.',
+ description:
+ 'Callback when the gallery index changes via prev/next navigation.',
},
{
name: 'hasZoom',
type: 'boolean',
- description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
+ description:
+ 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
default: 'false',
},
{
name: 'defaultIndex',
type: 'number',
- description: 'Initial image index in gallery mode for uncontrolled usage.',
+ description:
+ 'Initial image index in gallery mode for uncontrolled usage.',
default: '0',
},
{
name: 'hasAutoPlay',
type: 'boolean',
- description: 'Automatically start video playback when a video media item is shown.',
+ description:
+ 'Automatically start video playback when a video media item is shown.',
default: 'false',
},
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization. Must be stylex.create() value.',
+ description:
+ 'StyleX styles for layout customization. Must be stylex.create() value.',
},
],
theming: {
- targets: [
- {className: 'astryx-lightbox', visualProps: []},
- ],
+ targets: [{className: 'astryx-lightbox', visualProps: []}],
},
usage: {
+ anatomy,
description:
'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
bestPractices: [
- { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },
- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
- { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },
- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+ {
+ guidance: true,
+ description:
+ 'Always provide alt text for every image for screen reader accessibility.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use gallery mode with onIndexChange for multi-image sets.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use the lightbox for non-image content; it is specialized for images.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest interactive content inside captions; keep them plain text.',
+ },
],
},
// The lightbox opens via showModal() and renders nothing while closed —
@@ -91,7 +167,8 @@ export const docs = {
media: {
src: '/template-assets/light-scene-horizontal-1.png',
alt: 'Coastal shoreline with ocean waves',
- caption: 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
+ caption:
+ 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
},
},
},
@@ -117,7 +194,8 @@ export const docsZh = {
{
name: 'media',
type: 'LightboxMedia | LightboxMedia[]',
- description: "要显示的媒体。传入单个对象或数组(用于画廊模式的上一张/下一张导航)。每项为 {src, alt, caption?, type?: 'image' | 'video'};type 默认为 'image','video' 禁用缩放/平移。",
+ description:
+ "要显示的媒体。传入单个对象或数组(用于画廊模式的上一张/下一张导航)。每项为 {src, alt, caption?, type?: 'image' | 'video'};type 默认为 'image','video' 禁用缩放/平移。",
required: true,
},
{
@@ -139,39 +217,76 @@ export const docsZh = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+ description:
+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
},
],
theming: {
- targets: [
- {className: 'astryx-lightbox', visualProps: []},
- ],
+ targets: [{className: 'astryx-lightbox', visualProps: []}],
},
usage: {
+ anatomy,
description:
'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
bestPractices: [
- { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },
- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
- { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },
- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+ {
+ guidance: true,
+ description:
+ 'Always provide alt text for every image for screen reader accessibility.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use gallery mode with onIndexChange for multi-image sets.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use the lightbox for non-image content; it is specialized for images.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest interactive content inside captions; keep them plain text.',
+ },
],
},
};
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',
+ description:
+ 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',
usage: {
+ anatomy,
description:
'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
bestPractices: [
- { guidance: true, description: 'Always provide alt text for every image.' },
- { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
- { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
- { guidance: false, description: 'Use for non-image content; specialized for images.' },
- { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+ {guidance: true, description: 'Always provide alt text for every image.'},
+ {
+ guidance: true,
+ description:
+ 'Use gallery mode with onIndexChange for multi-image sets.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+ },
+ {
+ guidance: false,
+ description: 'Use for non-image content; specialized for images.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Nest interactive content inside captions; keep them plain text.',
+ },
],
},
propDescriptions: {
@@ -180,7 +295,8 @@ export const docsDense = {
media: 'Single media object or array for gallery mode.',
index: 'Current index in gallery mode.',
onIndexChange: 'Callback when gallery index changes.',
- hasZoom: 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',
+ hasZoom:
+ 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',
xstyle: 'StyleX styles for layout customization.',
},
};
diff --git a/packages/core/src/Lightbox/Lightbox.spec.md b/packages/core/src/Lightbox/Lightbox.spec.md
new file mode 100644
index 0000000000..ae4a60fffb
--- /dev/null
+++ b/packages/core/src/Lightbox/Lightbox.spec.md
@@ -0,0 +1,197 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Lightbox
+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/Lightbox/Lightbox.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:layer-runtime,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# Lightbox component contract
+
+## Intent
+
+Lightbox presents one active image or video in a full-viewport viewer and may
+add gallery navigation, a caption, and a position counter. This draft records
+current consumer anatomy and theming ownership 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 Viewer overlay and its current `lightbox` target.
+- Media presentation, optional Caption and Counter placement, gallery navigation,
+ and current image zoom and pan behavior.
+
+**Does not own / non-goals**
+
+- The Close, Previous, and Next button surfaces — delegated to
+ `component:Button` through IconButton.
+- Caller-provided Caption content.
+- New targets for Media, Caption, or Counter; none exist on current `main`.
+- Shared layer hosting or dismissal policy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Lightbox.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current viewer contains one active Media item and a Close button; galleries additionally contain Previous and Next buttons plus a Counter, and Caption renders only when supplied. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Viewer overlay carries the current `lightbox` target. Media, Caption, and Counter carry no Lightbox public target. | Current source and public docs | Verified current reachability; no target change |
+| FR3 | Close, Previous, and Next button surfaces use Button's `button` target through IconButton rather than Lightbox-owned button targets. | Current source and target docs | Verified current delegation; no ownership change |
+
+### Allowed variation
+
+- **AV1 — Media mode.** Media may be an image or video; zoom and pan are available
+ only on the current image path.
+- **AV2 — Gallery mode.** Previous, Next, and Counter are absent for a single
+ item. Navigation button disabled state follows the current gallery boundary.
+- **AV3 — Caption content.** Caller-provided Caption content may vary without
+ becoming a Lightbox-owned target.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------- | ------------------------------------------------------------------- | --------------------------------------------- |
+| Single image | Viewer overlay, Media, and Close button render. | Caption and zoom may be absent or present. |
+| Gallery boundary | Both navigation buttons and Counter remain rendered. | Previous or Next is disabled at its boundary. |
+| Video | Media renders native video controls without image zoom interaction. | Autoplay follows the existing consumer prop. |
+| Captioned media | Caption follows the active Media inside the centered media group. | Caption content remains caller-provided. |
+
+### Transformation and precedence order
+
+- No new index, zoom, pan, media, 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 Lightbox's existing dialog naming, focus,
+media alternatives, announcements, button labels, keyboard behavior, or
+dismissal behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Viewer overlay | Presents the full-viewport dialog and surrounding overlay treatment. | Current source and public docs | Supporting | FR1, FR2 |
+| Media | Presents the active image or video. | Current source and public docs | Prominent | FR1, FR2 |
+| Close button | Provides the persistent viewer dismissal action. | `component:Button` | Supporting | FR1, FR3 |
+| Previous button | Moves gallery presentation to the preceding item. | `component:Button` | Supporting | FR1, FR3 |
+| Next button | Moves gallery presentation to the following item. | `component:Button` | Supporting | FR1, FR3 |
+| Caption | Presents caller-provided context below the active Media. | Current source and public docs | Context-dependent | FR1, FR2 |
+| Counter | Presents current gallery position and total. | Current source and tests | Supporting | FR1, FR2 |
+
+Media, Caption, and Counter are stable visible parts, but no current public
+target reaches them. Their `none` dispositions record factual reachability, not
+a decision that they must remain unthemeable.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Viewer overlay": {"target": "lightbox"},
+ "Media": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the active image or video"
+ }
+ },
+ "Close button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Previous button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Next button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Caption": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the caption container"
+ }
+ },
+ "Counter": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the gallery counter"
+ }
+ }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, delegation, and factual `none` dispositions.
+- `architecture:layer-runtime` owns the current native-dialog host and shared
+ layer plumbing; Lightbox retains its current media and local backdrop behavior.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
+ records Lightbox as a current adopter.
+- `architecture:interaction-modality` and `architecture:public-component-api`
+ own their shared modality and API boundaries; this draft changes neither.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `Lightbox.test.tsx` render, gallery, caption, media, and zoom suites | Single image, gallery edges, caption, video | Removing a documented part fails existing role, content, media, or navigation assertions. | `audit:Lightbox/anatomy` |
+| FR2 | Source inspection and `themingTargets.test.ts` | Viewer overlay, Media, Caption, and Counter | Removing the root target or documenting an unshipped child target fails evidence or inventory. | `audit:Lightbox/theming` |
+| FR3 | Source inspection plus Button and IconButton public composition | Close and gallery navigation controls | Re-owning a control surface requires the delegated owner and this map to change. | `audit:Lightbox/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Lightbox/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, or layer-system decision.
+
+## Open questions
+
+- **OQ1 — Should Media, Caption, or Counter gain a stable public theming target?**
+ (`human-api`) Their current lack of reachability is an audit gap, not settled
+ intent.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, media algorithms,
+shared layer rules, current audit results, or implementation steps. It links to
+their owners.
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 6090f5cae4..2652044197 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -1,5 +1,43 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Navigation overlay',
+ required: true,
+ description:
+ 'Full-viewport dialog overlay that hosts the mobile navigation drawer.',
+ },
+ {
+ name: 'Drawer',
+ required: true,
+ description:
+ 'Painted panel that slides in from the resolved viewport edge.',
+ },
+ {
+ name: 'Header',
+ required: true,
+ description:
+ 'Fixed row containing optional header content and the close button.',
+ },
+ {
+ name: 'Content',
+ required: true,
+ description: 'Scrollable region containing the navigation content.',
+ },
+ {
+ name: 'Close button',
+ required: true,
+ description: 'Button that closes the navigation drawer.',
+ },
+ {
+ name: 'Toggle button',
+ required: false,
+ description:
+ 'AppShell-aware Button that opens or closes the drawer on mobile viewports.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -8,12 +46,24 @@ export const docs = {
group: 'Navigation',
category: 'Navigation',
isHiddenFromOverview: true,
- keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer","toggle"],
+ keywords: [
+ 'mobilenav',
+ 'drawer',
+ 'sidebar',
+ 'navigation',
+ 'hamburger',
+ 'menu',
+ 'offcanvas',
+ 'slideout',
+ 'navdrawer',
+ 'toggle',
+ ],
components: [
{
name: 'MobileNav',
displayName: 'Mobile Nav',
- description: 'A slide-out drawer for mobile navigation. Accepts SideNav children.',
+ description:
+ 'A slide-out drawer for mobile navigation. Accepts SideNav children.',
// The drawer opens via showModal() and renders nothing while closed —
// overlay mode gives the Properties preview an open trigger instead of
// an empty stage (#2706). Declared on this entry (not the directory
@@ -27,7 +77,10 @@ export const docs = {
__element: 'SideNavSection',
props: {title: 'Main'},
children: [
- {__element: 'SideNavItem', props: {label: 'Dashboard', isSelected: true}},
+ {
+ __element: 'SideNavItem',
+ props: {label: 'Dashboard', isSelected: true},
+ },
{__element: 'SideNavItem', props: {label: 'Projects'}},
{__element: 'SideNavItem', props: {label: 'Settings'}},
],
@@ -38,7 +91,8 @@ export const docs = {
{
name: 'isOpen',
type: 'boolean',
- description: 'Whether the drawer is open. Inside AppShell, this is managed automatically via context. Outside AppShell, provide this prop to control the drawer yourself.',
+ description:
+ 'Whether the drawer is open. Inside AppShell, this is managed automatically via context. Outside AppShell, provide this prop to control the drawer yourself.',
},
{
name: 'onOpenChange',
@@ -56,7 +110,8 @@ export const docs = {
{
name: 'header',
type: 'ReactNode',
- description: 'Header content for the drawer. Rendered next to the close button. Pass a string for a simple text heading, or a ReactNode for custom content (logo, search bar, etc.).',
+ description:
+ 'Header content for the drawer. Rendered next to the close button. Pass a string for a simple text heading, or a ReactNode for custom content (logo, search bar, etc.).',
},
{
name: 'width',
@@ -77,7 +132,8 @@ export const docs = {
{
name: 'MobileNavToggle',
displayName: 'Mobile Nav Toggle',
- description: 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
+ description:
+ 'Hamburger button that opens/closes the mobile nav drawer. Reads open state from AppShell context automatically: does NOT accept isOpen or onOpenChange props. Renders nothing above the mobile breakpoint.',
// The toggle renders null unless AppShell mobile context reports an
// enabled mobile viewport — the default context outside AppShell never
// does, so the Properties preview was an empty stage. appShellMobile
@@ -89,7 +145,8 @@ export const docs = {
{
name: 'children',
type: 'ReactNode',
- description: 'Custom content to render instead of the default hamburger icon.',
+ description:
+ 'Custom content to render instead of the default hamburger icon.',
},
{
name: 'label',
@@ -101,18 +158,33 @@ export const docs = {
},
],
theming: {
- targets: [
- {className: 'astryx-mobile-nav', visualProps: ['side']},
- ],
+ targets: [{className: 'astryx-mobile-nav', visualProps: ['side']}],
},
usage: {
+ anatomy,
description:
'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical. Inside AppShell, use MobileNavToggle as the trigger; it reads state from context automatically.',
bestPractices: [
- { guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
- { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
- { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
- { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
+ {
+ guidance: true,
+ description:
+ 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.',
+ },
+ {
+ guidance: true,
+ description:
+ "Provide a header when the drawer's purpose is not obvious from its content.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use MobileNav on desktop: use a persistent SideNav instead.',
+ },
],
},
};
@@ -144,13 +216,13 @@ export const docsZh = {
{
name: 'header',
type: 'ReactNode',
- description: '抽屉的头部内容。渲染在关闭按钮旁边。传入字符串作为简单文本标题,或传入 ReactNode 作为自定义内容。',
+ description:
+ '抽屉的头部内容。渲染在关闭按钮旁边。传入字符串作为简单文本标题,或传入 ReactNode 作为自定义内容。',
},
{
name: 'width',
type: 'number',
- description:
- '抽屉宽度(像素)。上限为 85vw 以防止在小屏幕上溢出。',
+ description: '抽屉宽度(像素)。上限为 85vw 以防止在小屏幕上溢出。',
default: '320',
},
{
@@ -162,18 +234,33 @@ export const docsZh = {
},
],
theming: {
- targets: [
- {className: 'astryx-mobile-nav', visualProps: ['side']},
- ],
+ targets: [{className: 'astryx-mobile-nav', visualProps: ['side']}],
},
usage: {
+ anatomy,
description:
'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
bestPractices: [
- { guidance: true, description: 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.' },
- { guidance: true, description: 'Provide a header when the drawer\'s purpose is not obvious from its content.' },
- { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
- { guidance: false, description: 'Use MobileNav on desktop: use a persistent SideNav instead.' },
+ {
+ guidance: true,
+ description:
+ 'Share the same nav items between MobileNav and SideNav by extracting them into a variable.',
+ },
+ {
+ guidance: true,
+ description:
+ "Provide a header when the drawer's purpose is not obvious from its content.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use MobileNav on desktop: use a persistent SideNav instead.',
+ },
],
},
};
@@ -183,23 +270,42 @@ export const docsDense = {
description:
'Slide-out drawer overlay for mobile navigation. Mobile counterpart to SideNav; accepts same children (SideNavSection, SideNavItem, or any ReactNode).',
usage: {
+ anatomy,
description:
'A slide-out drawer for mobile navigation. MobileNav is the mobile counterpart to SideNav and accepts the same children. Use it on narrow viewports where a persistent sidebar is not practical.',
bestPractices: [
- { guidance: true, description: 'Share nav items between MobileNav and SideNav by extracting into a variable.' },
- { guidance: true, description: 'Provide a header when the drawer purpose is not obvious from content.' },
- { guidance: true, description: 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.' },
- { guidance: false, description: 'Use MobileNav on desktop; use a persistent SideNav instead.' },
+ {
+ guidance: true,
+ description:
+ 'Share nav items between MobileNav and SideNav by extracting into a variable.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Provide a header when the drawer purpose is not obvious from content.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Inside AppShell, use MobileNavToggle to open the drawer; it reads state from context. Do not pass isOpen/onOpenChange to the toggle.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use MobileNav on desktop; use a persistent SideNav instead.',
+ },
],
},
components: [
{
name: 'MobileNav',
- description: 'Slide-out drawer for mobile navigation. Accepts SideNav children.',
+ description:
+ 'Slide-out drawer for mobile navigation. Accepts SideNav children.',
},
{
name: 'MobileNavToggle',
- description: 'Hamburger button that opens/closes mobile nav drawer. Reads open state from AppShell context automatically. Renders nothing above mobile breakpoint.',
+ description:
+ 'Hamburger button that opens/closes mobile nav drawer. Reads open state from AppShell context automatically. Renders nothing above mobile breakpoint.',
},
],
propDescriptions: {
@@ -208,8 +314,10 @@ export const docsDense = {
'called when drawer visibility changes (backdrop click, Escape, close button)',
children:
'drawer content; typically SideNavSection/SideNavItem or any ReactNode',
- header: 'header content (string or ReactNode), rendered next to close button',
- width: 'drawer width px; capped at 85vw to prevent overflow on small screens',
+ header:
+ 'header content (string or ReactNode), rendered next to close button',
+ width:
+ 'drawer width px; capped at 85vw to prevent overflow on small screens',
side: 'slide direction; start=left LTR, right RTL',
},
};
diff --git a/packages/core/src/MobileNav/MobileNav.spec.md b/packages/core/src/MobileNav/MobileNav.spec.md
new file mode 100644
index 0000000000..470b8167aa
--- /dev/null
+++ b/packages/core/src/MobileNav/MobileNav.spec.md
@@ -0,0 +1,208 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:MobileNav
+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/MobileNav/MobileNav.test.tsx,
+ packages/core/src/MobileNav/MobileNavToggle.test.tsx,
+ packages/core/src/MobileNav/MobileNavCloseEdgeCases.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:layer-runtime,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# MobileNav component contract
+
+## Intent
+
+MobileNav presents mobile navigation in a modal drawer and exports an AppShell-
+aware Toggle button for opening and closing it. This draft records the aggregate
+consumer anatomy and theming ownership of both exports 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 Navigation overlay and its current `mobile-nav` target.
+- Drawer placement and motion, the stable Header and Content regions, and the
+ connection between AppShell state, MobileNav, and MobileNavToggle.
+- Canonical anatomy for both exported components. `component:MobileNav` is the
+ parent owner; MobileNavToggle does not have a separate component contract.
+
+**Does not own / non-goals**
+
+- The Close and Toggle button surfaces — delegated to `component:Button`.
+- Header or navigation content supplied by the caller.
+- A public target for the painted Drawer, Header, or Content region; none exists
+ on current `main`.
+- AppShell responsive policy or shared layer and dismissal policy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, exports, and usage remain
+documented in `MobileNav.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | MobileNav renders one Navigation overlay containing a Drawer with a stable Header, Close button, and scrollable Content region. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Navigation overlay carries the current `mobile-nav` target. Drawer, Header, and Content carry no MobileNav public target. | Current source and public docs | Verified current reachability; no target change |
+| FR3 | Close button and the separately exported Toggle button use Button's `button` target; Toggle renders only when AppShell mobile context enables it and references the drawer by ID. | Current source, docs, and tests | Verified current delegation; no ownership change |
+
+### Allowed variation
+
+- **AV1 — Drawer edge.** The Drawer may resolve to logical start or end through
+ the current explicit or trigger-derived side behavior.
+- **AV2 — Header content.** Header may contain a string rendered through Heading,
+ caller-provided content, or only the Close button.
+- **AV3 — Navigation content.** Caller-provided navigation content may vary
+ without becoming MobileNav-owned anatomy.
+- **AV4 — Toggle presence.** Toggle button is absent outside an enabled AppShell
+ mobile context.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------- |
+| Standalone drawer | Navigation overlay contains Drawer, Header, Close button, and Content. | Caller controls open state and may choose an edge. |
+| AppShell drawer | The same drawer anatomy consumes AppShell mobile state. | Header and navigation content remain caller-owned. |
+| AppShell mobile toggle | Toggle button controls and references the current drawer. | Custom button content may replace the menu glyph. |
+| Non-mobile/disabled host | Toggle button does not render. | MobileNav remains owned by the parent contract. |
+
+### Transformation and precedence order
+
+- No new side resolution, open-state, close timing, 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 MobileNav's existing dialog naming, focus,
+Toggle relationship, Button labels, modal behavior, or dismissal behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------ | --------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Navigation overlay | Hosts the modal navigation layer and its backdrop. | Current source and public docs | Supporting | FR1, FR2 |
+| Drawer | Paints the sliding mobile navigation surface. | Current source and public docs | Prominent | FR1, FR2 |
+| Header | Arranges optional header content with the persistent Close button. | Current source and public docs | Supporting | FR1, FR2 |
+| Content | Provides the scrolling region for caller-supplied navigation content. | Current source and public docs | Prominent | FR1, FR2 |
+| Close button | Dismisses the current drawer. | `component:Button` | Supporting | FR1, FR3 |
+| Toggle button | Opens or closes the AppShell-owned mobile drawer state. | `component:Button` | Supporting | FR3 |
+
+Drawer is the primary painted surface, but the only current MobileNav target is
+on the full-viewport dialog overlay. Its `none` disposition is a factual
+reachability gap, not a decision that the Drawer must remain unthemeable. Header
+and Content likewise have no current local target. Close and Toggle retain Button
+ownership.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Navigation overlay": {"target": "mobile-nav"},
+ "Drawer": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the painted drawer panel"
+ }
+ },
+ "Header": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the stable header row"
+ }
+ },
+ "Content": {
+ "none": {
+ "reason": "reachability-gap: No current public target is applied to the scrollable content region"
+ }
+ },
+ "Close button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ },
+ "Toggle button": {
+ "delegatesTo": {"owner": "component:Button", "target": "button"}
+ }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, delegation, and factual `none` dispositions.
+- `architecture:layer-runtime` owns the current native-dialog host and shared
+ layer plumbing; MobileNav retains its current drawer motion and backdrop path.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
+ records MobileNav as a current adopter.
+- `architecture:public-component-api` owns the shared API boundary; this draft
+ changes neither MobileNav nor MobileNavToggle API.
+- AppShell remains the higher-level responsive owner. This parent component
+ record owns the two MobileNav exports' shared anatomy only.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1 | `MobileNav.test.tsx` content/header/close assertions plus source inspection | Standalone open and closed drawer | Removing dialog content or the Close action fails tests; distinct Drawer/Header/Content wrappers rely on review. | `audit:MobileNav/anatomy` |
+| FR2 | Source inspection and `themingTargets.test.ts` | Overlay, Drawer, Header, and Content | Removing the root target or documenting an unshipped child target fails evidence or inventory. | `audit:MobileNav/theming` |
+| FR3 | `MobileNavToggle.test.tsx`, `MobileNavReopen.test.tsx`, and source inspection | Closed/open AppShell drawer and toggle | Breaking Button delegation or the ID/state relationship fails focused toggle coverage. | `audit:MobileNav/anatomy` |
+| Close lifecycle | `MobileNavCloseEdgeCases.test.tsx` and related close/visibility suites | Escape, backdrop, close, reopen, unmount | Leaving the modal open or disconnecting state fails existing lifecycle assertions. | `audit:MobileNav/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical parent anatomy and current target | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:MobileNav/theming` |
+
+Current tests find header and navigation content by text and the Close action by
+role, but do not identify the distinct Drawer, Header, or Content elements. Their
+existence and nesting are source-inspected; merging or reordering those wrappers
+currently lacks focused regression evidence.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, responsive, or layer-system decision.
+
+## Open questions
+
+- **OQ1 — Should Drawer gain a stable public theming target?** (`human-api`) The
+ current target reaches the Navigation overlay rather than the primary painted
+ drawer surface; this is an audit gap, not settled intent.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, AppShell responsive
+policy, close-timing mechanics, shared layer rules, current audit results, or
+implementation steps. It links to their owners.
diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjs
index 7d9b06c5a0..55282a431b 100644
--- a/packages/core/src/Resizable/Resizable.doc.mjs
+++ b/packages/core/src/Resizable/Resizable.doc.mjs
@@ -1,5 +1,27 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Handle',
+ required: true,
+ description:
+ 'Focusable separator that owns pointer and keyboard resize interaction.',
+ },
+ {
+ name: 'Grip pill',
+ required: false,
+ description:
+ 'Default visible grip indicator; custom handle content can replace it.',
+ },
+ {
+ name: 'Grab zone',
+ required: true,
+ description:
+ 'Invisible enlarged pointer region aligned with the grip or divider.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
name: 'Resizable',
@@ -19,6 +41,7 @@ export const docs = {
'grip',
],
usage: {
+ anatomy,
description:
'Hook-based resizable panel system. useResizable() manages size state ' +
'and ResizeHandle provides the interactive pill-grip separator. ' +
@@ -86,8 +109,7 @@ export const docs = {
{
name: 'collapsedSize',
type: 'number',
- description:
- 'Pixel threshold that triggers collapse during drag.',
+ description: 'Pixel threshold that triggers collapse during drag.',
default: '40',
},
{
@@ -98,13 +120,13 @@ export const docs = {
{
name: 'shrinkOrder',
type: 'number',
- description:
- 'Cascade priority: lower number shrinks first.',
+ description: 'Cascade priority: lower number shrinks first.',
},
{
name: 'autoSaveId',
type: 'string',
- description: 'Key for persisting sizes and collapse state to localStorage.',
+ description:
+ 'Key for persisting sizes and collapse state to localStorage.',
},
],
},
@@ -190,20 +212,35 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',
+ description:
+ 'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator.',
usage: {
+ anatomy,
description:
'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
bestPractices: [
- {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
- {guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
- {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
+ {
+ guidance: true,
+ description:
+ 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.',
+ },
],
},
components: [
{
name: 'useResizable',
- description: 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',
+ description:
+ 'Hook managing resize state for one or more panel regions. Returns size, isCollapsed, collapse/expand/resize methods, + props to pass to handles.',
propDescriptions: {
defaultSize: 'initial size in px or % string (e.g. "20%")',
minSizePx: 'minimum size in px',
@@ -217,14 +254,20 @@ export const docsDense = {
},
{
name: 'ResizeHandle',
- description: 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
+ description:
+ 'Draggable separator between panels. Pill-grip: invisible at rest, visible on hover (0.6 opacity), fully opaque during drag (1.0). Keyboard-accessible.',
propDescriptions: {
- direction: 'layout direction: determines cursor + indicator orientation',
- isReversed: 'reverse drag direction. Use when handle controls panel on end/right/bottom side',
+ direction:
+ 'layout direction: determines cursor + indicator orientation',
+ isReversed:
+ 'reverse drag direction. Use when handle controls panel on end/right/bottom side',
isDisabled: 'handle interactive?',
- hasDivider: 'show full-length 1px divider line through handle. Use when adjacent panels share same background',
- isAlwaysVisible: 'show pill grip at rest instead of only on hover. Use when discoverability important',
- pillPlacement: 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
+ hasDivider:
+ 'show full-length 1px divider line through handle. Use when adjacent panels share same background',
+ isAlwaysVisible:
+ 'show pill grip at rest instead of only on hover. Use when discoverability important',
+ pillPlacement:
+ 'which side of divider pill sits on. auto = content side (derived from isReversed), flips when collapsed; start = left/top, end = right/bottom, center = centered on divider',
label: 'accessible label for separator',
resizable: 'resize props from useResizable: connects handle to panel',
},
diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.md
new file mode 100644
index 0000000000..88c7aff9ad
--- /dev/null
+++ b/packages/core/src/Resizable/Resizable.spec.md
@@ -0,0 +1,194 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Resizable
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Resizable/ResizeHandle.test.tsx,
+ packages/core/src/Resizable/useResizable.test.ts,
+ 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: []
+---
+
+# Resizable component contract
+
+## Intent
+
+Resizable combines the useResizable state and behavior hook with a focusable
+ResizeHandle. The handle presents a default Grip pill over an enlarged invisible
+Grab zone. This draft records current consumer anatomy and theming ownership
+without changing resize semantics, 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**
+
+- useResizable size, collapse, snapping, persistence, and resize lifecycle.
+- ResizeHandle's separator semantics, pointer and keyboard interaction, and
+ current `resize-handle` target.
+- The default Grip pill and its current `resize-handle-pill` target, plus the
+ aligned invisible Grab zone.
+
+**Does not own / non-goals**
+
+- The structural region being resized — owned by LayoutPanel, SideNav, or another
+ caller.
+- Layout-region topology, inset, divider, or scrolling rules.
+- A public target for the Grab zone; none exists on current `main`.
+- Fixing the missing runtime reflection for the documented Handle `direction`
+ theming state in this documentation-only change.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, hook outputs, and usage
+remain documented in `Resizable.doc.mjs` and `useResizable.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------- |
+| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone; the default render also contains a Grip pill, while caller-provided children replace that pill. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Handle carries `resize-handle`, Grip pill carries `resize-handle-pill`, and Grab zone carries no public target. | Current source and public docs | Verified current target inventory; no target change |
+| FR3 | Pointer, keyboard, collapse, snap, persistence, reversal, and size behavior remain owned by ResizeHandle and useResizable rather than layout-regions collaborators. | Current source, docs, and tests | Verified current ownership; resize semantics remain unchanged |
+| FR4 | Resizable metadata advertises `direction` as a Handle visual state, but current runtime calls `themeProps('resize-handle')` without reflecting that value, so direction selectors cannot match. | Current source and public docs | Verified audit gap; deliberately not fixed in this change |
+
+### Allowed variation
+
+- **AV1 — Axis.** Handle may resize along the horizontal or vertical layout axis;
+ separator orientation and cursor follow the current implementation.
+- **AV2 — Placement.** Handle may participate inline or overlay its parent, and
+ Grip pill may sit at start, end, center, or the current automatic side.
+- **AV3 — Grip content.** Caller-provided children may replace Grip pill without
+ changing Handle or Grab zone ownership.
+- **AV4 — Divider.** Handle may paint its current divider treatment; a composing
+ region remains responsible for avoiding a duplicate adjacent divider.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
+| Default handle | Handle, Grab zone, and Grip pill render. | Divider and always-visible treatment may vary. |
+| Custom handle content | Handle and Grab zone remain; caller content replaces Grip pill. | Caller content remains caller-owned. |
+| Horizontal or vertical | Interaction follows the selected axis and current ARIA orientation. | Size, reversal, and pill placement may vary. |
+| Collapsed or expanded | Handle preserves valid separator value semantics and resize controls. | Grip pill automatic side follows current behavior. |
+| Disabled | Handle remains represented but is removed from interactive tab order. | Painted treatment follows existing styles. |
+
+### Transformation and precedence order
+
+- No new clamp, snap, collapse, persistence, reversal, pointer, or keyboard order
+ is introduced.
+
+### Performance and resources
+
+- No new listener, storage, observer, or render requirement is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend ResizeHandle's existing separator role,
+label, orientation, value, collapsed value text, focus, pointer, or keyboard
+behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Handle | Presents the focusable resize separator and optional divider treatment. | Current source and public docs | Prominent | FR1, FR2, FR3 |
+| Grip pill | Presents the default visible resize affordance. | Current source and public docs | Supporting | FR1, FR2 |
+| Grab zone | Enlarges pointer reach while remaining visually transparent. | Current source and tests | Supporting | FR1, FR2 |
+| Direction state | Selects horizontal or vertical resize presentation. | Current public metadata | Supporting | FR3, FR4 |
+
+Grab zone is interaction structure rather than a painted public theming seam. Its
+`none` disposition records factual reachability. The missing Handle direction
+reflection is a separate current audit gap: the target exists, but runtime does
+not emit the documented target state.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Handle": {"target": "resize-handle"},
+ "Grip pill": {"target": "resize-handle-pill"},
+ "Grab zone": {
+ "none": {
+ "reason": "intentional: The invisible pointer hit area is nonvisual interaction structure and has no public target"
+ }
+ }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+ mapping, and target-state reflection requirements.
+- `architecture:interaction-modality` and `architecture:public-component-api`
+ own shared modality and API boundaries; this draft changes neither.
+- `family:layout-regions` lists useResizable and ResizeHandle as collaborators
+ that may drive a LayoutPanel's size. Resizable is not a layout-regions member,
+ and that family does not own or redefine resize state, snapping, persistence,
+ collapse, pointer, or keyboard semantics.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1 | `ResizeHandle.test.tsx` plus source inspection | Default, custom, collapsed, disabled, both axes | Handle and Grab zone regressions fail focused tests; custom Grip replacement currently relies on source review. | `audit:Resizable/anatomy` |
+| FR2 | Source inspection and `themingTargets.test.ts` | Handle, Grip pill, and Grab zone | Removing a target or documenting an unshipped Grab zone target fails evidence or inventory. | `audit:Resizable/theming` |
+| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts` | Pointer, keyboard, snap, collapse, persistence | Moving resize ownership or changing current transformations fails focused behavior coverage. | `audit:Resizable/behavior` |
+| FR4 | Source and public metadata comparison | Horizontal and vertical Handle | No current test detects that documented `direction` is absent from runtime target-state reflection. | `audit:Resizable/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two current targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Resizable/theming` |
+
+Current tests exercise Handle and Grab zone structure and behavior but do not
+render `children` to prove that custom content replaces Grip pill. That branch is
+source-inspected and lacks focused regression evidence. The documented
+`direction` visual axis is a closed union, so `extensibleAxes.test.ts` does not
+cover its missing runtime reflection; that mismatch is currently unguarded.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, resize, layout-family, or theming decision.
+
+## Open questions
+
+- **OQ1 — Which follow-up should add and verify the missing Handle `direction`
+ target-state reflection?** (`checkable`)
+- **OQ2 — Which focused test should pin custom content replacing Grip pill?**
+ (`checkable`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, resize algorithms,
+layout-region rules, current audit results, or implementation steps. It links to
+their owners.