@ratio-ui/core 0.1.0 → 0.2.0

package/dist/catalogue.json

@@ -1,6 +1,814 @@
 {
-  "version": "0.1.0",
+  "version": "0.2.0",
   "components": [
+    {
+      "name": "AppShell",
+      "import": "import { AppShell } from '@ratio-ui/core'",
+      "description": "The frame of every page: the side nav at the left, the top bar above and the content below it. It fills the height of its container, so the app gives it a height and the content scrolls beside the side nav and under the top bar. The parts are slots, so the shell does not depend on their components. On a phone the side nav is a drawer: the menu button in TopBar opens it, and Escape or choosing a row closes it.",
+      "props": [
+        {
+          "name": "sideNav",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The side navigation, for example SideNav. It sits at the left of the top bar and the content."
+        },
+        {
+          "name": "topBar",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The top bar, for example TopBar. It spans the width beside the side nav."
+        },
+        {
+          "name": "navOpen",
+          "type": "boolean",
+          "required": false,
+          "description": "Whether the side navigation drawer is open on a phone. Set it with onNavOpenChange to control the drawer."
+        },
+        {
+          "name": "defaultNavOpen",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether the drawer starts open on a phone when navOpen is not set. Defaults to false."
+        },
+        {
+          "name": "onNavOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "Called when the drawer asks to open or close on a phone: the menu button in TopBar, Escape, or choosing a row."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The page content, centred in a column that is 1152px wide at most."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The frame of an admin page: side nav, top bar and content\n- Content that should be at most 1152px wide and centred",
+        "whenNotToUse": "- A page without the admin chrome, such as sign in\n- Spacing inside the content: use Stack",
+        "example": "<AppShell sideNav={<SideNav />} topBar={<TopBar />}>\n  <PageHeader title=\"Products\" />\n</AppShell>"
+      }
+    },
+    {
+      "name": "Avatar",
+      "import": "import { Avatar } from '@ratio-ui/core'",
+      "description": "A picture or the initials of a person or a store: round for people, square for stores.",
+      "props": [
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "The full name of the person or store. It is the accessible label, and its first letters are the initials."
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "required": false,
+          "description": "The address of a picture. The initials show until it loads and when it fails."
+        },
+        {
+          "name": "shape",
+          "type": "\"round\" | \"square\"",
+          "required": false,
+          "default": "round",
+          "description": "Round for a person, square for a store. Defaults to round."
+        },
+        {
+          "name": "size",
+          "type": "\"default\" | \"lg\" | \"sm\"",
+          "required": false,
+          "default": "default",
+          "description": "Defaults to default, which is 32px."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The identity of a person (round) or a store (square), in the top bar, account menu or a list\n- A picture with the initials as fallback while it loads or when it fails",
+        "whenNotToUse": "- A generic icon or logo that is not an identity: use Icon\n- A status marker: use StatusPill",
+        "example": "<Avatar name=\"My Store\" shape=\"square\" />\n<Avatar name=\"Kavya Singh\" />"
+      }
+    },
+    {
+      "name": "Button",
+      "import": "import { Button } from '@ratio-ui/core'",
+      "description": "The design system's 28px button in five looks: main, secondary, ghost, link and destructive. Hover and pressed change the fill only, disabled is 50% opacity and the colours fade in 120ms. Put an Icon beside the label, or use iconOnly with an aria-label. It has no size prop: 28px is the only height.",
+      "props": [
+        {
+          "name": "iconOnly",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Draws a 28px square for one icon. Needs aria-label, because there is no text to name the button."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The label, optionally with an Icon beside it. One Icon."
+        },
+        {
+          "name": "variant",
+          "type": "\"destructive\" | \"ghost\" | \"link\" | \"main\" | \"secondary\"",
+          "required": false,
+          "default": "main",
+          "description": "The look of the button. Defaults to main."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLButtonElement>",
+          "required": false,
+          "description": "Gives the button back to the caller's ref."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of an icon-only button."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The main action of a view, once per page header or table toolbar: variant main\n- A second action beside it, such as Export: variant secondary\n- Quiet actions like Cancel: ghost. Navigation inside running text or a card: link\n- A delete or remove action: destructive, followed by a confirm step\n- A single icon action, such as add or close: iconOnly with an aria-label",
+        "whenNotToUse": "- A choice among options that filters a list: use FilterTabs\n- Going to another page from a menu: use the menu's own items\n- A different height: Button is 28px only, with no size prop\n- Styling: Button takes no `className` and no `style`",
+        "example": "<Stack gap={8}>\n  <Button><Icon name=\"plus\" />Add customer</Button>\n  <Button variant=\"secondary\">Export</Button>\n  <Button iconOnly variant=\"ghost\" aria-label=\"Add\"><Icon name=\"plus\" /></Button>\n</Stack>"
+      }
+    },
+    {
+      "name": "Card",
+      "import": "import { Card } from '@ratio-ui/core'",
+      "description": "A container for a panel of content: a 1px hairline border on white, no shadow and 24px of padding. The design system has no cards, so this is only the hairline container.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A panel of related content that needs a boundary, such as a settings group or a metric with its notes\n- With a title in B4 and, optionally, a description, content and a footer of actions",
+        "whenNotToUse": "- Page content that needs no boundary: it sits directly on white\n- A menu or popup: those have no shadow either, but they are not cards",
+        "example": "<Card>\n  <CardHeader>\n    <CardTitle>Payout account</CardTitle>\n    <CardDescription>Where settlements are paid</CardDescription>\n  </CardHeader>\n  <CardContent>HDFC ending 4021</CardContent>\n</Card>"
+      },
+      "parts": [
+        {
+          "name": "CardHeader",
+          "import": "import { CardHeader } from '@ratio-ui/core'",
+          "description": "The top of a card: its title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "CardTitle",
+          "import": "import { CardTitle } from '@ratio-ui/core'",
+          "description": "The title of a card, set in the B4 text style.",
+          "props": [
+            {
+              "name": "as",
+              "type": "\"div\" | \"h2\" | \"h3\" | \"h4\"",
+              "required": false,
+              "default": "h3",
+              "description": "The heading element. Defaults to h3."
+            }
+          ]
+        },
+        {
+          "name": "CardDescription",
+          "import": "import { CardDescription } from '@ratio-ui/core'",
+          "description": "A line under the title that says what the card holds.",
+          "props": []
+        },
+        {
+          "name": "CardContent",
+          "import": "import { CardContent } from '@ratio-ui/core'",
+          "description": "The body of a card.",
+          "props": []
+        },
+        {
+          "name": "CardFooter",
+          "import": "import { CardFooter } from '@ratio-ui/core'",
+          "description": "The foot of a card, a row for its actions.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "Checkbox",
+      "import": "import { Checkbox } from '@ratio-ui/core'",
+      "description": "A 14px box with a 4px radius, drawn with a hairline ring and filled in the primary colour when checked. Set indeterminate for a select-all that stands for some rows. An invisible 24px area around the box takes the tap.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A row selector in a table or list, one box per row\n- A select-all in a table header: set `indeterminate` while only some rows are selected\n- A yes or no option in a form, or a list of channels where several can be on",
+        "whenNotToUse": "- A setting that applies at once: use a switch\n- One choice among several: use radio buttons or FilterTabs\n- Styling: Checkbox takes no `className` and no `style`",
+        "example": "<Checkbox aria-label=\"Select row\" checked={selected} onCheckedChange={setSelected} />"
+      }
+    },
+    {
+      "name": "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": "Definition",
+      "import": "import { Definition } from '@ratio-ui/core'",
+      "description": "A term that explains itself. It is a span with the button role and a dotted underline, so it takes the font of the text around it, so keyboard users reach it with Tab and open it with Enter or Space, touch users open it with a tap, and mouse users with hover or click. It does not use the browser's own title tooltip, which keyboard and touch users cannot open. Escape closes it.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The term, shown in the text with a dotted underline."
+        },
+        {
+          "name": "definition",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The explanation shown when the term is opened. Keep it to a sentence."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A term in a heading or label that needs a one-sentence explanation, such as a metric title\n- Where keyboard and touch users must be able to read the explanation: it opens with Tab and Enter, with a tap, and on hover",
+        "whenNotToUse": "- An icon-only hint: use Tooltip\n- Long or interactive content: use Popover\n- Text that the task cannot be finished without: show it on the screen",
+        "example": "<Definition definition=\"Gross merchandise value, before returns\">GMV</Definition>"
+      }
+    },
+    {
+      "name": "Dialog",
+      "import": "import { Dialog } from '@ratio-ui/core'",
+      "description": "The root of a dialog. It holds the open state and renders nothing itself. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to leave it uncontrolled. The page behind is inert while it is open, with no scrim over it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short task that needs the user's full attention before going back to the page, such as adding a product or defining a field\n- A confirm step before a destructive action\n- Work that fits in 480px: the panel is fixed at that width and has no scrim",
+        "whenNotToUse": "- A message after an action: use toast()\n- A long form or a multi-step flow: give it a page\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Dialog>\n  <DialogTrigger>Add product</DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Add product</DialogTitle>\n      <DialogDescription>Fill in the basics</DialogDescription>\n    </DialogHeader>\n    <DialogFooter>\n      <DialogClose>Cancel</DialogClose>\n    </DialogFooter>\n  </DialogContent>\n</Dialog>"
+      },
+      "parts": [
+        {
+          "name": "DialogClose",
+          "import": "import { DialogClose } from '@ratio-ui/core'",
+          "description": "A button that closes the dialog, such as Cancel in the footer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogContent",
+          "import": "import { DialogContent } from '@ratio-ui/core'",
+          "description": "The panel: 480px wide, white, drawn with the ring outline and no shadow, with no scrim behind it. Put DialogHeader, the form and DialogFooter inside.",
+          "props": [
+            {
+              "name": "showCloseButton",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Whether the corner close button shows. Defaults to true."
+            },
+            {
+              "name": "closeLabel",
+              "type": "string",
+              "required": false,
+              "default": "Close",
+              "description": "The accessible name of the corner close button. Defaults to Close."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogDescription",
+          "import": "import { DialogDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the dialog is for, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogFooter",
+          "import": "import { DialogFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom, aligned to the end.",
+          "props": []
+        },
+        {
+          "name": "DialogHeader",
+          "import": "import { DialogHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked.",
+          "props": []
+        },
+        {
+          "name": "DialogTitle",
+          "import": "import { DialogTitle } from '@ratio-ui/core'",
+          "description": "The dialog's name, in the b4 style. It names the dialog for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DialogTrigger",
+          "import": "import { DialogTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the dialog.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "DropdownMenu",
+      "import": "import { DropdownMenu } from '@ratio-ui/core'",
+      "description": "The root of a menu of actions that opens from a trigger. Compose it with DropdownMenuTrigger and DropdownMenuContent.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short list of actions behind one control: \"More actions\", a store menu, a \"…\" button\n- Actions that belong in groups, with a label per group, a hairline between groups, or a submenu\n- Items that show a key hint, a check (on or off) or one choice out of a few",
+        "whenNotToUse": "- Choosing a value for a form field: use a select\n- Content that is not a list of actions, such as notifications or a form: use Popover\n- A destructive action without a confirm step: the destructive item only colours it\n- Styling: the parts take no `className` and no `style`, and the menu has no shadow",
+        "example": "<DropdownMenu>\n  <DropdownMenuTrigger>More actions</DropdownMenuTrigger>\n  <DropdownMenuContent>\n    <DropdownMenuGroup>\n      <DropdownMenuLabel>Product</DropdownMenuLabel>\n      <DropdownMenuItem>\n        Edit\n        <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>\n      </DropdownMenuItem>\n    </DropdownMenuGroup>\n    <DropdownMenuSeparator />\n    <DropdownMenuItem variant=\"destructive\">Delete</DropdownMenuItem>\n  </DropdownMenuContent>\n</DropdownMenu>"
+      },
+      "parts": [
+        {
+          "name": "DropdownMenuCheckboxItem",
+          "import": "import { DropdownMenuCheckboxItem } from '@ratio-ui/core'",
+          "description": "An item that toggles an option. A check shows at its start while it is on and keeps the menu open, so several options can be changed in one visit.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuCheckboxItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuContent",
+          "import": "import { DropdownMenuContent } from '@ratio-ui/core'",
+          "description": "The menu panel: a white popup with a hairline ring, 8px corners and no shadow. It opens in a portal.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"",
+              "required": false,
+              "default": "bottom",
+              "description": "Which side of the trigger the menu opens on. Defaults to bottom."
+            },
+            {
+              "name": "align",
+              "type": "\"center\" | \"end\" | \"start\"",
+              "required": false,
+              "default": "start",
+              "description": "How the menu lines up with the trigger along that side. Defaults to start."
+            },
+            {
+              "name": "sideOffset",
+              "type": "number",
+              "required": false,
+              "default": "4",
+              "description": "The gap between the trigger and the menu in px. Defaults to 4."
+            },
+            {
+              "name": "alignOffset",
+              "type": "number",
+              "required": false,
+              "default": "0",
+              "description": "A shift along the side in px. Defaults to 0."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuGroup",
+          "import": "import { DropdownMenuGroup } from '@ratio-ui/core'",
+          "description": "Groups items under one DropdownMenuLabel, so assistive technology announces the label with the group.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuItem",
+          "import": "import { DropdownMenuItem } from '@ratio-ui/core'",
+          "description": "One action in the menu. It runs onClick and closes the menu; disabled is drawn at half opacity and cannot be chosen.",
+          "props": [
+            {
+              "name": "variant",
+              "type": "\"default\" | \"destructive\"",
+              "required": false,
+              "default": "default",
+              "description": "What the item means. destructive is drawn in the destructive token; a delete action also needs a confirm step. Defaults to default."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuLabel",
+          "import": "import { DropdownMenuLabel } from '@ratio-ui/core'",
+          "description": "The caption of a group, in the design system's label style: 12px, uppercase, subdued. Place it inside DropdownMenuGroup.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupLabelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuRadioGroup",
+          "import": "import { DropdownMenuRadioGroup } from '@ratio-ui/core'",
+          "description": "Holds radio items and the one chosen value.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioGroupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuRadioItem",
+          "import": "import { DropdownMenuRadioItem } from '@ratio-ui/core'",
+          "description": "One choice of a DropdownMenuRadioGroup. A dot shows at its start while it is the chosen value.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioItemState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSeparator",
+          "import": "import { DropdownMenuSeparator } from '@ratio-ui/core'",
+          "description": "A hairline between groups of items.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuShortcut",
+          "import": "import { DropdownMenuShortcut } from '@ratio-ui/core'",
+          "description": "A key hint pushed to the end of an item. It is a hint only: the host binds the key.",
+          "props": [
+            {
+              "name": "children",
+              "type": "ReactNode",
+              "required": true,
+              "description": "The key hint, such as ⌘E. It is text only and does not bind a key."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSub",
+          "import": "import { DropdownMenuSub } from '@ratio-ui/core'",
+          "description": "The root of a nested menu. Hold a DropdownMenuSubTrigger and a DropdownMenuSubContent.",
+          "props": []
+        },
+        {
+          "name": "DropdownMenuSubContent",
+          "import": "import { DropdownMenuSubContent } from '@ratio-ui/core'",
+          "description": "The panel of a submenu. It opens to the side of its trigger.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"inline-end\" | \"inline-start\" | \"left\" | \"right\" | \"top\"",
+              "required": false,
+              "default": "right",
+              "description": "Which side of the trigger the menu opens on. Defaults to bottom."
+            },
+            {
+              "name": "align",
+              "type": "\"center\" | \"end\" | \"start\"",
+              "required": false,
+              "description": "How the menu lines up with the trigger along that side. Defaults to start."
+            },
+            {
+              "name": "sideOffset",
+              "type": "number",
+              "required": false,
+              "default": "0",
+              "description": "The gap between the trigger and the menu in px. Defaults to 4."
+            },
+            {
+              "name": "alignOffset",
+              "type": "number",
+              "required": false,
+              "default": "-6",
+              "description": "A shift along the side in px. Defaults to 0."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuSubTrigger",
+          "import": "import { DropdownMenuSubTrigger } from '@ratio-ui/core'",
+          "description": "The item that opens a submenu, on hover, click or ArrowRight. A chevron at its end marks it.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuSubmenuTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DropdownMenuTrigger",
+          "import": "import { DropdownMenuTrigger } from '@ratio-ui/core'",
+          "description": "The control that opens the menu. It is a button, and carries aria-expanded and aria-haspopup.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "EmptyState",
+      "import": "import { EmptyState } from '@ratio-ui/core'",
+      "description": "What a list, table or panel shows when it has nothing to show: one clause and an optional action, centred in a hairline container.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "One clause that says why nothing is shown, in sentence case with no period."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second clause that says what to do next."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional action, usually one Button."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A list, table or panel with nothing to show, such as a filter that matches no products\n- With one action when the user can fix it, such as clearing the filter",
+        "whenNotToUse": "- A load that is still running: use Skeleton\n- An error: say what failed in one clause, in the error colour, not here",
+        "example": "<EmptyState title=\"No products match this filter\" action={<Button>Clear filter</Button>} />"
+      }
+    },
+    {
+      "name": "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'",
@@ -8,87 +816,595 @@
       "props": [
         {
           "name": "name",
-          "type": "\"alert-triangle\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"info-circle\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-home\" | \"nav-product\" | \"nav-product-2\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
+          "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\"",
+          "required": true,
+          "description": "Which icon to draw, by name."
+        },
+        {
+          "name": "size",
+          "type": "8 | 12 | 16",
+          "required": false,
+          "default": "12",
+          "description": "The square box in px: 8, 12 or 16. Defaults to 12, the size inside controls."
+        },
+        {
+          "name": "tone",
+          "type": "\"current\" | \"icon\" | \"primary\" | \"subdued\"",
+          "required": false,
+          "default": "current",
+          "description": "The colour. current, the default, takes the colour of the text around the icon; the other tones set their own."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name. With a label the icon is an image that assistive technology announces under that name. Without one it is decoration, hidden from assistive technology, and the text beside it has to say what it means."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
+        "whenNotToUse": "- Decoration that adds no meaning. An icon next to text that already says the same thing is hidden from assistive technology, so leave the label off, and leave the icon out when it adds nothing\n- An icon the registry does not have. Components accept no className or style, and icons come from the registry only, so a new one is a registry entry: the design system's glyph first, Tabler for the rest\n- An icon-only control without a name. Pass label, or give the control its own accessible name\n- A size other than 8, 12 or 16, or a colour other than the four tones. There is no red, no destructive colour and no third accent: an error is marked with the alert-triangle glyph beside its message, not with a colour\n- Emoji, or unicode arrows and symbols, as icons. Inter's web subsets do not hold them and the design system bans them",
+        "example": "import { Icon } from '@ratio-ui/core'\n\n// Beside text that names it: decoration, hidden from assistive technology\n<button type=\"button\">\n  <Icon name=\"plus\" />\n  Add product\n</button>\n\n// Alone: the label is the accessible name\n<Icon name=\"search\" tone=\"icon\" label=\"Search\" />\n\n// Pagination chevrons are drawn for an 8px box\n<Icon name=\"chevron-right\" size={8} />"
+      }
+    },
+    {
+      "name": "Inline",
+      "import": "import { Inline } from '@ratio-ui/core'",
+      "description": "Lays its children out in a row with a fixed space between them. It takes no className and no style: the gap is a step of the design system's spacing scale, and the layout is the only styling it has.",
+      "props": [
+        {
+          "name": "gap",
+          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "required": true,
+          "description": "The space between children, a step of the design system's scale in px: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80."
+        },
+        {
+          "name": "align",
+          "type": "\"baseline\" | \"center\" | \"end\" | \"start\" | \"stretch\"",
+          "required": false,
+          "default": "center",
+          "description": "How children line up across the row, which is the vertical axis. Defaults to center."
+        },
+        {
+          "name": "justify",
+          "type": "\"between\" | \"center\" | \"end\" | \"start\"",
+          "required": false,
+          "default": "start",
+          "description": "How children spread along the row, which is the horizontal axis. Defaults to start."
+        },
+        {
+          "name": "wrap",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether children move to a new line when the row is full. Defaults to false, which keeps one line."
+        },
+        {
+          "name": "as",
+          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "required": false,
+          "default": "div",
+          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Children side by side with a fixed space between them: a toolbar, a row of tags, a label next to a value\n- Children that spread along the row (`justify`: start, center, end or between) or move to the next line when the row is full (`wrap`)\n- A gap taken from the design system's spacing scale: 0, 1, 2, 4, 6, 7, 8, 11, 12, 14, 24, 32 or 80 px\n- A row that is also a list or a landmark: `as` renders `ul`, `ol`, `li`, `nav`, `header`, `footer`, `main`, `aside`, `section`, `form` or `fieldset` instead of `div`",
+        "whenNotToUse": "- Children one under another: use Stack\n- Columns that have to line up from one row to the next: Inline lays out one row at a time, and wave 0 has no grid\n- Space around one child or at the edge of a container: Inline spaces siblings only, and has no padding or margin\n- Styling: Inline takes no `className` and no `style`\n- A list without markers: `as=\"ul\"` and `as=\"ol\"` leave the browser's list markers as they are",
+        "example": "<Inline gap={8} justify=\"between\" wrap>\n  <div>Orders</div>\n  <Inline gap={4}>\n    <div>Export</div>\n    <div>Filter</div>\n  </Inline>\n</Inline>"
+      }
+    },
+    {
+      "name": "Input",
+      "import": "import { Input } from '@ratio-ui/core'",
+      "description": "A single-line text field in the design system's look: 8px radius, a 1px ring that turns blue on focus, 14px body type. It takes every attribute of an input (type, inputMode, value, onChange). For a prefix, suffix, icon or shortcut hint, put an InputGroupInput in an InputGroup.",
+      "props": [
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms and search, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A single-line text field in a form, a settings page or a table cell: `size` is 36 for forms and 32 for fields inside a table\n- Any input type the browser supports, such as text, email, number or password: Input takes every attribute of an input\n- A field with an error: set `aria-invalid` and the ring changes, and put the error message beside it in text",
+        "whenNotToUse": "- A field with a prefix, suffix, icon or shortcut hint, such as a rupee price, a weight in kg or a search field: use InputGroup\n- Several lines of text: use a textarea\n- A choice from a fixed list: use a select\n- Custom classes or inline styles: Input takes no `className` and no `style`",
+        "example": "<Input aria-label=\"Product title\" placeholder=\"Short sleeve t-shirt\" />\n<Input aria-label=\"Variant stock\" size={32} inputMode=\"numeric\" />"
+      }
+    },
+    {
+      "name": "InputGroup",
+      "import": "import { InputGroup } from '@ratio-ui/core'",
+      "description": "A field with a prefix, suffix, icon or shortcut hint beside the input, inside one ring. Put an InputGroupInput in it and an InputGroupAddon on either side, for example a rupee sign before a price or kg after a weight.",
+      "props": [
+        {
+          "name": "size",
+          "type": "32 | 36",
+          "required": false,
+          "default": "36",
+          "description": "The height in px: 36 for forms and search, 32 for fields inside a table. Defaults to 36."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the group element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A field with something beside the input, all inside one ring: a rupee sign before a price, kg after a weight, a search icon, or a shortcut hint such as ⌘K\n- A table search field or the top bar search: an icon at the start and a shortcut hint at the end\n- A compact field in a table: `size` 32, as for Input",
+        "whenNotToUse": "- A plain field with nothing beside the input: use Input\n- A button inside the field: put it next to the group, because an addon holds text and icons only\n- Custom classes or inline styles: none of the parts take `className` or `style`",
+        "example": "<InputGroup>\n  <InputGroupAddon>\n    <InputGroupText>₹</InputGroupText>\n  </InputGroupAddon>\n  <InputGroupInput aria-label=\"Selling price\" inputMode=\"decimal\" />\n</InputGroup>\n<InputGroup>\n  <InputGroupAddon><Icon name=\"search\" /></InputGroupAddon>\n  <InputGroupInput aria-label=\"Search\" placeholder=\"Search by name, email, etc.\" />\n  <InputGroupAddon align=\"end\"><InputGroupShortcut>⌘K</InputGroupShortcut></InputGroupAddon>\n</InputGroup>"
+      },
+      "parts": [
+        {
+          "name": "InputGroupAddon",
+          "import": "import { InputGroupAddon } from '@ratio-ui/core'",
+          "description": "Holds an icon, a prefix, a suffix or a shortcut hint on one side of the input. Clicking it, off a button, moves focus to the input.",
+          "props": [
+            {
+              "name": "align",
+              "type": "\"end\" | \"start\"",
+              "required": false,
+              "default": "start",
+              "description": "The side of the input: start before it, end after it. Defaults to start."
+            }
+          ]
+        },
+        {
+          "name": "InputGroupInput",
+          "import": "import { InputGroupInput } from '@ratio-ui/core'",
+          "description": "The input of an InputGroup. It draws no ring: the group does. Mark it invalid with aria-invalid.",
+          "props": [
+            {
+              "name": "ref",
+              "type": "Ref<HTMLInputElement>",
+              "required": false,
+              "description": "Receives the input element."
+            }
+          ]
+        },
+        {
+          "name": "InputGroupShortcut",
+          "import": "import { InputGroupShortcut } from '@ratio-ui/core'",
+          "description": "A shortcut hint such as ⌘K inside an end addon, drawn as a small keycap.",
+          "props": []
+        },
+        {
+          "name": "InputGroupText",
+          "import": "import { InputGroupText } from '@ratio-ui/core'",
+          "description": "A text prefix or suffix inside an addon, such as a currency sign or a unit, in the muted colour.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "Kbd",
+      "import": "import { Kbd } from '@ratio-ui/core'",
+      "description": "A key hint, 20px high with a 4px radius, such as ⌘K or esc.",
+      "props": [
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A shortcut hint beside a control or in a menu: ⌘K, ↵, esc\n- Several keys of one shortcut, inside KbdGroup",
+        "whenNotToUse": "- A button that triggers the action: Kbd only shows the key and is not interactive\n- Long text: a key is one symbol or a short name",
+        "example": "<KbdGroup>\n  <Kbd>⌘</Kbd>\n  <Kbd>K</Kbd>\n</KbdGroup>"
+      },
+      "parts": [
+        {
+          "name": "KbdGroup",
+          "import": "import { KbdGroup } from '@ratio-ui/core'",
+          "description": "Puts the keys of one shortcut in a row with a 4px gap.",
+          "props": []
+        }
+      ]
+    },
+    {
+      "name": "LinkProvider",
+      "import": "import { LinkProvider } from '@ratio-ui/core'",
+      "description": "Draws every link of Ratio's components with the app's own router link, so a click navigates without a page reload: SideNav rows with an href, DataTable row links and the PageHeader back link. Wrap the app once, at its root. Without it those links are plain <a href> elements, which reload the page.",
+      "props": [
+        {
+          "name": "render",
+          "type": "LinkRender",
+          "required": true,
+          "description": "Draws every link Ratio renders. The function receives href, the styling class, the content and attributes such as aria-current and onClick, all to spread onto the element: `({ href, ...props }) => <RouterLink to={href} {...props} />`."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The app, or the part of it that the router serves."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- An app on a client-side router (React Router, Next.js, TanStack Router): wrap it once, at its root\n- So that SideNav rows with an href, DataTable row links and the PageHeader back link navigate without a page reload",
+        "whenNotToUse": "- An app whose pages load from the server: the plain links already work\n- A link in your own markup: use your router's link directly",
+        "example": "import { Link as RouterLink } from 'react-router-dom'\n\n<LinkProvider render={({ href, ...props }) => <RouterLink to={href} {...props} />}>\n  <App />\n</LinkProvider>"
+      }
+    },
+    {
+      "name": "MetricStrip",
+      "import": "import { MetricStrip } from '@ratio-ui/core'",
+      "description": "A row of metrics in one hairline container: each segment is a title, optionally with a definition, over its value.",
+      "props": [
+        {
+          "name": "segments",
+          "type": "MetricSegment[]",
+          "required": true,
+          "description": "The metrics, left to right."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name of the strip."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A few headline numbers above a listing, such as the Products metrics\n- A metric whose name needs a one-sentence definition",
+        "whenNotToUse": "- A chart or a trend: this is plain values\n- Many metrics or long values: use a table",
+        "example": "<MetricStrip\n  label=\"Product metrics\"\n  segments={[\n    {\n      id: 'rate',\n      title: 'Average sell-through rate',\n      definition: 'Share of stock sold',\n      value: '9.95%',\n    },\n    { id: 'days', title: 'Days of inventory remaining', value: null },\n    { id: 'abc', title: 'ABC product analysis', value: 0, format: 'money' },\n  ]}\n/>"
+      }
+    },
+    {
+      "name": "PageHeader",
+      "import": "import { PageHeader } from '@ratio-ui/core'",
+      "description": "The top of a page: an optional back link, then an icon, the title and a status pill on the left, and the actions with an overflow menu on the right. It wraps on a phone.",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
           "required": true,
-          "description": "Which icon to draw, by name."
+          "description": "The page title, shown as the level 1 heading."
         },
         {
-          "name": "size",
-          "type": "8 | 12 | 16",
+          "name": "icon",
+          "type": "ReactNode",
           "required": false,
-          "default": "12",
-          "description": "The square box in px: 8, 12 or 16. Defaults to 12, the size inside controls."
+          "description": "An icon or logo shown before the title."
         },
         {
-          "name": "tone",
-          "type": "\"current\" | \"icon\" | \"primary\" | \"subdued\"",
+          "name": "status",
+          "type": "{ label: string; tone?: StatusPillTone; }",
           "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."
+          "description": "The state of the record, one word, beside the title."
         },
         {
-          "name": "label",
+          "name": "backHref",
           "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."
+          "description": "Where the back link goes. The link shows only with this. On a router, LinkProvider draws it with the app's own link."
+        },
+        {
+          "name": "backLabel",
+          "type": "string",
+          "required": false,
+          "default": "Back",
+          "description": "The text of the back link, such as the parent page's name. Defaults to Back."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Buttons on the right, such as Export and Add product."
+        },
+        {
+          "name": "menuItems",
+          "type": "PageHeaderMenuItem[]",
+          "required": false,
+          "description": "Entries of the overflow menu. The More actions button shows only when there is at least one."
         }
       ],
       "usage": {
-        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16, and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle and info-circle. They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
-        "whenNotToUse": "- Decoration that adds no meaning. An icon next to text that already says the same thing is hidden from assistive technology, so leave the label off, and leave the icon out when it adds nothing\n- An icon the registry does not have. Components accept no className or style, and icons come from the registry only, so a new one is a registry entry: the design system's glyph first, Tabler for the rest\n- An icon-only control without a name. Pass label, or give the control its own accessible name\n- A size other than 8, 12 or 16, or a colour other than the four tones. There is no red, no destructive colour and no third accent: an error is marked with the alert-triangle glyph beside its message, not with a colour\n- Emoji, or unicode arrows and symbols, as icons. Inter's web subsets do not hold them and the design system bans them",
-        "example": "import { Icon } from '@ratio-ui/core'\n\n// Beside text that names it: decoration, hidden from assistive technology\n<button type=\"button\">\n  <Icon name=\"plus\" />\n  Add product\n</button>\n\n// Alone: the label is the accessible name\n<Icon name=\"search\" tone=\"icon\" label=\"Search\" />\n\n// Pagination chevrons are drawn for an 8px box\n<Icon name=\"chevron-right\" size={8} />"
+        "whenToUse": "- The 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": "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": "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": "gap",
-          "type": "0 | 1 | 2 | 4 | 6 | 7 | 8 | 11 | 12 | 14 | 24 | 32 | 80",
+          "name": "page",
+          "type": "number",
           "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 being shown, counting from 1."
         },
         {
-          "name": "align",
-          "type": "\"baseline\" | \"center\" | \"end\" | \"start\" | \"stretch\"",
+          "name": "pageSize",
+          "type": "number",
+          "required": true,
+          "description": "How many results one page holds."
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "required": true,
+          "description": "How many results there are in all, across every page."
+        },
+        {
+          "name": "onPageChange",
+          "type": "(page: number) => void",
+          "required": true,
+          "description": "Called with the page to show when Previous or Next is pressed."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The footer under a table or list that has more than one page of results\n- When the parent knows the page, the page size and the total",
+        "whenNotToUse": "- Numbered page links or jump to page: this is Previous and Next only\n- Infinite scroll or a load more button\n- Styling: Pagination takes no `className` and no `style`",
+        "example": "const [page, setPage] = useState(1)\n\n<Pagination page={page} pageSize={20} total={84} onPageChange={setPage} />"
+      }
+    },
+    {
+      "name": "Popover",
+      "import": "import { Popover } from '@ratio-ui/core'",
+      "description": "A panel that opens from a trigger and holds more than text, such as a list of notifications. Put a PopoverTrigger and a PopoverContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A small panel that opens from a button and holds more than a sentence, such as the notifications list\n- Content that people read or act on, and that they close with Escape or by clicking away",
+        "whenNotToUse": "- A one-line hint: use Tooltip, or Definition for a term\n- A choice of actions: use DropdownMenu\n- A task that needs the whole screen's attention: use Dialog",
+        "example": "<Popover>\n  <PopoverTrigger>Notifications</PopoverTrigger>\n  <PopoverContent>\n    <PopoverHeader>\n      <PopoverTitle>Notifications</PopoverTitle>\n      <PopoverDescription>No new notifications</PopoverDescription>\n    </PopoverHeader>\n  </PopoverContent>\n</Popover>"
+      },
+      "parts": [
+        {
+          "name": "PopoverContent",
+          "import": "import { PopoverContent } from '@ratio-ui/core'",
+          "description": "The popover panel: a white panel with a 1px outline and no shadow, 288px wide. It opens below the trigger by default.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverDescription",
+          "import": "import { PopoverDescription } from '@ratio-ui/core'",
+          "description": "The supporting text under the title, in the muted colour.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverHeader",
+          "import": "import { PopoverHeader } from '@ratio-ui/core'",
+          "description": "Groups a title and a description at the top of the panel.",
+          "props": []
+        },
+        {
+          "name": "PopoverTitle",
+          "import": "import { PopoverTitle } from '@ratio-ui/core'",
+          "description": "The title of the panel; it names the dialog for screen readers.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "PopoverTrigger",
+          "import": "import { PopoverTrigger } from '@ratio-ui/core'",
+          "description": "The element that opens the popover on click or Enter. It renders a button unless render says otherwise.",
+          "props": [
+            {
+              "name": "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": "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,
-          "default": "center",
-          "description": "How children line up across the row, which is the vertical axis. Defaults to center."
+          "description": "The text in the field. Pass it with onValueChange to control the field."
         },
         {
-          "name": "justify",
-          "type": "\"between\" | \"center\" | \"end\" | \"start\"",
+          "name": "defaultValue",
+          "type": "string",
           "required": false,
-          "default": "start",
-          "description": "How children spread along the row, which is the horizontal axis. Defaults to start."
+          "default": "",
+          "description": "The starting text of an uncontrolled field."
         },
         {
-          "name": "wrap",
-          "type": "boolean",
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
           "required": false,
-          "default": "false",
-          "description": "Whether children move to a new line when the row is full. Defaults to false, which keeps one line."
+          "description": "Called with the new text on every change and when the field is cleared. It is not debounced: debounce in the app."
         },
         {
-          "name": "as",
-          "type": "\"aside\" | \"div\" | \"fieldset\" | \"footer\" | \"form\" | \"header\" | \"li\" | \"main\" | \"nav\" | \"ol\" | \"section\" | \"ul\"",
+          "name": "size",
+          "type": "32 | 36",
           "required": false,
-          "default": "div",
-          "description": "The element to render. Defaults to div; use a list, landmark or form element where the content is one."
+          "default": "36",
+          "description": "The height in px: 36 above a listing, 32 inside a table. Defaults to 36."
         },
         {
           "name": "ref",
-          "type": "Ref<HTMLElement>",
+          "type": "Ref<HTMLInputElement>",
           "required": false,
-          "description": "Receives the rendered element."
+          "description": "Receives the input 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>"
+        "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'",
+      "description": "The 240px side navigation of the admin: an account switcher, blocks of rows with nested groups, counts and collapsible labels, and a footer pinned at the bottom. On a phone it becomes a drawer: inside AppShell the menu button in TopBar opens it and choosing a row closes it; used alone, the caller opens it with `open` and closes it in `onOpenChange`.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The accessible name of the navigation landmark."
+        },
+        {
+          "name": "sections",
+          "type": "SideNavSection[]",
+          "required": true,
+          "description": "The blocks of rows, top to bottom."
+        },
+        {
+          "name": "active",
+          "type": "string",
+          "required": false,
+          "description": "The id of the current row. It is marked and its group opens."
+        },
+        {
+          "name": "onSelect",
+          "type": "((id: string) => void)",
+          "required": false,
+          "description": "Called with the id of the row pressed."
+        },
+        {
+          "name": "account",
+          "type": "SideNavAccount",
+          "required": false,
+          "description": "The account switcher shown above the rows."
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Content pinned at the bottom, such as Settings."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "required": false,
+          "description": "On a phone, whether the drawer is open."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "((open: boolean) => void)",
+          "required": false,
+          "description": "On a phone, called when the drawer asks to open or close."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The admin's left navigation: grouped links with nested items, counts and a pinned footer\n- A phone layout where the same navigation slides in as a drawer",
+        "whenNotToUse": "- Switching between views inside one page: use Tabs or FilterTabs\n- A menu of actions: use DropdownMenu",
+        "example": "<SideNav\n  label=\"Main\"\n  active=\"orders\"\n  onSelect={setView}\n  sections={[{ id: 'main', items: [{ id: 'home', label: 'Home', icon: 'nav-home' }, { id: 'orders', label: 'Orders', count: '12' }] }]}\n  footer={<a href=\"/settings\">Settings</a>}\n/>"
+      }
+    },
+    {
+      "name": "Skeleton",
+      "import": "import { Skeleton } from '@ratio-ui/core'",
+      "description": "A static placeholder for content that is still loading on a first load. It is hidden from assistive technology: the container that holds it says it is busy. Its fill and animation come from the loading tokens, so it does not move.",
+      "props": [
+        {
+          "name": "shape",
+          "type": "\"block\" | \"circle\" | \"line\"",
+          "required": false,
+          "default": "line",
+          "description": "The shape of the placeholder. Defaults to line. A line and a block fill the width of their parent."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A first load, where the shape of the content is known: a line for text, a block for a tile, a circle for an avatar\n- Under real headings in a table, so the columns stay put while the rows load",
+        "whenNotToUse": "- A refetch of content already on screen: keep the content and show the thin progress bar\n- A wait with no known shape: use Spinner\n- A load that has failed or returned nothing: use EmptyState",
+        "example": "<Skeleton shape=\"line\" />\n<Skeleton shape=\"circle\" />"
+      }
+    },
+    {
+      "name": "Spinner",
+      "import": "import { Spinner } from '@ratio-ui/core'",
+      "description": "A small ring for a wait with no known shape. It is static until the designer answers question 5: its motion is the --rt-spinner-animation token, none for now, so the ring is drawn from the progress colours and the status role says what it means.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "default": "Loading",
+          "description": "The accessible name, announced to assistive technology. Defaults to Loading."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A short wait where the shape of the result is not known, such as a button that saves or a panel that opens",
+        "whenNotToUse": "- A first load of a list or table: use Skeleton rows\n- A refetch of content on screen: use the thin progress bar",
+        "example": "<Spinner label=\"Saving\" />"
       }
     },
     {
@@ -129,6 +1445,212 @@
         "example": "<Stack gap={12}>\n  <div>Settlement summary</div>\n  <Stack gap={4} align=\"start\">\n    <div>Paid out every weekday</div>\n    <div>Next payout on Monday</div>\n  </Stack>\n</Stack>"
       }
     },
+    {
+      "name": "StatusPill",
+      "import": "import { StatusPill } from '@ratio-ui/core'",
+      "description": "A 20px pill with a 4px radius and a 1px border that names the state of a row, such as a product's status in a listing.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"neutral\" | \"success\" | \"warning\"",
+          "required": false,
+          "default": "neutral",
+          "description": "The colour of the pill. Defaults to neutral."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "required": false,
+          "description": "Receives the rendered span."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The state of a row or record in a listing: Draft, Active, Hidden, Low, Pending\n- A single-word status, with success for a good state and warning for one that needs a look",
+        "whenNotToUse": "- A count or a tag that is not a status\n- A state that needs its own colour: the design system has two tones, and neutral is plain text until question 3 is answered\n- A button or a link: the pill is not interactive",
+        "example": "<StatusPill tone=\"success\">Active</StatusPill>"
+      }
+    },
+    {
+      "name": "Table",
+      "import": "import { Table } from '@ratio-ui/core'",
+      "description": "A data table in the design system's Listing look: a 36px heading row over 48px rows split by 1px hairlines, 12px uppercase headings and a fill on the row under the pointer. It scrolls sideways inside its own box when the columns do not fit. Compose it from TableHeader, TableBody, TableRow, TableHead and TableCell.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Rows of records with the same columns: products, orders, customers\n- A list that needs headings, right-aligned numbers and a hover fill\n- Static content composed by hand; for sorting, selection and paging use DataTable",
+        "whenNotToUse": "- Layout: a table is for data, so use Stack and Inline to arrange a page\n- A single record's fields: use a definition list or a card\n- Styling: the parts take no `className` and no `style`",
+        "example": "<Table>\n  <TableHeader>\n    <TableRow>\n      <TableHead>Product</TableHead>\n      <TableHead numeric>Stock</TableHead>\n    </TableRow>\n  </TableHeader>\n  <TableBody>\n    <TableRow>\n      <TableCell>RYZE - 2mg</TableCell>\n      <TableCell numeric>1200</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>"
+      },
+      "parts": [
+        {
+          "name": "TableBody",
+          "import": "import { TableBody } from '@ratio-ui/core'",
+          "description": "The data rows of a table. Its rows take the hover fill.",
+          "props": []
+        },
+        {
+          "name": "TableCaption",
+          "import": "import { TableCaption } from '@ratio-ui/core'",
+          "description": "The table's title for assistive technology, shown under the table in the subdued colour.",
+          "props": []
+        },
+        {
+          "name": "TableCell",
+          "import": "import { TableCell } from '@ratio-ui/core'",
+          "description": "One cell. Text stays on one line; a numeric cell is right aligned with tabular figures so digits line up.",
+          "props": [
+            {
+              "name": "numeric",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Aligns the cell to the right with tabular figures, for a number. Defaults to false, which aligns it to the left."
+            }
+          ]
+        },
+        {
+          "name": "TableFooter",
+          "import": "import { TableFooter } from '@ratio-ui/core'",
+          "description": "The summary rows at the foot of a table, such as totals. Its rows take no hover fill.",
+          "props": []
+        },
+        {
+          "name": "TableHead",
+          "import": "import { TableHead } from '@ratio-ui/core'",
+          "description": "A column heading: 12px uppercase text in the subdued colour. It is a column header unless `scope` says otherwise.",
+          "props": [
+            {
+              "name": "numeric",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Aligns the heading to the right, over a column of numbers. Defaults to false, which aligns it to the left."
+            }
+          ]
+        },
+        {
+          "name": "TableHeader",
+          "import": "import { TableHeader } from '@ratio-ui/core'",
+          "description": "The heading rows of a table. Its rows take no hover fill.",
+          "props": []
+        },
+        {
+          "name": "TableRow",
+          "import": "import { TableRow } from '@ratio-ui/core'",
+          "description": "One row, 48px high (36px in the heading), with a hairline under it. A body row is filled when the pointer is over it or it is selected.",
+          "props": [
+            {
+              "name": "selected",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Keeps the hover fill on the row to show it is chosen, for example when its checkbox is ticked. Defaults to false."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TableLoader",
+      "import": "import { TableLoader } from '@ratio-ui/core'",
+      "description": "What a table shows on its first load: the real headings over static skeleton rows, and a count line such as \"72 of 1000 products\". The table is marked busy and the fake rows are hidden from screen readers. Use it for the first load only; later loads keep the old rows.",
+      "props": [
+        {
+          "name": "columns",
+          "type": "TableLoaderColumn[]",
+          "required": true,
+          "description": "The columns, in order."
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "required": false,
+          "default": "5",
+          "description": "How many placeholder rows to draw. Defaults to 5."
+        },
+        {
+          "name": "shown",
+          "type": "number",
+          "required": true,
+          "description": "How many results the first page will hold, for the count line."
+        },
+        {
+          "name": "total",
+          "type": "number",
+          "required": true,
+          "description": "How many results there are in all."
+        },
+        {
+          "name": "noun",
+          "type": "string",
+          "required": true,
+          "description": "What the results are called, in the plural: \"products\"."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The first load of a list: it shows the real headings over static skeleton rows, with a count such as \"72 of 1000 products\"\n- When the column headings are known before the data arrives",
+        "whenNotToUse": "- Later loads such as a new page or sort: keep the old rows and show them as busy\n- Content that is not a table: use Skeleton on its own\n- Styling: it takes no `className` and no `style`",
+        "example": "<TableLoader\n  aria-label=\"Products\"\n  columns={[{ id: 'name', header: 'Product' }, { id: 'stock', header: 'Stock', numeric: true }]}\n  shown={72}\n  total={1000}\n  noun=\"products\"\n/>"
+      }
+    },
+    {
+      "name": "Tabs",
+      "import": "import { Tabs } from '@ratio-ui/core'",
+      "description": "Sections of one page, switched by an underlined row of tabs: ABC analysis, the sections of a settings page. Holds the selected value, uncontrolled with defaultValue or controlled with value and onValueChange. To filter a list use FilterTabs, which looks like the design system's chip tab.",
+      "props": [
+        {
+          "name": "render",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsRootState>",
+          "required": false,
+          "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Sections of one page that share a heading, such as the steps of an ABC analysis or the parts of a settings page\n- Content that is shown one section at a time, with the section named by an underlined tab\n- A row of tabs whose panels sit on the same page: the tab list and the panels are tied by value",
+        "whenNotToUse": "- A single choice that filters a list, such as All, Active and Inactive above a table: use FilterTabs\n- Moving to another page: use a link\n- Steps that must be done in order: use a wizard",
+        "example": "<Tabs defaultValue=\"rules\">\n  <TabsList aria-label=\"Sections\">\n    <TabsTrigger value=\"rules\">Rules</TabsTrigger>\n    <TabsTrigger value=\"history\">History</TabsTrigger>\n  </TabsList>\n  <TabsContent value=\"rules\">Rules</TabsContent>\n  <TabsContent value=\"history\">History</TabsContent>\n</Tabs>"
+      },
+      "parts": [
+        {
+          "name": "TabsContent",
+          "import": "import { TabsContent } from '@ratio-ui/core'",
+          "description": "The panel of the tab with the same value; only the selected one is shown.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsPanelState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TabsList",
+          "import": "import { TabsList } from '@ratio-ui/core'",
+          "description": "The row of tabs, with a hairline under it. Give it an aria-label that names the sections.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsListState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TabsTrigger",
+          "import": "import { TabsTrigger } from '@ratio-ui/core'",
+          "description": "One tab: 36px tall, with a 2px blue underline and a blue semibold label when selected. A disabled tab is at 50%.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TabsTabState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "Text",
       "import": "import { Text } from '@ratio-ui/core'",
@@ -174,6 +1696,160 @@
         "whenNotToUse": "- Text in a button: buttons take the design system's two button styles, which are not Text variants\n- A colour that is not a tone: `color` is a type error, and so are `className` and `style`\n- A style that is not in the type scale: `variant=\"h2\"` is a type error, so pick the nearest of the 13\n- Space around text: use Stack or Inline\n- Several lines cut at a number of lines: `truncate` keeps one line",
         "example": "<Text as=\"h1\" variant=\"h1\">Settlements</Text>\n<Text tone=\"subdued\">Paid out every weekday</Text>"
       }
+    },
+    {
+      "name": "Toaster",
+      "import": "import { Toaster } from '@ratio-ui/core'",
+      "description": "Mounts the toast viewport, bottom right, once for the app. Messages from toast() appear in it as plain panels with the ring outline, stacked, with no entrance animation.",
+      "props": [
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "default": "Close notification",
+          "description": "The accessible name of each close button. Defaults to Close notification."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Telling the user what happened after an action: a saved product, a started sync, a failed request\n- One of three kinds: `toast.success`, `toast.info` or `toast.error`; each is announced to screen readers",
+        "whenNotToUse": "- A decision the user must make: use a Dialog\n- A message that has to stay on the page: use a banner\n- Field validation: show it on the field",
+        "example": "<Toaster />\n\ntoast.success('Product saved')\ntoast.error('Could not save', { description: 'Try again' })"
+      }
+    },
+    {
+      "name": "Tooltip",
+      "import": "import { Tooltip } from '@ratio-ui/core'",
+      "description": "A short hint for a control or term, shown on hover and keyboard focus. Put a TooltipTrigger and a TooltipContent inside it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A short hint for an icon-only control or an \"i\" icon: it opens on hover and on keyboard focus\n- Extra detail that is not needed to finish the task, one short sentence\n- Wrap the app once in TooltipProvider so the tooltips share their open delay",
+        "whenNotToUse": "- A term in running text that explains itself: use Definition, which keyboard and touch users can open\n- Anything with a link, button or form inside: use Popover\n- Information that touch users need: a tooltip does not open on touch, so show the text on the screen",
+        "example": "<TooltipProvider>\n  <Tooltip>\n    <TooltipTrigger>Settlement</TooltipTrigger>\n    <TooltipContent>Paid out every weekday</TooltipContent>\n  </Tooltip>\n</TooltipProvider>"
+      },
+      "parts": [
+        {
+          "name": "TooltipContent",
+          "import": "import { TooltipContent } from '@ratio-ui/core'",
+          "description": "The tooltip text: a dark panel with light text, no shadow and no animation. It sits above the trigger by default.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "TooltipProvider",
+          "import": "import { TooltipProvider } from '@ratio-ui/core'",
+          "description": "Shares the open delay between the tooltips inside it. Wrap the app, or a group of tooltips, once. The delay defaults to 0 ms.",
+          "props": []
+        },
+        {
+          "name": "TooltipTrigger",
+          "import": "import { TooltipTrigger } from '@ratio-ui/core'",
+          "description": "The element that opens the tooltip on hover and focus. It renders a button unless render says otherwise.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, TooltipTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TopBar",
+      "import": "import { TopBar } from '@ratio-ui/core'",
+      "description": "The bar across the top of every page: logo, search, actions, the store switcher and the account. It is 60px high on a desktop and 52px on a phone, with a hairline under it. The parts are slots, so the bar does not depend on their components. Inside an AppShell with a side nav it shows a menu button on phones, which opens the side nav drawer.",
+      "props": [
+        {
+          "name": "logo",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The logo, usually an image. When it is left out the bar shows the text wordmark instead (--rt-wordmark)."
+        },
+        {
+          "name": "wordmarkLabel",
+          "type": "string",
+          "required": false,
+          "default": "Ratio",
+          "description": "The accessible name of the text wordmark, shown when there is no logo. Defaults to Ratio."
+        },
+        {
+          "name": "menuLabel",
+          "type": "string",
+          "required": false,
+          "default": "Open navigation menu",
+          "description": "The accessible name of the phone menu button that opens the side navigation. Defaults to Open navigation menu."
+        },
+        {
+          "name": "search",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The global search, for example GlobalSearch. It takes the free space in the middle."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The buttons at the right, such as help and notifications."
+        },
+        {
+          "name": "storeSwitcher",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The store switcher, for example StoreSwitcher. It sits at the right, after the actions."
+        },
+        {
+          "name": "account",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The account at the far right, such as an Avatar or a menu of the signed-in person."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- The bar across the top of the admin: logo, global search, actions, the store switcher and the account\n- Inside AppShell's `topBar` slot",
+        "whenNotToUse": "- A heading for one page: use PageHeader\n- Navigation between sections: use SideNav",
+        "example": "<TopBar\n  search={<GlobalSearch />}\n  actions={<Button variant=\"ghost\">Help</Button>}\n  storeSwitcher={<StoreSwitcher stores={stores} storeId={storeId} onStoreChange={setStoreId} />}\n  account={<Avatar name=\"Naman Gupta\" />}\n/>"
+      },
+      "parts": [
+        {
+          "name": "StoreSwitcher",
+          "import": "import { StoreSwitcher } from '@ratio-ui/core'",
+          "description": "The store switcher of TopBar: a square avatar, the store name and a chevron that open a menu of the stores the app passes. On a phone only the avatar shows. Pass it to TopBar's `storeSwitcher` slot.",
+          "props": [
+            {
+              "name": "stores",
+              "type": "StoreOption[]",
+              "required": true,
+              "description": "The stores the person can switch between, as the app passes them."
+            },
+            {
+              "name": "storeId",
+              "type": "string",
+              "required": true,
+              "description": "The id of the current store."
+            },
+            {
+              "name": "onStoreChange",
+              "type": "((id: string) => void)",
+              "required": false,
+              "description": "Called with the id of the store chosen."
+            },
+            {
+              "name": "label",
+              "type": "string",
+              "required": false,
+              "default": "Switch store",
+              "description": "The caption of its menu. Defaults to Switch store. The button is named by the store name."
+            }
+          ]
+        }
+      ]
     }
   ]
 }