@ratio-ui/core 0.2.0 → 0.4.0

package/dist/catalogue.json

@@ -1,6 +1,177 @@
 {
-  "version": "0.2.0",
+  "version": "0.4.0",
   "components": [
+    {
+      "name": "Accordion",
+      "import": "import { Accordion } from '@ratio-ui/core'",
+      "description": "A stack of sections that open and close. One section is open at a time unless multiple is set.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Grouped help or settings where the reader opens only the section they need\n- A short list of sections with a heading each, such as setup steps or FAQs",
+        "whenNotToUse": "- A single block that hides and shows: use a collapsible\n- Switching between views of the same content: use tabs\n- Styling: Accordion takes no `className` and no `style`",
+        "example": "<Accordion>\n  <AccordionItem value=\"shipping\">\n    <AccordionTrigger>Shipping</AccordionTrigger>\n    <AccordionContent>Ships in two days.</AccordionContent>\n  </AccordionItem>\n</Accordion>"
+      },
+      "parts": [
+        {
+          "name": "AccordionItem",
+          "import": "import { AccordionItem } from '@ratio-ui/core'",
+          "description": "One section: a trigger and its content, separated from the next by a hairline.",
+          "props": []
+        },
+        {
+          "name": "AccordionTrigger",
+          "import": "import { AccordionTrigger } from '@ratio-ui/core'",
+          "description": "The heading row of a section, with a chevron that turns when it is open.",
+          "props": []
+        },
+        {
+          "name": "AccordionContent",
+          "import": "import { AccordionContent } from '@ratio-ui/core'",
+          "description": "The body of a section. It appears and disappears at once, with no height animation.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "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'",
@@ -94,6 +265,36 @@
         "example": "<Avatar name=\"My Store\" shape=\"square\" />\n<Avatar name=\"Kavya Singh\" />"
       }
     },
+    {
+      "name": "Breadcrumb",
+      "import": "import { Breadcrumb } from '@ratio-ui/core'",
+      "description": "The trail to the current page: links, chevron separators, the current page as text and an overflow ellipsis.",
+      "props": [
+        {
+          "name": "items",
+          "type": "BreadcrumbItem[]",
+          "required": true,
+          "description": "The trail, from the root to the current page."
+        },
+        {
+          "name": "maxItems",
+          "type": "number",
+          "required": false,
+          "description": "Past this many items the middle ones collapse behind an ellipsis, keeping the first and the last two."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered nav."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Show where a page sits in a hierarchy, with a way back up",
+        "whenNotToUse": "- Switching between sibling views: use Tabs",
+        "example": "<Breadcrumb items={[{ label: 'Products', href: '/products' }, { label: 'Runner' }]} maxItems={4} />"
+      }
+    },
     {
       "name": "Button",
       "import": "import { Button } from '@ratio-ui/core'",
@@ -138,6 +339,17 @@
         "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'",
@@ -190,1125 +402,2609 @@
       ]
     },
     {
-      "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": "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.",
+      "name": "Chart",
+      "import": "import { Chart } from '@ratio-ui/core'",
+      "description": "A chart on Recharts, drawn with the chart tokens. It holds the config the tooltip and legend read, styles Recharts' ticks, grid and cursor with the tokens, and is a figure named by its label and summarised by a description, a visually hidden data table, or both. Motion is colour fades only, so every series passes isAnimationActive false.",
       "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",
+          "name": "description",
+          "type": "string",
           "required": false,
-          "description": "The page on show, counting from 1. Pass with `pageSize`, `total` and `onPageChange` to show the footer."
+          "description": "One sentence on what the chart shows, read after its name, such as \"Sales peak on Tuesday\"."
         },
         {
-          "name": "pageSize",
-          "type": "number",
+          "name": "table",
+          "type": "ChartTable",
           "required": false,
-          "description": "How many results one page holds."
+          "description": "The chart's rows as a visually hidden table, for assistive technology."
         },
         {
-          "name": "total",
-          "type": "number",
-          "required": false,
-          "description": "How many results there are in all, across every page."
+          "name": "config",
+          "type": "ChartConfig",
+          "required": true,
+          "description": "The series and categories, by data key: their labels, icons and chart tokens."
         },
         {
-          "name": "onPageChange",
-          "type": "((page: number) => void)",
-          "required": false,
-          "description": "Called with the page to show."
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The chart's accessible name, such as \"Sales by day\"."
         },
         {
-          "name": "rowHref",
-          "type": "((row: T) => string)",
+          "name": "aspect",
+          "type": "\"fill\" | \"square\" | \"video\"",
           "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."
+          "default": "video",
+          "description": "The size: video (16:9, the default) or square at the full width, or fill to take the parent's size."
         },
         {
-          "name": "empty",
-          "type": "ReactNode",
+          "name": "initialDimension",
+          "type": "{ width: number; height: number; }",
           "required": false,
-          "description": "Shown in place of the rows when there are none and the table is not loading. Usually an EmptyState."
+          "default": "{ width: 320, height: 200 } as const",
+          "description": "The size the chart is drawn at before it measures its box. Defaults to 320 by 200."
         },
         {
-          "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."
+          "name": "children",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+          "required": true,
+          "description": "One Recharts chart, such as a BarChart or a LineChart, whose series pass isAnimationActive false."
         }
       ],
       "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": "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": [
+        "whenToUse": "- Analytics: a trend or a comparison over days or categories, as bars or lines\n- The page loader's bar mark\n- With a label and a one-sentence description, a data table, or both, so assistive technology gets the same summary\n- Every series passes isAnimationActive false: motion is colour fades only, and the tooltip never moves",
+        "whenNotToUse": "- A single number or a few numbers side by side: use MetricStrip\n- Progress towards an end: use Progress\n- Colours outside chart-1 to chart-5, or chart-4 and chart-5 alone on white: they sit below 3:1, so draw them beside a darker series",
+        "example": "import { Bar, BarChart, CartesianGrid, XAxis } from 'recharts'\n\nconst config = { sales: { label: 'Sales', color: 'chart-1' } } satisfies ChartConfig\n\n<Chart config={config} label=\"Sales by day\" description=\"Sales peak on Friday\">\n  <BarChart data={week} accessibilityLayer>\n    <CartesianGrid vertical={false} />\n    <XAxis dataKey=\"day\" tickLine={false} axisLine={false} />\n    <ChartTooltip content={<ChartTooltipContent formatValue={formatMoney} />} />\n    <Bar dataKey=\"sales\" fill={chartColor('chart-1')} isAnimationActive={false} />\n  </BarChart>\n</Chart>"
+      },
+      "parts": [
         {
-          "name": "children",
-          "type": "ReactNode",
-          "required": true,
-          "description": "The term, shown in the text with a dotted underline."
+          "name": "ChartTooltip",
+          "import": "import { ChartTooltip } from '@ratio-ui/core'",
+          "description": "The chart's tooltip: Recharts' Tooltip, still (no movement), drawing ChartTooltipContent unless given other content.",
+          "props": [
+            {
+              "name": "cursor",
+              "type": "boolean",
+              "required": false,
+              "description": "Shows the cursor line or band under the pointer. On or off: Recharts' SVG props would carry a class name and a style."
+            }
+          ]
         },
         {
-          "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.",
+          "name": "ChartTooltipContent",
+          "import": "import { ChartTooltipContent } from '@ratio-ui/core'",
+          "description": "The box a chart tooltip draws: the active point's label, then a row per series with its swatch, its config label and its value, a count unless formatValue writes it. A 1px border on white, no shadow.",
           "props": [
             {
-              "name": "showCloseButton",
+              "name": "active",
               "type": "boolean",
               "required": false,
-              "default": "true",
-              "description": "Whether the corner close button shows. Defaults to true."
+              "description": "Set by the tooltip: whether a point is active."
             },
             {
-              "name": "closeLabel",
-              "type": "string",
+              "name": "payload",
+              "type": "readonly Payload<ValueType, TooltipNameType>[]",
               "required": false,
-              "default": "Close",
-              "description": "The accessible name of the corner close button. Defaults to Close."
+              "description": "Set by the tooltip: the values of the series at the active point."
             },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "name": "label",
+              "type": "ReactNode",
               "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": [
+              "description": "Set by the tooltip: the active point's label, such as its x-axis category."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>",
+              "name": "labelFormatter",
+              "type": "((label: ReactNode, payload: readonly Payload<ValueType, TooltipNameType>[]) => ReactNode)",
               "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": [
+              "description": "Writes the label from it and the payload."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>",
+              "name": "formatter",
+              "type": "Formatter<ValueType, TooltipNameType>",
               "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": [
+              "description": "Draws a whole row, in place of the swatch, name and value, from the value, name, item, index and payload."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>",
+              "name": "indicator",
+              "type": "\"dashed\" | \"dot\" | \"line\"",
               "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": [
+              "default": "dot",
+              "description": "The swatch: a dot (the default), a line or a dashed line."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuCheckboxItemState>",
+              "name": "hideLabel",
+              "type": "boolean",
               "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": [
+              "default": "false",
+              "description": "Leaves out the label."
+            },
             {
-              "name": "side",
-              "type": "\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"",
+              "name": "hideIndicator",
+              "type": "boolean",
               "required": false,
-              "default": "bottom",
-              "description": "Which side of the trigger the menu opens on. Defaults to bottom."
+              "default": "false",
+              "description": "Leaves out the swatches."
             },
             {
-              "name": "align",
-              "type": "\"center\" | \"end\" | \"start\"",
+              "name": "nameKey",
+              "type": "string",
               "required": false,
-              "default": "start",
-              "description": "How the menu lines up with the trigger along that side. Defaults to start."
+              "description": "The key of the item, or its data row, whose value names the config entry of a row."
             },
             {
-              "name": "sideOffset",
-              "type": "number",
+              "name": "labelKey",
+              "type": "string",
               "required": false,
-              "default": "4",
-              "description": "The gap between the trigger and the menu in px. Defaults to 4."
+              "description": "The key whose config entry labels the tooltip, in place of the active point's label."
             },
             {
-              "name": "alignOffset",
-              "type": "number",
+              "name": "color",
+              "type": "\"chart-1\" | \"chart-2\" | \"chart-3\" | \"chart-4\" | \"chart-5\"",
               "required": false,
-              "default": "0",
-              "description": "A shift along the side in px. Defaults to 0."
+              "description": "One chart token for every swatch, in place of each series' own."
             },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "name": "formatValue",
+              "type": "((value: number) => string)",
               "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."
+              "description": "Writes a number for its series, such as formatMoney for sales. Defaults to a count."
             }
           ]
         },
         {
-          "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": "ChartLegend",
+          "import": "import { ChartLegend } from '@ratio-ui/core'",
+          "description": "The chart's legend: Recharts' Legend, drawing ChartLegendContent unless given other content.",
+          "props": []
         },
         {
-          "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.",
+          "name": "ChartLegendContent",
+          "import": "import { ChartLegendContent } from '@ratio-ui/core'",
+          "description": "The row a chart legend draws: a swatch in each series' chart token, or its icon, and its config label.",
           "props": [
             {
-              "name": "variant",
-              "type": "\"default\" | \"destructive\"",
+              "name": "payload",
+              "type": "readonly LegendPayload[]",
               "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."
+              "description": "Set by the legend: its series."
             },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuItemState>",
+              "name": "verticalAlign",
+              "type": "\"bottom\" | \"middle\" | \"top\"",
               "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": [
+              "default": "bottom",
+              "description": "Set by the legend: whether it sits above or below the chart, which sets the side of its gap."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupLabelState>",
+              "name": "hideIcon",
+              "type": "boolean",
               "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": [
+              "default": "false",
+              "description": "Draws the swatch even where the config gives an icon."
+            },
             {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioGroupState>",
+              "name": "nameKey",
+              "type": "string",
               "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."
+              "description": "The key of the item whose value names the config entry of a series."
             }
           ]
+        }
+      ]
+    },
+    {
+      "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": "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": "items",
+          "type": "CheckboxListItem[]",
+          "required": true,
+          "description": "The options."
         },
         {
-          "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": "value",
+          "type": "string[]",
+          "required": false,
+          "description": "The chosen values, when controlled."
         },
         {
-          "name": "DropdownMenuShortcut",
+          "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": "Combobox",
+      "import": "import { Combobox } from '@ratio-ui/core'",
+      "description": "A field to choose one option from a list, with a search: type to narrow the list, pick with the mouse or Enter. The field looks like an Input and the list like a Popover panel. For several choices shown as chips, use TagInput. Mark it invalid with aria-invalid; give the list an empty text with emptyText. Inside a Field, the label, hint, error and required mark reach the input.",
+      "props": [
+        {
+          "name": "items",
+          "type": "readonly ComboboxItem[]",
+          "required": true,
+          "description": "The options. Strings or { value, label } objects."
+        },
+        {
+          "name": "value",
+          "type": "string | null",
+          "required": false,
+          "description": "The chosen value for a controlled combobox, or null for none."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | null",
+          "required": false,
+          "description": "The value to start with when the combobox keeps its own state."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string | null, eventDetails: ChangeEventDetails) => void)",
+          "required": false,
+          "description": "Called with the new value, or null when the choice is cleared."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "description": "The text shown while nothing is chosen."
+        },
+        {
+          "name": "emptyText",
+          "type": "string",
+          "required": false,
+          "default": "No results found",
+          "description": "The text shown when the search matches no option. Defaults to \"No results found\"."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the field invalid and draws the error ring, as on every form control. Field sets it when it shows an error."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "The same as aria-invalid, kept as its alias."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Shows a button that clears the choice while one is made. Defaults to true."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Stops people from changing the choice."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "description": "The name of the field in a form."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name when no label is wired to the field."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that name the field. Field sets it to its label."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that describe the field, such as its hint or error. Field sets it."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Tells assistive technology that the field must be filled. Field sets it for a required field."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the input, for a label's htmlFor."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Choosing one option from a long list that people search, such as a vendor or a product type\n- A field where the list may be empty or the search may match nothing",
+        "whenNotToUse": "- A short list of a few options: use a radio group or tabs\n- Several choices shown as chips: use TagInput\n- A list of actions: use DropdownMenu",
+        "example": "<Combobox aria-label=\"Vendor\" items={['Acme', 'Northwind']} placeholder=\"Choose a vendor\" onValueChange={setVendor} />"
+      }
+    },
+    {
+      "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 reports null (as soon as it is typed over a day, and when the field loses focus) and is marked invalid, aria-invalid, when the field loses focus; the app shows Field's error from the null. 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 or is not a date."
+        },
+        {
+          "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 is never reported as a day: `onValueChange` gets `null` (as soon as a held day is typed over, and again when the field loses focus), and the field turns invalid (`aria-invalid`) when it loses focus."
+      }
+    },
+    {
+      "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 reports null (as soon as it is typed over a range, and when the field loses focus) and is marked invalid, aria-invalid, when the field loses focus. 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 or is not a range."
+        },
+        {
+          "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, is never reported as a range: `onValueChange` gets `null` (as soon as a held range is typed over, and again on blur), and the field turns invalid (`aria-invalid`) when it loses focus. Show the error with Field as in DatePicker: `error={touched && range === null ? 'Enter a period as DD/MM/YYYY – DD/MM/YYYY' : undefined}`, `touched` set from `onBlur`.\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": "Drawer",
+      "import": "import { Drawer } from '@ratio-ui/core'",
+      "description": "The root of a drawer: a panel people swipe away on a phone. It holds the open state and renders nothing itself. `swipeDirection` picks the edge it leaves by (down, the default, makes a bottom drawer). Pass `open` and `onOpenChange` to control it, or `defaultOpen`. The page behind is inert while it is open, with no scrim over it.",
+      "props": [
+        {
+          "name": "showSwipeHandle",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether a short bar shows on the edge the drawer is swiped from, as a hint on phones. Defaults to false."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A panel on a phone that people swipe away, such as filters or a short form under the list\n- A bottom drawer by default; a side drawer (swipeDirection left or right) for a phone menu\n- Show the swipe handle on phones as a hint; the corner close button stays for people who do not swipe",
+        "whenNotToUse": "- A large surface on a wide screen, such as Settings: use a Sheet\n- A short task or a confirm step: use a Dialog\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Drawer showSwipeHandle>\n  <DrawerTrigger>Filters</DrawerTrigger>\n  <DrawerContent>\n    <DrawerHeader>\n      <DrawerTitle>Filters</DrawerTitle>\n      <DrawerDescription>Narrow the product list</DrawerDescription>\n    </DrawerHeader>\n    <DrawerFooter>\n      <DrawerClose>Done</DrawerClose>\n    </DrawerFooter>\n  </DrawerContent>\n</Drawer>"
+      },
+      "parts": [
+        {
+          "name": "DrawerClose",
+          "import": "import { DrawerClose } from '@ratio-ui/core'",
+          "description": "A button that closes the drawer, such as Done in the footer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerCloseState>",
+              "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": "DrawerContent",
+          "import": "import { DrawerContent } from '@ratio-ui/core'",
+          "description": "The panel, white with a hairline and 24px corners on its inner edge. A bottom drawer spans the screen and sizes to its content; a side drawer is full height and three quarters of a phone screen, 384px from the small breakpoint up. It follows the finger while it is swiped and otherwise does not move: no slide in or out, no scrim, blur or shadow. Put DrawerHeader, the content and DrawerFooter inside.",
+          "props": [
+            {
+              "name": "showCloseButton",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Whether the corner close button shows. It is the way to close without swiping. 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, DrawerPopupState>",
+              "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": "DrawerDescription",
+          "import": "import { DrawerDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the drawer is for, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerDescriptionState>",
+              "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": "DrawerFooter",
+          "import": "import { DrawerFooter } from '@ratio-ui/core'",
+          "description": "The actions at the bottom of the drawer, stacked full width for a thumb.",
+          "props": []
+        },
+        {
+          "name": "DrawerHeader",
+          "import": "import { DrawerHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked, with room on the right for the close button.",
+          "props": []
+        },
+        {
+          "name": "DrawerTitle",
+          "import": "import { DrawerTitle } from '@ratio-ui/core'",
+          "description": "The drawer's name, in the b4 style. It names the drawer for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerTitleState>",
+              "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": "DrawerTrigger",
+          "import": "import { DrawerTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the drawer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerTriggerState>",
+              "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": "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 and aria-labelledby (which also names a group such as RadioGroup), 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-labelledby, 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-labelledby, 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\nA Combobox or a RadioGroup goes straight inside, like an Input: the label names a radio group through `aria-labelledby`, because a label cannot point at a group.\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\" | \"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": "DropdownMenuSub",
-          "import": "import { DropdownMenuSub } from '@ratio-ui/core'",
-          "description": "The root of a nested menu. Hold a DropdownMenuSubTrigger and a DropdownMenuSubContent.",
-          "props": []
+          "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": "DropdownMenuSubContent",
-          "import": "import { DropdownMenuSubContent } from '@ratio-ui/core'",
-          "description": "The panel of a submenu. It opens to the side of its trigger.",
+          "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": "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",
+              "type": "\"end\" | \"start\"",
               "required": false,
-              "default": "-6",
-              "description": "A shift along the side in px. Defaults to 0."
-            },
+              "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": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "name": "ref",
+              "type": "Ref<HTMLInputElement>",
               "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."
+              "description": "Receives the input element."
             }
           ]
         },
         {
-          "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": "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": "InputOtp",
+      "import": "import { InputOtp } from '@ratio-ui/core'",
+      "description": "A one-time-code field: six 44px digit slots (set `length` for another count) over one hidden input, so the browser offers the SMS code (autocomplete one-time-code), a pasted code fills every slot, and the numeric keypad opens on phones. Digits only.",
+      "props": [
+        {
+          "name": "length",
+          "type": "number",
+          "required": false,
+          "default": "6",
+          "description": "The number of digits. Defaults to 6."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "description": "The code typed so far, for a controlled field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "description": "The code typed so far, for an uncontrolled field."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called with the whole code on every change, including a paste."
+        },
+        {
+          "name": "onComplete",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called once with the code when every slot is filled."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Stops editing and halves the opacity."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Draws the error ring on every slot."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name, for example \"6-digit code\"."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of an element that names the field."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that describe the field, such as its hint or error. Field sets it."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Tells assistive technology that the code must be filled. Field sets it for a required field."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the hidden input, for a label's htmlFor. Field sets it."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "description": "The form field name."
+        },
+        {
+          "name": "autoFocus",
+          "type": "boolean",
+          "required": false,
+          "description": "Focuses the field on mount."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the hidden input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The code step of a sign-in: the 6-digit code sent by SMS or email (\"Verify and sign in\")\n- Any short numeric code: set `length` for another count\n- A wrong code: set `aria-invalid` and every slot draws the error ring, and put the message beside the field in text",
+        "whenNotToUse": "- A code with letters: InputOtp takes digits only\n- A long or free-form value: use Input\n- Custom classes or inline styles: InputOtp takes no `className` and no `style`",
+        "example": "```tsx\n<InputOtp aria-label=\"6-digit code\" value={code} onValueChange={setCode} onComplete={(code) => verify(code)} />\n<InputOtp aria-label=\"PIN\" length={4} aria-invalid />\n```\n\nThe browser offers the SMS code through `autocomplete=\"one-time-code\"`, and a pasted code fills every slot."
+      }
+    },
+    {
+      "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": "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": "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": "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.",
+      "name": "KeyValueList",
+      "import": "import { KeyValueList } from '@ratio-ui/core'",
+      "description": "Settings rows in a hairline bordered panel: the label on the left, the value on the right and an optional action. It is a description list, so a screen reader announces each label with its value.",
       "props": [
         {
-          "name": "title",
-          "type": "ReactNode",
+          "name": "items",
+          "type": "KeyValueItem[]",
           "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."
+          "description": "The rows, in order."
         },
         {
-          "name": "action",
-          "type": "ReactNode",
+          "name": "emptyValue",
+          "type": "string",
           "required": false,
-          "description": "An optional action, usually one Button."
+          "default": "Not set",
+          "description": "What an empty value shows. Defaults to \"Not set\"."
         }
       ],
       "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>} />"
+        "whenToUse": "- Settings and detail rows: a label on the left, its value on the right, an optional action such as Edit\n- A value that may be empty: it shows a placeholder, \"Not set\" by default",
+        "whenNotToUse": "- Rows of many columns to scan or sort: use Table or DataTable\n- Editing a value in place: use a form with Input",
+        "example": "```tsx\n<KeyValueList\n  items={[\n    { label: 'Store name', value: 'Maison Yara', action: { label: 'Edit', onClick: edit } },\n    { label: 'Phone' },\n  ]}\n/>\n```\n\nMoney and dates arrive already formatted; use the format module."
       }
     },
     {
-      "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.",
+      "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": "items",
-          "type": "FilterTabsItem[]",
+          "name": "href",
+          "type": "string",
           "required": true,
-          "description": "The choices, in order."
+          "description": "Where the link goes."
         },
         {
-          "name": "value",
-          "type": "string",
-          "required": false,
-          "description": "The chosen value when controlled."
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The link text."
         },
         {
-          "name": "defaultValue",
-          "type": "string",
+          "name": "back",
+          "type": "boolean",
           "required": false,
-          "description": "The chosen value at the start when uncontrolled. Defaults to the first item."
+          "default": "false",
+          "description": "Shows a back arrow before the text, as in \"← Products\". Screen readers skip it."
         },
         {
-          "name": "onValueChange",
-          "type": "((value: string) => void)",
+          "name": "forward",
+          "type": "boolean",
           "required": false,
-          "description": "Called with the new value when another item is chosen. Choosing the chosen item again does nothing."
+          "default": "false",
+          "description": "Shows a forward arrow after the text, as in \"View all variants →\". Screen readers skip it."
         },
         {
-          "name": "disabled",
-          "type": "boolean",
+          "name": "ref",
+          "type": "Ref<HTMLAnchorElement>",
           "required": false,
-          "description": "Disables every item. Defaults to false."
+          "description": "Receives the anchor element."
         }
       ],
       "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/>"
+        "whenToUse": "- A text link to another page: \"← Products\", \"View all variants →\"\n- A back link in a detail page's body (the page header draws its back link with Link too, so the two look alike)",
+        "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": "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.",
+      "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": "label",
-          "type": "string",
+          "name": "render",
+          "type": "LinkRender",
           "required": true,
-          "description": "The accessible name of the field, such as \"Search the dashboard\"."
+          "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": "value",
-          "type": "string",
+          "name": "children",
+          "type": "ReactNode",
           "required": true,
-          "description": "The text typed in the field."
+          "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": "onValueChange",
-          "type": "(value: string) => void",
+          "name": "onAdd",
+          "type": "(files: File[]) => void",
           "required": true,
-          "description": "Called on every change of the text. Debounce and fetch in the app."
+          "description": "Called with the files chosen in the add tile or dropped on the grid."
         },
         {
-          "name": "groups",
-          "type": "GlobalSearchGroup[]",
+          "name": "onReorder",
+          "type": "(ids: string[]) => void",
           "required": true,
-          "description": "The results for the current text, grouped. The app supplies them; nothing is filtered here."
+          "description": "Called with every id in the new order after a drag, Move left, Move right or Make cover."
         },
         {
-          "name": "recent",
-          "type": "GlobalSearchResult[]",
+          "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,
-          "default": "[]",
-          "description": "Recent items, shown under \"Recent\" while the field is empty."
+          "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": "onSelect",
-          "type": "((result: GlobalSearchResult) => void)",
+          "name": "accept",
+          "type": "Accept",
           "required": false,
-          "description": "Called when a result is chosen by click or Enter."
+          "default": "{ 'image/*': [] }",
+          "description": "The file types the add tile takes, as react-dropzone's accept map. Defaults to every image type."
         },
         {
-          "name": "onShowMore",
-          "type": "((group: GlobalSearchGroup) => void)",
+          "name": "disabled",
+          "type": "boolean",
           "required": false,
-          "description": "Called when a \"+N more\" row is chosen, with its group."
+          "default": "false",
+          "description": "Stops adding, dragging and every button."
         },
         {
-          "name": "placeholder",
+          "name": "addLabel",
           "type": "string",
           "required": false,
-          "default": "Search",
-          "description": "The placeholder of the field. Defaults to \"Search\"."
+          "default": "Add media",
+          "description": "The accessible name of the add tile. Defaults to \"Add media\"."
         },
         {
-          "name": "emptyText",
+          "name": "id",
           "type": "string",
           "required": false,
-          "default": "No results",
-          "description": "The copy when the text matches nothing. Defaults to \"No results\"."
+          "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 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/>"
+        "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": "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.",
+      "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": "name",
-          "type": "\"alert-triangle\" | \"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\"",
+          "name": "segments",
+          "type": "MetricSegment[]",
           "required": true,
-          "description": "Which icon to draw, by name."
+          "description": "The metrics, left to right."
         },
         {
-          "name": "size",
-          "type": "8 | 12 | 16",
+          "name": "label",
+          "type": "string",
           "required": false,
-          "default": "12",
-          "description": "The square box in px: 8, 12 or 16. Defaults to 12, the size inside controls."
+          "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": "tone",
-          "type": "\"current\" | \"icon\" | \"primary\" | \"subdued\"",
+          "name": "defaultValue",
+          "type": "number | null",
           "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": "null",
+          "description": "The starting amount in integer paise when the field is not controlled. Defaults to empty."
         },
         {
-          "name": "label",
-          "type": "string",
+          "name": "onValueChange",
+          "type": "((paise: number | null) => void)",
           "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."
+          "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": "- 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- 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} />"
+        "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": "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": "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": "gap",
-          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "name": "title",
+          "type": "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 page title, shown as the level 1 heading."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An icon or logo shown before the title."
         },
         {
-          "name": "align",
-          "type": "\"baseline\" | \"center\" | \"end\" | \"start\" | \"stretch\"",
+          "name": "status",
+          "type": "{ label: string; tone?: StatusPillTone; }",
           "required": false,
-          "default": "center",
-          "description": "How children line up across the row, which is the vertical axis. Defaults to center."
+          "description": "The state of the record, one word, beside the title."
         },
         {
-          "name": "justify",
-          "type": "\"between\" | \"center\" | \"end\" | \"start\"",
+          "name": "backHref",
+          "type": "string",
           "required": false,
-          "default": "start",
-          "description": "How children spread along the row, which is the horizontal axis. Defaults to start."
+          "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": "wrap",
-          "type": "boolean",
+          "name": "backLabel",
+          "type": "string",
           "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": "Back",
+          "description": "The text of the back link, such as the parent page's name. Defaults to Back."
         },
         {
-          "name": "as",
-          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "name": "actions",
+          "type": "ReactNode",
           "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": "Buttons on the right, such as Export and Add product."
         },
         {
-          "name": "ref",
-          "type": "Ref<HTMLElement>",
+          "name": "menuItems",
+          "type": "PageHeaderMenuItem[]",
           "required": false,
-          "description": "Receives the rendered element."
+          "description": "Entries of the overflow menu. The More actions button shows only when there is at least one."
         }
       ],
       "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>"
+        "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": "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.",
+      "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": "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": "page",
+          "type": "number",
+          "required": true,
+          "description": "The page being shown, counting from 1."
         },
         {
-          "name": "ref",
-          "type": "Ref<HTMLInputElement>",
-          "required": false,
-          "description": "Receives the input element."
+          "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": "- 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\" />"
+        "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": "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."
-        }
-      ],
+      "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 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>"
+        "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": "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.",
+          "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": "align",
-              "type": "\"end\" | \"start\"",
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>",
               "required": false,
