gd-design-library 1.8.2 → 1.8.3

package/ai/README.md

@@ -419,6 +419,53 @@ const simpleComponents = componentIndex.byComplexity.Low;
 const formComponents = componentIndex.byFeature['Forms'];
 ```
 
+## Figma Token Maps
+
+Purpose-built reverse-lookup tables at `$GD_PATH/ai/figma-maps/`. Load before any Figma-to-code or Figma-to-A2UI task that involves translating Figma inspection output (hex values, px values, variable names, shadow strings, icon names) into GridKit design tokens.
+
+Each JSON file has a top-level `$usage` key documenting the exact lookup algorithm and critical rules for that category. Full resolution rules are in `.claude/rules/gd-design-rag-resolution.md`.
+
+### Quick-Reference Table
+
+| File                     | Use for                                                                                    | Primary lookup                |
+| ------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------- |
+| `figma-color-map.json`   | Figma `gds.color.*` variable or raw hex → color token + `themeAccess`                      | `hexIndex["#RRGGBB"]`         |
+| `figma-spacing-map.json` | Figma `gds.spacing/space/scale.*` or px → spacing token + `scaleDecisionGuide`             | `pxIndex["16px"]`             |
+| `figma-radius-map.json`  | Figma `gds.border.radius.*` or px/% → `radius.*` token                                     | `pxIndex["4px"]`              |
+| `figma-font-map.json`    | Figma `gds.font.*` or typography value → `font.*` token; includes `knownGaps`              | `valueIndex.fontSize["20px"]` |
+| `figma-shadow-map.json`  | Figma shadow style or CSS value → `shadows.*` token; `elevationDecisionGuide` for UI roles | `valueIndex["0px 2px..."]`    |
+| `figma-icon-map.json`    | Figma Material icon name ↔ GridKit `IconsList` key                                         | `figmaNameIndex["close"]`     |
+
+### Resolution Priority
+
+1. **CSS var name** — `var(--gds-color-text-default, ...)` → strip `--gds-`, kebab→dot → `color.text.default`.
+2. **Figma variable name** — CamelCase split: `borderRadiusXL` → `radius.xl`, `fontSizeH5` → `font.size.h5`.
+3. **Value reverse-lookup** — query `hexIndex` / `pxIndex` / `valueIndex` in the appropriate map file.
+4. **No match** — record `"unmatched:<rawValue>"` in `tokenBindings`.
+
+### Critical Cross-Category Rules
+
+- **Never emit `cssVar` or `var(--gds-*)` strings in TSX.** Always use `themeAccess` from `useTheme()`.
+- **`lineHeight` token is 3 levels deep**: `font.line.height.h5` → `theme.font?.line?.height?.h5`. Never `theme.font?.lineHeight?.h5`.
+- **Font tokens have no CSS vars** — use raw CSS value in `styling`; token dot-path in `tokenBindings`.
+- **Shadow design drift** (levels 1–3): Figma raw value ≠ token multi-layer value. Token is canonical.
+- **`#FFFFFF` → `color.bg.surface`** — not unmatched white. Always run `hexIndex` before declaring no match.
+
+### Importing Maps
+
+```typescript
+import { FIGMA_TOKEN_MAPS, FIGMA_COLOR_MAP, FIGMA_SPACING_MAP } from 'gd-design-library/ai/figma-maps';
+
+// All maps as a grouped object
+const { color, spacing, radius, font, shadow, icon } = FIGMA_TOKEN_MAPS;
+
+// Direct hex → token lookup
+const tokenPath = FIGMA_COLOR_MAP.hexIndex['#FFFFFF']; // → "color.bg.surface"
+
+// Spacing px → token lookup
+const { preferred } = FIGMA_SPACING_MAP.pxIndex['16px']; // → "spacing.md"
+```
+
 ## Usage Examples
 
 ### Contextual Prompt with Specific Components
@@ -515,6 +562,14 @@ yarn test:ai:watch
 │   ├── prompts.test.ts
 │   ├── schemas.test.ts
 │   └── validation.test.ts
+├── figma-maps/                        # Figma → GridKit token reverse-lookup tables
+│   ├── figma-color-map.json           # Figma gds.color.* vars + hex → color.* token + themeAccess
+│   ├── figma-spacing-map.json         # Figma gds.spacing/space/scale vars + px → spacing token + scaleDecisionGuide
+│   ├── figma-radius-map.json          # Figma gds.border.radius.* vars + px/% → radius.* token
+│   ├── figma-font-map.json            # Figma gds.font.* vars + values → font.* token; knownGaps list
+│   ├── figma-shadow-map.json          # Figma shadow styles + CSS values → shadows.box.*/semantic; elevationDecisionGuide
+│   ├── figma-icon-map.json            # GridKit IconsList keys ↔ Figma Material icon names; figmaNameIndex
+│   └── index.ts                       # Barrel exports (FIGMA_COLOR_MAP, FIGMA_SPACING_MAP, …, FIGMA_TOKEN_MAPS)
 ├── schemas/
 │   ├── components/                    # Component schemas (55 files)
 │   │   ├── Button.ts
@@ -539,7 +594,7 @@ yarn test:ai:watch
 
 <!-- AUTO-GENERATED:COMPONENTS:START -->
 
