@nysds/components 1.13.0 → 1.13.1

package/dist/.vscode/vscode.html-custom-data.json

@@ -4,41 +4,110 @@
   "tags": [
     {
       "name": "nys-accordion",
-      "description": "`<nys-accordion>` groups one or more `<nys-accordionitem>` elements.\n\nFeatures:\n- Optionally enforces single-expanded-item behavior via `singleSelect`.\n- Propagates shared visual `bordered` property to child items.\n- Generates a stable unique identifier if none is provided.\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle** - Fired when a child `<nys-accordionitem>` is toggled. Event detail includes `{ id: string, heading: string, expanded: boolean }`.\n\n### **Slots:**\n - **default** - Place one or more `<nys-accordionitem>` components here.",
+      "description": "Container for accordion items with optional single-select and bordered styling.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for `nys-accordionitem` elements.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "singleSelect", "values": [] },
-        { "name": "bordered", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "singleSelect",
+          "description": "Only one item can be expanded at a time. Expanding one collapses others.",
+          "values": []
+        },
+        {
+          "name": "bordered",
+          "description": "Adds borders around each accordion item. Propagates to all children.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-accordionitem",
-      "description": "`<nys-accordionitem>` represents a single collapsible item inside a `<nys-accordion>`.\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle** - Fired when the item is expanded or collapsed.\n\n### **Slots:**\n - _default_ - Default slot for the content inside the accordion panel.",
+      "description": "Collapsible panel for use within nys-accordion with keyboard support.\n---\n\n\n### **Events:**\n - **nys-accordionitem-toggle** - Fired when expanded state changes. Detail: `{id, heading, expanded}`.\n\n### **Slots:**\n - _default_ - Default slot for panel content shown when expanded.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "heading", "values": [] },
-        { "name": "expanded", "values": [] },
-        { "name": "bordered", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "heading",
+          "description": "Heading text displayed in the clickable toggle button.",
+          "values": []
+        },
+        {
+          "name": "expanded",
+          "description": "Whether the content panel is visible. Toggle via click or keyboard.",
+          "values": []
+        },
+        {
+          "name": "bordered",
+          "description": "Adds border styling. Set by parent `nys-accordion`, not directly.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-alert",
-      "description": "`<nys-alert>` renders an informational, success, warning, or error alert.\n---\n\n\n### **Events:**\n - **nys-close** - Fired when alert is dismissed (manual or timeout).\n\n### **Slots:**\n - _default_ - Default slot for additional alert content.",
+      "description": "Alert for contextual feedback with semantic types and live region support.\n---\n\n\n### **Events:**\n - **nys-close** - Fired when alert is dismissed. Detail: `{id, type, label}`.\n\n### **Slots:**\n - _default_ - Default slot for custom body content. Overrides `text` prop when provided.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "heading", "values": [] },
-        { "name": "icon", "values": [] },
-        { "name": "dismissible", "values": [] },
-        { "name": "duration", "values": [] },
-        { "name": "text", "values": [] },
-        { "name": "primaryAction", "values": [] },
-        { "name": "secondaryAction", "values": [] },
-        { "name": "primaryLabel", "values": [] },
-        { "name": "secondaryLabel", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "heading",
+          "description": "Bold heading text displayed at the top of the alert.",
+          "values": []
+        },
+        {
+          "name": "icon",
+          "description": "Custom icon name. Defaults to type-appropriate icon if not set.",
+          "values": []
+        },
+        {
+          "name": "dismissible",
+          "description": "Shows close button allowing users to dismiss the alert.",
+          "values": []
+        },
+        {
+          "name": "duration",
+          "description": "Auto-dismiss after specified milliseconds. Set to 0 to disable.",
+          "values": []
+        },
+        {
+          "name": "text",
+          "description": "Body text content. Ignored if slot content is provided.",
+          "values": []
+        },
+        {
+          "name": "primaryAction",
+          "description": "URL for the primary action link.",
+          "values": []
+        },
+        {
+          "name": "secondaryAction",
+          "description": "URL for the secondary action link.",
+          "values": []
+        },
+        {
+          "name": "primaryLabel",
+          "description": "Label text for primary action link.",
+          "values": []
+        },
+        {
+          "name": "secondaryLabel",
+          "description": "Label text for secondary action link.",
+          "values": []
+        },
         {
           "name": "type",
+          "description": "Semantic alert type affecting color and ARIA role. `danger`/`emergency` use assertive live region.",
           "values": [
             { "name": "" },
             { "name": "base" },
@@ -54,38 +123,91 @@
     },
     {
       "name": "nys-avatar",
-      "description": "`<nys-avatar>` displays a user avatar as an image, initials, or icon.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for custom icon content. Fallback icon is used if slot is empty. Features: - Computes foreground color for sufficient contrast based on background. - Supports interactive avatars with button role. - Fallback to icon when image or initials are missing. - Lazy loading for performance optimization.",
+      "description": "User avatar with image, initials, or icon fallback and contrast-aware colors.\n---\n\n\n### **Slots:**\n - _default_ - Custom icon content. Overrides default icon when no image or initials.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "ariaLabel", "values": [] },
-        { "name": "image", "values": [] },
-        { "name": "initials", "values": [] },
-        { "name": "icon", "values": [] },
-        { "name": "color", "values": [] },
-        { "name": "interactive", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "lazy", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "ariaLabel",
+          "description": "Accessible label for screen readers. Required when no image `alt` is available.",
+          "values": []
+        },
+        {
+          "name": "image",
+          "description": "Image URL. Takes priority over initials and icon.",
+          "values": []
+        },
+        {
+          "name": "initials",
+          "description": "1-2 character initials. Used when no image is provided.",
+          "values": []
+        },
+        {
+          "name": "icon",
+          "description": "Custom icon name. Falls back to `account_circle` if not set.",
+          "values": []
+        },
+        {
+          "name": "color",
+          "description": "Background color. Foreground auto-adjusts for contrast. Accepts CSS values or variables.",
+          "values": []
+        },
+        {
+          "name": "interactive",
+          "description": "Makes avatar clickable with button role and focus ring.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction when `interactive` is true.",
+          "values": []
+        },
+        {
+          "name": "lazy",
+          "description": "Enables lazy loading for the image.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-backtotop",
-      "description": "`<nys-backtotop>` renders a button that scrolls the page to the top.\n\nFeatures:\n- Automatically appears after scrolling past 1.5 viewport heights\n  if the page is at least 4 screens tall.\n- Adapts to mobile screens (renders as a circle button when narrow).\n- Can be explicitly shown with the `visible` attribute.\n---\n\n\n### **Events:**\n - **nys-click** - Fired when the button is clicked (scrolls page to top).",
+      "description": "Floating back-to-top button with auto-show behavior and smooth scroll.\n---\n",
       "attributes": [
-        { "name": "position", "values": [] },
-        { "name": "visible", "values": [] }
+        {
+          "name": "position",
+          "description": "Horizontal position: `left` or `right`.",
+          "values": []
+        },
+        {
+          "name": "visible",
+          "description": "Force button visibility. Overrides auto-show scroll behavior.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-badge",
-      "description": "`<nys-badge>` displays a badge with optional prefix/suffix icons and labels.\n\nFeatures:\n- Conveys an intent (`neutral`, `error`, `success`, `warning`) which affects default icons and styling.\n- Supports custom prefix and suffix icons.\n---\n",
+      "description": "Compact label for status, counts, or categorization with semantic styling.\n---\n",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] },
+        { "name": "id", "description": "Unique identifier.", "values": [] },
+        {
+          "name": "name",
+          "description": "Name attribute for form association.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Badge size: `sm` (smaller text) or `md` (default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        },
         {
           "name": "intent",
+          "description": "Semantic intent affecting color: `neutral`, `error`, `success`, or `warning`.",
           "values": [
             { "name": "" },
             { "name": "neutral" },
@@ -94,8 +216,20 @@
             { "name": "warning" }
           ]
         },
-        { "name": "prefixLabel", "values": [] },
-        { "name": "label", "values": [] },
+        {
+          "name": "prefixLabel",
+          "description": "Secondary label displayed before the main label.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Primary label text displayed in the badge.",
+          "values": []
+        },
+        {
+          "name": "variant",
+          "values": [{ "name": "strong" }, { "name": "\"\"" }]
+        },
         { "name": "prefixicon", "values": [] },
         { "name": "suffixicon", "values": [] }
       ],
@@ -103,17 +237,31 @@
     },
     {
       "name": "nys-button",
-      "description": "`<nys-button>` is a versatile button component supporting:\n- Multiple variants (`filled`, `outline`, `ghost`, `text`)\n- Sizes (`sm`, `md`, `lg`) and full-width layout\n- Icons (prefix, suffix, or circle) and optional labels\n- Native `<button>` or link `<a>` behavior with form association\n- Keyboard and accessibility support (`aria-label`, `aria-controls`, `aria-description`)\n---\n\n\n### **Events:**\n - **nys-focus** - Fired when button receives focus\n- **nys-blur** - Fired when button loses focus\n- **nys-click** - Fired on button click",
+      "description": "Button for actions and CTAs with variants, sizes, and icon support.\n---\n\n\n### **Events:**\n - **nys-focus** - Fired when the button receives focus.\n- **nys-blur** - Fired when the button loses focus.\n- **nys-click** - Fired when the button is clicked (mouse or keyboard). Not fired when disabled.\n\n### **Slots:**\n - **prefix-icon** - Icon before label. Not shown for `text` variant.\n- **suffix-icon** - Icon after label. Not shown for `text` variant.\n- **circle-icon** - Icon for circle mode. Overrides `icon` prop.\n\n### **CSS Properties:**\n - **--nys-button-color** - Text color of the button label. _(default: undefined)_\n- **--nys-button-color--hover** - Text color when hovered. _(default: undefined)_\n- **--nys-button-color--active** - Text color when active/pressed. _(default: undefined)_\n- **--nys-button-background-color** - Background color of the button. _(default: undefined)_\n- **--nys-button-background-color--hover** - Background color when hovered. _(default: undefined)_\n- **--nys-button-background-color--active** - Background color when active/pressed. _(default: undefined)_\n- **--nys-button-border-color** - Border color of the button. _(default: undefined)_\n- **--nys-button-border-color--hover** - Border color when hovered. _(default: undefined)_\n- **--nys-button-border-color--active** - Border color when active/pressed. _(default: undefined)_",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
         {
           "name": "size",
+          "description": "Button height: `sm` (40px) for dense UIs, `md` (48px, default) for standard use, `lg` (56px) for prominent CTAs.",
           "values": [{ "name": "sm" }, { "name": "md" }, { "name": "lg" }]
         },
-        { "name": "fullWidth", "values": [] },
+        {
+          "name": "fullWidth",
+          "description": "Expands button to fill container width. Use for mobile layouts or stacked button groups.",
+          "values": []
+        },
         {
           "name": "variant",
+          "description": "Visual style: `filled` for primary (one per section), `outline` for secondary, `ghost` for tertiary, `text` for inline actions. Avoid `text` for navigation.",
           "values": [
             { "name": "" },
             { "name": "filled" },
@@ -122,20 +270,69 @@
             { "name": "text" }
           ]
         },
-        { "name": "inverted", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "ariaLabel", "values": [] },
-        { "name": "ariaControls", "values": [] },
-        { "name": "prefixIcon", "values": [] },
-        { "name": "suffixIcon", "values": [] },
-        { "name": "circle", "values": [] },
-        { "name": "icon", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "ariaDescription", "values": [] },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible button text. Use sentence case, action-oriented text (e.g., \"Save Draft\"). Becomes aria-label in `circle` mode.",
+          "values": []
+        },
+        {
+          "name": "ariaLabel",
+          "description": "Screen reader label. Required for icon-only buttons if `label` is not set.",
+          "values": []
+        },
+        {
+          "name": "ariaControls",
+          "description": "ID of controlled element (e.g., dropdown or modal). Sets `aria-controls`.",
+          "values": []
+        },
+        {
+          "name": "prefixIcon",
+          "description": "Material Symbol icon before label. Not shown for `text` variant or `circle` mode.",
+          "values": []
+        },
+        {
+          "name": "suffixIcon",
+          "description": "Material Symbol icon after label. Use `chevron_down` for dropdowns, `open_in_new` for external links. Not shown for `text` variant or `circle` mode.",
+          "values": []
+        },
+        {
+          "name": "circle",
+          "description": "Renders circular icon-only button. Requires `icon` prop. `label` becomes aria-label.",
+          "values": []
+        },
+        {
+          "name": "icon",
+          "description": "Icon for circle mode. Required when `circle` is true. Scales with size (sm=24px, md=32px, lg=40px).",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction. Avoid disabling without explanation—show validation errors instead.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with. Use when button is outside the form element.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Value submitted with form data. Only used when `type=\"submit\"`.",
+          "values": []
+        },
+        {
+          "name": "ariaDescription",
+          "description": "Additional screen reader description. Sets `aria-description`.",
+          "values": []
+        },
         {
           "name": "type",
+          "description": "Form behavior: `button` (default, no form action), `submit` (submits form), `reset` (resets form). Always set explicitly to avoid unintended submissions.",
           "values": [
             { "name": "" },
             { "name": "submit" },
@@ -143,9 +340,14 @@
             { "name": "button" }
           ]
         },
-        { "name": "href", "values": [] },
+        {
+          "name": "href",
+          "description": "URL to navigate to. Renders as `<a>` tag. Omit for action buttons.",
+          "values": []
+        },
         {
           "name": "target",
+          "description": "Link target: `_self` (same tab), `_blank` (new tab—add `suffixIcon=\"open_in_new\"`), `_parent`, `_top`, or frame name.",
           "values": [
             { "name": "" },
             { "name": "_self" },
@@ -160,44 +362,160 @@
     },
     {
       "name": "nys-checkbox",
-      "description": "`<nys-checkbox>` is an accessible, form-associated checkbox component.\nCan be used standalone or within a `<nys-checkboxgroup>`.\n\nFeatures:\n- Supports labels, descriptions, and tooltips\n- Displays error messages with `showError` and `errorMessage`\n- Keyboard interaction with spacebar toggle\n- Form integration via ElementInternals (`checked` value submitted)\n---\n\n\n### **Events:**\n - **nys-change** - Fired when checkbox value changes\n- **nys-focus** - Fired on focus\n- **nys-blur** - Fired on blur\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Slot to provide a custom description element",
+      "description": "Checkbox for binary choices or multi-select options.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when checked state changes. Detail: `{id, checked, name, value}`.\n- **nys-focus** - Fired when checkbox gains focus.\n- **nys-blur** - Fired when checkbox loses focus.\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "checked", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
-        { "name": "groupExist", "values": [] },
-        { "name": "tile", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] }
+        {
+          "name": "checked",
+          "description": "Whether checkbox is checked.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Marks as required. Validates that checkbox is checked.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission. Use same name for grouped checkboxes.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Value submitted when checked.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with when checkbox is outside form element.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        },
+        {
+          "name": "groupExist",
+          "description": "Internal: Set by parent checkboxgroup. Do not set manually.",
+          "values": []
+        },
+        {
+          "name": "tile",
+          "description": "Renders as tile with larger clickable area. Apply to group for consistency.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Checkbox size: `sm` (24px) or `md` (32px, default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        }
       ],
       "references": []
     },
     {
       "name": "nys-checkboxgroup",
-      "description": "`<nys-checkboxgroup>` is a form-associated container for multiple `<nys-checkbox>` components.\nHandles grouping, validation, required constraints, form submission, and accessibility.\n\nFeatures:\n- Manages multiple checkboxes as a single form field\n- Supports required/optional flags and error messages\n- Propagates size, tile, and inverted styling to child checkboxes\n- Keyboard and screen reader accessible via fieldset/legend\n---\n\n\n### **Events:**\n - **nys-change** - Fired when any child checkbox changes\n- **nys-focus** - Fired when any child checkbox gains focus\n- **nys-blur** - Fired when any child checkbox loses focus\n\n### **Slots:**\n - **default** - Slot for child `<nys-checkbox>` elements\n- **description** - Slot for custom description content",
+      "description": "Container for grouping checkboxes as a single form control.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for `nys-checkbox` elements.\n- **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "tile", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission. Set on group, not individual checkboxes.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Requires at least one checkbox to be checked.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text for the group.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "tile",
+          "description": "Renders all checkboxes as tiles with larger clickable area.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds. Applied to all children.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with. Applied to all children.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Checkbox size for all children: `sm` (24px) or `md` (32px, default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        }
       ],
       "references": []
     },
@@ -231,50 +549,133 @@
     },
     {
       "name": "nys-divider",
-      "description": "`<nys-divider>` renders a horizontal rule `<hr>` element with optional styling.\nCan be inverted for dark backgrounds.\n---\n",
-      "attributes": [{ "name": "inverted", "values": [] }],
+      "description": "Horizontal divider for visual separation of content sections.\n---\n",
+      "attributes": [
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        }
+      ],
       "references": []
     },
     {
       "name": "nys-errormessage",
-      "description": "THIS IS A PRIVATE COMPONENT!\n`<nys-errormessage>` displays an error message for form elements.\nCan optionally show a divider and supports native form validation messages.\n---\n",
+      "description": "Internal error message display with icon and ARIA alert support.\n---\n",
       "attributes": [
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
-        { "name": "showDivider", "values": [] }
+        {
+          "name": "showError",
+          "description": "Whether to display the error message.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error text to display. Falls back to native validation message if available.",
+          "values": []
+        },
+        {
+          "name": "showDivider",
+          "description": "Shows a divider line above the error message.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-fileinput",
-      "description": "`<nys-fileinput>` provides accessible file selection with optional\ndrag-and-drop support, progress tracking, validation, and form submission.\n\nFeatures:\n- Supports single or multiple file uploads\n- Optional drag-and-drop dropzone\n- File type validation and upload progress\n- Form-associated with native validation behavior\n- Keyboard and screen reader accessible\n---\n\n\n### **Events:**\n - **nys-change** - Fired when files are added or removed\n\n### **Slots:**\n - **description** - Custom description content under the label",
+      "description": "File input with drag-and-drop, validation, and progress tracking.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when files are added or removed. Detail: `{id, files}`.\n\n### **Slots:**\n - **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "multiple", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "accept", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
-        { "name": "dropzone", "values": [] },
-        { "name": "width", "values": [{ "name": "lg" }, { "name": "full" }] },
-        { "name": "inverted", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
+        { "name": "label", "description": "Visible label text.", "values": [] },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "multiple",
+          "description": "Allows selecting multiple files.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "accept",
+          "description": "Accepted file types. Use MIME types (`image/*`) or extensions (`.pdf`). Validated via magic bytes.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Requires at least one file to be uploaded.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        },
+        {
+          "name": "dropzone",
+          "description": "Enables drag-and-drop zone UI.",
+          "values": []
+        },
+        {
+          "name": "width",
+          "description": "Component width: `lg` (384px) or `full` (100%, default).",
+          "values": [{ "name": "lg" }, { "name": "full" }]
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-fileitem",
-      "description": "`<nys-fileitem>` displays an individual file in a file input component.\nIt shows the file name, upload status, progress bar, and error messages.\n---\n\n\n### **Events:**\n - **nys-fileRemove**",
+      "description": "Internal file item display with status, progress bar, and remove action.\n---\n\n\n### **Events:**\n - **nys-fileRemove** - Fired when remove button is clicked. Detail: `{filename}`.",
       "attributes": [
-        { "name": "filename", "values": [] },
+        {
+          "name": "filename",
+          "description": "Name of the file being displayed.",
+          "values": []
+        },
         {
           "name": "status",
+          "description": "Upload status: `pending` (queued), `processing` (uploading), `done` (complete), `error` (failed).",
           "values": [
             { "name": "" },
             { "name": "pending" },
@@ -283,41 +684,90 @@
             { "name": "error" }
           ]
         },
-        { "name": "progress", "values": [] },
-        { "name": "errorMessage", "values": [] }
+        {
+          "name": "progress",
+          "description": "Upload progress percentage (0-100). Only shown when status is `processing`.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message displayed when status is `error`.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-globalfooter",
-      "description": "`<nys-globalfooter>` renders a New York State–style global footer.\n\nDisplays an agency name with an optional homepage link and supports\nstructured footer content via slots.\n---\n\n\n### **Slots:**\n - **default** - Footer content such as headings, links, or groups Layout behavior: - Multiple `<h4>` elements trigger a multi-column layout - Single group content renders in a compact layout",
+      "description": "Agency footer with auto-layout for contact info and link sections.\n---\n\n\n### **Slots:**\n - _default_ - Footer content (links, contact info). Use `<h4>` for column headings.",
       "attributes": [
-        { "name": "agencyName", "values": [] },
-        { "name": "homepageLink", "values": [] }
+        {
+          "name": "agencyName",
+          "description": "Agency name displayed as the footer heading.",
+          "values": []
+        },
+        {
+          "name": "homepageLink",
+          "description": "URL for the agency name link. If empty, name is not clickable.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-globalheader",
-      "description": "`<nys-globalheader>` renders a New York State–style global header.\n\nDisplays an optional application name, agency name, and homepage link.\nSupports slotted navigation content with automatic active-link detection\nand a responsive mobile menu.\n---\n\n\n### **Slots:**\n - **default** - Primary navigation list, typically a `<ul>` with links\n- **user-actions** - Optional user action elements such as login or profile Behavior: - Automatically highlights the best matching link based on the current URL - Duplicates navigation content for desktop and mobile layouts - Provides a toggleable mobile menu when navigation content exists",
+      "description": "Agency header with navigation, mobile menu, and active link highlighting.\n---\n\n\n### **Slots:**\n - _default_ - Navigation content (typically `<ul>` with `<li><a>` links). Auto-sanitized.",
       "attributes": [
-        { "name": "appName", "values": [] },
-        { "name": "agencyName", "values": [] },
-        { "name": "homepageLink", "values": [] }
+        {
+          "name": "appName",
+          "description": "Application name displayed prominently.",
+          "values": []
+        },
+        {
+          "name": "agencyName",
+          "description": "Agency name displayed below app name (or as main title if no appName).",
+          "values": []
+        },
+        {
+          "name": "homepageLink",
+          "description": "URL for the header title link. If empty, title is not clickable.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-icon",
-      "description": "`<nys-icon>` renders an SVG icon from the internal icon library.\n\nIcons are inline SVGs and support sizing, rotation, flipping, color,\nand accessibility labeling.\n---\n",
+      "description": "SVG icon from Material Symbols library with size, rotation, and color options.\n---\n",
       "attributes": [
-        { "name": "name", "values": [] },
-        { "name": "ariaLabel", "values": [] },
-        { "name": "rotate", "values": [] },
-        { "name": "flip", "values": [] },
-        { "name": "color", "values": [] },
+        {
+          "name": "name",
+          "description": "Icon name from Material Symbols library. Required.",
+          "values": []
+        },
+        {
+          "name": "ariaLabel",
+          "description": "Accessible label. When set, removes `aria-hidden` and adds `aria-label` to the SVG.",
+          "values": []
+        },
+        {
+          "name": "rotate",
+          "description": "Rotation in degrees. Applied via CSS `rotate`.",
+          "values": []
+        },
+        {
+          "name": "flip",
+          "description": "Flip direction: `horizontal`, `vertical`, or empty for none.",
+          "values": []
+        },
+        {
+          "name": "color",
+          "description": "Icon color. Accepts any CSS color value. Defaults to `currentcolor`.",
+          "values": []
+        },
         {
           "name": "size",
+          "description": "Icon size. Semantic sizes: `xs`-`5xl`. Pixel sizes: `12`-`50`.",
           "values": [
             { "name": "" },
             { "name": "xs" },
@@ -345,28 +795,73 @@
     },
     {
       "name": "nys-label",
-      "description": "THIS IS A PRIVATE COMPONENT!\n`NysLabel` is a component for rendering form labels with optional\ndescriptions, flags (required/optional), and tooltips.\n---\n",
+      "description": "Internal label component for form fields with flag and tooltip support.\n---\n\n\n### **Slots:**\n - **description** - Custom HTML description content below the label.",
       "attributes": [
-        { "name": "for", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "flag", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "tooltip", "values": [] }
+        {
+          "name": "for",
+          "description": "ID of the form element this label is associated with.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Label text displayed above the form field.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text displayed below the label.",
+          "values": []
+        },
+        {
+          "name": "flag",
+          "description": "Flag type: `required` shows asterisk, `optional` shows \"(Optional)\".",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon next to label.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-modal",
-      "description": "`<nys-modal>` renders an accessible modal dialog.\n\nSupports headings, optional subheading, body content, and action buttons.\nManages focus trapping, escape key handling, and body scroll locking.\n---\n\n\n### **Events:**\n - **nys-open** - Emitted when the modal opens\n- **nys-close** - Emitted when the modal closes\n\n### **Slots:**\n - _default_ - Modal body content\n- **actions** - Action buttons shown in the footer",
+      "description": "Accessible modal dialog with focus trap, keyboard support, and action slots.\n---\n\n\n### **Events:**\n - **nys-open** - Fired when modal opens. Detail: `{id}`.\n- **nys-close** - Fired when modal closes. Detail: `{id}`.\n\n### **Slots:**\n - _default_ - Default slot for body content.\n- **actions** - Action buttons displayed in footer. Buttons auto-resize on mobile.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "heading", "values": [] },
-        { "name": "subheading", "values": [] },
-        { "name": "open", "values": [] },
-        { "name": "mandatory", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "heading",
+          "description": "Modal heading text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "subheading",
+          "description": "Secondary heading below the main heading.",
+          "values": []
+        },
+        {
+          "name": "open",
+          "description": "Controls modal visibility. Set to `true` to show.",
+          "values": []
+        },
+        {
+          "name": "mandatory",
+          "description": "Prevents dismissal via close button or Escape key. User must take an action.",
+          "values": []
+        },
         {
           "name": "width",
+          "description": "Modal width: `sm` (400px), `md` (600px), or `lg` (800px).",
           "values": [{ "name": "sm" }, { "name": "md" }, { "name": "lg" }]
         }
       ],
@@ -374,86 +869,279 @@
     },
     {
       "name": "nys-pagination",
-      "description": "`<nys-pagination>` renders page navigation controls.\n\nDisplays previous and next buttons, page numbers, and ellipses\nwhen pages are skipped. Handles page bounds automatically.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the page changes detail: { page: number }",
+      "description": "Page navigation with numbered links, prev/next buttons, and responsive layout.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when page changes. Detail: `{page}`.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "currentPage", "values": [] },
-        { "name": "totalPages", "values": [] },
-        { "name": "_twoBeforeLast", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name attribute for form association.",
+          "values": []
+        },
+        {
+          "name": "currentPage",
+          "description": "Currently active page (1-indexed). Clamped to valid range.",
+          "values": []
+        },
+        {
+          "name": "totalPages",
+          "description": "Total number of pages. Must be at least 1.",
+          "values": []
+        },
+        {
+          "name": "_twoBeforeLast",
+          "description": "Internal state for layout adjustments near the end.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-radiobutton",
-      "description": "`<nys-radiobutton>` represents a single radio button for use in a `<nys-radiogroup>`.\n\nFeatures:\n- Single selection per group\n- Supports labels, descriptions, tile layout, inverted style, and size variants\n- Integrates with forms and dispatches `nys-change` events on selection\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the radio is selected or deselected detail: { id: string, checked: boolean, name: string, value: string }\n- **nys-focus** - Fired when the radio gains focus\n- **nys-blur** - Fired when the radio loses focus\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional description text announced to screen readers",
+      "description": "Radio button for single selection from mutually exclusive options.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when selection changes. Detail: `{id, checked, name, value}`.\n- **nys-focus** - Fired when radio gains focus.\n- **nys-blur** - Fired when radio loses focus.\n\n### **Methods:**\n - **getInputElement(): _Promise<HTMLInputElement | null>_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "checked", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] },
-        { "name": "tile", "values": [] }
+        {
+          "name": "checked",
+          "description": "Whether this radio is selected. Only one per group can be checked.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Marks group as required. Set on radiogroup, not individual radios.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Group name. Radios with same name are mutually exclusive.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Value submitted when this radio is selected.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Radio size: `sm` (24px) or `md` (32px, default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        },
+        {
+          "name": "tile",
+          "description": "Renders as tile with larger clickable area.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-radiogroup",
-      "description": "`<nys-radiogroup>` groups `<nys-radiobutton>` elements into a single\nselectable control.\n\nSupports keyboard navigation, validation, and native form submission\nthrough ElementInternals.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when selection changes detail: { name: string; value: string }\n\n### **Slots:**\n - **default** - One or more `<nys-radiobutton>` elements\n- **description** - Optional descriptive text announced to screen readers",
+      "description": "Container for grouping radio buttons as a single form control.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for `nys-radiobutton` elements.\n- **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "tile", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission. Auto-populated from child radiobuttons.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Requires a selection before form submission.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text for the group.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "tile",
+          "description": "Renders all radiobuttons as tiles with larger clickable area.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds. Applied to all children.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with. Applied to all children.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Radio size for all children: `sm` (24px) or `md` (32px, default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        }
       ],
       "references": []
     },
     {
       "name": "nys-option",
-      "description": "\n---\n",
+      "description": "Option item for nys-select dropdown.\n---\n\n\n### **Slots:**\n - _default_ - Option label text. Auto-populates the `label` prop if provided.",
       "attributes": [
-        { "name": "disabled", "values": [] },
-        { "name": "selected", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "hidden", "values": [] }
+        {
+          "name": "disabled",
+          "description": "Prevents selection of this option.",
+          "values": []
+        },
+        {
+          "name": "selected",
+          "description": "Pre-selects this option.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Value submitted when this option is selected.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Display text for the option. Auto-populated from slot content if not set.",
+          "values": []
+        },
+        {
+          "name": "hidden",
+          "description": "Hides the option from the dropdown list.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-select",
-      "description": "`<nys-select>` is a custom select/dropdown component.\n\nFeatures:\n- Supports slotted `<nys-option>` elements, native `<option>` and `<optgroup>`\n- Integrates with forms via ElementInternals\n- Handles validation, error messages, and required/optional states\n- Inverted style and width variants supported\n---\n\n\n### **Events:**\n - **nys-change** - Fired when the selected value changes detail: { id: string, value: string }\n- **nys-focus** - Fired when the select gains focus\n- **nys-blur** - Fired when the select loses focus\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional description text announced to screen readers\n- **default** - Options (<nys-option>, <option>, <optgroup>) to populate the dropdown",
+      "description": "Dropdown select for choosing one option from a list.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when selection changes. Detail: `{id, value}`.\n- **nys-focus** - Fired when select gains focus.\n- **nys-blur** - Fired when select loses focus. Triggers validation.\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - _default_ - Default slot for `<option>` and `<optgroup>` elements.\n- **description** - Custom HTML description content below the label.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Currently selected option value.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Marks as required. Shows \"Required\" flag and validates on blur.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag. Use when most fields are required.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with when select is outside form element.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true. Set by validation or manually.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        },
         {
           "name": "width",
+          "description": "Select width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).",
           "values": [
             { "name": "" },
             { "name": "sm" },
@@ -467,35 +1155,83 @@
     },
     {
       "name": "nys-skipnav",
-      "description": "`<nys-skipnav>` provides an accessible skip navigation link for keyboard\nand screen reader users to jump directly to the main content of a page.\n\nFeatures:\n- Default target is `#main-content` if `href` is not provided\n- Link becomes visible on focus and hides on blur\n- Ensures the target element is focusable for accessibility\n---\n",
+      "description": "Skip navigation link for keyboard accessibility. Hidden until focused.\n---\n",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "href", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "href",
+          "description": "Target element ID (with `#`). Defaults to `#main-content`.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-step",
-      "description": "\n---\n",
+      "description": "Individual step for use within nys-stepper with navigation support.\n---\n\n\n### **Events:**\n - **nys-step-click** - Fired when a navigable step is clicked. Detail: `{href, label}`. Cancelable.",
       "attributes": [
-        { "name": "selected", "values": [] },
-        { "name": "current", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "href", "values": [] },
-        { "name": "isCompactExpanded", "values": [] },
-        { "name": "stepNumber", "values": [] }
+        {
+          "name": "selected",
+          "description": "Whether this step is currently being viewed. Set by parent stepper.",
+          "values": []
+        },
+        {
+          "name": "current",
+          "description": "Marks the furthest reached step. Steps before this are navigable.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Step label text displayed alongside the step number.",
+          "values": []
+        },
+        {
+          "name": "href",
+          "description": "URL for page navigation when step is clicked. Optional for SPA routing.",
+          "values": []
+        },
+        {
+          "name": "isCompactExpanded",
+          "description": "Internal: Whether parent stepper's compact view is expanded.",
+          "values": []
+        },
+        {
+          "name": "stepNumber",
+          "description": "Step number (1-indexed). Auto-assigned by parent stepper.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-stepper",
-      "description": "`<nys-stepper>` manages a sequence of `<nys-step>` elements, providing\nmulti-step navigation for forms or workflows.\n\nFeatures:\n- Tracks selected and current steps\n- Displays a step counter (e.g., \"Step 2 of 5\")\n- Supports compact/expanded view toggle\n- Validates that only `<nys-step>` or `<div slot=\"actions\">` children are used\n---\n\n\n### **Events:**\n - **nys-step-click** - Fired when a step is clicked; bubbles with the event path",
+      "description": "Multi-step progress indicator with navigation and mobile-friendly compact view.\n---\n\n\n### **Slots:**\n - _default_ - Default slot for `nys-step` elements.\n- **actions** - Navigation buttons (e.g., Back, Continue). Must be wrapped in a `<div>`.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "counterText", "values": [] },
-        { "name": "isCompactExpanded", "values": [] }
+        { "name": "id", "description": "Unique identifier.", "values": [] },
+        {
+          "name": "name",
+          "description": "Name attribute for form association.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Title displayed above the step counter.",
+          "values": []
+        },
+        {
+          "name": "counterText",
+          "description": "Progress text (e.g., \"Step 2 of 5\"). Auto-updated based on selection.",
+          "values": []
+        },
+        {
+          "name": "isCompactExpanded",
+          "description": "Whether compact mobile view is expanded to show all steps.",
+          "values": []
+        }
       ],
       "references": []
     },
@@ -514,24 +1250,81 @@
     },
     {
       "name": "nys-textarea",
-      "description": "`<nys-textarea>` is a form-enabled textarea with validation, accessibility support,\nand live error messages. Integrates with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input, detail: `{ id, value }`\n- **nys-focus** - Fired on focus.\n- **nys-blur** - Fired on blur.\n- **nys-select** - Fired on text selection, detail: `{ id, value }`\n- **nys-selectionchange** - Fired on selection change, detail: `{ id, value }`\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional slot for custom description content below the label.",
+      "description": "Multi-line text input for comments, descriptions, and feedback.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input change. Detail: `{id, value}`.\n- **nys-focus** - Fired when textarea gains focus.\n- **nys-blur** - Fired when textarea loses focus. Triggers validation.\n- **nys-select** - Fired when user selects text. Detail: `{id, value}`.\n- **nys-selectionchange**\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Custom HTML description content below the label.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "placeholder", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "readonly", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "maxlength", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
+        {
+          "name": "label",
+          "description": "Visible label text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "placeholder",
+          "description": "Placeholder text. Don't use as label replacement.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Current textarea value.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "readonly",
+          "description": "Makes textarea read-only but focusable.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Marks as required. Shows \"Required\" flag and validates on blur.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag. Use when most fields are required.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with when textarea is outside form element.",
+          "values": []
+        },
+        {
+          "name": "maxlength",
+          "description": "Maximum character length.",
+          "values": []
+        },
         {
           "name": "width",
+          "description": "Textarea width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).",
           "values": [
             { "name": "" },
             { "name": "sm" },
@@ -540,24 +1333,46 @@
             { "name": "full" }
           ]
         },
-        { "name": "rows", "values": [] },
+        {
+          "name": "rows",
+          "description": "Visible height in lines.",
+          "values": []
+        },
         {
           "name": "resize",
+          "description": "Resize behavior: `vertical` (default, user can resize height), `none` (fixed size).",
           "values": [{ "name": "vertical" }, { "name": "none" }]
         },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] }
+        {
+          "name": "showError",
+          "description": "Shows error message when true. Set by validation or manually.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-textinput",
-      "description": "`<nys-textinput>` is a form-enabled text input with validation, optional\nmasking, password toggle, accessibility support, and live error messages.\nWorks with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input change. Detail: `{ id, value }`.\n- **nys-focus** - Fired when input receives focus.\n- **nys-blur** - Fired when input loses focus.\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Optional custom description content below the label.\n- **startButton** - Slot for a single <nys-button> at the start of the input.\n- **endButton** - Slot for a single <nys-button> at the end of the input.",
+      "description": "Text input for short single-line data with validation and masking support.\n---\n\n\n### **Events:**\n - **nys-input** - Fired on input change. Detail: `{id, value}`.\n- **nys-focus** - Fired when input gains focus.\n- **nys-blur** - Fired when input loses focus. Triggers validation.\n\n### **Methods:**\n - **checkValidity(): _boolean_** - Functions\n--------------------------------------------------------------------------\n\n### **Slots:**\n - **description** - Custom HTML description content below the label.\n- **startButton** - Button at input start. Use single `nys-button` only.\n- **endButton** - Button at input end. Use single `nys-button` only.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
         {
           "name": "type",
+          "description": "Input type: `text` (default), `email`, `number`, `password`, `search`, `tel` (auto-masked), `url`.",
           "values": [
             { "name": "" },
             { "name": "email" },
@@ -569,20 +1384,69 @@
             { "name": "url" }
           ]
         },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "placeholder", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "readonly", "values": [] },
-        { "name": "required", "values": [] },
-        { "name": "optional", "values": [] },
-        { "name": "tooltip", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "pattern", "values": [] },
-        { "name": "maxlength", "values": [] },
+        {
+          "name": "label",
+          "description": "Visible label text. Required for accessibility.",
+          "values": []
+        },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "placeholder",
+          "description": "Placeholder text. Don't use as label replacement.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Current input value.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "readonly",
+          "description": "Makes input read-only but focusable.",
+          "values": []
+        },
+        {
+          "name": "required",
+          "description": "Marks as required. Shows \"Required\" flag and validates on blur.",
+          "values": []
+        },
+        {
+          "name": "optional",
+          "description": "Shows \"Optional\" flag. Use when most fields are required.",
+          "values": []
+        },
+        {
+          "name": "tooltip",
+          "description": "Tooltip text shown on hover/focus of info icon.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with when input is outside form element.",
+          "values": []
+        },
+        {
+          "name": "pattern",
+          "description": "Regex pattern for validation. Shows error on mismatch.",
+          "values": []
+        },
+        {
+          "name": "maxlength",
+          "description": "Maximum character length.",
+          "values": []
+        },
         {
           "name": "width",
+          "description": "Input width: `sm` (88px), `md` (200px), `lg` (384px), `full` (100%, default).",
           "values": [
             { "name": "" },
             { "name": "sm" },
@@ -591,61 +1455,170 @@
             { "name": "full" }
           ]
         },
-        { "name": "step", "values": [] },
-        { "name": "min", "values": [] },
-        { "name": "max", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "showError", "values": [] },
-        { "name": "errorMessage", "values": [] }
+        {
+          "name": "step",
+          "description": "Step increment for `type=\"number\"`.",
+          "values": []
+        },
+        {
+          "name": "min",
+          "description": "Minimum value for `type=\"number\"`.",
+          "values": []
+        },
+        {
+          "name": "max",
+          "description": "Maximum value for `type=\"number\"`.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "showError",
+          "description": "Shows error message when true. Set by validation or manually.",
+          "values": []
+        },
+        {
+          "name": "errorMessage",
+          "description": "Error message text. Shown only when `showError` is true.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-toggle",
-      "description": "`<nys-toggle>` is a form-associated toggle switch with label, description,\nsize variants, inverted styles, and optional icons. Supports keyboard\ninteraction and integrates with forms via ElementInternals.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when toggle changes state. Detail: `{ id, checked }`.\n- **nys-focus** - Fired when toggle receives focus.\n- **nys-blur** - Fired when toggle loses focus.\n\n### **Slots:**\n - **description** - Optional slot to provide additional description below the label.",
+      "description": "Toggle switch for binary settings with immediate effect.\n---\n\n\n### **Events:**\n - **nys-change** - Fired when toggle state changes. Detail: `{id, checked}`.\n- **nys-focus** - Fired when toggle gains focus.\n- **nys-blur** - Fired when toggle loses focus.\n\n### **Slots:**\n - **description** - Custom HTML description content.",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "name", "values": [] },
-        { "name": "value", "values": [] },
-        { "name": "label", "values": [] },
-        { "name": "description", "values": [] },
-        { "name": "form", "values": [] },
-        { "name": "checked", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "noIcon", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "size", "values": [{ "name": "sm" }, { "name": "md" }] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "name",
+          "description": "Name for form submission.",
+          "values": []
+        },
+        {
+          "name": "value",
+          "description": "Value submitted when toggle is on.",
+          "values": []
+        },
+        { "name": "label", "description": "Visible label text.", "values": [] },
+        {
+          "name": "description",
+          "description": "Helper text below label. Use slot for custom HTML.",
+          "values": []
+        },
+        {
+          "name": "form",
+          "description": "Form `id` to associate with.",
+          "values": []
+        },
+        {
+          "name": "checked",
+          "description": "Whether toggle is on.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Prevents interaction.",
+          "values": []
+        },
+        {
+          "name": "noIcon",
+          "description": "Hides check/close icon inside toggle knob.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "size",
+          "description": "Toggle size: `sm` or `md` (default).",
+          "values": [{ "name": "sm" }, { "name": "md" }]
+        }
       ],
       "references": []
     },
     {
       "name": "nys-tooltip",
-      "description": "`<nys-tooltip>` is a custom tooltip component for NYS design system elements.\nIt supports dynamic positioning, screen-reader accessibility, keyboard interaction,\nand viewport overflow handling.\n\nThe tooltip automatically positions itself relative to a target element specified\nvia the `for` attribute, but can also respect a user-defined position.\n---\n\n\n### **Events:**\n - **nys-focus** - Dispatched when the reference element receives focus (via keyboard or programmatically).\n- **nys-blur** - Dispatched when the reference element loses focus or mouse leaves the tooltip. Notes: - Tooltip visibility is automatically managed on hover/focus of the reference element. - The component adjusts position dynamically to prevent overflow off-screen. - Supports keyboard dismissal with the Escape key.",
+      "description": "Contextual tooltip with auto-positioning, keyboard support, and screen reader integration.\n---\n",
       "attributes": [
-        { "name": "id", "values": [] },
-        { "name": "text", "values": [] },
-        { "name": "inverted", "values": [] },
-        { "name": "for", "values": [] },
-        { "name": "position", "values": [] }
+        {
+          "name": "id",
+          "description": "Unique identifier. Auto-generated if not provided.",
+          "values": []
+        },
+        {
+          "name": "text",
+          "description": "Tooltip content text. Required.",
+          "values": []
+        },
+        {
+          "name": "inverted",
+          "description": "Adjusts colors for dark backgrounds.",
+          "values": []
+        },
+        {
+          "name": "for",
+          "description": "ID of the trigger element to attach this tooltip to. Required.",
+          "values": []
+        },
+        {
+          "name": "position",
+          "description": "Preferred position relative to trigger. Auto-adjusts if space is insufficient.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "nys-unavfooter",
-      "description": "`<nys-unavfooter>` is a footer component for New York State websites.\nIt displays the official NYS logo linking to ny.gov and a set of primary navigation links.\n\nFeatures:\n- Renders the NYS logo as an inline SVG linking to https://www.ny.gov\n- Provides key navigation links\n---\n",
+      "description": "Universal NYS footer with logo and statewide links. Required site-wide.\n---\n",
       "attributes": [],
       "references": []
     },
     {
       "name": "nys-unavheader",
-      "description": "`<nys-unavheader>` is a universal header for New York State websites.\n\nFeatures:\n- Trust bar indicating official NYS site status, with expandable details\n- NYS logo linking to the homepage\n- Search bar with dropdown behavior for mobile and desktop\n- Language translation dropdown supporting multiple languages\n- Accessible interactions with ARIA attributes and keyboard handling\n---\n",
-      "attributes": [
-        { "name": "trustbarVisible", "values": [] },
-        { "name": "searchDropdownVisible", "values": [] },
-        { "name": "languageVisible", "values": [] },
-        { "name": "isSearchFocused", "values": [] },
-        { "name": "hideTranslate", "values": [] },
-        { "name": "hideSearch", "values": [] },
+      "description": "Universal NYS header with trust bar, search, and translation. Required site-wide.\n---\n",
+      "attributes": [
+        {
+          "name": "trustbarVisible",
+          "description": "Internal: Whether trust bar panel is expanded.",
+          "values": []
+        },
+        {
+          "name": "searchDropdownVisible",
+          "description": "Internal: Whether search dropdown is visible (mobile).",
+          "values": []
+        },
+        {
+          "name": "languageVisible",
+          "description": "Internal: Whether language dropdown is visible.",
+          "values": []
+        },
+        {
+          "name": "isSearchFocused",
+          "description": "Internal: Whether search input is focused.",
+          "values": []
+        },
+        {
+          "name": "hideTranslate",
+          "description": "Hides the translation dropdown.",
+          "values": []
+        },
+        {
+          "name": "hideSearch",
+          "description": "Hides the search functionality.",
+          "values": []
+        },
+        { "name": "searchUrl", "values": [] },
         {
           "name": "languages",
           "values": [{ "name": "[string" }, { "name": "string][]" }]