@ratio-ui/core 0.3.0 → 0.5.0

package/dist/catalogue.json

@@ -1,6 +1,37 @@
 {
-  "version": "0.3.0",
+  "version": "0.5.0",
   "components": [
+    {
+      "name": "Accordion",
+      "import": "import { Accordion } from '@ratio-ui/core'",
+      "description": "A stack of sections that open and close. One section is open at a time unless multiple is set.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- Grouped help or settings where the reader opens only the section they need\n- A short list of sections with a heading each, such as setup steps or FAQs",
+        "whenNotToUse": "- A single block that hides and shows: use a collapsible\n- Switching between views of the same content: use tabs\n- Styling: Accordion takes no `className` and no `style`",
+        "example": "<Accordion>\n  <AccordionItem value=\"shipping\">\n    <AccordionTrigger>Shipping</AccordionTrigger>\n    <AccordionContent>Ships in two days.</AccordionContent>\n  </AccordionItem>\n</Accordion>"
+      },
+      "parts": [
+        {
+          "name": "AccordionItem",
+          "import": "import { AccordionItem } from '@ratio-ui/core'",
+          "description": "One section: a trigger and its content, separated from the next by a hairline.",
+          "props": []
+        },
+        {
+          "name": "AccordionTrigger",
+          "import": "import { AccordionTrigger } from '@ratio-ui/core'",
+          "description": "The heading row of a section, with a chevron that turns when it is open.",
+          "props": []
+        },
+        {
+          "name": "AccordionContent",
+          "import": "import { AccordionContent } from '@ratio-ui/core'",
+          "description": "The body of a section. It appears and disappears at once, with no height animation.",
+          "props": []
+        }
+      ]
+    },
     {
       "name": "Alert",
       "import": "import { Alert } from '@ratio-ui/core'",
@@ -234,6 +265,36 @@
         "example": "<Avatar name=\"My Store\" shape=\"square\" />\n<Avatar name=\"Kavya Singh\" />"
       }
     },
+    {
+      "name": "Breadcrumb",
+      "import": "import { Breadcrumb } from '@ratio-ui/core'",
+      "description": "The trail to the current page: links, chevron separators, the current page as text and an overflow ellipsis.",
+      "props": [
+        {
+          "name": "items",
+          "type": "BreadcrumbItem[]",
+          "required": true,
+          "description": "The trail, from the root to the current page."
+        },
+        {
+          "name": "maxItems",
+          "type": "number",
+          "required": false,
+          "description": "Past this many items the middle ones collapse behind an ellipsis, keeping the first and the last two."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "description": "Receives the rendered nav."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Show where a page sits in a hierarchy, with a way back up",
+        "whenNotToUse": "- Switching between sibling views: use Tabs",
+        "example": "<Breadcrumb items={[{ label: 'Products', href: '/products' }, { label: 'Runner' }]} maxItems={4} />"
+      }
+    },
     {
       "name": "Button",
       "import": "import { Button } from '@ratio-ui/core'",
@@ -340,6 +401,198 @@
         }
       ]
     },