-_66 components total — generated from `libs/ui/src/ai/schemas/` on 2026-05-05._
+_66 components total — generated from `libs/ui/src/ai/schemas/` on 2026-06-23._
 
 ### Other
 
@@ -881,7 +936,7 @@ Versatile form input component supporting multiple field types including text, e
 | `disabled`    | `boolean`                                                                                                                                                                                       | Whether the input is disabled                                              |
 | `readOnly`    | `boolean`                                                                                                                                                                                       | Whether the input is read-only                                             |
 | `helpText`    | `string`                                                                                                                                                                                        | Helper text shown below the field (e.g. format hints, validation messages) |
-| _...+8 more_  |                                                                                                                                                                                                 |                                                                            |
+| _...+10 more_ |                                                                                                                                                                                                 |                                                                            |
 
 **Example:**
 
@@ -993,22 +1048,22 @@ Range input component for selecting numeric values within a defined range with v
 Toggle switch for binary on/off states. Ideal for settings, preferences, and feature toggles.
 
 <!-- prettier-ignore -->
-| Prop        | Type                  | Description                                                                            |
-| ----------- | --------------------- | -------------------------------------------------------------------------------------- |
-| `checked`   | `boolean`             | Checked/on state of the switch (controlled)                                            |
-| `disabled`  | `boolean`             | Whether the switch is disabled                                                         |
-| `isLoading` | `boolean`             | Shows a loading overlay on the switch and disables interaction during async operations |
-| `label`     | `string`              | Visible text label rendered next to the switch.                                        |
-| `labelSide` | `"left"` \| `"right"` | Label position relative to the switch toggle                                           |
-| `name`      | `string`              | HTML name attribute for form submission                                                |
-| `styling`   | `object`              | CSS style overrides for the switch                                                     |
-| `actions`   | `string[]`            | Action IDs from ui.actions to trigger on toggle                                        |
+| Prop        | Type                  | Description                                                                                                                                                          |
+| ----------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`   | `boolean`             | Checked/on state of the switch (controlled)                                                                                                                          |
+| `disabled`  | `boolean`             | Whether the switch is disabled                                                                                                                                       |
+| `isLoading` | `boolean`             | Shows a loading overlay on the switch and disables interaction during async operations                                                                               |
+| `value`     | `string`              | Text label content displayed next to the switch toggle (rendered as children).                                                                                       |
+| `label`     | `"left"` \| `"right"` | LabelPosition — which side of the toggle the text appears on. Valid values: "left" \| "right" (default "right"). NEVER use this for text content; put text in value. |
+| `name`      | `string`              | HTML name attribute for form submission                                                                                                                              |
+| `styling`   | `object`              | CSS style overrides for the switch                                                                                                                                   |
+| `actions`   | `string[]`            | Action IDs from ui.actions to trigger on toggle                                                                                                                      |
 
 **Example:**
 
 <!-- prettier-ignore -->
 ```tsx
