banhatten-ui 0.1.2 → 0.2.0

package/dist/specs/menu.json

@@ -0,0 +1,135 @@
+{
+  "name": "Menu",
+  "description": "Container for menu groups and items. Inserts dividers between MenuGroup children. Used in dropdowns, popovers, and context menus.",
+
+  "base": {
+    "display": "flex",
+    "flexDirection": "column",
+    "borderRadius": "{radius.sm}",
+    "bg": "{alias.bg-primary}",
+    "paddingY": "{spacing.md}",
+    "paddingX": "{spacing.sm}",
+    "shadow": "{shadow.sm}"
+  },
+
+  "behavior": {
+    "dividers": "Divider with my-sm inserted between each MenuGroup child"
+  },
+
+  "props": {
+    "children": { "type": "ReactNode", "description": "One or more MenuGroup components." }
+  },
+
+  "subComponents": {
+    "MenuGroup": {
+      "description": "Groups one optional MenuHeading and one or more MenuItem children.",
+      "base": {
+        "display": "flex",
+        "flexDirection": "column"
+      },
+      "props": {
+        "heading": { "type": "ReactNode", "description": "Optional section label. At most one." },
+        "headingId": { "type": "string", "description": "ID for heading wrapper. Used for role='group' aria-labelledby." },
+        "children": { "type": "ReactNode", "description": "MenuHeading (optional) and MenuItem components." }
+      },
+      "spacing": {
+        "headingToItems": "{spacing.sm}"
+      },
+      "accessibility": {
+        "role": "group",
+        "ariaLabelledby": "When heading and headingId provided"
+      }
+    },
+    "MenuHeading": {
+      "description": "Non-interactive section label for menu groups.",
+      "base": {
+        "paddingX": "{spacing.md}",
+        "paddingY": "{spacing.xs}",
+        "fontSize": "14px",
+        "fontWeight": 500,
+        "text": "{alias.text-tertiary}"
+      },
+      "props": {
+        "children": { "type": "ReactNode", "description": "Heading content (e.g. 'Section header')." }
+      }
+    },
+    "MenuItem": {
+      "description": "Individual menu item. Supports multiple types and slots.",
+      "base": {
+        "display": "flex",
+        "alignItems": "center",
+        "width": "100%",
+        "gap": "{spacing.md}",
+        "borderRadius": "{radius.sm}",
+        "paddingX": "{spacing.md}",
+        "paddingY": "{spacing.sm}",
+        "textAlign": "left",
+        "transition": "background-color, color",
+        "focusVisible": { "outline": "none", "ring": "2px", "ringColor": "{alias.border-brand}", "ringOffset": "2px" }
+      },
+      "types": {
+        "default": { "layout": "single-line" },
+        "multiline": { "layout": "primary + supportingText below", "gap": "{spacing.xxs}" },
+        "callToAction": { "layout": "primary + supportingText below + cta slot" },
+        "progress": { "layout": "ProgressBar with label and value" }
+      },
+      "states": {
+        "active": {
+          "true": { "bg": "{alias.bg-brand-tertiary}", "text": "{alias.text-brand}", "fontWeight": 500 },
+          "false": {}
+        },
+        "disabled": {
+          "true": { "opacity": 0.5, "cursor": "default", "pointerEvents": "none" },
+          "false": { "cursor": "pointer", "hover": { "bg": "{alias.bg-tertiary}" } }
+        }
+      },
+      "typography": {
+        "primary": { "fontSize": "14px", "fontWeight": 500, "lineHeight": "20px" },
+        "supportingText": { "fontSize": "14px", "lineHeight": "20px" },
+        "textRight": { "fontSize": "14px" }
+      },
+      "textColorByState": {
+        "primary": { "default": "{alias.text-primary}", "disabled": "{alias.text-inactive}" },
+        "supportingText": { "default": "{alias.text-secondary}", "disabled": "{alias.text-inactive}" },
+        "textRight": { "default": "{alias.text-secondary}", "disabled": "{alias.text-inactive}" }
+      },
+      "iconColorByState": {
+        "default": "{alias.icon-secondary}",
+        "disabled": "{alias.icon-inactive-subtle}"
+      },
+      "slots": {
+        "leftIcon": { "element": "Icon", "size": "sm", "position": "start" },
+        "rightIcon": { "element": "Icon", "size": "sm", "position": "end" },
+        "avatar": { "position": "start", "description": "Use Avatar component" },
+        "badge": { "position": "end", "description": "Use Badge component" },
+        "switch": { "element": "Toggle", "size": "sm", "togglePosition": "trailing", "position": "end", "description": "Use showSwitch, switchChecked, onSwitchChange props" },
+        "textRight": { "position": "end" },
+        "cta": { "element": "Button", "position": "end", "description": "For type='callToAction'" },
+        "progress": { "element": "ProgressBar", "size": "sm", "showValue": true, "description": "For type='progress'. Uses progressLabel, progressValue props." }
+      },
+      "props": {
+        "type": { "type": "enum", "values": ["default", "multiline", "callToAction", "progress"], "default": "default" },
+        "active": { "type": "boolean", "default": false, "description": "Selected/current state. Sets aria-current='page'." },
+        "disabled": { "type": "boolean", "default": false },
+        "children": { "type": "ReactNode", "description": "Primary content." },
+        "supportingText": { "type": "ReactNode", "description": "Supporting text below primary (multiline / callToAction)." },
+        "leftIcon": { "type": "string", "description": "Material Symbol name." },
+        "rightIcon": { "type": "string", "description": "Material Symbol name." },
+        "avatar": { "type": "ReactNode" },
+        "badge": { "type": "ReactNode" },
+        "showSwitch": { "type": "boolean", "default": false },
+        "switchChecked": { "type": "boolean" },
+        "onSwitchChange": { "type": "function" },
+        "textRight": { "type": "ReactNode" },
+        "cta": { "type": "ReactNode" },
+        "progressLabel": { "type": "ReactNode" },
+        "progressValue": { "type": "number", "description": "0-100" }
+      },
+      "defaults": { "type": "default", "active": false, "disabled": false }
+    }
+  },
+
+  "accessibility": {
+    "notes": "MenuItem sets aria-current='page' when active. Switch interactions stop propagation to prevent triggering parent button."
+  }
+}

