banhatten-ui 0.1.2 → 0.2.0

package/dist/specs/checkbox.json

@@ -0,0 +1,69 @@
+{
+  "name": "Checkbox",
+  "description": "Checkbox input with optional label and support text. Supports checked, unchecked, and indeterminate states.",
+
+  "base": {
+    "display": "inline-flex",
+    "gap": "{spacing.md}",
+    "cursor": "pointer"
+  },
+
+  "indicator": {
+    "size": "16px",
+    "outerSize": "20px",
+    "borderRadius": "{radius.xs}",
+    "unchecked": {
+      "bg": "{alias.bg-primary}",
+      "border": { "width": "1px", "color": "{alias.border-strong}" }
+    },
+    "checked": {
+      "bg": "{alias.bg-brand}",
+      "hover": { "bg": "{alias.bg-brand-hover}" },
+      "iconColor": "{alias.icon-primary-inverse}",
+      "icon": "check"
+    },
+    "indeterminate": {
+      "bg": "{alias.bg-brand}",
+      "hover": { "bg": "{alias.bg-brand-hover}" },
+      "iconColor": "{alias.icon-primary-inverse}",
+      "icon": "remove"
+    }
+  },
+
+  "states": {
+    "disabled": {
+      "cursor": "default",
+      "indicator": {
+        "bg": "{alias.bg-inactive-subtle}",
+        "border": { "color": "{alias.border-inactive}" },
+        "iconColor": "{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 checkbox." },
+    "supportText": { "type": "string", "description": "Support text below the label." },
+    "checkboxPosition": { "type": "enum", "values": ["leading", "trailing"], "default": "leading" },
+    "indeterminate": { "type": "boolean", "default": false },
+    "checked": { "type": "boolean" },
+    "disabled": { "type": "boolean", "default": false }
+  },
+
+  "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": "checkbox",
+    "notes": "aria-checked set to 'mixed' when indeterminate. Native input is visually hidden (sr-only)."
+  }
+}

package/dist/specs/close-button.json

@@ -0,0 +1,64 @@
+{
+  "name": "CloseButton",
+  "description": "Icon-only circular button for close/dismiss actions. Uses Icon component with 'close' icon.",
+
+  "base": {
+    "display": "inline-flex",
+    "alignItems": "center",
+    "justifyContent": "center",
+    "flexShrink": 0,
+    "borderRadius": "{radius.full}",
+    "transition": "background-color, color",
+    "focusVisible": { "outline": "none", "ring": "2px", "ringColor": "{alias.border-brand}", "ringOffset": "2px" },
+    "disabled": { "opacity": 0.5, "pointerEvents": "none" }
+  },
+
+  "variants": {
+    "ghost": {
+      "bg": "transparent",
+      "text": "{alias.icon-primary}",
+      "hover": { "bg": "{alias.bg-tertiary}" },
+      "active": { "bg": "{alias.bg-quarterary}" },
+      "disabled": { "text": "{alias.text-inactive}" }
+    },
+    "outlined": {
+      "bg": "transparent",
+      "border": { "width": "1px", "color": "{alias.border-strong}" },
+      "text": "{alias.icon-primary}",
+      "hover": { "borderColor": "{alias.border-strong}", "bg": "{alias.bg-secondary}" },
+      "active": { "bg": "{alias.bg-tertiary}" },
+      "disabled": { "borderColor": "{alias.border-inactive-subtle}", "bg": "{alias.bg-secondary}", "text": "{alias.text-inactive}" }
+    }
+  },
+
+  "sizes": {
+    "sm": { "width": "24px", "height": "24px", "iconSize": "sm" },
+    "md": { "width": "32px", "height": "32px", "iconSize": "md" },
+    "lg": { "width": "40px", "height": "40px", "iconSize": "md" },
+    "xl": { "width": "48px", "height": "48px", "iconSize": "lg" }
+  },
+
+  "slots": {
+    "icon": {
+      "element": "Icon",
+      "name": "close",
+      "iconSizeByButtonSize": { "sm": "sm", "md": "md", "lg": "md", "xl": "lg" }
+    }
+  },
+
+  "props": {
+    "variant": { "type": "enum", "values": ["ghost", "outlined"], "default": "ghost" },
+    "size": { "type": "enum", "values": ["sm", "md", "lg", "xl"], "default": "md" },
+    "iconVariant": { "type": "enum", "values": ["outlined", "rounded", "sharp"], "default": "outlined" },
+    "iconFilled": { "type": "boolean", "default": false },
+    "aria-label": { "type": "string", "default": "Close", "description": "Accessible name for the close action." },
+    "disabled": { "type": "boolean", "default": false }
+  },
+
+  "defaults": { "variant": "ghost", "size": "md" },
+
+  "accessibility": {
+    "role": "button",
+    "notes": "Requires aria-label for accessible name. Default: 'Close'."
+  }
+}

