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

package/src/Icon/Icon.doc.mjs

@@ -1,12 +1,29 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Glyph',
+    required: true,
+    description: 'Visual symbol rendered for the selected icon.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Icon',
   displayName: 'Icon',
   category: 'Content',
-  keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],
+  keywords: [
+    'icon',
+    'svg',
+    'glyph',
+    'symbol',
+    'pictogram',
+    'graphic',
+    'vector',
+  ],
   playground: {
     // `icon` is required and its type can't be auto-generated, so the
     // properties-tab preview showed "Missing: icon". Seed a valid semantic
@@ -19,7 +36,8 @@ export const docs = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+      description:
+        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
@@ -37,34 +55,79 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
+      description:
+        'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        'StyleX styles for customization (color, size, opacity). Folded into the icon\'s own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.',
+        "StyleX styles for customization (color, size, opacity). Folded into the icon's own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.",
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-icon', visualProps: ['color', 'size']},
-    ],
+    targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
   },
   usage: {
-    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    description:
+      'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    anatomy,
     bestPractices: [
-      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
-      { guidance: true, description: "Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam." },
-      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
-      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
-      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
-      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
-      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
-      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
-      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
-      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
+      {
+        guidance: true,
+        description:
+          'Use semantic icon names when available; they adapt to theme changes automatically.',
+      },
+      {
+        guidance: true,
+        description:
+          "Override icons through the theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>, and extends shallow-merges it into derived themes. registerIcons() mutates a process-wide registry and warns in dev, so keep it for app bootstrap rather than making it a library's theming seam.",
+      },
+      {
+        guidance: true,
+        description:
+          'Pair icons with text labels for accessibility; icon-only elements need an accessible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use color tokens for icon colors, not hardcoded hex values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Be mindful of context; decorative icons in compact components can distract rather than help.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use icons as the sole means of conveying meaning; always provide a text alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Resize icons with arbitrary pixel values; use the provided size props.',
+      },
+      {
+        guidance: false,
+        description:
+          'Mix icon styles (e.g. outline and filled) within the same context.',
+      },
+      {
+        guidance: false,
+        description:
+          'Render raw SVG elements; always wrap in Icon for consistent sizing and color.',
+      },
+      {
+        guidance: false,
+        description:
+          'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.',
+      },
     ],
   },
 };
@@ -77,7 +140,8 @@ export const docsZh = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+      description:
+        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
@@ -95,7 +159,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
+      description:
+        '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
     },
     {
       name: 'xstyle',
@@ -105,22 +170,57 @@ export const docsZh = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-icon', visualProps: ['color', 'size']},
-    ],
+    targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
   },
   usage: {
-    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    description:
+      'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
-      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
-      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
-      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
-      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
-      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
-      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
-      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
-      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
+      {
+        guidance: true,
+        description:
+          'Use semantic icon names when available; they adapt to theme changes automatically.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair icons with text labels for accessibility; icon-only elements need an accessible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use color tokens for icon colors, not hardcoded hex values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Be mindful of context; decorative icons in compact components can distract rather than help.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use icons as the sole means of conveying meaning; always provide a text alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Resize icons with arbitrary pixel values; use the provided size props.',
+      },
+      {
+        guidance: false,
+        description:
+          'Mix icon styles (e.g. outline and filled) within the same context.',
+      },
+      {
+        guidance: false,
+        description:
+          'Render raw SVG elements; always wrap in Icon for consistent sizing and color.',
+      },
+      {
+        guidance: false,
+        description:
+          'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.',
+      },
     ],
   },
 };
