ionbase-ui 0.18.1 → 0.19.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useToast"
@@ -260,6 +260,72 @@
       "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",
@@ -357,6 +423,63 @@
       "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",
@@ -439,6 +562,71 @@
       "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",
@@ -1040,6 +1228,88 @@
       "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",
@@ -1153,6 +1423,45 @@
       "propsType": "DividerProps",
       "description": "A single `<hr>`, matching Figma's `Border` (70:22153).\n\n`<hr>` rather than a styled `<div>`: it is a semantic thematic break, so a\nscreen reader announces it as one, and it needs no `role` to get there.\n`aria-orientation` is set for the vertical case, since a vertical rule\ninside a horizontal toolbar is the one shape a screen reader cannot infer\nfrom the element alone.",
       "import": "import { Divider } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A semantic thematic break, rendered as a real <hr>.",
+      "useWhen": [
+        "separating groups of content or controls that are related but distinct",
+        "a menu, toolbar or form needs a visible section break"
+      ],
+      "useInstead": [
+        {
+          "when": "you only want space between two things",
+          "use": "CSS gap or margin",
+          "why": "a rule announces a break to a screen reader; whitespace does not, and usually shouldn't"
+        }
+      ],
+      "variants": {
+        "orientation": {
+          "horizontal": {
+            "use": "the default — between stacked sections"
+          },
+          "vertical": {
+            "use": "inside a horizontal row: toolbars, button groups, header bars"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "`<hr>` is a thematic break to assistive tech without needing a role",
+          "`aria-orientation=\"vertical\"` is set for the vertical case — the one thing a screen reader cannot infer from the element"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a styled <div> for a rule",
+          "why": "that is what this component exists to replace"
+        },
+        {
+          "dont": "a Divider between every row of a list",
+          "why": "a break announced on every row is noise; use the list's own row borders"
+        }
+      ],
       "stylesheet": "src/styles/divider.css",
       "tokens": [
         "--border-strong",
@@ -1183,6 +1492,83 @@
       "propsType": "FullCardProps",
       "description": "Full Card — the full-bleed case study row from Figma `Full Card` (592:857).\n\nA text column beside a framed media panel, split down the middle, mirrored\nby the `Alignment` variant.\n\nThe split holds from 1080 and stacks below it, media above content in BOTH\nalignments — `Alignment` names a horizontal side and\nstops meaning anything once there is one column, so it does not get to\ndecide the vertical order too. Size is a media query, not a prop, the same\ncall Header makes about Device.\n\nWHY THE `show*` BOOLEANS ARE GONE\n\nFigma carries `Show Eyebrow`, `Show Description` and `Show Actions` beside\nthe slots they gate, because a Figma component instance always holds every\nlayer and needs a switch to hide one. React has no such constraint — an\nabsent prop is the switch. Badge made the same call with `Show Dot`, and\nkeeping both would have let `showActions` and `actions` disagree.\n\n`headline` is required, and it is the only required prop. The heading is\nwhat makes this a section rather than a decorated div, and every other part\nof the card is optional in Figma too.\n\nNo `'use client'`: nothing here is stateful or interactive. The interactive\nparts arrive through `actions`, and they carry their own boundary.",
       "import": "import { FullCard } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A full-bleed row: a text column beside a framed media panel, mirrored by `alignment`.",
+      "useWhen": [
+        "a marketing or overview section presents one thing with a screenshot beside it",
+        "a case-study or feature row on a landing or product page"
+      ],
+      "useInstead": [
+        {
+          "when": "you are listing records with comparable fields",
+          "use": "Table"
+        },
+        {
+          "when": "it is a short status message rather than a content section",
+          "use": "Alert"
+        }
+      ],
+      "slots": {
+        "eyebrow": {
+          "accepts": "Badge",
+          "note": "any node works"
+        },
+        "headline": {
+          "accepts": "text",
+          "note": "required — the heading is what makes this a section rather than a decorated div"
+        },
+        "description": {
+          "accepts": "text"
+        },
+        "actions": {
+          "accepts": "Button",
+          "note": "a secondary Button in the design"
+        },
+        "media": {
+          "accepts": "img or video",
+          "note": "rendered inside the framed screen holder — pass the screenshot or embed itself, not the frame"
+        },
+        "children": {
+          "accepts": "any",
+          "note": "extra content below the description"
+        }
+      },
+      "variants": {
+        "alignment": {
+          "left": {
+            "use": "media on the left, text on the right"
+          },
+          "right": {
+            "use": "media on the right — the variant names the media, not the text"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the headline renders as a real heading, so the card appears in the document outline"
+        ],
+        "requires": [
+          "`headingLevel` matching the surrounding outline — `h3` is the default because Figma applies Type/H3, but only the page knows the real level",
+          "`alt` on whatever you pass as `media`"
+        ],
+        "notes": [
+          "`h1` is deliberately not available: a full card is a section within a page, never the page's own title."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "looking for `showEyebrow` / `showDescription` / `showActions`",
+          "why": "an absent prop is the switch — Figma needs the boolean because an instance always holds every layer; React does not"
+        },
+        {
+          "dont": "leaving `headingLevel` at the default inside a section that is already at h3",
+          "why": "it produces a skipped or duplicated outline level"
+        },
+        {
+          "dont": "passing your own frame or border around `media`",
+          "why": "the component already draws the screen holder"
+        }
+      ],
       "stylesheet": "src/styles/full-card.css",
       "tokens": [
         "--border-default",
@@ -1280,16 +1666,75 @@
       "propsType": "HeaderProps",
       "description": "Header renders Figma's four Device variants — Desktop, Tablet,\nMobile-Closed, Mobile-Open — from one DOM tree.\n\nTWO AXES, AND THEY ARE NOT THE SAME KIND OF THING\n\nFigma spells Device as a single four-way variant, but it is really two: a\n*breakpoint* (Desktop / Tablet / Mobile) and a *state* (Closed / Open). They\nare modelled differently here because they are known by different people.\n\n  Breakpoint is a media query. It is the one variant axis in the system the\n  browser already knows the answer to — a header is Mobile because the\n  viewport is narrow — and having React duplicate that judgement is how the\n  two drift apart. Breakpoints match the Breakpoint collection's container\n  widths: Tablet below 1216, Mobile below 896.\n\n  Open/Closed is a prop, because only the caller knows. It follows the\n  controlled/uncontrolled pair the rest of the system uses.\n\nONE TREE, TWO LAYOUTS\n\n`center` and `end` sit inline in the bar on Desktop and Tablet, and inside\nthe dropped Menu-Container on Mobile-Open. They are rendered once, in one\nwrapper, which is `display: contents` above the mobile breakpoint and an\nabsolutely positioned panel below it. Rendering them twice — or moving them\nwith JavaScript — would mean the same nav link exists twice in the\naccessibility tree, and would reset any state a caller put in a slot every\ntime the viewport crossed 896px.\n\nThe centre slot is no longer hidden on Tablet. Figma's Tablet variant ships\nit populated; the previous release collapsed it, which was correct for the\nprevious design and is not for this one.\n\nA `<header>` element with no explicit role: it is a landmark already when it\nis a direct child of body, which is where a page header sits.",
       "import": "import { Header } from 'ionbase-ui';",
-      "stylesheet": "src/styles/header.css",
-      "tokens": [
-        "--border-default",
-        "--border-strong",
-        "--border-width-default",
-        "--border-width-thick",
-        "--font-family-sans",
-        "--icon-default",
-        "--icon-size-sm",
-        "--ion-header-center-gap",
+      "status": "stable",
+      "summary": "The page header bar. Renders Figma's Desktop, Tablet, Mobile-Closed and Mobile-Open from one DOM tree.",
+      "useWhen": [
+        "the app needs a top bar with a brand, navigation and actions",
+        "that bar must collapse to a mobile menu below 896px"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a sidebar rather than a top bar",
+          "use": "NavItem",
+          "why": "Header owns a horizontal bar and its own breakpoint behaviour"
+        }
+      ],
+      "slots": {
+        "brand": {
+          "accepts": "LogoMark or Logo",
+          "note": "rendered at the start; never shrinks"
+        },
+        "center": {
+          "accepts": "NavItem",
+          "note": "inline on Desktop and Tablet; moves into the mobile menu below 896px. Rendered once, so slot state survives crossing the breakpoint"
+        },
+        "end": {
+          "accepts": "Button, Avatar",
+          "note": "actions; same placement rules as `center`"
+        },
+        "children": {
+          "accepts": "any",
+          "note": "escape hatch — rendered in the bar after the menu wrapper and before the mobile toggle. Prefer the named slots"
+        }
+      },
+      "a11y": {
+        "role": "banner, from the <header> element when it is a direct child of body",
+        "guarantees": [
+          "the mobile toggle carries `aria-expanded` and `aria-controls` pointing at the menu container",
+          "Escape closes the open mobile menu — and the listener sits on the header, so a header that never opens never listens",
+          "the slots are rendered once, so no nav link exists twice in the accessibility tree"
+        ],
+        "requires": [
+          "`menuLabel` — the mobile toggle is icon-only and has no other name"
+        ],
+        "notes": [
+          "This is a disclosure, not a modal: no focus trap and no scroll lock, so Escape is the whole dismissal contract."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "rendering a second copy of the nav for mobile",
+          "why": "Header already moves the one copy; two copies duplicate every link in the accessibility tree"
+        },
+        {
+          "dont": "driving the mobile layout from JS state",
+          "why": "the breakpoint is a media query — the browser already knows the answer, and duplicating that judgement is how the two drift"
+        },
+        {
+          "dont": "passing `open` without `onOpenChange`",
+          "why": "controlled with no handler means the toggle can never change it"
+        }
+      ],
+      "stylesheet": "src/styles/header.css",
+      "tokens": [
+        "--border-default",
+        "--border-strong",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--icon-default",
+        "--icon-size-sm",
+        "--ion-header-center-gap",
         "--ion-header-end-gap",
         "--ion-header-height",
         "--ion-header-padding-x",
@@ -1371,6 +1816,60 @@
       "propsType": "IconProps",
       "description": "Wrapper that applies the design system's icon sizing and accessibility\ndefaults to whatever icon component you hand it.\n\n  import { Plus } from 'lucide-react';\n  <Icon as={Plus} size=\"sm\" />\n  <Icon as={Plus} label=\"Add item\" />   // meaningful, gets an a11y name\n\nTakes the icon as a prop rather than re-exporting a set: a barrel of a\nthousand-plus icons defeats tree-shaking in several bundlers, and pinning one\nicon library would force it on every consumer. You import the one icon you\nneed, from whichever library you use, and it is the only one bundled.",
       "import": "import { Icon } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Applies the system's icon sizing and accessibility defaults to any SVG component you hand it. The package ships no icon set.",
+      "useWhen": [
+        "rendering any icon inside this design system, from any library — lucide, heroicons, react-icons, your own SVG"
+      ],
+      "useInstead": [
+        {
+          "when": "the graphic is a brand mark",
+          "use": "Logo or LogoMark"
+        },
+        {
+          "when": "you need a coloured status marker with text",
+          "use": "Badge"
+        }
+      ],
+      "a11y": {
+        "guarantees": [
+          "with `label`, the icon gets `role=\"img\"` and that name",
+          "without `label`, it is `aria-hidden` and `focusable=\"false\"` — decoration, never read twice"
+        ],
+        "requires": [
+          "`label` when the icon carries meaning on its own — an icon-only button, a standalone status marker"
+        ],
+        "notes": [
+          "Omit `label` for an icon beside a visible text label. The text already names it."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`<Button startIcon={<Icon as={Plus} label=\"Add\" />}>Add</Button>`",
+          "do": "drop the `label`",
+          "why": "the button's own text names it; the labelled icon makes it announce twice"
+        },
+        {
+          "dont": "hardcoding `width`/`height` in px",
+          "do": "a `size` rung, or omit `size` to inherit the surrounding font size",
+          "why": "inheriting is what lets an icon sit correctly inside a Button without the Button knowing about it"
+        },
+        {
+          "dont": "assuming `size=\"xs\"` is 12px",
+          "why": "the ladder shifted in 2026-08: `xs` is 14, and `2xs` is the old 12. This raises no type error"
+        }
+      ],
+      "sizes": {
+        "note": "The rungs map one-to-one onto the Semantics `icon-size/*` tokens. Any CSS length is also accepted for a one-off.",
+        "ladder": {
+          "2xs": 12,
+          "xs": 14,
+          "sm": 16,
+          "md": 20,
+          "lg": 24,
+          "xl": 32
+        }
+      },
       "stylesheet": "src/styles/icon.css",
       "tokens": [],
       "props": {
@@ -1964,6 +2463,73 @@
       "propsType": "LinkProps",
       "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
       "import": "import { Link } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
+      "useWhen": [
+        "the interaction takes the user to a different page, view or resource",
+        "the destination should support middle-click, open-in-new-tab and copy-link"
+      ],
+      "useInstead": [
+        {
+          "when": "the interaction changes something rather than going somewhere",
+          "use": "Button",
+          "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
+        },
+        {
+          "when": "it is a primary navigation destination in a header or sidebar",
+          "use": "NavItem"
+        }
+      ],
+      "variants": {
+        "variant": {
+          "inline": {
+            "use": "the default — a link inside a paragraph. Underlined in every state, because a link in body copy must not rely on colour alone (WCAG 1.4.1)"
+          },
+          "standalone": {
+            "use": "a link that already reads as interactive from its position — a card footer, an action row. Underlines on hover only"
+          }
+        }
+      },
+      "slots": {
+        "startIcon": {
+          "accepts": "Icon",
+          "note": "omit Icon's `label` — the link text already names it"
+        },
+        "endIcon": {
+          "accepts": "Icon",
+          "note": "the external-link or arrow affordance; same rule about `label`"
+        }
+      },
+      "a11y": {
+        "role": "link when `href` is set, button when it is not",
+        "guarantees": [
+          "the rendered element follows what the caller is actually building, so the announcement is always honest",
+          "`inline` stays underlined in every state, so it never depends on colour alone"
+        ],
+        "requires": [
+          "link text that makes sense read on its own — screen-reader users navigate by a list of links"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "\"click here\" or \"read more\" as the whole link text",
+          "why": "out of context in a links list it names nothing"
+        },
+        {
+          "dont": "adding a size prop or wrapper to scale it",
+          "why": "a link is inline and inherits its type from the text around it, by design — icons are sized in `em` to follow"
+        },
+        {
+          "dont": "`target=\"_blank\"` with no warning in the text or endIcon",
+          "why": "an unannounced new tab disorients screen-reader and low-vision users"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
       "stylesheet": "src/styles/link.css",
       "tokens": [
         "--border-width-thick",
@@ -2203,6 +2769,55 @@
       "propsType": "LogoProps",
       "description": "The full lockup: mark + wordmark, matching Figma's `Logo-Ionbase`\n(52:21369).\n\nFigma also has a `Property=Name` axis — wordmark only, no mark — but both\nof its variants currently render the placeholder text \"raza\" rather than\n\"IonBase\", in an unbound raw colour. That is leftover debug content, not a\nreal asset, so it is not implemented here. Reproducing it would ship a\nstranger's name into a design system; extending `LogoMark` alone already\ncovers \"no wordmark\" for the cases that are real.",
       "import": "import { Logo } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The full IonBase lockup — mark plus wordmark.",
+      "useWhen": [
+        "the product needs to identify itself: header, sign-in page, empty state, marketing surface"
+      ],
+      "useInstead": [
+        {
+          "when": "space is tight, or a wordmark already appears nearby",
+          "use": "LogoMark"
+        },
+        {
+          "when": "you need any graphic that is not the brand",
+          "use": "Icon"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "the default — a 24px mark, which is what a header bar wants"
+          },
+          "lg": {
+            "use": "a 32px mark — sign-in, splash, or anywhere the brand is the subject"
+          }
+        },
+        "wordmark": {
+          "vector": {
+            "use": "the default and the safe choice — Figma's serif logotype as frozen artwork, immune to font substitution and visually distinct from the UI type"
+          },
+          "text": {
+            "use": "live, selectable Host Grotesk at `text/tertiary` — for surfaces where the name should behave like text (copyable, searchable) rather than like a mark"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the wordmark carries the accessible name, so the mark beside it is not announced twice",
+          "artwork uses `currentColor` rather than Figma's baked hex, so it themes with the rest of the icon layer"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "recolouring the lockup with your own fill",
+          "why": "it inherits `icon/default`; overriding it is how a brand mark ends up failing contrast in one theme"
+        },
+        {
+          "dont": "putting the Logo inside a Link with its own text \"IonBase\"",
+          "why": "the name is announced twice; label the link, not both"
+        }
+      ],
       "stylesheet": "src/styles/logo.css",
       "tokens": [
         "--font-family-sans",
@@ -2249,6 +2864,44 @@
       "propsType": "LogoMarkProps",
       "description": "The bare icon glyph, no wordmark — what `Header` actually uses.\n\nColour comes from the `.ion-logo__mark` class (`icon/default`), not the SVG\nitself, so it themes the same way every other icon in the system does.",
       "import": "import { LogoMark } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The bare mark, no wordmark — what Header uses.",
+      "useWhen": [
+        "a wordmark is already visible nearby, or the bar is too narrow for the lockup",
+        "a favicon-scale identity marker inside the product"
+      ],
+      "useInstead": [
+        {
+          "when": "this is the only place the product names itself",
+          "use": "Logo",
+          "why": "a mark alone identifies nothing to someone who has not learned it yet"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "the default, 24px — header bars"
+          },
+          "lg": {
+            "use": "32px — sign-in and other brand-forward surfaces"
+          }
+        }
+      },
+      "a11y": {
+        "requires": [
+          "`label` when the mark stands alone — it is the only thing naming it"
+        ],
+        "notes": [
+          "Omit `label` when a visible wordmark sits beside it; that text already carries the name."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`label=\"logo\"`",
+          "do": "`label=\"IonBase\"`",
+          "why": "the name of the brand is the useful announcement; the word \"logo\" is not"
+        }
+      ],
       "stylesheet": "src/styles/logo.css",
       "tokens": [
         "--font-family-sans",
@@ -2290,6 +2943,60 @@
       "propsType": "MenuProps",
       "description": "Menu is the list surface, not a popover.\n\nFigma models the list alone — there is no trigger, anchor or open state in\nthe design — so this renders the surface and nothing else. Positioning it\nagainst a button is the caller's job until Figma has a component that says\nhow. Building a popover here would be inventing design, and it would be the\nhard half to unpick later.\n\n`role=\"menu\"` is deliberately NOT set. A real ARIA menu owes the user\nroving-tabindex arrow navigation, typeahead and focus containment; claiming\nthe role without them is worse for a screen-reader user than an honest list,\nbecause it promises interactions that are not there. When the popover exists,\nthe role comes with it.",
       "import": "import { Menu } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The list surface only — no trigger, no anchor, no open state. Positioning it is the caller's job.",
+      "useWhen": [
+        "rendering a list of actions or options as a surface you have already positioned",
+        "the rows need icons, a selected check, or two lines — more than a native <select> can hold"
+      ],
+      "useInstead": [
+        {
+          "when": "you want a self-contained dropdown with a trigger and open state",
+          "use": "Popover",
+          "why": "Menu is the surface alone; Popover owns the trigger, positioning, focus containment and Escape"
+        },
+        {
+          "when": "one value is picked from a modest list of plain text options",
+          "use": "Select",
+          "why": "the native picker brings keyboard handling, type-ahead and the mobile platform picker for free"
+        },
+        {
+          "when": "it is primary navigation rather than a dropdown",
+          "use": "NavItem"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Menu",
+          "MenuItem"
+        ],
+        "example": "<Menu><MenuItem icon={<Icon as={Copy} />}>Duplicate</MenuItem><MenuItem isSelected>Archive</MenuItem></Menu>"
+      },
+      "slots": {
+        "children": {
+          "accepts": "MenuItem"
+        }
+      },
+      "a11y": {
+        "role": "none — it is a plain <ul>",
+        "guarantees": [
+          "no `role=\"menu\"`, deliberately: a real ARIA menu owes the user roving tabindex, arrow-key navigation and typeahead, and claiming the role without them promises interactions that are not there"
+        ],
+        "notes": [
+          "Each MenuItem is a real <button>, so Tab reaches every row. That is honest, and it is not the same as arrow-key menu navigation.",
+          "The role arrives when the popover that owns it does."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "adding `role=\"menu\"` yourself",
+          "why": "the keyboard behaviour that role promises is not implemented; an honest list is better for a screen-reader user than a lying menu"
+        },
+        {
+          "dont": "using Menu as a dropdown without positioning it",
+          "why": "it renders in flow — it has no anchor logic of its own"
+        }
+      ],
       "stylesheet": "src/styles/menu.css",
       "tokens": [
         "--border-focus",
@@ -2339,6 +3046,57 @@
       "source": "src/components/Menu.tsx",
       "propsType": "MenuItemProps",
       "import": "import { MenuItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+      "useWhen": [
+        "a row in a Menu surface"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a top-level navigation destination",
+          "use": "NavItem"
+        },
+        {
+          "when": "it is a standalone action outside a list",
+          "use": "Button"
+        }
+      ],
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "leading icon; omit its `label` — the row's text names it"
+        },
+        "children": {
+          "accepts": "text",
+          "note": "the row label"
+        }
+      },
+      "a11y": {
+        "role": "button",
+        "guarantees": [
+          "`isSelected` sets `aria-pressed`, so the selected state is announced and not only drawn",
+          "the check glyph always occupies its slot, so rows never reflow as the selection moves"
+        ],
+        "requires": [
+          "a text label in `children`"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "using MenuItem outside a Menu",
+          "why": "it renders an <li>, which is only valid inside a list"
+        },
+        {
+          "dont": "an icon-only MenuItem with no children",
+          "why": "the row announces nothing"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
       "stylesheet": "src/styles/menu.css",
       "tokens": [
         "--border-focus",
@@ -2656,25 +3414,78 @@
       "propsType": "NavItemProps",
       "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
       "import": "import { NavItem } from 'ionbase-ui';",
-      "stylesheet": "src/styles/nav-item.css",
-      "tokens": [
-        "--border-focus",
-        "--border-width-thick",
-        "--font-family-sans",
-        "--font-weight-regular",
-        "--icon-disabled",
-        "--icon-interactive-hover",
-        "--icon-size-sm",
-        "--icon-tertiary",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--radius-sm",
-        "--spacing-4",
-        "--spacing-8",
-        "--text-disabled",
-        "--text-interactive-hover",
-        "--text-secondary",
-        "--type-body-sm",
+      "status": "stable",
+      "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
+      "useWhen": [
+        "building a header nav bar, a sidebar or a section switcher",
+        "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
+      ],
+      "useInstead": [
+        {
+          "when": "the link sits inside body copy or a content block",
+          "use": "Link"
+        },
+        {
+          "when": "it is a row in a dropdown list rather than a top-level destination",
+          "use": "MenuItem"
+        }
+      ],
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "leading icon; omit its `label` — the item's text names it"
+        }
+      },
+      "a11y": {
+        "role": "link when `href` is set, button when it is not",
+        "guarantees": [
+          "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
+          "the focus ring shows for keyboard navigation only",
+          "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React"
+        ],
+        "requires": [
+          "an accessible name — `children`, or `aria-label` on an icon-only item"
+        ],
+        "notes": [
+          "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`showChevron` on a plain link that navigates",
+          "why": "the chevron promises a menu; nothing opens"
+        },
+        {
+          "dont": "marking the current page with colour only",
+          "do": "`aria-current=\"page\"`",
+          "why": "a screen-reader user is otherwise never told where they are"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
+      "stylesheet": "src/styles/nav-item.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--icon-disabled",
+        "--icon-interactive-hover",
+        "--icon-size-sm",
+        "--icon-tertiary",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-sm",
+        "--spacing-4",
+        "--spacing-8",
+        "--text-disabled",
+        "--text-interactive-hover",
+        "--text-secondary",
+        "--type-body-sm",
         "--type-body-sm-line-height"
       ],
       "props": {
@@ -2732,6 +3543,66 @@
       "propsType": "PhoneInputProps",
       "description": "PhoneInput — Figma `Input/Phone` (80:372).\n\nA dial-code block butted against an Input, sharing one outline: the block\ncarries the left radii and the control the right, so the seam is square on\nboth sides and reads as a single control. Both keep their full 1px border,\nwhich is what Figma draws — the 2px seam is the two strokes meeting, not an\naccident.\n\nThree sizes, no State axis. Every interaction state is the Input's, reached\nthrough the ordinary props, because Figma composes this from the same `Input`\ninstance rather than redrawing it.\n\nWHAT THIS DELIBERATELY DOES NOT DO\n\nIt does not pick countries. The chevron implies a menu and Figma specifies no\nopen state for it — no list, no flags, no search, no selected state. Country\ndata and the picker are application concerns with real editorial weight (which\nterritories, which names, which order), and inventing them here would be\ndesigning rather than implementing.\n\nSo the trigger is a real `<button>` with an accessible name, and\n`countryButtonProps` is how you wire it to a `Menu`, a popover or your own\nlistbox — including the `aria-haspopup` and `aria-expanded` that only the\nthing owning the popup can set honestly.",
       "import": "import { PhoneInput } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A dial-code block butted against an Input, sharing one outline. It does not pick countries.",
+      "useWhen": [
+        "collecting a phone number where the country calling code matters"
+      ],
+      "useInstead": [
+        {
+          "when": "the number is free-form and the code does not matter",
+          "use": "Input"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "prominent single-field forms"
+          }
+        }
+      },
+      "slots": {
+        "trailingIcon": {
+          "accepts": "Icon",
+          "note": "passed through to the Input"
+        },
+        "countryButtonProps": {
+          "accepts": "button props",
+          "note": "how a country picker is attached — spread your trigger's props here, including the `aria-haspopup` and `aria-expanded` only the thing owning the popup can set honestly"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the dial-code trigger is a real <button> with an accessible name",
+          "every interaction state is the Input's, reached through the ordinary Input props"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when no visible label is rendered",
+          "`countryLabel` if you change the default — the trigger shows only `+1`, which names a value rather than an action"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "expecting the chevron to open a country list",
+          "why": "the picker is deliberately not implemented — country data and ordering are editorial application decisions, and Figma specifies no open state. Wire your own through `countryButtonProps`"
+        },
+        {
+          "dont": "wrapping it in your own bordered container",
+          "why": "the block and the control already share one outline; a second border reads as two controls"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
       "stylesheet": "src/styles/phone-input.css",
       "tokens": [
         "--border-default",
@@ -3204,6 +4075,98 @@
       "propsType": "PopoverProps",
       "description": "Popover — Figma `Popover` (825:1853).\n\nSITS BETWEEN TOOLTIP AND MODAL. A tooltip is a hint that cannot hold\nfocusable content; a modal is a task that takes over the page. A popover\nholds interactive content but stays attached to the control that opened it.\n\n`usePopover` contains focus, closes on Escape or an outside click, and hides\nthe rest of the page from assistive tech while open — the same guarantees\nModal gives. What differs is the framing, and it is deliberate: no visible\nscrim, anchored to its trigger, and `surface/raised` rather than Modal's\n`surface/overlay`. It reads as attached to the page rather than replacing it.",
       "import": "import { Popover } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "An anchored panel that holds interactive content. Sits between Tooltip and Modal.",
+      "useWhen": [
+        "the content is interactive — a form, a filter, a list of actions — but should stay attached to the control that opened it",
+        "the surrounding page should stay visible and in context"
+      ],
+      "useInstead": [
+        {
+          "when": "the content is a short hint with nothing focusable in it",
+          "use": "Tooltip",
+          "why": "a tooltip cannot be focused or scrolled and closes when the pointer leaves"
+        },
+        {
+          "when": "the task takes over the page or must be completed before anything else",
+          "use": "Modal"
+        },
+        {
+          "when": "you only need the list surface and will position it yourself",
+          "use": "Menu"
+        }
+      ],
+      "variants": {
+        "placement": {
+          "top": {
+            "use": "above the trigger"
+          },
+          "bottom": {
+            "use": "below the trigger — the usual choice for a control in a header"
+          },
+          "left": {
+            "use": "to the left of the trigger"
+          },
+          "right": {
+            "use": "to the right of the trigger"
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "a couple of actions or one short field"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "a small form or a filter panel"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "Button",
+          "note": "the trigger. Must forward both a ref and DOM props — every component in this library does"
+        },
+        "content": {
+          "accepts": "any"
+        },
+        "title": {
+          "accepts": "text",
+          "note": "also gives the dialog its accessible name"
+        },
+        "footer": {
+          "accepts": "Button",
+          "note": "action row, right-aligned"
+        }
+      },
+      "a11y": {
+        "role": "dialog",
+        "guarantees": [
+          "focus is contained while open, Escape and outside clicks close it, and the rest of the page is hidden from assistive tech",
+          "`placement` is a preference, not a guarantee — it flips when there is no room, and the arrow follows"
+        ],
+        "requires": [
+          "`title`, or `aria-label` on the popover — a dialog with no name announces nothing about what opened"
+        ],
+        "notes": [
+          "`placement` names where the POPOVER sits, not where the arrow points."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a function-component trigger that drops its ref",
+          "why": "it renders, but the popover has nothing to position against"
+        },
+        {
+          "dont": "using a Popover where a Modal belongs",
+          "why": "a popover closes on an outside click; a task that must be finished should not be dismissible by a stray click"
+        },
+        {
+          "dont": "nesting a Popover inside another Popover",
+          "why": "two overlapping focus containments, and dismissing the outer one takes the inner one with it"
+        }
+      ],
       "stylesheet": "src/styles/popover.css",
       "tokens": [
         "--border-subtle",
@@ -3327,6 +4290,83 @@
       "source": "src/components/Radio.tsx",
       "propsType": "RadioProps",
       "import": "import { Radio } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One option inside a RadioGroup. Meaningless on its own — the group owns the name and the selected value.",
+      "useWhen": [
+        "a child of RadioGroup"
+      ],
+      "useInstead": [
+        {
+          "when": "the user may pick more than one",
+          "use": "Checkbox"
+        },
+        {
+          "when": "there are more than about five options",
+          "use": "Select",
+          "why": "a long radio list costs vertical space no one reads"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent choices"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "a choice with no positive reading — sort order, display mode"
+          },
+          "danger": {
+            "use": "selecting a destructive option"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the option's visible label"
+        }
+      },
+      "a11y": {
+        "role": "radio",
+        "guarantees": [
+          "`name` and the selected value come from the group's context, so no Radio has to repeat them",
+          "`isDisabled` falls back to the group's"
+        ],
+        "requires": [
+          "a `value` unique within the group",
+          "a text label in `children`"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Radio outside a RadioGroup",
+          "why": "it has no name and no siblings, so it can be selected but never unselected"
+        },
+        {
+          "dont": "wiring `checked`/`onChange` on each Radio",
+          "why": "the group owns selection; per-option wiring is what the context exists to remove"
+        },
+        {
+          "dont": "a group of one radio",
+          "why": "a single radio cannot be cleared once chosen — that is a Checkbox"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
       "stylesheet": "src/styles/radio.css",
       "tokens": [
         "--border-disabled",
@@ -3432,53 +4472,137 @@
       "propsType": "RadioGroupProps",
       "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.",
       "import": "import { RadioGroup } from 'ionbase-ui';",
-      "stylesheet": "src/styles/radio.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",
-        "--font-weight-medium",
-        "--icon-disabled",
-        "--icon-on-color",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--ion-radio-border",
-        "--ion-radio-dot",
-        "--ion-radio-fill",
-        "--ion-radio-font-size",
-        "--ion-radio-gap",
-        "--ion-radio-line-height",
-        "--ion-radio-raised",
-        "--ion-radio-size",
-        "--ion-shadow-raised-flush-lg",
-        "--ion-shadow-raised-flush-sm",
-        "--ion-shadow-raised-flush-xs",
-        "--radius-full",
-        "--spacing-12",
-        "--spacing-16",
-        "--spacing-2",
-        "--spacing-20",
-        "--spacing-24",
-        "--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"
+      "status": "stable",
+      "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value.",
+      "useWhen": [
+        "exactly one choice from a small set, all worth showing at once",
+        "the options need explaining — each one can carry its own label text"
       ],
-      "props": {
+      "useInstead": [
+        {
+          "when": "the list is long, or space is tight",
+          "use": "Select"
+        },
+        {
+          "when": "more than one may be picked",
+          "use": "Checkbox"
+        },
+        {
+          "when": "there are exactly two states and the change is immediate",
+          "use": "Toggle"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent choices"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "a choice with no positive reading — sort order, display mode"
+          },
+          "danger": {
+            "use": "a set where the options are destructive"
+          }
+        }
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "renders as the <legend> — the question the options answer"
+        },
+        "children": {
+          "accepts": "Radio"
+        }
+      },
+      "a11y": {
+        "role": "group, from <fieldset> and <legend>",
+        "guarantees": [
+          "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
+          "`name` is generated when omitted, so two groups on one page never collide",
+          "`isDisabled` cascades to every Radio that has not set its own"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when the question is already visible elsewhere"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "an unlabelled group",
+          "why": "the options are announced with no question attached"
+        },
+        {
+          "dont": "passing both `value` and `defaultValue`",
+          "why": "controlled and uncontrolled at once; the controlled value wins and `defaultValue` silently does nothing"
+        },
+        {
+          "dont": "no option selected by default with no \"none\" option",
+          "why": "a radio group cannot be returned to empty once touched"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
+      "stylesheet": "src/styles/radio.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",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-on-color",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-radio-border",
+        "--ion-radio-dot",
+        "--ion-radio-fill",
+        "--ion-radio-font-size",
+        "--ion-radio-gap",
+        "--ion-radio-line-height",
+        "--ion-radio-raised",
+        "--ion-radio-size",
+        "--ion-shadow-raised-flush-lg",
+        "--ion-shadow-raised-flush-sm",
+        "--ion-shadow-raised-flush-xs",
+        "--radius-full",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-20",
+        "--spacing-24",
+        "--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": {
         "name": {
           "type": "string | undefined",
           "required": false,
@@ -3558,6 +4682,47 @@
       "propsType": "ScrollProgressProps",
       "description": "The compact rail is the disclosure trigger. It is a real `<button>`, so a\nkeyboard user reaches it by Tab and opens it the same way as any button —\nEnter or Space — no `:focus-within` trick required; a mouse user can also\njust hover it. Built as a WAI-ARIA Disclosure (`aria-expanded` +\n`aria-controls`) rather than a menu: see the CSS header for why\n`role=\"menu\"` is deliberately not used here.\n\nCloses on outside pointerdown and on Escape — the minimum a disclosure\nneeds to not trap the page once opened, not a full popover/focus-trap\nimplementation.",
       "import": "import { ScrollProgress } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A compact progress rail that expands into a section list. A disclosure, not a menu — and it computes nothing itself.",
+      "useWhen": [
+        "a long document or page needs an in-page section index with reading progress",
+        "the caller already knows the scroll fraction and the active section"
+      ],
+      "useInstead": [
+        {
+          "when": "the sections are peer views rather than positions in one document",
+          "use": "Tabs"
+        },
+        {
+          "when": "it is site navigation rather than in-page position",
+          "use": "NavItem"
+        }
+      ],
+      "a11y": {
+        "role": "disclosure — a real <button> with aria-expanded and aria-controls",
+        "guarantees": [
+          "the rail is reachable by Tab and opens with Enter or Space, not just hover",
+          "closes on outside pointerdown and on Escape"
+        ],
+        "requires": [
+          "`progress` as 0–100 and `activeId` — the component has no opinion on where they come from",
+          "handling `onSelect` yourself: it reports the choice and does not scroll anywhere"
+        ],
+        "notes": [
+          "Deliberately not `role=\"menu\"` — see the stylesheet header. It is a disclosure with a list inside it, not a menu with roving focus.",
+          "Not a focus trap: it is the minimum a disclosure needs to not trap the page once opened."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "expecting it to scroll the page when a section is chosen",
+          "why": "it reports the choice, matching Menu — what \"select this section\" means is the page's decision"
+        },
+        {
+          "dont": "deriving `progress` from a scroll listener without throttling",
+          "why": "this re-renders the rail on every scroll frame"
+        }
+      ],
       "stylesheet": "src/styles/scroll-progress.css",
       "tokens": [
         "--border-default",
@@ -3815,6 +4980,48 @@
       "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Item.d.ts",
       "propsType": null,
       "import": "import { TabItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One tab and its panel. Re-exported from react-stately's collection Item — `title` is the tab label, children are the panel.",
+      "useWhen": [
+        "a child of Tabs — it is not usable anywhere else"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a row in a dropdown list",
+          "use": "MenuItem"
+        },
+        {
+          "when": "it is a navigation destination",
+          "use": "NavItem"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Tabs",
+          "TabItem"
+        ],
+        "note": "A collection item, not a rendered component: Tabs reads it to build the collection, so it never appears in the DOM itself. That is why it exposes no props of its own here — `key` and `title` are the collection's API.",
+        "example": "<TabItem key=\"billing\" title=\"Billing\">Billing panel content</TabItem>"
+      },
+      "a11y": {
+        "guarantees": [
+          "the tab/panel roles, ids and aria-controls pairing are supplied by Tabs, not by this element"
+        ],
+        "requires": [
+          "a stable `key` — it identifies the tab across renders and is what selection is expressed in",
+          "a `title` that reads as a label on its own"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "wrapping TabItem in a <div> or a fragment inside Tabs",
+          "why": "Tabs reads the collection from its direct children; a wrapper makes the item invisible to it"
+        },
+        {
+          "dont": "conditionally rendering TabItems with array indexes as keys",
+          "why": "selection is tracked by key, so the selected tab silently becomes a different tab"
+        }
+      ],
       "stylesheet": null,
       "tokens": [],
       "props": {},
@@ -3965,6 +5172,42 @@
       "source": "src/components/Table.tsx",
       "propsType": null,
       "import": "import { TableBody } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The <tbody> section. Takes no props — it places the data rows and gives their cells body context.",
+      "useWhen": [
+        "every Table — the data rows go here"
+      ],
+      "useInstead": [
+        {
+          "when": "the row names the columns",
+          "use": "TableHead"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Table",
+          "TableBody",
+          "TableRow",
+          "TableCell"
+        ],
+        "note": "Zebra striping is read from each row's position inside this section rather than a prop repeated on every TableRow.",
+        "example": "<TableBody><TableRow><TableCell>Ada</TableCell></TableRow></TableBody>"
+      },
+      "a11y": {
+        "guarantees": [
+          "cells inside it default to <td>, and `scope` is inferred as `row` when a cell is marked `header`"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "rendering rows directly under Table with no TableBody",
+          "why": "the browser inserts a tbody anyway, but the head-or-body context does not exist, so cells cannot infer their scope"
+        },
+        {
+          "dont": "an empty TableBody with no empty state",
+          "why": "an empty table looks like a broken one — Table has no empty state of its own, so it is the caller's"
+        }
+      ],
       "stylesheet": "src/styles/table.css",
       "tokens": [
         "--border-default",
@@ -4009,6 +5252,89 @@
       "propsType": "TableCellProps",
       "description": "One component covers Figma's `Table Cell` + `Cell Text`: the two are never\nused apart in the design (`Table Cell` always wraps exactly one `Cell\nText`), so splitting them into two exported components would only add API\nsurface for a composition nothing ever varies independently.\n\n`header` decides `<th>` vs `<td>` directly rather than a `type` prop that\ncould disagree with where the cell actually sits — a `<th>` rendered inside\n`<tbody>` is still a header cell to the browser and to CSS either way.",
       "import": "import { TableCell } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "One cell, covering Figma's Table Cell and Cell Text together. `header` decides <th> versus <td>.",
+      "useWhen": [
+        "every cell in a Table, header or data"
+      ],
+      "useInstead": [
+        {
+          "when": "the content is a status label",
+          "use": "Badge",
+          "why": "put it inside the cell — the cell is the container, not the label"
+        }
+      ],
+      "variants": {
+        "scope": {
+          "col": {
+            "use": "a column header — inferred inside TableHead"
+          },
+          "row": {
+            "use": "a row header, e.g. the name column — inferred for a `header` cell in TableBody"
+          },
+          "colgroup": {
+            "use": "a header spanning several columns, with colspan"
+          },
+          "rowgroup": {
+            "use": "a header spanning several rows, with rowspan"
+          }
+        },
+        "align": {
+          "leading": {
+            "use": "the default — text, names, identifiers"
+          },
+          "trailing": {
+            "use": "numbers, currency and dates, so digits line up column-wise"
+          },
+          "center": {
+            "use": "icons, short status marks, checkboxes"
+          }
+        },
+        "variant": {
+          "default": {
+            "use": "the default — body text and icon colours"
+          },
+          "link": {
+            "use": "recolours the content to `text/link` / `icon/primary` for a cell whose content navigates"
+          }
+        }
+      },
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "leading icon; omit its `label`"
+        },
+        "trailingIcon": {
+          "accepts": "Icon",
+          "note": "trailing icon; same rule"
+        },
+        "children": {
+          "accepts": "any"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "`scope` is inferred when omitted — `col` in TableHead, `row` in TableBody — and can be set explicitly when the inference is wrong",
+          "`header` decides the element directly rather than a `type` prop that could disagree with where the cell sits"
+        ],
+        "requires": [
+          "`scope=\"col\"` on header cells — inferred inside TableHead, but explicit for a header rendered outside it"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`variant=\"link\"` on a cell with no link in it",
+          "why": "link-coloured text that does nothing is the clearest possible false affordance"
+        },
+        {
+          "dont": "leading-aligning a numeric column",
+          "why": "digits stop lining up, so the column can no longer be scanned for magnitude"
+        },
+        {
+          "dont": "`showDivider` on every cell",
+          "why": "it is a column rule, not a row rule — on every cell it becomes a grid"
+        }
+      ],
       "stylesheet": "src/styles/table.css",
       "tokens": [
         "--border-default",
@@ -4113,6 +5439,45 @@
       "source": "src/components/Table.tsx",
       "propsType": null,
       "import": "import { TableHead } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "The <thead> section. Takes no props — it places the header row and gives its cells their head-or-body context.",
+      "useWhen": [
+        "every Table with column headers, which is every data table"
+      ],
+      "useInstead": [
+        {
+          "when": "the rows are data",
+          "use": "TableBody"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Table",
+          "TableHead",
+          "TableRow",
+          "TableCell"
+        ],
+        "note": "Exists so TableRow and TableCell can tell head from body through context, rather than the caller repeating a prop that has to stay in sync with where the row actually sits.",
+        "example": "<TableHead><TableRow><TableCell scope=\"col\">Name</TableCell></TableRow></TableHead>"
+      },
+      "a11y": {
+        "guarantees": [
+          "cells inside it default to <th scope=\"col\">, and a row-selection cell becomes the select-all header"
+        ],
+        "requires": [
+          "a header row for every data table — without one, no data cell has a column to be associated with"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a data table with no TableHead",
+          "why": "a screen-reader user hears values with no field names"
+        },
+        {
+          "dont": "styling a first TableBody row to look like a header",
+          "why": "it looks like a header and announces as data"
+        }
+      ],
       "stylesheet": "src/styles/table.css",
       "tokens": [
         "--border-default",
@@ -4157,6 +5522,51 @@
       "propsType": "TableRowProps",
       "description": "A plain `<tr>`. Hover is CSS-only (`:hover` plus a `data-hovered` escape\nhatch, matching the rest of the system) rather than React Aria's\n`useHover`: a row is not itself an interactive element — nothing about it\ntakes focus or fires a click — so there is no keyboard-vs-pointer\ndistinction to track. A clickable row is a link or button inside a cell,\nthe same accessible pattern Menu and Table Cell's own link variant use;\nnesting an interactive role on `<tr>` itself is not valid HTML.",
       "import": "import { TableRow } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A plain <tr>. Hover is CSS-only; a row is not itself interactive.",
+      "useWhen": [
+        "every row, in either TableHead or TableBody"
+      ],
+      "useInstead": [
+        {
+          "when": "the whole row should be clickable",
+          "use": "Link",
+          "why": "put the link or Button in a cell — nesting an interactive role on <tr> is not valid HTML"
+        }
+      ],
+      "slots": {
+        "selection": {
+          "accepts": "Checkbox props",
+          "note": "renders a leading Checkbox cell — a <th scope=\"col\"> select-all inside TableHead, a <td> inside TableBody. Takes the checkbox's own props rather than a boolean, since a selectable row needs `checked`/`onChange` wiring"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "hover comes from CSS `:hover` plus a `data-hovered` escape hatch, not React Aria — a row takes no focus and fires no click, so there is no keyboard-versus-pointer distinction to track",
+          "the selection cell's element follows the section it sits in"
+        ],
+        "requires": [
+          "every row-selection Checkbox to be labelled — those boxes have no visible label by design, so see Checkbox's own contract",
+          "`isSelected` alongside a checked selection checkbox, so the row's state is not carried by colour alone"
+        ],
+        "notes": [
+          "TableRow itself is never named — a <tr> is not an interactive element and takes no accessible name. The naming requirement above belongs to the Checkbox inside it."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`onClick` on TableRow",
+          "why": "it takes no focus, so a keyboard user can never fire it"
+        },
+        {
+          "dont": "`selection={{ checked }}` with no `onChange`",
+          "why": "a checkbox that cannot be changed reads as broken rather than as disabled"
+        },
+        {
+          "dont": "`isSelected` without a selection checkbox",
+          "why": "the row is tinted with nothing announcing why"
+        }
+      ],
       "stylesheet": "src/styles/table.css",
       "tokens": [
         "--border-default",
@@ -4212,6 +5622,91 @@
       "source": "src/components/Tabs.tsx",
       "propsType": "TabsProps",
       "import": "import { Tabs } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A tab list and its panels, built on react-aria's tab collection. Children are TabItem.",
+      "useWhen": [
+        "one region of the page shows one of several peer views, and only one at a time",
+        "the views are peers — no ordering, no progression between them"
+      ],
+      "useInstead": [
+        {
+          "when": "the steps must be completed in order",
+          "use": "Button",
+          "why": "tabs imply peers you may visit in any order; a wizard is a sequence"
+        },
+        {
+          "when": "the sections should all be readable at once, or printable",
+          "use": "Divider",
+          "why": "tabs hide everything but the active panel, including from Ctrl-F"
+        },
+        {
+          "when": "it is navigation between pages rather than panels within one",
+          "use": "NavItem"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Tabs",
+          "TabItem"
+        ],
+        "note": "TabItem comes from react-stately's collection Item — it takes no props of its own beyond `title` (the tab label) and `key`; its children are the panel.",
+        "example": "<Tabs aria-label=\"Account\"><TabItem key=\"profile\" title=\"Profile\">…</TabItem><TabItem key=\"billing\" title=\"Billing\">…</TabItem></Tabs>"
+      },
+      "variants": {
+        "type": {
+          "pill": {
+            "use": "the default — a filled track, for switching views inside a panel or card"
+          },
+          "underline": {
+            "use": "a rule under the active tab, for page-level sections"
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "dense panels and toolbars"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "page-level section switching"
+          }
+        },
+        "orientation": {
+          "horizontal": {
+            "use": "the default"
+          },
+          "vertical": {
+            "use": "a stacked track with up/down arrow keys",
+            "caveat": "keyboard and ARIA are complete, but the decoration is not — the underline rule and the pill track's padding are still written for the horizontal axis. Figma has not specified the vertical drawing"
+          }
+        }
+      },
+      "a11y": {
+        "role": "tablist / tab / tabpanel",
+        "guarantees": [
+          "roving tabindex, arrow-key navigation and the aria-controls/aria-labelledby pairing between each tab and its panel come from react-aria",
+          "the focus ring shows for keyboard focus only, and hover does not latch on touch"
+        ],
+        "requires": [
+          "`aria-label` or `aria-labelledby` on Tabs — the tab list is a named region",
+          "a stable `key` on every TabItem"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "tabs whose panels the user must read in order",
+          "why": "the role announces peers, and nothing stops a user landing on the last one first"
+        },
+        {
+          "dont": "hiding required form fields behind a tab",
+          "why": "a validation error in an inactive panel is invisible; the user is told the form is invalid with nothing on screen to fix"
+        },
+        {
+          "dont": "one tab",
+          "why": "a tablist with a single tab is chrome with no choice in it"
+        }
+      ],
       "stylesheet": "src/styles/tabs.css",
       "tokens": [
         "--border-default",
@@ -4399,6 +5894,87 @@
       "propsType": "ToastProps",
       "description": "Toast — Figma `Toast` (820:1655).\n\nNeutral chrome on `surface/raised`; the intent is carried by the icon alone.\nA tinted panel floating over unknown content competes with whatever is\nbehind it, and makes Toast and Alert indistinguishable at a glance.\n\nAUTO-DISMISS PAUSES ON HOVER AND FOCUS. A toast that keeps counting down\nwhile being read or while its action has keyboard focus takes the action\naway mid-reach — WCAG 2.2.1 asks for exactly this. The timer restarts rather\nthan resumes, which is the forgiving direction.",
       "import": "import { Toast } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A transient notification on neutral chrome. Intent is carried by the icon, not by a tinted panel.",
+      "useWhen": [
+        "confirming that something the user just did succeeded or failed",
+        "the message is short, transient, and not required to complete a task"
+      ],
+      "useInstead": [
+        {
+          "when": "the message must stay until the condition is resolved",
+          "use": "Alert",
+          "why": "a toast disappears, and anything the user must act on should not"
+        },
+        {
+          "when": "the message belongs to one field",
+          "use": "Input",
+          "why": "Input's error text sits with the field it is about"
+        },
+        {
+          "when": "you need a decision from the user",
+          "use": "Modal",
+          "why": "a toast offers one action and takes it away on a timer"
+        }
+      ],
+      "variants": {
+        "intent": {
+          "neutral": {
+            "use": "a plain fact with no status attached"
+          },
+          "primary": {
+            "use": "brand-flavoured confirmations"
+          },
+          "success": {
+            "use": "the action completed"
+          },
+          "warning": {
+            "use": "it completed with a caveat worth knowing"
+          },
+          "error": {
+            "use": "it failed — pair with a way to retry"
+          },
+          "information": {
+            "use": "the default — a neutral update"
+          }
+        }
+      },
+      "slots": {
+        "title": {
+          "accepts": "text"
+        },
+        "message": {
+          "accepts": "text"
+        },
+        "action": {
+          "accepts": "{ label, onPress }",
+          "note": "exactly one action. A second choice belongs in a Modal, which will still be there"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "auto-dismiss pauses on hover and on focus, and restarts rather than resumes — WCAG 2.2.1, and the forgiving direction",
+          "announcement comes from ToastProvider's live region, which is always present rather than appearing with its content"
+        ],
+        "requires": [
+          "rendering inside a ToastProvider — a Toast on its own is not in a live region",
+          "`duration={null}` when the message carries an action the user genuinely needs"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a toast for an error the user must fix",
+          "why": "it vanishes; the fix does not"
+        },
+        {
+          "dont": "two actions in one toast",
+          "why": "a timed choice is not a choice"
+        },
+        {
+          "dont": "stacking several toasts for one operation",
+          "why": "the stack covers the page and the last one is the only one read"
+        }
+      ],
       "stylesheet": "src/styles/toast.css",
       "tokens": [
         "--border-subtle",
@@ -4504,6 +6080,63 @@
       "propsType": "ToastProviderProps",
       "description": "Renders the queue and supplies `useToast`.\n\nThe live region is the CONTAINER, declared once and always present. A region\nthat appears at the same moment as its content is not reliably announced —\nassistive tech has to be watching the node before the text lands in it.",
       "import": "import { ToastProvider } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Renders the toast queue and supplies the `useToast` hook. Mount once, near the app root.",
+      "useWhen": [
+        "the app shows toasts anywhere — this is the only way to get `useToast`"
+      ],
+      "useInstead": [
+        {
+          "when": "you only need one persistent in-page message",
+          "use": "Alert",
+          "why": "no provider, no queue, and it stays put"
+        }
+      ],
+      "variants": {
+        "placement": {
+          "top-left": {
+            "use": "rare — for RTL layouts or where the top-right is occupied"
+          },
+          "top-right": {
+            "use": "the common desktop choice, out of the way of primary content"
+          },
+          "bottom-left": {
+            "use": "keeps toasts clear of a right-hand panel"
+          },
+          "bottom-right": {
+            "use": "close to where a save or submit action usually sits"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "any",
+          "note": "your app — the provider wraps it"
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the live region is the container, declared once and always present — a region that appears at the same moment as its content is not reliably announced",
+          "`limit` drops the oldest toasts, so the stack can never cover the page"
+        ],
+        "requires": [
+          "mounting exactly one ToastProvider — a second live region competes with the first"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "mounting a ToastProvider per route or per page",
+          "why": "toasts queued before the switch are unmounted mid-announcement, and two live regions announce over each other"
+        },
+        {
+          "dont": "placing it inside a Modal",
+          "why": "the toasts are removed from the tree when the modal closes, and hidden from assistive tech while it is open"
+        },
+        {
+          "dont": "raising `limit` to keep everything",
+          "why": "an unbounded stack covers the content the toasts are about"
+        }
+      ],
       "stylesheet": "src/styles/toast.css",
       "tokens": [
         "--border-subtle",
@@ -4579,6 +6212,82 @@
       "propsType": "ToggleProps",
       "description": "Toggle is a checkbox with `role=\"switch\"`.\n\nNot a button with aria-pressed: a switch is a form value, and the checkbox\ngives form association and `:checked` for free. `role=\"switch\"` changes only\nhow it is announced — \"on/off\" rather than \"checked/unchecked\" — which is\nwhat Figma's On/Off states describe.\n\nThe visual difference from Checkbox is entirely in CSS; this component and\nCheckbox are near-identical by design rather than by accident, and are kept\napart because Figma models them as separate components with separate size\nramps.",
       "import": "import { Toggle } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A switch — a checkbox with role=\"switch\", announced as on/off.",
+      "useWhen": [
+        "the change takes effect immediately: a setting, a feature flag, a preference"
+      ],
+      "useInstead": [
+        {
+          "when": "the value is collected and submitted with a form",
+          "use": "Checkbox",
+          "why": "a switch reads as taking effect now; a checkbox reads as a value being gathered"
+        },
+        {
+          "when": "there are more than two states",
+          "use": "RadioGroup"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense settings rows and table filters"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent single settings"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "a setting with no positive or negative reading — display and layout preferences"
+          },
+          "danger": {
+            "use": "turning on something destructive or hard to undo"
+          }
+        }
+      },
+      "slots": {
+        "children": {
+          "accepts": "text",
+          "note": "the visible label; omit for a bare switch and supply `aria-label`"
+        }
+      },
+      "a11y": {
+        "role": "switch",
+        "guarantees": [
+          "a real <input type=\"checkbox\"> underneath, so form association, label clicking and `:checked` come from the platform",
+          "`role=\"switch\"` changes only the announcement — \"on/off\" rather than \"checked/unchecked\""
+        ],
+        "requires": [
+          "`children`, or `aria-label` when there is no visible label"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Toggle with a Save button beside it",
+          "why": "a switch says the change is already applied; if it needs saving it is a Checkbox"
+        },
+        {
+          "dont": "labelling a Toggle \"Enable dark mode?\" as a question",
+          "why": "a switch label names the thing being switched, not a question about it"
+        },
+        {
+          "dont": "a button with `aria-pressed` for a setting",
+          "why": "a switch is a form value; the checkbox gives form association and `:checked` for free"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
       "stylesheet": "src/styles/toggle.css",
       "tokens": [
         "--border-disabled",
@@ -4681,6 +6390,80 @@
       "propsType": "TooltipProps",
       "description": "Tooltip — Figma `Tooltip` (801:1568).\n\nWraps its trigger rather than taking a ref, so the common case is one\nelement deep: `<Tooltip label=\"...\"><Button/></Tooltip>`.\n\nFOCUS OPENS IT, NOT JUST HOVER. A hover-only tooltip is invisible to keyboard\nand switch users, and `useTooltipTrigger` wires both plus Escape to dismiss.\nIt also enforces one open tooltip at a time and a shared warmup, so moving\nalong a row of icon buttons does not flash a tooltip per button.\n\nThe trigger is cloned with the interaction props and a ref, which means it\nmust forward both. Every component in this library does; a bare `<div>` does\ntoo. A function component that drops its ref will render, but the tooltip\nwill have nothing to position against.",
       "import": "import { Tooltip } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A text-only hint attached to a trigger. Opens on hover and on focus.",
+      "useWhen": [
+        "naming an icon-only control",
+        "adding a short clarification that is genuinely optional to read"
+      ],
+      "useInstead": [
+        {
+          "when": "the content has anything focusable in it — a link, a button, a field",
+          "use": "Popover",
+          "why": "a tooltip cannot be focused, cannot be scrolled, and closes the moment the pointer leaves"
+        },
+        {
+          "when": "the information is required to complete the field",
+          "use": "Input",
+          "why": "Input's helper text is always visible; a tooltip is not discoverable on touch"
+        }
+      ],
+      "variants": {
+        "placement": {
+          "top": {
+            "use": "above the trigger — the default reading position"
+          },
+          "bottom": {
+            "use": "below the trigger, for something near the top of the viewport"
+          },
+          "left": {
+            "use": "to the left of the trigger"
+          },
+          "right": {
+            "use": "to the right of the trigger"
+          }
+        }
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "the hint. Text only"
+        },
+        "title": {
+          "accepts": "text",
+          "note": "optional heading above the label"
+        },
+        "children": {
+          "accepts": "Button",
+          "note": "the trigger. Must forward both a ref and DOM props"
+        }
+      },
+      "a11y": {
+        "role": "tooltip",
+        "guarantees": [
+          "focus opens it, not only hover — a hover-only tooltip is invisible to keyboard and switch users",
+          "Escape dismisses it",
+          "one tooltip open at a time with a shared warmup, so moving along a row of icon buttons does not flash one per button",
+          "`placement` flips to the opposite side when there is no room"
+        ],
+        "requires": [
+          "a trigger that is already labelled for icon-only controls — Tooltip supplies the hint, not the trigger's name"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "putting a link or button inside `label`",
+          "why": "it cannot be reached — the tooltip closes when the pointer leaves the trigger"
+        },
+        {
+          "dont": "a tooltip as the only place information appears",
+          "why": "it is undiscoverable on touch, where there is no hover"
+        },
+        {
+          "dont": "a tooltip on a disabled Button",
+          "why": "a disabled button takes no focus and often no pointer events, so the hint never appears for a keyboard user"
+        }
+      ],
       "stylesheet": "src/styles/tooltip.css",
       "tokens": [
         "--font-family-sans",