+    {
+      "name": "Chart",
+      "import": "import { Chart } from '@ratio-ui/core'",
+      "description": "A chart on Recharts, drawn with the chart tokens. It holds the config the tooltip and legend read, styles Recharts' ticks, grid and cursor with the tokens, and is a figure named by its label and summarised by a description, a visually hidden data table, or both. Motion is colour fades only, so every series passes isAnimationActive false.",
+      "props": [
+        {
+          "name": "description",
+          "type": "string",
+          "required": false,
+          "description": "One sentence on what the chart shows, read after its name, such as \"Sales peak on Tuesday\"."
+        },
+        {
+          "name": "table",
+          "type": "ChartTable",
+          "required": false,
+          "description": "The chart's rows as a visually hidden table, for assistive technology."
+        },
+        {
+          "name": "config",
+          "type": "ChartConfig",
+          "required": true,
+          "description": "The series and categories, by data key: their labels, icons and chart tokens."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "description": "The chart's accessible name, such as \"Sales by day\"."
+        },
+        {
+          "name": "aspect",
+          "type": "\"fill\" | \"square\" | \"video\"",
+          "required": false,
+          "default": "video",
+          "description": "The size: video (16:9, the default) or square at the full width, or fill to take the parent's size."
+        },
+        {
+          "name": "initialDimension",
+          "type": "{ width: number; height: number; }",
+          "required": false,
+          "default": "{ width: 320, height: 200 } as const",
+          "description": "The size the chart is drawn at before it measures its box. Defaults to 320 by 200."
+        },
+        {
+          "name": "children",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+          "required": true,
+          "description": "One Recharts chart, such as a BarChart or a LineChart, whose series pass isAnimationActive false."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Analytics: a trend or a comparison over days or categories, as bars or lines\n- The page loader's bar mark\n- With a label and a one-sentence description, a data table, or both, so assistive technology gets the same summary\n- Every series passes isAnimationActive false: motion is colour fades only, and the tooltip never moves",
+        "whenNotToUse": "- A single number or a few numbers side by side: use MetricStrip\n- Progress towards an end: use Progress\n- Colours outside chart-1 to chart-5, or chart-4 and chart-5 alone on white: they sit below 3:1, so draw them beside a darker series",
+        "example": "import { Bar, BarChart, CartesianGrid, XAxis } from 'recharts'\n\nconst config = { sales: { label: 'Sales', color: 'chart-1' } } satisfies ChartConfig\n\n<Chart config={config} label=\"Sales by day\" description=\"Sales peak on Friday\">\n  <BarChart data={week} accessibilityLayer>\n    <CartesianGrid vertical={false} />\n    <XAxis dataKey=\"day\" tickLine={false} axisLine={false} />\n    <ChartTooltip content={<ChartTooltipContent formatValue={formatMoney} />} />\n    <Bar dataKey=\"sales\" fill={chartColor('chart-1')} isAnimationActive={false} />\n  </BarChart>\n</Chart>"
+      },
+      "parts": [
+        {
+          "name": "ChartTooltip",
+          "import": "import { ChartTooltip } from '@ratio-ui/core'",
+          "description": "The chart's tooltip: Recharts' Tooltip, still (no movement), drawing ChartTooltipContent unless given other content.",
+          "props": [
+            {
+              "name": "cursor",
+              "type": "boolean",
+              "required": false,
+              "description": "Shows the cursor line or band under the pointer. On or off: Recharts' SVG props would carry a class name and a style."
+            }
+          ]
+        },
+        {
+          "name": "ChartTooltipContent",
+          "import": "import { ChartTooltipContent } from '@ratio-ui/core'",
+          "description": "The box a chart tooltip draws: the active point's label, then a row per series with its swatch, its config label and its value, a count unless formatValue writes it. A 1px border on white, no shadow.",
+          "props": [
+            {
+              "name": "active",
+              "type": "boolean",
+              "required": false,
+              "description": "Set by the tooltip: whether a point is active."
+            },
+            {
+              "name": "payload",
+              "type": "readonly Payload<ValueType, TooltipNameType>[]",
+              "required": false,
+              "description": "Set by the tooltip: the values of the series at the active point."
+            },
+            {
+              "name": "label",
+              "type": "ReactNode",
+              "required": false,
+              "description": "Set by the tooltip: the active point's label, such as its x-axis category."
+            },
+            {
+              "name": "labelFormatter",
+              "type": "((label: ReactNode, payload: readonly Payload<ValueType, TooltipNameType>[]) => ReactNode)",
+              "required": false,
+              "description": "Writes the label from it and the payload."
+            },
+            {
+              "name": "formatter",
+              "type": "Formatter<ValueType, TooltipNameType>",
+              "required": false,
+              "description": "Draws a whole row, in place of the swatch, name and value, from the value, name, item, index and payload."
+            },
+            {
+              "name": "indicator",
+              "type": "\"dashed\" | \"dot\" | \"line\"",
+              "required": false,
+              "default": "dot",
+              "description": "The swatch: a dot (the default), a line or a dashed line."
+            },
+            {
+              "name": "hideLabel",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Leaves out the label."
+            },
+            {
+              "name": "hideIndicator",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Leaves out the swatches."
+            },
+            {
+              "name": "nameKey",
+              "type": "string",
+              "required": false,
+              "description": "The key of the item, or its data row, whose value names the config entry of a row."
+            },
+            {
+              "name": "labelKey",
+              "type": "string",
+              "required": false,
+              "description": "The key whose config entry labels the tooltip, in place of the active point's label."
+            },
+            {
+              "name": "color",
+              "type": "\"chart-1\" | \"chart-2\" | \"chart-3\" | \"chart-4\" | \"chart-5\"",
+              "required": false,
+              "description": "One chart token for every swatch, in place of each series' own."
+            },
+            {
+              "name": "formatValue",
+              "type": "((value: number) => string)",
+              "required": false,
+              "description": "Writes a number for its series, such as formatMoney for sales. Defaults to a count."
+            }
+          ]
+        },
+        {
+          "name": "ChartLegend",
+          "import": "import { ChartLegend } from '@ratio-ui/core'",
+          "description": "The chart's legend: Recharts' Legend, drawing ChartLegendContent unless given other content.",
+          "props": []
+        },
+        {
+          "name": "ChartLegendContent",
+          "import": "import { ChartLegendContent } from '@ratio-ui/core'",
+          "description": "The row a chart legend draws: a swatch in each series' chart token, or its icon, and its config label.",
+          "props": [
+            {
+              "name": "payload",
+              "type": "readonly LegendPayload[]",
+              "required": false,
+              "description": "Set by the legend: its series."
+            },
+            {
+              "name": "verticalAlign",
+              "type": "\"bottom\" | \"middle\" | \"top\"",
+              "required": false,
+              "default": "bottom",
+              "description": "Set by the legend: whether it sits above or below the chart, which sets the side of its gap."
+            },
+            {
+              "name": "hideIcon",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Draws the swatch even where the config gives an icon."
+            },
+            {
+              "name": "nameKey",
+              "type": "string",
+              "required": false,
+              "description": "The key of the item whose value names the config entry of a series."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "Checkbox",
       "import": "import { Checkbox } from '@ratio-ui/core'",
@@ -474,6 +727,124 @@
         "example": "```tsx\n<Collapsible title=\"More pricing\" summary={[{ label: 'Cost price', value: '₹450.00' }, { label: 'HSN code', value: '6109' }]}>\n  ...fields...\n</Collapsible>\n```\n\nThe panel appears and disappears at once; the library has no height animation."
       }
     },
+    {
+      "name": "Combobox",
+      "import": "import { Combobox } from '@ratio-ui/core'",
+      "description": "A field to choose one option from a list, with a search: type to narrow the list, pick with the mouse or Enter. The field looks like an Input and the list like a Popover panel. For several choices shown as chips, use TagInput. Mark it invalid with aria-invalid; give the list an empty text with emptyText. Inside a Field, the label, hint, error and required mark reach the input.",
+      "props": [
+        {
+          "name": "items",
+          "type": "readonly ComboboxItem[]",
+          "required": true,
+          "description": "The options. Strings or { value, label } objects."
+        },
+        {
+          "name": "value",
+          "type": "string | null",
+          "required": false,
+          "description": "The chosen value for a controlled combobox, or null for none."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | null",
+          "required": false,
+          "description": "The value to start with when the combobox keeps its own state."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string | null, eventDetails: ChangeEventDetails) => void)",
+          "required": false,
+          "description": "Called with the new value, or null when the choice is cleared."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "description": "The text shown while nothing is chosen."
+        },
+        {
+          "name": "emptyText",
+          "type": "string",
+          "required": false,
+          "default": "No results found",
+          "description": "The text shown when the search matches no option. Defaults to \"No results found\"."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Marks the field invalid and draws the error ring, as on every form control. Field sets it when it shows an error."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "The same as aria-invalid, kept as its alias."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "Shows a button that clears the choice while one is made. Defaults to true."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Stops people from changing the choice."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "description": "The name of the field in a form."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name when no label is wired to the field."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that name the field. Field sets it to its label."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that describe the field, such as its hint or error. Field sets it."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Tells assistive technology that the field must be filled. Field sets it for a required field."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the input, for a label's htmlFor."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the input element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Choosing one option from a long list that people search, such as a vendor or a product type\n- A field where the list may be empty or the search may match nothing",
+        "whenNotToUse": "- A short list of a few options: use a radio group or tabs\n- Several choices shown as chips: use TagInput\n- A list of actions: use DropdownMenu",
+        "example": "<Combobox aria-label=\"Vendor\" items={['Acme', 'Northwind']} placeholder=\"Choose a vendor\" onValueChange={setVendor} />"
+      }
+    },
     {
       "name": "DataTable",
       "import": "import { DataTable } from '@ratio-ui/core'",
@@ -580,7 +951,7 @@
     {
       "name": "DatePicker",
       "import": "import { DatePicker } from '@ratio-ui/core'",
-      "description": "A field that shows a day as DD/MM/YYYY, reads a typed date through the format module and opens a calendar in a popover from the button at its end. Text that is not a date is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits the day as YYYY-MM-DD (empty when there is none), never the text on screen.",
+      "description": "A field that shows a day as DD/MM/YYYY, reads a typed date through the format module and opens a calendar in a popover from the button at its end. Text that is not a date reports null (as soon as it is typed over a day, and when the field loses focus) and is marked invalid, aria-invalid, when the field loses focus; the app shows Field's error from the null. Under a name, a form submits the day as YYYY-MM-DD (empty when there is none), never the text on screen.",
       "props": [
         {
           "name": "value",
@@ -599,7 +970,7 @@
           "name": "onValueChange",
           "type": "((value: Date | null) => void)",
           "required": false,
-          "description": "Called with the day when a typed date is complete or a day is picked, and with null when the text is cleared."
+          "description": "Called with the day when a typed date is complete or a day is picked, and with null when the text is cleared or is not a date."
         },
         {
           "name": "disabledDays",
@@ -636,13 +1007,13 @@
       "usage": {
         "whenToUse": "- One day a person types or picks, such as a \"Best before\" custom field: `value` and `onValueChange` take a `Date` (or null when empty)\n- A date inside a table: `size` 32\n- Limiting the days: `disabledDays` (for example `{ before: new Date() }`), `startMonth` and `endMonth`, which limit the calendar (a typed date is not checked against them)",
         "whenNotToUse": "- A period of days, such as an analytics range: use DateRangePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a date as text: write it with the format module (`formatDate`)\n- Custom classes or inline styles: DatePicker takes neither `className` nor `style`",
-        "example": "```tsx\nconst [bestBefore, setBestBefore] = useState<Date | null>(null)\n\n<DatePicker aria-label=\"Best before\" value={bestBefore} onValueChange={setBestBefore} />\n<DatePicker aria-label=\"Expiry\" size={32} aria-invalid aria-describedby=\"expiry-error\" />\n```\n\nThe field shows DD/MM/YYYY and reads typed dates through the format module (\"3/1/2026\" is 3 January). Text that is not a date turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits the committed day as `YYYY-MM-DD` (an empty string when the field is empty), not the text on screen: `<DatePicker name=\"bestBefore\" />` posts `bestBefore=2026-10-28`. A disabled field posts nothing."
+        "example": "```tsx\nconst [bestBefore, setBestBefore] = useState<Date | null>(null)\n\n<DatePicker aria-label=\"Best before\" value={bestBefore} onValueChange={setBestBefore} />\n<DatePicker aria-label=\"Expiry\" size={32} aria-invalid aria-describedby=\"expiry-error\" />\n```\n\nThe field shows DD/MM/YYYY and reads typed dates through the format module (\"3/1/2026\" is 3 January). Text that is not a date is never reported as a day: `onValueChange` gets `null` (as soon as a held day is typed over, and again when the field loses focus), and the field turns invalid (`aria-invalid`) when it loses focus."
       }
     },
     {
       "name": "DateRangePicker",
       "import": "import { DateRangePicker } from '@ratio-ui/core'",
-      "description": "A field that shows a range as two DD/MM/YYYY days, reads a typed range through the format module and opens a calendar in a popover from the button at its end, for analytics periods. Pick the first day, then the last. Text that is not a range in order is marked invalid when the field loses focus, and reports nothing. Under a name, a form submits two fields, `name.from` and `name.to`, each as YYYY-MM-DD (empty when there is no range), never the text on screen.",
+      "description": "A field that shows a range as two DD/MM/YYYY days, reads a typed range through the format module and opens a calendar in a popover from the button at its end, for analytics periods. Pick the first day, then the last. Text that is not a range in order reports null (as soon as it is typed over a range, and when the field loses focus) and is marked invalid, aria-invalid, when the field loses focus. Under a name, a form submits two fields, `name.from` and `name.to`, each as YYYY-MM-DD (empty when there is no range), never the text on screen.",
       "props": [
         {
           "name": "value",
@@ -661,7 +1032,7 @@
           "name": "onValueChange",
           "type": "((value: DateRangeValue | null) => void)",
           "required": false,
-          "description": "Called with the range when a typed range is complete or two days are picked, and with null when the text is cleared."
+          "description": "Called with the range when a typed range is complete or two days are picked, and with null when the text is cleared or is not a range."
         },
         {
           "name": "disabledDays",
@@ -698,7 +1069,7 @@
       "usage": {
         "whenToUse": "- A period of days a person types or picks, such as an analytics range: `value` and `onValueChange` take `{ from, to }` (or null when empty)\n- Limiting the days: `disabledDays` (for example `{ after: new Date() }` for reports), `startMonth` and `endMonth`, which limit the calendar (a typed range is not checked against them)\n- A range inside a table: `size` 32",
         "whenNotToUse": "- One day: use DatePicker\n- A calendar shown on the page, not behind a field: use Calendar\n- Showing a range as text: write both days with the format module (`formatDate`)\n- Custom classes or inline styles: DateRangePicker takes neither `className` nor `style`",
-        "example": "```tsx\nconst [period, setPeriod] = useState<DateRangeValue | null>(null)\n\n<DateRangePicker aria-label=\"Period\" value={period} onValueChange={setPeriod} disabledDays={{ after: new Date() }} />\n```\n\nThe field shows `28/10/2026 – 03/11/2026`. Pick the first day, then the last (an earlier second day swaps them). A typed range with the end before the start, or one day only, turns the field invalid when it loses focus and is never reported.\n\nUnder a `name`, a form submits two fields, `name.from` and `name.to`, each the committed day as `YYYY-MM-DD` (empty strings when the field is empty), not the text on screen: `<DateRangePicker name=\"period\" />` posts `period.from=2026-10-28` and `period.to=2026-11-03`. A disabled field posts nothing."
+        "example": "```tsx\nconst [period, setPeriod] = useState<DateRangeValue | null>(null)\n\n<DateRangePicker aria-label=\"Period\" value={period} onValueChange={setPeriod} disabledDays={{ after: new Date() }} />\n```\n\nThe field shows `28/10/2026 – 03/11/2026`. Pick the first day, then the last (an earlier second day swaps them). A typed range with the end before the start, or one day only, is never reported as a range: `onValueChange` gets `null` (as soon as a held range is typed over, and again on blur), and the field turns invalid (`aria-invalid`) when it loses focus. Show the error with Field as in DatePicker: `error={touched && range === null ? 'Enter a period as DD/MM/YYYY – DD/MM/YYYY' : undefined}`, `touched` set from `onBlur`.\n\nUnder a `name`, a form submits two fields, `name.from` and `name.to`, each the committed day as `YYYY-MM-DD` (empty strings when the field is empty), not the text on screen: `<DateRangePicker name=\"period\" />` posts `period.from=2026-10-28` and `period.to=2026-11-03`. A disabled field posts nothing."
       }
     },
     {
@@ -829,6 +1200,118 @@
         }
       ]
     },
+    {
+      "name": "Drawer",
+      "import": "import { Drawer } from '@ratio-ui/core'",
+      "description": "The root of a drawer: a panel people swipe away on a phone. It holds the open state and renders nothing itself. `swipeDirection` picks the edge it leaves by (down, the default, makes a bottom drawer). Pass `open` and `onOpenChange` to control it, or `defaultOpen`. The page behind is inert while it is open, with no scrim over it.",
+      "props": [
+        {
+          "name": "showSwipeHandle",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Whether a short bar shows on the edge the drawer is swiped from, as a hint on phones. Defaults to false."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A panel on a phone that people swipe away, such as filters or a short form under the list\n- A bottom drawer by default; a side drawer (swipeDirection left or right) for a phone menu\n- Show the swipe handle on phones as a hint; the corner close button stays for people who do not swipe",
+        "whenNotToUse": "- A large surface on a wide screen, such as Settings: use a Sheet\n- A short task or a confirm step: use a Dialog\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Drawer showSwipeHandle>\n  <DrawerTrigger>Filters</DrawerTrigger>\n  <DrawerContent>\n    <DrawerHeader>\n      <DrawerTitle>Filters</DrawerTitle>\n      <DrawerDescription>Narrow the product list</DrawerDescription>\n    </DrawerHeader>\n    <DrawerFooter>\n      <DrawerClose>Done</DrawerClose>\n    </DrawerFooter>\n  </DrawerContent>\n</Drawer>"
+      },
+      "parts": [
+        {
+          "name": "DrawerClose",
+          "import": "import { DrawerClose } from '@ratio-ui/core'",
+          "description": "A button that closes the drawer, such as Done in the footer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerCloseState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DrawerContent",
+          "import": "import { DrawerContent } from '@ratio-ui/core'",
+          "description": "The panel, white with a hairline and 24px corners on its inner edge. A bottom drawer spans the screen and sizes to its content; a side drawer is full height and three quarters of a phone screen, 384px from the small breakpoint up. It follows the finger while it is swiped and otherwise does not move: no slide in or out, no scrim, blur or shadow. Put DrawerHeader, the content and DrawerFooter inside.",
+          "props": [
+            {
+              "name": "showCloseButton",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Whether the corner close button shows. It is the way to close without swiping. Defaults to true."
+            },
+            {
+              "name": "closeLabel",
+              "type": "string",
+              "required": false,
+              "default": "Close",
+              "description": "The accessible name of the corner close button. Defaults to Close."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DrawerDescription",
+          "import": "import { DrawerDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the drawer is for, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerDescriptionState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DrawerFooter",
+          "import": "import { DrawerFooter } from '@ratio-ui/core'",
+          "description": "The actions at the bottom of the drawer, stacked full width for a thumb.",
+          "props": []
+        },
+        {
+          "name": "DrawerHeader",
+          "import": "import { DrawerHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked, with room on the right for the close button.",
+          "props": []
+        },
+        {
+          "name": "DrawerTitle",
+          "import": "import { DrawerTitle } from '@ratio-ui/core'",
+          "description": "The drawer's name, in the b4 style. It names the drawer for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerTitleState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "DrawerTrigger",
+          "import": "import { DrawerTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the drawer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DrawerTriggerState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "DropdownMenu",
       "import": "import { DropdownMenu } from '@ratio-ui/core'",
@@ -1099,7 +1582,7 @@
     {
       "name": "Field",
       "import": "import { Field } from '@ratio-ui/core'",
-      "description": "A form row: label, control, hint and error. It wires the label to the control by id, links the hint and error with aria-describedby, and sets aria-invalid when there is an error. The control keeps an id it already has.",
+      "description": "A form row: label, control, hint and error. It wires the label to the control by id and aria-labelledby (which also names a group such as RadioGroup), links the hint and error with aria-describedby, and sets aria-invalid when there is an error. The control keeps an id it already has.",
       "props": [
         {
           "name": "label",
@@ -1141,13 +1624,13 @@
           "name": "children",
           "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>> | ((props: FieldControlProps) => ReactNode)",
           "required": true,
-          "description": "The control: one element, such as Input, which gets an id, aria-describedby, aria-invalid, aria-required and disabled. When the control sits inside a wrapper such as InputGroup, pass a function instead and spread the props it receives onto the input itself."
+          "description": "The control: one element, such as Input, which gets an id, aria-labelledby, aria-describedby, aria-invalid, aria-required and disabled. When the control sits inside a wrapper such as InputGroup, pass a function instead and spread the props it receives onto the input itself."
         }
       ],
       "usage": {
-        "whenToUse": "- Every form row: a label, one control, and optional hint, error, info tooltip and required mark\n- Wiring: Field sets the control's id, aria-describedby, aria-invalid, aria-required and disabled, so you do not",
+        "whenToUse": "- Every form row: a label, one control, and optional hint, error, info tooltip and required mark\n- Wiring: Field sets the control's id, aria-labelledby, aria-describedby, aria-invalid, aria-required and disabled, so you do not",
         "whenNotToUse": "- A heading for a group of controls: use a fieldset with a legend\n- A label with no control beside it: use Label alone, with `htmlFor`\n- Long help that must be read to finish the task: put it on the screen as the hint",
-        "example": "```tsx\n<Field label=\"Title\" hint=\"Shown in search results\" error={errors.title} required>\n  <Input />\n</Field>\n<Field label=\"MRP\" info=\"Maximum retail price, with tax\">\n  <Input inputMode=\"decimal\" />\n</Field>\n```\n\nFor an input inside an InputGroup, pass a function child and spread its props onto the input: `<Field label=\"MRP\">{(props) => <InputGroup>…<InputGroupInput {...props} /></InputGroup>}</Field>`.\n\nFor a Select, which renders no element of its own, spread the props onto its trigger: `<Field label=\"GST rate\">{(props) => <Select items={rates}><SelectTrigger {...props}><SelectValue /></SelectTrigger><SelectContent>…</SelectContent></Select>}</Field>`.\n\nThe error shows beside the alert glyph in the error ink (question 1) and replaces the hint. Label is the same label as a separate part."
+        "example": "```tsx\n<Field label=\"Title\" hint=\"Shown in search results\" error={errors.title} required>\n  <Input />\n</Field>\n<Field label=\"MRP\" info=\"Maximum retail price, with tax\">\n  <Input inputMode=\"decimal\" />\n</Field>\n```\n\nFor an input inside an InputGroup, pass a function child and spread its props onto the input: `<Field label=\"MRP\">{(props) => <InputGroup>…<InputGroupInput {...props} /></InputGroup>}</Field>`.\n\nA Combobox or a RadioGroup goes straight inside, like an Input: the label names a radio group through `aria-labelledby`, because a label cannot point at a group.\n\nFor a Select, which renders no element of its own, spread the props onto its trigger: `<Field label=\"GST rate\">{(props) => <Select items={rates}><SelectTrigger {...props}><SelectValue /></SelectTrigger><SelectContent>…</SelectContent></Select>}</Field>`.\n\nThe error shows beside the alert glyph in the error ink (question 1) and replaces the hint. Label is the same label as a separate part."
       },
       "parts": [
         {
@@ -1279,11 +1762,11 @@
     {
       "name": "Icon",
       "import": "import { Icon } from '@ratio-ui/core'",
-      "description": "Draws one icon of the registry: the design system's own glyphs, filled in a single colour, and Tabler's icons for the rest, drawn with a 1.5px line at every size. The icon is a square box of 8, 12 or 16px and takes the colour of its tone.",
+      "description": "Draws one icon of the registry: the design system's own glyphs, filled (or, for check-mark, stroked) in a single colour, and Tabler's icons for the rest, drawn with a 1.5px line at every size. The icon is a square box of 8, 12 or 16px and takes the colour of its tone.",
       "props": [
         {
           "name": "name",
-          "type": "\"alert-triangle\" | \"calendar\" | \"check\" | \"chevron-left\" | \"chevron-right\" | \"export\" | \"import\" | \"info-circle\" | \"menu\" | \"more\" | \"nav-analytics\" | \"nav-apps\" | \"nav-caret-down\" | \"nav-chevron\" | \"nav-content\" | \"nav-customers\" | \"nav-discounts\" | \"nav-growth\" | \"nav-home\" | \"nav-markets\" | \"nav-orders\" | \"nav-product\" | \"nav-product-2\" | \"nav-sales-channels\" | \"nav-settings\" | \"nav-shortcut\" | \"plus\" | \"search\" | \"x\"",
+          "type": "\"alert-triangle\" | \"arrow-down\" | \"arrow-up\" | \"calendar\" | \"check\" | \"check-mark\" | \"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."
         },
@@ -1309,7 +1792,7 @@
         }
       ],
       "usage": {
-        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- The date pickers' open button: calendar (Tabler) at size 12\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a 1.5px CSS caret in an 8px box, so chevron-left and chevron-right stand in. Each is the outline of a line 1.5 units wide with round ends, two legs at 45 degrees, each 2.5 units across and 2.5 down, through (2.75, 1.5), (5.25, 4) and (2.75, 6.5) in an 8 unit box. They scale like every filled glyph, so draw them at size 8, and expect them to be replaced when the designer sends real vectors",
+        "whenToUse": "- A glyph beside a label inside a control: the plus on a main button, the magnifier in a search field, the export tray on a secondary button. Use size 12\n- The side navigation: the nav glyphs at size 16 (nav-home and nav-product are the design system's own; nav-orders, nav-customers, nav-growth, nav-discounts, nav-content, nav-markets, nav-analytics, nav-sales-channels, nav-apps and nav-settings are Tabler stand-ins for the dashboard's sections, question 7), and the disclosure caret (nav-chevron or nav-caret-down, one glyph under two names) at size 8\n- The date pickers' open button: calendar (Tabler) at size 12\n- Pagination: chevron-left and chevron-right at size 8\n- A mark that Tabler supplies: check, x, alert-triangle, info-circle, import, more (three dots) and menu (the phone menu button). They are drawn with a 1.5px line at every size, so they sit beside the design system's own glyphs without looking heavier\n- Meaning that lives only in the icon: pass label. The icon is then an image that assistive technology announces under that name. Without a label it is decoration and is hidden from assistive technology\n- Colour: tone current, the default, takes the colour of the text around the icon. icon is the design system's icon ink, subdued is its subdued text ink and primary is the accent\n- Chevron geometry (design question 9): the design system has no vector for its pagination chevrons, only a CSS caret in an 8px box (a 4.48px square with 1.5px top and right borders, rotated 45 degrees, square ends), so chevron-left and chevron-right draw that caret as a path: about 8.5px tall, so it reaches 0.23 units past the top and bottom of the 8 unit box (glyphs are not clipped), centred at x 3.5 for the right chevron and 4.5 for the left. Draw them at size 8, and expect them to be replaced when the designer sends real vectors\n- check-mark is the design system's own checkbox check, the path M1 4.2 L3 6.2 L7 1.8 in an 8 unit box as a 1.4 line with round ends; use it at size 8. arrow-up and arrow-down are Tabler's, for a table's sort direction, because the design system has no sort glyph (question 7)",
         "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} />"
       }
@@ -1403,59 +1886,169 @@
           "default": "36",
           "description": "The height in px: 36 for forms and search, 32 for fields inside a table. Defaults to 36."
         },
+        {
+          "name": "search",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Draws the design system search bar's 8px side padding instead of 12px. SearchField sets it; forms leave it off."
+        },
         {
           "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": [
+          "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": "InputOtp",
+      "import": "import { InputOtp } from '@ratio-ui/core'",
+      "description": "A one-time-code field: six 44px digit slots (set `length` for another count) over one hidden input, so the browser offers the SMS code (autocomplete one-time-code), a pasted code fills every slot, and the numeric keypad opens on phones. Digits only.",
+      "props": [
+        {
+          "name": "length",
+          "type": "number",
+          "required": false,
+          "default": "6",
+          "description": "The number of digits. Defaults to 6."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "description": "The code typed so far, for a controlled field."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "description": "The code typed so far, for an uncontrolled field."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called with the whole code on every change, including a paste."
+        },
+        {
+          "name": "onComplete",
+          "type": "((value: string) => void)",
+          "required": false,
+          "description": "Called once with the code when every slot is filled."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "description": "Stops editing and halves the opacity."
+        },
+        {
+          "name": "aria-invalid",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Draws the error ring on every slot."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name, for example \"6-digit code\"."
+        },
+        {
+          "name": "aria-labelledby",
+          "type": "string",
+          "required": false,
+          "description": "The id of an element that names the field."
+        },
+        {
+          "name": "aria-describedby",
+          "type": "string",
+          "required": false,
+          "description": "The ids of the elements that describe the field, such as its hint or error. Field sets it."
+        },
+        {
+          "name": "aria-required",
+          "type": "boolean | \"true\" | \"false\"",
+          "required": false,
+          "description": "Tells assistive technology that the code must be filled. Field sets it for a required field."
+        },
         {
-          "name": "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": "id",
+          "type": "string",
+          "required": false,
+          "description": "The id of the hidden input, for a label's htmlFor. Field sets it."
         },
         {
-          "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": "name",
+          "type": "string",
+          "required": false,
+          "description": "The form field name."
         },
         {
-          "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": "autoFocus",
+          "type": "boolean",
+          "required": false,
+          "description": "Focuses the field on mount."
         },
         {
-          "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": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "description": "Receives the hidden input element."
         }
-      ]
+      ],
+      "usage": {
+        "whenToUse": "- The code step of a sign-in: the 6-digit code sent by SMS or email (\"Verify and sign in\")\n- Any short numeric code: set `length` for another count\n- A wrong code: set `aria-invalid` and every slot draws the error ring, and put the message beside the field in text",
+        "whenNotToUse": "- A code with letters: InputOtp takes digits only\n- A long or free-form value: use Input\n- Custom classes or inline styles: InputOtp takes no `className` and no `style`",
+        "example": "```tsx\n<InputOtp aria-label=\"6-digit code\" value={code} onValueChange={setCode} onComplete={(code) => verify(code)} />\n<InputOtp aria-label=\"PIN\" length={4} aria-invalid />\n```\n\nThe browser offers the SMS code through `autocomplete=\"one-time-code\"`, and a pasted code fills every slot."
+      }
     },
     {
       "name": "Kbd",
@@ -1483,6 +2076,31 @@
         }
       ]
     },
+    {
+      "name": "KeyValueList",
+      "import": "import { KeyValueList } from '@ratio-ui/core'",
+      "description": "Settings rows in a hairline bordered panel: the label on the left, the value on the right and an optional action. It is a description list, so a screen reader announces each label with its value.",
+      "props": [
+        {
+          "name": "items",
+          "type": "KeyValueItem[]",
+          "required": true,
+          "description": "The rows, in order."
+        },
+        {
+          "name": "emptyValue",
+          "type": "string",
+          "required": false,
+          "default": "Not set",
+          "description": "What an empty value shows. Defaults to \"Not set\"."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- Settings and detail rows: a label on the left, its value on the right, an optional action such as Edit\n- A value that may be empty: it shows a placeholder, \"Not set\" by default",
+        "whenNotToUse": "- Rows of many columns to scan or sort: use Table or DataTable\n- Editing a value in place: use a form with Input",
+        "example": "```tsx\n<KeyValueList\n  items={[\n    { label: 'Store name', value: 'Maison Yara', action: { label: 'Edit', onClick: edit } },\n    { label: 'Phone' },\n  ]}\n/>\n```\n\nMoney and dates arrive already formatted; use the format module."
+      }
+    },
     {
       "name": "Link",
       "import": "import { Link } from '@ratio-ui/core'",
@@ -1522,7 +2140,7 @@
         }
       ],
       "usage": {
-        "whenToUse": "- A text link to another page: \"← Products\", \"View all variants →\"\n- A back link in a detail page's body (the page header has its own back link)",
+        "whenToUse": "- A text link to another page: \"← Products\", \"View all variants →\"\n- A back link in a detail page's body (the page header draws its back link with Link too, so the two look alike)",
         "whenNotToUse": "- An action that changes something: use Button\n- A whole table row: use DataTable's `rowHref`\n- A navigation row in the side navigation: use SideNav",
         "example": "<Link href=\"/products\" back>Products</Link>\n<Link href=\"/products/blue-shirt/variants\" forward>View all variants</Link>"
       }
@@ -1870,6 +2488,12 @@
           "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>",
@@ -1882,12 +2506,6 @@
               "required": false,
               "description": "A payload to pass to the popover when it is opened."
             },
-            {
-              "name": "render",
-              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>",
-              "required": false,
-              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
-            },
             {
               "name": "delay",
               "type": "number",
@@ -1913,6 +2531,75 @@
         }
       ]
     },
+    {
+      "name": "Progress",
+      "import": "import { Progress } from '@ratio-ui/core'",
+      "description": "The thin progress bar of question 5, 2px high, for page loads and refetches. Determinate with a value, indeterminate without one (a partial bar that moves only when the loading animation token names a motion, question 5). Base UI gives it the progressbar role, its label and its value text.",
+      "props": [
+        {
+          "name": "value",
+          "type": "number | null",
+          "required": false,
+          "default": "null",
+          "description": "The current value; leave it out or pass null for an indeterminate bar."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "default": "100",
+          "description": "The value at which the bar is full. Defaults to 100; for steps, the number of steps."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "description": "A visible label, which also names the bar for screen readers."
+        },
+        {
+          "name": "showValue",
+          "type": "boolean",
+          "required": false,
+          "description": "Shows the value on the right: a percent, or \"value/max\" with steps."
+        },
+        {
+          "name": "steps",
+          "type": "boolean",
+          "required": false,
+          "description": "The step variant: counts completed steps out of max, such as 0/5 for the setup guide. Implies showValue."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "description": "The accessible name when there is no visible label."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A page load or a refetch of content already on screen (the thin 2px bar, question 5)\n- The setup guide's step count, with the steps variant (\"0/5\")",
+        "whenNotToUse": "- A first load of a list or table: use Skeleton rows\n- A short wait on one control: use Spinner",
+        "example": "```tsx\n<Progress label=\"Loading orders\" value={60} showValue />\n<Progress label=\"Setup guide\" value={0} max={5} steps />\n<Progress aria-label=\"Refreshing\" />\n```\n\nWithout a value the bar is indeterminate: a static partial bar, since the loading animation token is none."
+      }
+    },
+    {
+      "name": "RadioGroup",
+      "import": "import { RadioGroup } from '@ratio-ui/core'",
+      "description": "A column of radio buttons where exactly one can be on. The arrow keys move the choice. aria-invalid on the group, as Field sets it, draws the error ring on every item.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- One choice among a few options that all deserve to be seen at once, such as a plan or a delivery method\n- A form field where the answer is exactly one of two to five values",
+        "whenNotToUse": "- Several answers can be on: use checkboxes\n- A setting that applies at once: use a switch\n- A long list of options: use a select\n- Styling: RadioGroup and RadioGroupItem take no `className` and no `style`",
+        "example": "```tsx\n<RadioGroup aria-label=\"Plan\" value={plan} onValueChange={setPlan}>\n  <Inline gap={8} align=\"center\">\n    <RadioGroupItem id=\"plan-free\" value=\"free\" />\n    <Label htmlFor=\"plan-free\">Free</Label>\n  </Inline>\n  <Inline gap={8} align=\"center\">\n    <RadioGroupItem id=\"plan-pro\" value=\"pro\" />\n    <Label htmlFor=\"plan-pro\">Pro</Label>\n  </Inline>\n</RadioGroup>\n```\n\nGive every item an `id` and a visible `Label` that points at it, so the text people read is the radio's name."
+      },
+      "parts": [
+        {
+          "name": "RadioGroupItem",
+          "import": "import { RadioGroupItem } from '@ratio-ui/core'",
+          "description": "One choice in a RadioGroup: a 14px round control like the checkbox, drawn with a hairline ring and filled in the primary colour with a white dot when chosen. An invisible 24px area around it takes the tap.",
+          "props": []
+        }
+      ]
+    },
     {
       "name": "SaveBar",
       "import": "import { SaveBar } from '@ratio-ui/core'",
@@ -1984,6 +2671,37 @@
         "example": "```tsx\n<SaveBar dirty={form.isDirty} saving={form.isSaving} onSave={form.save} onDiscard={form.reset} />\n```\n\nIt renders in flow and nothing when not dirty; the app shell decides where it sits. While saving, Save is disabled."
       }
     },
+    {
+      "name": "ScrollArea",
+      "import": "import { ScrollArea } from '@ratio-ui/core'",
+      "description": "A scrolling region that fills its parent, which sets the height or width, with a thin scrollbar in the design system greys.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The scrolling content."
+        },
+        {
+          "name": "orientation",
+          "type": "\"both\" | \"horizontal\" | \"vertical\"",
+          "required": false,
+          "default": "vertical",
+          "description": "Which scrollbars to offer. Defaults to vertical."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A bounded region (a list, a panel body) that scrolls inside a fixed height or width",
+        "whenNotToUse": "- The page itself: let the page scroll",
+        "example": "<div style={{ height: 240 }}>\n  <ScrollArea>{rows}</ScrollArea>\n</div>"
+      }
+    },
     {
       "name": "SearchField",
       "import": "import { SearchField } from '@ratio-ui/core'",
@@ -2145,6 +2863,155 @@
         }
       ]
     },
+    {
+      "name": "Separator",
+      "import": "import { Separator } from '@ratio-ui/core'",
+      "description": "A 1px hairline in the divider grey, horizontal or vertical. A horizontal line fills its row and shrinks to share it, so two lines and a word between them in an Inline make the \"or\" divider; a vertical line keeps its 1px.",
+      "props": [
+        {
+          "name": "orientation",
+          "type": "\"horizontal\" | \"vertical\"",
+          "required": false,
+          "default": "horizontal",
+          "description": "The direction of the line. Defaults to horizontal."
+        },
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "True, the default, hides the line from assistive technology; false makes it a semantic separator."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "description": "Receives the rendered element."
+        }
+      ],
+      "usage": {
+        "whenToUse": "- A hairline between groups of content, or the \"or\" divider on the login screen\n- A vertical hairline between inline items",
+        "whenNotToUse": "- A card or table edge: those own their border",
+        "example": "```tsx\n<Separator />\n<Inline gap={8}>\n  <Separator />\n  <Text variant=\"c1\" tone=\"muted\">or</Text>\n  <Separator />\n</Inline>\n<Separator orientation=\"vertical\" />\n<Separator decorative={false} />\n```\n\nIn the \"or\" divider the two lines share the row and the word keeps its width. Keep the word short: a longer phrase wraps before the lines give way."
+      }
+    },
+    {
+      "name": "Sheet",
+      "import": "import { Sheet } from '@ratio-ui/core'",
+      "description": "The root of a sheet. It holds the open state and renders nothing itself. Pass `open` and `onOpenChange` to control it, or `defaultOpen` to leave it uncontrolled. The page behind is inert while it is open, with no scrim over it.",
+      "props": [],
+      "usage": {
+        "whenToUse": "- A bottom sheet for a large surface that sits over the page, such as Settings: it spans the screen and has 24px top corners\n- A side sheet for a panel that keeps the page in view, such as filters or the phone navigation\n- Work that needs more room than a 480px dialog",
+        "whenNotToUse": "- A short task or a confirm step: use a Dialog\n- A panel people swipe away on a phone: use a Drawer\n- Help text on a control: use a Tooltip or Popover",
+        "example": "<Sheet>\n  <SheetTrigger>Settings</SheetTrigger>\n  <SheetContent side=\"bottom\" closeLabel=\"Close settings\">\n    <SheetHeader>\n      <SheetTitle>General</SheetTitle>\n      <SheetDescription>Store name, contact and address</SheetDescription>\n    </SheetHeader>\n    <SheetBody>Store details</SheetBody>\n    <SheetFooter>\n      <SheetClose>Done</SheetClose>\n    </SheetFooter>\n  </SheetContent>\n</Sheet>"
+      },
+      "parts": [
+        {
+          "name": "SheetBody",
+          "import": "import { SheetBody } from '@ratio-ui/core'",
+          "description": "The content between header and footer. It takes the free height and scrolls when the content is taller.",
+          "props": []
+        },
+        {
+          "name": "SheetClose",
+          "import": "import { SheetClose } from '@ratio-ui/core'",
+          "description": "A button that closes the sheet, such as Done in the footer.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, 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": "SheetContent",
+          "import": "import { SheetContent } from '@ratio-ui/core'",
+          "description": "The panel, white with a hairline on its inner edge. A side sheet is full height and three quarters of a phone screen, 384px from the small breakpoint up; a bottom sheet spans the screen, sizes to its content and has 24px top corners. It appears without sliding and with no scrim, blur or shadow. Put SheetHeader, SheetBody and SheetFooter inside.",
+          "props": [
+            {
+              "name": "side",
+              "type": "\"bottom\" | \"left\" | \"right\"",
+              "required": false,
+              "default": "right",
+              "description": "The edge the sheet sits on: a full-height side sheet, or a bottom sheet with 24px top corners. Defaults to right."
+            },
+            {
+              "name": "showCloseButton",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "Whether the corner close button shows. Defaults to true."
+            },
+            {
+              "name": "closeLabel",
+              "type": "string",
+              "required": false,
+              "default": "Close",
+              "description": "The accessible name of the corner close button. Defaults to Close."
+            },
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState>",
+              "required": false,
+              "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+            }
+          ]
+        },
+        {
+          "name": "SheetDescription",
+          "import": "import { SheetDescription } from '@ratio-ui/core'",
+          "description": "One line that says what the sheet is for, in subdued body text.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, 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": "SheetFooter",
+          "import": "import { SheetFooter } from '@ratio-ui/core'",
+          "description": "The row of actions at the bottom of the sheet, aligned to the end.",
+          "props": []
+        },
+        {
+          "name": "SheetHeader",
+          "import": "import { SheetHeader } from '@ratio-ui/core'",
+          "description": "The title and description, stacked, with room on the right for the close button.",
+          "props": []
+        },
+        {
+          "name": "SheetTitle",
+          "import": "import { SheetTitle } from '@ratio-ui/core'",
+          "description": "The sheet's name, in the b4 style. It names the sheet for assistive technology.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, 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": "SheetTrigger",
+          "import": "import { SheetTrigger } from '@ratio-ui/core'",
+          "description": "The button that opens the sheet.",
+          "props": [
+            {
+              "name": "render",
+              "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, 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": "SideNav",
       "import": "import { SideNav } from '@ratio-ui/core'",
@@ -2387,7 +3254,7 @@
         {
           "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.",
+          "description": "A column heading: 12px uppercase text in the muted foreground, the design system's colour for column headings. It is a column header unless `scope` says otherwise.",
           "props": [
             {
               "name": "numeric",
@@ -2646,7 +3513,7 @@
       "props": [
         {
           "name": "variant",
-          "type": "\"b1\" | \"b2\" | \"b3\" | \"b4\" | \"c1\" | \"c2\" | \"c3\" | \"display\" | \"h1\" | \"h5\" | \"label\" | \"s1\" | \"s2\"",
+          "type": "\"b1\" | \"b2\" | \"b3\" | \"b4\" | \"badge\" | \"c1\" | \"c2\" | \"c3\" | \"display\" | \"h1\" | \"h5\" | \"label\" | \"s1\" | \"s2\" | \"section\"",
           "required": false,
           "default": "b3",
           "description": "The text style: size, line height, weight and letter spacing. Defaults to b3, the body text."
@@ -2680,8 +3547,8 @@
         }
       ],
       "usage": {
-        "whenToUse": "- Any text on a screen: every label, heading, value and hint is set with Text, because components take no `className` and no `style`\n- A style from the design system's type scale: `variant` is one of display, h1, h5, s1, s2, b1, b2, b3, b4, c1, c2, c3 or label, and b3 is the default\n- A colour from the design system's text colours: `tone` is default, subdued, muted, primary or inherit\n- A heading, paragraph or list term that must look like another style: `as` picks the element (span, p, div, strong, em, h1 to h6, legend, dt or dd) and `variant` picks the look, so the two are chosen apart\n- A single line that is cut with an ellipsis: `truncate`, on a block element such as `as=\"p\"` or `as=\"div\"`",
-        "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",
+        "whenToUse": "- Any text on a screen: every label, heading, value and hint is set with Text, because components take no `className` and no `style`\n- A style from the design system's type scale: `variant` is one of display, h1, h5, s1, s2, b1, b2, b3, b4, c1, c2, c3, label, section or badge, and b3 is the default\n- A colour from the design system's text colours: `tone` is default, subdued, muted, primary or inherit\n- A heading, paragraph or list term that must look like another style: `as` picks the element (span, p, div, strong, em, h1 to h6, legend, dt or dd) and `variant` picks the look, so the two are chosen apart\n- A single line that is cut with an ellipsis: `truncate`, on a block element such as `as=\"p\"` or `as=\"div\"`",
+        "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 15\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>"
       }
     },
@@ -2743,7 +3610,7 @@
         {
           "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.",
+          "description": "The tooltip text: a white panel with a 1px line-100 border and ink-800 text, like a popover, no shadow and no animation. It sits above the trigger by default.",
           "props": [
             {
               "name": "render",
@@ -2783,14 +3650,7 @@
           "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."
+          "description": "The logo, usually the SVG the app gets from its designer. The bar draws no logo of its own: without one the slot is empty."
         },
         {
           "name": "menuLabel",