package/dist/specs/progress-bar.json

@@ -0,0 +1,104 @@
+{
+  "name": "ProgressBar",
+  "description": "Horizontal bar indicating task completion or loading state. Supports determinate (0–100%) and indeterminate (animated pulse) modes.",
+
+  "base": {
+    "display": "flex",
+    "flexDirection": "column",
+    "minWidth": 0
+  },
+
+  "track": {
+    "width": "100%",
+    "overflow": "hidden",
+    "borderRadius": "{radius.sm}",
+    "bg": "{alias.bg-tertiary}"
+  },
+
+  "fill": {
+    "height": "100%",
+    "borderRadius": "{radius.sm}",
+    "flexShrink": 0
+  },
+
+  "sizes": {
+    "sm": { "trackHeight": "4px" },
+    "lg": { "trackHeight": "8px" }
+  },
+
+  "variants": {
+    "brand":   { "fillBg": "{alias.bg-brand}" },
+    "success": { "fillBg": "{alias.bg-success}" },
+    "danger":  { "fillBg": "{alias.bg-danger}" },
+    "info":    { "fillBg": "{alias.bg-info}" },
+    "neutral": { "fillBg": "{alias.bg-quarterary}" }
+  },
+
+  "states": {
+    "indeterminate": {
+      "fillWidth": "40%",
+      "animation": "pulse"
+    }
+  },
+
+  "props": {
+    "value": { "type": "number", "description": "Progress value 0–100. Omit for indeterminate (animated) state." },
+    "size": { "type": "enum", "values": ["sm", "lg"], "default": "sm" },
+    "color": { "type": "enum", "values": ["brand", "success", "danger", "info", "neutral"], "default": "brand" },
+    "label": { "type": "ReactNode", "description": "Optional label above the bar." },
+    "showLabelInfoIcon": { "type": "boolean", "default": false, "description": "Optional info icon shown next to the label." },
+    "helperText": { "type": "ReactNode", "description": "Optional helper text below the bar." },
+    "showValue": { "type": "boolean", "default": false, "description": "Whether to show the numeric value (e.g. '40%') beside the bar." },
+    "onRefresh": { "type": "function", "description": "Callback for the optional refresh icon button. When set, a refresh icon is shown next to the value." }
+  },
+
+  "slots": {
+    "label": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "{spacing.xs}",
+      "fontSize": "14px",
+      "fontWeight": 500,
+      "color": "{alias.text-primary}",
+      "marginBottom": "{spacing.sm}"
+    },
+    "labelInfoIcon": {
+      "element": "Icon",
+      "name": "info",
+      "size": "xs",
+      "color": "{alias.icon-tertiary}"
+    },
+    "barContainer": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "{spacing.md}",
+      "minWidth": 0
+    },
+    "valueText": {
+      "fontSize": "14px",
+      "color": "{alias.text-secondary}",
+      "flexShrink": 0
+    },
+    "refreshButton": {
+      "element": "button",
+      "borderRadius": "{radius.sm}",
+      "padding": "{spacing.xxs}",
+      "color": "{alias.icon-secondary}",
+      "hover": { "color": "{alias.icon-primary}", "bg": "{alias.bg-tertiary}" },
+      "focus": { "ring": "2px", "ringColor": "{alias.border-brand}", "ringOffset": "1px" },
+      "icon": { "name": "refresh", "size": "xs" }
+    },
+    "helperText": {
+      "fontSize": "14px",
+      "color": "{alias.text-secondary}",
+      "marginTop": "{spacing.sm}"
+    }
+  },
+
+  "defaults": { "size": "sm", "color": "brand", "showValue": false },
+
+  "accessibility": {
+    "role": "progressbar",
+    "notes": "Determinate: aria-valuenow, aria-valuemin=0, aria-valuemax=100, aria-valuetext='N%'. Indeterminate: no value attributes, aria-valuetext='Loading'. Refresh button has aria-label='Refresh'. Helper text linked via aria-describedby."
+  }
+}

