division-ds 0.9.1 → 0.11.0

package/AGENTS.md

@@ -51,7 +51,7 @@ installs these rules into that project's `AGENTS.md`, `GEMINI.md` and Cursor rul
 `.claude/skills/` (Claude Code).
 
 An agent that supports MCP can have the docs and the same checks as tools instead:
-`claude mcp add division-ds -- npx -y division-ds@0.8.0 mcp` (`list_components`, `get_component`,
+`claude mcp add division-ds -- npx -y division-ds@0.10.0 mcp` (`list_components`, `get_component`,
 `search`, `get_tokens`, `validate_code`, `check_contrast`, `get_add_command`,
 `get_review_checklist`, and two that report back: `request_change` and `report_drift`, which open
 an issue on the public repository instead of patching the installed copy).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "division-ds",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Checks a project that uses Division DS components (raw colours, invented tokens, touching buttons, unknown props), and serves the docs and the same checks to agents over MCP.",
   "license": "MIT",
   "author": "Victor Ilioiu",

package/public/docs/components/badge.md

@@ -20,7 +20,8 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `tone` | `'neutral' \| 'signal' \| 'ok' \| 'warning' \| 'hostile' \| 'info'` | `'neutral'` | The status the badge shows. Leave it out when you pass color. |
-| `color` | `'gray' \| 'brown' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'purple' \| 'pink' \| 'red'` |  | A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes. |
+| `color` | `'gray' \| 'brown' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'purple' \| 'pink' \| 'red'` |  | A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both, or passing it with severity. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes. |
+| `severity` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | A step on the ordered severity scale, from 1 (lowest) to 6, for a measure with more levels than the four status tones, like air quality from Good to Hazardous. The fill goes from green to maroon. It replaces tone and color: the types reject passing two. The steps are exported as SEVERITY_STEPS. The badge still needs the level's word: the step's colour is never the message on its own. Works with both emphases and both sizes. |
 | `emphasis` | `'solid' \| 'subtle'` | `'subtle'` | Solid uses the invariant fill (the same in light and dark themes) with its matching ink. Subtle is the outline badge: a 1px border and text in the tone’s theme-adaptive text token, with no fill. There's no separate outline emphasis, because it would be this same look under a second name. |
 | `size` | `'sm' \| 'md'` | `'sm'` | sm (small) is the chip for everyday interface: rows, cards, tables. md (medium) takes the small control height (32px) and the 14px text step. Use it for a badge next to display-size type, like a price. |
 | `dot` | `boolean` | `false` | Adds a marker next to the text. |
@@ -97,6 +98,30 @@ const TONES = ['neutral', 'signal', 'ok', 'warning', 'hostile', 'info'] as const
 ))}
 ```
 
+### Severity, solid: the six air quality levels, each with its word
+
+```tsx
+const AQI_LEVELS = ['Good', 'Moderate', 'Unhealthy for sensitive groups', 'Unhealthy', 'Very unhealthy', 'Hazardous'] as const
+
+{SEVERITY_STEPS.map(step => (
+  <Badge key={step} severity={step} emphasis="solid">
+    {AQI_LEVELS[step - 1]}
+  </Badge>
+))}
+```
+
+### Severity, subtle
+
+```tsx
+const AQI_LEVELS = ['Good', 'Moderate', 'Unhealthy for sensitive groups', 'Unhealthy', 'Very unhealthy', 'Hazardous'] as const
+
+{SEVERITY_STEPS.map(step => (
+  <Badge key={step} severity={step}>
+    {AQI_LEVELS[step - 1]}
+  </Badge>
+))}
+```
+
 ### With a dot
 
 ```tsx
@@ -192,6 +217,8 @@ Not focusable. No keyboard behaviour of its own.
 - Keep the tone mapping the same across the product. ok is never ‘in progress’ on one screen and ‘done’ on another.
 - Use size md when the badge sits next to a headline figure, so the two read as one statement.
 - Use tone for a status the system knows (paid, failed, syncing) and color for a label a person made (Design, Q3, Home). A colour on its own is not a status.
+- Use severity when a measure has more than four ordered levels, like air quality, so each level gets its own step and no two share a colour. Use the same step for the same level on every screen.
+- Prefer solid for a severity scale: the fills darken step by step in both themes, so the order reads at a glance. In the dark theme the subtle text steps are ordered by hue, not lightness.
 - Store the colour with the label, so it stays the same on every screen. Pick one from CATEGORY_COLORS when the label is created.
 
 ## Don't
@@ -200,6 +227,8 @@ Not focusable. No keyboard behaviour of its own.
 - Don't put a badge inside a button. It muddies what the clickable target is.
 - Don't use hostile for something that's only pending.
 - Don't use a category colour to show a status. A red project label is not an error, and an error is tone="hostile", so it means the same thing on every screen.
+- Don't squeeze a six-level scale into the four status tones. Two levels end up sharing a colour, and only the word tells them apart. That's what severity is for.
+- Don't use severity for a status that isn't on a scale. A failed payment is tone="hostile", not severity={5}.
 - Don't bevel it (give it a cut corner). At 22px a badge is chrome, the frame around content, not an object with its own footprint. Kbd follows the same rule for the same reason.
 - Don't resize a badge with height or text classes. The two sizes are the prop. A third size is a change to the system.
 - Don't use size md in a table row or on a card. It's as tall as a small button, so it starts to look like one.

package/public/docs/components/chart-panel.md

@@ -34,7 +34,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `centerLabel` | `string` |  | Donut only. The caption under the total in the centre of the ring. |
 | `formatValue` | `(value: number) => string` | `Intl.NumberFormat('en-IE')` | Formats numbers in the tooltip and the table. It formats the y-axis too, unless you give formatAxisValue. |
 | `formatAxisValue` | `(value: number) => string` | `formatValue` | Formats only the y-axis tick labels. Use a shorter, compact formatter when formatValue's output is too wide for the axis. SpendChart's compact euro formatter is one example. |
-| `axisWidth` | `number` | `48` | The width the y-axis reserves, in px (pixels). 48 is Recharts' own YAxis default. Make it bigger if formatAxisValue's labels still get cut off. |
+| `axisWidth` | `number` | `automatic` | An override for the width the y-axis reserves, in px (pixels). By default the axis sizes itself to its widest formatted tick label, never narrower than 48, so a currency symbol is never cut off. Set it only to line up the axes of several panels. |
 | `bands` | `{ from: string \| number; to: string \| number; label?: string }[]` | `[]` | Line and bar only. Shades stretches of the x-axis, such as night hours on a 24-hour chart. from and to are x-axis values (values of xKey), both included. When from comes after to in the data, the band wraps past the end: 22:00 to 06:00 shades 22:00 to the last point and the first point to 06:00. A band naming a value that isn't in the data is skipped. Every band is listed under the chart with its label, so screen readers hear it too. |
 | `limits` | `{ value: number; label?: string }[]` | `[]` | Line and bar only, not at size sm. Draws a dashed horizontal line at a y value, such as an alert limit of 35 µg/m³. The y-axis grows to include it, so a limit above every data point stays in view. Every limit is listed under the chart with its label and its value formatted by formatValue, so screen readers hear it too. |
 | `headingLevel` | `2 \| 3 \| 4` | `3` | Pick the level that fits the page's heading outline. |

package/public/docs/components/progress.md