-              "default": "start",
-              "description": "The side of the input: start before it, end after it. Defaults to start."
+              "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": "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.",
+          "name": "PopoverDescription",
+          "import": "import { PopoverDescription } from '@ratio-ui/core'",
+          "description": "The supporting text under the title, in the muted colour.",
           "props": [
             {
-              "name": "ref",
-              "type": "Ref<HTMLInputElement>",
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>",
               "required": false,
-              "description": "Receives the input element."
+              "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": "InputGroupShortcut",
-          "import": "import { InputGroupShortcut } from '@ratio-ui/core'",
-          "description": "A shortcut hint such as ⌘K inside an end addon, drawn as a small keycap.",
+          "name": "PopoverHeader",
+          "import": "import { PopoverHeader } from '@ratio-ui/core'",
+          "description": "Groups a title and a description at the top of the panel.",
           "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": "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": "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": "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": "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": "Kbd",
-      "import": "import { Kbd } from '@ratio-ui/core'",
-      "description": "A key hint, 20px high with a 4px radius, such as ⌘K or esc.",
+      "name": "Progress",
+      "import": "import { Progress } from '@ratio-ui/core'",
+      "description": "The thin progress bar of question 5, 2px high, for page loads and refetches. Determinate with a value, indeterminate without one (a partial bar that moves only when the loading animation token names a motion, question 5). Base UI gives it the progressbar role, its label and its value text.",
       "props": [
         {
-          "name": "ref",
-          "type": "Ref<HTMLElement>",
+          "name": "value",
+          "type": "number | null",
           "required": false,
-          "description": "Receives the rendered element."
+          "default": "null",
+          "description": "The current value; leave it out or pass null for an indeterminate bar."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "default": "100",
+          "description": "The value at which the bar is full. Defaults to 100; for steps, the number of steps."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "A visible label, which also names the bar for screen readers."
+        },
+        {
+          "name": "showValue",
+          "type": "boolean",
+          "required": false,
+          "description": "Shows the value on the right: a percent, or \"value/max\" with steps."
+        },
+        {
+          "name": "steps",
+          "type": "boolean",
+          "required": false,
+          "description": "The step variant: counts completed steps out of max, such as 0/5 for the setup guide. Implies showValue."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name when there is no visible label."
         }
       ],
       "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>"
+        "whenToUse": "- A page load or a refetch of content already on screen (the thin 2px bar, question 5)\n- The setup guide's step count, with the steps variant (\"0/5\")",
+        "whenNotToUse": "- A first load of a list or table: use Skeleton rows\n- A short wait on one control: use Spinner",
+        "example": "```tsx\n<Progress label=\"Loading orders\" value={60} showValue />\n<Progress label=\"Setup guide\" value={0} max={5} steps />\n<Progress aria-label=\"Refreshing\" />\n```\n\nWithout a value the bar is indeterminate: a static partial bar, since the loading animation token is none."
+      }
+    },
+    {
+      "name": "RadioGroup",
+      "import": "import { RadioGroup } from '@ratio-ui/core'",
+      "description": "A column of radio buttons where exactly one can be on. The arrow keys move the choice. aria-invalid on the group, as Field sets it, draws the error ring on every item.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- One choice among a few options that all deserve to be seen at once, such as a plan or a delivery method\n- A form field where the answer is exactly one of two to five values",
+        "whenNotToUse": "- Several answers can be on: use checkboxes\n- A setting that applies at once: use a switch\n- A long list of options: use a select\n- Styling: RadioGroup and RadioGroupItem take no `className` and no `style`",
+        "example": "```tsx\n<RadioGroup aria-label=\"Plan\" value={plan} onValueChange={setPlan}>\n  <Inline gap={8} align=\"center\">\n    <RadioGroupItem id=\"plan-free\" value=\"free\" />\n    <Label htmlFor=\"plan-free\">Free</Label>\n  </Inline>\n  <Inline gap={8} align=\"center\">\n    <RadioGroupItem id=\"plan-pro\" value=\"pro\" />\n    <Label htmlFor=\"plan-pro\">Pro</Label>\n  </Inline>\n</RadioGroup>\n```\n\nGive every item an `id` and a visible `Label` that points at it, so the text people read is the radio's name."
       },
       "parts": [
         {
-          "name": "KbdGroup",
-          "import": "import { KbdGroup } from '@ratio-ui/core'",
-          "description": "Puts the keys of one shortcut in a row with a 4px gap.",
+          "name": "RadioGroupItem",
+          "import": "import { RadioGroupItem } from '@ratio-ui/core'",
+          "description": "One choice in a RadioGroup: a 14px round control like the checkbox, drawn with a hairline ring and filled in the primary colour with a white dot when chosen. An invisible 24px area around it takes the tap.",
           "props": []
         }
       ]
     },
     {
-      "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.",
+      "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": "render",
-          "type": "LinkRender",
+          "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": "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} />`."
+          "description": "Called by Save."
         },
         {
-          "name": "children",
-          "type": "ReactNode",
+          "name": "onDiscard",
+          "type": "() => void",
           "required": true,
-          "description": "The app, or the part of it that the router serves."
+          "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": "- 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>"
+        "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": "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.",
+      "name": "ScrollArea",
+      "import": "import { ScrollArea } from '@ratio-ui/core'",
+      "description": "A scrolling region that fills its parent, which sets the height or width, with a thin scrollbar in the design system greys.",
       "props": [
         {
-          "name": "segments",
-          "type": "MetricSegment[]",
+          "name": "children",
+          "type": "ReactNode",
           "required": true,
-          "description": "The metrics, left to right."
+          "description": "The scrolling content."
         },
         {
-          "name": "label",
-          "type": "string",
+          "name": "orientation",
+          "type": "\"both\" | \"horizontal\" | \"vertical\"",
           "required": false,
-          "description": "The accessible name of the strip."
+          "default": "vertical",
+          "description": "Which scrollbars to offer. Defaults to vertical."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered element."
         }
       ],
       "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/>"
+        "whenToUse": "- A bounded region (a list, a panel body) that scrolls inside a fixed height or width",
+        "whenNotToUse": "- The page itself: let the page scroll",
+        "example": "<div style={{ height: 240 }}>\n  <ScrollArea>{rows}</ScrollArea>\n</div>"
       }
     },
     {
-      "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.",
+      "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": "title",
+          "name": "label",
           "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."
+          "description": "The accessible name of the field, such as \"Search products\". Required because the field has no visible label."
         },
         {
-          "name": "status",
-          "type": "{ label: string; tone?: StatusPillTone; }",
+          "name": "value",
+          "type": "string",
           "required": false,
-          "description": "The state of the record, one word, beside the title."
+          "description": "The text in the field. Pass it with onValueChange to control the field."
         },
         {
-          "name": "backHref",
+          "name": "defaultValue",
           "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."
+          "default": "",
+          "description": "The starting text of an uncontrolled field."
         },
         {
-          "name": "backLabel",
-          "type": "string",
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
           "required": false,
-          "default": "Back",
-          "description": "The text of the back link, such as the parent page's name. Defaults to Back."
+          "description": "Called with the new text on every change and when the field is cleared. It is not debounced: debounce in the app."
         },
         {
-          "name": "actions",
-          "type": "ReactNode",
+          "name": "size",
+          "type": "32 | 36",
           "required": false,
-          "description": "Buttons on the right, such as Export and Add product."
+          "default": "36",
+          "description": "The height in px: 36 above a listing, 32 inside a table. Defaults to 36."
         },
         {
-          "name": "menuItems",
-          "type": "PageHeaderMenuItem[]",
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
           "required": false,
-          "description": "Entries of the overflow menu. The More actions button shows only when there is at least one."
+          "description": "Receives the input element."
         }
       ],
       "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/>"