package/dist/specs/divider.json

@@ -0,0 +1,32 @@
+{
+  "name": "Divider",
+  "description": "Visual separator line for sectioning content. Supports horizontal and vertical orientation with solid or dashed styles.",
+
+  "base": {
+    "borderColor": "{alias.border-default}"
+  },
+
+  "variants": {
+    "solid": { "borderStyle": "solid" },
+    "dashed": { "borderStyle": "dashed" }
+  },
+
+  "sizes": {},
+
+  "orientations": {
+    "horizontal": { "width": "100%", "borderTop": "1px" },
+    "vertical": { "height": "100%", "borderLeft": "1px" }
+  },
+
+  "props": {
+    "orientation": { "type": "enum", "values": ["horizontal", "vertical"], "default": "horizontal" },
+    "variant": { "type": "enum", "values": ["solid", "dashed"], "default": "solid" }
+  },
+
+  "defaults": { "orientation": "horizontal", "variant": "solid" },
+
+  "accessibility": {
+    "role": "separator",
+    "notes": "Renders as <hr> for horizontal, <div> for vertical. aria-orientation reflects the orientation prop."
+  }
+}

package/dist/specs/dropdown-input.json

@@ -0,0 +1,87 @@
+{
+  "name": "DropdownInput",
+  "description": "Select trigger button with label, helper text, error state, and selection indicator. Used as the trigger for Dropdown/Select components.",
+
+  "base": {
+    "display": "flex",
+    "width": "100%",
+    "alignItems": "center",
+    "bg": "{alias.component-input-bg}",
+    "borderRadius": "{radius.sm}",
+    "transition": "border-color",
+    "cursor": "pointer"
+  },
+
+  "sizes": {
+    "sm": { "height": "36px", "paddingX": "{spacing.sm}", "fontSize": "14px" },
+    "md": { "height": "40px", "paddingX": "{spacing.sm}", "fontSize": "14px" },
+    "lg": { "height": "44px", "paddingX": "{spacing.sm}", "fontSize": "14px" }
+  },
+
+  "states": {
+    "default": {
+      "border": { "width": "1px", "color": "{alias.border-strong}" },
+      "shadow": "{shadow.xs}"
+    },
+    "disabled": {
+      "bg": "{alias.bg-secondary}",
+      "border": { "color": "{alias.border-inactive}" },
+      "shadow": "none",
+      "cursor": "default",
+      "pointerEvents": "none",
+      "text": "{alias.text-inactive}"
+    },
+    "error": {
+      "border": { "color": "{alias.border-danger-secondary}" }
+    },
+    "focused": {
+      "border": { "color": "{alias.border-brand}" },
+      "focusRing": { "width": "4px", "color": "{alias.border-focused}", "inset": "-1px", "borderRadius": "{radius.sm}" }
+    },
+    "focused+error": {
+      "border": { "color": "{alias.border-danger}" },
+      "focusRing": { "width": "4px", "color": "{alias.border-focused-danger}", "inset": "-1px", "borderRadius": "{radius.sm}" }
+    }
+  },
+
+  "props": {
+    "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+    "label": { "type": "string", "description": "Label text above the trigger." },
+    "optional": { "type": "boolean", "default": false },
+    "helperText": { "type": "string" },
+    "errorMessage": { "type": "string", "description": "Error message. Overrides helperText." },
+    "placeholder": { "type": "string", "default": "Select an option" },
+    "value": { "type": "string | string[]" },
+    "displayValue": { "type": "string", "description": "Custom display text for the selected value." },
+    "open": { "type": "boolean", "default": false },
+    "showIndicator": { "type": "boolean", "default": false, "description": "Show selection count badge." },
+    "indicatorCount": { "type": "number" },
+    "leftIcon": { "type": "string", "description": "Material Symbol name for leading icon." },
+    "leftElement": { "type": "ReactNode", "description": "Custom left element. Overrides leftIcon." },
+    "disabled": { "type": "boolean", "default": false }
+  },
+
+  "slots": {
+    "leftIcon": { "position": "start", "element": "Icon", "size": "md", "color": "{alias.text-tertiary}", "disabledColor": "{alias.icon-inactive-subtle}" },
+    "chevron": { "position": "end", "element": "Icon", "openIcon": "expand_less", "closedIcon": "expand_more", "size": "md", "color": "{alias.text-tertiary}" },
+    "indicator": {
+      "position": "before-chevron",
+      "height": "24px",
+      "borderRadius": "{radius.full}",
+      "paddingX": "{spacing.xs}",
+      "fontSize": "12px",
+      "fontWeight": 500,
+      "bg": "{alias.bg-brand}",
+      "text": "{alias.text-on-color}"
+    },
+    "label": { "position": "above", "fontSize": "14px", "fontWeight": 500, "color": "{alias.text-primary}", "marginBottom": "{spacing.sm}" },
+    "helperText": { "position": "below", "fontSize": "14px", "color": "{alias.text-secondary}", "errorColor": "{alias.text-error}", "marginTop": "{spacing.sm}" }
+  },
+
+  "defaults": { "size": "md" },
+
+  "accessibility": {
+    "role": "button",
+    "notes": "aria-haspopup='listbox', aria-expanded reflects open state, aria-invalid when error, aria-describedby links to helperText/errorMessage."
+  }
+}