@@ -130,26 +230,74 @@ export const docsDense = {
   description:
     'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
   usage: {
-    description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    description:
+      'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
+    anatomy,
     bestPractices: [
-      { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
-      { guidance: true, description: "Override icons via theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>; extends shallow-merges into derived themes. registerIcons() mutates a global registry and warns in dev: app bootstrap only, not a library theming seam." },
-      { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
-      { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), set an accessible name via `label`: sets role="img" + aria-label, unhides icon.' },
-      { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
-      { guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },
-      { guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },
-      { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
-      { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
-      { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: '`name` prop, which does not exist. Use `icon` to specify which icon to render.' },
+      {
+        guidance: true,
+        description:
+          'Use semantic icon names when available; they adapt to theme changes automatically.',
+      },
+      {
+        guidance: true,
+        description:
+          'Override icons via theme, not globally: defineTheme({icons: {close: <XMarkIcon />}}) scopes the swap to the active <Theme>; extends shallow-merges into derived themes. registerIcons() mutates a global registry and warns in dev: app bootstrap only, not a library theming seam.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair icons with text labels for accessibility; icon-only elements need an accessible label.',
+      },
+      {
+        guidance: true,
+        description:
+          'For a meaningful standalone icon (no adjacent text), set an accessible name via `label`: sets role="img" + aria-label, unhides icon.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use color tokens for icon colors, not hardcoded hex values.',
+      },
+      {
+        guidance: true,
+        description:
+          'Be mindful of context; decorative icons in compact components can distract rather than help.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use icons as the sole means of conveying meaning; always provide a text alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Resize icons with arbitrary pixel values; use the provided size props.',
+      },
+      {
+        guidance: false,
+        description:
+          'Mix icon styles (e.g. outline and filled) within the same context.',
+      },
+      {
+        guidance: false,
+        description:
+          'Render raw SVG elements; always wrap in Icon for consistent sizing and color.',
+      },
+      {
+        guidance: false,
+        description:
+          '`name` prop, which does not exist. Use `icon` to specify which icon to render.',
+      },
     ],
   },
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
-    label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
-    xstyle: 'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
+    label:
+      'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
+    xstyle:
+      'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
   },
 };

package/src/Icon/Icon.spec.md

@@ -0,0 +1,191 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Icon
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by: [packages/core/src/Icon/Icon.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:icon-resolution-and-component-slots,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Icon component contract
+
+## Intent
+
+Icon presents one visual symbol with consistent size, color, and accessibility
+semantics. Consumer usage remains documented in `Icon.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling, and
+  public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none; this record characterizes the released component
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Accepting a semantic icon key or a supplied icon component as the glyph source.
+- Applying Icon's size, color, theming target, and accessibility semantics to
+  the rendered glyph.
+
+**Does not own / non-goals**
+
+- The shared registry's key-resolution and fallback order — owned by the shared
+  icon system.
+- The meaning of a glyph in product context or whether nearby text makes it
+  decorative — owned by the product callsite.
+- Interaction, focus, or control naming — owned by the interactive parent.
+- The artwork supplied by a consumer or registered through a theme.
+
+## Public concepts
+
+| Concept       | Closed values or states                                   | Meaning                                                   | Availability by variant/orientation/state | Default    | Owner            | Stability | Invalid-value behavior                                 |
+| ------------- | --------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ---------- | ---------------- | --------- | ------------------------------------------------------ |
+| Glyph source  | semantic key, namespaced extension key, or icon component | Selects the visual symbol.                                | Every render                              | Required   | `component:Icon` | Stable    | TypeScript rejects unsupported built-in string values. |
+| Size          | `xsm`, `sm`, `md`, `lg`                                   | Selects the icon box size.                                | Every rendered glyph                      | `md`       | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Color         | documented semantic and palette values                    | Selects the glyph color or inherits it from context.      | Every rendered glyph                      | `inherit`  | `component:Icon` | Stable    | TypeScript rejects unsupported values.                 |
+| Accessibility | decorative or meaningfully labelled                       | Controls whether assistive technology receives the glyph. | Every rendered glyph                      | Decorative | `component:Icon` | Stable    | Empty labels use the decorative behavior.              |
+
+A namespaced key that does not resolve currently renders nothing. This is
+existing behavior, not an intentional fallback promise.
+
+## Behavioral and layout contract
+
+Requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                               | Basis                                      | Draft review state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------- |
+| FR1 | Icon MUST present at most one glyph from the supplied semantic key, namespaced key, or icon component.                                                                                            | Documented promise and current tests.      | Settled intent.                                         |
+| FR2 | Every rendered glyph MUST carry the `icon` theming target with its selected size and color reflected as target data.                                                                              | Current source, docs, and theming tests.   | Settled intent.                                         |
+| FR3 | Icon MUST apply the selected size as width and height for every glyph, plus font size where needed for 1em-based icon sources. This sizing contract MUST NOT promise an HTML or SVG element type. | Human decision, current source, and tests. | Settled intent.                                         |
+| FR4 | Supported SVG and styling escape hatches MUST retain their established merge and override behavior.                                                                                               | Current source and regression tests.       | Current compatibility behavior; verify before changing. |
+
+### Allowed variation
+
+- **AV1 — Artwork.** The path, view box, and internal structure may vary by icon
+  source or theme without changing Icon's one-part consumer anatomy.
+- **AV2 — Rendering strategy.** Icon may render a supplied component directly or
+  use an internal wrapper for a resolved key; neither element shape is public
+  anatomy.
+- **AV3 — Theme and consumer styling.** Existing theme and styling escape hatches
+  may change visual CSS properties without changing glyph ownership.
+
+### Representative states
+
+| State                     | Required invariant                                    | Allowed variation                              |
+| ------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| Semantic key              | One resolved glyph carries the `icon` target.         | Theme, registry, or built-in artwork.          |
+| Namespaced extension key  | A resolved extension glyph carries the `icon` target. | Consumer- or library-owned artwork.            |
+| Supplied icon component   | The supplied glyph carries the `icon` target.         | Component implementation and SVG internals.    |
+| Unresolved namespaced key | No glyph is currently rendered.                       | No fallback behavior is established by intent. |
+
+### Transformation and precedence order
+
+- **ORD1 — Presentation.** Apply the target, component size and color styles,
+  then merge consumer `xstyle`, `className`, inline `style`, and supported
+  pass-through props in their established order.
+
+### Performance and resources
+
+- **PR1 — Render work.** Icon owns no listeners, observers, or layout
+  measurement; semantic resolution is synchronous during render.
+
+## Accessibility contract
+
+- **AR1 — Decorative default.** Without a non-empty `label`, Icon MUST hide its
+  glyph from assistive technology by default.
+- **AR2 — Meaningful glyph.** A non-empty `label` MUST expose the glyph as an
+  image with that accessible name.
+- **AR3 — Parent-owned interaction.** Icon MUST NOT add interactive semantics or
+  focus behavior; an interactive parent owns the control and its name.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                  | Representation authority                                      | Hierarchy role    | Component contract |
+| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- | ------------------ |
+| Glyph            | Carries the selected visual symbol at the requested size and color. | Consumer or registry selects artwork; Icon owns presentation. | Context-dependent | FR1, FR2, FR3      |
+
+`Glyph` is the single conceptual consumer part in both source modes. Current
+implementation may render a supplied icon component directly or place a
+registry-resolved icon in an internal wrapper; this contract intentionally does
+not promise a `span`, `svg`, or other element type.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Glyph": {"target": "icon"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns the qualification and validation
+  rules for the `icon` target.
+- `architecture:icon-resolution-and-component-slots` owns semantic-key and
+  component-slot resolution before Icon renders the selected source.
+- `architecture:public-component-api` owns admission and compatibility rules for
+  Icon's public props.
+- Icon has no current family contract.
+
+## Verification map
+
+| Contract            | Verification                                                 | Representative states                         | Mutation or failure expectation                                                                                                                            | Audit section              |
+| ------------------- | ------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3            | `Icon.test.tsx` source-mode and sizing suites                | Built-in, themed, namespaced, component       | Breaking source rendering or cross-mode sizing fails assertions.                                                                                           | `audit:Icon/behavior`      |
+| FR2, FR4            | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants    | Removing the target or breaking override composition fails existing assertions; `data-size` and `data-color` reflection currently lack focused assertions. | `audit:Icon/theming`       |
+| AR1, AR2, AR3       | `Icon.test.tsx` accessible-name suites                       | Decorative, labelled, explicit ARIA override  | Changing default or labelled semantics fails accessibility assertions.                                                                                     | `audit:Icon/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                    | `audit:Icon/theming`       |
+
+Focused coverage for `data-size` and `data-color` on both glyph source modes is
+a checkable test gap; source inspection is the current evidence for that part of
+FR2.
+
+## Decision log
+
+### DEC-1 — One conceptual Glyph across source modes
+
+**Reference:** `component:Icon/DEC-1`
+**Decider:** cixzhang, 2026-08-30
+
+Consumers theme and reason about one visual symbol regardless of whether it
+comes from a semantic key or a supplied component. `Glyph` therefore maps to the
+existing `icon` target without freezing either mode's current element shape.
+Icon applies width and height for every source and adds font size where a 1em-
+based source needs it. This preserves one consistent icon box without promising
+a `span`, `svg`, or other element.
+
+Rejected: separate wrapper and SVG anatomy entries, because those describe
+implementation strategies rather than stable consumer concepts.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.

package/src/IconButton/IconButton.doc.mjs

@@ -74,6 +74,44 @@ export const docs = {
 
   usage: {
     description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+    accessibility: [
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Loading'],
+        description:
+          'IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading.',
+      },
+      {
+        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.',
+      },
+      {
+        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 the red outline on destructive buttons too.',
+      },
+      {
+        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: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
       { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },

package/src/Indicator/Indicator.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'Indicator',
   displayName: 'Indicator',
   group: 'Indicator',
-  category: 'Data Input',
+  category: 'Form Controls',
   isHiddenFromOverview: true,
   keywords: [
     'indicator',

package/src/InputGroup/InputGroup.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'InputGroup',
   displayName: 'Input Group',
   group: 'Field',
-  category: 'Data Input',
+  category: 'Form Controls',
   isHiddenFromOverview: true,
   keywords: [
     'inputgroup',

package/src/Kbd/Kbd.doc.mjs

@@ -1,5 +1,20 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Shortcut',
+    required: true,
+    description:
+      'Group that presents the complete keyboard shortcut and its accessible name.',
+  },
+  {
+    name: 'Key badge',
+    required: true,
+    description: 'Painted key badge rendered once for each key in the shortcut.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -38,6 +53,7 @@ export const docs = {
     targets: [{className: 'astryx-kbd'}],
   },
   usage: {
+    anatomy,
     description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
     bestPractices: [
       { guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },
@@ -82,6 +98,7 @@ export const docsZh = {
     targets: [{className: 'astryx-kbd'}],
   },
   usage: {
+    anatomy,
     description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
     bestPractices: [
       { guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },
@@ -96,6 +113,7 @@ export const docsDense = {
   description:
     'Renders keyboard shortcut as styled key badges. Use in tooltips, menus + help text to show key combinations.',
   usage: {
+    anatomy,
     description: 'Renders a keyboard shortcut as styled key badges. Use Kbd in tooltips, menus, and help text to show key combinations.',
     bestPractices: [
       { guidance: true, description: 'Place shortcuts near the action they trigger: in a tooltip, menu item, or inline instruction.' },