-<Switch checked={isEnabled} onValueChange={setIsEnabled}>Enable notifications</Switch>
+{ "type": "switch", "id": "notifications_switch", "value": "Enable notifications" }
 ```
 
 #### Toggle
@@ -1158,7 +1213,7 @@ Radio button group component for single selection from multiple options with fle
 
 **Complexity:** Low | **Import:** `import { Checkbox } from 'gd-design-library'`
 
-Standalone checkbox atom with indeterminate state, size variants, and accessible labeling. Use for boolean toggles in forms and settings.
+Standalone checkbox atom with indeterminate state, size variants, and accessible labeling. Use for boolean toggles in forms and settings. In A2UI specs, represent checkboxes as { type: "input", variant: "checkbox" } — do NOT emit { type: "checkbox" }.
 
 <!-- prettier-ignore -->
 | Prop            | Type             | Description                                                      |
@@ -1210,20 +1265,20 @@ Multi-line text input organism with auto-growing rows, character count, attachme
 
 **Complexity:** Low | **Import:** `import { AttachmentFile } from 'gd-design-library'`
 
-File attachment chip that displays a selected file with its name, optional type and size metadata, and a remove action. Long file names truncate with ellipsis and show a tooltip on hover; long fileType values truncate with ellipsis. The separator between fileType and fileSize defaults to "·" and is configurable. Designed to render as a child of InputArea above the textarea, or standalone in any file-selection context.
+File attachment chip: file-copy icon on the left, bold file name (truncates with tooltip on hover), optional small metadata row (fileType · fileSize, both truncate), and a close/remove (×) button on the right. Horizontal inline chip, typically 40–48 px tall with rounded corners. Renders above the InputArea textarea or standalone. Use actions[] to wire the remove button in A2UI; in TSX use onRemove. Figma component set names: "AttachmentFile", "Attachment File", "File Chip", "File Tag", "attachment-chip". Also matches any chip/pill node that contains a file name + a remove/close affordance.
 
 <!-- prettier-ignore -->
-| Prop                | Type         | Description                                                                                                      |
-| ------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `fileName`          | `string`     | Name of the attached file displayed in the chip                                                                  |
-| `fileType`          | `string`     | File type label shown below the file name (e.g. "PDF", "doc")                                                    |
-| `fileSize`          | `string`     | File size label shown below the file name (e.g. "1.2 MB")                                                        |
-| `separator`         | `string`     | Character rendered between fileType and fileSize in the meta row                                                 |
-| `fileIcon`          | `ReactNode`  | Custom icon replacing the default fileCopy icon. Use an Icon component sized xl (32px).                          |
-| `onRemove`          | `() => void` | Callback fired when the remove button is clicked. The remove button is only rendered when this prop is provided. |
-| `removeButtonLabel` | `string`     | Accessible aria-label for the remove button                                                                      |
-| `disabled`          | `boolean`    | Disables the remove button                                                                                       |
-| _...+2 more_        |              |                                                                                                                  |
+| Prop                | Type       | Description                                                                                                                                                                                                                                                                                      |
+| ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fileName`          | `string`   | Name of the attached file displayed in the chip. Truncates with a tooltip on hover when long. Required.                                                                                                                                                                                          |
+| `fileType`          | `string`   | File type label shown below the file name (e.g. "PDF", "doc"). Truncates with ellipsis when long.                                                                                                                                                                                                |
+| `fileSize`          | `string`   | File size label shown below the file name (e.g. "1.2 MB").                                                                                                                                                                                                                                       |
+| `separator`         | `string`   | Character rendered between fileType and fileSize in the metadata row. Defaults to "·". Override for designs that use "/" or "\|".                                                                                                                                                                |
+| `actions`           | `string[]` | Action IDs from ui.actions to trigger when the remove (×) button is clicked. The remove button is only rendered when this array is non-empty. In TSX this maps to onRemove. Example: set actions: ["remove_notes_txt"] and define { id: "remove_notes_txt", type: "remove-file" } in ui.actions. |
+| `removeButtonLabel` | `string`   | Accessible aria-label for the remove button.                                                                                                                                                                                                                                                     |
+| `disabled`          | `boolean`  | Disables the remove button, preventing file removal.                                                                                                                                                                                                                                             |
+| `isLoading`         | `boolean`  | Shows a spinner in place of the remove button while the file is uploading. Only takes effect when actions[] is also provided (TSX: when onRemove is set).                                                                                                                                        |
+| _...+1 more_        |            |                                                                                                                                                                                                                                                                                                  |
 
 **Example:**
 
@@ -1292,16 +1347,16 @@ Chat message bubble component for displaying conversation messages with distinct
 All text: headings (h1–h6), body paragraphs, caption-styled metadata, code snippets. Accepts box model props (margin, padding, width) directly — no wrapper needed. IMPORTANT: variant="caption" renders a real <caption> element by default, so outside table captions pair it with as="div" or as="span".
 
 <!-- prettier-ignore -->
-| Prop           | Type                                                                                                                                                                                                   | Description                                                                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label`        | `string`                                                                                                                                                                                               | Text content to display (also accepted as value)                                                                                                                        |
-| `variant`      | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"p"` \| `"span"` \| `"small"` \| `"strong"` \| `"i"` \| `"code"` \| `"kbd"` \| `"caption"` \| `"header"` \| `"sup"` \| `"sub"` \| `"div"` | Semantic HTML element and typography style variant. IMPORTANT: variant="caption" renders a real <caption> element by default; outside tables use as="div" or as="span". |
-| `color`        | `string`                                                                                                                                                                                               | Text color. Prefer theme color token paths (e.g. "text.secondary", "text.warning", "text.default"). Use raw CSS/hex only when no theme token fits.                      |
-| `align`        | `"start"` \| `"end"` \| `"left"` \| `"center"` \| `"right"` \| `"justify"`                                                                                                                             | Text alignment                                                                                                                                                          |
-| `styleVariant` | `"bold"` \| `"semibold"` \| `"normal"` \| `"light"` \| `"italic"` \| `"small"` \| `"underline"` \| `"uppercase"` \| `"lowercase"` \| `"strike"`                                                        | Additional style modifiers (can be combined as array)                                                                                                                   |
-| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                                                                                                                                         | Size override for the text                                                                                                                                              |
-| `as`           | `string`                                                                                                                                                                                               | Override the rendered HTML element (e.g. render h2 styles on an h1 element). Use as="div" or as="span" with variant="caption" outside table captions.                   |
-| `styling`      | `object`                                                                                                                                                                                               | CSS style overrides including textAlign, color, and other CSS properties                                                                                                |
+| Prop           | Type                                                                                                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`        | `string`                                                                                                                                                                                               | Text content to display (also accepted as value)                                                                                                                                                                                                                                                                                                                            |
+| `variant`      | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` \| `"p"` \| `"span"` \| `"small"` \| `"strong"` \| `"i"` \| `"code"` \| `"kbd"` \| `"caption"` \| `"header"` \| `"sup"` \| `"sub"` \| `"div"` | Semantic HTML element. Valid values: h1\|h2\|h3\|h4\|h5\|h6\|p\|span\|small\|strong\|i\|code\|kbd\|caption\|header\|sup\|sub\|div. NEVER use body1, body2, inherit, display, subtitle1, subtitle2 — these are enum key names, not valid variant values. IMPORTANT: variant="caption" renders a real <caption> element by default; outside tables use as="div" or as="span". |
+| `color`        | `string`                                                                                                                                                                                               | Text color. Prefer theme color token paths (e.g. "text.secondary", "text.warning", "text.default"). Use raw CSS/hex only when no theme token fits.                                                                                                                                                                                                                          |
+| `align`        | `"start"` \| `"end"` \| `"left"` \| `"center"` \| `"right"` \| `"justify"`                                                                                                                             | Text alignment                                                                                                                                                                                                                                                                                                                                                              |
+| `styleVariant` | `"bold"` \| `"semibold"` \| `"normal"` \| `"light"` \| `"italic"` \| `"small"` \| `"underline"` \| `"uppercase"` \| `"lowercase"` \| `"strike"`                                                        | Additional style modifiers (can be combined as array)                                                                                                                                                                                                                                                                                                                       |
+| `size`         | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"`                                                                                                                                                         | Size override for the text                                                                                                                                                                                                                                                                                                                                                  |
+| `as`           | `string`                                                                                                                                                                                               | Override the rendered HTML element (e.g. render h2 styles on an h1 element). Use as="div" or as="span" with variant="caption" outside table captions.                                                                                                                                                                                                                       |
+| `styling`      | `object`                                                                                                                                                                                               | CSS style overrides including textAlign, color, and other CSS properties                                                                                                                                                                                                                                                                                                    |
 
 **Example:**
 
