@astryxdesign/core 0.5.2-canary.2da7a39 → 0.5.2-canary.3828a31

package/dist/Carousel/Carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAKhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyJD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAgYf;yBAhZe,QAAQ"}
+{"version":3,"file":"Carousel.d.ts","sourceRoot":"","sources":["../../src/Carousel/Carousel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAef,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAKhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,SAAS,EACT,QAAQ,EACR,GAAO,EACP,UAAiB,EACjB,WAAkB,EAClB,OAAe,EACf,OAAe,EACf,OAAO,EACP,YAAY,EAAE,kBAAkB,EAChC,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,SAAS,EACb,EAAE,aAAa,+BAgYf;yBAhZe,QAAQ"}

package/dist/Carousel/Carousel.js

@@ -69,11 +69,11 @@ const styles = {
     $$css: true
   },
   fadeStart: {
-    kX1K2I: "x1ujl4f5",
+    kX1K2I: "x1ujl4f5 x17xqekc",
     $$css: true
   },
   fadeEnd: {
-    kX1K2I: "xtdd0ob",
+    kX1K2I: "xtdd0ob x8ulde1",
     $$css: true
   },
   fadeBoth: {

package/dist/astryx.css

@@ -1317,7 +1317,9 @@
   .x16khyan:is(:disabled,[aria-disabled="true"]):not(#\#):not(#\#):not(#\#){cursor:default}
   .x1y40yee:popover-open:not(#\#):not(#\#):not(#\#){display:flex}
   .x1sik18w:not(:first-child):not(#\#):not(#\#):not(#\#){margin-inline-start:var(--_avatar-group-overlap)}
+  .x17xqekc:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to left,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
   .x1nwey30:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to left,transparent var(--_tab-strip-bleed),black calc(var(--_tab-strip-bleed) + var(--spacing-8)))}
+  .x8ulde1:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent 0%,rgba(0,0,0,.3) 2px,black var(--spacing-1))}
   .x1rxa4r8:is([dir="rtl"] *):not(#\#):not(#\#):not(#\#){mask-image:linear-gradient(to right,transparent var(--_tab-strip-bleed),black calc(var(--_tab-strip-bleed) + var(--spacing-8)))}
   .x1euntei:focus-within:not(#\#):not(#\#):not(#\#){opacity:1}
   .x25t5g8:focus-visible:not(#\#):not(#\#):not(#\#){opacity:1}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.2-canary.2da7a39",
+  "version": "0.5.2-canary.3828a31",
   "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.2da7a39",
+    "@astryxdesign/cli": "0.5.2-canary.3828a31",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/Button/Button.doc.mjs

@@ -23,6 +23,62 @@ export const docs = {
       {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
       {guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
     ],
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Button text must have at least 4.5:1 contrast with the button background in every state. 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 used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Badge text',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Badge text inside a button must have at least 4.5:1 contrast with the Badge background. Check all 14 built-in Badge colors in Rest, Hover, and Pointer down on page and surface backgrounds. This covers 336 pairs per mode. Check custom end content separately.',
+      },
+      {
+        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 text-only button can rely on its label.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline needs at least 3:1 contrast with the area around the button. Check every style. Destructive buttons use a red outline.',
+      },
+      {
+        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.',
+      },
+    ],
     anatomy: [
       {name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
       {name: 'Label', required: true, description: 'The visible text describing the action. Also used as the accessible name.'},

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -39,6 +39,53 @@ export const docs = {
   usage: {
     description:
       'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Text in each button must have at least 4.5:1 contrast with its background in every state. 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 used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'Some groups need a divider or edge to show each button. That divider or edge must have at least 3:1 contrast.',
+      },
+      {
+        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 it.',
+      },
+      {
+        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: 'Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.'},
       {guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},

package/src/Carousel/Carousel.test.tsx

@@ -850,4 +850,87 @@ describe('Carousel', () => {
       expect(scroller).not.toHaveAttribute('data-padding');
     });
   });
+
+  describe('edge fade', () => {
+    function getScroller() {
+      const region = screen.getByRole('region');
+      return region.firstElementChild as HTMLElement;
+    }
+
+    function makeOverflowing(el: HTMLElement, scrollLeft: number) {
+      Object.defineProperty(el, 'scrollWidth', {
+        value: 500,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'clientWidth', {
+        value: 200,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'scrollLeft', {
+        value: scrollLeft,
+        writable: true,
+        configurable: true,
+      });
+      fireEvent.scroll(el);
+    }
+
+    function injectedCss(): string {
+      let out = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            out += rule.cssText + '\n';
+          }
+        } catch {
+          // Ignore cross-origin sheets.
+        }
+      }
+      return out;
+    }
+
+    it('fades the physical left edge when only the start overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 300);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to right',
+      );
+    });
+
+    it('fades the physical right edge when only the end overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 0);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to left',
+      );
+    });
+
+    it('mirrors both single-edge fade gradients under RTL', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const css = injectedCss();
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to left/,
+      );
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to right/,
+      );
+    });
+  });
+
 });

package/src/Carousel/Carousel.tsx

@@ -178,10 +178,16 @@ const styles = stylex.create({
     maskImage: 'none',
   },
   fadeStart: {
-    maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeEnd: {
-    maskImage: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeBoth: {
     maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']}, black calc(100% - ${spacingVars['--spacing-1']}), rgba(0,0,0,0.3) calc(100% - 2px), transparent 100%)`,

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/FieldStatus/FieldStatus.doc.mjs

@@ -1,5 +1,24 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Message box',
+    required: true,
+    description: 'Painted container for the validation feedback.',
+  },
+  {
+    name: 'Detached icon',
+    required: false,
+    description: 'Leading status glyph shown only by the detached variant.',
+  },
+  {
+    name: 'Message text',
+    required: true,
+    description: 'Text describing the validation status.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'FieldStatus',
@@ -61,6 +80,7 @@ export const docs = {
           'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
       },
     ],
+    anatomy,
   },
 };
 
@@ -86,6 +106,7 @@ export const docsDense = {
           'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
       },
     ],
+    anatomy,
   },
   propDescriptions: {
     type: 'error/warning/success status tone',