@viraui/react 2026.10.0 → 2026.11.0-next.1

package/dist/specs/components/gauge/props.xml

@@ -0,0 +1,452 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="gauge">
+  <when_to_use>
+    <item>Use `Gauge` for composable round determinate dials (air quality, temperature, fuel, heading).</item>
+    <item>Use `GaugeControl` when the round dial must be adjusted with pointer and keyboard (single or range).</item>
+    <item>Use zone helpers (`zoneColor`, `zoneCutoffs`) when band colors drive arc or mark paint.</item>
+    <item>Optional part colors: omit `color` for defaults, or pass `var(--global-*)` / `var(--highlight-*)` (see `usage.xml` and pattern `optional-token-colors`).</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Use `Meter` for a compact horizontal capacity track without polar composition.</item>
+    <item>Use `Slider` for linear interactive ranges (Gauge is round-only so it does not replace Slider).</item>
+    <item>Use `LinearProgress` for in-progress or indeterminate work.</item>
+  </when_not_to_use>
+
+  <prop name="value" kind="react">
+    <description>Domain reading, or a `[from, to]` range to fill between. Required on `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="min" kind="react">
+    <description>Lower bound of the domain. Default `0`. Shared by `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="max" kind="react">
+    <description>Upper bound of the domain. Default `100`. Shared by `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="startAngle" kind="react">
+    <description>Round sweep start in gauge degrees (clockwise from six o'clock). Default `40`. Shared by `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="endAngle" kind="react">
+    <description>Round sweep end in gauge degrees. Default `320`. Shared by `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="radius" kind="react">
+    <description>Reference radius in SVG units. Default `200` on `Gauge`; `GaugeInset` inherits the host radius when omitted.</description>
+  </prop>
+  <prop name="padding" kind="react">
+    <description>`Gauge` only. Extra room around the reference geometry for strokes and labels. Default `48`.</description>
+  </prop>
+  <prop name="fit" kind="react">
+    <description>`Gauge` only. `square` boxes the full circle; `content` fits the arc sweep and sets `--vui-gauge-aspect-ratio`. Default `square`.</description>
+  </prop>
+  <prop name="transition" kind="react">
+    <description>Animate toward new values on `Gauge` / `GaugeInset`: `true` / spring / tween config, or omit for instant updates. Reduced motion snaps.</description>
+  </prop>
+  <prop name="initialValue" kind="react">
+    <description>`Gauge` / `GaugeInset`. Where the animated reading starts on mount. Default starts at the target value.</description>
+  </prop>
+  <prop name="wrap" kind="react">
+    <description>Treat the domain as a closed ring (fold + shortest-path animation). Default `false`. Shared by `Gauge`, `GaugeControl`, and `GaugeInset`.</description>
+  </prop>
+  <prop name="rotate" kind="react">
+    <description>`Gauge` / `GaugeInset`. Turn the whole scale this many degrees clockwise. Default `0`.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Accessible name for meter roots; required on `GaugeControl`. On `Gauge`, omit and name via `aria-label` when needed.</description>
+  </prop>
+
+  <prop name="GaugeControl.onChange" kind="react">
+    <description>Callback emitting the next number or `[from, to]` tuple.</description>
+  </prop>
+  <prop name="GaugeControl.onPress" kind="react">
+    <description>Face-centre press or Enter for dials that also act as a switch. Omit when unused.</description>
+  </prop>
+  <prop name="GaugeControl.step" kind="react">
+    <description>Snap size and arrow-key delta. Default `1`.</description>
+  </prop>
+  <prop name="GaugeControl.thumbLabels" kind="react">
+    <description>Accessible names for range thumbs. Defaults to `{label} start` / `{label} end`.</description>
+  </prop>
+  <prop name="GaugeControl.valueText" kind="react">
+    <description>Spoken value text (string or pair for range).</description>
+  </prop>
+  <prop name="GaugeControl.knob" kind="react">
+    <description>Relative drag anywhere on the control instead of absolute ring targeting. Default `false`.</description>
+  </prop>
+  <prop name="GaugeControl.disabled" kind="react">
+    <description>Ignore pointer and keyboard input. Presence via `data-disabled` `"true"`/`"false"`.</description>
+  </prop>
+
+  <prop name="GaugeTrack.width" kind="react">
+    <description>Stroke width in SVG units. Default `24`.</description>
+  </prop>
+  <prop name="GaugeTrack.color" kind="react">
+    <description>Stroke colour. Default `var(--global-contrast)`.</description>
+  </prop>
+  <prop name="GaugeTrack.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeTrack.cap" kind="react">
+    <description>Stroke line cap. Default `round`.</description>
+  </prop>
+  <prop name="GaugeTrack.offset" kind="react">
+    <description>Radial offset from the scale reference line. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeArc.width" kind="react">
+    <description>Stroke width in SVG units. Default `24`.</description>
+  </prop>
+  <prop name="GaugeArc.color" kind="react">
+    <description>Stroke colour. Default `var(--global-primary)`.</description>
+  </prop>
+  <prop name="GaugeArc.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeArc.cap" kind="react">
+    <description>Stroke line cap. Default `round`.</description>
+  </prop>
+  <prop name="GaugeArc.offset" kind="react">
+    <description>Radial offset from the scale reference line. Default `0`.</description>
+  </prop>
+  <prop name="GaugeArc.from" kind="react">
+    <description>Domain value the arc starts at. Default gauge `from` (min on a single value).</description>
+  </prop>
+  <prop name="GaugeArc.to" kind="react">
+    <description>Domain value the arc ends at. Default current gauge `value`.</description>
+  </prop>
+  <prop name="GaugeArc.reverse" kind="react">
+    <description>Grow the arc back from the end of the sweep. Default `false`.</description>
+  </prop>
+  <prop name="GaugeArc.wrap" kind="react">
+    <description>Carry the arc across a closed-ring seam instead of clamping. Default `false`.</description>
+  </prop>
+
+  <prop name="GaugeStack.parts" kind="react">
+    <description>Ordered segments: each `{ weight?, to?, color, opacity? }` (use weights or fixed cutoffs, not both styles mixed).</description>
+  </prop>
+  <prop name="GaugeStack.from" kind="react">
+    <description>Domain value the stack starts at. Default gauge `from`.</description>
+  </prop>
+  <prop name="GaugeStack.width" kind="react">
+    <description>Stroke width in SVG units. Default `24`.</description>
+  </prop>
+  <prop name="GaugeStack.opacity" kind="react">
+    <description>Group stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeStack.cap" kind="react">
+    <description>Stroke line cap. Default `butt`.</description>
+  </prop>
+  <prop name="GaugeStack.offset" kind="react">
+    <description>Radial offset from the scale reference line. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeZones.zones" kind="react">
+    <description>Ordered `{ to, color }` cutoffs; each band runs from the previous `to` (or `min`) and the last extends to `max`.</description>
+  </prop>
+  <prop name="GaugeZones.width" kind="react">
+    <description>Stroke width in SVG units. Default `8`.</description>
+  </prop>
+  <prop name="GaugeZones.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeZones.cap" kind="react">
+    <description>Cap on joints between zones. Default `butt`.</description>
+  </prop>
+  <prop name="GaugeZones.endCap" kind="react">
+    <description>Cap on the two outer ends of the whole band. Default same as `cap`.</description>
+  </prop>
+  <prop name="GaugeZones.offset" kind="react">
+    <description>Radial offset from the scale reference line. Default `0`.</description>
+  </prop>
+  <prop name="GaugeZones.gap" kind="react">
+    <description>Gap between neighbouring zones in scale units. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeTicks.count" kind="react">
+    <description>Number of intervals across the domain (`count + 1` ticks). Default `10`.</description>
+  </prop>
+  <prop name="GaugeTicks.length" kind="react">
+    <description>Tick line length in SVG units. Default `12`.</description>
+  </prop>
+  <prop name="GaugeTicks.width" kind="react">
+    <description>Stroke width of each tick. Default `2`.</description>
+  </prop>
+  <prop name="GaugeTicks.color" kind="react">
+    <description>One colour or `(value) =&gt; color`. Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeTicks.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeTicks.cap" kind="react">
+    <description>Stroke line cap. Default `round`.</description>
+  </prop>
+  <prop name="GaugeTicks.offset" kind="react">
+    <description>Offset of each tick midpoint from the scale reference line. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeTickFill.count" kind="react">
+    <description>Number of intervals across the domain. Default `40`.</description>
+  </prop>
+  <prop name="GaugeTickFill.from" kind="react">
+    <description>Where the lit stretch starts. Default gauge `from`.</description>
+  </prop>
+  <prop name="GaugeTickFill.to" kind="react">
+    <description>Where the lit stretch ends. Default current gauge `value`.</description>
+  </prop>
+  <prop name="GaugeTickFill.mode" kind="react">
+    <description>`fill` lights every tick between ends; `nearest` lights only the tick nearest each end. Default `fill`.</description>
+  </prop>
+  <prop name="GaugeTickFill.color" kind="react">
+    <description>Lit tick colour (string or per-value). Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeTickFill.dimColor" kind="react">
+    <description>Unlit tick colour. Default faint theme foreground.</description>
+  </prop>
+  <prop name="GaugeTickFill.length" kind="react">
+    <description>Unlit tick length. Default `12`.</description>
+  </prop>
+  <prop name="GaugeTickFill.litLength" kind="react">
+    <description>Lit tick length. Default same as `length`.</description>
+  </prop>
+  <prop name="GaugeTickFill.width" kind="react">
+    <description>Stroke width. Default `2`.</description>
+  </prop>
+  <prop name="GaugeTickFill.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeTickFill.cap" kind="react">
+    <description>Stroke line cap. Default `round`.</description>
+  </prop>
+  <prop name="GaugeTickFill.offset" kind="react">
+    <description>Offset of each tick midpoint from the scale reference line. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeMarks.values" kind="react">
+    <description>Domain values to mark (for example zone cutoffs).</description>
+  </prop>
+  <prop name="GaugeMarks.count" kind="react">
+    <description>Equal segment cuts instead of `values` (marks between segments, not at open ends).</description>
+  </prop>
+  <prop name="GaugeMarks.length" kind="react">
+    <description>Mark line length. Default `12`.</description>
+  </prop>
+  <prop name="GaugeMarks.width" kind="react">
+    <description>Stroke width. Default `2`.</description>
+  </prop>
+  <prop name="GaugeMarks.color" kind="react">
+    <description>One colour or `(value) =&gt; color`. Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeMarks.opacity" kind="react">
+    <description>Stroke opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeMarks.cap" kind="react">
+    <description>Stroke line cap. Default `round`.</description>
+  </prop>
+  <prop name="GaugeMarks.offset" kind="react">
+    <description>Offset of each mark midpoint from the scale reference line. Default `0`.</description>
+  </prop>
+
+  <prop name="GaugeTickLabels.count" kind="react">
+    <description>Number of intervals across the domain. Default `10`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.offset" kind="react">
+    <description>Label offset from the scale reference line. Default `-48`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.anchor" kind="react">
+    <description>Which edge of each label sits at its point. Default `middle`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.fontSize" kind="react">
+    <description>Font size in SVG units. Default `16`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.color" kind="react">
+    <description>One colour or `(value) =&gt; color`. Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.font" kind="react">
+    <description>Typeface map (`sans` / `rounded` / `mono`). Default `sans`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.weight" kind="react">
+    <description>Font weight token. Default `medium`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.decimals" kind="react">
+    <description>Fixed decimal places when `format` is omitted. Default `0`.</description>
+  </prop>
+  <prop name="GaugeTickLabels.format" kind="react">
+    <description>Custom label formatter; overrides `decimals` when set.</description>
+  </prop>
+
+  <prop name="GaugeText.x" kind="react">
+    <description>Position relative to centre in SVG units. Default `0`.</description>
+  </prop>
+  <prop name="GaugeText.y" kind="react">
+    <description>Position relative to centre in SVG units (positive down). Default `0`.</description>
+  </prop>
+  <prop name="GaugeText.fontSize" kind="react">
+    <description>Font size in SVG units. Default `24`.</description>
+  </prop>
+  <prop name="GaugeText.color" kind="react">
+    <description>Fill colour. Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeText.font" kind="react">
+    <description>Typeface map. Default `sans`.</description>
+  </prop>
+  <prop name="GaugeText.weight" kind="react">
+    <description>Font weight token. Default `medium`.</description>
+  </prop>
+  <prop name="GaugeText.anchor" kind="react">
+    <description>Which edge of the text sits at `(x, y)`. Default `middle`.</description>
+  </prop>
+  <prop name="GaugeText.children" kind="react">
+    <description>Label content.</description>
+  </prop>
+
+  <prop name="GaugeValue.decimals" kind="react">
+    <description>Fixed decimal places when `format` is omitted. Default `0`.</description>
+  </prop>
+  <prop name="GaugeValue.format" kind="react">
+    <description>Formats each number; a range formats its two ends apart.</description>
+  </prop>
+  <prop name="GaugeValue.separator" kind="react">
+    <description>Placed between the two ends of a range. Default en dash.</description>
+  </prop>
+  <prop name="GaugeValue.end" kind="react">
+    <description>Show only one end of a range (`from` / `to`). Default both ends when ranged.</description>
+  </prop>
+  <prop name="GaugeValue.fontSize" kind="react">
+    <description>Font size in SVG units. Default `96`.</description>
+  </prop>
+  <prop name="GaugeValue.weight" kind="react">
+    <description>Font weight token. Default `semibold`.</description>
+  </prop>
+  <prop name="GaugeValue.x" kind="react">
+    <description>Position relative to centre. Default `0`.</description>
+  </prop>
+  <prop name="GaugeValue.y" kind="react">
+    <description>Position relative to centre. Default `0`.</description>
+  </prop>
+  <prop name="GaugeValue.color" kind="react">
+    <description>Fill colour. Default `var(--global-foreground)`.</description>
+  </prop>
+  <prop name="GaugeValue.font" kind="react">
+    <description>Typeface map. Default `sans`.</description>
+  </prop>
+  <prop name="GaugeValue.anchor" kind="react">
+    <description>Text anchor. Default `middle`.</description>
+  </prop>
+
+  <prop name="GaugeDot.radius" kind="react">
+    <description>Dot radius in SVG units. Default `10`.</description>
+  </prop>
+  <prop name="GaugeDot.color" kind="react">
+    <description>Fill colour. Default `var(--global-primary)`.</description>
+  </prop>
+  <prop name="GaugeDot.opacity" kind="react">
+    <description>Fill opacity. Default `1`.</description>
+  </prop>
+  <prop name="GaugeDot.offset" kind="react">
+    <description>Offset of the centre from the scale reference line. Default `0`.</description>
+  </prop>
+  <prop name="GaugeDot.turns" kind="react">
+    <description>Sweeps of the scale across the domain. Default `1`.</description>
+  </prop>
+  <prop name="GaugeDot.halo" kind="react">
+    <description>Width of a ring behind the dot. Default `0` (bare).</description>
+  </prop>
+  <prop name="GaugeDot.haloColor" kind="react">
+    <description>Halo colour. Default `var(--global-background)`.</description>
+  </prop>
+  <prop name="GaugeDot.end" kind="react">
+    <description>Which end of a range the dot rides. Default `to`.</description>
+  </prop>
+
+  <prop name="GaugeNeedle.kind" kind="react">
+    <description>Needle shape: `line` | `pointer` | `compass` | `arrow`. Default `line`.</description>
+  </prop>
+  <prop name="GaugeNeedle.length" kind="react">
+    <description>Length as a fraction of the reference radius. Default `0.85`.</description>
+  </prop>
+  <prop name="GaugeNeedle.width" kind="react">
+    <description>Stroke width for `line`; centre width for filled styles. Default `6`.</description>
+  </prop>
+  <prop name="GaugeNeedle.color" kind="react">
+    <description>Fill/stroke colour. Default `var(--global-primary)`.</description>
+  </prop>
+  <prop name="GaugeNeedle.tail" kind="react">
+    <description>How far the needle extends behind the centre, in SVG units. Default `30`.</description>
+  </prop>
+  <prop name="GaugeNeedle.tailColor" kind="react">
+    <description>Colour of the tail half. Default same as `color`.</description>
+  </prop>
+  <prop name="GaugeNeedle.tailDot" kind="react">
+    <description>Radius of a disc at the end of the tail. Default `0`.</description>
+  </prop>
+  <prop name="GaugeNeedle.turns" kind="react">
+    <description>Sweeps of the arc across the domain. Default `1`.</description>
+  </prop>
+  <prop name="GaugeNeedle.gap" kind="react">
+    <description>Clear circle around the centre that splits the needle. Default `0`.</description>
+  </prop>
+  <prop name="GaugeNeedle.end" kind="react">
+    <description>Which end of a range the needle points at. Default `to`.</description>
+  </prop>
+
+  <prop name="GaugeHub.radius" kind="react">
+    <description>Hub disc radius in SVG units; `0` hides it. Default `12`.</description>
+  </prop>
+  <prop name="GaugeHub.color" kind="react">
+    <description>Fill colour. Default `var(--global-foreground)`.</description>
+  </prop>
+
+  <prop name="GaugeTooltip.position" kind="react">
+    <description>Anchor on the gauge (`value`, edges, corners). Default `value`.</description>
+  </prop>
+  <prop name="GaugeTooltip.side" kind="react">
+    <description>Side the bubble stands off its point. Default `auto`.</description>
+  </prop>
+  <prop name="GaugeTooltip.at" kind="react">
+    <description>Domain value a `value` tooltip points at. Default current value (or range middle).</description>
+  </prop>
+  <prop name="GaugeTooltip.offset" kind="react">
+    <description>How far out from the scale reference the point sits, in SVG units. Default `24`.</description>
+  </prop>
+  <prop name="GaugeTooltip.gap" kind="react">
+    <description>Room between the point and the bubble, in CSS pixels. Default `8`.</description>
+  </prop>
+  <prop name="GaugeTooltip.avoidCollisions" kind="react">
+    <description>Keep the bubble on screen. Default `true`.</description>
+  </prop>
+  <prop name="GaugeTooltip.collisionPadding" kind="react">
+    <description>Clearance from the viewport edge, in CSS pixels. Default `8`.</description>
+  </prop>
+  <prop name="GaugeTooltip.open" kind="react">
+    <description>Force open or shut instead of hover/press/focus.</description>
+  </prop>
+  <prop name="GaugeTooltip.label" kind="react">
+    <description>Small line above the value.</description>
+  </prop>
+  <prop name="GaugeTooltip.unit" kind="react">
+    <description>Printed after the value, a size down.</description>
+  </prop>
+  <prop name="GaugeTooltip.decimals" kind="react">
+    <description>Fraction digits when formatting with `toFixed`. Default `0`.</description>
+  </prop>
+  <prop name="GaugeTooltip.format" kind="react">
+    <description>Formats each number; a range formats its two ends apart.</description>
+  </prop>
+  <prop name="GaugeTooltip.separator" kind="react">
+    <description>Placed between the two ends of a range. Default en dash.</description>
+  </prop>
+  <prop name="GaugeTooltip.children" kind="react">
+    <description>Replace default label/value/unit, or a `(value, from?) =&gt; node` renderer.</description>
+  </prop>
+
+  <prop name="GaugeInset.x" kind="react">
+    <description>Centre in the host gauge's SVG units. Default `0`.</description>
+  </prop>
+  <prop name="GaugeInset.y" kind="react">
+    <description>Centre in the host gauge's SVG units (positive down). Default `0`.</description>
+  </prop>
+  <prop name="GaugeInset.scale" kind="react">
+    <description>Size relative to the host gauge. Default `1`.</description>
+  </prop>
+
+  <prop name="aspect-ratio" kind="css">
+    <description>Public `--vui-gauge-aspect-ratio` used when `fit="content"` on the round Gauge SVG host.</description>
+  </prop>
+</props>

package/dist/specs/components/gauge/usage.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="gauge">
+  <do>Compose round dials with `Gauge` + parts (`Track`, `Arc`, `Zones`, `Marks`, `Ticks`, `Dot`, `Hub`, `Value`, `Text`) sharing one domain</do>
+  <do>Wrap with `GaugeControl` for interactive single or dual-thumb polar adjustment; keep Control angles aligned with the child dial</do>
+  <do>Color is optional: omit part `color` to keep theme defaults (Track `var(--global-contrast)`, Arc/Dot/Needle `var(--global-primary)`, ticks/labels/text/value/hub `var(--global-foreground)` — see each part in `props.xml`)</do>
+  <do>When you need paint, pass theme CSS vars as strings on `color` (and Needle `tailColor`, TickFill `dimColor`, Dot `haloColor`, Zones `zones[].color`): `--global-*` for chrome/labels (`foreground`, `background`, `primary`, `contrast`, `muted`), `--highlight-*` for status/decorative bands (`red`, `green`, `yellow`, `cyan`, `acid`, `blue`, `purple`, …)</do>
+  <do>Zone-driven readings: put token colors on `zones[].color`, then reuse with `zoneColor(zones, value)` (or `zoneCutoffs`) on Arc / Marks so the live fill matches the active band</do>
+  <do>Pass `label` on read-only roots (or `aria-label`) and always pass `label` on `GaugeControl`</do>
+  <do>Prefer `Meter` for compact horizontal capacity chrome; prefer `Slider` for linear interactive ranges; prefer Gauge when polar composition or dial Control is needed</do>
+  <do>Needle visual style prop is `kind` (not upstream `style`) to avoid clashing with React `style`</do>
+  <dont>Using Gauge / GaugeControl as a linear bar — use Slider (or Meter / LinearProgress for non-interactive)</dont>
+  <dont>Using Gauge for discrete icon-row scores — use IconMeter</dont>
+  <dont>Expecting a Meter/Chip-style `variant` on Gauge — parts take explicit CSS color strings (`var(--global-*)` / `var(--highlight-*)`), not a highlight variant prop</dont>
+  <dont>Hard-coding hex/rgb for themeable dial paint when a `--global-*` or `--highlight-*` token fits</dont>
+  <dont>Nesting multiple Gauge domain providers</dont>
+  <dont>Putting widget roles on decorative SVG strokes</dont>
+  <dont>Shipping without Control `label` or thumb names on ranges</dont>
+  <dont>Adding `gauge-ui` or `motion` as runtime dependencies</dont>
+  <dont>Using Stack for polar dial geometry — SVG scale math owns layout (documented Stack exception)</dont>
+  <dont>Expecting LinearGauge / LinearGaugeInset / lineScale — intentionally out of surface so Gauge does not replace Slider</dont>
+</usage>

package/dist/specs/components/icon-button/props.xml

@@ -55,7 +55,7 @@
     <description>Button block size; size prop presets via data attributes.</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Defaults to a fixed fraction of `--vui-button-height` so glyphs stay proportional across space scales; prefer this over setting `size` on the glyph ReactNode.</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button.</description>
@@ -79,7 +79,7 @@
     <description>Button block size; size prop presets via data attributes. (icon-button-link)</description>
   </prop>
   <prop name="icon-size" kind="css">
-    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode. (icon-button-link)</description>
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Defaults to a fixed fraction of `--vui-button-height` so glyphs stay proportional across space scales; prefer this over setting `size` on the glyph ReactNode. (icon-button-link)</description>
   </prop>
   <prop name="padding-block" kind="css">
     <description>Vertical padding inside the button. (icon-button-link)</description>

package/dist/specs/components/icon-button/usage.xml

@@ -3,7 +3,7 @@
   <do>Compact toolbar or chrome actions identified only by icon</do>
   <do>Same size, variant, and loading model as Button without a visible label</do>
   <do>Decorative glyph with an explicit accessible name on the root (`aria-label` / `aria-labelledby`)</do>
-  <do>Omit `size` / width / height on the `icon` glyph — host CSS sizes SVG via `--vui-button-icon-size`; set glyph size only to expressly override</do>
+  <do>Omit `size` / width / height on the `icon` glyph — host CSS sizes SVG via `--vui-button-icon-size` (fraction of `--vui-button-height`); set glyph size only to expressly override</do>
   <do>Toolbar / zoom / chrome clusters: Stack row of IconButtons inside Surface — gap via Stack, not per-control CSS</do>
   <do>Textfield `endAddon` / `startAddon` for compact field chrome (e.g. copy) — keep addon control `size=&quot;s&quot;` (control size, not glyph size)</do>
   <do>Menu / overlay triggers via `Menu.Trigger render={&lt;IconButton … /&gt;}` (and peers with the same pattern)</do>

package/dist/specs/components/icon-meter/a11y.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="icon-meter">
+  <rule>Follow the APG Meter pattern: role meter, valuemin 0, valuemax = clamped iconCount, valuenow = clamped value.</rule>
+  <rule>Always expose value text — default `"{value} of {iconCount}"`, or override with `valueText`.</rule>
+  <rule>Provide a visible `label` (or default numeric label) or an accessible name via `aria-label` / `aria-labelledby` when `hideLabel` is true.</rule>
+  <rule>Icon glyphs and the half-fill gradient defs are decorative (`aria-hidden`); do not put widget roles on them.</rule>
+  <rule>Display-only — not an interactive rating and not a progressbar; do not add keyboard value editing.</rule>
+  <rule>Value `0 of N` is valid: all icons render empty/unhighlighted.</rule>
+</a11y>

package/dist/specs/components/icon-meter/meta.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="icon-meter" title="IconMeter" category="feedback" shared_contract="icon-meter">
+  <summary>Display-only discrete icon row for scores and levels (empty / half / full), with APG Meter semantics. Distinct from track Meter, arc Gauge, and LinearProgress.</summary>
+  <exports>
+    <export name="IconMeter" />
+  </exports>
+  <related>
+    <ref id="meter" />
+    <ref id="gauge" />
+    <ref id="linear-progress" />
+    <ref id="text" />
+    <ref id="stack" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/meter#api-reference" />
+</meta>

package/dist/specs/components/icon-meter/patterns.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="icon-meter">
+  <example title="Score row with label">
+    <tsx><![CDATA[
+<IconMeter label="Quality" value={3.5} iconCount={5} />
+]]></tsx>
+    <notes>Default chrome star; half fill at 3.5. Visible label names the meter. Accent defaults to `var(--global-primary)`.</notes>
+  </example>
+
+  <example title="Zero is valid">
+    <tsx><![CDATA[
+<IconMeter aria-label="Guest rating" hideLabel value={0} iconCount={5} />
+]]></tsx>
+    <notes>All icons empty; valuetext `0 of 5`. Name via aria-label when label hidden.</notes>
+  </example>
+
+  <example title="Custom icon component">
+    <tsx><![CDATA[
+<IconMeter icon={HeartIcon} value={4} highlightColor="var(--highlight-red)" size="l" />
+]]></tsx>
+    <notes>`HeartIcon` must honor `fill` (and optional `size` / `className`). Not an opaque ReactNode.</notes>
+  </example>
+</patterns>

package/dist/specs/components/icon-meter/props.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="icon-meter">
+  <when_to_use>
+    <item>Show a discrete score or level as a row of recolorable icons (stars, hearts, custom SVG components).</item>
+    <item>Use when empty / half / full icon paint communicates the reading better than a continuous track or arc.</item>
+    <item>Accent with `highlightColor` (CSS color string, default `var(--global-primary)`); override further via `--vui-icon-meter-*` when needed.</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Continuous capacity / storage / battery track — use Meter.</item>
+    <item>Polar dial or needle reading — use Gauge.</item>
+    <item>In-progress or indeterminate task completion — use LinearProgress.</item>
+    <item>Interactive star rating the user edits — out of scope; do not misuse IconMeter as a control.</item>
+  </when_not_to_use>
+  <prop name="value" kind="react">
+    <description>Current reading. Clamped to `[0, iconCount]` after `iconCount` is clamped. `0` paints all empty icons.</description>
+  </prop>
+  <prop name="iconCount" kind="react">
+    <description>Number of icon slots. Clamped to at least `3`. Defaults to `5`.</description>
+  </prop>
+  <prop name="icon" kind="react">
+    <description>Recolorable icon component instantiated once per slot with `fill` / `size` / `className`. Defaults to private ChromeStar.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Compact size step (`s` | `m` | `l`). Maps to `data-dimension` for icon size, gap, and label text size. Defaults to `m`.</description>
+  </prop>
+  <prop name="highlightColor" kind="react">
+    <description>CSS color string for full / half icons (`--vui-icon-meter-icon-color`). Pass any valid color or theme var (e.g. `var(--highlight-yellow)`). Defaults to `var(--global-primary)`.</description>
+  </prop>
+  <prop name="label" kind="react">
+    <description>Custom visible label. When omitted and not hidden, the clamped value string is shown.</description>
+  </prop>
+  <prop name="hideLabel" kind="react">
+    <description>Hides the visible label. Provide `aria-label` or `aria-labelledby` for the accessible name. Defaults to `false`.</description>
+  </prop>
+  <prop name="valueText" kind="react">
+    <description>Overrides the default AT value text (`"{value} of {iconCount}"`).</description>
+  </prop>
+  <prop name="icon-color" kind="css">
+    <description>Full / half accent color (`--vui-icon-meter-icon-color`). Defaults from `highlightColor` / `var(--global-primary)`.</description>
+  </prop>
+  <prop name="empty-color" kind="css">
+    <description>Empty / unhighlighted icon color (`--vui-icon-meter-empty-color`). Defaults to `var(--global-contrast)`.</description>
+  </prop>
+</props>

package/dist/specs/components/icon-meter/usage.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="icon-meter">
+  <do>Discrete scores and levels as icon rows: ratings display, quality tiers, guest scores — `value` + `iconCount` (min 3, default 5)</do>
+  <do>Pass a recolorable `icon` component when the default chrome star is wrong; meter injects `fill` per empty / half / full slot</do>
+  <do>Size with `s` | `m` | `l` (default `m`); accent with `highlightColor` CSS string (default `var(--global-primary)`)</do>
+  <do>Name the meter: visible `label` (or default numeric label), or `hideLabel` + `aria-label` / `aria-labelledby`</do>
+  <do>Override AT value text with `valueText` when `"{value} of {iconCount}"` is not enough</do>
+  <dont>Using IconMeter for continuous capacity tracks — use Meter</dont>
+  <dont>Using IconMeter for polar / needle dials — use Gauge</dont>
+  <dont>Using IconMeter for loading or task progress — use LinearProgress</dont>
+  <dont>Turning IconMeter into an interactive rating control (keyboard / onChange) — out of scope</dont>
+  <dont>Passing a finished opaque ReactNode as `icon` — pass a component the meter can recolor</dont>
+</usage>

package/dist/specs/components/linear-progress/usage.xml

@@ -6,6 +6,7 @@
   <do>Goal cards: Surface + Stack headlines / captions around a track-only LinearProgress (`aria-label` when no `label` prop)</do>
   <do>Prefer Meter for static capacity / score within a range (storage, quota, battery) — LinearProgress for in-progress tasks</do>
   <dont>Using LinearProgress as an interactive value control — use Slider</dont>
+  <dont>Using LinearProgress for discrete icon-row scores — use IconMeter; for static capacity tracks use Meter</dont>
   <dont>Using LinearProgress for layout placeholders — use Skeleton; for tiny busy chrome use Spinner / Button `loading`</dont>
   <dont>Modeling invalid or disabled progress — Base UI Progress exposes neither</dont>
   <dont>Hiding the task name when multiple progress indicators share a view</dont>

package/dist/specs/components/meter/meta.xml

@@ -5,6 +5,7 @@
     <export name="Meter" />
   </exports>
   <related>
+    <ref id="icon-meter" />
     <ref id="linear-progress" />
     <ref id="slider" />
     <ref id="text" />