@@ -1350,12 +1405,12 @@ Composite avatar component that displays a user with avatar image, name, optiona
 | `name`        | `string`                                       | Primary user display name shown next to or below the avatar. When src is omitted, the A2UI renderer derives initials from this name. |
 | `variant`     | `"card"` \| `"profile"`                        | Layout variant of the component                                                                                                      |
 | `subtitle`    | `string`                                       | Secondary line of text beneath the name, such as a role, team, or email address                                                      |
+| `description` | `string`                                       | Fallback subtitle text. Used when subtitle is absent — the renderer promotes description to the subtitle slot automatically.         |
 | `src`         | `string`                                       | URL of the avatar image                                                                                                              |
 | `alt`         | `string`                                       | Alt text for the avatar image                                                                                                        |
-| `sizeVariant` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Avatar size variant. A2UI also accepts the shared top-level "size" alias.                                                            |
-| `withBadge`   | `boolean`                                      | Whether to show a presence/status badge dot                                                                                          |
-| `badgeColor`  | `string`                                       | Badge dot color. Prefer theme color token paths (for example "bg.fill.success.primary.default") before raw CSS/hex colors.           |
-| _...+6 more_  |                                                |                                                                                                                                      |
+| `size`        | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Avatar size. Preferred A2UI field — use this over sizeVariant for consistency with the Avatar component.                             |
+| `sizeVariant` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Avatar size variant. Alias for size — both are accepted; size is preferred in A2UI specs.                                            |
+| _...+9 more_  |                                                |                                                                                                                                      |
 
 **Example:**
 
@@ -1433,17 +1488,17 @@ Text truncation component that limits content to a specified number of lines usi
 Clickable button with multiple style variants (primary, secondary, tertiary, outlined, text). Use actions[] to wire up A2UI interactions.
 
 <!-- prettier-ignore -->
