ionbase-ui 0.51.0 → 0.59.0

package/dist/meta/components.json

@@ -1,11 +1,224 @@
 {
   "package": "ionbase-ui",
-  "version": "0.51.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"
@@ -2907,32 +3567,266 @@
           "dont": "a styled <div> for a rule",
           "why": "that is what this component exists to replace"
         },
-        {
-          "dont": "a Divider between every row of a list",
-          "why": "a break announced on every row is noise; use the list's own row borders"
-        }
-      ],
-      "stylesheet": "src/styles/divider.css",
-      "tokens": [
-        "--border-strong",
-        "--border-width-default"
-      ],
-      "props": {
-        "orientation": {
-          "type": "DividerOrientation | undefined",
+        {
+          "dont": "a Divider between every row of a list",
+          "why": "a break announced on every row is noise; use the list's own row borders"
+        }
+      ],
+      "stylesheet": "src/styles/divider.css",
+      "tokens": [
+        "--border-strong",
+        "--border-width-default"
+      ],
+      "props": {
+        "orientation": {
+          "type": "DividerOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches Figma's `Style` variant.",
+          "values": [
+            "horizontal",
+            "vertical"
+          ]
+        }
+      },
+      "propCounts": {
+        "own": 1,
+        "aria": 0,
+        "dom": 278,
+        "other": 0
+      }
+    },
+    "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": "A modal panel anchored to an edge. Modal behaviour — focus trap, Escape, scrim — with the shape of a side panel.",
+      "useWhen": [
+        "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": "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 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 dialog's accessible name"
+        },
+        "description": {
+          "accepts": "text"
+        },
+        "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": "Matches Figma's `Style` variant.",
-          "values": [
-            "horizontal",
-            "vertical"
-          ]
+          "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": 1,
-        "aria": 0,
-        "dom": 278,
+        "own": 11,
+        "aria": 3,
+        "dom": 0,
         "other": 0
       }
     },
@@ -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",
@@ -3146,30 +4040,276 @@
         "size": {
           "type": "EmptyStateSize | undefined",
           "required": false,
-          "origin": "own",
-          "description": "Defaults to `panel`.",
-          "values": [
-            "inline",
-            "page",
-            "panel"
-          ]
+          "origin": "own",
+          "description": "Defaults to `panel`.",
+          "values": [
+            "inline",
+            "page",
+            "panel"
+          ]
+        },
+        "headingLevel": {
+          "type": "EmptyStateHeadingLevel | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Heading level for the title. Defaults to `h3`; only the page knows its own\noutline, so it is a prop rather than a constant."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 9,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
+    "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 drop target wrapped around a real file input, with client-side accept and size checks.",
+      "useWhen": [
+        "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": "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": "upload progress needs to be shown",
+          "use": "ProgressBar",
+          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "inside a dense form, or beside other fields"
+          },
+          "md": {
+            "use": "the default — a standalone attachment area"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "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": [
+          "`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": "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": "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": "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"
+        }
+      ],
+      "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-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"
         },
-        "headingLevel": {
-          "type": "EmptyStateHeadingLevel | undefined",
+        "id": {
+          "type": "string | undefined",
           "required": false,
-          "origin": "own",
-          "description": "Heading level for the title. Defaults to `h3`; only the page knows its own\noutline, so it is a prop rather than a constant."
+          "origin": "own"
         },
-        "children": {
-          "type": "React.ReactNode",
+        "name": {
+          "type": "string | undefined",
           "required": false,
           "origin": "own"
         }
       },
       "propCounts": {
-        "own": 9,
+        "own": 20,
         "aria": 0,
-        "dom": 276,
+        "dom": 0,
         "other": 0
       }
     },
@@ -5547,41 +6687,11 @@
           "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",