package/dist/specs/radio-card.json

@@ -0,0 +1,111 @@
+{
+  "name": "RadioCard",
+  "description": "Card-style radio with optional icon, label, and description. Supports checked, unchecked, disabled, and focused states.",
+
+  "base": {
+    "display": "flex",
+    "position": "relative",
+    "borderRadius": "{radius.md}",
+    "padding": "{spacing.lg}",
+    "border": { "width": "1px" },
+    "transition": "background-color, border-color"
+  },
+
+  "states": {
+    "unchecked": {
+      "bg": "{alias.bg-primary}",
+      "borderColor": "{alias.border-default}",
+      "cursor": "pointer",
+      "hover": { "bg": "{alias.highlight-hover}" }
+    },
+    "checked": {
+      "bg": "{alias.bg-primary}",
+      "borderColor": "{alias.border-brand}",
+      "cursor": "pointer"
+    },
+    "disabled": {
+      "bg": "{alias.bg-inactive-subtle}",
+      "borderColor": "{alias.border-inactive-subtle}",
+      "cursor": "default"
+    },
+    "focused": {
+      "overlay": {
+        "position": "absolute",
+        "inset": "-1px",
+        "borderRadius": "{radius.md}",
+        "border": { "width": "2px", "color": "{alias.border-focused}" }
+      }
+    }
+  },
+
+  "layout": {
+    "leading": { "gap": "{spacing.md}", "alignItems": "center (no description) / start (with description)" },
+    "trailing": { "gap": "{spacing.lg}", "alignItems": "start" }
+  },
+
+  "subComponents": {
+    "RadioIndicator": {
+      "description": "16×16 radio circle inside a 20×20 hit area.",
+      "outerSize": "20px",
+      "innerSize": "16px",
+      "borderRadius": "{radius.full}",
+      "unchecked": {
+        "bg": "{alias.bg-primary}",
+        "border": { "width": "1px", "color": "{alias.border-strong}" }
+      },
+      "checked": {
+        "bg": "{alias.bg-brand}",
+        "dotColor": "{alias.icon-primary-inverse}",
+        "dot": "6px circle (SVG)"
+      },
+      "disabled": {
+        "bg": "{alias.bg-inactive-subtle}",
+        "border": { "width": "1px", "color": "{alias.border-inactive}" },
+        "dotColor": "{alias.icon-inactive-subtle}"
+      }
+    }
+  },
+
+  "slots": {
+    "icon": {
+      "element": "Icon",
+      "size": "lg",
+      "color": "{alias.icon-secondary}",
+      "disabledColor": "{alias.icon-inactive}"
+    },
+    "label": {
+      "fontWeight": 500,
+      "withDescription": { "fontSize": "14px", "lineHeight": "16px" },
+      "withoutDescription": { "fontSize": "16px", "lineHeight": "20px" },
+      "color": "{alias.text-primary}",
+      "disabledColor": "{alias.text-inactive}"
+    },
+    "description": {
+      "fontSize": "14px",
+      "lineHeight": "20px",
+      "color": "{alias.text-secondary}",
+      "disabledColor": "{alias.text-inactive}",
+      "gap": "{spacing.xs}"
+    }
+  },
+
+  "props": {
+    "label": { "type": "string", "description": "Label text displayed in the card." },
+    "description": { "type": "string", "description": "Description text below the label." },
+    "icon": { "type": "string", "description": "Material Symbol name for the card icon." },
+    "iconVariant": { "type": "enum", "values": ["outlined", "rounded", "sharp"], "default": "outlined" },
+    "iconFilled": { "type": "boolean", "default": false },
+    "radioPosition": { "type": "enum", "values": ["leading", "trailing"], "default": "trailing" },
+    "checked": { "type": "boolean" },
+    "disabled": { "type": "boolean", "default": false },
+    "name": { "type": "string", "description": "Radio group name for native grouping." },
+    "value": { "type": "string", "description": "Radio value." }
+  },
+
+  "defaults": { "radioPosition": "trailing" },
+
+  "accessibility": {
+    "role": "radio",
+    "notes": "Hidden native radio input (sr-only) inside a <label>. Focus/selection ring overlay shown when checked or focused (not disabled)."
+  }
+}