@@ -2,7 +2,7 @@
 
 > A progress bar that's either determinate (it knows how far along the task is) or indeterminate (it doesn't). The readout is real text in the DOM (the Document Object Model, the live page structure the browser builds) from the very first render. That's motion token M3's rule, and it means a screen reader, the software that reads the page aloud for blind and low-vision people, never hears a number roll.
 
-- **Best for:** Showing how far a measurable task has got. Switch to indeterminate once you no longer know how much is left.
+- **Best for:** Showing how far a measurable task has got, or how much of a limit is used: set allowOverMax so a budget at 112% reads as over, not as 100%.
 - **Not for:** A wait with no measurable work. Use Spinner.
 - Atom. Source: `src/components/atoms/progress/Progress.tsx`
 - Rendered docs page: `/components/progress`
@@ -20,10 +20,12 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `string` |  | Required. The bar’s accessible name. |
-| `value` | `number \| null` |  | null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track. |
+| `value` | `number \| null` |  | null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track. Set allowOverMax to show a value above max as it is. |
 | `max` | `number` | `100` | The value at which the bar is complete. |
 | `showValue` | `boolean` | `false` | Shows the percentage (or "In progress") as a readout. |
 | `tone` | `'signal' \| 'ok' \| 'warning' \| 'hostile'` | `'signal'` | The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.80:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there. |
+| `allowOverMax` | `boolean` | `false` | Shows a value above max as it is instead of clamping it, for a budget at 112%. The track rescales to span the value, a marker shows where max sits, the part past it paints hostile, and the readout shows the real value (112%) in hostile. aria-valuenow is the real value, and aria-valuetext reads "112%, 12% over". |
+| `shape` | `'bar' \| 'ring'` | `'bar'` | ring draws a circular indicator with the readout in its centre and the label beneath, for a countdown or session timer. It takes the same value and max, It is not a live region, so a ticking timer stays quiet; announce milestones from your own status message. allowOverMax does not apply to it: the value is clamped. |
 | `className` | `string` |  | Merged with the outer wrapper’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system is styled with) win. |
 | `ref` | `Ref<HTMLDivElement>` |  | Passed through to the Radix Progress root, which is the bar itself. Radix is the library of accessible building blocks this component sits on. |
 | `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` |  | Every native div prop except children, spread onto the outer wrapper, so a molecule can attach a data-testid there. children is typed away because this component draws its own label row and track, and a children prop would be thrown away without any warning. |
@@ -75,6 +77,24 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 </div>
 ```
 
+### Over the limit
+
+```tsx
+<div className="flex flex-col gap-4 w-full max-w-sm">
+  <Progress label="Groceries" value={64} tone="ok" allowOverMax showValue />
+  <Progress label="Eating out" value={112} tone="ok" allowOverMax showValue />
+</div>
+```
+
+### Ring
+
+```tsx
+<div className="flex gap-6">
+  <Progress shape="ring" label="Focus session" value={18} max={25} showValue />
+  <Progress shape="ring" label="Break" value={2} max={5} tone="ok" showValue />
+</div>
+```
+
 ## Keyboard
 
 Not focusable. No keyboard behaviour of its own.
@@ -90,6 +110,7 @@ Not focusable. No keyboard behaviour of its own.
 - Don't animate the number up from zero and call that animated value the readout. The real value belongs in the DOM straight away.
 - Don't use Progress for a wait with no measurable work. That's a Spinner.
 - Don't put the padded readout into the accessible name. That's exactly why the pad is a separate aria-hidden span, and label is what Radix announces.
+- Don't leave allowOverMax off on a spend-against-limit bar. Clamped, an overspent category reads as exactly on budget.
 - Don't rely on the tone alone to say something failed. Say it in text.
 
 ## Anatomy

package/public/docs/components/select.md

@@ -2,7 +2,7 @@
 
 > A single choice from a list, shown in a portalled listbox (a pop-up list rendered at the top level of the page, so nothing around it can clip it). Options come in as an array instead of as children, because the trigger, the panel and the look of each row are decisions the system makes once, not per use.
 
-- **Best for:** One choice from a list of about five options or more.
+- **Best for:** One choice from a list of about five options or more: a country, a time zone, a currency.
 - **Not for:** Several values: use MultiSelect. Fewer than about five options: use Radio.
 - Atom. Source: `src/components/atoms/select/Select.tsx`
 - Rendered docs page: `/components/select`
@@ -35,6 +35,7 @@ Paths are from the Division DS repository root. Installed with shadcn they start
 | `name` | `string` |  | The form field name, for native form submission. |
 | `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches Input’s sizes so the two line up. |
 | `invalid` | `boolean` | `false` | Sets aria-invalid, which tells assistive tech the field has an error, and shows the invalid border. |
+| `iconInTrigger` | `boolean` | `false` | Repeats the chosen row’s icon in the trigger, before its label, still aria-hidden. For icons people recognise the option by, such as a country’s flag; leave it off for decorative ones. |
 | `className` | `string` |  | Merged with the trigger’s classes. Later Tailwind utilities (Tailwind is the CSS framework the system uses) win. |
 | `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the trigger button. |
 | `id` | `string` |  | The trigger’s id. FormField sets it. |
@@ -51,17 +52,17 @@ export type SelectOption = { value: string; label: string; disabled?: boolean }
 ```
 
 ```ts
-/** A Select row: a `SelectOption` plus an optional leading icon. Kept as its own type rather than
- *  an `icon` field on `SelectOption`, because MultiSelect takes `SelectOption[]` too and renders
- *  no icons: widening the shared type would let an icon compile there and vanish. */
-export type SelectOptionWithIcon = SelectOption & {
-  /** Leading glyph, aria-hidden: the label names the row. Not repeated in the trigger. */
-  icon?: ReactNode
+/** A Select row: a `SelectOption` plus an optional leading icon. Kept as its own type rather than
+ *  an `icon` field on `SelectOption`, because MultiSelect takes `SelectOption[]` too and renders
+ *  no icons: widening the shared type would let an icon compile there and vanish. */
+export type SelectOptionWithIcon = SelectOption & {
+  /** Leading glyph, aria-hidden: the label names the row. Shown in the trigger only with `iconInTrigger`. */
+  icon?: ReactNode
 }
 ```
 
 ```ts
-/** A titled run of rows. The heading is not selectable; it names the group for screen readers. */
+/** A titled run of rows. The heading is not selectable; it names the group for screen readers. */
 export type SelectGroup = { label: string; options: SelectOptionWithIcon[] }
 ```
 
@@ -72,10 +73,10 @@ Each is compiled and rendered on the docs page. Imports are omitted; see above.
 ### Placeholder
 
 ```tsx
-const SPEED_OPTIONS = [
-  { value: 'standard', label: 'Standard' },
-  { value: 'priority', label: 'Priority' },
-  { value: 'overnight', label: 'Overnight', disabled: true },
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
 ]
 
 <Select label="Dispatch speed" options={SPEED_OPTIONS} placeholder="Choose a speed" />
@@ -84,10 +85,10 @@ const SPEED_OPTIONS = [
 ### With a value
 
 ```tsx
-const SPEED_OPTIONS = [
-  { value: 'standard', label: 'Standard' },
-  { value: 'priority', label: 'Priority' },
-  { value: 'overnight', label: 'Overnight', disabled: true },
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
 ]
 
 <Select label="Dispatch speed" options={SPEED_OPTIONS} defaultValue="priority" />
