banhatten-ui 0.1.2 → 0.2.0

package/dist/CURSOR_RULE.md

@@ -0,0 +1,106 @@
+# Banhatten Design System — Library Customization Rule
+
+Use this rule to customize any UI library to match the Banhatten Design System.
+Copy this file into your project's `.cursor/rules/` directory.
+
+---
+
+## Source of Truth
+
+After running `npm install banhatten-ui`, two resources are available:
+
+1. **Design Tokens** — `node_modules/banhatten-ui/dist/tokens/tokens.json`
+2. **Component Specs** — `node_modules/banhatten-ui/dist/specs/<component>.json`
+
+Always read these files before making styling decisions. They are the single source of truth.
+
+---
+
+## Token Resolution
+
+`tokens.json` has four top-level sections:
+
+| Section     | Purpose                                     | Example                                |
+|-------------|---------------------------------------------|----------------------------------------|
+| `brand`     | Raw color palette (hex values)              | `"primary-600": "#2563eb"`             |
+| `alias`     | Semantic tokens referencing `brand`         | `"bg-brand": "{brand.primary-600}"`    |
+| `shadow`    | Box-shadow CSS strings                      | `"md": "0px 1.75px 4px -1px ..."`     |
+| `radius`    | Border-radius pixel values                  | `"sm": "8px"`                          |
+| `spacing`   | Spacing values (rem or px)                  | `"lg": "1rem"`                         |
+
+**Resolution chain:** Component specs reference `{alias.*}`, `{shadow.*}`, `{radius.*}`, and `{spacing.*}`. Alias tokens reference `{brand.*}` which holds the final hex value.
+
+Example:
+```
+spec: "{alias.component-button-brand-bg}" → tokens alias: "{brand.primary-600}" → tokens brand: "#2563eb"
+```
+
+---
+
+## Component Spec Schema
+
+Each `<component>.json` in `specs/` follows this structure:
+
+- **`base`** — Default CSS properties applied to every instance.
+- **`variants`** — Named style presets (e.g. `primary`, `secondary`, `danger`). Each variant specifies `bg`, `text`, `border`, `hover`, `active` etc. using token references.
+- **`sizes`** — Named size presets (e.g. `xs`, `md`, `lg`). Each size specifies `height`, `paddingX`, `paddingY`, `fontSize`, `borderRadius`, `gap` using token references or raw CSS values.
+- **`states`** — `disabled`, `focus`, `error`, and other state styles.
+- **`compoundVariants`** — Conditional overrides when multiple props match simultaneously.
+- **`props`** — Component API: prop name, type, allowed values, and defaults.
+- **`slots`** — Named sub-elements within the component (e.g. `leftIcon`, `rightIcon`).
+- **`subComponents`** — Definitions for child components (e.g. `MenuItem` inside `Menu`).
+- **`defaults`** — Default variant and size.
+- **`accessibility`** — Required ARIA attributes and notes.
+
+---
+
+## Customization Process
+
+### Step 1: Global Theme
+
+Read `tokens.json` and configure your library's global theme:
+
+1. **Colors** — Map every `alias.*` token to your library's color system. Resolve each alias through `brand` to get the final hex value. Create semantic color keys that match the alias names.
+2. **Shadows** — Map `shadow.*` values directly as CSS box-shadow strings.
+3. **Border Radius** — Map `radius.*` values to your library's radius/shape tokens.
+4. **Spacing** — Map `spacing.*` values to your library's spacing scale.
+
+### Step 2: Component Overrides
+
+For each component your project uses:
+
+1. Read the matching spec from `node_modules/banhatten-ui/dist/specs/<component>.json`.
+2. Map **variants** to the library's variant/color system. Match backgrounds, text colors, borders, and hover/active/focus states exactly.
+3. Map **sizes** to the library's size system. Match height, padding, font size, border radius, and gap exactly.
+4. Map **states** (disabled opacity, focus rings) to the library's state styling.
+5. Map **compound variants** as conditional overrides.
+6. Ensure the component exposes the same **props** as the spec (or provide wrappers that do).
+
+### Step 3: Missing Components
+
+For components in the specs that do not exist in your library:
+
+1. Create a custom component using your library's primitives and styling utilities.
+2. Follow the spec exactly for all variants, sizes, states, and props.
+3. Resolve all token references to final CSS values through `tokens.json`.
+4. Implement the accessibility requirements from the spec's `accessibility` section.
+
+---
+
+## Available Component Specs
+
+accordion, alert, avatar, avatar-group, avatar-profile, badge, breadcrumb, 
+button, button-group, checkbox, checkbox-card, close-button, divider, 
+dropdown, dropdown-input, featured-icon, icon, input, menu, progress-bar, 
+radio, radio-card, sidebar, slider, tag, textarea, toggle, tooltip
+
+---
+
+## Rules
+
+- Never hardcode hex colors — always resolve through `tokens.json` so themes stay updatable.
+- Preserve the variant/size naming from specs (e.g. `primary`, `md`) in your theme configuration.
+- When a spec uses `{alias.*}`, resolve it to the final value through `brand` only at the point of CSS output — keep semantic names in theme config.
+- Match pixel-perfect dimensions: if the spec says `height: "40px"` and `paddingX: "{spacing.lg}"` (1rem), use those exact values.
+- Focus rings must use `{alias.border-brand}` (resolved: `#2563eb`) with a 2px offset unless the spec says otherwise.
+- Icon sizing follows the spec's `slots.*.iconSizeByButtonSize` mappings when present.