package/dist/specs/radio.json

@@ -0,0 +1,64 @@
+{
+  "name": "Radio",
+  "description": "Radio input with optional label and support text. Used within a group for single selection.",
+
+  "base": {
+    "display": "inline-flex",
+    "gap": "{spacing.md}",
+    "cursor": "pointer"
+  },
+
+  "indicator": {
+    "size": "16px",
+    "outerSize": "20px",
+    "borderRadius": "{radius.full}",
+    "unchecked": {
+      "bg": "{alias.bg-primary}",
+      "border": { "width": "1px", "color": "{alias.border-strong}" }
+    },
+    "checked": {
+      "bg": "{alias.bg-brand}",
+      "hover": { "bg": "{alias.bg-brand-hover}" },
+      "dotColor": "{alias.icon-primary-inverse}",
+      "dotRadius": "3px"
+    }
+  },
+
+  "states": {
+    "disabled": {
+      "cursor": "default",
+      "indicator": {
+        "bg": "{alias.bg-inactive-subtle}",
+        "border": { "color": "{alias.border-inactive}" },
+        "dotColor": "{alias.icon-inactive-subtle}"
+      },
+      "labelColor": "{alias.text-inactive}"
+    },
+    "focused": {
+      "indicator": {
+        "ring": { "width": "2px", "color": "{alias.border-focused}" },
+        "border": { "color": "{alias.border-brand}" }
+      }
+    }
+  },
+
+  "props": {
+    "label": { "type": "string", "description": "Label text next to the radio." },
+    "supportText": { "type": "string", "description": "Support text below the label." },
+    "radioPosition": { "type": "enum", "values": ["leading", "trailing"], "default": "leading" },
+    "checked": { "type": "boolean" },
+    "disabled": { "type": "boolean", "default": false },
+    "name": { "type": "string", "description": "Radio group name." },
+    "value": { "type": "string", "description": "Radio value within the group." }
+  },
+
+  "slots": {
+    "label": { "fontSize": "14px", "fontWeight": 500, "lineHeight": "16px", "color": "{alias.text-primary}" },
+    "supportText": { "fontSize": "14px", "lineHeight": "20px", "color": "{alias.text-secondary}", "gap": "{spacing.xxs}" }
+  },
+
+  "accessibility": {
+    "role": "radio",
+    "notes": "Native input is visually hidden (sr-only). Use within a fieldset/radiogroup for grouping."
+  }
+}

package/dist/specs/sidebar.json

