ionbase-ui 0.22.0 → 0.25.0

package/dist/meta/components.json

@@ -1,675 +1,560 @@
 {
   "package": "ionbase-ui",
-  "version": "0.22.0",
+  "version": "0.25.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
   ],
   "components": {
-    "Alert": {
-      "name": "Alert",
-      "source": "src/components/Alert.tsx",
-      "propsType": "AlertProps",
-      "description": "Alert — Figma `Alert` (812:1902).\n\n`Intent` x `Emphasis` x `Layout`, with the parts as props rather than\nvariants. Intents match `Badge` exactly, so a status mapped to one can be\npassed to the other.\n\nROLE IS CHOSEN BY INTENT, NOT PASSED IN. `error` and `warning` render\n`role=\"alert\"`, which interrupts a screen reader; the rest render\n`role=\"status\"`, which waits for a pause. Getting this backwards is the\ncommon failure — a page of `role=\"alert\"` status messages talks over the\nuser, and an error announced as a status is missed.\n\nThe icon is decorative: it repeats what the intent's colour and copy already\nsay, so it is `aria-hidden` and the live region carries the text alone.",
-      "import": "import { Alert } from 'ionbase-ui';",
+    "AgentActivity": {
+      "name": "AgentActivity",
+      "source": "src/components/AgentActivity.tsx",
+      "propsType": "AgentActivityProps",
+      "description": "AgentActivity — what the agent is doing, in plain language.\n\nAn ordered list, because the steps happened in an order and a screen reader\nshould say \"3 of 7\". Not a log viewer: this is the account a person reads to\ndecide whether to let the run continue, so the text belongs in their\nlanguage — \"Searched the invoice archive\", not `searchIndex(q, {limit:50})`.\n\nSTATUS IS NEVER CARRIED BY THE ICON ALONE. Every step renders its status as\ntext as well as a glyph. The glyphs differ in shape rather than only in\ncolour, so the list survives greyscale, colour blindness and forced-colours\nmode — WCAG 1.4.1, which a row of coloured dots fails outright.\n\nONE POLITE ANNOUNCEMENT PER STEP, not one per render. The active step's text\nis announced when it changes, so a user who is not watching still knows where\nthe run has got to. Watching the DOM instead would re-announce on every\nunrelated update, which is the failure mode that makes people turn logs off.",
+      "import": "import { AgentActivity } from 'ionbase-ui';",
       "status": "stable",
-      "since": "0.13.1",
-      "summary": "A persistent, in-page status message. Intent picks the ARIA role for you.",
+      "summary": "An ordered, plain-language log of what the agent is doing. Status is text and shape, never colour alone.",
       "useWhen": [
-        "the message belongs to the page and should stay until the condition clears",
-        "form-level validation summaries, permission notices, degraded-state banners"
+        "a run takes long enough that the user needs to know where it has got to",
+        "a person will decide whether to let it continue — which means they need to read what it did"
       ],
       "useInstead": [
         {
-          "when": "the message is transient and self-dismissing",
-          "use": "Toast",
-          "why": "an Alert stays in the layout; a Toast does not"
+          "when": "the output is prose rather than steps",
+          "use": "StreamingText"
         },
         {
-          "when": "it labels a value inline rather than telling the user something",
-          "use": "Badge",
-          "why": "Badge shares Alert's intent vocabulary exactly, so a status mapped to one passes to the other"
-        }
-      ],
-      "variants": {
-        "intent": {
-          "error": {
-            "use": "something failed and the user must act",
-            "aria": "role=alert — interrupts the screen reader"
-          },
-          "warning": {
-            "use": "something may fail or has degraded",
-            "aria": "role=alert — interrupts the screen reader"
-          },
-          "success": {
-            "use": "an operation completed",
-            "aria": "role=status"
-          },
-          "information": {
-            "use": "neutral context the user did not ask for",
-            "aria": "role=status"
-          },
-          "primary": {
-            "use": "product announcements and promotions",
-            "aria": "role=status"
-          },
-          "neutral": {
-            "use": "low-emphasis context",
-            "aria": "role=status"
-          }
-        },
-        "emphasis": {
-          "subtle": {
-            "use": "the default — tinted surface, readable in long pages"
-          },
-          "solid": {
-            "use": "reserve for a single high-stakes banner; it dominates the layout"
-          }
+          "when": "you need a decision, not a report",
+          "use": "ApprovalGate"
         },
-        "layout": {
-          "inline": {
-            "use": "inside a form or card, in the flow of content"
-          },
-          "banner": {
-            "use": "full-bleed at the top of a page or region"
-          }
+        {
+          "when": "it is one finished outcome",
+          "use": "Alert"
         }
+      ],
+      "composition": {
+        "order": [
+          "AgentActivity",
+          "AgentActivityStep"
+        ],
+        "note": "An <ol>, so a screen reader can say \"3 of 7\" and the order is structural rather than typed into each row.",
+        "example": "<AgentActivity><AgentActivityStep status=\"done\">Searched the invoice archive</AgentActivityStep><AgentActivityStep status=\"active\">Reading 12 matches</AgentActivityStep></AgentActivity>"
       },
       "a11y": {
+        "role": "list",
         "guarantees": [
-          "the role follows the intent — error and warning are role=alert, everything else role=status",
-          "the icon is aria-hidden, so the live region announces the text once and not the glyph"
+          "every step renders its status as visually hidden text as well as a glyph, and the glyphs differ in shape rather than only in colour — a row of coloured dots fails WCAG 1.4.1 outright",
+          "the active step is announced once, when it changes, in a polite live region",
+          "the active step's spinner stops under `prefers-reduced-motion`"
         ],
         "requires": [
-          "`dismissLabel` when `onDismiss` is set and the surrounding copy does not name the action"
+          "step text in the user's language — \"Searched the invoice archive\", not a function signature",
+          "`announceActive={false}` when several logs are on screen, or they narrate over each other"
         ],
         "notes": [
-          "role=alert interrupts whatever the screen reader is saying; role=status waits for a pause. This is why the role is not a prop."
+          "The active step is read out of the children rather than taken as a prop. Two sources for one fact is how they come to disagree."
         ]
       },
       "antiPatterns": [
         {
-          "dont": "using intent=\"error\" for a message that is merely informational",
-          "why": "error renders role=alert, which interrupts the screen reader. A page of interrupting status messages talks over the user."
+          "dont": "raw tool calls or JSON as the step label",
+          "why": "this is the account a person reads to decide whether to let the run continue"
         },
         {
-          "dont": "using intent=\"information\" for a genuine failure",
-          "why": "role=status waits for a pause, so a real error can be missed entirely"
+          "dont": "more than one step with `status=\"active\"`",
+          "why": "the announcement names one thing, and two claims about what is happening now cannot both be true"
         },
         {
-          "dont": "rendering an Alert conditionally for a transient confirmation",
-          "do": "useToast",
-          "why": "an Alert that appears and disappears shifts the layout under the user"
+          "dont": "several announcing logs on one screen",
+          "do": "`announceActive={false}` on all but one",
+          "why": "they interrupt each other and the user turns the whole thing off"
         }
       ],
-      "stylesheet": "src/styles/alert.css",
+      "stylesheet": "src/styles/agent-activity.css",
       "tokens": [
-        "--border-default",
-        "--border-error-strong",
-        "--border-error-subtle",
-        "--border-information-strong",
-        "--border-information-subtle",
-        "--border-inverse",
-        "--border-primary-strong",
-        "--border-primary-subtle",
-        "--border-success-strong",
-        "--border-success-subtle",
-        "--border-warning-strong",
-        "--border-warning-subtle",
-        "--border-width-default",
-        "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
-        "--font-weight-regular",
         "--icon-error",
-        "--icon-information",
-        "--icon-on-color",
         "--icon-primary",
-        "--icon-secondary",
-        "--icon-size-md",
+        "--icon-size-sm",
         "--icon-success",
-        "--icon-warning",
-        "--ion-alert-border",
-        "--ion-alert-icon",
-        "--ion-alert-surface",
-        "--ion-alert-text",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--radius-md",
-        "--radius-sm",
-        "--ring-focus",
-        "--spacing-12",
-        "--spacing-16",
-        "--spacing-32",
+        "--icon-tertiary",
+        "--spacing-2",
         "--spacing-8",
-        "--surface-error",
-        "--surface-error-subtle",
-        "--surface-hover",
-        "--surface-information",
-        "--surface-information-subtle",
-        "--surface-inverse",
-        "--surface-muted",
-        "--surface-primary",
-        "--surface-primary-subtle",
-        "--surface-success",
-        "--surface-success-subtle",
-        "--surface-warning",
-        "--surface-warning-subtle",
+        "--text-default",
         "--text-error",
-        "--text-information",
-        "--text-link",
-        "--text-on-color",
         "--text-secondary",
-        "--text-success",
-        "--text-warning",
-        "--type-body",
-        "--type-body-line-height"
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
       ],
       "props": {
-        "intent": {
-          "type": "AlertIntent | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Matches the Figma `Intent` variant. Same vocabulary as `Badge`.",
-          "values": [
-            "neutral",
-            "primary",
-            "success",
-            "warning",
-            "error",
-            "information"
-          ],
-          "default": "information"
-        },
-        "emphasis": {
-          "type": "AlertEmphasis | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Matches the Figma `Emphasis` variant.",
-          "values": [
-            "subtle",
-            "solid"
-          ],
-          "default": "subtle"
-        },
-        "layout": {
-          "type": "AlertLayout | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Matches the Figma `Layout` variant.",
-          "values": [
-            "inline",
-            "banner"
-          ],
-          "default": "inline"
-        },
-        "title": {
+        "children": {
           "type": "React.ReactNode",
           "required": false,
-          "origin": "own",
-          "description": "Optional heading above the message."
+          "origin": "own"
         },
-        "hideIcon": {
+        "announceActive": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Hide the leading icon. Shown by default."
-        },
-        "icon": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "Replace the intent's glyph."
-        },
-        "actions": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "Action buttons, rendered under the message."
-        },
-        "onDismiss": {
-          "type": "(() => void) | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Called when the dismiss button is pressed. Omit for no dismiss button."
-        },
-        "dismissLabel": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Accessible name for the dismiss button.",
-          "default": "Dismiss"
-        },
-        "children": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "The message."
+          "description": "Announce the step that just became active, once, in a polite live region.\n\nOn by default because the whole point of an activity log is knowing what\nthe agent is doing without watching it. Turn it off when several logs are\non screen at once, or they narrate over each other."
         }
       },
       "propCounts": {
-        "own": 10,
+        "own": 2,
         "aria": 0,
-        "dom": 276,
+        "dom": 277,
         "other": 0
       }
     },