package/dist/specs/accordion.json

@@ -0,0 +1,115 @@
+{
+  "name": "Accordion",
+  "description": "Expandable/collapsible content sections. Supports single (one open) or multiple (many open) modes. Chevron icon rotates on expand/collapse.",
+
+  "base": {
+    "display": "flex",
+    "flexDirection": "column"
+  },
+
+  "variants": {
+    "type": {
+      "single": { "description": "Only one item open at a time. Value is string." },
+      "multiple": { "description": "Many items can be open. Value is string[]." }
+    }
+  },
+
+  "props": {
+    "type": { "type": "enum", "values": ["single", "multiple"], "default": "single" },
+    "value": { "type": "string | string[]", "description": "Controlled open value(s). Single uses string; multiple uses string[]." },
+    "defaultValue": { "type": "string | string[]", "description": "Default open value(s) when uncontrolled." },
+    "onValueChange": { "type": "function", "description": "(value: string | string[]) => void. Called when open state changes." }
+  },
+
+  "subComponents": {
+    "AccordionItem": {
+      "description": "Wrapper for a single accordion section. Provides value, disabled, and showDivider context.",
+      "element": "div",
+      "base": {
+        "display": "flex",
+        "flexDirection": "column"
+      },
+      "props": {
+        "value": { "type": "string", "description": "Unique value for this item (used for open state and accessibility)." },
+        "disabled": { "type": "boolean", "default": false, "description": "When true, trigger and content use disabled styling and are not expandable." },
+        "showDivider": { "type": "boolean", "default": false, "description": "When true, a Divider is shown between trigger and content when expanded." }
+      }
+    },
+
+    "AccordionTrigger": {
+      "description": "Button that toggles expand/collapse. Optional iconLeft. Chevron rotates: expand_more (collapsed) → expand_less (expanded).",
+      "element": "button",
+      "base": {
+        "display": "flex",
+        "width": "100%",
+        "alignItems": "center",
+        "gap": "{spacing.md}",
+        "paddingY": "{spacing.md}",
+        "paddingX": "{spacing.md}",
+        "textAlign": "left",
+        "color": "{alias.text-primary}",
+        "transition": "background-color",
+        "focusRing": { "width": "2px", "color": "{alias.border-brand}", "offset": "2px" }
+      },
+      "states": {
+        "default": {
+          "cursor": "pointer",
+          "hover": { "bg": "{alias.bg-tertiary}" },
+          "expandIconColor": "{alias.icon-primary}",
+          "iconLeftColor": "{alias.icon-secondary}"
+        },
+        "disabled": {
+          "cursor": "default",
+          "color": "{alias.text-inactive}",
+          "pointerEvents": "none",
+          "expandIconColor": "{alias.icon-inactive}",
+          "iconLeftColor": "{alias.icon-inactive}"
+        }
+      },
+      "props": {
+        "iconLeft": { "type": "ReactNode", "description": "Optional icon or element shown to the left of the heading (e.g. info icon)." },
+        "disabled": { "type": "boolean", "description": "Overrides item-level disabled. When undefined, inherits from AccordionItem." }
+      },
+      "slots": {
+        "iconLeft": {
+          "position": "start",
+          "className": "accordion-icon-left",
+          "shrink": 0
+        },
+        "expandIcon": {
+          "element": "Icon",
+          "name": "expand_more | expand_less",
+          "size": "sm",
+          "className": "accordion-expand-icon",
+          "position": "end",
+          "shrink": 0,
+          "rotation": { "collapsed": "0deg", "expanded": "180deg" }
+        }
+      },
+      "accessibility": {
+        "ariaExpanded": "boolean",
+        "ariaControls": "contentId",
+        "ariaDisabled": "boolean when disabled"
+      }
+    },
+
+    "AccordionContent": {
+      "description": "Collapsible content panel. Renders only when item is expanded. When AccordionItem.showDivider is true, Divider renders above content.",
+      "element": "div",
+      "base": {
+        "paddingY": "{spacing.md}",
+        "paddingX": "{spacing.md}",
+        "color": "{alias.text-secondary}",
+        "fontSize": "14px"
+      },
+      "accessibility": {
+        "role": "region",
+        "ariaLabelledby": "triggerId"
+      }
+    }
+  },
+
+  "accessibility": {
+    "notes": "AccordionItem provides triggerId and contentId for aria-controls/aria-labelledby. AccordionTrigger uses aria-expanded and aria-controls."
+  }
+}

