@ratio-ui/core 0.1.1 → 0.3.0

package/dist/catalogue.json

@@ -1,132 +1,2642 @@
 {
-  "version": "0.1.1",
+  "version": "0.3.0",
   "components": [
+    {
+      "name": "Alert",
+      "import": "import { Alert } from '@ratio-ui/core'",
+      "description": "A message that stays in the page: a tone glyph, an optional title and description, and an optional action.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"critical\" | \"info\" | \"success\" | \"warning\"",
+          "required": false,
+          "default": "info",
+          "description": "The tone. Defaults to info."
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional bold first line."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second line."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional action on the right, usually one Button."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered div."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A message that sits in the page and stays until the cause is gone: a banner above a form, a notice in a card\n- Four tones: info, success, warning, critical (question 1 tokens: no fill, strong border, warning glyph)",
+        "whenNotToUse": "- A message that disappears by itself: use Toaster\n- A confirmation before a destructive step: use AlertDialog\n- A field error: say it in one clause under the field",
+        "example": "```tsx\n<Alert\n  tone=\"critical\"\n  title=\"Payment failed\"\n  description=\"Try another method.\"\n  action={<Button>Retry</Button>}\n/>\n```\n\nInfo and success have role status (polite); warning and critical have role alert (assertive)."
+      }
+    },
+    {
+      "name": "AlertDialog",
+      "import": "import { AlertDialog } from '@ratio-ui/core'",
+      "description": "The root of a confirmation. It holds the open state and renders nothing itself. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to leave it uncontrolled. Escape closes it; a click outside does not.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A confirm step before deleting something, or before a money action such as a refund\n- An answer that must be given: Escape closes it, a click outside does not\n- A short question that fits in 480px: the panel is fixed at that width, with a ring outline and no scrim",
+        "whenNotToUse": "- A form or any input: use Dialog\n- A message after an action: use toast()\n- A reversible action: do it and offer undo instead",
+        "example": "```tsx\n<AlertDialog>\n  <AlertDialogTrigger>Delete product</AlertDialogTrigger>\n  <AlertDialogContent>\n    <AlertDialogHeader>\n      <AlertDialogTitle>Delete this product?</AlertDialogTitle>\n      <AlertDialogDescription>It leaves the storefront at once.</AlertDialogDescription>\n    </AlertDialogHeader>\n    <AlertDialogFooter>\n      <AlertDialogCancel>Cancel</AlertDialogCancel>\n      <AlertDialogAction>Delete</AlertDialogAction>\n    </AlertDialogFooter>\n  </AlertDialogContent>\n</AlertDialog>\n```\n\n- `AlertDialogAction` is the Button's destructive variant and closes the dialog after `onClick` runs. Pass `variant=\"main\"` for a non-destructive confirmation such as a refund. For an async action that must stay open until it finishes, control the dialog with `open` and `onOpenChange`.\n- `AlertDialogCancel` is the secondary Button and closes the dialog.\n- Name the action with the verb (\"Delete\", \"Refund\"), never \"OK\". Put the amount in the title for money actions, formatted with the format helpers."
+      },
+      "parts": [
+        {
+          "name": "AlertDialogAction",
+          "import": "import { AlertDialogAction } from '@ratio-ui/core'",
+          "description": "The confirming button. It is the Button's destructive variant and closes the dialog after its onClick runs.",
+          "props": [
+            {
+              "name": "variant",
+              "type": "\"destructive\" | \"main\"",
+              "required": false,
+              "default": "destructive",
+              "description": "The Button look. Defaults to destructive; use main for a confirmation that deletes nothing."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogCancel",
+          "import": "import { AlertDialogCancel } from '@ratio-ui/core'",
+          "description": "The secondary button that closes the dialog without doing anything.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogContent",
+          "import": "import { AlertDialogContent } from '@ratio-ui/core'",
+          "description": "The panel: 480px wide, white, drawn with the ring outline and no shadow, with no scrim behind it. Put AlertDialogHeader and AlertDialogFooter inside.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogDescription",
+          "import": "import { AlertDialogDescription } from '@ratio-ui/core'",
+          "description": "What will happen, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogFooter",
+          "import": "import { AlertDialogFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom, aligned to the end.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogHeader",
+          "import": "import { AlertDialogHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "AlertDialogTitle",
+          "import": "import { AlertDialogTitle } from '@ratio-ui/core'",
+          "description": "The question, in the b4 style. It names the dialog for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "AlertDialogTrigger",
+          "import": "import { AlertDialogTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the confirmation.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "AppShell",
+      "import": "import { AppShell } from '@ratio-ui/core'",
+      "description": "The frame of every page: the side nav at the left, the top bar above and the content below it. It fills the height of its container, so the app gives it a height and the content scrolls beside the side nav and under the top bar. The parts are slots, so the shell does not depend on their components. On a phone the side nav is a drawer: the menu button in TopBar opens it, and Escape or choosing a row closes it.",
+      "props": [
+        {
+          "name": "sideNav",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The side navigation, for example SideNav. It sits at the left of the top bar and the content."
+        },
+        {
+          "name": "topBar",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The top bar, for example TopBar. It spans the width beside the side nav."
+        },
+        {
+          "name": "navOpen",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the side navigation drawer is open on a phone. Set it with onNavOpenChange to control the drawer."
+        },
+        {
+          "name": "defaultNavOpen",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the drawer starts open on a phone when navOpen is not set. Defaults to false."
+        },
+        {
+          "name": "onNavOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "Called when the drawer asks to open or close on a phone: the menu button in TopBar, Escape, or choosing a row."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The page content, centred in a column that is 1152px wide at most."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The frame of an admin page: side nav, top bar and content\n- Content that should be at most 1152px wide and centred",
+        "whenNotToUse": "- A page without the admin chrome, such as sign in\n- Spacing inside the content: use Stack",
+        "example": "<AppShell sideNav={<SideNav />} topBar={<TopBar />}>\n  <PageHeader title=\"Products\" />\n</AppShell>"
+      }
+    },
+    {
+      "name": "Avatar",
+      "import": "import { Avatar } from '@ratio-ui/core'",
+      "description": "A picture or the initials of a person or a store: round for people, square for stores.",
+      "props": [
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "The full name of the person or store. It is the accessible label, and its first letters are the initials."
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "required": false,
+          "description": "The address of a picture. The initials show until it loads and when it fails."
+        },
+        {
+          "name": "shape",
+          "type": "\"round\" | \"square\"",
+          "required": false,
+          "default": "round",
+          "description": "Round for a person, square for a store. Defaults to round."
+        },
+        {
+          "name": "size",
+          "type": "\"default\" | \"lg\" | \"sm\"",
+          "required": false,
+          "default": "default",
+          "description": "Defaults to default, which is 32px."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The identity of a person (round) or a store (square), in the top bar, account menu or a list\n- A picture with the initials as fallback while it loads or when it fails",
+        "whenNotToUse": "- A generic icon or logo that is not an identity: use Icon\n- A status marker: use StatusPill",
+        "example": "<Avatar name=\"My Store\" shape=\"square\" />\n<Avatar name=\"Kavya Singh\" />"
+      }
+    },
+    {
+      "name": "Button",
+      "import": "import { Button } from '@ratio-ui/core'",
+      "description": "The design system's 28px button in five looks: main, secondary, ghost, link and destructive. Hover and pressed change the fill only, disabled is 50% opacity and the colours fade in 120ms. Put an Icon beside the label, or use iconOnly with an aria-label. It has no size prop: 28px is the only height.",
+      "props": [
+        {
+          "name": "iconOnly",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Draws a 28px square for one icon. Needs aria-label, because there is no text to name the button."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The label, optionally with an Icon beside it. One Icon."
+        },
+        {
+          "name": "variant",
+          "type": "\"destructive\" | \"ghost\" | \"link\" | \"main\" | \"secondary\"",
+          "required": false,
+          "default": "main",
+          "description": "The look of the button. Defaults to main."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLButtonElement>",
+          "required": false,
+          "description": "Gives the button back to the caller's ref."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of an icon-only button."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The main action of a view, once per page header or table toolbar: variant main\n- A second action beside it, such as Export: variant secondary\n- Quiet actions like Cancel: ghost. Navigation inside running text or a card: link\n- A delete or remove action: destructive, followed by a confirm step\n- A single icon action, such as add or close: iconOnly with an aria-label",
+        "whenNotToUse": "- A choice among options that filters a list: use FilterTabs\n- Going to another page from a menu: use the menu's own items\n- A different height: Button is 28px only, with no size prop\n- Styling: Button takes no `className` and no `style`",
+        "example": "<Stack gap={8}>\n  <Button><Icon name=\"plus\" />Add customer</Button>\n  <Button variant=\"secondary\">Export</Button>\n  <Button iconOnly variant=\"ghost\" aria-label=\"Add\"><Icon name=\"plus\" /></Button>\n</Stack>"
+      }
+    },
+    {
+      "name": "Calendar",
+      "import": "import { Calendar } from '@ratio-ui/core'",
+      "description": "A month grid to pick a day or a range of days, drawn by the design system: 28px days with a 6px radius, today in the accent ink, the selected day filled with the accent, a range as accent ends on a tinted band, disabled days at 50% and the days of the months around it in the muted ink. Every day is named in the format module's date order (28/10/2026). Arrow keys move between days and the previous and next buttons between months. It has no fill of its own, so it sits in a popover or a container as drawn.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Picking one day, such as a \"Best before\" date, inside a popover or a form: `mode=\"single\"`\n- Picking a range of days, such as an analytics period: `mode=\"range\"`, with `numberOfMonths={2}` for a wide range\n- Limiting the days that can be picked: `disabled` (for example `{ before: today }`), `startMonth` and `endMonth`",
+        "whenNotToUse": "- A date field people type into: use DatePicker or DateRangePicker, which open this calendar in a popover\n- Showing a date as text: write it with the format module, never with a calendar\n- Styling: Calendar takes no `className`, `classNames`, `style`, `components` or `formatters`; dates are written in the format module's order (28/10/2026)",
+        "example": "const [day, setDay] = useState<Date | undefined>()\n\n<Calendar mode=\"single\" selected={day} onSelect={setDay} disabled={{ before: new Date() }} />"
+      }
+    },
+    {
+      "name": "Card",
+      "import": "import { Card } from '@ratio-ui/core'",
+      "description": "A container for a panel of content: a 1px hairline border on white, no shadow and 24px of padding. The design system has no cards, so this is only the hairline container.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A panel of related content that needs a boundary, such as a settings group or a metric with its notes\n- With a title in B4 and, optionally, a description, content and a footer of actions",
+        "whenNotToUse": "- Page content that needs no boundary: it sits directly on white\n- A menu or popup: those have no shadow either, but they are not cards",
+        "example": "<Card>\n  <CardHeader>\n    <CardTitle>Payout account</CardTitle>\n    <CardDescription>Where settlements are paid</CardDescription>\n  </CardHeader>\n  <CardContent>HDFC ending 4021</CardContent>\n</Card>"
+      },
+      "parts": [
+        {
+          "name": "CardHeader",
+          "import": "import { CardHeader } from '@ratio-ui/core'",
+          "description": "The top of a card: its title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "CardTitle",
+          "import": "import { CardTitle } from '@ratio-ui/core'",
+          "description": "The title of a card, set in the B4 text style.",
+          "props": [
+            {
+              "name": "as",
+              "type": "\"div\" | \"h2\" | \"h3\" | \"h4\"",
+              "required": false,
+              "default": "h3",
+              "description": "The heading element. Defaults to h3."
+            }
+          ]
+        },
+        {
+          "name": "CardDescription",
+          "import": "import { CardDescription } from '@ratio-ui/core'",
+          "description": "A line under the title that says what the card holds.",
+          "props": []
+        },
+        {
+          "name": "CardContent",
+          "import": "import { CardContent } from '@ratio-ui/core'",
+          "description": "The body of a card.",
+          "props": []
+        },
+        {
+          "name": "CardFooter",
+          "import": "import { CardFooter } from '@ratio-ui/core'",
+          "description": "The foot of a card, a row for its actions.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "Checkbox",
+      "import": "import { Checkbox } from '@ratio-ui/core'",
+      "description": "A 14px box with a 4px radius, drawn with a hairline ring and filled in the primary colour when checked. Set indeterminate for a select-all that stands for some rows. An invisible 24px area around the box takes the tap.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A row selector in a table or list, one box per row\n- A select-all in a table header: set `indeterminate` while only some rows are selected\n- A yes or no option in a form, or a list of channels where several can be on",
+        "whenNotToUse": "- A setting that applies at once: use a switch\n- One choice among several: use radio buttons or FilterTabs\n- Styling: Checkbox takes no `className` and no `style`",
+        "example": "<Checkbox aria-label=\"Select row\" checked={selected} onCheckedChange={setSelected} />"
+      }
+    },
+    {
+      "name": "CheckboxList",
+      "import": "import { CheckboxList } from '@ratio-ui/core'",
+      "description": "A titled list of checkboxes with the count of chosen items in the heading (\"4 of 6\"), an optional description under each label and an optional select-all.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "required": true,
+          "description": "The heading. The count of chosen items sits beside it."
+        },
+        {
+          "name": "items",
+          "type": "CheckboxListItem[]",
+          "required": true,
+          "description": "The options."
+        },
+        {
+          "name": "value",
+          "type": "string[]",
+          "required": false,
+          "description": "The chosen values, when controlled."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string[]",
+          "required": false,
+          "description": "The chosen values to start with, when not controlled."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string[]) => void)",
+          "required": false,
+          "description": "Called with the new list of chosen values."
+        },
+        {
+          "name": "selectAll",
+          "type": "boolean",
+          "required": false,
+          "description": "Adds a \"Select all\" box that is mixed while only some are chosen."
+        },
+        {
+          "name": "selectAllLabel",
+          "type": "string",
+          "required": false,
+          "default": "Select all",
+          "description": "The label of the select-all box. Defaults to \"Select all\"."
+        },
+        {
+          "name": "countLabel",
+          "type": "((chosen: string, total: string) => string)",
+          "required": false,
+          "default": "(c, t) => `${c} of ${t}`",
+          "description": "Writes the count in the heading from the chosen and total counts, already formatted. Defaults to \"4 of 6\"."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A titled list where several options can be on and the heading should say how many (\"Sales channels  4 of 6\")\n- Add `selectAll` for a long list; it shows a mixed box while only some are on",
+        "whenNotToUse": "- One choice among several: use radio buttons or FilterTabs\n- A single yes or no: use Checkbox\n- Styling: CheckboxList takes no `className` and no `style`",
+        "example": "<CheckboxList title=\"Sales channels\" items={channels} value={on} onValueChange={setOn} selectAll />"
+      }
+    },
+    {
+      "name": "Collapsible",
+      "import": "import { Collapsible } from '@ratio-ui/core'",
+      "description": "A section that opens and closes on its heading and, while closed, still shows its values as chips. The panel appears and disappears with no height animation.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "required": true,
+          "description": "The section heading, shown on the trigger."
+        },
+        {
+          "name": "summary",
+          "type": "readonly SummaryChip[]",
+          "required": false,
+          "description": "The values to show as chips while the section is closed."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the section is open, when controlled."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the section starts open, when uncontrolled. Defaults to closed."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "Called when the section opens or closes."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Stops the section from opening or closing."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The section's content, shown when open."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered root."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A form section that is rarely edited and can stay closed, such as the pricing details under the price\n- A closed section that must still show its values: pass `summary` and the chips show while it is closed",
+        "whenNotToUse": "- Content the person must see to finish the task: leave it open\n- Switching between peer views: use Tabs",
+        "example": "```tsx\n<Collapsible title=\"More pricing\" summary={[{ label: 'Cost price', value: '₹450.00' }, { label: 'HSN code', value: '6109' }]}>\n  ...fields...\n</Collapsible>\n```\n\nThe panel appears and disappears at once; the library has no height animation."
+      }
+    },
+    {
+      "name": "DataTable",
+      "import": "import { DataTable } from '@ratio-ui/core'",
+      "description": "A data table on Table with TanStack Table v9: a selection column, server-side sorting and paging, alignment, one-line truncation, row links, and empty and loading slots. The parent owns the state (sort, page, selection) and passes it in. On phones it keeps the columns marked essential and hides the rest.",
+      "props": [
+        {
+          "name": "columns",
+          "type": "DataTableColumn<T>[]",
+          "required": true,
+          "description": "The columns, in order."
+        },
+        {
+          "name": "data",
+          "type": "T[]",
+          "required": true,
+          "description": "The rows of the page on show, already sorted by the parent."
+        },
+        {
+          "name": "getRowId",
+          "type": "(row: T) => string",
+          "required": true,
+          "description": "A stable id for a row."
+        },
+        {
+          "name": "selectedIds",
+          "type": "string[]",
+          "required": false,
+          "description": "Ids of the selected rows. Pass it with `onSelectedIdsChange` to show a checkbox column."
+        },
+        {
+          "name": "onSelectedIdsChange",
+          "type": "((ids: string[]) => void)",
+          "required": false,
+          "description": "Called with the ids that are selected after a change."
+        },
+        {
+          "name": "getRowLabel",
+          "type": "((row: T) => string)",
+          "required": false,
+          "description": "The label of one row's checkbox: \"RYZE - 2mg\", which the table prefixes with \"Select \". Defaults to \"Select row N\"."
+        },
+        {
+          "name": "sort",
+          "type": "DataTableSort | null",
+          "required": false,
+          "default": "null",
+          "description": "The sort the parent applied, or null for none."
+        },
+        {
+          "name": "onSortChange",
+          "type": "((sort: DataTableSort | null) => void)",
+          "required": false,
+          "description": "Called with the next sort, or null to clear it. The parent sorts and passes new data."
+        },
+        {
+          "name": "page",
+          "type": "number",
+          "required": false,
+          "description": "The page on show, counting from 1. Pass with `pageSize`, `total` and `onPageChange` to show the footer."
+        },
+        {
+          "name": "pageSize",
+          "type": "number",
+          "required": false,
+          "description": "How many results one page holds."
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "required": false,
+          "description": "How many results there are in all, across every page."
+        },
+        {
+          "name": "onPageChange",
+          "type": "((page: number) => void)",
+          "required": false,
+          "description": "Called with the page to show."
+        },
+        {
+          "name": "rowHref",
+          "type": "((row: T) => string)",
+          "required": false,
+          "description": "Where a row leads. The first data cell of the row becomes a link to it. On a router, LinkProvider draws it with the app's own link."
+        },
+        {
+          "name": "empty",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Shown in place of the rows when there are none and the table is not loading. Usually an EmptyState."
+        },
+        {
+          "name": "loading",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Shown in place of the whole table while loading, usually a TableLoader. A falsy value shows the table."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A list of records with selection, server-side sorting and paging: products, variants, inventory\n- A first load: pass a TableLoader as `loading` and it replaces the table\n- Rows that link to a detail page, with an empty and a loading state\n- Phones: mark the columns a list needs as `essential` and the rest are hidden",
+        "whenNotToUse": "- Static content composed by hand: use Table\n- Client-side sorting or paging: the parent owns the sort and the page, and passes already sorted data\n- Styling: it takes no `className` and no `style`",
+        "example": "<DataTable\n  aria-label=\"Products\"\n  columns={[\n    { id: 'name', header: 'Product', cell: (p) => p.name, essential: true, sortable: true, truncate: true },\n    { id: 'stock', header: 'Stock', cell: (p) => p.stock, numeric: true },\n  ]}\n  data={products}\n  getRowId={(p) => p.id}\n  rowHref={(p) => `/products/${p.id}`}\n  sort={sort}\n  onSortChange={setSort}\n  page={page}\n  pageSize={20}\n  total={84}\n  onPageChange={setPage}\n  empty=\"No products match this filter\"\n/>"
+      }
+    },
+    {
+      "name": "DatePicker",
+      "import": "import { DatePicker } from '@ratio-ui/core'",
+      "description": "A field that shows a day as DD/MM/YYYY, reads a typed date through the format module and opens a calendar in a popover from the button at its end. Text that is not a date is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits the day as YYYY-MM-DD (empty when there is none), never the text on screen.",
+      "props": [
+        {
+          "name": "value",
+          "type": "Date | null",
+          "required": false,
+          "description": "The day, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "Date | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting day when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: Date | null) => void)",
+          "required": false,
+          "description": "Called with the day when a typed date is complete or a day is picked, and with null when the text is cleared."
+        },
+        {
+          "name": "disabledDays",
+          "type": "Matcher | Matcher[]",
+          "required": false,
+          "description": "The days that cannot be picked in the calendar, for example { before: new Date() }."
+        },
+        {
+          "name": "startMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The first month the calendar can show."
+        },
+        {
+          "name": "endMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The last month the calendar can show."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- One day a person types or picks, such as a \"Best before\" custom field: `value` and `onValueChange` take a `Date` (or null when empty)\n- A date inside a table: `size` 32\n- Limiting the days: `disabledDays` (for example `{ before: new Date() }`), `startMonth` and `endMonth`, which limit the calendar (a typed date is not checked against them)",
+        "whenNotToUse": "- A period of days, such as an analytics range: use DateRangePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a date as text: write it with the format module (`formatDate`)\n- Custom classes or inline styles: DatePicker takes neither `className` nor `style`",
+        "example": "```tsx\nconst [bestBefore, setBestBefore] = useState<Date | null>(null)\n\n<DatePicker aria-label=\"Best before\" value={bestBefore} onValueChange={setBestBefore} />\n<DatePicker aria-label=\"Expiry\" size={32} aria-invalid aria-describedby=\"expiry-error\" />\n```\n\nThe field shows DD/MM/YYYY and reads typed dates through the format module (\"3/1/2026\" is 3 January). Text that is not a date turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits the committed day as `YYYY-MM-DD` (an empty string when the field is empty), not the text on screen: `<DatePicker name=\"bestBefore\" />` posts `bestBefore=2026-10-28`. A disabled field posts nothing."
+      }
+    },
+    {
+      "name": "DateRangePicker",
+      "import": "import { DateRangePicker } from '@ratio-ui/core'",
+      "description": "A field that shows a range as two DD/MM/YYYY days, reads a typed range through the format module and opens a calendar in a popover from the button at its end, for analytics periods. Pick the first day, then the last. Text that is not a range in order is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits two fields, `name.from` and `name.to`, each as YYYY-MM-DD (empty when there is no range), never the text on screen.",
+      "props": [
+        {
+          "name": "value",
+          "type": "DateRangeValue | null",
+          "required": false,
+          "description": "The range, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "DateRangeValue | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting range when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: DateRangeValue | null) => void)",
+          "required": false,
+          "description": "Called with the range when a typed range is complete or two days are picked, and with null when the text is cleared."
+        },
+        {
+          "name": "disabledDays",
+          "type": "Matcher | Matcher[]",
+          "required": false,
+          "description": "The days that cannot be picked in the calendar, for example { after: new Date() } for an analytics period."
+        },
+        {
+          "name": "startMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The first month the calendar can show."
+        },
+        {
+          "name": "endMonth",
+          "type": "Date",
+          "required": false,
+          "description": "The last month the calendar can show."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A period of days a person types or picks, such as an analytics range: `value` and `onValueChange` take `{ from, to }` (or null when empty)\n- Limiting the days: `disabledDays` (for example `{ after: new Date() }` for reports), `startMonth` and `endMonth`, which limit the calendar (a typed range is not checked against them)\n- A range inside a table: `size` 32",
+        "whenNotToUse": "- One day: use DatePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a range as text: write both days with the format module (`formatDate`)\n- Custom classes or inline styles: DateRangePicker takes neither `className` nor `style`",
+        "example": "```tsx\nconst [period, setPeriod] = useState<DateRangeValue | null>(null)\n\n<DateRangePicker aria-label=\"Period\" value={period} onValueChange={setPeriod} disabledDays={{ after: new Date() }} />\n```\n\nThe field shows `28/10/2026 – 03/11/2026`. Pick the first day, then the last (an earlier second day swaps them). A typed range with the end before the start, or one day only, turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits two fields, `name.from` and `name.to`, each the committed day as `YYYY-MM-DD` (empty strings when the field is empty), not the text on screen: `<DateRangePicker name=\"period\" />` posts `period.from=2026-10-28` and `period.to=2026-11-03`. A disabled field posts nothing."
+      }
+    },
+    {
+      "name": "Definition",
+      "import": "import { Definition } from '@ratio-ui/core'",
+      "description": "A term that explains itself. It is a span with the button role and a dotted underline, so it takes the font of the text around it, so keyboard users reach it with Tab and open it with Enter or Space, touch users open it with a tap, and mouse users with hover or click. It does not use the browser's own title tooltip, which keyboard and touch users cannot open. Escape closes it.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The term, shown in the text with a dotted underline."
+        },
+        {
+          "name": "definition",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The explanation shown when the term is opened. Keep it to a sentence."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A term in a heading or label that needs a one-sentence explanation, such as a metric title\n- Where keyboard and touch users must be able to read the explanation: it opens with Tab and Enter, with a tap, and on hover",
+        "whenNotToUse": "- An icon-only hint: use Tooltip\n- Long or interactive content: use Popover\n- Text that the task cannot be finished without: show it on the screen",
+        "example": "<Definition definition=\"Gross merchandise value, before returns\">GMV</Definition>"
+      }
+    },
+    {
+      "name": "Dialog",
+      "import": "import { Dialog } from '@ratio-ui/core'",
+      "description": "The root of a dialog. It holds the open state and renders nothing itself. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to leave it uncontrolled. The page behind is inert while it is open, with no scrim over it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short task that needs the user's full attention before going back to the page, such as adding a product or defining a field\n- A confirm step before a destructive action\n- Work that fits in 480px: the panel is fixed at that width and has no scrim",
+        "whenNotToUse": "- A message after an action: use toast()\n- A long form or a multi-step flow: give it a page\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Dialog>\n  <DialogTrigger>Add product</DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Add product</DialogTitle>\n      <DialogDescription>Fill in the basics</DialogDescription>\n    </DialogHeader>\n    <DialogFooter>\n      <DialogClose>Cancel</DialogClose>\n    </DialogFooter>\n  </DialogContent>\n</Dialog>"
+      },
+      "parts": [
+        {
+          "name": "DialogClose",
+          "import": "import { DialogClose } from '@ratio-ui/core'",
+          "description": "A button that closes the dialog, such as Cancel in the footer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogContent",
+          "import": "import { DialogContent } from '@ratio-ui/core'",
+          "description": "The panel: 480px wide, white, drawn with the ring outline and no shadow, with no scrim behind it. Put DialogHeader, the form and DialogFooter inside.",
+          "props": [
+            {
+              "name": "showCloseButton",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Whether the corner close button shows. Defaults to true."
+            },
+            {
+              "name": "closeLabel",
+              "type": "string",
+              "required": false,
+              "default": "Close",
+              "description": "The accessible name of the corner close button. Defaults to Close."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogDescription",
+          "import": "import { DialogDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the dialog is for, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogFooter",
+          "import": "import { DialogFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom, aligned to the end.",
+          "props": []
+        },
+        {
+          "name": "DialogHeader",
+          "import": "import { DialogHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "DialogTitle",
+          "import": "import { DialogTitle } from '@ratio-ui/core'",
+          "description": "The dialog's name, in the b4 style. It names the dialog for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogTrigger",
+          "import": "import { DialogTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the dialog.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "DropdownMenu",
+      "import": "import { DropdownMenu } from '@ratio-ui/core'",
+      "description": "The root of a menu of actions that opens from a trigger. Compose it with DropdownMenuTrigger and DropdownMenuContent.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short list of actions behind one control: \"More actions\", a store menu, a \"…\" button\n- Actions that belong in groups, with a label per group, a hairline between groups, or a submenu\n- Items that show a key hint, a check (on or off) or one choice out of a few",
+        "whenNotToUse": "- Choosing a value for a form field: use a select\n- Content that is not a list of actions, such as notifications or a form: use Popover\n- A destructive action without a confirm step: the destructive item only colours it\n- Styling: the parts take no `className` and no `style`, and the menu has no shadow",
+        "example": "<DropdownMenu>\n  <DropdownMenuTrigger>More actions</DropdownMenuTrigger>\n  <DropdownMenuContent>\n    <DropdownMenuGroup>\n      <DropdownMenuLabel>Product</DropdownMenuLabel>\n      <DropdownMenuItem>\n        Edit\n        <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>\n      </DropdownMenuItem>\n    </DropdownMenuGroup>\n    <DropdownMenuSeparator />\n    <DropdownMenuItem variant=\"destructive\">Delete</DropdownMenuItem>\n  </DropdownMenuContent>\n</DropdownMenu>"
+      },
+      "parts": [
+        {
+          "name": "DropdownMenuCheckboxItem",
+          "import": "import { DropdownMenuCheckboxItem } from '@ratio-ui/core'",
+          "description": "An item that toggles an option. A check shows at its start while it is on and keeps the menu open, so several options can be changed in one visit.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuCheckboxItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuContent",
+          "import": "import { DropdownMenuContent } from '@ratio-ui/core'",
+          "description": "The menu panel: a white popup with a hairline ring, 8px corners and no shadow. It opens in a portal.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"",
+              "required": false,
+              "default": "bottom",
+              "description": "Which side of the trigger the menu opens on. Defaults to bottom."
+            },
+            {
+              "name": "align",
+              "type": "\"center\" | \"end\" | \"start\"",
+              "required": false,
+              "default": "start",
+              "description": "How the menu lines up with the trigger along that side. Defaults to start."
+            },
+            {
+              "name": "sideOffset",
+              "type": "number",
+              "required": false,
+              "default": "4",
+              "description": "The gap between the trigger and the menu in px. Defaults to 4."
+            },
+            {
+              "name": "alignOffset",
+              "type": "number",
+              "required": false,
+              "default": "0",
+              "description": "A shift along the side in px. Defaults to 0."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuGroup",
+          "import": "import { DropdownMenuGroup } from '@ratio-ui/core'",
+          "description": "Groups items under one DropdownMenuLabel, so assistive technology announces the label with the group.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuItem",
+          "import": "import { DropdownMenuItem } from '@ratio-ui/core'",
+          "description": "One action in the menu. It runs onClick and closes the menu; disabled is drawn at half opacity and cannot be chosen.",
+          "props": [
+            {
+              "name": "variant",
+              "type": "\"default\" | \"destructive\"",
+              "required": false,
+              "default": "default",
+              "description": "What the item means. destructive is drawn in the destructive token; a delete action also needs a confirm step. Defaults to default."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuLabel",
+          "import": "import { DropdownMenuLabel } from '@ratio-ui/core'",
+          "description": "The caption of a group, in the design system's label style: 12px, uppercase, subdued. Place it inside DropdownMenuGroup.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupLabelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuRadioGroup",
+          "import": "import { DropdownMenuRadioGroup } from '@ratio-ui/core'",
+          "description": "Holds radio items and the one chosen value.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuRadioItem",
+          "import": "import { DropdownMenuRadioItem } from '@ratio-ui/core'",
+          "description": "One choice of a DropdownMenuRadioGroup. A dot shows at its start while it is the chosen value.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSeparator",
+          "import": "import { DropdownMenuSeparator } from '@ratio-ui/core'",
+          "description": "A hairline between groups of items.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuShortcut",
+          "import": "import { DropdownMenuShortcut } from '@ratio-ui/core'",
+          "description": "A key hint pushed to the end of an item. It is a hint only: the host binds the key.",
+          "props": [
+            {
+              "name": "children",
+              "type": "ReactNode",
+              "required": true,
+              "description": "The key hint, such as ⌘E. It is text only and does not bind a key."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSub",
+          "import": "import { DropdownMenuSub } from '@ratio-ui/core'",
+          "description": "The root of a nested menu. Hold a DropdownMenuSubTrigger and a DropdownMenuSubContent.",
+          "props": []
+        },
+        {
+          "name": "DropdownMenuSubContent",
+          "import": "import { DropdownMenuSubContent } from '@ratio-ui/core'",
+          "description": "The panel of a submenu. It opens to the side of its trigger.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"",
+              "required": false,
+              "default": "right",
+              "description": "Which side of the trigger the menu opens on. Defaults to bottom."
+            },
+            {
+              "name": "align",
+              "type": "\"center\" | \"end\" | \"start\"",
+              "required": false,
+              "description": "How the menu lines up with the trigger along that side. Defaults to start."
+            },
+            {
+              "name": "sideOffset",
+              "type": "number",
+              "required": false,
+              "default": "0",
+              "description": "The gap between the trigger and the menu in px. Defaults to 4."
+            },
+            {
+              "name": "alignOffset",
+              "type": "number",
+              "required": false,
+              "default": "-6",
+              "description": "A shift along the side in px. Defaults to 0."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSubTrigger",
+          "import": "import { DropdownMenuSubTrigger } from '@ratio-ui/core'",
+          "description": "The item that opens a submenu, on hover, click or ArrowRight. A chevron at its end marks it.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuSubmenuTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuTrigger",
+          "import": "import { DropdownMenuTrigger } from '@ratio-ui/core'",
+          "description": "The control that opens the menu. It is a button, and carries aria-expanded and aria-haspopup.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "EmptyState",
+      "import": "import { EmptyState } from '@ratio-ui/core'",
+      "description": "What a list, table or panel shows when it has nothing to show: one clause and an optional action, centred in a hairline container.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "One clause that says why nothing is shown, in sentence case with no period."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second clause that says what to do next."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional action, usually one Button."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A list, table or panel with nothing to show, such as a filter that matches no products\n- With one action when the user can fix it, such as clearing the filter",
+        "whenNotToUse": "- A load that is still running: use Skeleton\n- An error: say what failed in one clause, in the error colour, not here",
+        "example": "<EmptyState title=\"No products match this filter\" action={<Button>Clear filter</Button>} />"
+      }
+    },
+    {
+      "name": "Field",
+      "import": "import { Field } from '@ratio-ui/core'",
+      "description": "A form row: label, control, hint and error. It wires the label to the control by id, links the hint and error with aria-describedby, and sets aria-invalid when there is an error. The control keeps an id it already has.",
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The label text."
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Help text under the control. An error replaces it."
+        },
+        {
+          "name": "error",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The error message. It shows under the control beside the alert glyph and marks the control invalid."
+        },
+        {
+          "name": "info",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An explanation of the field, opened from a small info icon beside the label by keyboard, touch or hover."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "required": false,
+          "description": "Shows a star after the label and marks the control aria-required."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Dims the label and disables the control."
+        },
+        {
+          "name": "children",
+          "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>> | ((props: FieldControlProps) => ReactNode)",
+          "required": true,
+          "description": "The control: one element, such as Input, which gets an id, aria-describedby, aria-invalid, aria-required and disabled. When the control sits inside a wrapper such as InputGroup, pass a function instead and spread the props it receives onto the input itself."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Every form row: a label, one control, and optional hint, error, info tooltip and required mark\n- Wiring: Field sets the control's id, aria-describedby, aria-invalid, aria-required and disabled, so you do not",
+        "whenNotToUse": "- A heading for a group of controls: use a fieldset with a legend\n- A label with no control beside it: use Label alone, with `htmlFor`\n- Long help that must be read to finish the task: put it on the screen as the hint",
+        "example": "```tsx\n<Field label=\"Title\" hint=\"Shown in search results\" error={errors.title} required>\n  <Input />\n</Field>\n<Field label=\"MRP\" info=\"Maximum retail price, with tax\">\n  <Input inputMode=\"decimal\" />\n</Field>\n```\n\nFor an input inside an InputGroup, pass a function child and spread its props onto the input: `<Field label=\"MRP\">{(props) => <InputGroup>…<InputGroupInput {...props} /></InputGroup>}</Field>`.\n\nFor a Select, which renders no element of its own, spread the props onto its trigger: `<Field label=\"GST rate\">{(props) => <Select items={rates}><SelectTrigger {...props}><SelectValue /></SelectTrigger><SelectContent>…</SelectContent></Select>}</Field>`.\n\nThe error shows beside the alert glyph in the error ink (question 1) and replaces the hint. Label is the same label as a separate part."
+      },
+      "parts": [
+        {
+          "name": "Label",
+          "import": "import { Label } from '@ratio-ui/core'",
+          "description": "The text that names a control, in the 12px medium label type. Point htmlFor at the control's id; Field does this for you.",
+          "props": [
+            {
+              "name": "ref",
+              "type": "Ref<HTMLLabelElement>",
+              "required": false,
+              "description": "Receives the label element."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "FilterTabs",
+      "import": "import { FilterTabs } from '@ratio-ui/core'",
+      "description": "A single choice that filters a list, such as All, Active and Inactive above a table: the design system's Tab chips in a row with an 8px gap. One item is always chosen. For sections of a page use Tabs instead.",
+      "props": [
+        {
+          "name": "items",
+          "type": "FilterTabsItem[]",
+          "required": true,
+          "description": "The choices, in order."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "description": "The chosen value when controlled."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "description": "The chosen value at the start when uncontrolled. Defaults to the first item."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called with the new value when another item is chosen. Choosing the chosen item again does nothing."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Disables every item. Defaults to false."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A single choice that filters the list below it, such as All, Active and Inactive above the products table\n- A short set of choices, one chosen at all times, shown as the design system's chip tabs in a row",
+        "whenNotToUse": "- Sections of a page with their own content: use Tabs\n- Choices that can be combined or cleared: use checkboxes or a menu\n- Many choices: the chips wrap onto more lines, so use a select",
+        "example": "<FilterTabs\n  aria-label=\"Status\"\n  items={[\n    { value: 'all', label: 'All' },\n    { value: 'active', label: 'Active' },\n    { value: 'draft', label: 'Draft' },\n  ]}\n  defaultValue=\"all\"\n  onValueChange={setStatus}\n/>"
+      }
+    },
+    {
+      "name": "GlobalSearch",
+      "import": "import { GlobalSearch } from '@ratio-ui/core'",
+      "description": "The search in the top bar. Typing opens a panel of grouped results that the app supplies, an empty field shows recent items, and the arrow keys, Enter and Escape work the list. Cmd+K or Ctrl+K focuses the field from anywhere.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of the field, such as \"Search the dashboard\"."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": true,
+          "description": "The text typed in the field."
+        },
+        {
+          "name": "onValueChange",
+          "type": "(value: string) => void",
+          "required": true,
+          "description": "Called on every change of the text. Debounce and fetch in the app."
+        },
+        {
+          "name": "groups",
+          "type": "GlobalSearchGroup[]",
+          "required": true,
+          "description": "The results for the current text, grouped. The app supplies them; nothing is filtered here."
+        },
+        {
+          "name": "recent",
+          "type": "GlobalSearchResult[]",
+          "required": false,
+          "default": "[]",
+          "description": "Recent items, shown under \"Recent\" while the field is empty."
+        },
+        {
+          "name": "onSelect",
+          "type": "((result: GlobalSearchResult) => void)",
+          "required": false,
+          "description": "Called when a result is chosen by click or Enter."
+        },
+        {
+          "name": "onShowMore",
+          "type": "((group: GlobalSearchGroup) => void)",
+          "required": false,
+          "description": "Called when a \"+N more\" row is chosen, with its group."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "default": "Search",
+          "description": "The placeholder of the field. Defaults to \"Search\"."
+        },
+        {
+          "name": "emptyText",
+          "type": "string",
+          "required": false,
+          "default": "No results",
+          "description": "The copy when the text matches nothing. Defaults to \"No results\"."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The search in the top bar that finds products, orders, customers and pages across the dashboard\n- Results that the app fetches and groups itself, with recent items while the field is empty",
+        "whenNotToUse": "- Narrowing the rows of one listing: use SearchField\n- Picking a value for a form field: use a select",
+        "example": "<GlobalSearch\n  label=\"Search the dashboard\"\n  value={query}\n  onValueChange={setQuery}\n  groups={[{ id: 'products', label: 'Products', total: 8, items: products }]}\n  recent={recentItems}\n  onSelect={(result) => navigate(result.id)}\n  onShowMore={(group) => navigate(`/search?group=${group.id}&q=${query}`)}\n/>"
+      }
+    },
     {
       "name": "Icon",
       "import": "import { Icon } from '@ratio-ui/core'",
       "description": "Draws one icon of the registry: the design system's own glyphs, filled in a single colour, and Tabler's icons for the rest, drawn with a 1.5px line at every size. The icon is a square box of 8, 12 or 16px and takes the colour of its tone.",
       "props": [
         {
-          "name": "name",
-          "type": "\"alert-triangle\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"info-circle\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-home\" | \"nav-product\" | \"nav-product-2\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
+          "name": "name",
+          "type": "\"alert-triangle\" | \"calendar\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"import\" | \"info-circle\" | \"menu\" | \"more\" | \"nav-analytics\" | \"nav-apps\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-content\" | \"nav-customers\" | \"nav-discounts\" | \"nav-growth\" | \"nav-home\" | \"nav-markets\" | \"nav-orders\" | \"nav-product\" | \"nav-product-2\" | \"nav-sales-channels\" | \"nav-settings\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
+          "required": true,
+          "description": "Which icon to draw, by name."
+        },
+        {
+          "name": "size",
+          "type": "8 | 12 | 16",
+          "required": false,
+          "default": "12",
+          "description": "The square box in px: 8, 12 or 16. Defaults to 12, the size inside controls."
+        },
+        {
+          "name": "tone",
+          "type": "\"current\" | \"icon\" | \"primary\" | \"subdued\"",
+          "required": false,
+          "default": "current",
+          "description": "The colour. current, the default, takes the colour of the text around the icon; the other tones set their own."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name. With a label the icon is an image that assistive technology announces under that name. Without one it is decoration, hidden from assistive technology, and the text beside it has to say what it means."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- The date pickers' open button: calendar (Tabler) at size 12\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
+        "whenNotToUse": "- Decoration that adds no meaning. An icon next to text that already says the same thing is hidden from assistive technology, so leave the label off, and leave the icon out when it adds nothing\n- An icon the registry does not have. Components accept no className or style, and icons come from the registry only, so a new one is a registry entry: the design system's glyph first, Tabler for the rest\n- An icon-only control without a name. Pass label, or give the control its own accessible name\n- A size other than 8, 12 or 16, or a colour other than the four tones. There is no red, no destructive colour and no third accent: an error is marked with the alert-triangle glyph beside its message, not with a colour\n- Emoji, or unicode arrows and symbols, as icons. Inter's web subsets do not hold them and the design system bans them",
+        "example": "import { Icon } from '@ratio-ui/core'\n\n// Beside text that names it: decoration, hidden from assistive technology\n<button type=\"button\">\n  <Icon name=\"plus\" />\n  Add product\n</button>\n\n// Alone: the label is the accessible name\n<Icon name=\"search\" tone=\"icon\" label=\"Search\" />\n\n// Pagination chevrons are drawn for an 8px box\n<Icon name=\"chevron-right\" size={8} />"
+      }
+    },
+    {
+      "name": "Inline",
+      "import": "import { Inline } from '@ratio-ui/core'",
+      "description": "Lays its children out in a row with a fixed space between them. It takes no className and no style: the gap is a step of the design system's spacing scale, and the layout is the only styling it has.",
+      "props": [
+        {
+          "name": "gap",
+          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "required": true,
+          "description": "The space between children, a step of the design system's scale in px: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80."
+        },
+        {
+          "name": "align",
+          "type": "\"baseline\" | \"center\" | \"end\" | \"start\" | \"stretch\"",
+          "required": false,
+          "default": "center",
+          "description": "How children line up across the row, which is the vertical axis. Defaults to center."
+        },
+        {
+          "name": "justify",
+          "type": "\"between\" | \"center\" | \"end\" | \"start\"",
+          "required": false,
+          "default": "start",
+          "description": "How children spread along the row, which is the horizontal axis. Defaults to start."
+        },
+        {
+          "name": "wrap",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether children move to a new line when the row is full. Defaults to false, which keeps one line."
+        },
+        {
+          "name": "as",
+          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "required": false,
+          "default": "div",
+          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Children side by side with a fixed space between them: a toolbar, a row of tags, a label next to a value\n- Children that spread along the row (`justify`: start, center, end or between) or move to the next line when the row is full (`wrap`)\n- A gap taken from the design system's spacing scale: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80 px\n- A row that is also a list or a landmark: `as` renders `ul`, `ol`, `li`, `nav`, `header`, `footer`, `main`, `aside`, `section`, `form` or `fieldset` instead of `div`",
+        "whenNotToUse": "- Children one under another: use Stack\n- Columns that have to line up from one row to the next: Inline lays out one row at a time, and wave 0 has no grid\n- Space around one child or at the edge of a container: Inline spaces siblings only, and has no padding or margin\n- Styling: Inline takes no `className` and no `style`\n- A list without markers: `as=\"ul\"` and `as=\"ol\"` leave the browser's list markers as they are",
+        "example": "<Inline gap={8} justify=\"between\" wrap>\n  <div>Orders</div>\n  <Inline gap={4}>\n    <div>Export</div>\n    <div>Filter</div>\n  </Inline>\n</Inline>"
+      }
+    },
+    {
+      "name": "Input",
+      "import": "import { Input } from '@ratio-ui/core'",
+      "description": "A single-line text field in the design system's look: 8px radius, a 1px ring that turns blue on focus, 14px body type. It takes every attribute of an input (type, inputMode, value, onChange). For a prefix, suffix, icon or shortcut hint, put an InputGroupInput in an InputGroup.",
+      "props": [
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms and search, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A single-line text field in a form, a settings page or a table cell: `size` is 36 for forms and 32 for fields inside a table\n- Any input type the browser supports, such as text, email, number or password: Input takes every attribute of an input\n- A field with an error: set `aria-invalid` and the ring changes, and put the error message beside it in text",
+        "whenNotToUse": "- A field with a prefix, suffix, icon or shortcut hint, such as a rupee price, a weight in kg or a search field: use InputGroup\n- Several lines of text: use a textarea\n- A choice from a fixed list: use a select\n- Custom classes or inline styles: Input takes no `className` and no `style`",
+        "example": "<Input aria-label=\"Product title\" placeholder=\"Short sleeve t-shirt\" />\n<Input aria-label=\"Variant stock\" size={32} inputMode=\"numeric\" />"
+      }
+    },
+    {
+      "name": "InputGroup",
+      "import": "import { InputGroup } from '@ratio-ui/core'",
+      "description": "A field with a prefix, suffix, icon or shortcut hint beside the input, inside one ring. Put an InputGroupInput in it and an InputGroupAddon on either side, for example a rupee sign before a price or kg after a weight.",
+      "props": [
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms and search, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the group element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A field with something beside the input, all inside one ring: a rupee sign before a price, kg after a weight, a search icon, or a shortcut hint such as ⌘K\n- A table search field or the top bar search: an icon at the start and a shortcut hint at the end\n- A compact field in a table: `size` 32, as for Input",
+        "whenNotToUse": "- A plain field with nothing beside the input: use Input\n- A button inside the field: put it next to the group, because an addon holds text and icons only\n- Custom classes or inline styles: none of the parts take `className` or `style`",
+        "example": "<InputGroup>\n  <InputGroupAddon>\n    <InputGroupText>₹</InputGroupText>\n  </InputGroupAddon>\n  <InputGroupInput aria-label=\"Selling price\" inputMode=\"decimal\" />\n</InputGroup>\n<InputGroup>\n  <InputGroupAddon><Icon name=\"search\" /></InputGroupAddon>\n  <InputGroupInput aria-label=\"Search\" placeholder=\"Search by name, email, etc.\" />\n  <InputGroupAddon align=\"end\"><InputGroupShortcut>⌘K</InputGroupShortcut></InputGroupAddon>\n</InputGroup>"
+      },
+      "parts": [
+        {
+          "name": "InputGroupAddon",
+          "import": "import { InputGroupAddon } from '@ratio-ui/core'",
+          "description": "Holds an icon, a prefix, a suffix or a shortcut hint on one side of the input. Clicking it, off a button, moves focus to the input.",
+          "props": [
+            {
+              "name": "align",
+              "type": "\"end\" | \"start\"",
+              "required": false,
+              "default": "start",
+              "description": "The side of the input: start before it, end after it. Defaults to start."
+            }
+          ]
+        },
+        {
+          "name": "InputGroupInput",
+          "import": "import { InputGroupInput } from '@ratio-ui/core'",
+          "description": "The input of an InputGroup. It draws no ring: the group does. Mark it invalid with aria-invalid.",
+          "props": [
+            {
+              "name": "ref",
+              "type": "Ref<HTMLInputElement>",
+              "required": false,
+              "description": "Receives the input element."
+            }
+          ]
+        },
+        {
+          "name": "InputGroupShortcut",
+          "import": "import { InputGroupShortcut } from '@ratio-ui/core'",
+          "description": "A shortcut hint such as ⌘K inside an end addon, drawn as a small keycap.",
+          "props": []
+        },
+        {
+          "name": "InputGroupText",
+          "import": "import { InputGroupText } from '@ratio-ui/core'",
+          "description": "A text prefix or suffix inside an addon, such as a currency sign or a unit, in the muted colour.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "Kbd",
+      "import": "import { Kbd } from '@ratio-ui/core'",
+      "description": "A key hint, 20px high with a 4px radius, such as ⌘K or esc.",
+      "props": [
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A shortcut hint beside a control or in a menu: ⌘K, ↵, esc\n- Several keys of one shortcut, inside KbdGroup",
+        "whenNotToUse": "- A button that triggers the action: Kbd only shows the key and is not interactive\n- Long text: a key is one symbol or a short name",
+        "example": "<KbdGroup>\n  <Kbd>⌘</Kbd>\n  <Kbd>K</Kbd>\n</KbdGroup>"
+      },
+      "parts": [
+        {
+          "name": "KbdGroup",
+          "import": "import { KbdGroup } from '@ratio-ui/core'",
+          "description": "Puts the keys of one shortcut in a row with a 4px gap.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "Link",
+      "import": "import { Link } from '@ratio-ui/core'",
+      "description": "A text link to another page, such as \"← Products\" or \"View all variants →\". It is drawn by the app's LinkProvider, so a router navigates without a reload; without one it is a plain <a href>. The arrows are decoration and are hidden from screen readers.",
+      "props": [
+        {
+          "name": "href",
+          "type": "string",
+          "required": true,
+          "description": "Where the link goes."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The link text."
+        },
+        {
+          "name": "back",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Shows a back arrow before the text, as in \"← Products\". Screen readers skip it."
+        },
+        {
+          "name": "forward",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Shows a forward arrow after the text, as in \"View all variants →\". Screen readers skip it."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLAnchorElement>",
+          "required": false,
+          "description": "Receives the anchor element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A text link to another page: \"← Products\", \"View all variants →\"\n- A back link in a detail page's body (the page header has its own back link)",
+        "whenNotToUse": "- An action that changes something: use Button\n- A whole table row: use DataTable's `rowHref`\n- A navigation row in the side navigation: use SideNav",
+        "example": "<Link href=\"/products\" back>Products</Link>\n<Link href=\"/products/blue-shirt/variants\" forward>View all variants</Link>"
+      }
+    },
+    {
+      "name": "LinkProvider",
+      "import": "import { LinkProvider } from '@ratio-ui/core'",
+      "description": "Draws every link of Ratio's components with the app's own router link, so a click navigates without a page reload: SideNav rows with an href, DataTable row links and the PageHeader back link. Wrap the app once, at its root. Without it those links are plain <a href> elements, which reload the page.",
+      "props": [
+        {
+          "name": "render",
+          "type": "LinkRender",
+          "required": true,
+          "description": "Draws every link Ratio renders. The function receives href, the styling class, the content and attributes such as aria-current and onClick, all to spread onto the element: `({ href, ...props }) => <RouterLink to={href} {...props} />`."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The app, or the part of it that the router serves."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- An app on a client-side router (React Router, Next.js, TanStack Router): wrap it once, at its root\n- So that SideNav rows with an href, DataTable row links and the PageHeader back link navigate without a page reload",
+        "whenNotToUse": "- An app whose pages load from the server: the plain links already work\n- A link in your own markup: use your router's link directly",
+        "example": "import { Link as RouterLink } from 'react-router-dom'\n\n<LinkProvider render={({ href, ...props }) => <RouterLink to={href} {...props} />}>\n  <App />\n</LinkProvider>"
+      }
+    },
+    {
+      "name": "MediaGrid",
+      "import": "import { MediaGrid } from '@ratio-ui/core'",
+      "description": "The media of a product: a row of square thumbs with an add tile that opens the file picker and takes dropped files. Thumbs reorder by drag (pointer, touch or keyboard) and by the Move left, Move right and Make cover buttons, so no drag is needed. The first image is the cover and carries a badge. Uploads show a thin progress bar and failures an error under the thumb. Every move, cover change and removal is announced to screen readers.",
+      "props": [
+        {
+          "name": "items",
+          "type": "MediaGridItem[]",
+          "required": true,
+          "description": "The images in order. The first one is the cover."
+        },
+        {
+          "name": "onAdd",
+          "type": "(files: File[]) => void",
+          "required": true,
+          "description": "Called with the files chosen in the add tile or dropped on the grid."
+        },
+        {
+          "name": "onReorder",
+          "type": "(ids: string[]) => void",
+          "required": true,
+          "description": "Called with every id in the new order after a drag, Move left, Move right or Make cover."
+        },
+        {
+          "name": "onRemove",
+          "type": "(id: string) => void",
+          "required": true,
+          "description": "Called with the id of the item to take off the grid."
+        },
+        {
+          "name": "onMakeCover",
+          "type": "((id: string) => void)",
+          "required": false,
+          "description": "Called with the id after Make cover has moved it first through onReorder, for an app that saves the cover on its own."
+        },
+        {
+          "name": "accept",
+          "type": "Accept",
+          "required": false,
+          "default": "{ 'image/*': [] }",
+          "description": "The file types the add tile takes, as react-dropzone's accept map. Defaults to every image type."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Stops adding, dragging and every button."
+        },
+        {
+          "name": "addLabel",
+          "type": "string",
+          "required": false,
+          "default": "Add media",
+          "description": "The accessible name of the add tile. Defaults to \"Add media\"."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the grid."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the grid. Defaults to \"Media\" when there is no aria-labelledby."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of the visible label that names the grid, such as a Field label."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The id of help text for the grid."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The images of a product or any ordered set of images, with an add tile that opens the file picker and takes dropped files\n- The app uploads: MediaGrid reports `onAdd(files)`, `onReorder(ids)`, `onRemove(id)` and `onMakeCover(id)`, and shows each item's `progress` (0 to 100) and `error`\n- The first image is the cover; Make cover moves an image first through `onReorder`, then calls `onMakeCover`\n- Images reorder by drag (pointer, touch or keyboard) and by the Move left and Move right buttons, so no drag is needed",
+        "whenNotToUse": "- A single image such as a logo or an avatar: use Avatar or a single file input\n- Files that are not images in a visual order (documents, CSV imports): use a list\n- Remove has no confirm step, because the save bar's Discard brings an image back; confirm in `onRemove` with AlertDialog when the removal is final\n- Styling: MediaGrid takes no `className` and no `style`",
+        "example": "<MediaGrid\n  items={media}\n  onAdd={(files) => upload(files)}\n  onReorder={(ids) => setMedia(ids.map((id) => media.find((m) => m.id === id)!))}\n  onRemove={(id) => setMedia(media.filter((m) => m.id !== id))}\n/>"
+      }
+    },
+    {
+      "name": "MetricStrip",
+      "import": "import { MetricStrip } from '@ratio-ui/core'",
+      "description": "A row of metrics in one hairline container: each segment is a title, optionally with a definition, over its value.",
+      "props": [
+        {
+          "name": "segments",
+          "type": "MetricSegment[]",
+          "required": true,
+          "description": "The metrics, left to right."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the strip."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A few headline numbers above a listing, such as the Products metrics\n- A metric whose name needs a one-sentence definition",
+        "whenNotToUse": "- A chart or a trend: this is plain values\n- Many metrics or long values: use a table",
+        "example": "<MetricStrip\n  label=\"Product metrics\"\n  segments={[\n    {\n      id: 'rate',\n      title: 'Average sell-through rate',\n      definition: 'Share of stock sold',\n      value: '9.95%',\n    },\n    { id: 'days', title: 'Days of inventory remaining', value: null },\n    { id: 'abc', title: 'ABC product analysis', value: 0, format: 'money' },\n  ]}\n/>"
+      }
+    },
+    {
+      "name": "MoneyInput",
+      "import": "import { MoneyInput } from '@ratio-ui/core'",
+      "description": "A money field: the currency symbol before the amount, inside one ring. It takes and gives integer paise, shows the amount grouped as India groups it with two decimals (1,23,456.50) once the field loses focus, and reads a pasted amount written with the currency symbol or with either grouping. Under a name, a form submits paise.",
+      "props": [
+        {
+          "name": "value",
+          "type": "number | null",
+          "required": false,
+          "description": "The amount in integer paise (12345650 is 1,23,456 rupees and 50 paise), or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "required": false,
+          "default": "null",
+          "description": "The starting amount in integer paise when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((paise: number | null) => void)",
+          "required": false,
+          "description": "Called with the amount in integer paise as it is typed, pasted or cleared (null when empty)."
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "required": false,
+          "description": "The smallest amount in integer paise; the field moves a smaller one up to it on blur. Leave it out to allow negatives."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "description": "The largest amount in integer paise; the field moves a larger one down to it on blur."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for prices inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Any amount of money a person types: MRP, selling price, cost price, variant prices\n- Values stored as integer paise: `value` and `onValueChange` take and give paise, and under a `name` a form submits paise\n- A price inside a table: `size` 32\n- Amounts people paste from a spreadsheet or another page: a pasted amount with the rupee sign or either grouping is read as paise",
+        "whenNotToUse": "- Showing an amount that is not edited: write it with the format module (`formatPaise`) in text\n- A number that is not money, such as a weight or a length: use UnitInput\n- A count of items: use Input with `inputMode=\"numeric\"`\n- Custom classes or inline styles: MoneyInput takes neither `className` nor `style`",
+        "example": "const [mrp, setMrp] = useState<number | null>(129900)\n\n<MoneyInput aria-label=\"MRP\" value={mrp} onValueChange={setMrp} min={0} />\n<MoneyInput aria-label=\"Price of L\" size={32} defaultValue={44900} name=\"price\" />\n<MoneyInput aria-label=\"Selling price\" aria-invalid aria-describedby=\"price-error\" />"
+      }
+    },
+    {
+      "name": "PageHeader",
+      "import": "import { PageHeader } from '@ratio-ui/core'",
+      "description": "The top of a page: an optional back link, then an icon, the title and a status pill on the left, and the actions with an overflow menu on the right. It wraps on a phone.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "required": true,
+          "description": "The page title, shown as the level 1 heading."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An icon or logo shown before the title."
+        },
+        {
+          "name": "status",
+          "type": "{ label: string; tone?: StatusPillTone; }",
+          "required": false,
+          "description": "The state of the record, one word, beside the title."
+        },
+        {
+          "name": "backHref",
+          "type": "string",
+          "required": false,
+          "description": "Where the back link goes. The link shows only with this. On a router, LinkProvider draws it with the app's own link."
+        },
+        {
+          "name": "backLabel",
+          "type": "string",
+          "required": false,
+          "default": "Back",
+          "description": "The text of the back link, such as the parent page's name. Defaults to Back."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Buttons on the right, such as Export and Add product."
+        },
+        {
+          "name": "menuItems",
+          "type": "PageHeaderMenuItem[]",
+          "required": false,
+          "description": "Entries of the overflow menu. The More actions button shows only when there is at least one."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The top of a page: Products, Product detail\n- A title with an icon, a one-word status, a back link, actions and an overflow menu",
+        "whenNotToUse": "- A heading inside a panel: use Text\n- More than one main action: keep one main Button, the rest secondary or in the overflow menu",
+        "example": "<PageHeader\n  title=\"Blue shirt\"\n  status={{ label: 'Active', tone: 'success' }}\n  backHref=\"/products\"\n  backLabel=\"Products\"\n  actions={<Button>Save</Button>}\n  menuItems={[\n    { label: 'Duplicate', onSelect: duplicate },\n    { label: 'Delete', onSelect: remove, destructive: true },\n  ]}\n/>"
+      }
+    },
+    {
+      "name": "Pagination",
+      "import": "import { Pagination } from '@ratio-ui/core'",
+      "description": "The footer under a table: Previous and Next arrows and the range on show, written \"1 – 20 of 84 results\". An arrow is dimmed to 50% and disabled (aria-disabled, still focusable) when there is no page that way. The parent owns the page: it passes `page` and updates it in `onPageChange`.",
+      "props": [
+        {
+          "name": "page",
+          "type": "number",
+          "required": true,
+          "description": "The page being shown, counting from 1."
+        },
+        {
+          "name": "pageSize",
+          "type": "number",
+          "required": true,
+          "description": "How many results one page holds."
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "required": true,
+          "description": "How many results there are in all, across every page."
+        },
+        {
+          "name": "onPageChange",
+          "type": "(page: number) => void",
+          "required": true,
+          "description": "Called with the page to show when Previous or Next is pressed."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The footer under a table or list that has more than one page of results\n- When the parent knows the page, the page size and the total",
+        "whenNotToUse": "- Numbered page links or jump to page: this is Previous and Next only\n- Infinite scroll or a load more button\n- Styling: Pagination takes no `className` and no `style`",
+        "example": "const [page, setPage] = useState(1)\n\n<Pagination page={page} pageSize={20} total={84} onPageChange={setPage} />"
+      }
+    },
+    {
+      "name": "Popover",
+      "import": "import { Popover } from '@ratio-ui/core'",
+      "description": "A panel that opens from a trigger and holds more than text, such as a list of notifications. Put a PopoverTrigger and a PopoverContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A small panel that opens from a button and holds more than a sentence, such as the notifications list\n- Content that people read or act on, and that they close with Escape or by clicking away",
+        "whenNotToUse": "- A one-line hint: use Tooltip, or Definition for a term\n- A choice of actions: use DropdownMenu\n- A task that needs the whole screen's attention: use Dialog",
+        "example": "<Popover>\n  <PopoverTrigger>Notifications</PopoverTrigger>\n  <PopoverContent>\n    <PopoverHeader>\n      <PopoverTitle>Notifications</PopoverTitle>\n      <PopoverDescription>No new notifications</PopoverDescription>\n    </PopoverHeader>\n  </PopoverContent>\n</Popover>"
+      },
+      "parts": [
+        {
+          "name": "PopoverContent",
+          "import": "import { PopoverContent } from '@ratio-ui/core'",
+          "description": "The popover panel: a white panel with a 1px outline and no shadow, 288px wide. It opens below the trigger by default.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverDescription",
+          "import": "import { PopoverDescription } from '@ratio-ui/core'",
+          "description": "The supporting text under the title, in the muted colour.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverHeader",
+          "import": "import { PopoverHeader } from '@ratio-ui/core'",
+          "description": "Groups a title and a description at the top of the panel.",
+          "props": []
+        },
+        {
+          "name": "PopoverTitle",
+          "import": "import { PopoverTitle } from '@ratio-ui/core'",
+          "description": "The title of the panel; it names the dialog for screen readers.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverTrigger",
+          "import": "import { PopoverTrigger } from '@ratio-ui/core'",
+          "description": "The element that opens the popover on click or Enter. It renders a button unless render says otherwise.",
+          "props": [
+            {
+              "name": "handle",
+              "type": "PopoverHandle<unknown>",
+              "required": false,
+              "description": "A handle to associate the trigger with a popover."
+            },
+            {
+              "name": "payload",
+              "type": "unknown",
+              "required": false,
+              "description": "A payload to pass to the popover when it is opened."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            },
+            {
+              "name": "delay",
+              "type": "number",
+              "required": false,
+              "default": "300",
+              "description": "How long to wait before the popover may be opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."
+            },
+            {
+              "name": "closeDelay",
+              "type": "number",
+              "required": false,
+              "default": "0",
+              "description": "How long to wait before closing the popover that was opened on hover. Specified in milliseconds.\n\nRequires the `openOnHover` prop."
+            },
+            {
+              "name": "openOnHover",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Whether the popover should also open when the trigger is hovered."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "SaveBar",
+      "import": "import { SaveBar } from '@ratio-ui/core'",
+      "description": "The bar that appears under the top bar when a form is dirty: a message, Discard and Save. It renders in flow, so the page (AppShell) decides where it sits. While saving, Save is disabled; Discard only calls onDiscard.",
+      "props": [
+        {
+          "name": "dirty",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether the form has unsaved changes. The bar renders nothing when false."
+        },
+        {
+          "name": "saving",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "True while the save is running: Save is disabled and reads the saving label."
+        },
+        {
+          "name": "onSave",
+          "type": "() => void",
+          "required": true,
+          "description": "Called by Save."
+        },
+        {
+          "name": "onDiscard",
+          "type": "() => void",
+          "required": true,
+          "description": "Called by Discard. The bar asks nothing itself: confirm in the caller if you need to."
+        },
+        {
+          "name": "message",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Unsaved changes",
+          "description": "The message. Defaults to \"Unsaved changes\"."
+        },
+        {
+          "name": "saveLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Save",
+          "description": "The Save label. Defaults to \"Save\"."
+        },
+        {
+          "name": "savingLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Saving…",
+          "description": "The Save label while saving. Defaults to \"Saving…\"."
+        },
+        {
+          "name": "discardLabel",
+          "type": "ReactNode",
+          "required": false,
+          "default": "Discard",
+          "description": "The Discard label. Defaults to \"Discard\"."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered div."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Under the top bar of a form page, when the form has unsaved changes: \"Unsaved changes\", Discard, Save\n- Drive `dirty` from the form's dirty state and `saving` from the pending save",
+        "whenNotToUse": "- A confirmation: Discard only calls `onDiscard`; open an AlertDialog yourself if the loss needs confirming\n- Per-field saving: save on change or use the field's own action",
+        "example": "```tsx\n<SaveBar dirty={form.isDirty} saving={form.isSaving} onSave={form.save} onDiscard={form.reset} />\n```\n\nIt renders in flow and nothing when not dirty; the app shell decides where it sits. While saving, Save is disabled."
+      }
+    },
+    {
+      "name": "SearchField",
+      "import": "import { SearchField } from '@ratio-ui/core'",
+      "description": "The search field above a listing: a search icon, the input and a clear button that appears once there is text. Escape clears it too. The field reports every change; the debounce stays in the app.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of the field, such as \"Search products\". Required because the field has no visible label."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "description": "The text in the field. Pass it with onValueChange to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "default": "",
+          "description": "The starting text of an uncontrolled field."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called with the new text on every change and when the field is cleared. It is not debounced: debounce in the app."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 above a listing, 32 inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The search above a listing or inside a table, where typing narrows the rows\n- A field that needs a clear button and Escape to clear",
+        "whenNotToUse": "- A search across the whole product from the top bar: use GlobalSearch\n- A field that must wait before searching: debounce in the app, the field reports every keystroke",
+        "example": "<SearchField label=\"Search products\" placeholder=\"Search by name, SKU\" value={query} onValueChange={setQuery} />"
+      }
+    },
+    {
+      "name": "Select",
+      "import": "import { Select } from '@ratio-ui/core'",
+      "description": "A choice from a fixed list. Pass items ({ label, value }[]) so the trigger shows the label of the chosen value. Put a SelectTrigger and a SelectContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A choice from a short, fixed list in a form, such as a GST rate (0, 5, 12, 18, 28%), a return window or a status\n- A field in a table cell: `size={32}` on the trigger\n- A form row with a label, hint, error or required mark: put the Select inside a Field with a function child (see below)",
+        "whenNotToUse": "- A long list, or one the user searches: use a combobox\n- Free text or several values (tags): use Input or TagInput\n- A menu of actions: use DropdownMenu\n- Custom classes or inline styles: no part takes `className` or `style`",
+        "example": "```tsx\nconst rates = [\n  { label: '0%', value: '0' },\n  { label: '18%', value: '18' },\n]\n\n<Select items={rates} defaultValue=\"18\">\n  <SelectTrigger aria-label=\"GST rate\">\n    <SelectValue placeholder=\"Choose a rate\" />\n  </SelectTrigger>\n  <SelectContent>\n    <SelectGroup>\n      <SelectLabel>Rates</SelectLabel>\n      <SelectItem value=\"0\">0%</SelectItem>\n      <SelectItem value=\"18\">18%</SelectItem>\n    </SelectGroup>\n  </SelectContent>\n</Select>\n```\n\nPass `items` to `Select` so the trigger shows the label, not the raw value."
+      },
+      "parts": [
+        {
+          "name": "SelectContent",
+          "import": "import { SelectContent } from '@ratio-ui/core'",
+          "description": "The list: the popover look (8px radius, outline, no shadow, 6px 0 padding), as wide as the trigger. It opens below the trigger.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectGroup",
+          "import": "import { SelectGroup } from '@ratio-ui/core'",
+          "description": "Groups related options under a SelectLabel.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectItem",
+          "import": "import { SelectItem } from '@ratio-ui/core'",
+          "description": "One option. The highlighted one has the accent background, the chosen one a check at its end, a disabled one is dimmed and cannot be chosen.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectLabel",
+          "import": "import { SelectLabel } from '@ratio-ui/core'",
+          "description": "The heading of a group, in the muted colour.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectGroupLabelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectSeparator",
+          "import": "import { SelectSeparator } from '@ratio-ui/core'",
+          "description": "A hairline between groups.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectSeparatorState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SelectTrigger",
+          "import": "import { SelectTrigger } from '@ratio-ui/core'",
+          "description": "The closed field: the chosen value (or the placeholder) and a chevron at the right. Put a SelectValue inside it.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            },
+            {
+              "name": "size",
+              "type": "32 | 36",
+              "required": false,
+              "default": "36",
+              "description": "The height in px: 36 for forms, 32 inside a table. Defaults to 36."
+            }
+          ]
+        },
+        {
+          "name": "SelectValue",
+          "import": "import { SelectValue } from '@ratio-ui/core'",
+          "description": "Shows the label of the chosen option inside the trigger, or the placeholder while nothing is chosen.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SelectValueState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "SideNav",
+      "import": "import { SideNav } from '@ratio-ui/core'",
+      "description": "The 240px side navigation of the admin: an account switcher, blocks of rows with nested groups, counts and collapsible labels, and a footer pinned at the bottom. On a phone it becomes a drawer: inside AppShell the menu button in TopBar opens it and choosing a row closes it; used alone, the caller opens it with `open` and closes it in `onOpenChange`.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of the navigation landmark."
+        },
+        {
+          "name": "sections",
+          "type": "SideNavSection[]",
+          "required": true,
+          "description": "The blocks of rows, top to bottom."
+        },
+        {
+          "name": "active",
+          "type": "string",
+          "required": false,
+          "description": "The id of the current row. It is marked and its group opens."
+        },
+        {
+          "name": "onSelect",
+          "type": "((id: string) => void)",
+          "required": false,
+          "description": "Called with the id of the row pressed."
+        },
+        {
+          "name": "account",
+          "type": "SideNavAccount",
+          "required": false,
+          "description": "The account switcher shown above the rows."
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content pinned at the bottom, such as Settings."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": false,
+          "description": "On a phone, whether the drawer is open."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "On a phone, called when the drawer asks to open or close."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The admin's left navigation: grouped links with nested items, counts and a pinned footer\n- A phone layout where the same navigation slides in as a drawer",
+        "whenNotToUse": "- Switching between views inside one page: use Tabs or FilterTabs\n- A menu of actions: use DropdownMenu",
+        "example": "<SideNav\n  label=\"Main\"\n  active=\"orders\"\n  onSelect={setView}\n  sections={[{ id: 'main', items: [{ id: 'home', label: 'Home', icon: 'nav-home' }, { id: 'orders', label: 'Orders', count: '12' }] }]}\n  footer={<a href=\"/settings\">Settings</a>}\n/>"
+      }
+    },
+    {
+      "name": "Skeleton",
+      "import": "import { Skeleton } from '@ratio-ui/core'",
+      "description": "A static placeholder for content that is still loading on a first load. It is hidden from assistive technology: the container that holds it says it is busy. Its fill and animation come from the loading tokens, so it does not move.",
+      "props": [
+        {
+          "name": "shape",
+          "type": "\"block\" | \"circle\" | \"line\"",
+          "required": false,
+          "default": "line",
+          "description": "The shape of the placeholder. Defaults to line. A line and a block fill the width of their parent."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A first load, where the shape of the content is known: a line for text, a block for a tile, a circle for an avatar\n- Under real headings in a table, so the columns stay put while the rows load",
+        "whenNotToUse": "- A refetch of content already on screen: keep the content and show the thin progress bar\n- A wait with no known shape: use Spinner\n- A load that has failed or returned nothing: use EmptyState",
+        "example": "<Skeleton shape=\"line\" />\n<Skeleton shape=\"circle\" />"
+      }
+    },
+    {
+      "name": "Spinner",
+      "import": "import { Spinner } from '@ratio-ui/core'",
+      "description": "A small ring for a wait with no known shape. It is static until the designer answers question 5: its motion is the --rt-spinner-animation token, none for now, so the ring is drawn from the progress colours and the status role says what it means.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "default": "Loading",
+          "description": "The accessible name, announced to assistive technology. Defaults to Loading."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A short wait where the shape of the result is not known, such as a button that saves or a panel that opens",
+        "whenNotToUse": "- A first load of a list or table: use Skeleton rows\n- A refetch of content on screen: use the thin progress bar",
+        "example": "<Spinner label=\"Saving\" />"
+      }
+    },
+    {
+      "name": "Stack",
+      "import": "import { Stack } from '@ratio-ui/core'",
+      "description": "Lays its children out in a column with a fixed space between them. It takes no className and no style: the gap is a step of the design system's spacing scale, and the layout is the only styling it has.",
+      "props": [
+        {
+          "name": "gap",
+          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "required": true,
+          "description": "The space between children, a step of the design system's scale in px: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\" | \"stretch\"",
+          "required": false,
+          "default": "stretch",
+          "description": "How children line up across the stack, which is the horizontal axis. Defaults to stretch, which fills the width."
+        },
+        {
+          "name": "as",
+          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "required": false,
+          "default": "div",
+          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Children one under another with a fixed space between them: form fields, the parts of a card, page sections\n- A gap taken from the design system's spacing scale: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80 px\n- A column that is also a list or a landmark: `as` renders `ul`, `ol`, `li`, `nav`, `header`, `footer`, `main`, `aside`, `section`, `form` or `fieldset` instead of `div`",
+        "whenNotToUse": "- Children side by side: use Inline\n- Space around one child or at the edge of a container: Stack spaces siblings only, and has no padding or margin\n- A gap that is not on the scale: 10 or 16 is a type error, so use the nearest step\n- Styling: Stack takes no `className` and no `style`\n- A list without markers: `as=\"ul\"` and `as=\"ol\"` leave the browser's list markers as they are",
+        "example": "<Stack gap={12}>\n  <div>Settlement summary</div>\n  <Stack gap={4} align=\"start\">\n    <div>Paid out every weekday</div>\n    <div>Next payout on Monday</div>\n  </Stack>\n</Stack>"
+      }
+    },
+    {
+      "name": "StatusPill",
+      "import": "import { StatusPill } from '@ratio-ui/core'",
+      "description": "A 20px pill with a 4px radius and a 1px border that names the state of a row, such as a product's status in a listing.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"neutral\" | \"success\" | \"warning\"",
+          "required": false,
+          "default": "neutral",
+          "description": "The colour of the pill. Defaults to neutral."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "required": false,
+          "description": "Receives the rendered span."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The state of a row or record in a listing: Draft, Active, Hidden, Low, Pending\n- A single-word status, with success for a good state and warning for one that needs a look",
+        "whenNotToUse": "- A count or a tag that is not a status\n- A state that needs its own colour: the design system has two tones, and neutral is plain text until question 3 is answered\n- A button or a link: the pill is not interactive",
+        "example": "<StatusPill tone=\"success\">Active</StatusPill>"
+      }
+    },
+    {
+      "name": "SummaryChips",
+      "import": "import { SummaryChips } from '@ratio-ui/core'",
+      "description": "A row of 20px chips that summarise values, such as the ones a collapsed section still shows.",
+      "props": [
+        {
+          "name": "items",
+          "type": "readonly SummaryChip[]",
           "required": true,
-          "description": "Which icon to draw, by name."
+          "description": "The chips, in order. Nothing is rendered when empty."
         },
         {
-          "name": "size",
-          "type": "8 | 12 | 16",
+          "name": "ref",
+          "type": "Ref<HTMLUListElement>",
           "required": false,
-          "default": "12",
-          "description": "The square box in px: 8, 12 or 16. Defaults to 12, the size inside controls."
+          "description": "Receives the rendered list."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A collapsed section that still shows its values: \"Cost price · HSN code · Includes GST Yes\"\n- A short read-only summary of a record's settings",
+        "whenNotToUse": "- Values the person can edit or remove: use a tag input\n- A status of a row: use StatusPill",
+        "example": "<SummaryChips items={[{ label: 'Cost price', value: '₹450.00' }, { label: 'Includes GST', value: 'Yes' }]} />"
+      }
+    },
+    {
+      "name": "Switch",
+      "import": "import { Switch } from '@ratio-ui/core'",
+      "description": "An on/off switch, 32px by 18px. Off it is drawn with the control hairline; on it is filled in the primary colour. In forced-colours mode the thumb keeps a system-colour outline, and its side shows the state. The thumb jumps to the other end with no slide, and colours fade over 120ms.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- An on/off setting that takes effect as soon as it changes, such as \"Inventory tracked\" or \"Cash on delivery\"\n- Give it an `aria-label`, or a label that points to it",
+        "whenNotToUse": "- A choice that is sent with a form and several others: use Checkbox\n- Custom classes or inline styles: Switch takes no `className` and no `style`",
+        "example": "<Switch aria-label=\"Inventory tracked\" defaultChecked />"
+      }
+    },
+    {
+      "name": "Table",
+      "import": "import { Table } from '@ratio-ui/core'",
+      "description": "A data table in the design system's Listing look: a 36px heading row over 48px rows split by 1px hairlines, 12px uppercase headings and a fill on the row under the pointer. It scrolls sideways inside its own box when the columns do not fit. Compose it from TableHeader, TableBody, TableRow, TableHead and TableCell.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Rows of records with the same columns: products, orders, customers\n- A list that needs headings, right-aligned numbers and a hover fill\n- Static content composed by hand; for sorting, selection and paging use DataTable",
+        "whenNotToUse": "- Layout: a table is for data, so use Stack and Inline to arrange a page\n- A single record's fields: use a definition list or a card\n- Styling: the parts take no `className` and no `style`",
+        "example": "<Table>\n  <TableHeader>\n    <TableRow>\n      <TableHead>Product</TableHead>\n      <TableHead numeric>Stock</TableHead>\n    </TableRow>\n  </TableHeader>\n  <TableBody>\n    <TableRow>\n      <TableCell>RYZE - 2mg</TableCell>\n      <TableCell numeric>1200</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>"
+      },
+      "parts": [
+        {
+          "name": "TableBody",
+          "import": "import { TableBody } from '@ratio-ui/core'",
+          "description": "The data rows of a table. Its rows take the hover fill.",
+          "props": []
         },
         {
-          "name": "tone",
-          "type": "\"current\" | \"icon\" | \"primary\" | \"subdued\"",
+          "name": "TableCaption",
+          "import": "import { TableCaption } from '@ratio-ui/core'",
+          "description": "The table's title for assistive technology, shown under the table in the subdued colour.",
+          "props": []
+        },
+        {
+          "name": "TableCell",
+          "import": "import { TableCell } from '@ratio-ui/core'",
+          "description": "One cell. Text stays on one line; a numeric cell is right aligned with tabular figures so digits line up.",
+          "props": [
+            {
+              "name": "numeric",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Aligns the cell to the right with tabular figures, for a number. Defaults to false, which aligns it to the left."
+            }
+          ]
+        },
+        {
+          "name": "TableFooter",
+          "import": "import { TableFooter } from '@ratio-ui/core'",
+          "description": "The summary rows at the foot of a table, such as totals. Its rows take no hover fill.",
+          "props": []
+        },
+        {
+          "name": "TableHead",
+          "import": "import { TableHead } from '@ratio-ui/core'",
+          "description": "A column heading: 12px uppercase text in the subdued colour. It is a column header unless `scope` says otherwise.",
+          "props": [
+            {
+              "name": "numeric",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Aligns the heading to the right, over a column of numbers. Defaults to false, which aligns it to the left."
+            }
+          ]
+        },
+        {
+          "name": "TableHeader",
+          "import": "import { TableHeader } from '@ratio-ui/core'",
+          "description": "The heading rows of a table. Its rows take no hover fill.",
+          "props": []
+        },
+        {
+          "name": "TableRow",
+          "import": "import { TableRow } from '@ratio-ui/core'",
+          "description": "One row, 48px high (36px in the heading), with a hairline under it. A body row is filled when the pointer is over it or it is selected.",
+          "props": [
+            {
+              "name": "selected",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Keeps the hover fill on the row to show it is chosen, for example when its checkbox is ticked. Defaults to false."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TableLoader",
+      "import": "import { TableLoader } from '@ratio-ui/core'",
+      "description": "What a table shows on its first load: the real headings over static skeleton rows, and a count line such as \"72 of 1000 products\". The table is marked busy and the fake rows are hidden from screen readers. Use it for the first load only; later loads keep the old rows.",
+      "props": [
+        {
+          "name": "columns",
+          "type": "TableLoaderColumn[]",
+          "required": true,
+          "description": "The columns, in order."
+        },
+        {
+          "name": "rows",
+          "type": "number",
           "required": false,
-          "default": "current",
-          "description": "The colour. current, the default, takes the colour of the text around the icon; the other tones set their own."
+          "default": "5",
+          "description": "How many placeholder rows to draw. Defaults to 5."
         },
         {
-          "name": "label",
+          "name": "shown",
+          "type": "number",
+          "required": true,
+          "description": "How many results the first page will hold, for the count line."
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "required": true,
+          "description": "How many results there are in all."
+        },
+        {
+          "name": "noun",
           "type": "string",
-          "required": false,
-          "description": "The accessible name. With a label the icon is an image that assistive technology announces under that name. Without one it is decoration, hidden from assistive technology, and the text beside it has to say what it means."
+          "required": true,
+          "description": "What the results are called, in the plural: \"products\"."
         }
       ],
       "usage": {
-        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16, and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle and info-circle. They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
-        "whenNotToUse": "- Decoration that adds no meaning. An icon next to text that already says the same thing is hidden from assistive technology, so leave the label off, and leave the icon out when it adds nothing\n- An icon the registry does not have. Components accept no className or style, and icons come from the registry only, so a new one is a registry entry: the design system's glyph first, Tabler for the rest\n- An icon-only control without a name. Pass label, or give the control its own accessible name\n- A size other than 8, 12 or 16, or a colour other than the four tones. There is no red, no destructive colour and no third accent: an error is marked with the alert-triangle glyph beside its message, not with a colour\n- Emoji, or unicode arrows and symbols, as icons. Inter's web subsets do not hold them and the design system bans them",
-        "example": "import { Icon } from '@ratio-ui/core'\n\n// Beside text that names it: decoration, hidden from assistive technology\n<button type=\"button\">\n  <Icon name=\"plus\" />\n  Add product\n</button>\n\n// Alone: the label is the accessible name\n<Icon name=\"search\" tone=\"icon\" label=\"Search\" />\n\n// Pagination chevrons are drawn for an 8px box\n<Icon name=\"chevron-right\" size={8} />"
+        "whenToUse": "- The first load of a list: it shows the real headings over static skeleton rows, with a count such as \"72 of 1000 products\"\n- When the column headings are known before the data arrives",
+        "whenNotToUse": "- Later loads such as a new page or sort: keep the old rows and show them as busy\n- Content that is not a table: use Skeleton on its own\n- Styling: it takes no `className` and no `style`",
+        "example": "<TableLoader\n  aria-label=\"Products\"\n  columns={[{ id: 'name', header: 'Product' }, { id: 'stock', header: 'Stock', numeric: true }]}\n  shown={72}\n  total={1000}\n  noun=\"products\"\n/>"
       }
     },
     {
-      "name": "Inline",
-      "import": "import { Inline } from '@ratio-ui/core'",
-      "description": "Lays its children out in a row with a fixed space between them. It takes no className and no style: the gap is a step of the design system's spacing scale, and the layout is the only styling it has.",
+      "name": "Tabs",
+      "import": "import { Tabs } from '@ratio-ui/core'",
+      "description": "Sections of one page, switched by an underlined row of tabs: ABC analysis, the sections of a settings page. Holds the selected value, uncontrolled with defaultValue or controlled with value and onValueChange. To filter a list use FilterTabs, which looks like the design system's chip tab.",
       "props": [
         {
-          "name": "gap",
-          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "name": "render",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsRootState>",
+          "required": false,
+          "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Sections of one page that share a heading, such as the steps of an ABC analysis or the parts of a settings page\n- Content that is shown one section at a time, with the section named by an underlined tab\n- A row of tabs whose panels sit on the same page: the tab list and the panels are tied by value",
+        "whenNotToUse": "- A single choice that filters a list, such as All, Active and Inactive above a table: use FilterTabs\n- Moving to another page: use a link\n- Steps that must be done in order: use a wizard",
+        "example": "<Tabs defaultValue=\"rules\">\n  <TabsList aria-label=\"Sections\">\n    <TabsTrigger value=\"rules\">Rules</TabsTrigger>\n    <TabsTrigger value=\"history\">History</TabsTrigger>\n  </TabsList>\n  <TabsContent value=\"rules\">Rules</TabsContent>\n  <TabsContent value=\"history\">History</TabsContent>\n</Tabs>"
+      },
+      "parts": [
+        {
+          "name": "TabsContent",
+          "import": "import { TabsContent } from '@ratio-ui/core'",
+          "description": "The panel of the tab with the same value; only the selected one is shown.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsPanelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TabsList",
+          "import": "import { TabsList } from '@ratio-ui/core'",
+          "description": "The row of tabs, with a hairline under it. Give it an aria-label that names the sections.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsListState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TabsTrigger",
+          "import": "import { TabsTrigger } from '@ratio-ui/core'",
+          "description": "One tab: 36px tall, with a 2px blue underline and a blue semibold label when selected. A disabled tab is at 50%.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsTabState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TagInput",
+      "import": "import { TagInput } from '@ratio-ui/core'",
+      "description": "Several values as chips in one field in the input's look. The picker offers the existing values (typing filters them), a small field below adds a new one on Enter, and a chip goes with its remove button or with Backspace in the empty picker. Base UI's combobox cannot accept a value it does not list, which is why new values have their own field.",
+      "props": [
+        {
+          "name": "options",
+          "type": "readonly string[]",
           "required": true,
-          "description": "The space between children, a step of the design system's scale in px: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80."
+          "description": "The existing values the picker offers, such as S, M, L, XL and XXL."
         },
         {
-          "name": "align",
-          "type": "\"baseline\" | \"center\" | \"end\" | \"start\" | \"stretch\"",
+          "name": "value",
+          "type": "readonly string[]",
           "required": false,
-          "default": "center",
-          "description": "How children line up across the row, which is the vertical axis. Defaults to center."
+          "description": "The chosen values, in order, when the owner holds the state."
         },
         {
-          "name": "justify",
-          "type": "\"between\" | \"center\" | \"end\" | \"start\"",
+          "name": "defaultValue",
+          "type": "readonly string[]",
           "required": false,
-          "default": "start",
-          "description": "How children spread along the row, which is the horizontal axis. Defaults to start."
+          "description": "The values chosen at first, when the component holds the state."
         },
         {
-          "name": "wrap",
+          "name": "onValueChange",
+          "type": "((value: string[]) => void)",
+          "required": false,
+          "description": "Called with every new list of values: after a pick, an added value or a removal."
+        },
+        {
+          "name": "creatable",
           "type": "boolean",
           "required": false,
-          "default": "false",
-          "description": "Whether children move to a new line when the row is full. Defaults to false, which keeps one line."
+          "default": "true",
+          "description": "Shows a small field that adds a typed value on Enter. Defaults to true."
         },
         {
-          "name": "as",
-          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "name": "addLabel",
+          "type": "string",
           "required": false,
-          "default": "div",
-          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+          "default": "Add value",
+          "description": "The placeholder and accessible name of the small field. Defaults to \"Add value\"."
         },
         {
-          "name": "ref",
-          "type": "Ref<HTMLElement>",
+          "name": "placeholder",
+          "type": "string",
           "required": false,
-          "description": "Receives the rendered element."
-        }
-      ],
-      "usage": {
-        "whenToUse": "- Children side by side with a fixed space between them: a toolbar, a row of tags, a label next to a value\n- Children that spread along the row (`justify`: start, center, end or between) or move to the next line when the row is full (`wrap`)\n- A gap taken from the design system's spacing scale: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80 px\n- A row that is also a list or a landmark: `as` renders `ul`, `ol`, `li`, `nav`, `header`, `footer`, `main`, `aside`, `section`, `form` or `fieldset` instead of `div`",
-        "whenNotToUse": "- Children one under another: use Stack\n- Columns that have to line up from one row to the next: Inline lays out one row at a time, and wave 0 has no grid\n- Space around one child or at the edge of a container: Inline spaces siblings only, and has no padding or margin\n- Styling: Inline takes no `className` and no `style`\n- A list without markers: `as=\"ul\"` and `as=\"ol\"` leave the browser's list markers as they are",
-        "example": "<Inline gap={8} justify=\"between\" wrap>\n  <div>Orders</div>\n  <Inline gap={4}>\n    <div>Export</div>\n    <div>Filter</div>\n  </Inline>\n</Inline>"
-      }
-    },
-    {
-      "name": "Stack",
-      "import": "import { Stack } from '@ratio-ui/core'",
-      "description": "Lays its children out in a column with a fixed space between them. It takes no className and no style: the gap is a step of the design system's spacing scale, and the layout is the only styling it has.",
-      "props": [
+          "description": "The placeholder of the picker, shown while nothing is chosen."
+        },
         {
-          "name": "gap",
-          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
-          "required": true,
-          "description": "The space between children, a step of the design system's scale in px: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80."
+          "name": "emptyText",
+          "type": "string",
+          "required": false,
+          "default": "No matching values",
+          "description": "The line the list shows when no value matches the typed text. Defaults to \"No matching values\"."
         },
         {
-          "name": "align",
-          "type": "\"center\" | \"end\" | \"start\" | \"stretch\"",
+          "name": "name",
+          "type": "string",
           "required": false,
-          "default": "stretch",
-          "description": "How children line up across the stack, which is the horizontal axis. Defaults to stretch, which fills the width."
+          "description": "The form field name: one hidden input per chosen value is submitted under it."
         },
         {
-          "name": "as",
-          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "name": "disabled",
+          "type": "boolean",
           "required": false,
-          "default": "div",
-          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+          "description": "Dims the component and stops every change."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the picker's input, which a label points to."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the picker, when no label points to it."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of the element that names the picker."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the hint or error that describe the component."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the values as invalid, which draws the error ring."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the values as required."
         },
         {
           "name": "ref",
-          "type": "Ref<HTMLElement>",
+          "type": "Ref<HTMLInputElement>",
           "required": false,
-          "description": "Receives the rendered element."
+          "description": "Receives the picker's input element."
         }
       ],
       "usage": {
-        "whenToUse": "- Children one under another with a fixed space between them: form fields, the parts of a card, page sections\n- A gap taken from the design system's spacing scale: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80 px\n- A column that is also a list or a landmark: `as` renders `ul`, `ol`, `li`, `nav`, `header`, `footer`, `main`, `aside`, `section`, `form` or `fieldset` instead of `div`",
-        "whenNotToUse": "- Children side by side: use Inline\n- Space around one child or at the edge of a container: Stack spaces siblings only, and has no padding or margin\n- A gap that is not on the scale: 10 or 16 is a type error, so use the nearest step\n- Styling: Stack takes no `className` and no `style`\n- A list without markers: `as=\"ul\"` and `as=\"ol\"` leave the browser's list markers as they are",
-        "example": "<Stack gap={12}>\n  <div>Settlement summary</div>\n  <Stack gap={4} align=\"start\">\n    <div>Paid out every weekday</div>\n    <div>Next payout on Monday</div>\n  </Stack>\n</Stack>"
+        "whenToUse": "- Several values in one field, such as a product's tags or a variant option's values (S, M, L, XL, XXL)\n- Picking from existing values, with typing to filter them, and adding a new one in the small field below (Enter adds it)\n- Inside a Field: the label, hint, error and required mark land on the picker",
+        "whenNotToUse": "- One value from a fixed list: use Select\n- A read-only summary of values: use SummaryChips\n- Only existing values and no new ones: keep TagInput and set `creatable={false}`\n- Custom classes or inline styles: TagInput takes no `className` and no `style`",
+        "example": "```tsx\nconst [sizes, setSizes] = useState(['S', 'M'])\n\n<Field label=\"Size\" error={errors.size}>\n  <TagInput options={['S', 'M', 'L', 'XL', 'XXL']} value={sizes} onValueChange={setSizes} placeholder=\"Choose sizes\" />\n</Field>\n```\n\nA chip goes with its remove button, or with Backspace in the empty picker. A new value is trimmed, takes the spelling of an existing value that differs only in letter case, and is not added twice. Base UI's combobox cannot accept a value it does not list, so new values have their own field."
       }
     },
     {
@@ -174,6 +2684,253 @@
         "whenNotToUse": "- Text in a button: buttons take the design system's two button styles, which are not Text variants\n- A colour that is not a tone: `color` is a type error, and so are `className` and `style`\n- A style that is not in the type scale: `variant=\"h2\"` is a type error, so pick the nearest of the 13\n- Space around text: use Stack or Inline\n- Several lines cut at a number of lines: `truncate` keeps one line",
         "example": "<Text as=\"h1\" variant=\"h1\">Settlements</Text>\n<Text tone=\"subdued\">Paid out every weekday</Text>"
       }
+    },
+    {
+      "name": "Textarea",
+      "import": "import { Textarea } from '@ratio-ui/core'",
+      "description": "A multi-line text field in the input's look: 8px radius, 1px ring that turns blue on focus, 10px 12px padding, 88px tall (64px compact).",
+      "props": [
+        {
+          "name": "size",
+          "type": "64 | 88",
+          "required": false,
+          "default": "88",
+          "description": "The height in px: 88 by default, 64 compact. The field can still be dragged taller."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTextAreaElement>",
+          "required": false,
+          "description": "Receives the textarea element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A multi-line text field such as a product description: 88px tall by default, `size={64}` for a compact one\n- A field with an error: set `aria-invalid` and the ring changes, and put the error message beside it in text",
+        "whenNotToUse": "- A single line of text: use Input\n- Custom classes or inline styles: Textarea takes no `className` and no `style`",
+        "example": "<Textarea aria-label=\"Description\" placeholder=\"Describe the product\" />\n<Textarea aria-label=\"Note\" size={64} />"
+      }
+    },
+    {
+      "name": "Toaster",
+      "import": "import { Toaster } from '@ratio-ui/core'",
+      "description": "Mounts the toast viewport, bottom right, once for the app. Messages from toast() appear in it as plain panels with the ring outline, stacked, with no entrance animation.",
+      "props": [
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "default": "Close notification",
+          "description": "The accessible name of each close button. Defaults to Close notification."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Telling the user what happened after an action: a saved product, a started sync, a failed request\n- One of three kinds: `toast.success`, `toast.info` or `toast.error`; each is announced to screen readers",
+        "whenNotToUse": "- A decision the user must make: use a Dialog\n- A message that has to stay on the page: use a banner\n- Field validation: show it on the field",
+        "example": "<Toaster />\n\ntoast.success('Product saved')\ntoast.error('Could not save', { description: 'Try again' })"
+      }
+    },
+    {
+      "name": "Tooltip",
+      "import": "import { Tooltip } from '@ratio-ui/core'",
+      "description": "A short hint for a control or term, shown on hover and keyboard focus. Put a TooltipTrigger and a TooltipContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short hint for an icon-only control or an \"i\" icon: it opens on hover and on keyboard focus\n- Extra detail that is not needed to finish the task, one short sentence\n- Wrap the app once in TooltipProvider so the tooltips share their open delay",
+        "whenNotToUse": "- A term in running text that explains itself: use Definition, which keyboard and touch users can open\n- Anything with a link, button or form inside: use Popover\n- Information that touch users need: a tooltip does not open on touch, so show the text on the screen",
+        "example": "<TooltipProvider>\n  <Tooltip>\n    <TooltipTrigger>Settlement</TooltipTrigger>\n    <TooltipContent>Paid out every weekday</TooltipContent>\n  </Tooltip>\n</TooltipProvider>"
+      },
+      "parts": [
+        {
+          "name": "TooltipContent",
+          "import": "import { TooltipContent } from '@ratio-ui/core'",
+          "description": "The tooltip text: a dark panel with light text, no shadow and no animation. It sits above the trigger by default.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TooltipProvider",
+          "import": "import { TooltipProvider } from '@ratio-ui/core'",
+          "description": "Shares the open delay between the tooltips inside it. Wrap the app, or a group of tooltips, once. The delay defaults to 0 ms.",
+          "props": []
+        },
+        {
+          "name": "TooltipTrigger",
+          "import": "import { TooltipTrigger } from '@ratio-ui/core'",
+          "description": "The element that opens the tooltip on hover and focus. It renders a button unless render says otherwise.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TopBar",
+      "import": "import { TopBar } from '@ratio-ui/core'",
+      "description": "The bar across the top of every page: logo, search, actions, the store switcher and the account. It is 60px high on a desktop and 52px on a phone, with a hairline under it. The parts are slots, so the bar does not depend on their components. Inside an AppShell with a side nav it shows a menu button on phones, which opens the side nav drawer.",
+      "props": [
+        {
+          "name": "logo",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The logo, usually an image. When it is left out the bar shows the text wordmark instead (--rt-wordmark)."
+        },
+        {
+          "name": "wordmarkLabel",
+          "type": "string",
+          "required": false,
+          "default": "Ratio",
+          "description": "The accessible name of the text wordmark, shown when there is no logo. Defaults to Ratio."
+        },
+        {
+          "name": "menuLabel",
+          "type": "string",
+          "required": false,
+          "default": "Open navigation menu",
+          "description": "The accessible name of the phone menu button that opens the side navigation. Defaults to Open navigation menu."
+        },
+        {
+          "name": "search",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The global search, for example GlobalSearch. It takes the free space in the middle."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The buttons at the right, such as help and notifications."
+        },
+        {
+          "name": "storeSwitcher",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The store switcher, for example StoreSwitcher. It sits at the right, after the actions."
+        },
+        {
+          "name": "account",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The account at the far right, such as an Avatar or a menu of the signed-in person."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The bar across the top of the admin: logo, global search, actions, the store switcher and the account\n- Inside AppShell's `topBar` slot",
+        "whenNotToUse": "- A heading for one page: use PageHeader\n- Navigation between sections: use SideNav",
+        "example": "<TopBar\n  search={<GlobalSearch />}\n  actions={<Button variant=\"ghost\">Help</Button>}\n  storeSwitcher={<StoreSwitcher stores={stores} storeId={storeId} onStoreChange={setStoreId} />}\n  account={<Avatar name=\"Naman Gupta\" />}\n/>"
+      },
+      "parts": [
+        {
+          "name": "StoreSwitcher",
+          "import": "import { StoreSwitcher } from '@ratio-ui/core'",
+          "description": "The store switcher of TopBar: a square avatar, the store name and a chevron that open a menu of the stores the app passes. On a phone only the avatar shows. Pass it to TopBar's `storeSwitcher` slot.",
+          "props": [
+            {
+              "name": "stores",
+              "type": "StoreOption[]",
+              "required": true,
+              "description": "The stores the person can switch between, as the app passes them."
+            },
+            {
+              "name": "storeId",
+              "type": "string",
+              "required": true,
+              "description": "The id of the current store."
+            },
+            {
+              "name": "onStoreChange",
+              "type": "((id: string) => void)",
+              "required": false,
+              "description": "Called with the id of the store chosen."
+            },
+            {
+              "name": "label",
+              "type": "string",
+              "required": false,
+              "default": "Switch store",
+              "description": "The caption of its menu. Defaults to Switch store. The button is named by the store name."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "UnitInput",
+      "import": "import { UnitInput } from '@ratio-ui/core'",
+      "description": "A number field with its unit after it, inside one ring: a weight in kg, a length in cm. It takes and gives a number, written without thousands separators as counts are, and keeps at most `decimals` decimals.",
+      "props": [
+        {
+          "name": "unit",
+          "type": "string",
+          "required": true,
+          "description": "The unit after the number, such as kg or cm. Screen readers read it as the field's description."
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "required": false,
+          "description": "The number, or null for an empty field. Pass it to control the field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "required": false,
+          "description": "The starting number when the field is not controlled. Defaults to empty."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: number | null) => void)",
+          "required": false,
+          "description": "Called with the number as it is typed or cleared (null when empty), and with the rounded number on blur."
+        },
+        {
+          "name": "decimals",
+          "type": "number",
+          "required": false,
+          "default": "3",
+          "description": "The most decimals the number keeps; the field rounds to them on blur. Defaults to 3 (grams in kg)."
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "required": false,
+          "description": "The smallest number; the field moves a smaller one up to it on blur."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "description": "The largest number; the field moves a larger one down to it on blur."
+        },
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A number with a unit after it: weight in kg, length in cm, a lead time in days\n- Values stored as numbers: `value` and `onValueChange` take and give a number, null when empty\n- A field inside a table: `size` 32",
+        "whenNotToUse": "- Money: use MoneyInput, which takes and gives paise\n- A unit before the number, or an icon: use InputGroup with an addon\n- Text that is not a number: use Input\n- Custom classes or inline styles: UnitInput takes neither `className` nor `style`",
+        "example": "const [weight, setWeight] = useState<number | null>(0.24)\n\n<UnitInput aria-label=\"Weight\" unit=\"kg\" value={weight} onValueChange={setWeight} min={0} />\n<UnitInput aria-label=\"Length\" unit=\"cm\" decimals={0} defaultValue={30} name=\"length\" />"
+      }
     }
   ]
 }