-| Prop         | Type                                                                                    | Description                                               |
-| ------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `label`      | `string`                                                                                | Button text content (maps to children)                    |
-| `variant`    | `"primary"` \| `"secondary"` \| `"tertiary"` \| `"outlined"` \| `"text"` \| `"inherit"` | Visual style variant of the button                        |
-| `disabled`   | `boolean`                                                                               | Disables the button preventing interaction                |
-| `isLoading`  | `boolean`                                                                               | Shows a loading spinner inside the button and disables it |
-| `fullWidth`  | `boolean`                                                                               | Makes the button fill the full width of its container     |
-| `isIcon`     | `boolean`                                                                               | Renders the button as a square icon-only button (no text) |
-| `icon`       | `string`                                                                                | Leading icon name from the shared A2UI icon catalog.      |
-| `iconEnd`    | `string`                                                                                | Trailing icon name from the shared A2UI icon catalog.     |
-| _...+5 more_ |                                                                                         |                                                           |
+| Prop         | Type                                                                                    | Description                                                                                                                                                                                                                                        |
+| ------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`                                                                                | Button text content (maps to children)                                                                                                                                                                                                             |
+| `variant`    | `"primary"` \| `"secondary"` \| `"tertiary"` \| `"outlined"` \| `"text"` \| `"inherit"` | Visual style variant of the button. Valid ButtonVariant values (always lowercase): primary\|secondary\|tertiary\|outlined\|text\|inherit. NEVER use capitalized forms (Primary, Secondary…) or non-existent variants (danger, contained, default). |
+| `disabled`   | `boolean`                                                                               | Disables the button preventing interaction                                                                                                                                                                                                         |
+| `isLoading`  | `boolean`                                                                               | Shows a loading spinner inside the button and disables it                                                                                                                                                                                          |
+| `fullWidth`  | `boolean`                                                                               | Makes the button fill the full width of its container                                                                                                                                                                                              |
+| `isIcon`     | `boolean`                                                                               | Renders the button as a square icon-only button (no text)                                                                                                                                                                                          |
+| `icon`       | `string`                                                                                | Leading icon name from the shared A2UI icon catalog.                                                                                                                                                                                               |
+| `iconEnd`    | `string`                                                                                | Trailing icon name from the shared A2UI icon catalog.                                                                                                                                                                                              |
+| _...+7 more_ |                                                                                         |                                                                                                                                                                                                                                                    |
 
 **Example:**
 
@@ -1458,7 +1513,7 @@ Clickable button with multiple style variants (primary, secondary, tertiary, out
 
 **Complexity:** Low | **Import:** `import { Link } from 'gd-design-library'`
 
-Accessible anchor component for navigation with support for internal and absolute URL destinations, multiple visual variants, and proper security attributes. A2UI SPEC: use top-level "label" for text, plus top-level "href", "variant", "underline", "target", and "rel". Do NOT use "children" or put href inside "attributes". For custom hover colors, use the top-level "styling" object with standard CSS values.
+Accessible anchor component for navigation with support for internal and absolute URL destinations, multiple visual variants, and proper security attributes. A2UI SPEC: use top-level "label" for text, plus top-level "href", "variant", "underline", "target", and "rel". Do NOT use "children" or put href inside "attributes". For custom hover colors, use the top-level "styling" object with standard CSS values. Figma color tokens: gds.color.text.link → color.text.link.default (#53B7E8) for default link state; gds.color.text.link.hover → color.text.link.hover (#278CBF) — pass default via the top-level "color" prop and hover via styling["&:hover"].color.
 
 <!-- prettier-ignore -->
 | Prop         | Type                                                        | Description                                                                                                 |
@@ -1471,7 +1526,7 @@ Accessible anchor component for navigation with support for internal and absolut
 | `size`       | `"sm"` \| `"md"` \| `"lg"`                                  | Size variant of the link text. Top-level field in A2UI.                                                     |
 | `underline`  | `"default"` \| `"highlight"` \| `"none"`                    | Underline style for the link. Top-level field in A2UI.                                                      |
 | `disabled`   | `boolean`                                                   | Whether the link is disabled (prevents click interaction)                                                   |
-| _...+3 more_ |                                                             |                                                                                                             |
+| _...+7 more_ |                                                             |                                                                                                             |
 
 **Example:**
 
@@ -1754,17 +1809,17 @@ Responsive image component with loading states, fallback support, and optional c
 User avatar component for displaying profile pictures, initials, or icons with support for badges, fallback content, and various size options. A2UI SPEC: all props are top-level fields — do NOT use "attributes" or "fallbackComponent". Use "label" or "value" for initials text. Use "size" or "sizeVariant" for size. For an icon inside the avatar, set top-level "icon" plus optional "fill" or "fillSvg"; the renderer maps that to Avatar fallback content internally. For a status badge ON the avatar use withBadge + badgeColor directly on this component — do NOT place a separate "badge" or sibling "icon" next to the avatar. Prefer theme color tokens before raw CSS/hex. Example: {"type":"avatar","icon":"star","size":"xl","backgroundColor":"#cfaaa7","fill":"#646464"}.
 
 <!-- prettier-ignore -->
-| Prop         | Type                                           | Description                                                                                                                                                                                       |
-| ------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label`      | `string`                                       | A2UI: initials text shown as fallback (e.g. "JD"). Use label OR value — do NOT use "fallbackComponent".                                                                                           |
-| `src`        | `string`                                       | Image URL. Top-level field in A2UI spec.                                                                                                                                                          |
-| `alt`        | `string`                                       | Image alt text. Top-level field in A2UI spec.                                                                                                                                                     |
-| `size`       | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | A2UI size field (preferred). Alias: "sizeVariant" also accepted.                                                                                                                                  |
-| `withBadge`  | `boolean`                                      | Show status dot badge ON the avatar. Top-level field.                                                                                                                                             |
-| `badgeColor` | `string`                                       | Badge background color. Top-level field. Prefer theme color token paths (e.g. "bg.fill.success.primary.default", "bg.fill.error.primary.default"). Use raw CSS/hex only when no theme token fits. |
-| `icon`       | `string`                                       | A2UI-only avatar fallback icon name (for example "star" or "user"). This renders inside the avatar itself via the existing fallbackComponent behavior.                                            |
-| `fill`       | `string`                                       | Avatar fallback icon fill color. Prefer theme icon token paths (e.g. "icon.default", "icon.warning"). Use raw CSS/hex only when no theme token fits.                                              |
-| _...+4 more_ |                                                |                                                                                                                                                                                                   |
+| Prop          | Type                                           | Description                                                                                                                                                                                       |
+| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`       | `string`                                       | A2UI: initials text shown as fallback (e.g. "JD"). Use label OR value — do NOT use "fallbackComponent". Renderer checks label first, then value.                                                  |
+| `value`       | `string`                                       | Alias for label: initials text shown as avatar fallback when label is absent (e.g. "JD"). The renderer promotes value to the fallback slot automatically. Prefer label in new A2UI specs.         |
+| `src`         | `string`                                       | Image URL. Top-level field in A2UI spec.                                                                                                                                                          |
+| `alt`         | `string`                                       | Image alt text. Top-level field in A2UI spec.                                                                                                                                                     |
+| `size`        | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Avatar size. Preferred A2UI field — use this over sizeVariant.                                                                                                                                    |
+| `sizeVariant` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Avatar size variant. Alias for size — both are accepted; size is preferred in A2UI specs.                                                                                                         |
+| `withBadge`   | `boolean`                                      | Show status dot badge ON the avatar. Top-level field.                                                                                                                                             |
+| `badgeColor`  | `string`                                       | Badge background color. Top-level field. Prefer theme color token paths (e.g. "bg.fill.success.primary.default", "bg.fill.error.primary.default"). Use raw CSS/hex only when no theme token fits. |
+| _...+6 more_  |                                                |                                                                                                                                                                                                   |
 
 **Example:**
 

package/ai/a2ui/component-map.cjs

@@ -1 +1 @@
-const e=require(`../schemas/components/Icon.cjs`),t=require(`../schemas/components.cjs`);function n(e){let t={};for(let n of e){let e;e=n.enum&&n.enum.length>0?n.enum.map(e=>`"${e}"`).join(`|`):n.type,n.description&&(e+=` — ${n.description}`),t[n.name]=e}return t}function r(e,t){let n=[],r=e,i=!!e.a2uiName;if(t&&t.compositionTips.length>0&&n.push(...t.compositionTips),i)return n.length>0?n:void 0;let a=r.commonPatterns;if(a)for(let[e,t]of Object.entries(a)){let r=t.useCase??``,i=t.code?` Example: ${t.code}`:``;n.push(`${e}: ${r}${i}`)}let o=r.examples;if(Array.isArray(o))for(let e of o)typeof e==`string`&&n.push(e);let s=r.troubleshooting;if(s)for(let[e,t]of Object.entries(s))n.push(`Troubleshooting — ${e}: ${t}`);return n.length>0?n:void 0}function i(){let e={};for(let i of t.aiComponentsSchema.components){let a=i;if(!a.a2uiName)continue;let o=t.componentModulesByName.get(a.name);if(e[a.a2uiName]={component:a.name,import:a.import,description:a.description,props:n(a.props),notes:r(a,o),category:a.category,complexity:a.complexity},a.a2uiSubcomponents){let t=a.subcomponents;for(let[r,i]of Object.entries(a.a2uiSubcomponents)){let s=t?.[i.component]?.description??a.description;e[r]={component:i.component,import:a.import,description:s,props:n(i.props),notes:o&&o.compositionTips.length>0?o.compositionTips:void 0,category:a.category?`${a.category} Subcomponents`:`Card Subcomponents`,complexity:a.complexity}}}}return e}var a=i(),o=Object.keys(a),s=e.default.component.availableIcons,c=e.default.component.iconCatalog;function l(e,n){return t.aiComponentsSchema.components.find(t=>t.a2uiName===e)?.props.find(e=>e.name===n)?.enum??[]}var u=l(`button`,`variant`);function d(e){return a[e]?.component??`Unknown`}exports.A2UI_AVAILABLE_ICONS=s,exports.A2UI_BUTTON_VARIANTS=u,exports.A2UI_COMPONENT_MAP=a,exports.A2UI_COMPONENT_TYPES=o,exports.A2UI_ICON_CATALOG=c,exports.getA2UIPropEnum=l,exports.getGridKitComponent=d;
+const e=require("../schemas/components/Icon.cjs"),t=require("../schemas/components.cjs");function n(e){let t={};for(let n of e){let e;e=n.enum&&n.enum.length>0?n.enum.map(e=>`"${e}"`).join(`|`):n.type,n.description&&(e+=` — ${n.description}`),t[n.name]=e}return t}function r(e,t){let n=[],r=e,i=!!e.a2uiName;if(t&&t.compositionTips.length>0&&n.push(...t.compositionTips),i)return n.length>0?n:void 0;let a=r.commonPatterns;if(a)for(let[e,t]of Object.entries(a)){let r=t.useCase??``,i=t.code?` Example: ${t.code}`:``;n.push(`${e}: ${r}${i}`)}let o=r.examples;if(Array.isArray(o))for(let e of o)typeof e==`string`&&n.push(e);let s=r.troubleshooting;if(s)for(let[e,t]of Object.entries(s))n.push(`Troubleshooting — ${e}: ${t}`);return n.length>0?n:void 0}function i(){let e={};for(let i of t.aiComponentsSchema.components){let a=i;if(!a.a2uiName)continue;let o=t.componentModulesByName.get(a.name);if(e[a.a2uiName]={component:a.name,import:a.import,description:a.description,props:n(a.props),notes:r(a,o),category:a.category,complexity:a.complexity},a.a2uiSubcomponents){let t=a.subcomponents;for(let[r,i]of Object.entries(a.a2uiSubcomponents)){let s=t?.[i.component]?.description??a.description;e[r]={component:i.component,import:a.import,description:s,props:n(i.props),notes:o&&o.compositionTips.length>0?o.compositionTips:void 0,category:a.category?`${a.category} Subcomponents`:`Card Subcomponents`,complexity:a.complexity}}}}return e}var a=i(),o=Object.keys(a),s=e.default.component.availableIcons,c=e.default.component.iconCatalog;function l(e,n){return t.aiComponentsSchema.components.find(t=>t.a2uiName===e)?.props.find(e=>e.name===n)?.enum??[]}var u=l(`button`,`variant`);function d(e){return a[e]?.component??`Unknown`}exports.A2UI_AVAILABLE_ICONS=s,exports.A2UI_BUTTON_VARIANTS=u,exports.A2UI_COMPONENT_MAP=a,exports.A2UI_COMPONENT_TYPES=o,exports.A2UI_ICON_CATALOG=c,exports.getA2UIPropEnum=l,exports.getGridKitComponent=d;

package/ai/a2ui/component-map.d.cts

@@ -0,0 +1,138 @@
+import { default as IconSchemaModule } from '../schemas/components/Icon.js';
+export type A2UIComponentEntry = {
+    /** gd-design-library component name */
+    component: string;
+    /** npm import statement */
+    import: string;
+    /** Short description for LLM context */
+    description?: string;
+    /** Accepted prop shapes (descriptive strings for LLM consumption) */
+    props: Record<string, string>;
+    /**
+     * Unified guidance notes for the LLM — merged from all schema sources:
+     * compositionTips, commonPatterns use-case descriptions, examples, and
+     * troubleshooting tips.
+     */
+    notes?: string[];
+    /** Component category */
+    category?: string;
+    /** Component complexity level */
+    complexity?: string;
+};
+/**
+ * Complete A2UI type → GridKit component mapping.
+ * Every key is a valid A2UI component "type" value.
+ * Built from aiComponentsSchema — no manual duplication.
+ */
+export declare const A2UI_COMPONENT_MAP: Record<string, A2UIComponentEntry>;
+/**
+ * All valid A2UI component type strings.
+ * Generated from A2UI_COMPONENT_MAP keys.
+ */
+export declare const A2UI_COMPONENT_TYPES: (keyof typeof A2UI_COMPONENT_MAP)[];
+/**
+ * Available icon names for the "icon" component type.
+ * The label prop of an "icon" component MUST be one of these values.
+ * Source of truth: libs/ui/src/ai/schemas/components/Icon.ts → availableIcons
+ */
+export declare const A2UI_AVAILABLE_ICONS: readonly string[] & typeof IconSchemaModule.component.availableIcons;
+export type A2UIIconName = (typeof A2UI_AVAILABLE_ICONS)[number];
+/**
+ * Semantic usage guide for each icon, grouped by category.
+ * Source of truth: libs/ui/src/ai/schemas/components/Icon.ts → iconCatalog
+ */
+export declare const A2UI_ICON_CATALOG: {
+    'Status & Feedback': {
+        cross: string;
+        success: string;
+        error: string;
+        warning: string;
+        info: string;
+        dot: string;
+        check: string;
+        errorOutline: string;
+    };
+    'Navigation & Direction': {
+        arrowDown: string;
+        arrowRight: string;
+        arrowLeft: string;
+        arrowForward: string;
+        keyboardArrowDown: string;
+        keyboardArrowUp: string;
+    };
+    'UI & Interface': {
+        mobileMenu: string;
+        home: string;
+        slash: string;
+    };
+    'E-commerce & Shopping': {
+        localShipping: string;
+        favorite: string;
+        favoriteOutlined: string;
+        shoppingBag: string;
+        paymentCard: string;
+    };
+    'User & Account': {
+        accountCircle: string;
+        portrait: string;
+    };
+    'Actions & Operations': {
+        deleteOutlined: string;
+        minus: string;
+        plus: string;
+        edit: string;
+        search: string;
+        filter: string;
+        ruler: string;
+    };
+    'File & Document': {
+        attachment: string;
+        upload: string;
+        folder: string;
+        folderOpen: string;
+        contentCopy: string;
+        fileCopy: string;
+    };
+    'Media & Communication': {
+        eye: string;
+        volumeUp: string;
+        send: string;
+        mic: string;
+        chat: string;
+        chatBubble: string;
+        phone: string;
+    };
+    'System & Technical': {
+        processing: string;
+        wifiTethering: string;
+    };
+    'Rating & Feedback': {
+        star: string;
+        starOutlined: string;
+        starHalf: string;
+        thumbUp: string;
+        thumbDown: string;
+        thumbUpFilled: string;
+        thumbDownFilled: string;
+    };
+};
+export type A2UIIconCatalog = typeof A2UI_ICON_CATALOG;
+/**
+ * Get the enum values for a named prop of any A2UI component type.
+ * Works for any component — no per-component special exports needed.
+ *
+ * @example
+ * getA2UIPropEnum('button', 'variant')  // ['primary', 'secondary', ...]
+ * getA2UIPropEnum('badge', 'size')      // ['sm', 'md', 'lg']
+ */
+export declare function getA2UIPropEnum(a2uiType: string, propName: string): readonly string[];
+/**
+ * Valid Button variant values.
+ * Derived from the 'button' component's variant prop enum via getA2UIPropEnum.
+ */
+export declare const A2UI_BUTTON_VARIANTS: readonly string[];
+export type A2UIButtonVariant = (typeof A2UI_BUTTON_VARIANTS)[number];
+/**
+ * Get the GridKit component name for a given A2UI type.
+ */
+export declare function getGridKitComponent(a2uiType: string): string;

package/ai/a2ui/component-map.d.ts

@@ -1,4 +1,4 @@
-import { default as IconSchemaModule } from '../schemas/components/Icon';
+import { default as IconSchemaModule } from '../schemas/components/Icon.js';
 export type A2UIComponentEntry = {
     /** gd-design-library component name */
     component: string;

package/ai/a2ui/image-policy.d.cts

@@ -0,0 +1,7 @@
+export type A2UIImageSources = string | string[];
+/**
+ * Normalizes an `A2UIImageSources` value into a lowercase, trimmed string array.
+ * Returns `null` when `imageSources` is `undefined` (i.e. unconfigured — any host allowed).
+ * Returns an empty array when `imageSources` is an empty string or empty array (no hosts allowed).
+ */
+export declare function normalizeImageSources(imageSources?: A2UIImageSources): string[] | null;

package/ai/a2ui/index.d.cts

@@ -0,0 +1,22 @@
+/**
+ * A2UI Integration — GridKit Design System
+ *
+ * Tools for generating and rendering A2UI JSON specifications using
+ * gd-design-library (GridKit) React components.
+ *
+ * Two integration modes exist in libs/ui/src/ai:
+ *
+ *   1. CODE MODE (./prompts.ts)
+ *      LLM → React/TSX code using GridKit components.
+ *      Use buildClaudeSystemPrompt, buildGPT4Prompt, buildGeminiPrompt.
+ *
+ *   2. A2UI MODE (this module)
+ *      LLM → A2UI JSON spec → rendered by GridKit components at runtime.
+ *      Use buildA2UISystemPrompt, A2UI_SPEC_SCHEMA, A2UI_COMPONENT_MAP.
+ *
+ * A2UI protocol: https://a2ui.org
+ */
+export { A2UI_COMPONENT_MAP, A2UI_COMPONENT_TYPES, A2UI_AVAILABLE_ICONS, A2UI_ICON_CATALOG, A2UI_BUTTON_VARIANTS, getA2UIPropEnum, getGridKitComponent, type A2UIComponentEntry, type A2UIIconName, type A2UIIconCatalog, type A2UIButtonVariant, } from './component-map.js';
+export { A2UI_SPEC_SCHEMA, A2UI_SPEC_SCHEMA_SIMPLE, extendA2UISpecSchema, type A2UISpec, type A2UIMetadata, type A2UIComponent, type A2UIAction, type A2UIStyling, type A2UILayoutType, type A2UIVariant, type A2UIActionDefinition, type A2UICustomComponentMeta, } from './spec-schema.js';
+export { buildA2UISystemPrompt, buildA2UIGeminiRequest, type PriceFormatCustom, type A2UISystemPromptOptions, } from './system-prompt.js';
+export { type A2UIImageSources, normalizeImageSources } from './image-policy.js';

package/ai/a2ui/index.d.ts

@@ -16,7 +16,7 @@
  *
  * A2UI protocol: https://a2ui.org
  */
-export { A2UI_COMPONENT_MAP, A2UI_COMPONENT_TYPES, A2UI_AVAILABLE_ICONS, A2UI_ICON_CATALOG, A2UI_BUTTON_VARIANTS, getA2UIPropEnum, getGridKitComponent, type A2UIComponentEntry, type A2UIIconName, type A2UIIconCatalog, type A2UIButtonVariant, } from './component-map';
-export { A2UI_SPEC_SCHEMA, A2UI_SPEC_SCHEMA_SIMPLE, extendA2UISpecSchema, type A2UISpec, type A2UIMetadata, type A2UIComponent, type A2UIAction, type A2UIStyling, type A2UILayoutType, type A2UIVariant, type A2UIActionDefinition, type A2UICustomComponentMeta, } from './spec-schema';
-export { buildA2UISystemPrompt, buildA2UIGeminiRequest, type PriceFormatCustom, type A2UISystemPromptOptions, } from './system-prompt';
-export { type A2UIImageSources, normalizeImageSources } from './image-policy';
+export { A2UI_COMPONENT_MAP, A2UI_COMPONENT_TYPES, A2UI_AVAILABLE_ICONS, A2UI_ICON_CATALOG, A2UI_BUTTON_VARIANTS, getA2UIPropEnum, getGridKitComponent, type A2UIComponentEntry, type A2UIIconName, type A2UIIconCatalog, type A2UIButtonVariant, } from './component-map.js';
+export { A2UI_SPEC_SCHEMA, A2UI_SPEC_SCHEMA_SIMPLE, extendA2UISpecSchema, type A2UISpec, type A2UIMetadata, type A2UIComponent, type A2UIAction, type A2UIStyling, type A2UILayoutType, type A2UIVariant, type A2UIActionDefinition, type A2UICustomComponentMeta, } from './spec-schema.js';
+export { buildA2UISystemPrompt, buildA2UIGeminiRequest, type PriceFormatCustom, type A2UISystemPromptOptions, } from './system-prompt.js';
+export { type A2UIImageSources, normalizeImageSources } from './image-policy.js';