package/dist/specs/alert.json

@@ -0,0 +1,178 @@
+{
+  "name": "Alert",
+  "description": "Contextual feedback banner with status icon, title, optional description, action buttons, and close control. Supports 5 semantic types across 4 emphasis levels.",
+
+  "base": {
+    "display": "flex",
+    "gap": "{spacing.md}",
+    "borderRadius": "{radius.sm}",
+    "paddingX": "{spacing.md}",
+    "paddingY": "{spacing.md}",
+    "transition": "background-color, border-color, color",
+    "fontSize": "14px",
+    "lineHeight": "20px"
+  },
+
+  "variants": {
+    "low": {
+      "bg": "{alias.bg-primary}",
+      "border": { "width": "1px", "color": "{alias.border-strong}" },
+      "text": "{alias.text-primary}"
+    },
+    "medium": {},
+    "moderate": {},
+    "high": {}
+  },
+
+  "sizes": {},
+
+  "states": {
+    "expanded": {
+      "alignItems": "flex-start",
+      "title": { "fontWeight": 500 },
+      "description": { "marginTop": "{spacing.xs}" },
+      "actions": { "marginTop": "{spacing.sm}", "gap": "{spacing.md}" }
+    },
+    "collapsed": {
+      "alignItems": "center",
+      "title": { "fontWeight": 400 }
+    }
+  },
+
+  "compoundVariants": [
+    {
+      "when": { "emphasis": "medium", "type": "info" },
+      "apply": { "bg": "{alias.bg-info-tertiary}", "border": { "width": "1px", "color": "{alias.border-info-subtle}" }, "text": "{alias.text-info}" }
+    },
+    {
+      "when": { "emphasis": "medium", "type": "success" },
+      "apply": { "bg": "{alias.bg-success-tertiary}", "border": { "width": "1px", "color": "{alias.border-success-secondary}" }, "text": "{alias.text-success}" }
+    },
+    {
+      "when": { "emphasis": "medium", "type": "warning" },
+      "apply": { "bg": "{alias.bg-warning-tertiary}", "border": { "width": "1px", "color": "{alias.border-warning-secondary}" }, "text": "{alias.text-warning-strong}" }
+    },
+    {
+      "when": { "emphasis": "medium", "type": "danger" },
+      "apply": { "bg": "{alias.bg-danger-tertiary}", "border": { "width": "1px", "color": "{alias.border-danger-secondary}" }, "text": "{alias.text-danger}" }
+    },
+    {
+      "when": { "emphasis": "medium", "type": "neutral" },
+      "apply": { "bg": "{alias.bg-secondary}", "border": { "width": "1px", "color": "{alias.border-strong}" }, "text": "{alias.text-primary}" }
+    },
+    {
+      "when": { "emphasis": "moderate", "type": "info" },
+      "apply": { "bg": "{alias.bg-info-secondary}", "border": { "width": "1px", "color": "{alias.border-info-subtle}" }, "text": "{alias.text-info}" }
+    },
+    {
+      "when": { "emphasis": "moderate", "type": "success" },
+      "apply": { "bg": "{alias.bg-success-secondary}", "border": { "width": "1px", "color": "{alias.border-success-secondary}" }, "text": "{alias.text-success}" }
+    },
+    {
+      "when": { "emphasis": "moderate", "type": "warning" },
+      "apply": { "bg": "{alias.bg-warning-secondary}", "border": { "width": "1px", "color": "{alias.border-warning-secondary}" }, "text": "{alias.text-warning-strong}" }
+    },
+    {
+      "when": { "emphasis": "moderate", "type": "danger" },
+      "apply": { "bg": "{alias.bg-danger-secondary}", "border": { "width": "1px", "color": "{alias.border-danger-secondary}" }, "text": "{alias.text-danger}" }
+    },
+    {
+      "when": { "emphasis": "moderate", "type": "neutral" },
+      "apply": { "bg": "{alias.bg-tertiary}", "border": { "width": "1px", "color": "{alias.border-strong}" }, "text": "{alias.text-primary}" }
+    },
+    {
+      "when": { "emphasis": "high", "type": "info" },
+      "apply": { "bg": "{alias.bg-info}", "text": "{alias.text-on-color}" }
+    },
+    {
+      "when": { "emphasis": "high", "type": "success" },
+      "apply": { "bg": "{alias.bg-success}", "text": "{alias.text-on-color}" }
+    },
+    {
+      "when": { "emphasis": "high", "type": "warning" },
+      "apply": { "bg": "{alias.bg-warning}", "text": "{alias.text-on-color}" }
+    },
+    {
+      "when": { "emphasis": "high", "type": "danger" },
+      "apply": { "bg": "{alias.bg-danger}", "text": "{alias.text-on-color}" }
+    },
+    {
+      "when": { "emphasis": "high", "type": "neutral" },
+      "apply": { "bg": "{alias.bg-quarterary}", "text": "{alias.text-primary}" }
+    },
+    {
+      "when": { "emphasis": "low" },
+      "apply": { "iconSize": "sm" }
+    },
+    {
+      "when": { "emphasis": ["medium", "moderate", "high"] },
+      "apply": { "iconSize": "md" }
+    }
+  ],
+
+  "props": {
+    "title": { "type": "string", "description": "Main title text displayed in the alert." },
+    "description": { "type": "string", "description": "Optional subtitle/description text (shown when expand=true)." },
+    "actions": { "type": "AlertAction[]", "description": "Action buttons rendered as link-style buttons (shown when expand=true)." },
+    "onClose": { "type": "function", "description": "Callback fired when the close button is clicked." },
+    "expand": { "type": "boolean", "default": false, "description": "Expand to show description and action buttons." },
+    "type": { "type": "enum", "values": ["info", "success", "warning", "danger", "neutral"], "default": "info" },
+    "emphasis": { "type": "enum", "values": ["low", "medium", "moderate", "high"], "default": "medium" },
+    "iconVariant": { "type": "enum", "values": ["outlined", "rounded", "sharp"], "default": "outlined" },
+    "iconFilled": { "type": "boolean", "default": false }
+  },
+
+  "slots": {
+    "icon": {
+      "position": "start",
+      "element": "Icon",
+      "iconByType": {
+        "info": "info",
+        "success": "check_circle",
+        "warning": "warning",
+        "danger": "error",
+        "neutral": "notifications"
+      },
+      "iconColorByType": {
+        "info": "{alias.text-info}",
+        "success": "{alias.text-success}",
+        "warning": "{alias.text-warning-strong}",
+        "danger": "{alias.text-danger}",
+        "neutral": "{alias.icon-primary}"
+      },
+      "highEmphasisIconColor": "{alias.text-on-color}",
+      "highNeutralIconColor": "{alias.icon-primary}"
+    },
+    "title": {
+      "fontSize": "14px",
+      "lineHeight": "20px"
+    },
+    "description": {
+      "fontSize": "14px",
+      "lineHeight": "20px",
+      "marginTop": "{spacing.xs}"
+    },
+    "actions": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "{spacing.md}",
+      "marginTop": "{spacing.sm}",
+      "element": "Button",
+      "buttonVariant": "link-brand",
+      "buttonSize": "xs"
+    },
+    "closeButton": {
+      "position": "end",
+      "element": "CloseButton",
+      "variant": "ghost",
+      "size": "sm"
+    }
+  },
+
+  "defaults": { "type": "info", "emphasis": "medium", "expand": false },
+
+  "accessibility": {
+    "role": "alert | status",
+    "notes": "role='alert' and aria-live='assertive' for danger/warning types; role='status' and aria-live='polite' for info/success/neutral."
+  }
+}