package/dist/specs/dropdown.json

@@ -0,0 +1,71 @@
+{
+  "name": "Dropdown",
+  "description": "Complete select/dropdown component combining a trigger (DropdownInput), popover positioning, and menu with options. Supports single and multi-select.",
+
+  "composition": {
+    "trigger": "DropdownInput",
+    "popover": "Positioned overlay anchored to trigger",
+    "menu": "Menu with MenuGroup and MenuItem/DropdownItem children"
+  },
+
+  "props": {
+    "options": { "type": "DropdownOption[]", "description": "Array of { value, label, leftIcon?, disabled? } for simple usage." },
+    "value": { "type": "string | string[]", "description": "Selected value(s)." },
+    "onValueChange": { "type": "function", "description": "(value: string | string[]) => void" },
+    "multiple": { "type": "boolean", "default": false, "description": "Enable multi-select mode." },
+    "displayValue": { "type": "string", "description": "Custom display text override." },
+    "menuWidth": { "type": "enum", "values": ["trigger", "auto"], "default": "trigger", "description": "Menu width behavior. 'trigger' matches trigger width." },
+    "maxHeight": { "type": "number", "default": 300, "description": "Max menu height before scrolling." },
+    "align": { "type": "enum", "values": ["start", "center", "end"], "default": "start" },
+    "sideOffset": { "type": "number", "default": 4 },
+    "placeholder": { "type": "string", "default": "Select an option" },
+    "disabled": { "type": "boolean", "default": false }
+  },
+
+  "behavior": {
+    "singleSelect": "Selecting an option closes the dropdown and sets the value.",
+    "multiSelect": "Selecting an option toggles it. Dropdown stays open. Trigger shows count badge.",
+    "keyboard": "Escape closes the dropdown and returns focus to trigger."
+  },
+
+  "subComponents": {
+    "DropdownItem": {
+      "description": "Individual selectable option within the dropdown menu.",
+      "props": {
+        "value": { "type": "string", "required": true },
+        "selected": { "type": "boolean", "default": false },
+        "leftIcon": { "type": "string" },
+        "disabled": { "type": "boolean", "default": false },
+        "multiple": { "type": "boolean", "default": false }
+      },
+      "singleSelectIndicator": {
+        "selected": { "icon": "check", "size": "sm", "color": "{alias.text-brand}", "position": "end" },
+        "active": { "uses": "MenuItem active state" }
+      },
+      "multiSelectIndicator": {
+        "position": "start",
+        "size": "16px",
+        "borderRadius": "{radius.xs}",
+        "unchecked": { "bg": "{alias.component-input-bg}", "border": "{alias.border-strong}" },
+        "checked": { "bg": "{alias.bg-brand}", "border": "{alias.border-brand}", "icon": "check", "iconColor": "{alias.text-on-color}" }
+      }
+    },
+    "DropdownGroup": {
+      "description": "Groups options with an optional heading. Wraps MenuGroup.",
+      "props": {
+        "heading": { "type": "ReactNode" },
+        "headingId": { "type": "string" }
+      }
+    }
+  },
+
+  "popover": {
+    "animation": "fade-in + zoom-in-95 on open, reverse on close",
+    "slideDirection": "from-top when below trigger, from-bottom when above"
+  },
+
+  "accessibility": {
+    "role": "listbox",
+    "notes": "Menu has role='listbox'. DropdownItem has role='option' with aria-selected. Multi-select sets aria-multiselectable on the listbox."
+  }
+}