@@ -96,33 +97,76 @@ const SPEED_OPTIONS = [
 ### Groups with headings and icons
 
 ```tsx
-const DELIVERY_GROUPS: SelectGroup[] = [
-  {
-    label: 'Courier',
-    options: [
-      { value: 'standard', label: 'Standard', icon: <Truck /> },
-      { value: 'priority', label: 'Priority', icon: <Zap /> },
-    ],
-  },
-  {
-    label: 'Collect',
-    options: [
-      { value: 'depot', label: 'Brasov depot', icon: <Package /> },
-      { value: 'field', label: 'At the field', icon: <Crosshair /> },
-    ],
-  },
+const DELIVERY_GROUPS: SelectGroup[] = [
+  {
+    label: 'Courier',
+    options: [
+      { value: 'standard', label: 'Standard', icon: <Truck /> },
+      { value: 'priority', label: 'Priority', icon: <Zap /> },
+    ],
+  },
+  {
+    label: 'Collect',
+    options: [
+      { value: 'depot', label: 'Brasov depot', icon: <Package /> },
+      { value: 'field', label: 'At the field', icon: <Crosshair /> },
+    ],
+  },
 ]
 
 <Select label="Delivery" groups={DELIVERY_GROUPS} placeholder="Choose delivery" />
 ```
 
+### Countries
+
+```tsx
+type Stripes = { dir: 'v' | 'h'; colors: string[] }
+
+const FLAGS: Record<string, Stripes> = {
+  at: { dir: 'h', colors: ['#c8102e', '#ffffff', '#c8102e'] }, // token-discipline: allow, Austria's flag colours, not interface colour
+  be: { dir: 'v', colors: ['#000000', '#fdda24', '#ef3340'] }, // token-discipline: allow, Belgium's flag colours, not interface colour
+  de: { dir: 'h', colors: ['#000000', '#dd0000', '#ffce00'] }, // token-discipline: allow, Germany's flag colours, not interface colour
+  es: { dir: 'h', colors: ['#aa151b', '#f1bf00', '#f1bf00', '#aa151b'] }, // token-discipline: allow, Spain's flag colours, not interface colour
+  fr: { dir: 'v', colors: ['#0055a4', '#ffffff', '#ef4135'] }, // token-discipline: allow, France's flag colours, not interface colour
+  ie: { dir: 'v', colors: ['#169b62', '#ffffff', '#ff883e'] }, // token-discipline: allow, Ireland's flag colours, not interface colour
+  it: { dir: 'v', colors: ['#009246', '#ffffff', '#ce2b37'] }, // token-discipline: allow, Italy's flag colours, not interface colour
+  nl: { dir: 'h', colors: ['#ae1c28', '#ffffff', '#21468b'] }, // token-discipline: allow, the Netherlands' flag colours, not interface colour
+  pl: { dir: 'h', colors: ['#ffffff', '#dc143c'] }, // token-discipline: allow, Poland's flag colours, not interface colour
+  ro: { dir: 'v', colors: ['#002b7f', '#fcd116', '#ce1126'] }, // token-discipline: allow, Romania's flag colours, not interface colour
+}
+
+function Flag({ code }: { code: string }) {
+  const { dir, colors } = FLAGS[code]
+  const n = colors.length
+  return (
+    <svg viewBox="0 0 20 14" style={{ width: 20, height: 14 }} className="block">
+      {colors.map((fill, i) =>
+        dir === 'v' ? (
+          <rect key={i} x={(20 / n) * i} y={0} width={20 / n} height={14} fill={fill} />
+        ) : (
+          <rect key={i} x={0} y={(14 / n) * i} width={20} height={14 / n} fill={fill} />
+        )
+      )}
+      <rect x={0.5} y={0.5} width={19} height={13} fill="none" stroke="var(--color-border-hairline-strong)" />
+    </svg>
+  )
+}
+
+const COUNTRY_OPTIONS = [
+  ['at', 'Austria'], ['be', 'Belgium'], ['fr', 'France'], ['de', 'Germany'], ['ie', 'Ireland'],
+  ['it', 'Italy'], ['nl', 'Netherlands'], ['pl', 'Poland'], ['ro', 'Romania'], ['es', 'Spain'],
+].map(([value, label]) => ({ value, label, icon: <Flag code={value} /> }))
+
+<Select label="Country" options={COUNTRY_OPTIONS} iconInTrigger defaultValue="ro" />
+```
+
 ### Long list
 
 ```tsx
-const MONTH_OPTIONS = Array.from({ length: 30 }, (_, i) => {
-  const date = new Date(Date.UTC(2026, 10 - i, 1))
-  const label = date.toLocaleDateString('en-GB', { month: 'long', year: 'numeric', timeZone: 'UTC' })
-  return { value: date.toISOString().slice(0, 7), label }
+const MONTH_OPTIONS = Array.from({ length: 30 }, (_, i) => {
+  const date = new Date(Date.UTC(2026, 10 - i, 1))
+  const label = date.toLocaleDateString('en-GB', { month: 'long', year: 'numeric', timeZone: 'UTC' })
+  return { value: date.toISOString().slice(0, 7), label }
 })
 
 <Select label="Billing month" options={MONTH_OPTIONS} placeholder="Choose a month" />
@@ -131,25 +175,25 @@ const MONTH_OPTIONS = Array.from({ length: 30 }, (_, i) => {
 ### Sizes
 
 ```tsx
-const TERRAIN_OPTIONS = [
-  { value: 'woodland', label: 'Woodland' },
-  { value: 'urban', label: 'Urban' },
-  { value: 'desert', label: 'Desert' },
-  { value: 'indoor', label: 'Indoor' },
+const TERRAIN_OPTIONS = [
+  { value: 'woodland', label: 'Woodland' },
+  { value: 'urban', label: 'Urban' },
+  { value: 'desert', label: 'Desert' },
+  { value: 'indoor', label: 'Indoor' },
 ]
 
-<Select label="Terrain (small)" inputSize="sm" options={TERRAIN_OPTIONS} placeholder="Terrain" />
-<Select label="Terrain (medium)" inputSize="md" options={TERRAIN_OPTIONS} placeholder="Terrain" />
+<Select label="Terrain (small)" inputSize="sm" options={TERRAIN_OPTIONS} placeholder="Terrain" />
+<Select label="Terrain (medium)" inputSize="md" options={TERRAIN_OPTIONS} placeholder="Terrain" />
 <Select label="Terrain (large)" inputSize="lg" options={TERRAIN_OPTIONS} placeholder="Terrain" />
 ```
 
 ### Disabled control
 
 ```tsx
-const SPEED_OPTIONS = [
-  { value: 'standard', label: 'Standard' },
-  { value: 'priority', label: 'Priority' },
-  { value: 'overnight', label: 'Overnight', disabled: true },
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
 ]
 
 <Select label="Dispatch speed, unavailable" options={SPEED_OPTIONS} defaultValue="standard" disabled />
@@ -158,10 +202,10 @@ const SPEED_OPTIONS = [
 ### Invalid
 
 ```tsx
-const SPEED_OPTIONS = [
-  { value: 'standard', label: 'Standard' },
-  { value: 'priority', label: 'Priority' },
-  { value: 'overnight', label: 'Overnight', disabled: true },
+const SPEED_OPTIONS = [
+  { value: 'standard', label: 'Standard' },
+  { value: 'priority', label: 'Priority' },
+  { value: 'overnight', label: 'Overnight', disabled: true },
 ]
 
 <Select label="Dispatch speed" options={SPEED_OPTIONS} invalid placeholder="Choose a speed" />
@@ -170,26 +214,26 @@ const SPEED_OPTIONS = [
 ### Beside an Input
 
 ```tsx
-const TERRAIN_OPTIONS = [
-  { value: 'woodland', label: 'Woodland' },
-  { value: 'urban', label: 'Urban' },
-  { value: 'desert', label: 'Desert' },
-  { value: 'indoor', label: 'Indoor' },
+const TERRAIN_OPTIONS = [
+  { value: 'woodland', label: 'Woodland' },
+  { value: 'urban', label: 'Urban' },
+  { value: 'desert', label: 'Desert' },
+  { value: 'indoor', label: 'Indoor' },
 ]
 
-<label className="flex flex-col gap-1 text-sm">
-  Call sign
-  <Input placeholder="Anvil-3" />
-</label>
-{/* Deliberately NOT a <label>. A <label> associates with a labelable element — input,
-    select, textarea, button among them — but Radix's trigger is a <button>, and a
-    <label> wrapping a button is inert: it neither names it nor forwards a click. The
-    Select's accessible name comes from its required `label` prop, and the visible text
-    here matches it exactly (SC 2.5.3, label in name). Wrapping it in a <label> would
-    have looked correct and done nothing. */}
-<div className="flex flex-col gap-1 text-sm">
-  <span>Terrain</span>
-  <Select label="Terrain" options={TERRAIN_OPTIONS} placeholder="Choose terrain" />
+<label className="flex flex-col gap-1 text-sm">
+  Call sign
+  <Input placeholder="Anvil-3" />
+</label>
+{/* Deliberately NOT a <label>. A <label> associates with a labelable element — input,
+    select, textarea, button among them — but Radix's trigger is a <button>, and a
+    <label> wrapping a button is inert: it neither names it nor forwards a click. The
+    Select's accessible name comes from its required `label` prop, and the visible text
+    here matches it exactly (SC 2.5.3, label in name). Wrapping it in a <label> would
+    have looked correct and done nothing. */}
+<div className="flex flex-col gap-1 text-sm">
+  <span>Terrain</span>
+  <Select label="Terrain" options={TERRAIN_OPTIONS} placeholder="Choose terrain" />
 </div>
 ```
 
@@ -213,6 +257,7 @@ const TERRAIN_OPTIONS = [
 - Below about five options, use radios instead.
 - Group rows under headings once the list mixes different kinds of thing, and keep each group to a handful.
 - Give every row an icon, or none of them.
+- Set iconInTrigger when the icon is how people recognise the option, such as a flag in a country list.
 - Wrap it in a FormField for a visible label, help and error. FormField hands it the label.
 
 ## Don't
@@ -220,6 +265,7 @@ const TERRAIN_OPTIONS = [
 - Don't build a searchable select out of this. That's the command palette's job.
 - Don't use it for several values. That's MultiSelect, which shows each choice as a removable tag.
 - Don't put more than a couple of dozen options in it without search.
+- Don't use emoji flags. Windows draws them as letter pairs such as RO; pass a small image or SVG as the icon instead.
 - Don't make a group of one. A heading over a single row is just noise.
 - Don't style the trigger differently from Input. A form with mismatched control heights looks broken.
 - Don't bevel the trigger. It shares Input's frame and draws its own focus ring (the outline that shows which control the keyboard is on), and a cut corner would clip it. The listbox carries the crosshair instead: the shape lives on the surface, not on the control.
@@ -232,5 +278,5 @@ const TERRAIN_OPTIONS = [
 - **Content**: Portalled and positioned by Radix, the library of accessible building blocks this sits on. It slides down out of the trigger as it opens (M7; Radix’s Select closes at once, with no exit animation). It’s the one atom that carries the corner crosshair, because it’s a surface framing other content, and that’s what the crosshair marks. It’s also the shape that can’t be cut, since clip-path would clip the crosshair’s arms and the last row’s selection fill along with them.
 - **Item**: Highlighted rows use accent.signal.indicator with accent.signal.indicator-ink. That’s the fill-selection grammar, the system’s rule for how a selection looks.
 - **ItemIndicator**: A tick on the selected row, so selection isn’t shown by the highlight alone.
-- **Item icon**: Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger.
+- **Item icon**: Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger unless iconInTrigger is set.
 - **Group label**: Used with groups: a mono (monospaced font) heading over its rows that names the group for screen readers. It can’t be selected. A hairline separates the groups.

package/public/manifest/components.json

@@ -290,7 +290,12 @@
         {
           "name": "color",
           "type": "'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'purple' | 'pink' | 'red'",
-          "description": "A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes."
+          "description": "A category colour for a label people make themselves, like a project tag or a topic. It replaces tone: the types reject passing both, or passing it with severity. A category colour means 'these belong together', never good or bad. The list is exported as CATEGORY_COLORS, so an app can give each new label one at random. Works with both emphases and both sizes."
+        },
+        {
+          "name": "severity",
+          "type": "1 | 2 | 3 | 4 | 5 | 6",
+          "description": "A step on the ordered severity scale, from 1 (lowest) to 6, for a measure with more levels than the four status tones, like air quality from Good to Hazardous. The fill goes from green to maroon. It replaces tone and color: the types reject passing two. The steps are exported as SEVERITY_STEPS. The badge still needs the level's word: the step's colour is never the message on its own. Works with both emphases and both sizes."
         },
         {
           "name": "emphasis",
@@ -358,6 +363,8 @@
         "Keep the tone mapping the same across the product. ok is never ‘in progress’ on one screen and ‘done’ on another.",
         "Use size md when the badge sits next to a headline figure, so the two read as one statement.",
         "Use tone for a status the system knows (paid, failed, syncing) and color for a label a person made (Design, Q3, Home). A colour on its own is not a status.",
+        "Use severity when a measure has more than four ordered levels, like air quality, so each level gets its own step and no two share a colour. Use the same step for the same level on every screen.",
+        "Prefer solid for a severity scale: the fills darken step by step in both themes, so the order reads at a glance. In the dark theme the subtle text steps are ordered by hue, not lightness.",
         "Store the colour with the label, so it stays the same on every screen. Pick one from CATEGORY_COLORS when the label is created."
       ],
       "donts": [
@@ -365,6 +372,8 @@
         "Don't put a badge inside a button. It muddies what the clickable target is.",
         "Don't use hostile for something that's only pending.",
         "Don't use a category colour to show a status. A red project label is not an error, and an error is tone=\"hostile\", so it means the same thing on every screen.",
+        "Don't squeeze a six-level scale into the four status tones. Two levels end up sharing a colour, and only the word tells them apart. That's what severity is for.",
+        "Don't use severity for a status that isn't on a scale. A failed payment is tone=\"hostile\", not severity={5}.",
         "Don't bevel it (give it a cut corner). At 22px a badge is chrome, the frame around content, not an object with its own footprint. Kbd follows the same rule for the same reason.",
         "Don't resize a badge with height or text classes. The two sizes are the prop. A third size is a change to the system.",
         "Don't use size md in a table row or on a card. It's as tall as a small button, so it starts to look like one.",
@@ -406,6 +415,14 @@
           "caption": "Category colours, solid",
           "source": "{CATEGORY_COLORS.map(color => (\n  <Badge key={color} color={color} emphasis=\"solid\">\n    {color}\n  </Badge>\n))}"
         },
+        {
+          "caption": "Severity, solid: the six air quality levels, each with its word",
+          "source": "const AQI_LEVELS = ['Good', 'Moderate', 'Unhealthy for sensitive groups', 'Unhealthy', 'Very unhealthy', 'Hazardous'] as const\n\n{SEVERITY_STEPS.map(step => (\n  <Badge key={step} severity={step} emphasis=\"solid\">\n    {AQI_LEVELS[step - 1]}\n  </Badge>\n))}"
+        },
+        {
+          "caption": "Severity, subtle",
+          "source": "const AQI_LEVELS = ['Good', 'Moderate', 'Unhealthy for sensitive groups', 'Unhealthy', 'Very unhealthy', 'Hazardous'] as const\n\n{SEVERITY_STEPS.map(step => (\n  <Badge key={step} severity={step}>\n    {AQI_LEVELS[step - 1]}\n  </Badge>\n))}"
+        },
         {
           "caption": "With a dot",
           "source": "<Badge tone=\"ok\" dot>\n  Nominal\n</Badge>\n<Badge tone=\"warning\" dot>\n  Degraded\n</Badge>\n<Badge tone=\"hostile\" dot>\n  Offline\n</Badge>"
@@ -1719,7 +1736,7 @@
       "tier": "atoms",
       "slug": "progress",
       "summary": "A progress bar that's either determinate (it knows how far along the task is) or indeterminate (it doesn't). The readout is real text in the DOM (the Document Object Model, the live page structure the browser builds) from the very first render. That's motion token M3's rule, and it means a screen reader, the software that reads the page aloud for blind and low-vision people, never hears a number roll.",
-      "useWhen": "Showing how far a measurable task has got. Switch to indeterminate once you no longer know how much is left.",
+      "useWhen": "Showing how far a measurable task has got, or how much of a limit is used: set allowOverMax so a budget at 112% reads as over, not as 100%.",
       "notFor": "A wait with no measurable work. Use Spinner.",
       "source": "src/components/atoms/progress/Progress.tsx",
       "docs": "/docs/components/progress.md",
@@ -1740,7 +1757,7 @@
         {
           "name": "value",
           "type": "number | null",
-          "description": "null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track."
+          "description": "null means indeterminate. The value is clamped to [0, max], so an out-of-range value shows as complete instead of overflowing the track. Set allowOverMax to show a value above max as it is."
         },
         {
           "name": "max",
@@ -1760,6 +1777,18 @@
           "default": "'signal'",
           "description": "The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.80:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there."
         },
+        {
+          "name": "allowOverMax",
+          "type": "boolean",
+          "default": "false",
+          "description": "Shows a value above max as it is instead of clamping it, for a budget at 112%. The track rescales to span the value, a marker shows where max sits, the part past it paints hostile, and the readout shows the real value (112%) in hostile. aria-valuenow is the real value, and aria-valuetext reads \"112%, 12% over\"."
+        },
+        {
+          "name": "shape",
+          "type": "'bar' | 'ring'",
+          "default": "'bar'",
+          "description": "ring draws a circular indicator with the readout in its centre and the label beneath, for a countdown or session timer. It takes the same value and max, It is not a live region, so a ticking timer stays quiet; announce milestones from your own status message. allowOverMax does not apply to it: the value is clamped."
+        },
         {
           "name": "className",
           "type": "string",
@@ -1786,6 +1815,7 @@
         "Don't animate the number up from zero and call that animated value the readout. The real value belongs in the DOM straight away.",
         "Don't use Progress for a wait with no measurable work. That's a Spinner.",
         "Don't put the padded readout into the accessible name. That's exactly why the pad is a separate aria-hidden span, and label is what Radix announces.",
+        "Don't leave allowOverMax off on a spend-against-limit bar. Clamped, an overspent category reads as exactly on budget.",
         "Don't rely on the tone alone to say something failed. Say it in text."
       ],
       "anatomy": [
@@ -1830,6 +1860,14 @@
         {
           "caption": "Tones",
           "source": "<div className=\"flex flex-col gap-4 w-full max-w-sm\">\n  <Progress label=\"Signal supply run\" value={40} tone=\"signal\" showValue />\n  <Progress label=\"BB reserves\" value={82} tone=\"ok\" showValue />\n  <Progress label=\"Gas reserves\" value={22} tone=\"warning\" showValue />\n  <Progress label=\"Battery reserves\" value={6} tone=\"hostile\" showValue />\n</div>"
+        },
+        {
+          "caption": "Over the limit",
+          "source": "<div className=\"flex flex-col gap-4 w-full max-w-sm\">\n  <Progress label=\"Groceries\" value={64} tone=\"ok\" allowOverMax showValue />\n  <Progress label=\"Eating out\" value={112} tone=\"ok\" allowOverMax showValue />\n</div>"
+        },
+        {
+          "caption": "Ring",
+          "source": "<div className=\"flex gap-6\">\n  <Progress shape=\"ring\" label=\"Focus session\" value={18} max={25} showValue />\n  <Progress shape=\"ring\" label=\"Break\" value={2} max={5} tone=\"ok\" showValue />\n</div>"
         }
       ],
       "closed": false
@@ -2135,7 +2173,7 @@
       "tier": "atoms",
       "slug": "select",
       "summary": "A single choice from a list, shown in a portalled listbox (a pop-up list rendered at the top level of the page, so nothing around it can clip it). Options come in as an array instead of as children, because the trigger, the panel and the look of each row are decisions the system makes once, not per use.",
-      "useWhen": "One choice from a list of about five options or more.",
+      "useWhen": "One choice from a list of about five options or more: a country, a time zone, a currency.",
       "notFor": "Several values: use MultiSelect. Fewer than about five options: use Radio.",
       "source": "src/components/atoms/select/Select.tsx",
       "docs": "/docs/components/select.md",
@@ -2214,6 +2252,12 @@
           "default": "false",
           "description": "Sets aria-invalid, which tells assistive tech the field has an error, and shows the invalid border."
         },
+        {
+          "name": "iconInTrigger",
+          "type": "boolean",
+          "default": "false",
+          "description": "Repeats the chosen row’s icon in the trigger, before its label, still aria-hidden. For icons people recognise the option by, such as a country’s flag; leave it off for decorative ones."
+        },
         {
           "name": "className",
           "type": "string",
@@ -2255,13 +2299,13 @@
         {
           "name": "SelectOptionWithIcon",
           "kind": "type",
-          "code": "/** A Select row: a `SelectOption` plus an optional leading icon. Kept as its own type rather than\n *  an `icon` field on `SelectOption`, because MultiSelect takes `SelectOption[]` too and renders\n *  no icons: widening the shared type would let an icon compile there and vanish. */\nexport type SelectOptionWithIcon = SelectOption & {\n  /** Leading glyph, aria-hidden: the label names the row. Not repeated in the trigger. */\n  icon?: ReactNode\n}",
+          "code": "/** A Select row: a `SelectOption` plus an optional leading icon. Kept as its own type rather than\r\n *  an `icon` field on `SelectOption`, because MultiSelect takes `SelectOption[]` too and renders\r\n *  no icons: widening the shared type would let an icon compile there and vanish. */\r\nexport type SelectOptionWithIcon = SelectOption & {\r\n  /** Leading glyph, aria-hidden: the label names the row. Shown in the trigger only with `iconInTrigger`. */\r\n  icon?: ReactNode\r\n}",
           "from": "src/components/atoms/select/Select"
         },
         {
           "name": "SelectGroup",
           "kind": "type",
-          "code": "/** A titled run of rows. The heading is not selectable; it names the group for screen readers. */\nexport type SelectGroup = { label: string; options: SelectOptionWithIcon[] }",
+          "code": "/** A titled run of rows. The heading is not selectable; it names the group for screen readers. */\r\nexport type SelectGroup = { label: string; options: SelectOptionWithIcon[] }",
           "from": "src/components/atoms/select/Select"
         }
       ],
@@ -2319,12 +2363,14 @@
         "Below about five options, use radios instead.",
         "Group rows under headings once the list mixes different kinds of thing, and keep each group to a handful.",
         "Give every row an icon, or none of them.",
+        "Set iconInTrigger when the icon is how people recognise the option, such as a flag in a country list.",
         "Wrap it in a FormField for a visible label, help and error. FormField hands it the label."
       ],
       "donts": [
         "Don't build a searchable select out of this. That's the command palette's job.",
         "Don't use it for several values. That's MultiSelect, which shows each choice as a removable tag.",
         "Don't put more than a couple of dozen options in it without search.",
+        "Don't use emoji flags. Windows draws them as letter pairs such as RO; pass a small image or SVG as the icon instead.",
         "Don't make a group of one. A heading over a single row is just noise.",
         "Don't style the trigger differently from Input. A form with mismatched control heights looks broken.",
         "Don't bevel the trigger. It shares Input's frame and draws its own focus ring (the outline that shows which control the keyboard is on), and a cut corner would clip it. The listbox carries the crosshair instead: the shape lives on the surface, not on the control.",
@@ -2353,7 +2399,7 @@
         },
         {
           "part": "Item icon",
-          "description": "Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger."
+          "description": "Optional. Sits before the label and is aria-hidden, an ARIA (Accessible Rich Internet Applications) attribute that hides it from assistive tech. It follows the row colour, so it turns ink on the highlight. It isn’t shown in the trigger unless iconInTrigger is set."
         },
         {
           "part": "Group label",
@@ -2363,35 +2409,39 @@
       "examples": [
         {
           "caption": "Placeholder",
-          "source": "const SPEED_OPTIONS = [\n  { value: 'standard', label: 'Standard' },\n  { value: 'priority', label: 'Priority' },\n  { value: 'overnight', label: 'Overnight', disabled: true },\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} placeholder=\"Choose a speed\" />"
+          "source": "const SPEED_OPTIONS = [\r\n  { value: 'standard', label: 'Standard' },\r\n  { value: 'priority', label: 'Priority' },\r\n  { value: 'overnight', label: 'Overnight', disabled: true },\r\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} placeholder=\"Choose a speed\" />"
         },
         {
           "caption": "With a value",
-          "source": "const SPEED_OPTIONS = [\n  { value: 'standard', label: 'Standard' },\n  { value: 'priority', label: 'Priority' },\n  { value: 'overnight', label: 'Overnight', disabled: true },\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} defaultValue=\"priority\" />"
+          "source": "const SPEED_OPTIONS = [\r\n  { value: 'standard', label: 'Standard' },\r\n  { value: 'priority', label: 'Priority' },\r\n  { value: 'overnight', label: 'Overnight', disabled: true },\r\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} defaultValue=\"priority\" />"
         },
         {
           "caption": "Groups with headings and icons",
-          "source": "const DELIVERY_GROUPS: SelectGroup[] = [\n  {\n    label: 'Courier',\n    options: [\n      { value: 'standard', label: 'Standard', icon: <Truck /> },\n      { value: 'priority', label: 'Priority', icon: <Zap /> },\n    ],\n  },\n  {\n    label: 'Collect',\n    options: [\n      { value: 'depot', label: 'Brasov depot', icon: <Package /> },\n      { value: 'field', label: 'At the field', icon: <Crosshair /> },\n    ],\n  },\n]\n\n<Select label=\"Delivery\" groups={DELIVERY_GROUPS} placeholder=\"Choose delivery\" />"
+          "source": "const DELIVERY_GROUPS: SelectGroup[] = [\r\n  {\r\n    label: 'Courier',\r\n    options: [\r\n      { value: 'standard', label: 'Standard', icon: <Truck /> },\r\n      { value: 'priority', label: 'Priority', icon: <Zap /> },\r\n    ],\r\n  },\r\n  {\r\n    label: 'Collect',\r\n    options: [\r\n      { value: 'depot', label: 'Brasov depot', icon: <Package /> },\r\n      { value: 'field', label: 'At the field', icon: <Crosshair /> },\r\n    ],\r\n  },\r\n]\n\n<Select label=\"Delivery\" groups={DELIVERY_GROUPS} placeholder=\"Choose delivery\" />"
+        },
+        {
+          "caption": "Countries",
+          "source": "type Stripes = { dir: 'v' | 'h'; colors: string[] }\n\nconst FLAGS: Record<string, Stripes> = {\r\n  at: { dir: 'h', colors: ['#c8102e', '#ffffff', '#c8102e'] }, // token-discipline: allow, Austria's flag colours, not interface colour\r\n  be: { dir: 'v', colors: ['#000000', '#fdda24', '#ef3340'] }, // token-discipline: allow, Belgium's flag colours, not interface colour\r\n  de: { dir: 'h', colors: ['#000000', '#dd0000', '#ffce00'] }, // token-discipline: allow, Germany's flag colours, not interface colour\r\n  es: { dir: 'h', colors: ['#aa151b', '#f1bf00', '#f1bf00', '#aa151b'] }, // token-discipline: allow, Spain's flag colours, not interface colour\r\n  fr: { dir: 'v', colors: ['#0055a4', '#ffffff', '#ef4135'] }, // token-discipline: allow, France's flag colours, not interface colour\r\n  ie: { dir: 'v', colors: ['#169b62', '#ffffff', '#ff883e'] }, // token-discipline: allow, Ireland's flag colours, not interface colour\r\n  it: { dir: 'v', colors: ['#009246', '#ffffff', '#ce2b37'] }, // token-discipline: allow, Italy's flag colours, not interface colour\r\n  nl: { dir: 'h', colors: ['#ae1c28', '#ffffff', '#21468b'] }, // token-discipline: allow, the Netherlands' flag colours, not interface colour\r\n  pl: { dir: 'h', colors: ['#ffffff', '#dc143c'] }, // token-discipline: allow, Poland's flag colours, not interface colour\r\n  ro: { dir: 'v', colors: ['#002b7f', '#fcd116', '#ce1126'] }, // token-discipline: allow, Romania's flag colours, not interface colour\r\n}\n\nfunction Flag({ code }: { code: string }) {\r\n  const { dir, colors } = FLAGS[code]\r\n  const n = colors.length\r\n  return (\r\n    <svg viewBox=\"0 0 20 14\" style={{ width: 20, height: 14 }} className=\"block\">\r\n      {colors.map((fill, i) =>\r\n        dir === 'v' ? (\r\n          <rect key={i} x={(20 / n) * i} y={0} width={20 / n} height={14} fill={fill} />\r\n        ) : (\r\n          <rect key={i} x={0} y={(14 / n) * i} width={20} height={14 / n} fill={fill} />\r\n        )\r\n      )}\r\n      <rect x={0.5} y={0.5} width={19} height={13} fill=\"none\" stroke=\"var(--color-border-hairline-strong)\" />\r\n    </svg>\r\n  )\r\n}\n\nconst COUNTRY_OPTIONS = [\r\n  ['at', 'Austria'], ['be', 'Belgium'], ['fr', 'France'], ['de', 'Germany'], ['ie', 'Ireland'],\r\n  ['it', 'Italy'], ['nl', 'Netherlands'], ['pl', 'Poland'], ['ro', 'Romania'], ['es', 'Spain'],\r\n].map(([value, label]) => ({ value, label, icon: <Flag code={value} /> }))\n\n<Select label=\"Country\" options={COUNTRY_OPTIONS} iconInTrigger defaultValue=\"ro\" />"
         },
         {
           "caption": "Long list",
-          "source": "const MONTH_OPTIONS = Array.from({ length: 30 }, (_, i) => {\n  const date = new Date(Date.UTC(2026, 10 - i, 1))\n  const label = date.toLocaleDateString('en-GB', { month: 'long', year: 'numeric', timeZone: 'UTC' })\n  return { value: date.toISOString().slice(0, 7), label }\n})\n\n<Select label=\"Billing month\" options={MONTH_OPTIONS} placeholder=\"Choose a month\" />"
+          "source": "const MONTH_OPTIONS = Array.from({ length: 30 }, (_, i) => {\r\n  const date = new Date(Date.UTC(2026, 10 - i, 1))\r\n  const label = date.toLocaleDateString('en-GB', { month: 'long', year: 'numeric', timeZone: 'UTC' })\r\n  return { value: date.toISOString().slice(0, 7), label }\r\n})\n\n<Select label=\"Billing month\" options={MONTH_OPTIONS} placeholder=\"Choose a month\" />"
         },
         {
           "caption": "Sizes",
-          "source": "const TERRAIN_OPTIONS = [\n  { value: 'woodland', label: 'Woodland' },\n  { value: 'urban', label: 'Urban' },\n  { value: 'desert', label: 'Desert' },\n  { value: 'indoor', label: 'Indoor' },\n]\n\n<Select label=\"Terrain (small)\" inputSize=\"sm\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />\n<Select label=\"Terrain (medium)\" inputSize=\"md\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />\n<Select label=\"Terrain (large)\" inputSize=\"lg\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />"
+          "source": "const TERRAIN_OPTIONS = [\r\n  { value: 'woodland', label: 'Woodland' },\r\n  { value: 'urban', label: 'Urban' },\r\n  { value: 'desert', label: 'Desert' },\r\n  { value: 'indoor', label: 'Indoor' },\r\n]\n\n<Select label=\"Terrain (small)\" inputSize=\"sm\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />\r\n<Select label=\"Terrain (medium)\" inputSize=\"md\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />\r\n<Select label=\"Terrain (large)\" inputSize=\"lg\" options={TERRAIN_OPTIONS} placeholder=\"Terrain\" />"
         },
         {
           "caption": "Disabled control",
-          "source": "const SPEED_OPTIONS = [\n  { value: 'standard', label: 'Standard' },\n  { value: 'priority', label: 'Priority' },\n  { value: 'overnight', label: 'Overnight', disabled: true },\n]\n\n<Select label=\"Dispatch speed, unavailable\" options={SPEED_OPTIONS} defaultValue=\"standard\" disabled />"
+          "source": "const SPEED_OPTIONS = [\r\n  { value: 'standard', label: 'Standard' },\r\n  { value: 'priority', label: 'Priority' },\r\n  { value: 'overnight', label: 'Overnight', disabled: true },\r\n]\n\n<Select label=\"Dispatch speed, unavailable\" options={SPEED_OPTIONS} defaultValue=\"standard\" disabled />"
         },
         {
           "caption": "Invalid",
-          "source": "const SPEED_OPTIONS = [\n  { value: 'standard', label: 'Standard' },\n  { value: 'priority', label: 'Priority' },\n  { value: 'overnight', label: 'Overnight', disabled: true },\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} invalid placeholder=\"Choose a speed\" />"
+          "source": "const SPEED_OPTIONS = [\r\n  { value: 'standard', label: 'Standard' },\r\n  { value: 'priority', label: 'Priority' },\r\n  { value: 'overnight', label: 'Overnight', disabled: true },\r\n]\n\n<Select label=\"Dispatch speed\" options={SPEED_OPTIONS} invalid placeholder=\"Choose a speed\" />"
         },
         {
           "caption": "Beside an Input",
-          "source": "const TERRAIN_OPTIONS = [\n  { value: 'woodland', label: 'Woodland' },\n  { value: 'urban', label: 'Urban' },\n  { value: 'desert', label: 'Desert' },\n  { value: 'indoor', label: 'Indoor' },\n]\n\n<label className=\"flex flex-col gap-1 text-sm\">\n  Call sign\n  <Input placeholder=\"Anvil-3\" />\n</label>\n{/* Deliberately NOT a <label>. A <label> associates with a labelable element — input,\n    select, textarea, button among them — but Radix's trigger is a <button>, and a\n    <label> wrapping a button is inert: it neither names it nor forwards a click. The\n    Select's accessible name comes from its required `label` prop, and the visible text\n    here matches it exactly (SC 2.5.3, label in name). Wrapping it in a <label> would\n    have looked correct and done nothing. */}\n<div className=\"flex flex-col gap-1 text-sm\">\n  <span>Terrain</span>\n  <Select label=\"Terrain\" options={TERRAIN_OPTIONS} placeholder=\"Choose terrain\" />\n</div>"
+          "source": "const TERRAIN_OPTIONS = [\r\n  { value: 'woodland', label: 'Woodland' },\r\n  { value: 'urban', label: 'Urban' },\r\n  { value: 'desert', label: 'Desert' },\r\n  { value: 'indoor', label: 'Indoor' },\r\n]\n\n<label className=\"flex flex-col gap-1 text-sm\">\r\n  Call sign\r\n  <Input placeholder=\"Anvil-3\" />\r\n</label>\r\n{/* Deliberately NOT a <label>. A <label> associates with a labelable element — input,\r\n    select, textarea, button among them — but Radix's trigger is a <button>, and a\r\n    <label> wrapping a button is inert: it neither names it nor forwards a click. The\r\n    Select's accessible name comes from its required `label` prop, and the visible text\r\n    here matches it exactly (SC 2.5.3, label in name). Wrapping it in a <label> would\r\n    have looked correct and done nothing. */}\r\n<div className=\"flex flex-col gap-1 text-sm\">\r\n  <span>Terrain</span>\r\n  <Select label=\"Terrain\" options={TERRAIN_OPTIONS} placeholder=\"Choose terrain\" />\r\n</div>"
         }
       ],
       "closed": false,
@@ -9840,8 +9890,8 @@
         {
           "name": "axisWidth",
           "type": "number",
-          "default": "48",
-          "description": "The width the y-axis reserves, in px (pixels). 48 is Recharts' own YAxis default. Make it bigger if formatAxisValue's labels still get cut off."
+          "default": "automatic",
+          "description": "An override for the width the y-axis reserves, in px (pixels). By default the axis sizes itself to its widest formatted tick label, never narrower than 48, so a currency symbol is never cut off. Set it only to line up the axes of several panels."
         },
         {
           "name": "bands",

package/public/manifest/tokens.json

@@ -965,6 +965,132 @@
       "value": "#0a0602",
       "use": "Text on category.red.fill."
     },
+    {
+      "name": "--color-severity-1-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#49d092",
+        "light": "#1d714b"
+      },
+      "use": "Subtle Badge severity=1: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-1-fill",
+      "layer": "semantic",
+      "value": "#2fb577",
+      "use": "Solid Badge severity=1: the fill."
+    },
+    {
+      "name": "--color-severity-1-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on severity.1.fill."
+    },
+    {
+      "name": "--color-severity-2-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#ffcb79",
+        "light": "#804e00"
+      },
+      "use": "Subtle Badge severity=2: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-2-fill",
+      "layer": "semantic",
+      "value": "#ffbb52",
+      "use": "Solid Badge severity=2: the fill."
+    },
+    {
+      "name": "--color-severity-2-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on severity.2.fill."
+    },
+    {
+      "name": "--color-severity-3-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f19300",
+        "light": "#b13200"
+      },
+      "use": "Subtle Badge severity=3: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-3-fill",
+      "layer": "semantic",
+      "value": "#f19300",
+      "use": "Solid Badge severity=3: the fill."
+    },
+    {
+      "name": "--color-severity-3-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on severity.3.fill."
+    },
+    {
+      "name": "--color-severity-4-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#ff5512",
+        "light": "#ae0a0a"
+      },
+      "use": "Subtle Badge severity=4: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-4-fill",
+      "layer": "semantic",
+      "value": "#f33636",
+      "use": "Solid Badge severity=4: the fill."
+    },
+    {
+      "name": "--color-severity-4-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text on severity.4.fill."
+    },
+    {
+      "name": "--color-severity-5-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f55b5b",
+        "light": "#790707"
+      },
+      "use": "Subtle Badge severity=5: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-5-fill",
+      "layer": "semantic",
+      "value": "#ae0a0a",
+      "use": "Solid Badge severity=5: the fill."
+    },
+    {
+      "name": "--color-severity-5-ink",
+      "layer": "semantic",
+      "value": "#ffffff",
+      "use": "Text on severity.5.fill."
+    },
+    {
+      "name": "--color-severity-6-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#f78181",
+        "light": "#440404"
+      },
+      "use": "Subtle Badge severity=6: text and border. A step, with its word."
+    },
+    {
+      "name": "--color-severity-6-fill",
+      "layer": "semantic",
+      "value": "#440404",
+      "use": "Solid Badge severity=6: the fill."
+    },
+    {
+      "name": "--color-severity-6-ink",
+      "layer": "semantic",
+      "value": "#ffffff",
+      "use": "Text on severity.6.fill."
+    },
     {
       "name": "--color-numeral-pad",
       "layer": "semantic",

package/scripts/lib/search-score.mjs

@@ -1,24 +1,47 @@
-// The one ranking for "find me the thing for X". The MCP server's `search` tool and the docs site's
-// top-bar search both call it, so an agent and a person typing the same words get the same order.
-// Pure and dependency-free: it runs in Node and in the browser.
-
-export const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
-
-/** A scorer for one query. `title` is the names, `body` the summary; `props` (descriptions) and
- *  `propNames` count once each, as hints, so a long prop table does not outrank a component or
- *  token whose own summary is about the query. 0 means no match. */
-export function scorer(query) {
-  const terms = words(query)
-  return (title, body, props = '', propNames = '') => {
-    if (terms.length === 0) return 0
-    const t = words(title).join(' ')
-    const b = words(body)
-    const p = words(props)
-    const n = words(propNames)
-    const inMain = term => t.includes(term) || b.some(w => w.startsWith(term))
-    // Every word of the query in the name or summary beats one word found often: "page
-    // background" is the surface token, not PageHeader, whose name matches "page" alone.
-    const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
-    return all + terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + Math.min(b.filter(w => w.startsWith(term)).length, 3) + (inMain(term) ? 0 : n.some(w => w.startsWith(term)) ? 2 : p.some(w => w.startsWith(term)) ? 1 : 0), 0)
-  }
-}
+// The one ranking for "find me the thing for X". The MCP server's `search` tool and the docs site's
+// top-bar search both call it, so an agent and a person typing the same words get the same order.
+// Pure and dependency-free: it runs in Node and in the browser.
+
+export const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+
+// Words that say nothing about the component. Left in, "a" and "an" prefix-match half the
+// summaries, so "pick a country" ranked on filler (issue #2).
+// "one" stays: it is what tells Select from MultiSelect. Dropped only when the query has another
+// word, so a search for "the" alone still works.
+const STOP = new Set(['a', 'an', 'the', 'of', 'to', 'for', 'from', 'in', 'on', 'with', 'and', 'or', 'some', 'i', 'me', 'my', 'user', 'users', 'let', 'lets'])
+
+// Ways people say the same intent. A query word also matches the other words of its group, so
+// "pick a country" and "choose an option" reach Select, whose own words are select and choice.
+const SYNONYMS = [
+  ['pick', 'choose', 'select', 'choice', 'option'],
+]
+const variants = term => {
+  const group = SYNONYMS.find(g => g.includes(term))
+  return group ? [term, ...group.filter(w => w !== term)] : [term]
+}
+
+/** A scorer for one query. `title` is the names, `body` the summary; `props` (descriptions) and
+ *  `propNames` count once each, as hints, so a long prop table does not outrank a component or
+ *  token whose own summary is about the query. 0 means no match. */
+export function scorer(query) {
+  const all_ = words(query)
+  const kept = all_.filter(w => !STOP.has(w))
+  const terms = (kept.length ? kept : all_).map(variants)
+  return (title, body, props = '', propNames = '') => {
+    if (terms.length === 0) return 0
+    const t = words(title).join(' ')
+    const b = words(body)
+    const p = words(props)
+    const n = words(propNames)
+    const tw = t.split(' ')
+    const inTitle = vs => vs.some(v => t.includes(v))
+    // A name that is the word beats a name that contains it: Select over MultiSelect for "select".
+    const titleWord = vs => (vs.some(v => tw.includes(v)) ? 1 : 0)
+    const bodyHits = vs => b.filter(w => vs.some(v => w.startsWith(v))).length
+    const inMain = vs => inTitle(vs) || bodyHits(vs) > 0
+    // Every word of the query in the name or summary beats one word found often: "page
+    // background" is the surface token, not PageHeader, whose name matches "page" alone.
+    const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
+    return all + terms.reduce((sum, vs) => sum + (inTitle(vs) ? 3 + titleWord(vs) : 0) + Math.min(bodyHits(vs), 3) + (inMain(vs) ? 0 : n.some(w => vs.some(v => w.startsWith(v))) ? 2 : p.some(w => vs.some(v => w.startsWith(v))) ? 1 : 0), 0)
+  }
+}