package/dist/specs/avatar-group.json

@@ -0,0 +1,91 @@
+{
+  "name": "AvatarGroup",
+  "description": "Displays a row of overlapping avatars with optional overflow badge and add-member button.",
+
+  "base": {
+    "display": "inline-flex",
+    "alignItems": "center"
+  },
+
+  "sizes": {
+    "24": {
+      "avatarSize": "24px",
+      "avatarProfileSize": "xs",
+      "badgeSize": "24px",
+      "badgeFontSize": "12px",
+      "iconSize": "xs"
+    },
+    "32": {
+      "avatarSize": "32px",
+      "avatarProfileSize": "md",
+      "badgeSize": "32px",
+      "badgeFontSize": "14px",
+      "iconSize": "sm"
+    },
+    "40": {
+      "avatarSize": "40px",
+      "avatarProfileSize": "xl",
+      "badgeSize": "40px",
+      "badgeFontSize": "16px",
+      "iconSize": "md"
+    }
+  },
+
+  "overlap": {
+    "marginLeft": "-{spacing.sm}",
+    "note": "Every avatar after the first is offset by -ml-sm. Z-index stacking controlled by lastOnTop prop."
+  },
+
+  "zIndex": {
+    "lastOnTop": "First avatar gets highest z-index; decreasing toward last.",
+    "firstOnTop": "First avatar gets lowest z-index; increasing toward last."
+  },
+
+  "slots": {
+    "overflowBadge": {
+      "description": "+N indicator shown when avatars exceed maxVisible.",
+      "display": "inline-flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "borderRadius": "{radius.full}",
+      "border": { "width": "2px", "color": "{alias.border-subtract}" },
+      "bg": "{alias.bg-tertiary}",
+      "text": "{alias.text-secondary}",
+      "fontWeight": 500,
+      "zIndex": 0
+    },
+    "addButton": {
+      "description": "Dashed circular button to add a new member.",
+      "display": "inline-flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "borderRadius": "{radius.full}",
+      "border": { "width": "2px", "style": "dashed", "color": "{alias.border-strong}" },
+      "bg": "transparent",
+      "iconColor": "{alias.icon-tertiary}",
+      "hover": { "bg": "{alias.bg-tertiary}", "borderColor": "{alias.border-strong}" },
+      "focus": { "ring": "2px", "ringColor": "{alias.border-brand}", "ringOffset": "2px" }
+    }
+  },
+
+  "composition": {
+    "avatar": "AvatarProfile (shape: circle)"
+  },
+
+  "props": {
+    "size": { "type": "enum", "values": ["24", "32", "40"], "default": "32" },
+    "lastOnTop": { "type": "boolean", "default": true, "description": "When true, leftmost avatar is drawn on top." },
+    "moreAvatars": { "type": "boolean", "default": false, "description": "Show +N overflow badge after visible avatars." },
+    "addMore": { "type": "boolean", "default": false, "description": "Show an Add More button at the end." },
+    "avatars": { "type": "AvatarGroupItem[]", "description": "List of avatar items (initials, aria-label)." },
+    "maxVisible": { "type": "number", "default": 4, "description": "Max visible avatars before +N overflow." },
+    "onAddMore": { "type": "function", "description": "Called when Add More button is clicked." }
+  },
+
+  "defaults": { "size": "32", "lastOnTop": true, "maxVisible": 4 },
+
+  "accessibility": {
+    "role": "group",
+    "notes": "aria-label set to '{count} member(s)'. Add button has aria-label 'Add member'. Overflow badge is aria-hidden."
+  }
+}