+        "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": "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": "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": "page",
-          "type": "number",
-          "required": true,
-          "description": "The page being shown, counting from 1."
+          "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": "pageSize",
-          "type": "number",
-          "required": true,
-          "description": "How many results one page holds."
+          "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": "total",
-          "type": "number",
-          "required": true,
-          "description": "How many results there are in all, across every page."
+          "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": "onPageChange",
-          "type": "(page: number) => void",
-          "required": true,
-          "description": "Called with the page to show when Previous or Next is pressed."
+          "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": "Separator",
+      "import": "import { Separator } from '@ratio-ui/core'",
+      "description": "A 1px hairline in the divider grey, horizontal or vertical. A horizontal line fills its row and shrinks to share it, so two lines and a word between them in an Inline make the \"or\" divider; a vertical line keeps its 1px.",
+      "props": [
+        {
+          "name": "orientation",
+          "type": "\"horizontal\" | \"vertical\"",
+          "required": false,
+          "default": "horizontal",
+          "description": "The direction of the line. Defaults to horizontal."
+        },
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "True, the default, hides the line from assistive technology; false makes it a semantic separator."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered element."
         }
       ],
       "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} />"
+        "whenToUse": "- A hairline between groups of content, or the \"or\" divider on the login screen\n- A vertical hairline between inline items",
+        "whenNotToUse": "- A card or table edge: those own their border",
+        "example": "```tsx\n<Separator />\n<Inline gap={8}>\n  <Separator />\n  <Text variant=\"c1\" tone=\"muted\">or</Text>\n  <Separator />\n</Inline>\n<Separator orientation=\"vertical\" />\n<Separator decorative={false} />\n```\n\nIn the \"or\" divider the two lines share the row and the word keeps its width. Keep the word short: a longer phrase wraps before the lines give way."
       }
     },
     {
-      "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.",
+      "name": "Sheet",
+      "import": "import { Sheet } from '@ratio-ui/core'",
+      "description": "The root of a sheet. 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 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>"
+        "whenToUse": "- A bottom sheet for a large surface that sits over the page, such as Settings: it spans the screen and has 24px top corners\n- A side sheet for a panel that keeps the page in view, such as filters or the phone navigation\n- Work that needs more room than a 480px dialog",
+        "whenNotToUse": "- A short task or a confirm step: use a Dialog\n- A panel people swipe away on a phone: use a Drawer\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Sheet>\n  <SheetTrigger>Settings</SheetTrigger>\n  <SheetContent side=\"bottom\" closeLabel=\"Close settings\">\n    <SheetHeader>\n      <SheetTitle>General</SheetTitle>\n      <SheetDescription>Store name, contact and address</SheetDescription>\n    </SheetHeader>\n    <SheetBody>Store details</SheetBody>\n    <SheetFooter>\n      <SheetClose>Done</SheetClose>\n    </SheetFooter>\n  </SheetContent>\n</Sheet>"
       },
       "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.",
