ionbase-ui 0.48.0 → 0.59.0

package/dist/meta/components.json

@@ -1,11 +1,224 @@
 {
   "package": "ionbase-ui",
-  "version": "0.48.0",
+  "version": "0.59.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
   ],
   "components": {
+    "Accordion": {
+      "name": "Accordion",
+      "source": "src/components/Accordion.tsx",
+      "propsType": "AccordionProps",
+      "description": "Accordion — sections that collapse, with the heading structure intact.\n\nWHY THE TRIGGER IS A BUTTON INSIDE A HEADING\n\nBoth parts are load-bearing and the obvious implementations drop one of them.\nThe heading is how a screen-reader user navigates a long page — pressing `h`\nmoves between sections, and an accordion built from `div`s removes every one\nof those stops. The button is what makes the section operable by keyboard and\nannounced as expandable; a heading with a click handler is neither.\n\nSo the shape is `<h3><button aria-expanded aria-controls>`, which is the only\narrangement that keeps document structure AND operability.\n\n`headingLevel` is a prop with no safe default beyond 3, because the right\nlevel depends on the document around it and nothing here can see that. Two\naccordions at the wrong level produce a page whose outline is nonsense while\nlooking perfectly fine.\n\nTHE PANEL IS NOT UNMOUNTED\n\nCollapsed sections keep their DOM and are hidden with `hidden`. Unmounting\nwould lose form state in a collapsed section — the classic multi-step-form\nbug where answers vanish when a section is folded away — and would break\nin-page search, which cannot find text that is not there.",
+      "import": "import { Accordion } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Sections that collapse, with the document's heading structure intact. Holds the open set and the heading level.",
+      "useWhen": [
+        "a page has several long sections and most users need one of them",
+        "optional or advanced settings should be present but not in the way",
+        "an FAQ or a reference list where scanning titles is the primary action"
+      ],
+      "useInstead": [
+        {
+          "when": "the sections are alternatives and only one is ever relevant",
+          "use": "Tabs",
+          "why": "tabs say \"pick one\"; an accordion says \"all of these exist, open what you need\""
+        },
+        {
+          "when": "hiding the content would hide something the user must act on",
+          "use": "render it directly",
+          "why": "a required field inside a collapsed section is a form that cannot be completed without exploration"
+        }
+      ],
+      "slots": {
+        "children": {
+          "accepts": "AccordionItem"
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`headingLevel` that fits the surrounding document — the default of 3 is a guess this component cannot verify"
+        ],
+        "notes": [
+          "each section's trigger is a button inside a heading, which is the only arrangement that keeps both document structure and operability",
+          "collapsed panels are hidden rather than unmounted, so form state survives and in-page search still finds the text"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "allowsMultiple on a long FAQ",
+          "do": "leave it off, so opening one section closes the last",
+          "why": "with every section openable at once the page has no maximum height, and a user who opens six is scrolling a wall of text looking for the one they wanted. Reach for it when sections are settings or reference material a user may need to compare side by side"
+        },
+        {
+          "dont": "headingLevel left at 3 inside a section already under an h4",
+          "do": "headingLevel={5}",
+          "why": "the page looks correct and its outline is nonsense — a heading-level jump is invisible to sighted users and disorienting to everyone navigating by headings"
+        },
+        {
+          "dont": "an accordion holding a single section",
+          "do": "a heading and the content",
+          "why": "one collapsible section is a control that exists to hide the only thing on screen"
+        }
+      ],
+      "stylesheet": "src/styles/accordion.css",
+      "tokens": [
+        "--border-focus",
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--icon-size-md",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-4",
+        "--text-default",
+        "--text-disabled",
+        "--text-primary",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height"
+      ],
+      "props": {
+        "allowsMultiple": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Let more than one section be open at once."
+        },
+        "defaultExpandedKeys": {
+          "type": "string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Uncontrolled: which sections start open."
+        },
+        "expandedKeys": {
+          "type": "string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Controlled: which sections are open. Pass `onExpandedChange` with it."
+        },
+        "onExpandedChange": {
+          "type": "((keys: string[]) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "headingLevel": {
+          "type": "AccordionHeadingLevel | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The level each section's heading renders at. Must fit the surrounding\ndocument — a panel inside an `h2` section wants `3`."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
+    "AccordionItem": {
+      "name": "AccordionItem",
+      "source": "src/components/Accordion.tsx",
+      "propsType": "AccordionItemProps",
+      "import": "import { AccordionItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One collapsible section: an always-visible title that toggles a region beneath it.",
+      "useWhen": [
+        "inside an Accordion, once per section"
+      ],
+      "slots": {
+        "title": {
+          "accepts": "text",
+          "note": "always visible, so it must say what is inside — \"Advanced\" tells the user nothing about whether to open it"
+        },
+        "children": {
+          "accepts": "any content"
+        }
+      },
+      "a11y": {
+        "requires": [
+          "a stable `id`, which is the section's identity in the open set — an index breaks the moment the list reorders"
+        ],
+        "notes": [
+          "the trigger carries aria-expanded and aria-controls; the panel is a region labelled by the trigger",
+          "the panel keeps its DOM when collapsed, so a half-filled form inside one does not lose its answers"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a required form field inside a collapsed section",
+          "do": "keep required fields outside, or expand the section when validation fails",
+          "why": "a user cannot fix an error they cannot see, and the browser cannot focus a hidden invalid field"
+        }
+      ],
+      "stylesheet": "src/styles/accordion.css",
+      "tokens": [
+        "--border-focus",
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--icon-size-md",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-4",
+        "--text-default",
+        "--text-disabled",
+        "--text-primary",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height"
+      ],
+      "props": {
+        "id": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "Stable identity for the open set. Required."
+        },
+        "title": {
+          "type": "React.ReactNode",
+          "required": true,
+          "origin": "own",
+          "description": "The always-visible label."
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 275,
+        "other": 0
+      }
+    },
     "AgentActivity": {
       "name": "AgentActivity",
       "source": "src/components/AgentActivity.tsx",
@@ -1751,127 +1964,292 @@
         "other": 0
       }
     },
-    "Button": {
-      "name": "Button",
-      "source": "src/components/Button.tsx",
-      "propsType": "ButtonProps",
-      "import": "import { Button } from 'ionbase-ui';",
+    "Breadcrumb": {
+      "name": "Breadcrumb",
+      "source": "src/components/Breadcrumb.tsx",
+      "propsType": "BreadcrumbProps",
+      "description": "Breadcrumb — where this page sits, and how to get back up.\n\nWHY AN ORDERED LIST INSIDE A NAMED LANDMARK\n\nThe trail is a sequence, and `ol` is what says so: a screen reader announces\n\"list, 4 items\" and the position within it, which is the entire content of a\nbreadcrumb. A row of `div`s with slashes conveys none of that, and the\nslashes themselves get read out as punctuation.\n\nThe separator here is drawn by CSS `::before` on each item after the first,\nso it is decoration that never enters the accessibility tree. Putting a \"/\"\nin the markup is the usual version of this component and the usual defect.\n\nTHE LAST CRUMB IS NOT A LINK\n\n`isCurrent` renders text with `aria-current=\"page\"`. A link to the page you\nare already on is a dead control: it announces as a link, invites a click,\nand does nothing. This is the most common breadcrumb bug and the reason the\nprop exists rather than being inferred from position — a trail whose last\ncrumb IS a link to somewhere else is legitimate, and inferring would break it.",
+      "import": "import { Breadcrumb } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Triggers an action in place. Never navigates.",
+      "summary": "Where this page sits in the hierarchy, and how to get back up. An ordered list inside a named landmark.",
       "useWhen": [
-        "the interaction performs an action — submit, save, delete, open a dialog",
-        "the result stays on the current page"
+        "a page sits more than one level deep and the parent is not otherwise reachable",
+        "a record view needs its collection one click away",
+        "the hierarchy itself is information the user needs — which project, which environment"
       ],
       "useInstead": [
         {
-          "when": "it navigates to a URL or changes route",
-          "use": "Link",
-          "why": "Link renders an <a>. Middle-click, cmd-click, copy-link-address and 'open in new tab' all work on an anchor and none of them work on a button."
+          "when": "the destinations are siblings rather than ancestors",
+          "use": "Tabs",
+          "why": "a breadcrumb describes depth; tabs describe alternatives at the same depth"
         },
         {
-          "when": "it toggles a persistent boolean setting",
-          "use": "Toggle",
-          "why": "a toggle announces its on/off state; a button announces only its name"
+          "when": "the trail is the primary navigation for the whole app",
+          "use": "NavItem inside the app shell",
+          "why": "a breadcrumb supplements navigation, it does not replace it — it appears after a user has already gone somewhere"
         }
       ],
-      "variants": {
-        "variant": {
-          "primary-brand": {
-            "use": "the single most important action in a view",
-            "limit": "one per view or dialog"
-          },
-          "primary-neutral": {
-            "use": "a primary action that should not carry brand colour"
-          },
-          "primary-soft": {
-            "use": "a primary action on a dense or already-colourful surface"
-          },
-          "secondary": {
-            "use": "supporting actions shown alongside a primary one"
-          },
-          "tertiary": {
-            "use": "low-emphasis actions — Cancel, Back, inline row actions"
-          },
-          "destructive": {
-            "use": "irreversible actions",
-            "requires": "a Modal confirmation before the action runs"
-          },
-          "success": {
-            "use": "confirms the end of a flow. Rarely the right answer — prefer primary-brand."
-          }
-        },
-        "size": {
-          "sm": {
-            "use": "table rows, toolbars, dense layouts"
-          },
-          "md": {
-            "use": "the default; forms and page-level actions"
-          },
-          "lg": {
-            "use": "prominent standalone actions"
-          },
-          "xl": {
-            "use": "marketing and empty-state calls to action"
-          }
-        }
-      },
       "slots": {
-        "startIcon": {
-          "accepts": "Icon",
-          "note": "omit Icon's `label` — the Button's own text already names it, and a labelled icon is announced twice"
-        },
-        "endIcon": {
-          "accepts": "Icon",
-          "note": "same as startIcon"
+        "children": {
+          "accepts": "BreadcrumbItem",
+          "note": "ancestor first, current page last. Anything else and the trail reads backwards"
         }
       },
       "a11y": {
-        "role": "button",
-        "guarantees": [
-          "the focus ring appears for keyboard focus and not for a mouse click",
-          "hover does not latch on touch devices"
-        ],
         "requires": [
-          "an accessible name — `children`, or `aria-label` when the button is icon-only"
+          "`label` when a page has more than one nav landmark — it defaults to \"Breadcrumb\", which is what screen-reader users listen for"
+        ],
+        "notes": [
+          "the separator is drawn by CSS ::before and never enters the accessibility tree; a \"/\" in the markup is announced as punctuation between every crumb",
+          "the list is an `ol`, so the position and length are announced — which is the entire content of a breadcrumb"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "<Button onPress={() => router.push('/settings')}>Settings</Button>",
-          "do": "<Link href=\"/settings\">Settings</Link>",
-          "why": "a button that navigates breaks middle-click, cmd-click and copy-link, and is announced as a button rather than a link"
-        },
-        {
-          "dont": "two variant=\"primary-brand\" buttons in the same dialog",
-          "do": "one primary-brand, the rest secondary or tertiary",
-          "why": "two primaries is the same as none — nothing indicates the expected action"
-        },
-        {
-          "dont": "<Button variant=\"destructive\" onPress={deleteAccount}>",
-          "do": "open a Modal first and put the destructive Button in its footer",
-          "why": "irreversible actions need a confirmation step"
-        },
-        {
-          "dont": "<Button><Icon as={Trash} /></Button>",
-          "do": "<Button aria-label=\"Delete\"><Icon as={Trash} /></Button>",
-          "why": "an icon-only button with no aria-label is announced as just 'button'"
+          "dont": "<div>Home / Projects / Invoice 12</div>",
+          "do": "<Breadcrumb><BreadcrumbItem href=\"/\">Home</BreadcrumbItem>…</Breadcrumb>",
+          "why": "a row of divs conveys neither sequence nor position, and the slashes are read aloud"
         },
         {
-          "dont": "<Button onClick={...}>",
-          "do": "<Button onPress={...}>",
-          "why": "onPress is React Aria's unified pointer/keyboard/touch handler. onClick works but skips the touch and keyboard normalisation the rest of the system relies on."
-        }
-      ],
-      "deprecated": [
-        {
-          "prop": "disabled",
-          "replacement": "isDisabled",
-          "note": "still type-checks, so this will not fail loudly"
+          "dont": "a full trail on a top-level page",
+          "do": "omit it",
+          "why": "a breadcrumb with one crumb is furniture — it takes vertical space to say nothing"
         }
       ],
-      "stylesheet": "src/styles/button.css",
+      "stylesheet": "src/styles/breadcrumb.css",
       "tokens": [
-        "--border-disabled",
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--radius-xs",
+        "--spacing-8",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Names the landmark. A page with more than one `nav` needs them told apart,\nand \"Breadcrumb\" is what screen-reader users are listening for."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "`BreadcrumbItem` elements, ancestor first."
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "BreadcrumbItem": {
+      "name": "BreadcrumbItem",
+      "source": "src/components/Breadcrumb.tsx",
+      "propsType": "BreadcrumbItemProps",
+      "import": "import { BreadcrumbItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One crumb. A link to an ancestor, or the current page rendered as text.",
+      "useWhen": [
+        "inside a Breadcrumb, once per level"
+      ],
+      "useInstead": [
+        {
+          "when": "outside a breadcrumb trail",
+          "use": "Link",
+          "why": "the crumb's density, colour and truncation are tuned for a trail and look wrong on their own"
+        }
+      ],
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the name of the level, not its path"
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`isCurrent` on the last crumb, which renders it as text with aria-current=\"page\" rather than as a link"
+        ],
+        "notes": [
+          "isCurrent is a prop rather than inferred from position: a trail whose last crumb legitimately links elsewhere exists, and inferring would break it"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "<BreadcrumbItem href=\"/invoices/12\">Invoice 12</BreadcrumbItem> for the page you are on",
+          "do": "<BreadcrumbItem isCurrent>Invoice 12</BreadcrumbItem>",
+          "why": "a link to the current page is a dead control — it announces as a link, invites a click and does nothing"
+        }
+      ],
+      "stylesheet": "src/styles/breadcrumb.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--radius-xs",
+        "--spacing-8",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "href": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Omit on the current page — the last crumb is not a link."
+        },
+        "isCurrent": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The page the user is on. Marked `aria-current=\"page\"` and rendered as text\nrather than a link."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "Button": {
+      "name": "Button",
+      "source": "src/components/Button.tsx",
+      "propsType": "ButtonProps",
+      "import": "import { Button } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Triggers an action in place. Never navigates.",
+      "useWhen": [
+        "the interaction performs an action — submit, save, delete, open a dialog",
+        "the result stays on the current page"
+      ],
+      "useInstead": [
+        {
+          "when": "it navigates to a URL or changes route",
+          "use": "Link",
+          "why": "Link renders an <a>. Middle-click, cmd-click, copy-link-address and 'open in new tab' all work on an anchor and none of them work on a button."
+        },
+        {
+          "when": "it toggles a persistent boolean setting",
+          "use": "Toggle",
+          "why": "a toggle announces its on/off state; a button announces only its name"
+        }
+      ],
+      "variants": {
+        "variant": {
+          "primary-brand": {
+            "use": "the single most important action in a view",
+            "limit": "one per view or dialog"
+          },
+          "primary-neutral": {
+            "use": "a primary action that should not carry brand colour"
+          },
+          "primary-soft": {
+            "use": "a primary action on a dense or already-colourful surface"
+          },
+          "secondary": {
+            "use": "supporting actions shown alongside a primary one"
+          },
+          "tertiary": {
+            "use": "low-emphasis actions — Cancel, Back, inline row actions"
+          },
+          "destructive": {
+            "use": "irreversible actions",
+            "requires": "a Modal confirmation before the action runs"
+          },
+          "success": {
+            "use": "confirms the end of a flow. Rarely the right answer — prefer primary-brand."
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "table rows, toolbars, dense layouts"
+          },
+          "md": {
+            "use": "the default; forms and page-level actions"
+          },
+          "lg": {
+            "use": "prominent standalone actions"
+          },
+          "xl": {
+            "use": "marketing and empty-state calls to action"
+          }
+        }
+      },
+      "slots": {
+        "startIcon": {
+          "accepts": "Icon",
+          "note": "omit Icon's `label` — the Button's own text already names it, and a labelled icon is announced twice"
+        },
+        "endIcon": {
+          "accepts": "Icon",
+          "note": "same as startIcon"
+        }
+      },
+      "a11y": {
+        "role": "button",
+        "guarantees": [
+          "the focus ring appears for keyboard focus and not for a mouse click",
+          "hover does not latch on touch devices"
+        ],
+        "requires": [
+          "an accessible name — `children`, or `aria-label` when the button is icon-only"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "<Button onPress={() => router.push('/settings')}>Settings</Button>",
+          "do": "<Link href=\"/settings\">Settings</Link>",
+          "why": "a button that navigates breaks middle-click, cmd-click and copy-link, and is announced as a button rather than a link"
+        },
+        {
+          "dont": "two variant=\"primary-brand\" buttons in the same dialog",
+          "do": "one primary-brand, the rest secondary or tertiary",
+          "why": "two primaries is the same as none — nothing indicates the expected action"
+        },
+        {
+          "dont": "<Button variant=\"destructive\" onPress={deleteAccount}>",
+          "do": "open a Modal first and put the destructive Button in its footer",
+          "why": "irreversible actions need a confirmation step"
+        },
+        {
+          "dont": "<Button><Icon as={Trash} /></Button>",
+          "do": "<Button aria-label=\"Delete\"><Icon as={Trash} /></Button>",
+          "why": "an icon-only button with no aria-label is announced as just 'button'"
+        },
+        {
+          "dont": "<Button onClick={...}>",
+          "do": "<Button onPress={...}>",
+          "why": "onPress is React Aria's unified pointer/keyboard/touch handler. onClick works but skips the touch and keyboard normalisation the rest of the system relies on."
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled",
+          "note": "still type-checks, so this will not fail loudly"
+        }
+      ],
+      "stylesheet": "src/styles/button.css",
+      "tokens": [
+        "--border-disabled",
         "--border-error-strong",
         "--border-inverse",
         "--border-primary",
@@ -2354,6 +2732,11 @@
         {
           "dont": "a div with `role=\"checkbox\"`",
           "why": "form association, the indeterminate property and label clicking are not free to reimplement"
+        },
+        {
+          "dont": "<Checkbox isSelected={on} onChange={(isSelected) => setOn(isSelected)} />",
+          "do": "<Checkbox isSelected={on} onSelectionChange={setOn} />",
+          "why": "both selection shapes work, but they pair: `isSelected` goes with `onSelectionChange`, which receives the boolean, and `checked` goes with `onChange`, which receives the change event. Passing the Aria selection prop with the DOM handler name is the one combination that does not type — `onChange` is still the event handler. There is no `CheckboxChange` type; a generated eval invented one."
         }
       ],
       "deprecated": [
@@ -2460,10 +2843,22 @@
           "required": false,
           "origin": "own",
           "description": "Figma's `Show Label` + `Label`. Omit for a bare box."
+        },
+        "isSelected": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "React Aria's name for `checked`. Wins when both are passed."
+        },
+        "onSelectionChange": {
+          "type": "((isSelected: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Receives the new selection state rather than the change event."
         }
       },
       "propCounts": {
-        "own": 6,
+        "own": 8,
         "aria": 0,
         "dom": 304,
         "other": 0
@@ -2752,40 +3147,305 @@
         "other": 0
       }
     },
-    "ConfidenceIndicator": {
-      "name": "ConfidenceIndicator",
-      "source": "src/components/ConfidenceIndicator.tsx",
-      "propsType": "ConfidenceIndicatorProps",
-      "description": "ConfidenceIndicator — how much to trust the thing next to it.\n\nTHERE IS NO PERCENTAGE PROP, AND THERE WILL NOT BE ONE\n\n\"87% confident\" reads as a measurement. Almost nowhere is it one: it is\nusually a softmax score, a heuristic, or a number a model produced about\nitself — none of which are calibrated probabilities, and all of which invite\na reader to treat two digits of precision as real. Three levels cannot\noverclaim in that way.\n\n`basis` IS REQUIRED FOR THE SAME REASON. A level with nothing behind it is\ndecoration that changes behaviour: people act on \"high confidence\" whether or\nnot anything justifies it. Making the justification a required prop is the\nonly enforcement available here, and it is a type error rather than a policy\n— which is the strongest kind this system can offer.\n\nIt renders as text plus a three-bar meter, never the meter alone. The bars\ndiffer in filled COUNT, not only in colour, so the reading survives greyscale\nand forced-colours mode.",
-      "import": "import { ConfidenceIndicator } from 'ionbase-ui';",
+    "Combobox": {
+      "name": "Combobox",
+      "source": "src/components/Combobox.tsx",
+      "propsType": "ComboboxProps",
+      "description": "Combobox — a text field that filters a list, with one selected value.\n\nDrawn in Figma as `Combobox` (1370:2359) — three sizes by seven states, the\nsame axes `Input` carries, because the field IS Input's box. The open list is\na second Figma component, `Combobox Menu`, with no React export behind it.\n\nWHY THIS IS NOT `Select` WITH A SEARCH BOX\n\n`Select` wraps a native `<select>`, whose list the browser owns: it cannot be\nfiltered, and its rows can only hold text. Everything above about twenty\noptions needs filtering, and `Select`'s own contract has pointed at \"a\ncombobox — not yet in this system\" since it was written. This is it.\n\nThe cost is that everything the native control gave away for free — keyboard\nhandling, the mobile picker, screen-reader semantics — now has to be built.\nReact Aria's `useComboBox` builds it: `role=\"combobox\"` with `aria-expanded`,\n`aria-controls` and `aria-activedescendant`, arrow keys that move a virtual\nfocus while the real focus stays in the input, and Escape that reverts.\n\nFILTERING IS LOCALE-AWARE, NOT `toLowerCase().includes()`\n\n`useFilter({ sensitivity: 'base' })` is `Intl.Collator` underneath, so\n\"resume\" matches \"résumé\" and Turkish dotted/dotless I behave the way a\nTurkish reader expects. The lowercase-and-includes version fails both, and\nfails them silently in exactly the locales least likely to be tested.",
+      "import": "import { Combobox } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
+      "summary": "A text field that filters a list of options down to one selected value.",
       "useWhen": [
-        "a generated answer varies in reliability and the reader should weigh it",
-        "you can say what the confidence rests on"
+        "the list is long enough that scanning it is worse than typing",
+        "the user picks exactly one value from a known set",
+        "the options carry a second line of context the native <select> cannot render"
       ],
       "useInstead": [
         {
-          "when": "the answer is wrong or missing rather than uncertain",
-          "use": "Alert"
+          "when": "the list is short and fully scannable",
+          "use": "Select",
+          "why": "the native control brings keyboard handling and the mobile platform picker for free; this rebuilds all of it"
         },
         {
-          "when": "you want to show where the claim came from",
-          "use": "Citation",
-          "why": "a source is stronger than a confidence level, and often what the reader actually wanted"
+          "when": "there are two or three mutually exclusive choices worth showing at once",
+          "use": "RadioGroup"
         },
         {
-          "when": "it is a status rather than a reliability",
-          "use": "Badge"
+          "when": "the value is free text and the list is only a convenience",
+          "use": "Input",
+          "why": "or set `allowsCustomValue`, which is the same decision made explicitly"
+        },
+        {
+          "when": "the rows are commands rather than values",
+          "use": "Menu",
+          "why": "options are selected and stay selected; menu items are invoked and the menu closes"
         }
       ],
       "variants": {
-        "level": {
-          "low": {
-            "use": "thin or conflicting evidence. One bar, warning colour"
-          },
-          "medium": {
-            "use": "reasonable support with real gaps. Two bars"
+        "size": {
+          "sm": {
+            "use": "dense forms, table filters"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "prominent single-field forms"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "role=combobox with aria-expanded, aria-controls and aria-activedescendant, from react-aria's useComboBox",
+          "real focus never leaves the input; arrow keys move a virtual focus through the list, which is what keeps typing and browsing possible at once",
+          "the popover is non-modal, so the page behind stays readable and focus stays in the field",
+          "Escape reverts to the last committed value rather than clearing the field",
+          "filtering is Intl.Collator-based, so accents and locale-specific casing behave correctly",
+          "the empty message is a sibling of the listbox, not an option in it, so it is never counted, focused or selectable",
+          "the menu matches the field's width, clamped to the space right of it so a full-bleed field cannot push the menu past the viewport edge"
+        ],
+        "requires": [
+          "`label`, or an `aria-label` when no visible label is rendered",
+          "`emptyLabel` wording that says why nothing is listed, if the default is too terse"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "giving the disclosure button a tab stop",
+          "why": "the input already opens the list with ArrowDown. A second tab stop doubles the cost of tabbing past every combobox in a form and adds nothing"
+        },
+        {
+          "dont": "styling the focused option with :hover or :focus",
+          "why": "no option is ever either — focus is virtual. Use [data-focused], which react-aria sets for both pointer and keyboard"
+        },
+        {
+          "dont": "posting the input's text in a form",
+          "why": "the text is the label and the value is the key; pass `name` and the component posts the key in a hidden input"
+        },
+        {
+          "dont": "filtering with toLowerCase().includes()",
+          "why": "it fails on accents and on Turkish dotted/dotless I, silently, in the locales least likely to be tested"
+        },
+        {
+          "dont": "writing a width onto the menu from a ResizeObserver or any effect that runs while it is open",
+          "why": "a positioned popover that changes size feeds back into react-aria's positioning, and any scrollbar that results is read by useCloseOnScroll as a real scroll. The menu opens and closes within about a hundred milliseconds, which presents as a keyboard bug rather than a layout one"
+        }
+      ],
+      "slots": {
+        "emptyLabel": {
+          "expects": "what to show when the filter matches nothing"
+        }
+      },
+      "stylesheet": "src/styles/combobox.css",
+      "tokens": [
+        "--border-subtle",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-input-icon-size",
+        "--ion-shadow-shadow-lg",
+        "--radius-md",
+        "--radius-sm",
+        "--spacing-12",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-hover",
+        "--surface-primary-subtle",
+        "--surface-raised",
+        "--text-default",
+        "--text-disabled",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "options": {
+          "type": "readonly ComboboxOption[]",
+          "required": true,
+          "origin": "own",
+          "description": "The full option list. Filtering happens here, against what is typed."
+        },
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Field label. Required for a usable control — see `a11y.requires`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Helper text below the field."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Replaces the helper text when `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isReadOnly": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "size": {
+          "type": "ComboboxSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "placeholder": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "selectedKey": {
+          "type": "string | null | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Controlled selection. `null` means nothing is selected."
+        },
+        "defaultSelectedKey": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onSelectionChange": {
+          "type": "((key: string | null) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "inputValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Controlled text. Usually only needed for async/remote filtering."
+        },
+        "defaultInputValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onInputChange": {
+          "type": "((value: string) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "allowsCustomValue": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accept text that matches no option. Off by default: a combobox whose value\nis a free string is a text field with suggestions, and the caller should\nhave to say that is what they want."
+        },
+        "menuTrigger": {
+          "type": "\"focus\" | \"input\" | \"manual\" | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "What opens the list. `input` — react-aria's default and this one — opens it\non the first keystroke; the chevron opens it on demand. `focus` opens it\nthe moment the field is tabbed into, which is loud in a long form.",
+          "values": [
+            "focus",
+            "input",
+            "manual"
+          ]
+        },
+        "emptyLabel": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in place of the list when nothing matches."
+        },
+        "buttonLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible label for the disclosure button."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Posts the selected value under this name, for an uncontrolled form."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 23,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "ConfidenceIndicator": {
+      "name": "ConfidenceIndicator",
+      "source": "src/components/ConfidenceIndicator.tsx",
+      "propsType": "ConfidenceIndicatorProps",
+      "description": "ConfidenceIndicator — how much to trust the thing next to it.\n\nTHERE IS NO PERCENTAGE PROP, AND THERE WILL NOT BE ONE\n\n\"87% confident\" reads as a measurement. Almost nowhere is it one: it is\nusually a softmax score, a heuristic, or a number a model produced about\nitself — none of which are calibrated probabilities, and all of which invite\na reader to treat two digits of precision as real. Three levels cannot\noverclaim in that way.\n\n`basis` IS REQUIRED FOR THE SAME REASON. A level with nothing behind it is\ndecoration that changes behaviour: people act on \"high confidence\" whether or\nnot anything justifies it. Making the justification a required prop is the\nonly enforcement available here, and it is a type error rather than a policy\n— which is the strongest kind this system can offer.\n\nIt renders as text plus a three-bar meter, never the meter alone. The bars\ndiffer in filled COUNT, not only in colour, so the reading survives greyscale\nand forced-colours mode.",
+      "import": "import { ConfidenceIndicator } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
+      "useWhen": [
+        "a generated answer varies in reliability and the reader should weigh it",
+        "you can say what the confidence rests on"
+      ],
+      "useInstead": [
+        {
+          "when": "the answer is wrong or missing rather than uncertain",
+          "use": "Alert"
+        },
+        {
+          "when": "you want to show where the claim came from",
+          "use": "Citation",
+          "why": "a source is stronger than a confidence level, and often what the reader actually wanted"
+        },
+        {
+          "when": "it is a status rather than a reliability",
+          "use": "Badge"
+        }
+      ],
+      "variants": {
+        "level": {
+          "low": {
+            "use": "thin or conflicting evidence. One bar, warning colour"
+          },
+          "medium": {
+            "use": "reasonable support with real gaps. Two bars"
           },
           "high": {
             "use": "corroborated, and you can say by what. Three bars"
@@ -2936,41 +3596,275 @@
         "other": 0
       }
     },
-    "EmptyState": {
-      "name": "EmptyState",
-      "source": "src/components/EmptyState.tsx",
-      "propsType": "EmptyStateProps",
-      "description": "EmptyState — the state five of this system's nine patterns require and none\nof them could render.\n\n`DataTable`, `PageShell`, `SettingsPanel`, `AssistantAnswer` and\n`HumanApproval` all specify an empty state in their recipe. Until this\nexisted each consumer invented one, which is how a design system ends up\nwith four different ways to say \"nothing here\".\n\nREASON IS REQUIRED, AND HAS NO DEFAULT\n\nThe four reasons are genuinely different situations with different correct\nactions, and the failure mode is silent: an app that shows \"No invoices yet\n— Create your first invoice\" to a user whose filter excluded everything has\ntold them their records are gone. A default would make that the easy path,\nso there isn't one.\n\n`no-results` and `error` deliberately do NOT offer a create action in the\ncontract's guidance. The first needs the filter cleared; the second needs a\nretry, and offering \"Create\" over a failed fetch invites a duplicate.\n\nNOT A LIVE REGION\n\nAn empty state replaces content, so it is what the user reads next rather\nthan something announced over what they are reading. `role=\"status\"` here\nwould interrupt on every keystroke of a filter box. If a specific flow needs\nthe announcement, the caller owns that decision — the same reasoning\nStreamingText applies to `aria-live`.\n\n`error` is rendered as `role=\"alert\"` ONLY when the caller opts in via\n`role`, for the same reason: an error empty state arriving during typing is\nstill a read, not an interruption.\n\nNo `'use client'`: nothing here holds state. The buttons passed through\n`action` carry their own boundary.",
-      "import": "import { EmptyState } from 'ionbase-ui';",
+    "Drawer": {
+      "name": "Drawer",
+      "source": "src/components/Drawer.tsx",
+      "propsType": "DrawerProps",
+      "description": "Drawer — a modal panel anchored to an edge.\n\nWHY IT IS A MODAL AND NOT A SIDEBAR\n\nIt takes focus, traps it, closes on Escape and on an outside click, and marks\nthe rest of the page inert — all of `Modal`'s behaviour, differing only in\nwhere the panel sits and how it enters. A persistent side panel that does not\ndo those things is layout, not a drawer, and belongs in the page rather than\nin an overlay.\n\nWHEN TO REACH FOR MODAL INSTEAD\n\nA drawer suits work that is long or list-shaped — filters, a record's detail,\na sequence of settings — because an edge panel can be tall without becoming a\nsquare that fights the viewport. A decision, especially a destructive one,\nbelongs in a Modal: it is centred, it is smaller, and it does not invite\nscrolling past the thing being confirmed.\n\nRENDERS NOTHING WHEN CLOSED, and portals when open, for the reasons recorded\non Modal: a closed overlay left in the tree is still keyboard-focusable, and\nan inline one inherits whatever `overflow` and stacking context surrounds it.",
+      "import": "import { Drawer } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "The state a region shows when it has nothing to show, and why — first run, no results, no access, or a failed fetch.",
+      "summary": "A modal panel anchored to an edge. Modal behaviour — focus trap, Escape, scrim — with the shape of a side panel.",
       "useWhen": [
-        "a list, table, panel or route has no content to render",
-        "a filter or search returns nothing",
-        "the account is not permitted to see what would be here",
-        "the request that would have filled the region failed"
+        "work that is long or list-shaped: filters, a record's detail, a run of settings",
+        "the page behind should stay visible as context while a task is done beside it",
+        "a form long enough that a centred dialog would scroll its own actions off screen"
       ],
       "useInstead": [
         {
-          "when": "content exists and something went wrong beside it",
-          "use": "Alert",
-          "why": "an Alert sits with the content; an EmptyState replaces it. If there is a table on screen, the message about it is an Alert"
+          "when": "the user is making a decision, especially a destructive one",
+          "use": "Modal",
+          "why": "a modal is centred and small enough that the thing being confirmed cannot be scrolled past"
         },
         {
-          "when": "the message is transient and the content is unaffected",
-          "use": "Toast"
+          "when": "the panel should stay open while the user works elsewhere",
+          "use": "page layout",
+          "why": "a drawer traps focus and marks the rest of the page inert. A panel that does not do those things is layout, not an overlay"
+        },
+        {
+          "when": "the content is a short menu of actions",
+          "use": "Popover or Menu"
         }
       ],
+      "variants": {
+        "placement": {
+          "start": {
+            "use": "navigation and hierarchy, which readers expect at the leading edge"
+          },
+          "end": {
+            "use": "the default — detail and editing beside the record that opened it"
+          },
+          "top": {
+            "use": "rare: a global search or command surface"
+          },
+          "bottom": {
+            "use": "touch-first layouts, where the bottom edge is the reachable one"
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "a short form or a filter list"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "a record detail with its own sections"
+          }
+        }
+      },
       "slots": {
         "title": {
           "accepts": "text",
-          "note": "required — it is the region's statement. Name the thing and the situation: \"No invoices match these filters\", not \"No results\""
+          "note": "required — it is the dialog's accessible name"
         },
         "description": {
-          "accepts": "text",
-          "note": "one or two sentences: what would be here, and what puts it here"
+          "accepts": "text"
         },
-        "action": {
+        "children": {
+          "accepts": "any content",
+          "note": "the only scrolling region"
+        },
+        "footer": {
+          "accepts": "Button",
+          "note": "pinned to the bottom edge, so actions stay reachable in a long panel"
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`title`, which becomes the dialog's accessible name via aria-labelledby"
+        ],
+        "notes": [
+          "start and end follow writing direction, so a right-hand drawer in English is a left-hand one in Arabic with no second variant",
+          "renders nothing when closed and portals when open: a closed overlay left in the tree is still keyboard-focusable",
+          "only the body scrolls, so the title stays on screen — the one piece of context a user needs while working down a long list"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Drawer that stays open while the user edits the page behind it",
+          "do": "a layout panel",
+          "why": "it traps focus and marks the rest inert; a keyboard user cannot reach the page behind it"
+        },
+        {
+          "dont": "<Drawer> for a delete confirmation",
+          "do": "<Modal>",
+          "why": "an edge panel is tall, so the confirm button can sit below the fold — the one control that must never be missed"
+        }
+      ],
+      "stylesheet": "src/styles/drawer.css",
+      "tokens": [
+        "--border-focus",
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-semibold",
+        "--icon-secondary",
+        "--icon-size-md",
+        "--ion-drawer-size",
+        "--radius-lg",
+        "--radius-sm",
+        "--spacing-12",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-hover",
+        "--surface-raised",
+        "--surface-scrim",
+        "--text-default",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-h5",
+        "--type-h5-line-height"
+      ],
+      "props": {
+        "isOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether the drawer is shown."
+        },
+        "onOpenChange": {
+          "type": "((isOpen: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Called with the next open state — `false` when the drawer asks to close."
+        },
+        "placement": {
+          "type": "DrawerPlacement | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Which edge it enters from. `start` and `end` follow writing direction, so\na right-hand drawer in English is a left-hand one in Arabic without a\nsecond variant.",
+          "values": [
+            "start",
+            "end",
+            "top",
+            "bottom"
+          ],
+          "default": "end"
+        },
+        "size": {
+          "type": "DrawerSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "title": {
+          "type": "React.ReactNode",
+          "required": true,
+          "origin": "own",
+          "description": "Required: the dialog's accessible name, wired via `aria-labelledby`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Supporting copy under the title."
+        },
+        "footer": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Action row, pinned to the bottom edge."
+        },
+        "showClose": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "default": true
+        },
+        "closeLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "default": "Close drawer"
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isDismissable": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to close the modal when the user interacts outside it.",
+          "tags": {
+            "default": "false"
+          }
+        },
+        "isKeyboardDismissDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether pressing the escape key to close the modal should be disabled.",
+          "tags": {
+            "default": "false"
+          }
+        },
+        "shouldCloseOnInteractOutside": {
+          "type": "((element: Element) => boolean) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "When user interacts with the argument element outside of the overlay ref,\nreturn true if onClose should be called.  This gives you a chance to filter\nout interaction with elements that should not dismiss the overlay.\nBy default, onClose will always be called on interaction outside the overlay ref."
+        }
+      },
+      "propCounts": {
+        "own": 11,
+        "aria": 3,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "EmptyState": {
+      "name": "EmptyState",
+      "source": "src/components/EmptyState.tsx",
+      "propsType": "EmptyStateProps",
+      "description": "EmptyState — the state five of this system's nine patterns require and none\nof them could render.\n\n`DataTable`, `PageShell`, `SettingsPanel`, `AssistantAnswer` and\n`HumanApproval` all specify an empty state in their recipe. Until this\nexisted each consumer invented one, which is how a design system ends up\nwith four different ways to say \"nothing here\".\n\nREASON IS REQUIRED, AND HAS NO DEFAULT\n\nThe four reasons are genuinely different situations with different correct\nactions, and the failure mode is silent: an app that shows \"No invoices yet\n— Create your first invoice\" to a user whose filter excluded everything has\ntold them their records are gone. A default would make that the easy path,\nso there isn't one.\n\n`no-results` and `error` deliberately do NOT offer a create action in the\ncontract's guidance. The first needs the filter cleared; the second needs a\nretry, and offering \"Create\" over a failed fetch invites a duplicate.\n\nNOT A LIVE REGION\n\nAn empty state replaces content, so it is what the user reads next rather\nthan something announced over what they are reading. `role=\"status\"` here\nwould interrupt on every keystroke of a filter box. If a specific flow needs\nthe announcement, the caller owns that decision — the same reasoning\nStreamingText applies to `aria-live`.\n\n`error` is rendered as `role=\"alert\"` ONLY when the caller opts in via\n`role`, for the same reason: an error empty state arriving during typing is\nstill a read, not an interruption.\n\nNo `'use client'`: nothing here holds state. The buttons passed through\n`action` carry their own boundary.",
+      "import": "import { EmptyState } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The state a region shows when it has nothing to show, and why — first run, no results, no access, or a failed fetch.",
+      "useWhen": [
+        "a list, table, panel or route has no content to render",
+        "a filter or search returns nothing",
+        "the account is not permitted to see what would be here",
+        "the request that would have filled the region failed"
+      ],
+      "useInstead": [
+        {
+          "when": "content exists and something went wrong beside it",
+          "use": "Alert",
+          "why": "an Alert sits with the content; an EmptyState replaces it. If there is a table on screen, the message about it is an Alert"
+        },
+        {
+          "when": "the message is transient and the content is unaffected",
+          "use": "Toast"
+        }
+      ],
+      "slots": {
+        "title": {
+          "accepts": "text",
+          "note": "required — it is the region's statement. Name the thing and the situation: \"No invoices match these filters\", not \"No results\""
+        },
+        "description": {
+          "accepts": "text",
+          "note": "one or two sentences: what would be here, and what puts it here"
+        },
+        "action": {
           "accepts": "Button",
           "note": "the action that RESOLVES this reason — clearing a filter for no-results, not creating a record"
         },
@@ -3068,7 +3962,7 @@
       "stylesheet": "src/styles/empty-state.css",
       "tokens": [
         "--font-family-sans",
-        "--font-weight-medium",
+        "--font-weight-semibold",
         "--icon-error",
         "--icon-primary",
         "--icon-size-md",
@@ -3173,99 +4067,345 @@
         "other": 0
       }
     },
-    "FullCard": {
-      "name": "FullCard",
-      "source": "src/components/FullCard.tsx",
-      "propsType": "FullCardProps",
-      "description": "Full Card — the full-bleed case study row from Figma `Full Card` (592:857).\n\nA text column beside a framed media panel, split down the middle, mirrored\nby the `Alignment` variant.\n\nThe split holds from 1080 and stacks below it, media above content in BOTH\nalignments — `Alignment` names a horizontal side and\nstops meaning anything once there is one column, so it does not get to\ndecide the vertical order too. Size is a media query, not a prop, the same\ncall Header makes about Device.\n\nWHY THE `show*` BOOLEANS ARE GONE\n\nFigma carries `Show Eyebrow`, `Show Description` and `Show Actions` beside\nthe slots they gate, because a Figma component instance always holds every\nlayer and needs a switch to hide one. React has no such constraint — an\nabsent prop is the switch. Badge made the same call with `Show Dot`, and\nkeeping both would have let `showActions` and `actions` disagree.\n\n`headline` is required, and it is the only required prop. The heading is\nwhat makes this a section rather than a decorated div, and every other part\nof the card is optional in Figma too.\n\nNo `'use client'`: nothing here is stateful or interactive. The interactive\nparts arrive through `actions`, and they carry their own boundary.",
-      "import": "import { FullCard } from 'ionbase-ui';",
+    "FileUpload": {
+      "name": "FileUpload",
+      "source": "src/components/FileUpload.tsx",
+      "propsType": "FileUploadProps",
+      "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
+      "import": "import { FileUpload } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A full-bleed row: a text column beside a framed media panel, mirrored by `alignment`.",
+      "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
       "useWhen": [
-        "a marketing or overview section presents one thing with a screenshot beside it",
-        "a case-study or feature row on a landing or product page"
+        "the user attaches one or more files to a form or a message",
+        "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
       ],
       "useInstead": [
         {
-          "when": "you are listing records with comparable fields",
-          "use": "Table"
+          "when": "a single file is picked and no drop target or file list is wanted",
+          "use": "a plain <input type=\"file\">",
+          "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
         },
         {
-          "when": "it is a short status message rather than a content section",
-          "use": "Alert"
+          "when": "upload progress needs to be shown",
+          "use": "ProgressBar",
+          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
         }
       ],
-      "slots": {
-        "eyebrow": {
-          "accepts": "Badge",
-          "note": "any node works"
-        },
-        "headline": {
-          "accepts": "text",
-          "note": "required — the heading is what makes this a section rather than a decorated div"
-        },
-        "description": {
-          "accepts": "text"
-        },
-        "actions": {
-          "accepts": "Button",
-          "note": "a secondary Button in the design"
-        },
-        "media": {
-          "accepts": "img or video",
-          "note": "rendered inside the framed screen holder — pass the screenshot or embed itself, not the frame"
-        },
-        "children": {
-          "accepts": "any",
-          "note": "extra content below the description"
-        }
-      },
       "variants": {
-        "alignment": {
-          "left": {
-            "use": "media on the left, text on the right"
+        "size": {
+          "sm": {
+            "use": "inside a dense form, or beside other fields"
           },
-          "right": {
-            "use": "media on the right — the variant names the media, not the text"
+          "md": {
+            "use": "the default — a standalone attachment area"
           }
         }
       },
       "a11y": {
         "guarantees": [
-          "the headline renders as a real heading, so the card appears in the document outline"
+          "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
+          "the zone is a <label> for that input, so clicking anywhere opens the picker without any script",
+          "the input is clipped to 1px rather than display:none, which would remove it from the tab order and the accessibility tree",
+          "the focus ring is drawn on the zone, where the user is looking, not on the clipped input",
+          "a polite live region announces the number of files held, because a drop changes nothing near the user's focus",
+          "dragging is signalled by a solid border as well as a colour, so it is not conveyed by colour alone (WCAG 1.4.1)",
+          "each remove button is a 24px target with a name that includes the file (WCAG 2.5.8)"
         ],
         "requires": [
-          "`headingLevel` matching the surrounding outline — `h3` is the default because Figma applies Type/H3, but only the page knows the real level",
-          "`alt` on whatever you pass as `media`"
-        ],
-        "notes": [
-          "`h1` is deliberately not available: a full card is a section within a page, never the page's own title."
+          "`label`, or an `aria-label` — an unnamed file input announces only as \"button\"",
+          "`hint` describing the accepted types and size limit, since `accept` itself is never announced"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "looking for `showEyebrow` / `showDescription` / `showActions`",
-          "why": "an absent prop is the switch — Figma needs the boolean because an instance always holds every layer; React does not"
+          "dont": "treating `accept` or `maxSize` as validation",
+          "why": "both are client-side and advisory. A browser does not enforce `accept` on drop, and every platform picker offers an \"All files\" escape. The server must check again"
         },
         {
-          "dont": "leaving `headingLevel` at the default inside a section that is already at h3",
-          "why": "it produces a skipped or duplicated outline level"
+          "dont": "rebuilding this as a div with onClick={() => inputRef.current.click()}",
+          "why": "that version has no accessible name, no tab stop, no form participation and no keyboard path — it is the usual build of this component and the usual defect"
         },
         {
-          "dont": "passing your own frame or border around `media`",
-          "why": "the component already draws the screen holder"
+          "dont": "putting the file list inside the drop zone",
+          "why": "the zone is a label, so every row in it — including each remove button — would also open the file picker"
+        },
+        {
+          "dont": "using `onChange` as a delta",
+          "why": "it fires with the complete list after every add and every remove, never with what changed"
         }
       ],
-      "stylesheet": "src/styles/full-card.css",
+      "slots": {
+        "prompt": {
+          "expects": "the call to action inside the zone"
+        },
+        "hint": {
+          "expects": "the constraints in words — \"PNG or JPG, up to 5 MB\""
+        }
+      },
+      "stylesheet": "src/styles/file-upload.css",
       "tokens": [
         "--border-default",
+        "--border-disabled",
+        "--border-error",
+        "--border-focus",
+        "--border-strong",
         "--border-width-default",
+        "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-regular",
-        "--font-weight-semibold",
-        "--ion-full-card-gap",
-        "--ion-full-card-media-gutter",
-        "--ion-full-card-media-min-height",
+        "--font-weight-medium",
+        "--icon-default",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-sm",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-file-upload-gap",
+        "--ion-file-upload-icon-size",
+        "--ion-file-upload-padding",
+        "--radius-md",
+        "--radius-sm",
+        "--ring-focus",
+        "--spacing-12",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-hover",
+        "--surface-primary-subtle",
+        "--surface-subtle",
+        "--text-default",
+        "--text-disabled",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Field label. Also the accessible name of the file input."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Helper text below the control."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Replaces the helper text when `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "size": {
+          "type": "FileUploadSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant when drawn. Height of the drop target.",
+          "values": [
+            "sm",
+            "md"
+          ]
+        },
+        "accept": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Native `accept` — a comma-separated list of extensions or MIME types."
+        },
+        "multiple": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Allow more than one file."
+        },
+        "maxSize": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Reject anything larger, in bytes."
+        },
+        "maxFiles": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Reject once this many files are held. Only meaningful with `multiple`."
+        },
+        "files": {
+          "type": "readonly File[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The files held. Pass it to control the list; omit and the component keeps\nits own. A controlled list is the usual case, because the caller is the\nonly thing that knows which uploads have since succeeded or failed."
+        },
+        "onChange": {
+          "type": "((files: File[]) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Fires with the full list after every add or remove, never with a delta."
+        },
+        "onReject": {
+          "type": "((rejected: RejectedFile[]) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Fires with anything refused by `accept`, `maxSize` or `maxFiles`."
+        },
+        "prompt": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Call-to-action inside the drop target."
+        },
+        "hint": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Second line inside the drop target — the constraints, in words."
+        },
+        "removeLabel": {
+          "type": "((name: string) => string) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible label for each file's remove button. Receives the file name."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 20,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "FullCard": {
+      "name": "FullCard",
+      "source": "src/components/FullCard.tsx",
+      "propsType": "FullCardProps",
+      "description": "Full Card — the full-bleed case study row from Figma `Full Card` (592:857).\n\nA text column beside a framed media panel, split down the middle, mirrored\nby the `Alignment` variant.\n\nThe split holds from 1080 and stacks below it, media above content in BOTH\nalignments — `Alignment` names a horizontal side and\nstops meaning anything once there is one column, so it does not get to\ndecide the vertical order too. Size is a media query, not a prop, the same\ncall Header makes about Device.\n\nWHY THE `show*` BOOLEANS ARE GONE\n\nFigma carries `Show Eyebrow`, `Show Description` and `Show Actions` beside\nthe slots they gate, because a Figma component instance always holds every\nlayer and needs a switch to hide one. React has no such constraint — an\nabsent prop is the switch. Badge made the same call with `Show Dot`, and\nkeeping both would have let `showActions` and `actions` disagree.\n\n`headline` is required, and it is the only required prop. The heading is\nwhat makes this a section rather than a decorated div, and every other part\nof the card is optional in Figma too.\n\nNo `'use client'`: nothing here is stateful or interactive. The interactive\nparts arrive through `actions`, and they carry their own boundary.",
+      "import": "import { FullCard } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A full-bleed row: a text column beside a framed media panel, mirrored by `alignment`.",
+      "useWhen": [
+        "a marketing or overview section presents one thing with a screenshot beside it",
+        "a case-study or feature row on a landing or product page"
+      ],
+      "useInstead": [
+        {
+          "when": "you are listing records with comparable fields",
+          "use": "Table"
+        },
+        {
+          "when": "it is a short status message rather than a content section",
+          "use": "Alert"
+        }
+      ],
+      "slots": {
+        "eyebrow": {
+          "accepts": "Badge",
+          "note": "any node works"
+        },
+        "headline": {
+          "accepts": "text",
+          "note": "required — the heading is what makes this a section rather than a decorated div"
+        },
+        "description": {
+          "accepts": "text"
+        },
+        "actions": {
+          "accepts": "Button",
+          "note": "a secondary Button in the design"
+        },
+        "media": {
+          "accepts": "img or video",
+          "note": "rendered inside the framed screen holder — pass the screenshot or embed itself, not the frame"
+        },
+        "children": {
+          "accepts": "any",
+          "note": "extra content below the description"
+        }
+      },
+      "variants": {
+        "alignment": {
+          "left": {
+            "use": "media on the left, text on the right"
+          },
+          "right": {
+            "use": "media on the right — the variant names the media, not the text"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the headline renders as a real heading, so the card appears in the document outline"
+        ],
+        "requires": [
+          "`headingLevel` matching the surrounding outline — `h3` is the default because Figma applies Type/H3, but only the page knows the real level",
+          "`alt` on whatever you pass as `media`"
+        ],
+        "notes": [
+          "`h1` is deliberately not available: a full card is a section within a page, never the page's own title."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "looking for `showEyebrow` / `showDescription` / `showActions`",
+          "why": "an absent prop is the switch — Figma needs the boolean because an instance always holds every layer; React does not"
+        },
+        {
+          "dont": "leaving `headingLevel` at the default inside a section that is already at h3",
+          "why": "it produces a skipped or duplicated outline level"
+        },
+        {
+          "dont": "passing your own frame or border around `media`",
+          "why": "the component already draws the screen holder"
+        }
+      ],
+      "stylesheet": "src/styles/full-card.css",
+      "tokens": [
+        "--border-default",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--font-weight-semibold",
+        "--ion-full-card-gap",
+        "--ion-full-card-media-gutter",
+        "--ion-full-card-media-min-height",
         "--ion-full-card-media-width",
         "--ion-full-card-padding-x",
         "--ion-full-card-padding-y",
@@ -3684,7 +4824,6 @@
         "--border-strong",
         "--border-subtle",
         "--border-width-default",
-        "--border-width-thick",
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
@@ -5548,50 +6687,20 @@
           "origin": "own",
           "description": "Spread onto the dial-code `<button>`. This is how a country picker gets\nattached — see the note on scope below."
         },
-        "type": {
-          "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
-          "tags": {
-            "default": "'text'"
-          },
-          "default": "tel"
-        },
-        "disabled": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "own",
-          "tags": {
-            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-          }
-        },
-        "form": {
-          "type": "string | undefined",
+        "onChange": {
+          "type": "((value: string) => void) | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+          "description": "Handler that is called when the value changes."
         },
-        "name": {
+        "defaultValue": {
           "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+          "description": "The default value (uncontrolled)."
         },
-        "value": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The current value (controlled)."
-        },
-        "defaultValue": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The default value (uncontrolled)."
-        },
-        "autoCapitalize": {
-          "type": "\"none\" | \"off\" | \"on\" | \"sentences\" | \"words\" | \"characters\" | undefined",
+        "autoCapitalize": {
+          "type": "\"none\" | \"off\" | \"on\" | \"sentences\" | \"words\" | \"characters\" | undefined",
           "required": false,
           "origin": "own",
           "description": "Narrower than React's own typing, which also allows any `string`.\n`autoCapitalize` is declared on `AriaTextFieldOptions` rather than\n`AriaTextFieldProps`, so `keyof AriaTextFieldProps` above cannot omit it —\nand the wide DOM version does not satisfy what `useTextField` accepts.",
@@ -5773,12 +6882,6 @@
           "origin": "aria",
           "description": "Handler that is called when the element loses focus."
         },
-        "onChange": {
-          "type": "((value: string) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the value changes."
-        },
         "onBeforeInput": {
           "type": "FormEventHandler<HTMLInputElement> | undefined",
           "required": false,
@@ -5809,6 +6912,42 @@
           "origin": "aria",
           "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
         },
+        "type": {
+          "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+          "tags": {
+            "default": "'text'"
+          },
+          "default": "tel"
+        },
+        "disabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+          }
+        },
+        "form": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+        },
+        "value": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The current value (controlled)."
+        },
         "size": {
           "type": "InputSize | undefined",
           "required": false,
@@ -6115,10 +7254,10 @@
           "origin": "own",
           "description": "Matches the Figma `Placement` variant, and names where the POPOVER sits —\nnot where the arrow points. A preference, not a guarantee: it flips when\nthere is no room, and the arrow follows.",
           "values": [
-            "right",
-            "left",
             "top",
-            "bottom"
+            "bottom",
+            "right",
+            "left"
           ]
         },
         "size": {
@@ -6172,6 +7311,172 @@
         "other": 0
       }
     },
+    "ProgressBar": {
+      "name": "ProgressBar",
+      "source": "src/components/ProgressBar.tsx",
+      "propsType": "ProgressBarProps",
+      "description": "ProgressBar — a determinate or indeterminate measure of work.\n\nDETERMINATE AND INDETERMINATE ARE THE SAME COMPONENT ON PURPOSE\n\nWork that starts unmeasurable and becomes measurable is the common case — a\nupload that does not know its size until the first chunk lands. Splitting\nthem into two components would make that transition a swap, which remounts\nthe node and loses the live region with it.\n\nOmitting `value` is what makes it indeterminate. `aria-valuenow` is then\nomitted too, which is exactly what the ARIA spec asks for and is the detail\nhand-rolled progress bars get wrong most often — a bar reporting\n`aria-valuenow=\"0\"` forever tells a screen reader the work is stuck at zero,\nnot that it is unmeasured.\n\nWHY `label` IS REQUIRED\n\n`role=\"progressbar\"` announces a number. Without a name the user hears \"42\npercent\" with no indication of what is at 42 percent, which is worse than\nsilence because it sounds like information.",
+      "import": "import { ProgressBar } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A determinate or indeterminate measure of work, with the name of the work attached. Omitting `value` is what makes it indeterminate.",
+      "useWhen": [
+        "work reports a fraction complete — an upload, an import, a multi-step job",
+        "work will become measurable but is not yet, and the bar should not remount when it does",
+        "a quota or usage figure is better read as a bar than a number"
+      ],
+      "useInstead": [
+        {
+          "when": "the wait is short and unmeasurable",
+          "use": "Spinner",
+          "why": "an indeterminate bar occupies a block of layout to say what a spinner says inline"
+        },
+        {
+          "when": "the region is being replaced by content",
+          "use": "Skeleton"
+        }
+      ],
+      "variants": {
+        "intent": {
+          "primary": {
+            "use": "the default — work proceeding normally"
+          },
+          "success": {
+            "use": "work that finished, where the bar stays on screen as a record"
+          },
+          "warning": {
+            "use": "a quota approaching its limit",
+            "note": "warning describes the VALUE, not a failure of the bar"
+          },
+          "error": {
+            "use": "a quota exceeded, or a job that failed part-way",
+            "note": "the bar is still reporting correctly — reserve this for the measured thing being bad"
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "inside a row or a dense table cell"
+          },
+          "md": {
+            "use": "the default"
+          }
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`label` — it is required, because role=\"progressbar\" announces a number and a number with no noun sounds like information while carrying none",
+          "`valueText` when a percentage is not what a person wants read aloud — \"3 of 12 files\""
+        ],
+        "notes": [
+          "indeterminate omits aria-valuenow entirely, as the ARIA spec asks; a bar reporting aria-valuenow=0 forever says the work is stuck rather than unmeasured",
+          "value is clamped to 0..max, so a caller cannot render a bar past its own end"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "<ProgressBar label=\"Loading\" value={0} /> while the total is unknown",
+          "do": "<ProgressBar label=\"Loading\" />",
+          "why": "value={0} announces \"0 percent\" indefinitely. Omitting value is how you say \"not measurable yet\""
+        },
+        {
+          "dont": "swapping a Spinner for a ProgressBar once the size is known",
+          "do": "one ProgressBar, with `value` appearing when it becomes known",
+          "why": "the swap remounts the node and takes the live region with it, so the transition is silent to a screen reader"
+        },
+        {
+          "dont": "intent=\"error\" because the request failed",
+          "do": "leave the bar and put the failure in an Alert",
+          "why": "intent describes the value being measured. A failed request is not a red measurement, it is a different message"
+        }
+      ],
+      "stylesheet": "src/styles/progress-bar.css",
+      "tokens": [
+        "--border-width-default",
+        "--font-family-sans",
+        "--ion-duration-base",
+        "--ion-duration-slow",
+        "--ion-ease-in-out",
+        "--ion-ease-out",
+        "--ion-progress-bar-fill",
+        "--ion-progress-bar-height",
+        "--ion-progress-bar-pct",
+        "--radius-full",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-error",
+        "--surface-muted",
+        "--surface-primary",
+        "--surface-success",
+        "--surface-warning",
+        "--text-default",
+        "--text-secondary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "What is progressing. Required — a bare bar announces a number and no noun."
+        },
+        "value": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "0 to `max`. Omit for an indeterminate bar."
+        },
+        "max": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Defaults to 100."
+        },
+        "intent": {
+          "type": "ProgressBarIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "primary",
+            "success",
+            "warning",
+            "error"
+          ]
+        },
+        "size": {
+          "type": "ProgressBarSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md"
+          ]
+        },
+        "isLabelVisible": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Show the label as text above the track."
+        },
+        "isValueVisible": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Show the percentage beside the label. Determinate bars only."
+        },
+        "valueText": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Spoken instead of the percentage — \"3 of 12 files\". A percentage is rarely\nthe thing a person wants read aloud."
+        }
+      },
+      "propCounts": {
+        "own": 8,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "Radio": {
       "name": "Radio",
       "source": "src/components/Radio.tsx",
@@ -6692,7 +7997,8 @@
       "useInstead": [
         {
           "when": "the list is long enough to need search or type-ahead beyond the native behaviour",
-          "use": "a combobox — not yet in this system"
+          "use": "Combobox",
+          "why": "a native <select> list is the browser's, and cannot be filtered"
         },
         {
           "when": "the rows need icons, avatars or two lines of text",
@@ -6805,10 +8111,10 @@
           "default": "md"
         },
         "options": {
-          "type": "SelectOption[] | undefined",
+          "type": "readonly SelectOption[] | undefined",
           "required": false,
           "origin": "own",
-          "description": "The options to render. Omit and pass `children` for grouped options."
+          "description": "The options to render. Omit and pass `children` for grouped options.\n\n`readonly` because an options list is almost always a module-level constant,\nand `as const` on one produces a readonly array that a mutable parameter\nrejects. The component only ever maps over it, so demanding a mutable array\nbought nothing and cost callers a spread or a cast."
         },
         "placeholder": {
           "type": "string | undefined",
@@ -6872,107 +8178,350 @@
         "other": 0
       }
     },
-    "StreamingText": {
-      "name": "StreamingText",
-      "source": "src/components/StreamingText.tsx",
-      "propsType": "StreamingTextProps",
-      "description": "StreamingText — model output arriving a token at a time.\n\nIT IS NOT A LIVE REGION, AND THAT IS THE WHOLE DESIGN\n\nThe obvious implementation — `aria-live=\"polite\"` on the container — is the\none that makes a screen reader unusable. Every token mutation queues an\nannouncement, so the user hears the answer re-read, stuttered, dozens of\ntimes, and cannot get ahead of it. `aria-live=\"off\"` is not an oversight\nhere; it is the accessible choice.\n\nWhat it does instead: `aria-busy` while streaming, so assistive tech knows\nthe region is unsettled and can wait. The text is ordinary readable content\nthroughout — a screen-reader user navigates into it whenever they want,\nexactly like sighted users reading ahead of the cursor.\n\nANNOUNCING COMPLETION IS THE CALLER'S CALL, not this component's. Some\nsurfaces want \"response complete\"; a chat with ten turns on screen does not\nwant ten of them. Render your own `role=\"status\"` when you want it.\n\nTHE HEIGHT IS RESERVED, NOT ANIMATED. `minLines` holds space in `lh` units so\nthe content below stays still. A container that grows token by token drags\nthe whole page, which is worse for someone using magnification than the wait.\n\nThe cursor is CSS and `aria-hidden`. It stops blinking under\n`prefers-reduced-motion` — a blinking element is a WCAG 2.3.1 concern and a\ngenuine problem for some vestibular and attention conditions.",
-      "import": "import { StreamingText } from 'ionbase-ui';",
+    "Skeleton": {
+      "name": "Skeleton",
+      "source": "src/components/Skeleton.tsx",
+      "propsType": "SkeletonProps",
+      "description": "Skeleton — the shape of content that has not arrived.\n\nIT IS HIDDEN FROM ASSISTIVE TECHNOLOGY, ALWAYS, AND THAT IS THE WHOLE POINT\n\nA skeleton is a picture of content, and a screen reader cannot use a picture\nof content. Announcing it produces a stream of empty boxes between the user\nand the thing they asked for. So every skeleton is `aria-hidden`, with no way\nto opt out — a prop for that would only ever be used by mistake.\n\nWHICH MEANS THE CALLER OWES THE ANNOUNCEMENT, AND THIS COMPONENT CANNOT DO IT\n\nHiding the placeholder is only half an answer: something still has to tell a\nscreen-reader user that the region is loading. That belongs on the region\nbeing replaced — `aria-busy=\"true\"` while it loads — because only the caller\nknows where that region starts and ends. `Spinner` is the other half when the\nwait deserves an announcement of its own.\n\n  <section aria-busy={isLoading}>\n    {isLoading ? <Skeleton lines={3} /> : <Rows data={data} />}\n  </section>\n\nThis is the one component in the system whose correct use REQUIRES something\nof the caller that the type system cannot check, which is why it is stated\nhere, in the contract, and in the story.",
+      "import": "import { Skeleton } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Model output arriving a token at a time, in a container that does not move. Deliberately not a live region.",
+      "summary": "The shape of content that has not arrived. Always hidden from assistive technology — the caller owns the announcement.",
       "useWhen": [
-        "rendering a response that streams in rather than arriving whole",
-        "the reader should be able to start reading before generation finishes"
+        "a region will be replaced by content whose shape is known in advance",
+        "the layout would otherwise jump when the content lands",
+        "several regions load independently and a single page spinner would hide that"
       ],
       "useInstead": [
         {
-          "when": "the text is already complete",
-          "use": "Alert",
-          "why": "nothing about this component helps once there is nothing left to arrive"
+          "when": "the shape of what is coming is not known",
+          "use": "Spinner",
+          "why": "a skeleton that does not match what replaces it is a worse promise than no promise"
         },
         {
-          "when": "you are showing progress through steps rather than producing text",
-          "use": "AgentActivity"
+          "when": "the region is empty because there is nothing to show",
+          "use": "EmptyState",
+          "why": "a skeleton that never resolves is how an empty list looks like a broken one"
         }
       ],
+      "variants": {
+        "variant": {
+          "text": {
+            "use": "lines of copy",
+            "note": "height comes from the line box, so the block occupies what the real paragraph will. With `lines`, the last is drawn short because real paragraphs end mid-measure"
+          },
+          "circle": {
+            "use": "an avatar or an icon slot"
+          },
+          "rect": {
+            "use": "a card, a thumbnail, a chart"
+          }
+        }
+      },
       "a11y": {
-        "role": "region when `label` is set, none otherwise",
-        "guarantees": [
-          "`aria-live=\"off\"`, deliberately — a polite live region re-announces the whole answer on every token, which makes a streaming response unusable with a screen reader",
-          "`aria-busy` while streaming, so assistive tech knows the region is unsettled",
-          "the text stays ordinary readable content throughout, so a screen-reader user can read ahead exactly as a sighted user does",
-          "the cursor is `aria-hidden`, is a styled box rather than a text character, and stops blinking under `prefers-reduced-motion` (WCAG 2.3.1)"
-        ],
         "requires": [
-          "announcing completion yourself, with your own `role=\"status\"`, if the surface wants it — a chat with ten turns on screen does not want ten announcements",
-          "`label` when the region needs a name of its own"
+          "`aria-busy=\"true\"` on the region being replaced, set by the CALLER — this component cannot do it, because only the caller knows where the region starts and ends"
+        ],
+        "notes": [
+          "every skeleton is aria-hidden with no opt-out: a screen reader cannot use a picture of content, and announcing it puts a stream of empty boxes between the user and what they asked for",
+          "prefers-reduced-motion stops the pulse outright, unlike Spinner and ProgressBar — a skeleton conveys nothing a static block does not, so there is no signal to preserve"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "wrapping it in `aria-live=\"polite\"`",
-          "why": "every token queues an announcement; the user hears the answer stuttered dozens of times and cannot get ahead of it"
+          "dont": "<Skeleton /> inside a region with no aria-busy",
+          "do": "<section aria-busy={isLoading}>{isLoading ? <Skeleton lines={3} /> : <Rows />}</section>",
+          "why": "the skeleton is hidden, so without aria-busy a screen-reader user is told nothing at all — the region simply reads as empty"
         },
         {
-          "dont": "letting the container grow token by token with no reserved height",
-          "do": "`minLines`",
-          "why": "the content below climbs the screen while someone is reading it, which is worse under magnification than the wait"
+          "dont": "a skeleton whose shape does not match the content that replaces it",
+          "do": "match the line count and block sizes to the real thing",
+          "why": "the entire benefit is that the layout does not move; a mismatched skeleton pays the cost and keeps the jump"
         },
         {
-          "dont": "a text-character cursor like ▌",
-          "why": "some screen readers read it aloud even inside an aria-hidden span"
+          "dont": "leaving skeletons on screen when a request fails",
+          "do": "render EmptyState with reason=\"error\"",
+          "why": "a skeleton that never resolves is indistinguishable from a hung page"
         }
       ],
-      "stylesheet": "src/styles/streaming-text.css",
+      "stylesheet": "src/styles/skeleton.css",
       "tokens": [
-        "--font-family-sans",
-        "--ion-streaming-min-lines",
-        "--text-default",
-        "--text-tertiary",
-        "--type-body",
+        "--border-width-default",
+        "--icon-size-lg",
+        "--ion-duration-slow",
+        "--ion-ease-in-out",
+        "--ion-skeleton-height",
+        "--ion-skeleton-radius",
+        "--ion-skeleton-width",
+        "--radius-full",
+        "--radius-md",
+        "--radius-sm",
+        "--spacing-16",
+        "--spacing-64",
+        "--spacing-8",
+        "--surface-muted",
         "--type-body-line-height"
       ],
       "props": {
-        "children": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "The text so far. Re-render with more of it; this component appends nothing."
-        },
-        "isStreaming": {
-          "type": "boolean | undefined",
+        "variant": {
+          "type": "SkeletonVariant | undefined",
           "required": false,
           "origin": "own",
-          "description": "More is still arriving. Shows the cursor and marks the region busy."
+          "values": [
+            "circle",
+            "text",
+            "rect"
+          ]
         },
-        "minLines": {
-          "type": "number | undefined",
+        "width": {
+          "type": "string | undefined",
           "required": false,
           "origin": "own",
-          "description": "Rows of height to hold while the text is short, so the page below does not\nclimb the screen as tokens arrive. Costs blank space at the start and buys\na layout that does not move under a reader."
+          "description": "Any CSS length. Defaults to filling the width available."
         },
-        "label": {
+        "height": {
           "type": "string | undefined",
           "required": false,
           "origin": "own",
-          "description": "Accessible name for the region."
+          "description": "Any CSS length. `text` derives its height from the line box instead."
         },
-        "hideCursor": {
-          "type": "boolean | undefined",
+        "lines": {
+          "type": "number | undefined",
           "required": false,
           "origin": "own",
-          "description": "Hide the trailing cursor. The text still marks itself busy."
+          "description": "`text` only: how many lines to draw. The last is drawn short."
         }
       },
       "propCounts": {
-        "own": 5,
+        "own": 4,
         "aria": 0,
         "dom": 277,
         "other": 0
       }
     },
-    "TabItem": {
-      "name": "TabItem",
+    "Spinner": {
+      "name": "Spinner",
+      "source": "src/components/Spinner.tsx",
+      "propsType": "SpinnerProps",
+      "description": "Spinner — an indeterminate wait, announced once.\n\nWHY THIS IS NOT A DIV WITH A CSS ANIMATION\n\nThe obvious implementation is inaccessible in a specific and common way: a\nspinning graphic with no text is silence to a screen reader, so the user is\ntold nothing happened. Generated code in this repo's own eval corpus reached\nfor a bare `role=\"status\"` in 48 files, which is the right instinct and only\nhalf the job — the role creates a live region, but an empty one announces\nnothing at all.\n\nSo the default carries a label. It is visually hidden, it lives inside the\nlive region, and it is what makes \"Loading\" reach the user who cannot see the\nring.\n\n`isDecorative` exists because the opposite mistake is just as easy. A spinner\ninside a button whose label already changed to \"Saving…\" would announce\ntwice, and two live regions racing is worse than one. Decorative renders no\nrole at all rather than `aria-hidden` on a live region, which browsers treat\ninconsistently.\n\nMOTION\n\n`prefers-reduced-motion` slows the rotation rather than stopping it. A\nstationary spinner is not a calmer spinner — it is a broken one, and it\nremoves the only signal a sighted user has that the wait is still live.",
+      "import": "import { Spinner } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "An indeterminate wait, announced once. A ring plus a politely-announced label, sized off the icon ramp.",
+      "useWhen": [
+        "work is in flight and its duration cannot be measured",
+        "a control has started something and must show it is working",
+        "a small region is waiting and a skeleton would be more scaffolding than content"
+      ],
+      "useInstead": [
+        {
+          "when": "the work has a measurable fraction complete",
+          "use": "ProgressBar",
+          "why": "a spinner over measurable work discards information the user wants — a spinner and a 90%-complete upload look identical"
+        },
+        {
+          "when": "a region is being replaced by content with a known shape",
+          "use": "Skeleton",
+          "why": "a skeleton holds the layout so it does not jump when content lands; a spinner leaves a hole that then reflows"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "inside a control, or beside a line of text"
+          },
+          "md": {
+            "use": "the default — a panel or a section"
+          },
+          "lg": {
+            "use": "a whole route or a full-page wait"
+          }
+        }
+      },
+      "a11y": {
+        "requires": [
+          "a `label` naming what is loading — it is announced politely and is the only thing a screen-reader user receives",
+          "`isDecorative` when something else already announces the wait, so two live regions do not race"
+        ],
+        "notes": [
+          "the ring is aria-hidden; the label carries the meaning",
+          "prefers-reduced-motion slows the rotation rather than stopping it — a stationary spinner is indistinguishable from a hung one"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "<div className=\"spinner\" role=\"status\" />",
+          "do": "<Spinner label=\"Loading invoices\" />",
+          "why": "role=\"status\" creates a live region; an EMPTY live region announces nothing. This exact half-measure appeared in 48 files of this repo's eval corpus"
+        },
+        {
+          "dont": "<Button isDisabled>Saving… <Spinner /></Button>",
+          "do": "<Button isDisabled>Saving… <Spinner isDecorative /></Button>",
+          "why": "the button label already says it. Two live regions announcing the same wait talk over each other"
+        },
+        {
+          "dont": "a Spinner for an upload that reports bytes transferred",
+          "do": "ProgressBar with value",
+          "why": "throwing away a known percentage makes a finite wait feel unbounded"
+        }
+      ],
+      "stylesheet": "src/styles/spinner.css",
+      "tokens": [
+        "--border-primary-strong",
+        "--border-subtle",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-sm",
+        "--ion-duration-slow",
+        "--ion-ease-linear",
+        "--ion-spinner-head",
+        "--ion-spinner-size",
+        "--ion-spinner-track",
+        "--radius-full",
+        "--spacing-8",
+        "--text-secondary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "SpinnerSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the icon size ramp: sm, md, lg.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "What is loading. Announced politely; visible only with `isLabelVisible`."
+        },
+        "isLabelVisible": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Render the label as text beside the ring as well as announcing it."
+        },
+        "isDecorative": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The spinner conveys nothing on its own — something else already says the\nregion is busy. Renders inert: no role, no live region, hidden from AT."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "StreamingText": {
+      "name": "StreamingText",
+      "source": "src/components/StreamingText.tsx",
+      "propsType": "StreamingTextProps",
+      "description": "StreamingText — model output arriving a token at a time.\n\nIT IS NOT A LIVE REGION, AND THAT IS THE WHOLE DESIGN\n\nThe obvious implementation — `aria-live=\"polite\"` on the container — is the\none that makes a screen reader unusable. Every token mutation queues an\nannouncement, so the user hears the answer re-read, stuttered, dozens of\ntimes, and cannot get ahead of it. `aria-live=\"off\"` is not an oversight\nhere; it is the accessible choice.\n\nWhat it does instead: `aria-busy` while streaming, so assistive tech knows\nthe region is unsettled and can wait. The text is ordinary readable content\nthroughout — a screen-reader user navigates into it whenever they want,\nexactly like sighted users reading ahead of the cursor.\n\nANNOUNCING COMPLETION IS THE CALLER'S CALL, not this component's. Some\nsurfaces want \"response complete\"; a chat with ten turns on screen does not\nwant ten of them. Render your own `role=\"status\"` when you want it.\n\nTHE HEIGHT IS RESERVED, NOT ANIMATED. `minLines` holds space in `lh` units so\nthe content below stays still. A container that grows token by token drags\nthe whole page, which is worse for someone using magnification than the wait.\n\nThe cursor is CSS and `aria-hidden`. It stops blinking under\n`prefers-reduced-motion` — a blinking element is a WCAG 2.3.1 concern and a\ngenuine problem for some vestibular and attention conditions.",
+      "import": "import { StreamingText } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Model output arriving a token at a time, in a container that does not move. Deliberately not a live region.",
+      "useWhen": [
+        "rendering a response that streams in rather than arriving whole",
+        "the reader should be able to start reading before generation finishes"
+      ],
+      "useInstead": [
+        {
+          "when": "the text is already complete",
+          "use": "Alert",
+          "why": "nothing about this component helps once there is nothing left to arrive"
+        },
+        {
+          "when": "you are showing progress through steps rather than producing text",
+          "use": "AgentActivity"
+        }
+      ],
+      "a11y": {
+        "role": "region when `label` is set, none otherwise",
+        "guarantees": [
+          "`aria-live=\"off\"`, deliberately — a polite live region re-announces the whole answer on every token, which makes a streaming response unusable with a screen reader",
+          "`aria-busy` while streaming, so assistive tech knows the region is unsettled",
+          "the text stays ordinary readable content throughout, so a screen-reader user can read ahead exactly as a sighted user does",
+          "the cursor is `aria-hidden`, is a styled box rather than a text character, and stops blinking under `prefers-reduced-motion` (WCAG 2.3.1)"
+        ],
+        "requires": [
+          "announcing completion yourself, with your own `role=\"status\"`, if the surface wants it — a chat with ten turns on screen does not want ten announcements",
+          "`label` when the region needs a name of its own"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "wrapping it in `aria-live=\"polite\"`",
+          "why": "every token queues an announcement; the user hears the answer stuttered dozens of times and cannot get ahead of it"
+        },
+        {
+          "dont": "letting the container grow token by token with no reserved height",
+          "do": "`minLines`",
+          "why": "the content below climbs the screen while someone is reading it, which is worse under magnification than the wait"
+        },
+        {
+          "dont": "a text-character cursor like ▌",
+          "why": "some screen readers read it aloud even inside an aria-hidden span"
+        }
+      ],
+      "stylesheet": "src/styles/streaming-text.css",
+      "tokens": [
+        "--font-family-sans",
+        "--ion-streaming-min-lines",
+        "--text-default",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The text so far. Re-render with more of it; this component appends nothing."
+        },
+        "isStreaming": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "More is still arriving. Shows the cursor and marks the region busy."
+        },
+        "minLines": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Rows of height to hold while the text is short, so the page below does not\nclimb the screen as tokens arrive. Costs blank space at the start and buys\na layout that does not move under a reader."
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible name for the region."
+        },
+        "hideCursor": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Hide the trailing cursor. The text still marks itself busy."
+        }
+      },
+      "propCounts": {
+        "own": 5,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "TabItem": {
+      "name": "TabItem",
       "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Item.d.ts",
       "propsType": null,
       "import": "import { TabItem } from 'ionbase-ui';",
@@ -7778,79 +9327,454 @@
           "origin": "own",
           "description": "Drives both the arrow-key axis and the track layout.\n\n`vertical` is keyboard- and ARIA-complete — up/down move between tabs, and\nthe track stacks — but its *decoration* is not: the underline rule and the\npill track's padding are still written for the horizontal axis only. Those\nare Figma's to specify, not this file's to invent. See tabs.css.",
           "values": [
-            "horizontal",
-            "vertical"
+            "horizontal",
+            "vertical"
+          ],
+          "tags": {
+            "default": "'horizontal'"
+          },
+          "default": "horizontal"
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "keyboardActivation": {
+          "type": "\"manual\" | \"automatic\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether tabs are activated automatically on focus or manually.",
+          "values": [
+            "manual",
+            "automatic"
+          ],
+          "tags": {
+            "default": "'automatic'"
+          }
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "Whether the TabList is disabled.\nShows that a selection exists, but is not available in that circumstance."
+        },
+        "selectedKey": {
+          "type": "Key | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "The currently selected key in the collection (controlled)."
+        },
+        "defaultSelectedKey": {
+          "type": "Key | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "The initial selected keys in the collection (uncontrolled)."
+        },
+        "onSelectionChange": {
+          "type": "((key: Key) => void) | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "Handler that is called when the selection changes."
+        },
+        "children": {
+          "type": "CollectionChildren<T>",
+          "required": true,
+          "origin": "aria",
+          "description": "The contents of the collection."
+        },
+        "items": {
+          "type": "Iterable<T> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Item objects in the collection."
+        },
+        "disabledKeys": {
+          "type": "Iterable<Key> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise\ninteracted with."
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+        },
+        "aria-label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Defines a string value that labels the current element."
+        },
+        "aria-labelledby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that labels the current element."
+        },
+        "aria-describedby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that describes the object."
+        },
+        "aria-details": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 9,
+        "dom": 0,
+        "other": 4
+      }
+    },
+    "Textarea": {
+      "name": "Textarea",
+      "source": "src/components/Textarea.tsx",
+      "propsType": "TextareaProps",
+      "description": "A multi-line text field.\n\nGeometry from the Figma `Textarea` (1301:334). Every size and state is\nInput's — see textarea.css for why that is the point rather than a shortcut.",
+      "import": "import { Textarea } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A multi-line text field. Every size and state is Input's; it wraps and it resizes vertically.",
+      "useWhen": [
+        "the answer is prose — a description, a note, a message — and may run past one line",
+        "the user should be able to see several lines of what they wrote at once"
+      ],
+      "useInstead": [
+        {
+          "when": "the value is a single short string — a name, an email, a search term",
+          "use": "Input",
+          "why": "a one-line answer in a three-line box tells the user to write more than you want"
+        },
+        {
+          "when": "the answer is one of a known set",
+          "use": "Select",
+          "why": "free text you intend to parse into categories is a Select you have not built yet"
+        },
+        {
+          "when": "the field needs formatting controls or renders markup",
+          "use": "Input",
+          "why": "a rich-text editor is not in this library, and a textarea styled to look like one will not behave like one"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms and side panels"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "roomy layouts, and the primary field on a page"
+          }
+        }
+      },
+      "a11y": {
+        "role": "textbox (multiline)",
+        "guarantees": [
+          "the label, helper text and error message are wired to the control by React Aria's useTextField, so the accessible name and description are correct without the caller doing anything",
+          "`errorMessage` replaces the helper text only when `isInvalid` is set, and is announced as the field's description",
+          "the focus ring shows for keyboard focus only, and hover does not latch on touch",
+          "resize is disabled when the field is, matching what browsers do with a disabled textarea"
+        ],
+        "requires": [
+          "`label`, or an `aria-label` when the field is labelled by something on the page — an unlabelled textarea is announced only as \"edit text\"",
+          "a visible error cue that is not the border. THE INVALID BORDER IS 1px AS OF 0.49.0 and differs from a default field by hue alone, so pass `errorMessage` — WCAG 1.4.1 is not satisfied by the border on its own"
+        ]
+      },
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
+      "antiPatterns": [
+        {
+          "avoid": "setting a fixed `height` in CSS to size the box",
+          "instead": "use `rows`. The Figma height is derived from three lines of a bound line-height, so a fixed height pins the box while the text inside it keeps scaling with the type ramp"
+        },
+        {
+          "avoid": "drawing a custom resize grip",
+          "instead": "the browser paints one for `resize: vertical` and it cannot be styled or suppressed independently, so a custom grip sits beside it and the field gets two"
+        },
+        {
+          "avoid": "relying on `isInvalid` alone to communicate an error",
+          "instead": "pass `errorMessage` too. The border is 1px and the same width as every other state, so colour is the only difference without it"
+        }
+      ],
+      "stylesheet": "src/styles/textarea.css",
+      "tokens": [
+        "--border-default",
+        "--border-disabled",
+        "--border-error-strong",
+        "--border-focus",
+        "--border-strong",
+        "--border-subtle",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-textarea-border-width",
+        "--ion-textarea-font-size",
+        "--ion-textarea-line-height",
+        "--ion-textarea-padding-x",
+        "--ion-textarea-padding-y",
+        "--ion-textarea-radius",
+        "--radius-md",
+        "--radius-sm",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-page",
+        "--text-disabled",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "TextareaSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "autoCapitalize": {
+          "type": "\"none\" | \"off\" | \"on\" | \"sentences\" | \"words\" | \"characters\" | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Narrower than React's own typing, which also allows any `string` — the same\ncorrection Input carries. `autoCapitalize` is declared on\n`AriaTextFieldOptions` rather than `AriaTextFieldProps`, so the `keyof`\nomission above cannot reach it.",
+          "values": [
+            "none",
+            "off",
+            "on",
+            "sentences",
+            "words",
+            "characters"
+          ]
+        },
+        "rows": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Visible rows. Three matches the Figma frame, whose height is derived from\nthree lines of bound line-height rather than a fixed number — so this stays\ncorrect if the type ramp moves.",
+          "default": 3
+        },
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Field label. Renders the same `.ion-field` wrapper Input uses."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Helper text below the field."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Replaces the helper text when `isInvalid` is set."
+        },
+        "disabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+          }
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the control itself (`.ion-textarea`)."
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
+        },
+        "aria-activedescendant": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the currently active element when DOM focus is on a composite widget, textbox,\ngroup, or application."
+        },
+        "aria-autocomplete": {
+          "type": "\"inline\" | \"list\" | \"none\" | \"both\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates whether inputting text could trigger display of one or more predictions of the user's\nintended value for an input and specifies how predictions would be presented if they are made.",
+          "values": [
+            "inline",
+            "list",
+            "none",
+            "both"
+          ]
+        },
+        "aria-haspopup": {
+          "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+        },
+        "aria-controls": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+        },
+        "enterKeyHint": {
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
+          "values": [
+            "done",
+            "enter",
+            "go",
+            "next",
+            "previous",
+            "search",
+            "send"
+          ]
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input is disabled."
+        },
+        "isReadOnly": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input can be selected but not changed by the user."
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether user input is required on the input before form submission."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input value is invalid."
+        },
+        "validationState": {
+          "type": "ValidationState | undefined",
+          "required": false,
+          "origin": "aria",
+          "values": [
+            "valid",
+            "invalid"
           ],
           "tags": {
-            "default": "'horizontal'"
-          },
-          "default": "horizontal"
-        },
-        "className": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own"
+            "deprecated": "Use `isInvalid` instead."
+          }
         },