package/dist/specs/featured-icon.json

@@ -0,0 +1,80 @@
+{
+  "name": "FeaturedIcon",
+  "description": "Decorative icon container with 5 visual variants, 5 semantic types, and 3 sizes. Used to emphasize icon meaning in cards, empty states, and alerts.",
+
+  "base": {
+    "display": "inline-flex",
+    "alignItems": "center",
+    "justifyContent": "center",
+    "flexShrink": 0
+  },
+
+  "variants": {
+    "circle-light": { "borderRadius": "{radius.full}" },
+    "square-light": { "borderRadius": "{radius.lg}" },
+    "circle-pulse": { "borderRadius": "{radius.full}", "border": { "width": "8px" } },
+    "solid-circle": { "borderRadius": "{radius.full}" },
+    "solid-square": { "borderRadius": "{radius.lg}" }
+  },
+
+  "sizes": {
+    "sm": { "padding": "{spacing.sm}", "iconSize": "md" },
+    "md": { "padding": "{spacing.md}", "iconSize": "lg" },
+    "lg": { "padding": "{spacing.lg}", "iconSize": "xl" }
+  },
+
+  "compoundVariants": [
+    { "when": { "variant": "circle-light", "type": "brand" },    "apply": { "bg": "{alias.bg-brand-tertiary}",   "text": "{alias.text-brand}" } },
+    { "when": { "variant": "circle-light", "type": "success" },  "apply": { "bg": "{alias.bg-success-tertiary}", "text": "{alias.text-success}" } },
+    { "when": { "variant": "circle-light", "type": "danger" },   "apply": { "bg": "{alias.bg-danger-tertiary}",  "text": "{alias.text-danger}" } },
+    { "when": { "variant": "circle-light", "type": "warning" },  "apply": { "bg": "{alias.bg-warning-tertiary}", "text": "{alias.text-warning}" } },
+    { "when": { "variant": "circle-light", "type": "neutral" },  "apply": { "bg": "{alias.bg-tertiary}",         "text": "{alias.text-secondary}" } },
+
+    { "when": { "variant": "square-light", "type": "brand" },    "apply": { "bg": "{alias.bg-brand-tertiary}",   "text": "{alias.text-brand}" } },
+    { "when": { "variant": "square-light", "type": "success" },  "apply": { "bg": "{alias.bg-success-tertiary}", "text": "{alias.text-success}" } },
+    { "when": { "variant": "square-light", "type": "danger" },   "apply": { "bg": "{alias.bg-danger-tertiary}",  "text": "{alias.text-danger}" } },
+    { "when": { "variant": "square-light", "type": "warning" },  "apply": { "bg": "{alias.bg-warning-tertiary}", "text": "{alias.text-warning}" } },
+    { "when": { "variant": "square-light", "type": "neutral" },  "apply": { "bg": "{alias.bg-tertiary}",         "text": "{alias.text-secondary}" } },
+
+    { "when": { "variant": "circle-pulse", "type": "brand" },    "apply": { "borderColor": "{alias.border-brand-tertiary}",   "bg": "{alias.bg-brand-secondary}",   "text": "{alias.text-brand}" } },
+    { "when": { "variant": "circle-pulse", "type": "success" },  "apply": { "borderColor": "{alias.border-success-tertiary}", "bg": "{alias.bg-success-secondary}", "text": "{alias.text-success}" } },
+    { "when": { "variant": "circle-pulse", "type": "danger" },   "apply": { "borderColor": "{alias.border-danger-tertiary}",  "bg": "{alias.bg-danger-secondary}",  "text": "{alias.text-danger}" } },
+    { "when": { "variant": "circle-pulse", "type": "warning" },  "apply": { "borderColor": "{alias.border-warning-tertiary}", "bg": "{alias.bg-warning-secondary}", "text": "{alias.text-warning}" } },
+    { "when": { "variant": "circle-pulse", "type": "neutral" },  "apply": { "borderColor": "{alias.border-secondary}",        "bg": "{alias.bg-quarterary}",        "text": "{alias.text-secondary}" } },
+
+    { "when": { "variant": "solid-circle", "type": "brand" },    "apply": { "bg": "{alias.bg-brand}",            "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-circle", "type": "success" },  "apply": { "bg": "{alias.bg-success}",          "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-circle", "type": "danger" },   "apply": { "bg": "{alias.bg-danger}",           "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-circle", "type": "warning" },  "apply": { "bg": "{alias.bg-warning}",          "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-circle", "type": "neutral" },  "apply": { "bg": "{alias.bg-primary-inverse}",  "text": "{alias.text-on-color}" } },
+
+    { "when": { "variant": "solid-square", "type": "brand" },    "apply": { "bg": "{alias.bg-brand}",            "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-square", "type": "success" },  "apply": { "bg": "{alias.bg-success}",          "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-square", "type": "danger" },   "apply": { "bg": "{alias.bg-danger}",           "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-square", "type": "warning" },  "apply": { "bg": "{alias.bg-warning}",          "text": "{alias.text-on-color}" } },
+    { "when": { "variant": "solid-square", "type": "neutral" },  "apply": { "bg": "{alias.bg-primary-inverse}",  "text": "{alias.text-on-color}" } }
+  ],
+
+  "props": {
+    "variant": { "type": "enum", "values": ["circle-light", "square-light", "circle-pulse", "solid-circle", "solid-square"], "default": "solid-circle" },
+    "type": { "type": "enum", "values": ["brand", "success", "danger", "warning", "neutral"], "default": "brand" },
+    "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+    "name": { "type": "string", "description": "Material Symbol name in snake_case." },
+    "label": { "type": "string", "description": "Accessible label. If omitted, icon is decorative (aria-hidden)." }
+  },
+
+  "slots": {
+    "icon": {
+      "element": "Icon",
+      "filled": true,
+      "sizeByFeaturedSize": { "sm": "md", "md": "lg", "lg": "xl" }
+    }
+  },
+
+  "defaults": { "variant": "solid-circle", "type": "brand", "size": "md" },
+
+  "accessibility": {
+    "role": "img (when label is provided)",
+    "notes": "aria-label from label prop. aria-hidden when no label (decorative)."
+  }
+}