-    "Avatar": {
-      "name": "Avatar",
-      "source": "src/components/Avatar.tsx",
-      "propsType": "AvatarProps",
-      "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
-      "import": "import { Avatar } from 'ionbase-ui';",
+    "AgentActivityStep": {
+      "name": "AgentActivityStep",
+      "source": "src/components/AgentActivity.tsx",
+      "propsType": "AgentActivityStepProps",
+      "import": "import { AgentActivityStep } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A person or entity marker. Content is chosen by precedence — image, then initials, then icon — not by a type prop.",
+      "summary": "One step in an activity log: what happened, in the user's language, with a status carried by shape and text.",
       "useWhen": [
-        "identifying who owns, authored or is assigned to something",
-        "a table cell, menu row or header needs a compact identity marker beside a name"
+        "a child of AgentActivity — it is not usable elsewhere"
       ],
       "useInstead": [
         {
-          "when": "the thing being marked is a status, count or category rather than a person",
-          "use": "Badge"
+          "when": "it is a row in a dropdown",
+          "use": "MenuItem"
         },
         {
-          "when": "you only need a decorative graphic with no identity behind it",
-          "use": "Icon"
+          "when": "it is a data row",
+          "use": "TableRow"
         }
       ],
       "variants": {
-        "size": {
-          "mini": {
-            "use": "24px — inline beside body text, dense table rows"
+        "status": {
+          "pending": {
+            "use": "the default — queued, not started"
           },
-          "sm": {
-            "use": "32px — menu rows, compact lists"
+          "active": {
+            "use": "happening now. Only one step should carry it"
           },
-          "md": {
-            "use": "the default, 40px"
+          "done": {
+            "use": "finished successfully"
           },
-          "lg": {
-            "use": "48px — profile headers and detail pages"
-          }
-        },
-        "shape": {
-          "circle": {
-            "use": "the default — people"
+          "failed": {
+            "use": "did not finish. Say why in `detail`"
           },
-          "square": {
-            "use": "organisations, projects, workspaces and other non-human entities"
+          "skipped": {
+            "use": "deliberately not run — a branch not taken, a cached result"
           }
         }
       },
       "slots": {
-        "icon": {
-          "accepts": "Icon",
-          "note": "the last fallback — rendered only when there is neither `src` nor `initials`"
+        "children": {
+          "accepts": "text",
+          "note": "the step in plain language"
+        },
+        "detail": {
+          "accepts": "text",
+          "note": "the result, a count, a tool name — whatever makes the step checkable"
         }
       },
       "a11y": {
         "guarantees": [
-          "`alt` falls back to `initials`, so the avatar is never announced as an unlabelled image",
-          "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph"
-        ],
-        "requires": [
-          "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\""
+          "the status name is rendered as visually hidden text, so it is never carried by the glyph's colour alone",
+          "each status has a differently shaped glyph, which survives greyscale and forced-colours mode"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "passing `src` without `initials`",
-          "why": "a 404 leaves the fallback empty; initials are what make the failure invisible"
+          "dont": "`failed` with no `detail`",
+          "why": "a failure the reader cannot diagnose is just a red mark"
         },
         {
-          "dont": "using Avatar as a button",
-          "do": "put the Avatar inside a Button or Link",
-          "why": "Avatar renders a <span> with no role and takes no focus"
+          "dont": "using it outside AgentActivity",
+          "why": "it renders an <li>, which is only valid inside a list"
         }
       ],
-      "stylesheet": "src/styles/avatar.css",
+      "stylesheet": "src/styles/agent-activity.css",
       "tokens": [
-        "--border-strong",
-        "--border-width-default",
         "--font-family-sans",
-        "--font-weight-medium",
-        "--icon-size-2xs",
-        "--icon-size-lg",
-        "--icon-size-md",
+        "--icon-error",
+        "--icon-primary",
         "--icon-size-sm",
+        "--icon-success",
         "--icon-tertiary",
-        "--ion-avatar-font-size",
-        "--ion-avatar-group-overlap",
-        "--ion-avatar-icon",
-        "--ion-avatar-line-height",
-        "--ion-avatar-radius",
-        "--ion-avatar-size",
-        "--radius-full",
-        "--radius-md",
-        "--radius-sm",
-        "--radius-xs",
-        "--spacing-24",
-        "--spacing-32",
-        "--spacing-40",
-        "--spacing-48",
-        "--surface-muted",
+        "--spacing-2",
+        "--spacing-8",
+        "--text-default",
+        "--text-error",
+        "--text-secondary",
         "--text-tertiary",
-        "--type-body",
-        "--type-body-line-height",
         "--type-body-sm",
         "--type-body-sm-line-height",
         "--type-caption",
-        "--type-caption-line-height",
-        "--type-h5",
-        "--type-h5-line-height"
+        "--type-caption-line-height"
       ],
       "props": {
-        "size": {
-          "type": "AvatarSize | undefined",
+        "children": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
-          "values": [
-            "mini",
-            "sm",
-            "md",
-            "lg"
-          ]
+          "description": "What the agent did, in the user's language. Not a function name."
         },
-        "shape": {
-          "type": "AvatarShape | undefined",
+        "status": {
+          "type": "AgentActivityStatus | undefined",
           "required": false,
           "origin": "own",
-          "description": "Matches the Figma `Shape` variant.",
           "values": [
-            "circle",
-            "square"
+            "pending",
+            "active",
+            "done",
+            "failed",
+            "skipped"
           ]
         },
-        "src": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Image source. Figma's `Type=Image`."
-        },
-        "alt": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Describes the person, not the picture. Falls back to `initials` so the\navatar is never announced as an unlabelled image."
-        },
-        "initials": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Figma's `Type=Character`. Rendered when there is no `src`, or when `src`\nfails to load."
-        },
-        "icon": {
+        "detail": {
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Type=Icon`. Rendered when there is neither `src` nor `initials`."
+          "description": "The result, a tool name, a count — whatever makes the step checkable."
         }
       },
       "propCounts": {
-        "own": 6,
+        "own": 3,
         "aria": 0,
         "dom": 278,
         "other": 0
       }
     },
-    "AvatarGroup": {
-      "name": "AvatarGroup",
-      "source": "src/components/Avatar.tsx",
-      "propsType": "AvatarGroupProps",
-      "description": "AvatarGroup overlaps its children by a quarter of the avatar size, matching\nFigma's -6 / -8 / -10 / -12 gaps at Mini / Small / Medium / Large.\n\nGroup defaults fill in `size` / `shape` only when a child Avatar has not set\nthem itself — an explicit child prop wins. Non-Avatar children are left\nalone so `size`/`shape` are never pushed onto arbitrary DOM nodes.\n\nChildren render in source order because that is Figma's stacking: each avatar\npaints over the one before it, so the `+N` overflow ends up on top. Later\nsiblings paint later, so this needs no z-index.",
-      "import": "import { AvatarGroup } from 'ionbase-ui';",
+    "AgentStop": {
+      "name": "AgentStop",
+      "source": "src/components/AgentStop.tsx",
+      "propsType": "AgentStopProps",
+      "description": "AgentStop — the always-visible way to end a run.\n\nNOT OPTIONAL, AND NOT BEHIND A MENU. A user who cannot stop an agent is\nwatching it, not supervising it. Human oversight of an automated process is\na compliance surface in regulated contexts, not a UX preference, and the\ncontrol that provides it has to be present and reachable at the moment it is\nwanted — not two clicks into an overflow menu.\n\nWHY IT IS NOT JUST `<Button variant=\"destructive\">`\n\nThree things it owns that a Button does not:\n\n  It keeps its place while stopping. A control that vanishes the instant it\n  is pressed leaves the user unsure whether the press registered, and the\n  run is usually still going. It stays, relabels, and disables — the layout\n  does not move.\n\n  It announces. The label change is only announced to a screen reader if the\n  button happens to hold focus, which it usually does not when a run was\n  started elsewhere. A polite live region says \"Stopping\" once.\n\n  It is not destructive-red. Stopping is a normal, expected, reversible-in-\n  spirit action — you can run it again. Colouring it like `delete` teaches\n  hesitation about the one control that must never be hesitated over.\n\nWHAT IT DOES NOT DO. It does not stop anything. It reports intent; the\ncaller aborts the request, closes the stream and settles the state. A stop\nbutton that resolves optimistically while tokens keep arriving is worse than\nnone, because it lies about a guarantee the user is relying on.",
+      "import": "import { AgentStop } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Overlapping Avatars with a `+N` overflow, for showing several people in one row's width.",
+      "summary": "The always-visible way to end a running agent. Not optional, and not behind a menu.",
       "useWhen": [
-        "several people share one thing — assignees, participants, collaborators",
-        "the exact list matters less than the fact that there are several"
+        "anything runs long enough that a person might want it to stop — a generation, a tool chain, a batch job",
+        "the run was started by the user and is still going"
       ],
       "useInstead": [
         {
-          "when": "each person needs their own name, role or action visible",
-          "use": "Table",
-          "why": "an overlapping stack hides everything but the picture"
+          "when": "the action is instant and there is nothing to interrupt",
+          "use": "Button"
+        },
+        {
+          "when": "you are asking permission before something happens rather than ending something already happening",
+          "use": "ApprovalGate"
+        },
+        {
+          "when": "the thing to undo has already finished",
+          "use": "Toast",
+          "why": "an undo affordance belongs with the confirmation of what was done"
         }
       ],
       "variants": {
         "size": {
-          "mini": {
-            "use": "24px — inline beside body text, dense table rows"
-          },
           "sm": {
-            "use": "32px — menu rows, compact lists"
+            "use": "inside a toolbar or beside an inline activity row"
           },
           "md": {
-            "use": "the default, 40px"
+            "use": "the default"
           },
           "lg": {
-            "use": "48px — profile headers and detail pages"
-          }
-        },
-        "shape": {
-          "circle": {
-            "use": "the default — people"
-          },
-          "square": {
-            "use": "organisations, projects, workspaces"
+            "use": "a full-width run surface where stopping is the primary available action"
           }
         }
       },
-      "slots": {
-        "children": {
-          "accepts": "Avatar",
-          "note": "group `size`/`shape` fill in only where a child has not set its own; a child's explicit prop wins. Non-Avatar children are left untouched."
-        }
-      },
       "a11y": {
+        "role": "button",
+        "guarantees": [
+          "the control keeps its place while stopping — it relabels and disables rather than disappearing, so the layout does not move under the pointer",
+          "the transition to stopping is announced once through a polite live region, because the label change alone is only heard if the button happens to hold focus",
+          "`stopOnEscape` ignores Escape raised inside a dialog, so closing a modal never cancels a background run"
+        ],
         "requires": [
-          "`alt` on every child Avatar — the overflow avatar is the only one the group names for you"
+          "keeping it rendered and visible for the whole run — a stop control that scrolls away or hides in an overflow menu is the failure this component exists to prevent"
         ],
         "notes": [
-          "Children paint in source order, so the `+N` overflow lands on top without any z-index."
+          "It does not stop anything. It reports intent; aborting the request and settling the state is the caller's. A stop that resolves optimistically while output keeps arriving lies about the one guarantee the user is relying on."
         ]
       },
       "antiPatterns": [
         {
-          "dont": "omitting `max` on an unbounded list",
-          "why": "twenty overlapping avatars is not a summary; it is a smear"
+          "dont": "putting the stop control in an overflow menu",
+          "why": "a user who cannot reach it is watching the agent, not supervising it"
+        },
+        {
+          "dont": "disabling it while the run is going",
+          "why": "the only correct disabled state is `isStopping` — after the request, never before"
+        },
+        {
+          "dont": "unmounting it the moment it is pressed",
+          "do": "pass `isStopping`",
+          "why": "the run is usually still going, and a control that vanishes leaves the user unsure the press registered"
+        },
+        {
+          "dont": "styling it as destructive",
+          "why": "stopping is normal and repeatable; red teaches hesitation about the one control that must never be hesitated over"
+        },
+        {
+          "dont": "`stopOnEscape` on a page with modals over the run",
+          "why": "Escape already means dismiss to every overlay in this system"
         }
       ],
-      "stylesheet": "src/styles/avatar.css",
+      "stylesheet": "src/styles/agent-stop.css",
       "tokens": [
+        "--border-default",
+        "--border-error",
+        "--border-focus",
         "--border-strong",
         "--border-width-default",
+        "--border-width-thick",
         "--font-family-sans",
         "--font-weight-medium",
-        "--icon-size-2xs",
-        "--icon-size-lg",
         "--icon-size-md",
         "--icon-size-sm",
-        "--icon-tertiary",
-        "--ion-avatar-font-size",
-        "--ion-avatar-group-overlap",
-        "--ion-avatar-icon",
-        "--ion-avatar-line-height",
-        "--ion-avatar-radius",
-        "--ion-avatar-size",
-        "--radius-full",
+        "--icon-size-xs",
+        "--ion-duration-base",
+        "--ion-ease-out",
         "--radius-md",
-        "--radius-sm",
-        "--radius-xs",
-        "--spacing-24",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
         "--spacing-32",
+        "--spacing-4",
         "--spacing-40",
         "--spacing-48",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-error-subtle",
+        "--surface-error-subtle-hover",
         "--surface-muted",
-        "--text-tertiary",
+        "--text-default",
+        "--text-error",
+        "--text-secondary",
         "--type-body",
+        "--type-body-lg",
+        "--type-body-lg-line-height",
         "--type-body-line-height",
         "--type-body-sm",
-        "--type-body-sm-line-height",
-        "--type-caption",
-        "--type-caption-line-height",
-        "--type-h5",
-        "--type-h5-line-height"
+        "--type-body-sm-line-height"
       ],
       "props": {
-        "size": {
-          "type": "AvatarSize | undefined",
+        "onStop": {
+          "type": "() => void",
+          "required": true,
+          "origin": "own",
+          "description": "Called when the user asks the run to stop."
+        },
+        "isStopping": {
+          "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "values": [
-            "mini",
-            "sm",
-            "md",
-            "lg"
-          ]
+          "description": "The request is in flight. The control stays visible and keeps its place;\nit does not disappear while the thing it cancels is still running."
         },
-        "max": {
-          "type": "number | undefined",
+        "label": {
+          "type": "string | undefined",
           "required": false,
           "origin": "own",
-          "description": "Cap on avatars shown; the remainder becomes a `+N` overflow avatar."
+          "description": "Visible label."
         },
-        "shape": {
-          "type": "AvatarShape | undefined",
+        "stoppingLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Visible label once `isStopping` is set."
+        },
+        "size": {
+          "type": "AgentStopSize | undefined",
           "required": false,
           "origin": "own",
           "values": [
-            "circle",
-            "square"
+            "sm",
+            "md",
+            "lg"
           ]
         },
-        "children": {
-          "type": "React.ReactNode",
+        "stopOnEscape": {
+          "type": "boolean | undefined",
           "required": false,
-          "origin": "own"
+          "origin": "own",
+          "description": "Bind Escape, at the document, to stop the run.\n\nOff by default and deliberately so: Escape already means \"dismiss the\nthing in front of me\" to every modal, popover and menu in this system, and\na document-level handler would cancel a background run when the user meant\nto close a dialog. Turn it on only where the run IS the foreground task."
         }
       },
       "propCounts": {
-        "own": 4,
+        "own": 6,
         "aria": 0,
-        "dom": 277,
+        "dom": 286,
         "other": 0
       }
     },
-    "Badge": {
-      "name": "Badge",
-      "source": "src/components/Badge.tsx",
-      "propsType": "BadgeProps",
-      "description": "Badge is presentational — no role, no interaction. React Aria has nothing to\noffer here, so this is a plain span rather than a hook wrapper for its own\nsake.\n\nIt carries no `status` or `alert` role on purpose: a badge is a label on\nsomething else, and announcing it as a live region would interrupt screen\nreader users on every render. Wrap it yourself if the value genuinely changes\nand matters.",
-      "import": "import { Badge } from 'ionbase-ui';",
+    "Alert": {
+      "name": "Alert",
+      "source": "src/components/Alert.tsx",
+      "propsType": "AlertProps",
+      "description": "Alert — Figma `Alert` (812:1902).\n\n`Intent` x `Emphasis` x `Layout`, with the parts as props rather than\nvariants. Intents match `Badge` exactly, so a status mapped to one can be\npassed to the other.\n\nROLE IS CHOSEN BY INTENT, NOT PASSED IN. `error` and `warning` render\n`role=\"alert\"`, which interrupts a screen reader; the rest render\n`role=\"status\"`, which waits for a pause. Getting this backwards is the\ncommon failure — a page of `role=\"alert\"` status messages talks over the\nuser, and an error announced as a status is missed.\n\nThe icon is decorative: it repeats what the intent's colour and copy already\nsay, so it is `aria-hidden` and the live region carries the text alone.",
+      "import": "import { Alert } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A small, non-interactive label that classifies the thing next to it. Presentational — no role, no live region.",
+      "since": "0.13.1",
+      "summary": "A persistent, in-page status message. Intent picks the ARIA role for you.",
       "useWhen": [
-        "labelling a record's status, type, count or category",
-        "the label belongs to something else on the page and is read as part of it"
+        "the message belongs to the page and should stay until the condition clears",
+        "form-level validation summaries, permission notices, degraded-state banners"
       ],
       "useInstead": [
         {
-          "when": "the message is a standalone statement the user must read",
-          "use": "Alert",
-          "why": "Badge carries no role and is not announced on its own"
+          "when": "the message is transient and self-dismissing",
+          "use": "Toast",
+          "why": "an Alert stays in the layout; a Toast does not"
         },
         {
-          "when": "the label should be clickable — a filter chip, a removable tag",
-          "use": "Button",
-          "why": "Badge takes no focus and fires nothing"
+          "when": "it labels a value inline rather than telling the user something",
+          "use": "Badge",
+          "why": "Badge shares Alert's intent vocabulary exactly, so a status mapped to one passes to the other"
         }
       ],
       "variants": {
         "intent": {
-          "neutral": {
-            "use": "the default — a category with no judgement attached"
+          "error": {
+            "use": "something failed and the user must act",
+            "aria": "role=alert — interrupts the screen reader"
           },
-          "primary": {
-            "use": "brand emphasis: Beta, New, Pro"
+          "warning": {
+            "use": "something may fail or has degraded",
+            "aria": "role=alert — interrupts the screen reader"
           },
           "success": {
-            "use": "a terminal good state: Active, Paid, Passed"
-          },
-          "warning": {
-            "use": "needs attention but is not broken: Pending, Expiring"
-          },
-          "error": {
-            "use": "a failed or blocked state: Failed, Overdue, Rejected"
+            "use": "an operation completed",
+            "aria": "role=status"
           },
           "information": {
-            "use": "a neutral fact worth marking: Draft, Scheduled"
+            "use": "neutral context the user did not ask for",
+            "aria": "role=status"
+          },
+          "primary": {
+            "use": "product announcements and promotions",
+            "aria": "role=status"
+          },
+          "neutral": {
+            "use": "low-emphasis context",
+            "aria": "role=status"
+          }
+        },
+        "emphasis": {
+          "subtle": {
+            "use": "the default — tinted surface, readable in long pages"
+          },
+          "solid": {
+            "use": "reserve for a single high-stakes banner; it dominates the layout"
+          }
+        },
+        "layout": {
+          "inline": {
+            "use": "inside a form or card, in the flow of content"
+          },
+          "banner": {
+            "use": "full-bleed at the top of a page or region"
           }
-        }
-      },
-      "slots": {
-        "icon": {
-          "accepts": "Icon",
-          "note": "mutually exclusive with `dot` — `dot` wins and `icon` is dropped when both are set"
         }
       },
       "a11y": {
         "guarantees": [
-          "the dot marker is `aria-hidden`, so the badge announces its text only",
-          "no `status` or `alert` role, so a re-render never interrupts a screen reader"
+          "the role follows the intent — error and warning are role=alert, everything else role=status",
+          "the icon is aria-hidden, so the live region announces the text once and not the glyph"
+        ],
+        "requires": [
+          "`dismissLabel` when `onDismiss` is set and the surrounding copy does not name the action"
         ],
         "notes": [
-          "If the value genuinely changes and the change matters, wrap the Badge in your own live region — the component will not do it for you."
+          "role=alert interrupts whatever the screen reader is saying; role=status waits for a pause. This is why the role is not a prop."
         ]
       },
       "antiPatterns": [
         {
-          "dont": "relying on intent colour alone to carry the meaning",
-          "why": "colour is not a label (WCAG 1.4.1); the text has to say Failed, not just be red"
+          "dont": "using intent=\"error\" for a message that is merely informational",
+          "why": "error renders role=alert, which interrupts the screen reader. A page of interrupting status messages talks over the user."
         },
         {
-          "dont": "putting a Button or Link inside a Badge",
-          "why": "it renders a plain <span>; interactive content there has no affordance and no focus style"
+          "dont": "using intent=\"information\" for a genuine failure",
+          "why": "role=status waits for a pause, so a real error can be missed entirely"
+        },
+        {
+          "dont": "rendering an Alert conditionally for a transient confirmation",
+          "do": "useToast",
+          "why": "an Alert that appears and disappears shifts the layout under the user"
         }
       ],
-      "stylesheet": "src/styles/badge.css",
+      "stylesheet": "src/styles/alert.css",
       "tokens": [
         "--border-default",
+        "--border-error-strong",
         "--border-error-subtle",
+        "--border-information-strong",
         "--border-information-subtle",
+        "--border-inverse",
+        "--border-primary-strong",
         "--border-primary-subtle",
+        "--border-success-strong",
         "--border-success-subtle",
+        "--border-warning-strong",
         "--border-warning-subtle",
         "--border-width-default",
+        "--border-width-thick",
         "--font-family-sans",
         "--font-weight-medium",
+        "--font-weight-regular",
         "--icon-error",
         "--icon-information",
+        "--icon-on-color",
         "--icon-primary",
         "--icon-secondary",
+        "--icon-size-md",
         "--icon-success",
         "--icon-warning",
-        "--radius-full",
-        "--spacing-2",
-        "--spacing-4",
-        "--spacing-6",
+        "--ion-alert-border",
+        "--ion-alert-icon",
+        "--ion-alert-surface",
+        "--ion-alert-text",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-md",
+        "--radius-sm",
+        "--ring-focus",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-32",
         "--spacing-8",
+        "--surface-error",
         "--surface-error-subtle",
+        "--surface-hover",
+        "--surface-information",
         "--surface-information-subtle",
+        "--surface-inverse",
         "--surface-muted",
+        "--surface-primary",
         "--surface-primary-subtle",
+        "--surface-success",
         "--surface-success-subtle",
+        "--surface-warning",
         "--surface-warning-subtle",
         "--text-error",
         "--text-information",
         "--text-link",
+        "--text-on-color",
         "--text-secondary",
         "--text-success",
         "--text-warning",
-        "--type-caption",
-        "--type-caption-line-height"
+        "--type-body",
+        "--type-body-line-height"
       ],
       "props": {
         "intent": {
-          "type": "BadgeIntent | undefined",
+          "type": "AlertIntent | undefined",
           "required": false,
           "origin": "own",
-          "description": "Matches the Figma `Intent` variant.",
+          "description": "Matches the Figma `Intent` variant. Same vocabulary as `Badge`.",
           "values": [
             "neutral",
             "primary",
@@ -677,743 +562,1895 @@
             "warning",
             "error",
             "information"
-          ]
+          ],
+          "default": "information"
         },
-        "dot": {
+        "emphasis": {
+          "type": "AlertEmphasis | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Emphasis` variant.",
+          "values": [
+            "subtle",
+            "solid"
+          ],
+          "default": "subtle"
+        },
+        "layout": {
+          "type": "AlertLayout | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Layout` variant.",
+          "values": [
+            "inline",
+            "banner"
+          ],
+          "default": "inline"
+        },
+        "title": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Optional heading above the message."
+        },
+        "hideIcon": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Show the leading dot marker. Figma's `Show Dot` boolean.\nThe dot inherits the intent's foreground colour, so it needs no prop."
+          "description": "Hide the leading icon. Shown by default."
         },
         "icon": {
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Leading icon. Figma's `Show Icon` + `Icon` swap. Mutually exclusive with `dot`."
+          "description": "Replace the intent's glyph."
+        },
+        "actions": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Action buttons, rendered under the message."
+        },
+        "onDismiss": {
+          "type": "(() => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Called when the dismiss button is pressed. Omit for no dismiss button."
+        },
+        "dismissLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible name for the dismiss button.",
+          "default": "Dismiss"
         },
         "children": {
           "type": "React.ReactNode",
           "required": false,
-          "origin": "own"
+          "origin": "own",
+          "description": "The message."
         }
       },
       "propCounts": {
-        "own": 4,
+        "own": 10,
         "aria": 0,
-        "dom": 277,
+        "dom": 276,
         "other": 0
       }
     },
-    "Button": {
-      "name": "Button",
-      "source": "src/components/Button.tsx",
-      "propsType": "ButtonProps",
-      "import": "import { Button } from 'ionbase-ui';",
+    "ApprovalGate": {
+      "name": "ApprovalGate",
+      "source": "src/components/ApprovalGate.tsx",
+      "propsType": "ApprovalGateProps",
+      "description": "ApprovalGate — a proposed action, held until a person decides.\n\nThe human-in-the-loop control. An agent proposes; this is where a person\napproves, rejects, or amends before anything happens. In regulated contexts\ndemonstrable human oversight is a compliance surface rather than a nicety,\nwhich is why this is a first-class component and not a Modal with two\nbuttons in it.\n\nIT ENFORCES NOTHING, AND SAYING SO IS THE POINT\n\nThis renders a decision. It does not gate execution — the caller does, by not\nacting until `onApprove` fires. A component that *looked* like it enforced a\npolicy would be the worst possible thing to ship here: teams would rely on a\nguarantee that lives entirely in their own call site. `risk` changes emphasis\nand nothing else, for the same reason.\n\nNOT A MODAL, DELIBERATELY\n\nA modal steals focus and hides the page. But the page is the evidence: the\nuser needs the plan, the diff, the tool call and the context in front of them\nwhile deciding. This sits inline, keeps everything visible, and never\ntraps focus — an approval a user was rushed through is not oversight.\n\nNEITHER BUTTON IS FOCUSED ON MOUNT. Autofocusing approve turns a decision\ninto an Enter keypress on a page the user has not read. Focus is moved to the\nregion's heading instead, so a screen-reader user lands on what is being\nasked rather than on the answer.\n\nTHE RESOLVED STATES ARE NOT DECORATION. `approved`, `rejected` and `expired`\nreplace the actions with what happened, so the record of the decision stays\non the page. `expired` exists because an approval request that nobody answers\nis the common real outcome, and a gate that sits pending for ever is\nindistinguishable from one that is broken.",
+      "import": "import { ApprovalGate } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Triggers an action in place. Never navigates.",
+      "summary": "A proposed action held until a person approves, rejects or amends it. It renders the decision; it does not enforce it.",
       "useWhen": [
-        "the interaction performs an action — submit, save, delete, open a dialog",
-        "the result stays on the current page"
+        "an agent proposes something with consequences — spending, sending, deleting, deploying, changing permissions",
+        "a regulated or audited process needs demonstrable human oversight at a specific point",
+        "the proposal is worth showing in full, in context, before it runs"
       ],
       "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 action is already happening and needs stopping",
+          "use": "AgentStop"
         },
         {
-          "when": "it toggles a persistent boolean setting",
-          "use": "Toggle",
-          "why": "a toggle announces its on/off state; a button announces only its name"
+          "when": "a person initiated the action themselves and only needs to confirm it",
+          "use": "Modal",
+          "why": "confirming your own request is a dialog; reviewing something proposed for you is a decision"
+        },
+        {
+          "when": "you are reporting what happened rather than asking",
+          "use": "Alert"
         }
       ],
       "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"
+        "risk": {
+          "low": {
+            "use": "reversible and cheap — a draft, a local edit. Neutral surface"
           },
-          "tertiary": {
-            "use": "low-emphasis actions — Cancel, Back, inline row actions"
-          },
-          "destructive": {
-            "use": "irreversible actions",
-            "requires": "a Modal confirmation before the action runs"
+          "medium": {
+            "use": "the default. Real but recoverable consequences"
           },
-          "success": {
-            "use": "confirms the end of a flow. Rarely the right answer — prefer primary-brand."
+          "high": {
+            "use": "spending, sending externally, deleting, granting access. Warning surface, deliberately not error"
           }
         },
-        "size": {
-          "sm": {
-            "use": "table rows, toolbars, dense layouts"
+        "status": {
+          "pending": {
+            "use": "the default, and the only state with actions"
           },
-          "md": {
-            "use": "the default; forms and page-level actions"
+          "approved": {
+            "use": "resolved — the actions are replaced by the record"
           },
-          "lg": {
-            "use": "prominent standalone actions"
+          "rejected": {
+            "use": "resolved, declined"
           },
-          "xl": {
-            "use": "marketing and empty-state calls to action"
+          "expired": {
+            "use": "nobody answered. The common real outcome, and the reason a gate cannot sit pending for ever"
           }
         }
       },
       "slots": {
-        "startIcon": {
-          "accepts": "Icon",
-          "note": "omit Icon's `label` — the Button's own text already names it, and a labelled icon is announced twice"
+        "title": {
+          "accepts": "text",
+          "note": "required, and the region's accessible name. Name the action and its object — \"Delete 14 projects\", never \"Confirm action\""
         },
-        "endIcon": {
-          "accepts": "Icon",
-          "note": "same as startIcon"
+        "children": {
+          "accepts": "any",
+          "note": "the evidence: the plan, the diff, the tool call. This is what the person is deciding about"
+        },
+        "resolution": {
+          "accepts": "text",
+          "note": "shown in place of the actions once resolved; defaults to the status"
         }
       },
       "a11y": {
-        "role": "button",
+        "role": "region, named by its title",
         "guarantees": [
-          "the focus ring appears for keyboard focus and not for a mouse click",
-          "hover does not latch on touch devices"
+          "neither button is focused on mount — autofocusing approve turns a decision into an Enter keypress on an unread page",
+          "the title is programmatically focusable, so the caller can move focus to the question rather than to an answer",
+          "reject precedes approve in the DOM, so a keyboard reaches the safe answer first",
+          "resolution is announced once through a polite live region",
+          "focus is never trapped: an approval a user was rushed through is not oversight"
         ],
         "requires": [
-          "an accessible name — `children`, or `aria-label` when the button is icon-only"
+          "not acting until `onApprove` fires — this component gates nothing on its own",
+          "a `title` that names the action and its object"
+        ],
+        "notes": [
+          "`risk` changes emphasis and nothing else. It does not add confirmation, does not disable anything, and must never be read as a policy the component enforces."
         ]
       },
       "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": "treating the gate as the enforcement point",
+          "why": "it renders a decision. If your code acts before `onApprove`, there is no gate — only a picture of one"
         },
         {
-          "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": "putting it in a Modal",
+          "why": "the page is the evidence; hiding it to ask about it removes what the decision needs"
         },
         {
-          "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": "autofocusing the approve button",
+          "why": "Enter on an unread page is not oversight, and it is exactly what an audit will look for"
         },
         {
-          "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": "an approve-only gate with no reject",
+          "why": "a decision with one answer is a notification wearing a 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."
+          "dont": "`onEdit` when the proposal cannot actually be amended",
+          "why": "an edit button that discards the edit is worse than no edit button"
+        },
+        {
+          "dont": "leaving gates pending indefinitely",
+          "do": "the `expired` status",
+          "why": "a gate nobody answered is indistinguishable from one that is broken"
         }
       ],
-      "deprecated": [
-        {
-          "prop": "disabled",
-          "replacement": "isDisabled",
-          "note": "still type-checks, so this will not fail loudly"
-        }
-      ],
-      "stylesheet": "src/styles/button.css",
+      "stylesheet": "src/styles/approval-gate.css",
       "tokens": [
+        "--border-default",
         "--border-disabled",
-        "--border-error-strong",
-        "--border-inverse",
-        "--border-primary",
-        "--border-primary-strong",
-        "--border-primary-subtle",
+        "--border-focus",
+        "--border-information",
         "--border-strong",
-        "--border-stronger",
-        "--border-success-strong",
+        "--border-success",
+        "--border-warning-strong",
         "--border-width-default",
+        "--border-width-thick",
+        "--border-width-thicker",
         "--font-family-sans",
         "--font-weight-medium",
-        "--icon-size-lg",
+        "--font-weight-semibold",
+        "--icon-information",
+        "--icon-secondary",
         "--icon-size-md",
-        "--icon-size-xs",
-        "--ion-button-elevation",
-        "--ion-button-font-size",
-        "--ion-button-gap",
-        "--ion-button-icon-size",
-        "--ion-button-inset-flush",
-        "--ion-button-inset-lifted",
-        "--ion-button-line-height",
-        "--ion-button-padding-x",
-        "--ion-button-pressed",
-        "--ion-button-raised",
-        "--ion-button-ring",
-        "--ion-button-size",
+        "--icon-success",
+        "--icon-tertiary",
+        "--icon-warning",
+        "--ion-approval-accent",
+        "--ion-approval-border",
+        "--ion-approval-icon",
+        "--ion-approval-surface",
         "--ion-duration-base",
-        "--ion-duration-fast",
         "--ion-ease-out",
-        "--ion-shadow-focus-md",
-        "--ion-shadow-inset-flush-lg",
-        "--ion-shadow-inset-flush-sm",
-        "--ion-shadow-inset-flush-xs",
-        "--ion-shadow-inset-lifted-lg",
-        "--ion-shadow-inset-lifted-sm",
-        "--ion-shadow-inset-lifted-xs",
-        "--ion-shadow-none",
-        "--ion-shadow-raised-lifted-lg",
-        "--ion-shadow-raised-lifted-sm",
-        "--ion-shadow-raised-lifted-xs",
         "--radius-md",
+        "--radius-sm",
+        "--radius-xs",
         "--spacing-12",
         "--spacing-16",
-        "--spacing-20",
-        "--spacing-24",
         "--spacing-32",
-        "--spacing-40",
-        "--spacing-48",
-        "--spacing-56",
-        "--spacing-6",
+        "--spacing-4",
         "--spacing-8",
         "--surface-default",
         "--surface-disabled",
-        "--surface-error",
-        "--surface-error-hover",
-        "--surface-error-pressed",
-        "--surface-inverse",
-        "--surface-inverse-subtle",
+        "--surface-hover",
+        "--surface-information-subtle",
         "--surface-muted",
-        "--surface-page",
         "--surface-primary",
         "--surface-primary-hover",
-        "--surface-primary-pressed",
-        "--surface-primary-subtle",
-        "--surface-primary-subtle-hover",
-        "--surface-primary-tint",
-        "--surface-success",
-        "--surface-success-hover",
-        "--surface-success-pressed",
+        "--surface-warning-subtle",
+        "--text-default",
         "--text-disabled",
+        "--text-information",
         "--text-on-color",
-        "--text-primary",
         "--text-secondary",
+        "--text-success",
+        "--text-warning",
         "--type-body",
-        "--type-body-lg",
-        "--type-body-lg-line-height",
         "--type-body-line-height",
-        "--type-body-md",
-        "--type-body-md-line-height",
         "--type-body-sm",
         "--type-body-sm-line-height"
       ],
       "props": {
-        "variant": {
-          "type": "\"success\" | \"primary-brand\" | \"primary-neutral\" | \"primary-soft\" | \"secondary\" | \"tertiary\" | \"destructive\" | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "The visual style variant of the button.",
-          "values": [
-            "success",
-            "primary-brand",
-            "primary-neutral",
-            "primary-soft",
-            "secondary",
-            "tertiary",
-            "destructive"
-          ],
-          "default": "primary-brand"
-        },
-        "size": {
-          "type": "\"sm\" | \"md\" | \"lg\" | \"xl\" | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "The size of the button.",
-          "values": [
-            "sm",
-            "md",
-            "lg",
-            "xl"
-          ],
-          "default": "md"
-        },
-        "startIcon": {
-          "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "Optional icon to render before the label."
-        },
-        "endIcon": {
+        "title": {
           "type": "React.ReactNode",
-          "required": false,
-          "origin": "own",
-          "description": "Optional icon to render after the label."
-        },
-        "className": {
-          "type": "string | undefined",
-          "required": false,
+          "required": true,
           "origin": "own",
-          "description": "Additional CSS class names."
+          "description": "What is being approved, stated as the action and its object — \"Delete 14\nprojects\", not \"Confirm action\". Required: it is the region's accessible\nname, and a decision the user cannot name is not a decision."
         },
         "children": {
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Children element to render inside the button."
+          "description": "Why it stopped here, and what happens on approval."
         },
-        "disabled": {
-          "type": "boolean | undefined",
+        "risk": {
+          "type": "ApprovalGateRisk | undefined",
           "required": false,
           "origin": "own",
-          "tags": {
-            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-          }
-        },
-        "isDisabled": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Whether the button is disabled."
-        },
-        "onPress": {
-          "type": "((e: PressEvent) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the press is released over the target."
-        },
-        "onPressStart": {
-          "type": "((e: PressEvent) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when a press interaction starts."
-        },
-        "onPressEnd": {
-          "type": "((e: PressEvent) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when a press interaction ends, either\nover the target or when the pointer leaves the target."
-        },
-        "onPressChange": {
-          "type": "((isPressed: boolean) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the press state changes."
-        },
-        "onPressUp": {
-          "type": "((e: PressEvent) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when a press is released over the target, regardless of\nwhether it started on the target or not."
-        },
-        "onClick": {
-          "type": "((e: MouseEvent<FocusableElement>) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress`\nprovided for compatibility with other libraries. `onPress` provides\nadditional event details for non-mouse interactions."
-        },
-        "autoFocus": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Whether the element should receive focus on render."
-        },
-        "onFocus": {
-          "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the element receives focus."
+          "description": "How much is at stake. Drives emphasis only — it does NOT change what the\ncomponent enforces, because the component enforces nothing.",
+          "values": [
+            "low",
+            "medium",
+            "high"
+          ]
         },
-        "onBlur": {
-          "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+        "status": {
+          "type": "ApprovalGateStatus | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the element loses focus."
+          "origin": "own",
+          "description": "Where the decision has got to. `pending` is the only state with buttons.",
+          "values": [
+            "pending",
+            "approved",
+            "rejected",
+            "expired"
+          ]
         },
-        "onFocusChange": {
-          "type": "((isFocused: boolean) => void) | undefined",
+        "onApprove": {
+          "type": "(() => void) | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when the element's focus status changes."
+          "origin": "own"
         },
-        "onKeyDown": {
-          "type": "((e: KeyboardEvent) => void) | undefined",
+        "onReject": {
+          "type": "(() => void) | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when a key is pressed."
+          "origin": "own"
         },
-        "onKeyUp": {
-          "type": "((e: KeyboardEvent) => void) | undefined",
+        "onEdit": {
+          "type": "(() => void) | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Handler that is called when a key is released."
+          "origin": "own",
+          "description": "Offer \"edit\" as a third way out. Omit it when the proposal cannot be\namended — an approve/reject pair the user cannot influence is honest;\nan edit button that discards their edit is not."
         },
-        "href": {
+        "approveLabel": {
           "type": "string | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "A URL to link to if elementType=\"a\"."
+          "origin": "own"
         },
-        "target": {
+        "rejectLabel": {
           "type": "string | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "The target window for the link."
+          "origin": "own"
         },
-        "rel": {
+        "editLabel": {
           "type": "string | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
-        },
-        "elementType": {
-          "type": "JSXElementConstructor<any> | \"button\" | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.",
-          "tags": {
-            "default": "'button'"
-          }
-        },
-        "aria-disabled": {
-          "type": "boolean | \"true\" | \"false\" | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Indicates whether the element is disabled to users of assistive technology."
-        },
-        "aria-expanded": {
-          "type": "boolean | \"true\" | \"false\" | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Indicates whether the element, or another grouping element it controls, is currently expanded\nor collapsed."
+          "origin": "own"
         },
-        "aria-haspopup": {
-          "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+        "isSubmitting": {
+          "type": "boolean | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+          "origin": "own",
+          "description": "A decision is in flight. Both actions disable; neither disappears."
         },
-        "aria-controls": {
-          "type": "string | undefined",
+        "resolution": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in place of the actions once the decision is made."
+        }
+      },
+      "propCounts": {
+        "own": 12,
+        "aria": 0,
+        "dom": 275,
+        "other": 0
+      }
+    },
+    "Avatar": {
+      "name": "Avatar",
+      "source": "src/components/Avatar.tsx",
+      "propsType": "AvatarProps",
+      "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
+      "import": "import { Avatar } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A person or entity marker. Content is chosen by precedence — image, then initials, then icon — not by a type prop.",
+      "useWhen": [
+        "identifying who owns, authored or is assigned to something",
+        "a table cell, menu row or header needs a compact identity marker beside a name"
+      ],
+      "useInstead": [
+        {
+          "when": "the thing being marked is a status, count or category rather than a person",
+          "use": "Badge"
+        },
+        {
+          "when": "you only need a decorative graphic with no identity behind it",
+          "use": "Icon"
+        }
+      ],
+      "variants": {
+        "size": {
+          "mini": {
+            "use": "24px — inline beside body text, dense table rows"
+          },
+          "sm": {
+            "use": "32px — menu rows, compact lists"
+          },
+          "md": {
+            "use": "the default, 40px"
+          },
+          "lg": {
+            "use": "48px — profile headers and detail pages"
+          }
+        },
+        "shape": {
+          "circle": {
+            "use": "the default — people"
+          },
+          "square": {
+            "use": "organisations, projects, workspaces and other non-human entities"
+          }
+        }
+      },
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "the last fallback — rendered only when there is neither `src` nor `initials`"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "`alt` falls back to `initials`, so the avatar is never announced as an unlabelled image",
+          "a `src` that fails to load falls through to initials, then icon — never the browser's broken-image glyph"
+        ],
+        "requires": [
+          "`alt` describing the person, not the picture — \"Ada Lovelace\", not \"profile photo\""
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "passing `src` without `initials`",
+          "why": "a 404 leaves the fallback empty; initials are what make the failure invisible"
+        },
+        {
+          "dont": "using Avatar as a button",
+          "do": "put the Avatar inside a Button or Link",
+          "why": "Avatar renders a <span> with no role and takes no focus"
+        }
+      ],
+      "stylesheet": "src/styles/avatar.css",
+      "tokens": [
+        "--border-strong",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-size-2xs",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-sm",
+        "--icon-tertiary",
+        "--ion-avatar-font-size",
+        "--ion-avatar-group-overlap",
+        "--ion-avatar-icon",
+        "--ion-avatar-line-height",
+        "--ion-avatar-radius",
+        "--ion-avatar-size",
+        "--radius-full",
+        "--radius-md",
+        "--radius-sm",
+        "--radius-xs",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-40",
+        "--spacing-48",
+        "--surface-muted",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height",
+        "--type-h5",
+        "--type-h5-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "AvatarSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "mini"
+          ]
+        },
+        "shape": {
+          "type": "AvatarShape | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Shape` variant.",
+          "values": [
+            "circle",
+            "square"
+          ]
+        },
+        "src": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Image source. Figma's `Type=Image`."
+        },
+        "alt": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Describes the person, not the picture. Falls back to `initials` so the\navatar is never announced as an unlabelled image."
+        },
+        "initials": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Type=Character`. Rendered when there is no `src`, or when `src`\nfails to load."
+        },
+        "icon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Type=Icon`. Rendered when there is neither `src` nor `initials`."
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 278,
+        "other": 0
+      }
+    },
+    "AvatarGroup": {
+      "name": "AvatarGroup",
+      "source": "src/components/Avatar.tsx",
+      "propsType": "AvatarGroupProps",
+      "description": "AvatarGroup overlaps its children by a quarter of the avatar size, matching\nFigma's -6 / -8 / -10 / -12 gaps at Mini / Small / Medium / Large.\n\nGroup defaults fill in `size` / `shape` only when a child Avatar has not set\nthem itself — an explicit child prop wins. Non-Avatar children are left\nalone so `size`/`shape` are never pushed onto arbitrary DOM nodes.\n\nChildren render in source order because that is Figma's stacking: each avatar\npaints over the one before it, so the `+N` overflow ends up on top. Later\nsiblings paint later, so this needs no z-index.",
+      "import": "import { AvatarGroup } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Overlapping Avatars with a `+N` overflow, for showing several people in one row's width.",
+      "useWhen": [
+        "several people share one thing — assignees, participants, collaborators",
+        "the exact list matters less than the fact that there are several"
+      ],
+      "useInstead": [
+        {
+          "when": "each person needs their own name, role or action visible",
+          "use": "Table",
+          "why": "an overlapping stack hides everything but the picture"
+        }
+      ],
+      "variants": {
+        "size": {
+          "mini": {
+            "use": "24px — inline beside body text, dense table rows"
+          },
+          "sm": {
+            "use": "32px — menu rows, compact lists"
+          },
+          "md": {
+            "use": "the default, 40px"
+          },
+          "lg": {
+            "use": "48px — profile headers and detail pages"
+          }
+        },
+        "shape": {
+          "circle": {
+            "use": "the default — people"
+          },
+          "square": {
+            "use": "organisations, projects, workspaces"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "Avatar",
+          "note": "group `size`/`shape` fill in only where a child has not set its own; a child's explicit prop wins. Non-Avatar children are left untouched."
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`alt` on every child Avatar — the overflow avatar is the only one the group names for you"
+        ],
+        "notes": [
+          "Children paint in source order, so the `+N` overflow lands on top without any z-index."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "omitting `max` on an unbounded list",
+          "why": "twenty overlapping avatars is not a summary; it is a smear"
+        }
+      ],
+      "stylesheet": "src/styles/avatar.css",
+      "tokens": [
+        "--border-strong",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-size-2xs",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-sm",
+        "--icon-tertiary",
+        "--ion-avatar-font-size",
+        "--ion-avatar-group-overlap",
+        "--ion-avatar-icon",
+        "--ion-avatar-line-height",
+        "--ion-avatar-radius",
+        "--ion-avatar-size",
+        "--radius-full",
+        "--radius-md",
+        "--radius-sm",
+        "--radius-xs",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-40",
+        "--spacing-48",
+        "--surface-muted",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height",
+        "--type-h5",
+        "--type-h5-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "AvatarSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "mini"
+          ]
+        },
+        "max": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Cap on avatars shown; the remainder becomes a `+N` overflow avatar."
+        },
+        "shape": {
+          "type": "AvatarShape | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "circle",
+            "square"
+          ]
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "Badge": {
+      "name": "Badge",
+      "source": "src/components/Badge.tsx",
+      "propsType": "BadgeProps",
+      "description": "Badge is presentational — no role, no interaction. React Aria has nothing to\noffer here, so this is a plain span rather than a hook wrapper for its own\nsake.\n\nIt carries no `status` or `alert` role on purpose: a badge is a label on\nsomething else, and announcing it as a live region would interrupt screen\nreader users on every render. Wrap it yourself if the value genuinely changes\nand matters.",
+      "import": "import { Badge } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A small, non-interactive label that classifies the thing next to it. Presentational — no role, no live region.",
+      "useWhen": [
+        "labelling a record's status, type, count or category",
+        "the label belongs to something else on the page and is read as part of it"
+      ],
+      "useInstead": [
+        {
+          "when": "the message is a standalone statement the user must read",
+          "use": "Alert",
+          "why": "Badge carries no role and is not announced on its own"
+        },
+        {
+          "when": "the label should be clickable — a filter chip, a removable tag",
+          "use": "Button",
+          "why": "Badge takes no focus and fires nothing"
+        }
+      ],
+      "variants": {
+        "intent": {
+          "neutral": {
+            "use": "the default — a category with no judgement attached"
+          },
+          "primary": {
+            "use": "brand emphasis: Beta, New, Pro"
+          },
+          "success": {
+            "use": "a terminal good state: Active, Paid, Passed"
+          },
+          "warning": {
+            "use": "needs attention but is not broken: Pending, Expiring"
+          },
+          "error": {
+            "use": "a failed or blocked state: Failed, Overdue, Rejected"
+          },
+          "information": {
+            "use": "a neutral fact worth marking: Draft, Scheduled"
+          }
+        }
+      },
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "mutually exclusive with `dot` — `dot` wins and `icon` is dropped when both are set"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the dot marker is `aria-hidden`, so the badge announces its text only",
+          "no `status` or `alert` role, so a re-render never interrupts a screen reader"
+        ],
+        "notes": [
+          "If the value genuinely changes and the change matters, wrap the Badge in your own live region — the component will not do it for you."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "relying on intent colour alone to carry the meaning",
+          "why": "colour is not a label (WCAG 1.4.1); the text has to say Failed, not just be red"
+        },
+        {
+          "dont": "putting a Button or Link inside a Badge",
+          "why": "it renders a plain <span>; interactive content there has no affordance and no focus style"
+        }
+      ],
+      "stylesheet": "src/styles/badge.css",
+      "tokens": [
+        "--border-default",
+        "--border-error-subtle",
+        "--border-information-subtle",
+        "--border-primary-subtle",
+        "--border-success-subtle",
+        "--border-warning-subtle",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-error",
+        "--icon-information",
+        "--icon-primary",
+        "--icon-secondary",
+        "--icon-success",
+        "--icon-warning",
+        "--radius-full",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-error-subtle",
+        "--surface-information-subtle",
+        "--surface-muted",
+        "--surface-primary-subtle",
+        "--surface-success-subtle",
+        "--surface-warning-subtle",
+        "--text-error",
+        "--text-information",
+        "--text-link",
+        "--text-secondary",
+        "--text-success",
+        "--text-warning",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "intent": {
+          "type": "BadgeIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Intent` variant.",
+          "values": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "error",
+            "information"
+          ]
+        },
+        "dot": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Show the leading dot marker. Figma's `Show Dot` boolean.\nThe dot inherits the intent's foreground colour, so it needs no prop."
+        },
+        "icon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Leading icon. Figma's `Show Icon` + `Icon` swap. Mutually exclusive with `dot`."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "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",
+        "--border-primary-strong",
+        "--border-primary-subtle",
+        "--border-strong",
+        "--border-stronger",
+        "--border-success-strong",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-xs",
+        "--ion-button-elevation",
+        "--ion-button-font-size",
+        "--ion-button-gap",
+        "--ion-button-icon-size",
+        "--ion-button-inset-flush",
+        "--ion-button-inset-lifted",
+        "--ion-button-line-height",
+        "--ion-button-padding-x",
+        "--ion-button-pressed",
+        "--ion-button-raised",
+        "--ion-button-ring",
+        "--ion-button-size",
+        "--ion-duration-base",
+        "--ion-duration-fast",
+        "--ion-ease-out",
+        "--ion-shadow-focus-md",
+        "--ion-shadow-inset-flush-lg",
+        "--ion-shadow-inset-flush-sm",
+        "--ion-shadow-inset-flush-xs",
+        "--ion-shadow-inset-lifted-lg",
+        "--ion-shadow-inset-lifted-sm",
+        "--ion-shadow-inset-lifted-xs",
+        "--ion-shadow-none",
+        "--ion-shadow-raised-lifted-lg",
+        "--ion-shadow-raised-lifted-sm",
+        "--ion-shadow-raised-lifted-xs",
+        "--radius-md",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-40",
+        "--spacing-48",
+        "--spacing-56",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-error",
+        "--surface-error-hover",
+        "--surface-error-pressed",
+        "--surface-inverse",
+        "--surface-inverse-subtle",
+        "--surface-muted",
+        "--surface-page",
+        "--surface-primary",
+        "--surface-primary-hover",
+        "--surface-primary-pressed",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--surface-primary-tint",
+        "--surface-success",
+        "--surface-success-hover",
+        "--surface-success-pressed",
+        "--text-disabled",
+        "--text-on-color",
+        "--text-primary",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-lg",
+        "--type-body-lg-line-height",
+        "--type-body-line-height",
+        "--type-body-md",
+        "--type-body-md-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "variant": {
+          "type": "\"success\" | \"primary-brand\" | \"primary-neutral\" | \"primary-soft\" | \"secondary\" | \"tertiary\" | \"destructive\" | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The visual style variant of the button.",
+          "values": [
+            "success",
+            "primary-brand",
+            "primary-neutral",
+            "primary-soft",
+            "secondary",
+            "tertiary",
+            "destructive"
+          ],
+          "default": "primary-brand"
+        },
+        "size": {
+          "type": "\"sm\" | \"md\" | \"lg\" | \"xl\" | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The size of the button.",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "xl"
+          ],
+          "default": "md"
+        },
+        "startIcon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Optional icon to render before the label."
+        },
+        "endIcon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Optional icon to render after the label."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Additional CSS class names."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Children element to render inside the button."
+        },
+        "disabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+          }
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the button is disabled."
+        },
+        "onPress": {
+          "type": "((e: PressEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the press is released over the target."
+        },
+        "onPressStart": {
+          "type": "((e: PressEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a press interaction starts."
+        },
+        "onPressEnd": {
+          "type": "((e: PressEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a press interaction ends, either\nover the target or when the pointer leaves the target."
+        },
+        "onPressChange": {
+          "type": "((isPressed: boolean) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the press state changes."
+        },
+        "onPressUp": {
+          "type": "((e: PressEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a press is released over the target, regardless of\nwhether it started on the target or not."
+        },
+        "onClick": {
+          "type": "((e: MouseEvent<FocusableElement>) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress`\nprovided for compatibility with other libraries. `onPress` provides\nadditional event details for non-mouse interactions."
+        },
+        "autoFocus": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the element should receive focus on render."
+        },
+        "onFocus": {
+          "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element receives focus."
+        },
+        "onBlur": {
+          "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element loses focus."
+        },
+        "onFocusChange": {
+          "type": "((isFocused: boolean) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element's focus status changes."
+        },
+        "onKeyDown": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a key is pressed."
+        },
+        "onKeyUp": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a key is released."
+        },
+        "href": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A URL to link to if elementType=\"a\"."
+        },
+        "target": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The target window for the link."
+        },
+        "rel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
+        },
+        "elementType": {
+          "type": "JSXElementConstructor<any> | \"button\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.",
+          "tags": {
+            "default": "'button'"
+          }
+        },
+        "aria-disabled": {
+          "type": "boolean | \"true\" | \"false\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates whether the element is disabled to users of assistive technology."
+        },
+        "aria-expanded": {
+          "type": "boolean | \"true\" | \"false\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates whether the element, or another grouping element it controls, is currently expanded\nor collapsed."
+        },
+        "aria-haspopup": {
+          "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+        },
+        "aria-controls": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+        },
+        "aria-pressed": {
+          "type": "boolean | \"true\" | \"false\" | \"mixed\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates the current \"pressed\" state of toggle buttons."
+        },
+        "aria-current": {
+          "type": "boolean | \"true\" | \"false\" | \"page\" | \"step\" | \"location\" | \"date\" | \"time\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates whether this element represents the current item within a container or set of related\nelements."
+        },
+        "type": {
+          "type": "\"button\" | \"submit\" | \"reset\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The behavior of the button when used in an HTML form.",
+          "values": [
+            "button",
+            "submit",
+            "reset"
+          ],
+          "tags": {
+            "default": "'button'"
+          }
+        },
+        "preventFocusOnPress": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to prevent focus from moving to the button when pressing it.\n\nCaution, this can make the button inaccessible and should only be used when alternative\nkeyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's\nincrement/decrement control."
+        },
+        "form": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The `<form>` element to associate the button 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/button#form)."
+        },
+        "formAction": {
+          "type": "string | ((formData: FormData) => void | Promise<void>) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The URL that processes the information submitted by the button.\nOverrides the action attribute of the button's form owner."
+        },
+        "formEncType": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates how to encode the form data that is submitted."
+        },
+        "formMethod": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates the HTTP method used to submit the form."
+        },
+        "formNoValidate": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates that the form is not to be validated when it is submitted."
+        },
+        "formTarget": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Overrides the target attribute of the button's form owner."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Submitted as a pair with the button's value as part of the form data."
+        },
+        "value": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The value associated with the button's name when it's submitted with the form data."
+        },
+        "excludeFromTabOrder": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+        },
+        "aria-label": {
+          "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+          "description": "Defines a string value that labels the current element."
         },