package/dist/specs/avatar-profile.json

@@ -0,0 +1,65 @@
+{
+  "name": "AvatarProfile",
+  "description": "Wraps Avatar with a border ring and drop shadow. Supports circle and rounded shapes with optional badge slots at top-right and bottom-right.",
+
+  "base": {
+    "display": "inline-flex",
+    "position": "relative",
+    "flexShrink": 0,
+    "border": { "width": "2px", "color": "{alias.border-subtract}" },
+    "shadow": "{shadow.sm}"
+  },
+
+  "variants": {
+    "circle": { "borderRadius": "{radius.full}" },
+    "rounded": { "borderRadius": "{radius.md}" }
+  },
+
+  "composition": {
+    "avatar": "Avatar (shape and size passed through)"
+  },
+
+  "props": {
+    "shape": { "type": "enum", "values": ["circle", "rounded"], "default": "circle" },
+    "size": { "type": "enum", "values": ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"], "default": "md", "description": "Passed through to the inner Avatar." },
+    "initials": { "type": "string", "description": "Initials for the inner Avatar." },
+    "topRight": { "type": "ReactNode", "description": "Badge content at top-right (e.g. edit icon). Icon is forced to filled." },
+    "bottomRight": { "type": "ReactNode", "description": "Badge content at bottom-right (e.g. status icon). Icon is forced to filled." }
+  },
+
+  "slots": {
+    "badgeSlot": {
+      "description": "Shared styling for topRight and bottomRight badge positions.",
+      "position": "absolute",
+      "display": "flex",
+      "alignItems": "center",
+      "justifyContent": "center",
+      "borderRadius": "{radius.full}",
+      "overflow": "hidden",
+      "zIndex": 10,
+      "size": "{spacing.xl}",
+      "minSize": "{spacing.xl}",
+      "border": { "width": "2px", "color": "{alias.border-subtract}" },
+      "bg": "{alias.bg-brand}",
+      "text": "{alias.text-on-color}"
+    },
+    "topRight": {
+      "top": "0",
+      "right": "0",
+      "translateX": "50%",
+      "translateY": "-50%"
+    },
+    "bottomRight": {
+      "bottom": "0",
+      "right": "0",
+      "translateX": "50%",
+      "translateY": "50%"
+    }
+  },
+
+  "defaults": { "shape": "circle", "size": "md" },
+
+  "accessibility": {
+    "notes": "Badge slots are aria-hidden. Icons inside badges are forced to filled variant via cloneElement."
+  }
+}

package/dist/specs/avatar.json

@@ -0,0 +1,87 @@
+{
+  "name": "Avatar",
+  "description": "User representation as initials, fallback icon, or image. Optionally paired with a username and supporting text.",
+
+  "base": {
+    "display": "inline-flex",
+    "alignItems": "center",
+    "justifyContent": "center",
+    "fontWeight": 500,
+    "flexShrink": 0,
+    "bg": "{alias.bg-quarterary}",
+    "text": "{alias.text-secondary}",
+    "userSelect": "none",
+    "overflow": "hidden"
+  },
+
+  "variants": {
+    "circle": { "borderRadius": "{radius.full}" },
+    "rounded": { "borderRadius": "{radius.md}" }
+  },
+
+  "sizes": {
+    "xs":  { "height": "24px", "width": "24px", "fontSize": "12px" },
+    "sm":  { "height": "28px", "width": "28px", "fontSize": "12px" },
+    "md":  { "height": "32px", "width": "32px", "fontSize": "14px" },
+    "lg":  { "height": "36px", "width": "36px", "fontSize": "14px" },
+    "xl":  { "height": "40px", "width": "40px", "fontSize": "16px" },
+    "2xl": { "height": "48px", "width": "48px", "fontSize": "18px" },
+    "3xl": { "height": "56px", "width": "56px", "fontSize": "20px" },
+    "4xl": { "height": "64px", "width": "64px", "fontSize": "20px" }
+  },
+
+  "props": {
+    "shape": { "type": "enum", "values": ["circle", "rounded"], "default": "circle" },
+    "size": { "type": "enum", "values": ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl"], "default": "md" },
+    "initials": { "type": "string", "description": "Initials to show (e.g. 'AG'). Max 2 characters. Renders initials instead of the fallback icon." },
+    "username": { "type": "string", "description": "Username shown beside the avatar. Renders as primary text." },
+    "supportingText": { "type": "string", "description": "Supporting line below username (e.g. 'View profile'). Renders as secondary text." },
+    "aria-label": { "type": "string", "description": "Accessible name for the avatar. Required when the avatar conveys meaning." }
+  },
+
+  "slots": {
+    "initials": {
+      "flexShrink": 0,
+      "lineHeight": "1"
+    },
+    "fallbackIcon": {
+      "element": "Icon",
+      "name": "person",
+      "color": "{alias.icon-secondary}",
+      "iconSizeByAvatarSize": {
+        "xs": "xs",
+        "sm": "xs",
+        "md": "sm",
+        "lg": "sm",
+        "xl": "md",
+        "2xl": "md",
+        "3xl": "lg",
+        "4xl": "lg"
+      }
+    },
+    "username": {
+      "fontSize": "14px",
+      "fontWeight": 500,
+      "color": "{alias.text-primary}",
+      "overflow": "truncate"
+    },
+    "supportingText": {
+      "fontSize": "12px",
+      "color": "{alias.text-secondary}",
+      "overflow": "truncate"
+    },
+    "textContainer": {
+      "display": "flex",
+      "flexDirection": "column",
+      "justifyContent": "center",
+      "gap": "{spacing.md}"
+    }
+  },
+
+  "defaults": { "shape": "circle", "size": "md" },
+
+  "accessibility": {
+    "role": "img",
+    "notes": "When aria-label is provided, the avatar circle renders with role='img' and the label. When omitted, the avatar is treated as decorative. Initials are uppercased and capped at 2 characters."
+  }
+}