+          "name": "SheetBody",
+          "import": "import { SheetBody } from '@ratio-ui/core'",
+          "description": "The content between header and footer. It takes the free height and scrolls when the content is taller.",
+          "props": []
+        },
+        {
+          "name": "SheetClose",
+          "import": "import { SheetClose } from '@ratio-ui/core'",
+          "description": "A button that closes the sheet, such as Done in the footer.",
           "props": [
             {
               "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>",
+              "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": "PopoverDescription",
-          "import": "import { PopoverDescription } from '@ratio-ui/core'",
-          "description": "The supporting text under the title, in the muted colour.",
+          "name": "SheetContent",
+          "import": "import { SheetContent } from '@ratio-ui/core'",
+          "description": "The panel, white with a hairline on its inner edge. A side sheet is full height and three quarters of a phone screen, 384px from the small breakpoint up; a bottom sheet spans the screen, sizes to its content and has 24px top corners. It appears without sliding and with no scrim, blur or shadow. Put SheetHeader, SheetBody and SheetFooter inside.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"left\" | \"right\"",
+              "required": false,
+              "default": "right",
+              "description": "The edge the sheet sits on: a full-height side sheet, or a bottom sheet with 24px top corners. Defaults to right."
+            },
+            {
+              "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": "SheetDescription",
+          "import": "import { SheetDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the sheet is for, in subdued body text.",
           "props": [
             {
               "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>",
+              "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": "PopoverHeader",
-          "import": "import { PopoverHeader } from '@ratio-ui/core'",
-          "description": "Groups a title and a description at the top of the panel.",
+          "name": "SheetFooter",
+          "import": "import { SheetFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom of the sheet, aligned to the end.",
           "props": []
         },
         {
-          "name": "PopoverTitle",
-          "import": "import { PopoverTitle } from '@ratio-ui/core'",
-          "description": "The title of the panel; it names the dialog for screen readers.",
+          "name": "SheetHeader",
+          "import": "import { SheetHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked, with room on the right for the close button.",
+          "props": []
+        },
+        {
+          "name": "SheetTitle",
+          "import": "import { SheetTitle } from '@ratio-ui/core'",
+          "description": "The sheet's name, in the b4 style. It names the sheet for assistive technology.",
           "props": [
             {
               "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>",
+              "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": "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.",
+          "name": "SheetTrigger",
+          "import": "import { SheetTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the sheet.",
           "props": [
             {
               "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>",
+              "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": "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": "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": "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": "SideNav",
       "import": "import { SideNav } from '@ratio-ui/core'",
@@ -1470,6 +3166,41 @@
         "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": "The chips, in order. Nothing is rendered when empty."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLUListElement>",
+          "required": false,
+          "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'",
@@ -1651,6 +3382,123 @@
         }
       ]
     },
+    {
+      "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 existing values the picker offers, such as S, M, L, XL and XXL."
+        },
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "required": false,
+          "description": "The chosen values, in order, when the owner holds the state."
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "required": false,
+          "description": "The values chosen at first, when the component holds the state."
+        },
+        {
+          "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": "true",
+          "description": "Shows a small field that adds a typed value on Enter. Defaults to true."
+        },
+        {
+          "name": "addLabel",
+          "type": "string",
+          "required": false,
+          "default": "Add value",
+          "description": "The placeholder and accessible name of the small field. Defaults to \"Add value\"."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "description": "The placeholder of the picker, shown while nothing is chosen."
+        },
+        {
+          "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": "name",
+          "type": "string",
+          "required": false,
+          "description": "The form field name: one hidden input per chosen value is submitted under it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "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<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the picker's input element."
+        }
+      ],
+      "usage": {
+        "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."
+      }
+    },
     {
       "name": "Text",
       "import": "import { Text } from '@ratio-ui/core'",
@@ -1697,6 +3545,31 @@
         "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'",
@@ -1850,6 +3723,74 @@
           ]
         }
       ]
+    },
+    {
+      "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\" />"
+      }
     }
   ]
 }