-        "keyboardActivation": {
-          "type": "\"manual\" | \"automatic\" | undefined",
+        "validationBehavior": {
+          "type": "\"aria\" | \"native\" | undefined",
           "required": false,
           "origin": "aria",
-          "description": "Whether tabs are activated automatically on focus or manually.",
+          "description": "Whether to use native HTML form validation to prevent form submission\nwhen the value is missing or invalid, or mark the field as required\nor invalid via ARIA.",
           "values": [
-            "manual",
-            "automatic"
+            "aria",
+            "native"
           ],
           "tags": {
-            "default": "'automatic'"
+            "default": "'aria'"
           }
         },
-        "isDisabled": {
+        "validate": {
+          "type": "((value: string) => ValidationError | true | null | undefined) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A function that returns an error message if a given value is invalid.\nValidation errors are displayed to the user when the form is submitted\nif `validationBehavior=\"native\"`. For realtime validation, use the `isInvalid`\nprop instead."
+        },
+        "autoFocus": {
           "type": "boolean | undefined",
           "required": false,
-          "origin": "other",
-          "description": "Whether the TabList is disabled.\nShows that a selection exists, but is not available in that circumstance."
+          "origin": "aria",
+          "description": "Whether the element should receive focus on render."
         },
-        "selectedKey": {
-          "type": "Key | undefined",
+        "onFocus": {
+          "type": "((e: FocusEvent<HTMLTextAreaElement, Element>) => void) | undefined",
           "required": false,
-          "origin": "other",
-          "description": "The currently selected key in the collection (controlled)."
+          "origin": "aria",
+          "description": "Handler that is called when the element receives focus."
         },
-        "defaultSelectedKey": {
-          "type": "Key | undefined",
+        "onBlur": {
+          "type": "((e: FocusEvent<HTMLTextAreaElement, Element>) => void) | undefined",
           "required": false,
-          "origin": "other",
-          "description": "The initial selected keys in the collection (uncontrolled)."
+          "origin": "aria",
+          "description": "Handler that is called when the element loses focus."
         },
-        "onSelectionChange": {
-          "type": "((key: Key) => void) | undefined",
+        "onFocusChange": {
+          "type": "((isFocused: boolean) => void) | undefined",
           "required": false,
-          "origin": "other",
-          "description": "Handler that is called when the selection changes."
+          "origin": "aria",
+          "description": "Handler that is called when the element's focus status changes."
         },
-        "children": {
-          "type": "CollectionChildren<T>",
-          "required": true,
+        "onKeyDown": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
+          "required": false,
           "origin": "aria",
-          "description": "The contents of the collection."
+          "description": "Handler that is called when a key is pressed."
         },
-        "items": {
-          "type": "Iterable<T> | undefined",
+        "onKeyUp": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
           "required": false,
           "origin": "aria",
-          "description": "Item objects in the collection."
+          "description": "Handler that is called when a key is released."
         },
-        "disabledKeys": {
-          "type": "Iterable<Key> | undefined",
+        "placeholder": {
+          "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise\ninteracted with."
+          "description": "Temporary text that occupies the text input when it is empty."
         },
-        "id": {
+        "value": {
           "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+          "description": "The current value (controlled)."
+        },
+        "defaultValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The default value (uncontrolled)."
+        },
+        "onChange": {
+          "type": "((value: string) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the value changes."
         },
         "aria-label": {
           "type": "string | undefined",
@@ -7875,13 +9799,158 @@
           "required": false,
           "origin": "aria",
           "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+        },
+        "excludeFromTabOrder": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+        },
+        "autoComplete": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
+        },
+        "maxLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The maximum number of characters supported by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength)."
+        },
+        "minLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
+        },
+        "pattern": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Regex pattern that the value of the input must match to be valid. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern)."
+        },
+        "type": {
+          "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+          "tags": {
+            "default": "'text'"
+          }
+        },
+        "inputMode": {
+          "type": "\"none\" | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"numeric\" | \"decimal\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Hints at the type of data that might be entered by the user while editing the element or its\ncontents. See\n[MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute).",
+          "values": [
+            "none",
+            "search",
+            "text",
+            "url",
+            "tel",
+            "email",
+            "numeric",
+            "decimal"
+          ]
+        },
+        "autoCorrect": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An attribute that takes as its value a space-separated string that describes what, if any, type\nof autocomplete functionality the input should provide. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete)."
+        },
+        "spellCheck": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An enumerated attribute that defines whether the element may be checked for spelling errors.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck)."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+        },
+        "form": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+        },
+        "onCopy": {
+          "type": "ClipboardEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user copies text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy)."
+        },
+        "onCut": {
+          "type": "ClipboardEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user cuts text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut)."
+        },
+        "onPaste": {
+          "type": "ClipboardEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user pastes text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste)."
+        },
+        "onCompositionStart": {
+          "type": "CompositionEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a text composition system starts a new text composition session.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)."
+        },
+        "onCompositionEnd": {
+          "type": "CompositionEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a text composition system completes or cancels the current text\ncomposition session. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event)."
+        },
+        "onCompositionUpdate": {
+          "type": "CompositionEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a new character is received in the current text composition\nsession. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event)."
+        },
+        "onSelect": {
+          "type": "ReactEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
+        },
+        "onBeforeInput": {
+          "type": "FormEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is about to be modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event)."
+        },
+        "onInput": {
+          "type": "FormEventHandler<HTMLTextAreaElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)."
+        },
+        "aria-errormessage": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element that provides an error message for the object."
         }
       },
       "propCounts": {
-        "own": 4,
-        "aria": 9,
-        "dom": 0,
-        "other": 4
+        "own": 9,
+        "aria": 48,
+        "dom": 251,
+        "other": 0
       }
     },
     "Toast": {
@@ -8276,6 +10345,11 @@
         {
           "dont": "a button with `aria-pressed` for a setting",
           "why": "a switch is a form value; the checkbox gives form association and `:checked` for free"
+        },
+        {
+          "dont": "<Toggle isSelected={on} onChange={(isSelected) => setOn(isSelected)} />",
+          "do": "<Toggle isSelected={on} onSelectionChange={setOn} />",
+          "why": "as Checkbox: `isSelected` pairs with `onSelectionChange` and `checked` pairs with `onChange(event)`. Toggle extends the input element, so `onChange` keeps the DOM signature it has always had."
         }
       ],
       "deprecated": [
@@ -8371,10 +10445,22 @@
           "type": "React.ReactNode",
           "required": false,
           "origin": "own"
+        },
+        "isSelected": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "React Aria's name for `checked`. Wins when both are passed."
+        },
+        "onSelectionChange": {
+          "type": "((isSelected: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Receives the new selection state rather than the change event."
         }
       },
       "propCounts": {
-        "own": 5,
+        "own": 7,
         "aria": 0,
         "dom": 304,
         "other": 0
@@ -8495,10 +10581,10 @@
           "origin": "own",
           "description": "Matches the Figma `Placement` variant, and names where the TOOLTIP sits —\nnot where the arrow points. `top` is above the trigger, with the arrow on\nthe tooltip's bottom edge.\n\nTreated as a preference, not a guarantee: it flips to the opposite side\nwhen there is no room, which is the behaviour Figma cannot draw.",
           "values": [
-            "right",
-            "left",
             "top",
-            "bottom"
+            "bottom",
+            "right",
+            "left"
           ]
         },
         "delay": {