package/dist/specs/icon.json

@@ -0,0 +1,48 @@
+{
+  "name": "Icon",
+  "description": "Material Symbols icon rendered via variable font. Supports outlined, rounded, and sharp styles with configurable optical size, weight, fill, and grade.",
+
+  "base": {
+    "display": "inline",
+    "flexShrink": 0,
+    "userSelect": "none",
+    "fontFamily": "Material Symbols (variable font)"
+  },
+
+  "variants": {
+    "outlined": { "fontFamily": "Material Symbols Outlined" },
+    "rounded":  { "fontFamily": "Material Symbols Rounded" },
+    "sharp":    { "fontFamily": "Material Symbols Sharp" }
+  },
+
+  "sizes": {
+    "xs": { "fontSize": "12px" },
+    "sm": { "fontSize": "16px" },
+    "md": { "fontSize": "20px" },
+    "lg": { "fontSize": "24px" },
+    "xl": { "fontSize": "32px" }
+  },
+
+  "props": {
+    "name": { "type": "string", "description": "Material Symbol name in snake_case (e.g. 'home', 'arrow_forward', 'settings')." },
+    "variant": { "type": "enum", "values": ["outlined", "rounded", "sharp"], "default": "outlined" },
+    "size": { "type": "enum", "values": ["xs", "sm", "md", "lg", "xl"], "default": "md" },
+    "filled": { "type": "boolean", "default": false, "description": "Render the filled variant of the icon." },
+    "weight": { "type": "number", "default": 400, "description": "Font weight: 100–700." },
+    "grade": { "type": "number", "default": 0, "description": "Grade: -25 to 200." },
+    "label": { "type": "string", "description": "Accessible label. If omitted, the icon is treated as decorative (aria-hidden)." }
+  },
+
+  "fontVariationSettings": {
+    "FILL": { "off": 0, "on": 1 },
+    "wght": { "default": 400, "min": 100, "max": 700 },
+    "GRAD": { "default": 0, "min": -25, "max": 200 }
+  },
+
+  "defaults": { "variant": "outlined", "size": "md", "filled": false, "weight": 400, "grade": 0 },
+
+  "accessibility": {
+    "role": "img",
+    "notes": "When label is provided, renders with role='img' and aria-label. When omitted, aria-hidden='true' treats the icon as decorative."
+  }
+}

package/dist/specs/input.json

