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

package/src/TextArea/TextArea.spec.md

@@ -0,0 +1,204 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:TextArea
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/TextArea/TextArea.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# TextArea component contract
+
+## Intent
+
+TextArea presents a labeled multi-line text field. This draft records its current
+consumer anatomy and the theming ownership of parts rendered by TextArea, Field,
+FieldStatus, and Spinner. It changes no runtime behavior 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; TextArea remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The painted input container, native text area, and character counter represented
+  by the existing `text-area`, `text-area-control`, and `text-area-counter`
+  targets.
+
+**Does not own / non-goals**
+
+- Label and attached/detached validation-message presentation — owned by
+  `component:Field` and `component:FieldStatus`.
+- The tooltip-variant status surface — owned by `component:Tooltip`.
+- Standard start-icon presentation and the shared on-field status icon — owned
+  by `component:Icon` and `component:Field`, respectively.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- Caller-provided custom start content outside Icon's supported source forms.
+- The deprecated `textarea` alias as separate anatomy.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, states, and usage remain
+documented in `TextArea.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                 | Basis                                   | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places the native text area inside its painted input container.                                                                                  | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | The input container, native control, and conditional character counter carry the three current local targets.                                                       | Current source and public docs          | Verified current behavior; no target change        |
+| FR3 | Label, standard start icon, loading indicator, status icon, and status surfaces continue to use their shared Field, Icon, Spinner, FieldStatus, and Tooltip owners. | Current source                          | Verified conditional composition boundary          |
+| FR4 | Placeholder text remains part of the native control; the over-limit glyph remains part of the character counter.                                                    | Current source, docs, and focused tests | Verified current grouping                          |
+
+### Allowed variation
+
+- Value, placeholder, row count, size, status, disabled/read-only state, and
+  optional slots remain current capabilities rather than separate target names.
+- Start-icon content may be an Icon-supported value or caller-supplied ReactNode.
+
+### Representative states
+
+| State                | Required invariant                                                     | Allowed variation                   |
+| -------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
+| Default editable     | Label, input container, and native text area render.                   | Value, placeholder, rows, and size  |
+| With character limit | Character counter renders inside the input container.                  | Count and over-limit state          |
+| Busy or status       | Shared Spinner or status presentation renders in its current location. | Status variant and message presence |
+
+### Transformation and precedence order
+
+- No new value, layout, status, 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 TextArea's existing label, description,
+status, counter, busy state, disabled/read-only state, or announcement behavior.
+
+## Design relationships
+
+| Anatomy or state      | Design requirement                                                   | Representation authority        | Hierarchy role | Component contract |
+| --------------------- | -------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Input container       | Presents the current painted field boundary.                         | Current source and public docs  | Supporting     | FR1, FR2           |
+| Text area             | Presents and edits the current multi-line value.                     | Current source and public docs  | Prominent      | FR1, FR2           |
+| Character counter     | Presents current and maximum character counts.                       | Current source and public docs  | Supporting     | FR2, FR4           |
+| Shared field feedback | Presents current label, standard icons, status, and loading content. | Current shared-component source | Supporting     | FR3                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Input container": {"target": "text-area"},
+  "Text area": {"target": "text-area-control"},
+  "Placeholder": {"inherits": "text-area-control"},
+  "Start icon": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Custom start content": {
+    "none": {
+      "reason": "intentional: Custom start content is caller-provided ReactNode content outside TextArea's public theming ownership"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status icon": {
+    "delegatesTo": {
+      "owner": "component:Field",
+      "target": "input-status-icon"
+    }
+  },
+  "Character counter": {"target": "text-area-counter"},
+  "Field status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  },
+  "Tooltip status message": {
+    "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
+  }
+}
+```
+
+`Description` remains stable consumer anatomy, but no current public target
+reaches it; future exposure remains unsettled. Semantic names and icon component
+values render through Icon and delegate to its `icon` target; arbitrary ReactNode
+start content is caller-provided and intentionally stays outside TextArea's
+public theming ownership. Attached and detached status messages delegate to
+FieldStatus, while the tooltip variant delegates its rendered surface to Tooltip.
+The deprecated `textarea` alias is compatibility evidence only and does not
+appear in the map.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+  `none` dispositions, composition-preserving ownership, and alias exclusion.
+- Field, FieldStatus, Icon, Spinner, and Tooltip retain their existing public
+  target contracts when composed by TextArea.
+
+## Verification map
+
+| Contract            | Verification                                                                                  | Representative states                                                    | Mutation or failure expectation                                                                                                                 | Audit section            |
+| ------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, FR4            | `TextArea.test.tsx` structure and counter suites                                              | Default, placeholder, counter, over limit                                | Removing or regrouping stable parts breaks existing role, content, or DOM assertions.                                                           | `audit:TextArea/anatomy` |
+| FR2                 | `TextArea.test.tsx` root-target suite and `themingTargets.test.ts`                            | Current and deprecated root names; current targets                       | Removing root compatibility classes fails focused coverage; source/docs drift fails the target guard.                                           | `audit:TextArea/theming` |
+| FR3                 | `TextArea.test.tsx`, `useInputStatusIcon.test.tsx`, and source inspection of `renderIconSlot` | Standard/custom start content; Spinner; attached/detached/tooltip status | Removing or rerouting composed content breaks existing icon, spinner, tooltip, message, or association assertions.                              | `audit:TextArea/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                 | Canonical anatomy and current local targets                              | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | `audit:TextArea/theming` |
+
+The focused TextArea suite pins the current and deprecated root classes, but does
+not separately assert the exact `text-area-control` or `text-area-counter` class
+placement. The source/metadata target guard covers those local declarations. No
+current repository check resolves `delegatesTo` owner/target pairs; the pairs in
+this draft were verified manually, so semantic delegation drift remains a
+validation gap.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/TextInput/TextInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'TextInput',
   displayName: 'Text Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],
   props: [
     {

package/src/TimeInput/TimeInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'TimeInput',
   displayName: 'Time Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'timeinput',
     'timepicker',

package/src/Toast/ToastViewport.test.tsx

@@ -793,6 +793,11 @@ describe('Toast swipe dismissal', () => {
     expect(visualToast.style.getPropertyValue('--_toast-swipe-exit-y')).toBe(
       '120%',
     );
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('');
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-opacity')).toBe(
+      '',
+    );
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-scale')).toBe('');
     expect(getComputedStyle(visualToast).transform).not.toContain('translateX');
   });
 
@@ -1147,11 +1152,9 @@ describe('Toast swipe dismissal', () => {
 
     expect(onHide).toHaveBeenCalledWith('manual');
     expect(visualToast.style.getPropertyValue('--_toast-swipe-opacity')).toBe(
-      '0.700',
-    );
-    expect(visualToast.style.getPropertyValue('--_toast-swipe-scale')).toBe(
-      '0.985',
+      '',
     );
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-scale')).toBe('');
     expect(visualToast.style.getPropertyValue('--_toast-swipe-exit-y')).toBe(
       'calc(-1 * 120%)',
     );
@@ -1248,6 +1251,117 @@ describe('Toast swipe dismissal', () => {
     );
   });
 
+  it('abandons a one-finger swipe when a second touch starts', () => {
+    const {visualToast, onHide} = renderSwipeToast();
+    const dispatchTouch = (
+      type: 'touchstart' | 'touchmove',
+      touches: {identifier: number; clientX: number; clientY: number}[],
+      changedTouches = touches,
+    ) => {
+      const event = new Event(type, {bubbles: true, cancelable: true});
+      Object.defineProperty(event, 'touches', {value: touches});
+      Object.defineProperty(event, 'changedTouches', {value: changedTouches});
+      visualToast.dispatchEvent(event);
+      return event;
+    };
+    const first = {identifier: 51, clientX: 10, clientY: 0};
+    const second = {identifier: 52, clientX: 30, clientY: 40};
+
+    act(() => {
+      dispatchTouch('touchstart', [first]);
+      dispatchTouch('touchmove', [{...first, clientY: 40}]);
+    });
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('40px');
+
+    act(() => {
+      dispatchTouch('touchstart', [first, second], [second]);
+    });
+    const multitouchMove = dispatchTouch('touchmove', [first, second]);
+
+    expect(multitouchMove.defaultPrevented).toBe(false);
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('');
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-opacity')).toBe(
+      '',
+    );
+    expect(onHide).not.toHaveBeenCalled();
+  });
+
+  it('does not dismiss when another touch remains outside the Toast', () => {
+    const {visualToast, onHide} = renderSwipeToast();
+    const first = {identifier: 61, clientX: 10, clientY: 0};
+    const second = {identifier: 62, clientX: 200, clientY: 200};
+    const dispatchTouch = (
+      type: 'touchstart' | 'touchmove' | 'touchend',
+      touches: (typeof first)[],
+      changedTouches: (typeof first)[],
+    ) => {
+      const event = new Event(type, {bubbles: true, cancelable: true});
+      Object.defineProperty(event, 'touches', {value: touches});
+      Object.defineProperty(event, 'changedTouches', {value: changedTouches});
+      visualToast.dispatchEvent(event);
+      return event;
+    };
+
+    act(() => {
+      dispatchTouch('touchstart', [first], [first]);
+      dispatchTouch(
+        'touchmove',
+        [{...first, clientY: 60}],
+        [{...first, clientY: 60}],
+      );
+    });
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('60px');
+
+    // The second contact began outside the Toast, so its touchstart did not
+    // reach the Toast listener. Ending the tracked finger must still cancel
+    // while that other contact remains active.
+    act(() => {
+      dispatchTouch('touchend', [second], [{...first, clientY: 60}]);
+    });
+
+    expect(onHide).not.toHaveBeenCalled();
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('');
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-opacity')).toBe(
+      '',
+    );
+  });
+
+  it('does not let a pen event with the same numeric ID control a touch gesture', () => {
+    const {visualToast, onHide} = renderSwipeToast();
+    const touch = {identifier: 7, clientX: 10, clientY: 0};
+    const touchStart = new Event('touchstart', {
+      bubbles: true,
+      cancelable: true,
+    });
+    Object.defineProperty(touchStart, 'touches', {value: [touch]});
+    Object.defineProperty(touchStart, 'changedTouches', {value: [touch]});
+
+    act(() => {
+      visualToast.dispatchEvent(touchStart);
+      fireEvent.pointerMove(visualToast, {
+        pointerId: 7,
+        pointerType: 'pen',
+        clientX: 10,
+        clientY: 60,
+      });
+      fireEvent.pointerUp(visualToast, {
+        pointerId: 7,
+        pointerType: 'pen',
+        clientX: 10,
+        clientY: 60,
+      });
+    });
+
+    expect(onHide).not.toHaveBeenCalled();
+    expect(visualToast.style.getPropertyValue('--_toast-swipe-y')).toBe('');
+
+    act(() => {
+      visualToast.dispatchEvent(
+        new Event('touchcancel', {bubbles: true, cancelable: true}),
+      );
+    });
+  });
+
   it('removes native touch listeners when a Toast unmounts', () => {
     const {visualToast, unmount} = renderSwipeToast();
     const removeListener = vi.spyOn(visualToast, 'removeEventListener');

package/src/Toast/useToastGesture.ts

@@ -25,12 +25,14 @@ const SWIPE_ACTIVE_SCALE_MAX = 0.02;
 export type ToastGestureDirection = 1 | -1;
 
 interface GesturePoint {
+  source: 'touch' | 'pen';
   pointerId: number;
   clientX: number;
   clientY: number;
 }
 
 interface GestureState {
+  source: GesturePoint['source'];
   pointerId: number;
   startX: number;
   startY: number;
@@ -126,6 +128,7 @@ export function useToastGesture({
       }
       const surfaceSize = Math.max(root.getBoundingClientRect().height, 1);
       gestureRef.current = {
+        source: point.source,
         pointerId: point.pointerId,
         startX: point.clientX,
         startY: point.clientY,
@@ -159,7 +162,12 @@ export function useToastGesture({
     ) => {
       const state = gestureRef.current;
       const root = rootRef.current;
-      if (!state || !root || point.pointerId !== state.pointerId) {
+      if (
+        !state ||
+        !root ||
+        point.source !== state.source ||
+        point.pointerId !== state.pointerId
+      ) {
         return;
       }
       const deltaX = point.clientX - state.startX;
@@ -209,7 +217,12 @@ export function useToastGesture({
     (point: GesturePoint) => {
       const state = gestureRef.current;
       const root = rootRef.current;
-      if (!state || !root || point.pointerId !== state.pointerId) {
+      if (
+        !state ||
+        !root ||
+        point.source !== state.source ||
+        point.pointerId !== state.pointerId
+      ) {
         return;
       }
       const travel = Math.max(
@@ -225,6 +238,10 @@ export function useToastGesture({
       gestureRef.current = null;
       root.style.removeProperty('transition-duration');
       if (isDismissed) {
+        // The exit animation owns the final translation. Clear the live-drag
+        // transform/fade/scale first so a standalone Toast does not remain
+        // partially translated or faded after its dismiss callback fires.
+        clearTransientStyles(root);
         root.style.setProperty(
           '--_toast-swipe-exit-y',
           state.direction === 1
@@ -247,7 +264,15 @@ export function useToastGesture({
       if (
         event.pointerType === 'pen' &&
         (event.button == null || event.button === 0) &&
-        beginGesture(event, event.target)
+        beginGesture(
+          {
+            source: 'pen',
+            pointerId: event.pointerId,
+            clientX: event.clientX,
+            clientY: event.clientY,
+          },
+          event.target,
+        )
       ) {
         rootRef.current?.setPointerCapture?.(event.pointerId);
       }
@@ -261,7 +286,12 @@ export function useToastGesture({
         return;
       }
       moveGesture(
-        event,
+        {
+          source: 'pen',
+          pointerId: event.pointerId,
+          clientX: event.clientX,
+          clientY: event.clientY,
+        },
         () => event.preventDefault(),
         () => rootRef.current?.releasePointerCapture?.(event.pointerId),
       );
@@ -275,7 +305,12 @@ export function useToastGesture({
         return;
       }
       rootRef.current?.releasePointerCapture?.(event.pointerId);
-      endGesture(event);
+      endGesture({
+        source: 'pen',
+        pointerId: event.pointerId,
+        clientX: event.clientX,
+        clientY: event.clientY,
+      });
     },
     [endGesture],
   );
@@ -284,6 +319,7 @@ export function useToastGesture({
     (event: ReactPointerEvent<HTMLDivElement>) => {
       if (
         event.pointerType === 'pen' &&
+        gestureRef.current?.source === 'pen' &&
         gestureRef.current?.pointerId === event.pointerId
       ) {
         resetGesture(true);
@@ -298,12 +334,14 @@ export function useToastGesture({
       return;
     }
     const point = (touch: Touch): GesturePoint => ({
+      source: 'touch',
       pointerId: touch.identifier,
       clientX: touch.clientX,
       clientY: touch.clientY,
     });
     const changedTouch = (event: TouchEvent) => {
-      const pointerId = gestureRef.current?.pointerId;
+      const state = gestureRef.current;
+      const pointerId = state?.source === 'touch' ? state.pointerId : null;
       return pointerId == null
         ? undefined
         : [...event.changedTouches].find(
@@ -311,12 +349,23 @@ export function useToastGesture({
           );
     };
     const handleTouchStart = (event: TouchEvent) => {
-      const touch = event.touches.length === 1 ? event.changedTouches[0] : null;
-      if (touch) {
+      if (event.touches?.length !== 1) {
+        // A second contact means the browser may be handling pinch zoom or
+        // two-finger scrolling. Abandon any accepted one-finger swipe before
+        // touchmove can suppress that native gesture.
+        resetGesture(true);
+        return;
+      }
+      const touch = event.changedTouches[0];
+      if (touch != null) {
         beginGesture(point(touch), event.target);
       }
     };
     const handleTouchMove = (event: TouchEvent) => {
+      if (event.touches?.length !== 1) {
+        resetGesture(true);
+        return;
+      }
       const touch = changedTouch(event);
       if (touch) {
         moveGesture(point(touch), () => {
@@ -327,6 +376,10 @@ export function useToastGesture({
       }
     };
     const handleTouchEnd = (event: TouchEvent) => {
+      if (event.touches.length > 0) {
+        resetGesture(true);
+        return;
+      }
       const touch = changedTouch(event);
       if (touch) {
         endGesture(point(touch));

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -122,6 +122,62 @@ export const docs = {
   usage: {
     description:
       'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Unselected', 'Selected', 'Hover', 'Pointer down'],
+        description:
+          'The label must have at least 4.5:1 contrast with the button background when selected and unselected. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon-only ToggleButton must have at least 3:1 contrast between its icon and button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Selected state indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if relied upon',
+        states: ['Selected'],
+        description:
+          'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label weight or a changed icon can also show selection.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The button edge needs 3:1 contrast only when users need it to see the control. A visible label or icon can show the control instead.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around the button. Check both selected and unselected states.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.'},
       {guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'Tokenizer',
   displayName: 'Tokenizer',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],
   props: [
     {

package/src/Toolbar/Toolbar.doc.mjs

@@ -1,5 +1,21 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Outer chrome',
+    required: true,
+    description:
+      'Section-owned container that supplies the toolbar surface, padding, and selected divider edges.',
+  },
+  {
+    name: 'Toolbar',
+    required: true,
+    description:
+      'Named toolbar row that owns toolbar semantics and the start, optional center, and end layout.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -147,6 +163,7 @@ export const docs = {
       ],    },
   ],
   usage: {
+    anatomy,
     description:
       'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
     bestPractices: [
@@ -182,6 +199,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
     bestPractices: [
@@ -200,6 +218,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'Horizontal bar w/ left, center, right areas. For contextual actions in content, not page headers. Size cascades to children.',
   usage: {
+    anatomy,
     description:
       'Horizontal bar w/ left, optional center, right. For contextual actions within content (tables, cards, panels), not page-level headers. Size cascades to children.',
     bestPractices: [