-          "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",
+        "onChange": {
+          "type": "((value: string) => void) | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The current value (controlled)."
+          "description": "Handler that is called when the value changes."
         },
         "defaultValue": {
           "type": "string | undefined",
@@ -5772,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,
@@ -5808,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,
@@ -6059,115 +7199,281 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
-        "--font-weight-regular",
-        "--icon-secondary",
-        "--icon-size-md",
+        "--font-weight-medium",
+        "--font-weight-regular",
+        "--icon-secondary",
+        "--icon-size-md",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-popover-width",
+        "--ion-shadow-shadow-lg",
+        "--radius-md",
+        "--radius-sm",
+        "--ring-focus",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-32",
+        "--spacing-8",
+        "--surface-hover",
+        "--surface-raised",
+        "--text-default",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactElement<unknown, string | React.JSXElementConstructor<any>>",
+          "required": true,
+          "origin": "own",
+          "description": "The element that opens it. Must accept a ref and DOM props."
+        },
+        "content": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Panel contents."
+        },
+        "title": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Heading. Also gives the dialog its accessible name."
+        },
+        "footer": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Action row, right-aligned."
+        },
+        "placement": {
+          "type": "PopoverPlacement | undefined",
+          "required": false,
+          "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": [
+            "top",
+            "bottom",
+            "right",
+            "left"
+          ]
+        },
+        "size": {
+          "type": "PopoverSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant. Widths only; height always hugs.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "showClose": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Show the close button. Defaults to `true`."
+        },
+        "hideArrow": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Hide the caret."
+        },
+        "closeLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onOpenChange": {
+          "type": "((isOpen: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 12,
+        "aria": 0,
+        "dom": 0,
+        "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-popover-width",
-        "--ion-shadow-shadow-lg",
-        "--radius-md",
-        "--radius-sm",
-        "--ring-focus",
-        "--spacing-12",
-        "--spacing-16",
-        "--spacing-32",
+        "--ion-progress-bar-fill",
+        "--ion-progress-bar-height",
+        "--ion-progress-bar-pct",
+        "--radius-full",
+        "--spacing-4",
         "--spacing-8",
-        "--surface-hover",
-        "--surface-raised",
+        "--surface-error",
+        "--surface-muted",
+        "--surface-primary",
+        "--surface-success",
+        "--surface-warning",
         "--text-default",
         "--text-secondary",
-        "--type-body",
-        "--type-body-line-height",
         "--type-body-sm",
         "--type-body-sm-line-height"
       ],
       "props": {
-        "children": {
-          "type": "React.ReactElement<unknown, string | React.JSXElementConstructor<any>>",
+        "label": {
+          "type": "string",
           "required": true,
           "origin": "own",
-          "description": "The element that opens it. Must accept a ref and DOM props."
-        },
-        "content": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "Panel contents."
+          "description": "What is progressing. Required — a bare bar announces a number and no noun."
         },
-        "title": {
-          "type": "React.ReactNode",
+        "value": {
+          "type": "number | undefined",
           "required": false,
           "origin": "own",
-          "description": "Heading. Also gives the dialog its accessible name."
+          "description": "0 to `max`. Omit for an indeterminate bar."
         },
-        "footer": {
-          "type": "React.ReactNode",
+        "max": {
+          "type": "number | undefined",
           "required": false,
           "origin": "own",
-          "description": "Action row, right-aligned."
+          "description": "Defaults to 100."
         },
-        "placement": {
-          "type": "PopoverPlacement | undefined",
+        "intent": {
+          "type": "ProgressBarIntent | undefined",
           "required": false,
           "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"
+            "primary",
+            "success",
+            "warning",
+            "error"
           ]
         },
         "size": {
-          "type": "PopoverSize | undefined",
+          "type": "ProgressBarSize | undefined",
           "required": false,
           "origin": "own",
-          "description": "Matches the Figma `Size` variant. Widths only; height always hugs.",
           "values": [
             "sm",
-            "md",
-            "lg"
+            "md"
           ]
         },
-        "showClose": {
+        "isLabelVisible": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Show the close button. Defaults to `true`."
+          "description": "Show the label as text above the track."
         },
-        "hideArrow": {
+        "isValueVisible": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Hide the caret."
+          "description": "Show the percentage beside the label. Determinate bars only."
         },
-        "closeLabel": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own"
-        },
-        "isOpen": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "own"
-        },
-        "onOpenChange": {
-          "type": "((isOpen: boolean) => void) | undefined",
-          "required": false,
-          "origin": "own"
-        },
-        "className": {
+        "valueText": {
           "type": "string | undefined",
           "required": false,
-          "origin": "own"
+          "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": 12,
+        "own": 8,
         "aria": 0,
-        "dom": 0,
+        "dom": 277,
         "other": 0
       }
     },
@@ -6691,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",
@@ -6804,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",
@@ -6871,6 +8178,249 @@
         "other": 0
       }
     },
+    "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": "The shape of content that has not arrived. Always hidden from assistive technology — the caller owns the announcement.",
+      "useWhen": [
+        "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 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": "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": {
+        "requires": [
+          "`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": "<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": "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": "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/skeleton.css",
+      "tokens": [
+        "--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": {
+        "variant": {
+          "type": "SkeletonVariant | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "circle",
+            "text",
+            "rect"
+          ]
+        },
+        "width": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Any CSS length. Defaults to filling the width available."
+        },
+        "height": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Any CSS length. `text` derives its height from the line box instead."
+        },
+        "lines": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "`text` only: how many lines to draw. The last is drawn short."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "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",
@@ -8795,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": [
@@ -8890,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
@@ -9014,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": {