-        "aria-pressed": {
-          "type": "boolean | \"true\" | \"false\" | \"mixed\" | undefined",
+        "aria-labelledby": {
+          "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "Indicates the current \"pressed\" state of toggle buttons."
+          "description": "Identifies the element (or elements) that labels the current element."
         },
-        "aria-current": {
-          "type": "boolean | \"true\" | \"false\" | \"page\" | \"step\" | \"location\" | \"date\" | \"time\" | undefined",
+        "aria-describedby": {
+          "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "Indicates whether this element represents the current item within a container or set of related\nelements."
+          "description": "Identifies the element (or elements) that describes the object."
         },
-        "type": {
-          "type": "\"button\" | \"submit\" | \"reset\" | undefined",
+        "aria-details": {
+          "type": "string | undefined",
           "required": false,
           "origin": "aria",
-          "description": "The behavior of the button when used in an HTML form.",
+          "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+        }
+      },
+      "propCounts": {
+        "own": 7,
+        "aria": 39,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "Checkbox": {
+      "name": "Checkbox",
+      "source": "src/components/Checkbox.tsx",
+      "propsType": "CheckboxProps",
+      "description": "Checkbox wraps a native `<input type=\"checkbox\">` and hides it.\n\nThe native input is kept rather than replaced by a div with `role=checkbox`\nbecause it brings form association, the indeterminate property, label\nclicking, and correct announcement — none of which are free to reimplement,\nand all of which are easy to get subtly wrong.\n\n`indeterminate` is the reason for the effect below: HTML has no\n`indeterminate` attribute, only a DOM property, so React cannot set it\ndeclaratively and it must be written after every render.",
+      "import": "import { Checkbox } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A native checkbox with the system's styling, supporting an indeterminate state.",
+      "useWhen": [
+        "a single on/off choice inside a form that is submitted",
+        "selecting rows in a Table",
+        "several independent options where more than one may be picked"
+      ],
+      "useInstead": [
+        {
+          "when": "the change takes effect immediately rather than on submit",
+          "use": "Toggle",
+          "why": "a switch reads as a setting taking effect now; a checkbox reads as a value being collected"
+        },
+        {
+          "when": "the options are mutually exclusive",
+          "use": "RadioGroup"
+        },
+        {
+          "when": "there are many options and space is tight",
+          "use": "Select"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms and table rows"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent single choices"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "where the checked state is a fact rather than an approval — bulk-selection columns"
+          },
+          "danger": {
+            "use": "consenting to something destructive or irreversible"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the visible label; omit for a bare box and supply `aria-label` instead"
+        }
+      },
+      "a11y": {
+        "role": "checkbox",
+        "guarantees": [
+          "a real <input type=\"checkbox\">, so form association, label clicking, and correct announcement come from the platform",
+          "`isIndeterminate` is written to the DOM property after every render — HTML has no such attribute, so React cannot set it declaratively"
+        ],
+        "requires": [
+          "`children`, or `aria-label` when the box has no visible label — a row-selection checkbox always needs one"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a bare checkbox with no `children` and no `aria-label`",
+          "why": "every row announces an unnamed checkbox"
+        },
+        {
+          "dont": "`isIndeterminate` on a leaf checkbox",
+          "why": "indeterminate means \"some of my children are checked\"; on a leaf it is a state the user can never reach"
+        },
+        {
+          "dont": "a div with `role=\"checkbox\"`",
+          "why": "form association, the indeterminate property and label clicking are not free to reimplement"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
+      "stylesheet": "src/styles/checkbox.css",
+      "tokens": [
+        "--border-disabled",
+        "--border-error-strong",
+        "--border-focus",
+        "--border-inverse",
+        "--border-primary-strong",
+        "--border-stronger",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--icon-disabled",
+        "--icon-on-color",
+        "--ion-checkbox-border",
+        "--ion-checkbox-fill",
+        "--ion-checkbox-font-size",
+        "--ion-checkbox-gap",
+        "--ion-checkbox-line-height",
+        "--ion-checkbox-mark",
+        "--ion-checkbox-radius",
+        "--ion-checkbox-raised",
+        "--ion-checkbox-size",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-shadow-raised-flush-lg",
+        "--ion-shadow-raised-flush-sm",
+        "--ion-shadow-raised-flush-xs",
+        "--radius-sm",
+        "--radius-xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-error",
+        "--surface-inverse",
+        "--surface-primary",
+        "--text-disabled",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "size": {
+          "type": "CheckboxSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
           "values": [
-            "button",
-            "submit",
-            "reset"
+            "sm",
+            "md",
+            "lg"
           ],
-          "tags": {
-            "default": "'button'"
-          }
+          "default": "md"
         },
-        "preventFocusOnPress": {
+        "intent": {
+          "type": "CheckboxIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
+          "values": [
+            "neutral",
+            "brand",
+            "danger"
+          ],
+          "default": "brand"
+        },
+        "isIndeterminate": {
           "type": "boolean | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Whether to prevent focus from moving to the button when pressing it.\n\nCaution, this can make the button inaccessible and should only be used when alternative\nkeyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's\nincrement/decrement control."
+          "origin": "own",
+          "description": "Figma's `Indeterminate` state. Not an HTML attribute — `indeterminate` is a\nDOM property only, so it has to be assigned after render.",
+          "default": false
         },
-        "form": {
-          "type": "string | undefined",
+        "isDisabled": {
+          "type": "boolean | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "The `<form>` element to associate the button 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/button#form)."
+          "origin": "own",
+          "description": "Whether the checkbox is disabled."
         },
-        "formAction": {
-          "type": "string | ((formData: FormData) => void | Promise<void>) | undefined",
+        "disabled": {
+          "type": "boolean | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "The URL that processes the information submitted by the button.\nOverrides the action attribute of the button's form owner."
+          "origin": "own",
+          "tags": {
+            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+          }
         },
-        "formEncType": {
-          "type": "string | undefined",
+        "children": {
+          "type": "React.ReactNode",
           "required": false,
-          "origin": "aria",
-          "description": "Indicates how to encode the form data that is submitted."
+          "origin": "own",
+          "description": "Figma's `Show Label` + `Label`. Omit for a bare box."
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 304,
+        "other": 0
+      }
+    },
+    "Citation": {
+      "name": "Citation",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationProps",
+      "description": "Citation — the inline marker.\n\nTHE MARKER IS NOT THE NAME. Rendered naively, a superscript \"1\" announces as\n\"link, 1\", which tells a screen-reader user nothing about whether to follow\nit. The visible marker stays a number; the accessible name is\n\"Source 1: <source>\". The number is for the sighted reader's eye and the\nsentence is for everyone.\n\nNOT A TOOLTIP. A tooltip cannot be reached on touch and closes on the way to\nit; attribution has to survive both. It is a real link, or a real\nnon-interactive marker when there is nowhere to go.\n\nWITHOUT `href` IT IS NOT A LINK. A citation to a phone call or an internal\ndocument has no address, and rendering a dead anchor for it puts an\nunfollowable link in the page's link list. It becomes a plain marked-up\nreference instead.",
+      "import": "import { Citation } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The inline source marker. The visible number is for the eye; the accessible name is the sentence.",
+      "useWhen": [
+        "a claim in generated text is drawn from a specific source the reader can check",
+        "attribution has to survive being read aloud, on touch, and in a links list"
+      ],
+      "useInstead": [
+        {
+          "when": "the source needs a full row with a passage",
+          "use": "CitationListItem"
+        },
+        {
+          "when": "it is an ordinary link in prose",
+          "use": "Link"
+        },
+        {
+          "when": "you were about to put the source in a hover-only hint",
+          "use": "Popover",
+          "why": "a tooltip cannot be reached on touch and closes on the way to it"
+        }
+      ],
+      "a11y": {
+        "role": "link when `href` is set, note otherwise",
+        "guarantees": [
+          "the accessible name is \"Source <index>: <source>\", never the bare number — a superscript 1 announces as \"link, 1\", which tells a screen-reader user nothing about whether to follow it",
+          "without `href` it renders a marker rather than a dead anchor, so an unfollowable link never enters the page's link list"
+        ],
+        "requires": [
+          "`source` naming what is being cited",
+          "an `index` matching the footer row, if there is one"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a bare superscript number with no accessible name",
+          "why": "\"link, 1\" is not attribution"
         },
-        "formMethod": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Indicates the HTTP method used to submit the form."
+        {
+          "dont": "an empty `href` for a source with no address",
+          "do": "omit `href`",
+          "why": "a dead anchor is announced as a link and goes nowhere"
         },
-        "formNoValidate": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Indicates that the form is not to be validated when it is submitted."
+        {
+          "dont": "putting the source only in a tooltip",
+          "why": "undiscoverable on touch, and gone before it can be read"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "index": {
+          "type": "string | number",
+          "required": true,
+          "origin": "own",
+          "description": "The marker shown inline — usually a number matching the footer list."
         },
-        "formTarget": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Overrides the target attribute of the button's form owner."
+        "source": {
+          "type": "string",
+          "required": true,
+          "origin": "own",
+          "description": "What is being cited. Required: it is the link's accessible name, and a\ncitation a reader cannot identify without following it is not attribution."
         },
-        "name": {
+        "href": {
           "type": "string | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Submitted as a pair with the button's value as part of the form data."
+          "origin": "own",
+          "description": "Where it goes. Omit for a source with no address — a document, a call."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 0,
+        "dom": 284,
+        "other": 0
+      }
+    },
+    "CitationList": {
+      "name": "CitationList",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationListProps",
+      "description": "The footer list. An `<ol>` so the numbering is structural rather than typed\ninto each row, and so a screen reader can say how many sources there are\nbefore the reader commits to hearing them.",
+      "import": "import { CitationList } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The footer list of sources, as an ordered list so the count and order are structural.",
+      "useWhen": [
+        "several claims cite sources and the reader should be able to see them all at once"
+      ],
+      "useInstead": [
+        {
+          "when": "there is one source and it belongs in the sentence",
+          "use": "Link"
         },
-        "value": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The value associated with the button's name when it's submitted with the form data."
+        {
+          "when": "it is tabular data with more than a source per row",
+          "use": "Table"
+        }
+      ],
+      "composition": {
+        "order": [
+          "CitationList",
+          "CitationListItem"
+        ],
+        "example": "<CitationList><CitationListItem index={1} source=\"Q3 filing\" href=\"/q3\">Revenue rose 4%.</CitationListItem></CitationList>"
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "rendered as plain text, not a heading element — it should not enter the document outline as a section"
         },
-        "excludeFromTabOrder": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+        "children": {
+          "accepts": "CitationListItem"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "an <ol>, so a screen reader can say how many sources there are before the reader commits to hearing them",
+          "list markers are hidden in CSS while the semantics stay, because the visible number must match the inline Citation's exactly"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a <div> stack of sources",
+          "why": "the count and the ordering are the useful part, and only a list carries them"
         },
-        "id": {
-          "type": "string | undefined",
+        {
+          "dont": "numbers that disagree with the inline markers",
+          "why": "the marker is a promise about where to look"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
           "required": false,
-          "origin": "aria",
-          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+          "origin": "own"
         },
-        "aria-label": {
-          "type": "string | undefined",
+        "label": {
+          "type": "React.ReactNode",
           "required": false,
-          "origin": "aria",
-          "description": "Defines a string value that labels the current element."
+          "origin": "own",
+          "description": "Heading above the list. Rendered as plain text, not a heading element."
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 280,
+        "other": 0
+      }
+    },
+    "CitationListItem": {
+      "name": "CitationListItem",
+      "source": "src/components/Citation.tsx",
+      "propsType": "CitationListItemProps",
+      "import": "import { CitationListItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One source row: its number, what it is, and the passage it supports.",
+      "useWhen": [
+        "a child of CitationList"
+      ],
+      "useInstead": [
+        {
+          "when": "it is the inline marker in the prose",
+          "use": "Citation"
+        }
+      ],
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the quoted or summarised passage this source supports"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the visible number is `aria-hidden`; the row is named by its source text, which is what a reader needs to hear",
+          "without `href` the source renders as text rather than a dead link"
+        ],
+        "requires": [
+          "`source` naming what is being cited"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a bare URL as the `source`",
+          "why": "a screen reader spells it out character by character, and it names nothing"
+        }
+      ],
+      "stylesheet": "src/styles/citation.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-semibold",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-primary-subtle",
+        "--surface-primary-subtle-hover",
+        "--text-link",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "index": {
+          "type": "string | number",
+          "required": true,
+          "origin": "own"
         },
-        "aria-labelledby": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "Identifies the element (or elements) that labels the current element."
+        "source": {
+          "type": "string",
+          "required": true,
+          "origin": "own"
         },
-        "aria-describedby": {
+        "href": {
           "type": "string | undefined",
           "required": false,
-          "origin": "aria",
-          "description": "Identifies the element (or elements) that describes the object."
+          "origin": "own"
         },
-        "aria-details": {
-          "type": "string | undefined",
+        "children": {
+          "type": "React.ReactNode",
           "required": false,
-          "origin": "aria",
-          "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+          "origin": "own",
+          "description": "The quoted or summarised passage this citation supports."
         }
       },
       "propCounts": {
-        "own": 7,
-        "aria": 39,
-        "dom": 0,
+        "own": 4,
+        "aria": 0,
+        "dom": 278,
         "other": 0
       }
     },
-    "Checkbox": {
-      "name": "Checkbox",
-      "source": "src/components/Checkbox.tsx",
-      "propsType": "CheckboxProps",
-      "description": "Checkbox wraps a native `<input type=\"checkbox\">` and hides it.\n\nThe native input is kept rather than replaced by a div with `role=checkbox`\nbecause it brings form association, the indeterminate property, label\nclicking, and correct announcement — none of which are free to reimplement,\nand all of which are easy to get subtly wrong.\n\n`indeterminate` is the reason for the effect below: HTML has no\n`indeterminate` attribute, only a DOM property, so React cannot set it\ndeclaratively and it must be written after every render.",
-      "import": "import { Checkbox } from 'ionbase-ui';",
+    "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": "A native checkbox with the system's styling, supporting an indeterminate state.",
+      "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
       "useWhen": [
-        "a single on/off choice inside a form that is submitted",
-        "selecting rows in a Table",
-        "several independent options where more than one may be picked"
+        "a generated answer varies in reliability and the reader should weigh it",
+        "you can say what the confidence rests on"
       ],
       "useInstead": [
         {
-          "when": "the change takes effect immediately rather than on submit",
-          "use": "Toggle",
-          "why": "a switch reads as a setting taking effect now; a checkbox reads as a value being collected"
+          "when": "the answer is wrong or missing rather than uncertain",
+          "use": "Alert"
         },
         {
-          "when": "the options are mutually exclusive",
-          "use": "RadioGroup"
+          "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 many options and space is tight",
-          "use": "Select"
+          "when": "it is a status rather than a reliability",
+          "use": "Badge"
         }
       ],
       "variants": {
-        "size": {
-          "sm": {
-            "use": "dense forms and table rows"
-          },
-          "md": {
-            "use": "the default"
-          },
-          "lg": {
-            "use": "touch targets and prominent single choices"
-          }
-        },
-        "intent": {
-          "brand": {
-            "use": "the default"
+        "level": {
+          "low": {
+            "use": "thin or conflicting evidence. One bar, warning colour"
           },
-          "neutral": {
-            "use": "where the checked state is a fact rather than an approval — bulk-selection columns"
+          "medium": {
+            "use": "reasonable support with real gaps. Two bars"
           },
-          "danger": {
-            "use": "consenting to something destructive or irreversible"
-          }
-        }
-      },
-      "slots": {
-        "children": {
-          "accepts": "text",
-          "note": "the visible label; omit for a bare box and supply `aria-label` instead"
+          "high": {
+            "use": "corroborated, and you can say by what. Three bars"
+          }
         }
       },
       "a11y": {
-        "role": "checkbox",
         "guarantees": [
-          "a real <input type=\"checkbox\">, so form association, label clicking, and correct announcement come from the platform",
-          "`isIndeterminate` is written to the DOM property after every render — HTML has no such attribute, so React cannot set it declaratively"
+          "the level is spelled out in text, so it never depends on the meter",
+          "the meter differs in filled COUNT rather than only in colour, and in forced-colours mode filled bars are solid while empty ones are outlined"
         ],
         "requires": [
-          "`children`, or `aria-label` when the box has no visible label — a row-selection checkbox always needs one"
+          "`basis` — a type error if omitted, and the reason this component exists rather than a coloured dot"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "a bare checkbox with no `children` and no `aria-label`",
-          "why": "every row announces an unnamed checkbox"
+          "dont": "asking for a percentage prop",
+          "why": "\"87% confident\" reads as a measurement and almost never is one — usually a softmax score or a model's claim about itself, neither of which is a calibrated probability. Three levels cannot overclaim that way"
         },
         {
-          "dont": "`isIndeterminate` on a leaf checkbox",
-          "why": "indeterminate means \"some of my children are checked\"; on a leaf it is a state the user can never reach"
+          "dont": "a vague basis like \"model output\"",
+          "why": "it satisfies the type and defeats the purpose — say \"3 of 4 sources agree\" or \"single unverified source\""
         },
         {
-          "dont": "a div with `role=\"checkbox\"`",
-          "why": "form association, the indeterminate property and label clicking are not free to reimplement"
-        }
-      ],
-      "deprecated": [
-        {
-          "prop": "disabled",
-          "replacement": "isDisabled"
+          "dont": "high confidence on every response",
+          "why": "an indicator that never varies is decoration that still changes behaviour"
         }
       ],
-      "stylesheet": "src/styles/checkbox.css",
+      "stylesheet": "src/styles/confidence-indicator.css",
       "tokens": [
-        "--border-disabled",
-        "--border-error-strong",
-        "--border-focus",
-        "--border-inverse",
-        "--border-primary-strong",
-        "--border-stronger",
         "--border-width-default",
-        "--border-width-thick",
         "--font-family-sans",
-        "--icon-disabled",
-        "--icon-on-color",
-        "--ion-checkbox-border",
-        "--ion-checkbox-fill",
-        "--ion-checkbox-font-size",
-        "--ion-checkbox-gap",
-        "--ion-checkbox-line-height",
-        "--ion-checkbox-mark",
-        "--ion-checkbox-radius",
-        "--ion-checkbox-raised",
-        "--ion-checkbox-size",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--ion-shadow-raised-flush-lg",
-        "--ion-shadow-raised-flush-sm",
-        "--ion-shadow-raised-flush-xs",
-        "--radius-sm",
-        "--radius-xs",
+        "--font-weight-medium",
+        "--icon-information",
+        "--icon-success",
+        "--icon-tertiary",
+        "--icon-warning",
+        "--radius-2xs",
         "--spacing-12",
         "--spacing-16",
-        "--spacing-20",
-        "--spacing-24",
+        "--spacing-2",
         "--spacing-4",
         "--spacing-8",
-        "--surface-default",
-        "--surface-disabled",
-        "--surface-error",
-        "--surface-inverse",
-        "--surface-primary",
-        "--text-disabled",
+        "--text-default",
         "--text-secondary",
-        "--type-body",
-        "--type-body-line-height",
-        "--type-body-sm",
-        "--type-body-sm-line-height"
+        "--text-tertiary",
+        "--type-caption",
+        "--type-caption-line-height"
       ],
       "props": {
-        "size": {
-          "type": "CheckboxSize | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
-          "values": [
-            "sm",
-            "md",
-            "lg"
-          ],
-          "default": "md"
-        },
-        "intent": {
-          "type": "CheckboxIntent | undefined",
-          "required": false,
+        "level": {
+          "type": "ConfidenceLevel",
+          "required": true,
           "origin": "own",
-          "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
           "values": [
-            "neutral",
-            "brand",
-            "danger"
-          ],
-          "default": "brand"
-        },
-        "isIndeterminate": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Figma's `Indeterminate` state. Not an HTML attribute — `indeterminate` is a\nDOM property only, so it has to be assigned after render.",
-          "default": false
-        },
-        "isDisabled": {
-          "type": "boolean | undefined",
-          "required": false,
-          "origin": "own",
-          "description": "Whether the checkbox is disabled."
+            "low",
+            "medium",
+            "high"
+          ]
         },
-        "disabled": {
-          "type": "boolean | undefined",
-          "required": false,
+        "basis": {
+          "type": "string",
+          "required": true,
           "origin": "own",
-          "tags": {
-            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-          }
+          "description": "What the level is based on. REQUIRED, and the reason this component exists\nrather than a coloured dot: a confidence with no stated basis is a number\nthe reader has no way to weigh. \"3 of 4 sources agree\", \"no matching\nrecords found\", \"single unverified source\"."
         },
-        "children": {
-          "type": "React.ReactNode",
+        "label": {
+          "type": "string | undefined",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Show Label` + `Label`. Omit for a bare box."
+          "description": "Override the level's word. Keep it a word, not a percentage."
         }
       },
       "propCounts": {
-        "own": 6,
+        "own": 3,
         "aria": 0,
-        "dom": 304,
+        "dom": 277,
         "other": 0
       }
     },
@@ -2133,13 +3170,13 @@
           "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
         },
         "enterKeyHint": {
-          "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
           "required": false,
           "origin": "aria",
           "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
           "values": [
-            "enter",
             "done",
+            "enter",
             "go",
             "next",
             "previous",
@@ -3661,6 +4698,42 @@
           "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",
+          "required": false,
+          "origin": "aria",
+          "description": "The current value (controlled)."
+        },
         "defaultValue": {
           "type": "string | undefined",
           "required": false,
@@ -3694,13 +4767,13 @@
           "description": "Class names for the control box (`.ion-input`). Always lands here —\nnever on the form-field wrapper. Use `wrapperClassName` for that."
         },
         "enterKeyHint": {
-          "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
           "required": false,
           "origin": "aria",
           "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
           "values": [
-            "enter",
             "done",
+            "enter",
             "go",
             "next",
             "previous",
@@ -3898,36 +4971,12 @@
           ],
           "default": "md"
         },
-        "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"
-        },
         "autoComplete": {
           "type": "string | undefined",
           "required": false,
           "origin": "aria",
           "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
         },
-        "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)."
-        },
         "maxLength": {
           "type": "number | undefined",
           "required": false,
@@ -3940,12 +4989,6 @@
           "origin": "aria",
           "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
         },
-        "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)."
-        },
         "pattern": {
           "type": "string | undefined",
           "required": false,
@@ -3958,12 +5001,6 @@
           "origin": "aria",
           "description": "Temporary text that occupies the text input when it is empty."
         },
-        "value": {
-          "type": "string | undefined",
-          "required": false,
-          "origin": "aria",
-          "description": "The current value (controlled)."
-        },
         "isDisabled": {
           "type": "boolean | undefined",
           "required": false,
@@ -4975,6 +6012,105 @@
         "other": 0
       }
     },
+    "StreamingText": {
+      "name": "StreamingText",
+      "source": "src/components/StreamingText.tsx",
+      "propsType": "StreamingTextProps",
+      "description": "StreamingText — model output arriving a token at a time.\n\nIT IS NOT A LIVE REGION, AND THAT IS THE WHOLE DESIGN\n\nThe obvious implementation — `aria-live=\"polite\"` on the container — is the\none that makes a screen reader unusable. Every token mutation queues an\nannouncement, so the user hears the answer re-read, stuttered, dozens of\ntimes, and cannot get ahead of it. `aria-live=\"off\"` is not an oversight\nhere; it is the accessible choice.\n\nWhat it does instead: `aria-busy` while streaming, so assistive tech knows\nthe region is unsettled and can wait. The text is ordinary readable content\nthroughout — a screen-reader user navigates into it whenever they want,\nexactly like sighted users reading ahead of the cursor.\n\nANNOUNCING COMPLETION IS THE CALLER'S CALL, not this component's. Some\nsurfaces want \"response complete\"; a chat with ten turns on screen does not\nwant ten of them. Render your own `role=\"status\"` when you want it.\n\nTHE HEIGHT IS RESERVED, NOT ANIMATED. `minLines` holds space in `lh` units so\nthe content below stays still. A container that grows token by token drags\nthe whole page, which is worse for someone using magnification than the wait.\n\nThe cursor is CSS and `aria-hidden`. It stops blinking under\n`prefers-reduced-motion` — a blinking element is a WCAG 2.3.1 concern and a\ngenuine problem for some vestibular and attention conditions.",
+      "import": "import { StreamingText } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Model output arriving a token at a time, in a container that does not move. Deliberately not a live region.",
+      "useWhen": [
+        "rendering a response that streams in rather than arriving whole",
+        "the reader should be able to start reading before generation finishes"
+      ],
+      "useInstead": [
+        {
+          "when": "the text is already complete",
+          "use": "Alert",
+          "why": "nothing about this component helps once there is nothing left to arrive"
+        },
+        {
+          "when": "you are showing progress through steps rather than producing text",
+          "use": "AgentActivity"
+        }
+      ],
+      "a11y": {
+        "role": "region when `label` is set, none otherwise",
+        "guarantees": [
+          "`aria-live=\"off\"`, deliberately — a polite live region re-announces the whole answer on every token, which makes a streaming response unusable with a screen reader",
+          "`aria-busy` while streaming, so assistive tech knows the region is unsettled",
+          "the text stays ordinary readable content throughout, so a screen-reader user can read ahead exactly as a sighted user does",
+          "the cursor is `aria-hidden`, is a styled box rather than a text character, and stops blinking under `prefers-reduced-motion` (WCAG 2.3.1)"
+        ],
+        "requires": [
+          "announcing completion yourself, with your own `role=\"status\"`, if the surface wants it — a chat with ten turns on screen does not want ten announcements",
+          "`label` when the region needs a name of its own"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "wrapping it in `aria-live=\"polite\"`",
+          "why": "every token queues an announcement; the user hears the answer stuttered dozens of times and cannot get ahead of it"
+        },
+        {
+          "dont": "letting the container grow token by token with no reserved height",
+          "do": "`minLines`",
+          "why": "the content below climbs the screen while someone is reading it, which is worse under magnification than the wait"
+        },
+        {
+          "dont": "a text-character cursor like ▌",
+          "why": "some screen readers read it aloud even inside an aria-hidden span"
+        }
+      ],
+      "stylesheet": "src/styles/streaming-text.css",
+      "tokens": [
+        "--font-family-sans",
+        "--ion-streaming-min-lines",
+        "--text-default",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The text so far. Re-render with more of it; this component appends nothing."
+        },
+        "isStreaming": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "More is still arriving. Shows the cursor and marks the region busy."
+        },
+        "minLines": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Rows of height to hold while the text is short, so the page below does not\nclimb the screen as tokens arrive. Costs blank space at the start and buys\na layout that does not move under a reader."
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible name for the region."
+        },
+        "hideCursor": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Hide the trailing cursor. The text still marks itself busy."
+        }
+      },
+      "propCounts": {
+        "own": 5,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
     "TabItem": {
       "name": "TabItem",
       "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Item.d.ts",