@@ -0,0 +1,81 @@
+{
+  "name": "Input",
+  "description": "Single-line text input with label, helper text, error state, character counter, and icon slots. Supports presets for common input types.",
+
+  "base": {
+    "display": "flex",
+    "width": "100%",
+    "alignItems": "center",
+    "bg": "{alias.component-input-bg}",
+    "border": { "width": "1px", "color": "{alias.border-strong}" },
+    "borderRadius": "{radius.sm}",
+    "shadow": "{shadow.xs}",
+    "transition": "border-color"
+  },
+
+  "sizes": {
+    "sm": { "height": "36px", "paddingX": "{spacing.sm}", "fontSize": "14px" },
+    "md": { "height": "40px", "paddingX": "{spacing.sm}", "fontSize": "14px" },
+    "lg": { "height": "44px", "paddingX": "{spacing.sm}", "fontSize": "14px" }
+  },
+
+  "states": {
+    "disabled": {
+      "bg": "{alias.bg-secondary}",
+      "border": { "color": "{alias.border-inactive}" },
+      "shadow": "none",
+      "pointerEvents": "none",
+      "text": "{alias.text-inactive}"
+    },
+    "error": {
+      "border": { "color": "{alias.border-danger-secondary}" }
+    },
+    "focused": {
+      "border": { "color": "{alias.border-brand}" },
+      "focusRing": { "width": "4px", "color": "{alias.border-focused}", "inset": "-1px", "borderRadius": "{radius.sm}" }
+    },
+    "focused+error": {
+      "border": { "color": "{alias.border-danger}" },
+      "focusRing": { "width": "4px", "color": "{alias.border-focused-danger}", "inset": "-1px", "borderRadius": "{radius.sm}" }
+    }
+  },
+
+  "props": {
+    "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+    "label": { "type": "string", "description": "Label text above the input." },
+    "optional": { "type": "boolean", "default": false, "description": "Displays (Optional) next to label." },
+    "helperText": { "type": "string", "description": "Helper text below the input." },
+    "helperTextIcon": { "type": "string", "description": "Material Symbol name for helper text icon." },
+    "errorMessage": { "type": "string", "description": "Error message below the input. Overrides helperText." },
+    "maxLength": { "type": "number", "description": "Shows character counter beside the input." },
+    "leftIcon": { "type": "string", "description": "Material Symbol name for leading icon." },
+    "rightIcon": { "type": "string", "description": "Material Symbol name for trailing icon." },
+    "preset": { "type": "enum", "values": ["user", "email", "password", "date", "amount", "description", "search"], "description": "Preset that auto-configures icons, type, and behaviors." },
+    "disabled": { "type": "boolean", "default": false }
+  },
+
+  "presets": {
+    "user": { "leftIcon": "account_circle" },
+    "email": { "leftIcon": "email", "inputType": "email" },
+    "password": { "leftIcon": "lock", "rightIcon": "visibility", "inputType": "password", "hasPasswordToggle": true },
+    "date": { "leftIcon": "calendar_month", "inputType": "date" },
+    "amount": { "leftIcon": "attach_money", "rightIcon": "close", "inputType": "number", "hasClearBehavior": true },
+    "description": { "leftIcon": "description", "optional": true },
+    "search": { "leftIcon": "search", "rightIcon": "close", "optional": true, "hasClearBehavior": true }
+  },
+
+  "slots": {
+    "leftIcon": { "position": "start", "element": "Icon", "size": "md", "color": "{alias.text-tertiary}", "disabledColor": "{alias.icon-inactive-subtle}" },
+    "rightIcon": { "position": "end", "element": "Icon", "size": "md", "color": "{alias.text-tertiary}", "disabledColor": "{alias.icon-inactive-subtle}" },
+    "label": { "position": "above", "fontSize": "14px", "fontWeight": 500, "color": "{alias.text-primary}", "marginBottom": "{spacing.sm}" },
+    "helperText": { "position": "below", "fontSize": "14px", "color": "{alias.text-secondary}", "errorColor": "{alias.text-error}", "marginTop": "{spacing.sm}" },
+    "characterCounter": { "position": "end-outside", "fontSize": "14px", "color": "{alias.text-tertiary}", "errorColor": "{alias.text-error}" }
+  },
+
+  "defaults": { "size": "md" },
+
+  "accessibility": {
+    "role": "textbox",
+    "notes": "aria-invalid set when error. aria-describedby links to helperText or errorMessage. Label uses htmlFor."
+  }
+}