@@ -0,0 +1,254 @@
+{
+  "name": "Sidebar",
+  "description": "Vertical navigation sidebar with header, scrollable content, and footer sections. Supports collapsed (icon-only) and expanded states via SidebarContext.",
+
+  "base": {
+    "display": "flex",
+    "flexDirection": "column",
+    "height": "100%",
+    "bg": "{alias.bg-primary}",
+    "shadow": "{shadow.sm}",
+    "borderRadius": "{radius.sm}",
+    "transition": "width 200ms ease-out"
+  },
+
+  "variants": {
+    "expanded": { "width": "256px", "minWidth": "256px" },
+    "collapsed": { "width": "64px", "minWidth": "64px" }
+  },
+
+  "sections": {
+    "header": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "{spacing.sm}",
+      "paddingX": "{spacing.2xl}",
+      "paddingY": "{spacing.2xl}",
+      "flexShrink": 0,
+      "collapseToggle": {
+        "size": "32px",
+        "borderRadius": "{radius.full}",
+        "iconColor": "{alias.icon-secondary}",
+        "hover": { "bg": "{alias.bg-tertiary}", "iconColor": "{alias.icon-primary}" },
+        "focus": { "ring": "2px", "ringColor": "{alias.border-brand}", "ringOffset": "2px" },
+        "icons": { "expanded": "chevron_left", "collapsed": "chevron_right" },
+        "iconSize": "sm"
+      }
+    },
+    "divider": {
+      "element": "Divider",
+      "orientation": "horizontal"
+    },
+    "content": {
+      "display": "flex",
+      "flexDirection": "column",
+      "flex": 1,
+      "minHeight": 0,
+      "overflow": "auto (y), hidden (x)",
+      "paddingX": "{spacing.xl}",
+      "paddingY": "{spacing.xl}",
+      "scrollbar": "hidden"
+    },
+    "footer": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "{spacing.xxs}",
+      "flexShrink": 0,
+      "borderTop": { "width": "1px", "color": "{alias.border-secondary}" },
+      "paddingX": "{spacing.md}",
+      "paddingY": "{spacing.md}",
+      "paddingTop": "{spacing.lg}"
+    }
+  },
+
+  "props": {
+    "header": { "type": "ReactNode", "description": "Header content (e.g. logo)." },
+    "children": { "type": "ReactNode", "description": "Main scrollable content (SidebarMenuItems)." },
+    "footer": { "type": "ReactNode", "description": "Footer content (e.g. settings, account card)." },
+    "collapsible": { "type": "boolean", "default": false, "description": "When true, shows collapse toggle in header." },
+    "collapsed": { "type": "boolean", "default": false, "description": "Controlled collapsed state." },
+    "onCollapsedChange": { "type": "function", "description": "Called when collapse toggle is clicked." },
+    "defaultCollapsed": { "type": "boolean", "default": false, "description": "Default collapsed state (uncontrolled)." }
+  },
+
+  "defaults": { "collapsible": false, "collapsed": false },
+
+  "subComponents": {
+    "SidebarMenuItem": {
+      "description": "Navigation item supporting expanded (icon + label) and collapsed (icon-only) layout. Optional submenu with expand/collapse.",
+      "base": {
+        "display": "flex",
+        "alignItems": "center",
+        "width": "100%",
+        "gap": "{spacing.md}",
+        "borderRadius": "{radius.sm}",
+        "paddingX": "{spacing.md}",
+        "paddingY": "{spacing.sm}",
+        "fontSize": "14px",
+        "fontWeight": 500,
+        "lineHeight": "20px",
+        "transition": "background-color"
+      },
+      "states": {
+        "default": {
+          "bg": "transparent",
+          "text": "{alias.text-primary}",
+          "iconColor": "{alias.icon-secondary}",
+          "hover": { "bg": "{alias.bg-tertiary}" },
+          "cursor": "pointer"
+        },
+        "active": {
+          "bg": "{alias.bg-brand-tertiary}",
+          "text": "{alias.text-brand}",
+          "iconColor": "{alias.icon-brand}"
+        },
+        "disabled": {
+          "opacity": 0.5,
+          "pointerEvents": "none",
+          "cursor": "default",
+          "iconColor": "{alias.icon-inactive-subtle}",
+          "text": "{alias.text-inactive}"
+        },
+        "collapsed": {
+          "justifyContent": "center",
+          "paddingX": "{spacing.sm}",
+          "note": "Label hidden; aria-label used for accessibility."
+        },
+        "focused": {
+          "ring": "2px",
+          "ringColor": "{alias.border-brand}",
+          "ringOffset": "2px"
+        }
+      },
+      "slots": {
+        "leftIcon": { "element": "Icon", "size": "sm" },
+        "label": { "truncate": true },
+        "chevron": {
+          "element": "Icon",
+          "size": "sm",
+          "expandedIcon": "expand_less",
+          "collapsedIcon": "expand_more"
+        }
+      },
+      "submenu": {
+        "display": "flex",
+        "flexDirection": "column",
+        "overflow": "hidden",
+        "transition": "height 200ms ease-out",
+        "collapsed": "hidden",
+        "expanded": "visible"
+      },
+      "props": {
+        "active": { "type": "boolean", "default": false },
+        "collapsed": { "type": "boolean", "default": false, "description": "Inherits from SidebarContext when inside Sidebar." },
+        "children": { "type": "ReactNode", "description": "Label text." },
+        "leftIcon": { "type": "string", "description": "Material Symbol name for leading icon." },
+        "submenu": { "type": "ReactNode", "description": "SidebarSubmenuItem children." },
+        "expanded": { "type": "boolean", "description": "Controlled expanded state for submenu." },
+        "onExpandedChange": { "type": "function", "description": "Called when submenu expand/collapse is toggled." },
+        "defaultExpanded": { "type": "boolean", "default": false },
+        "disabled": { "type": "boolean", "default": false }
+      },
+      "accessibility": {
+        "role": "button",
+        "notes": "aria-current='page' when active. aria-expanded on submenu trigger. aria-controls references submenu region. aria-label set from children when collapsed."
+      }
+    },
+
+    "SidebarSubmenuItem": {
+      "description": "Nested navigation item under SidebarMenuItem. Visually indented, no leading icon.",
+      "base": {
+        "display": "flex",
+        "alignItems": "center",
+        "width": "100%",
+        "borderRadius": "{radius.sm}",
+        "paddingLeft": "{spacing.xl}",
+        "paddingRight": "{spacing.md}",
+        "paddingY": "{spacing.sm}",
+        "fontSize": "14px",
+        "fontWeight": 400,
+        "lineHeight": "20px",
+        "text": "{alias.text-secondary}",
+        "transition": "background-color"
+      },
+      "states": {
+        "default": {
+          "cursor": "pointer",
+          "hover": { "bg": "{alias.bg-tertiary}", "text": "{alias.text-primary}" }
+        },
+        "active": {
+          "bg": "{alias.bg-brand-tertiary}",
+          "text": "{alias.text-brand}",
+          "fontWeight": 500
+        },
+        "disabled": {
+          "opacity": 0.5,
+          "pointerEvents": "none",
+          "cursor": "default",
+          "text": "{alias.text-inactive}"
+        },
+        "focused": {
+          "ring": "2px",
+          "ringColor": "{alias.border-brand}",
+          "ringOffset": "2px"
+        }
+      },
+      "props": {
+        "active": { "type": "boolean", "default": false },
+        "children": { "type": "ReactNode", "description": "Label text." },
+        "disabled": { "type": "boolean", "default": false }
+      },
+      "accessibility": {
+        "role": "button",
+        "notes": "aria-current='page' when active. aria-disabled when disabled."
+      }
+    },
+
+    "SidebarAccountCard": {
+      "description": "User account display card with Avatar, username, supporting text, and optional right icon. Collapses to avatar-only in collapsed sidebar.",
+      "base": {
+        "display": "flex",
+        "alignItems": "center",
+        "width": "100%",
+        "gap": "{spacing.md}",
+        "borderRadius": "{radius.sm}",
+        "paddingX": "{spacing.md}",
+        "paddingY": "{spacing.md}"
+      },
+      "states": {
+        "default": { "bg": "transparent" },
+        "selected": { "bg": "{alias.bg-tertiary}" },
+        "collapsed": {
+          "justifyContent": "center",
+          "paddingX": "0",
+          "paddingY": "{spacing.sm}",
+          "note": "Avatar only; username, supportingText, and rightIcon are hidden."
+        }
+      },
+      "composition": {
+        "avatar": "Avatar (size: md)"
+      },
+      "slots": {
+        "rightIcon": {
+          "element": "Icon",
+          "size": "sm",
+          "color": "{alias.icon-secondary}"
+        }
+      },
+      "props": {
+        "username": { "type": "string", "description": "User display name passed to Avatar." },
+        "supportingText": { "type": "string", "description": "Supporting line below name passed to Avatar." },
+        "initials": { "type": "string", "description": "Initials for Avatar fallback." },
+        "rightIcon": { "type": "string", "description": "Material Symbol name for trailing icon." },
+        "selected": { "type": "boolean", "default": false },
+        "collapsed": { "type": "boolean", "default": false, "description": "Inherits from SidebarContext when inside Sidebar." }
+      },
+      "defaults": { "selected": false }
+    }
+  },
+
+  "accessibility": {
+    "role": "complementary (aside)",
+    "notes": "aria-label='Sidebar'. SidebarContext provides collapsed state to children. Collapse toggle has aria-label 'Expand/Collapse sidebar'. Submenu regions have role='group' with aria-label."
+  }
+}