Meter

ONE inline bar, absorbing three that were hand-rolled separately across the phase-10 corpus: an odds bar, a score meter and a reviewer bar. They differed in tone and in what the denominator meant; they did not differ in anything that justified three…

data displayserver320pxuiv1.0.0

Preview

Meter — live renderprimitives-meter--zero-is-not-missing

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL
npx shadcn@latest add https://ds.interlace.tools/r/meter.json
With the @interlace alias
npx shadcn@latest add @interlace/meter

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

9 states, one closed union — not a boolean per condition. Partial is a state, not an absence: a spinner that hides progress, or a missing prior rendered as 0, is the failure this model exists to make impossible.

StateReads asRoleEncoding
loadingloadingStands instead of the bodymuted
error! errorStands instead of the bodydanger
not-applicablen/aStands instead of the bodyhatchedrecede
not-countednot countedStands instead of the bodyhatchedmuted
emptynoneStands instead of the bodymuted
partialpartialStands next to the body and changes how to read itdashedmuted
truncatedtruncatedStands next to the body and changes how to read itdashedmuted
first-measurement· first measurementStands next to the body and changes how to read itdashedaccent
idleThe absence of absencemuted

Hatched and dashed are the two absences drawn apart on purpose: not-counted means no measurement was taken and is never a zero; truncated means the total is unknown and must never be used as a denominator. Each state also carries a spoken announcement — transitions, never ticks.

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is destructive on background at 7.60:1 (harbor · light), against a floor of 3:1.

Measured WCAG contrast ratios per token pair and theme
PairinterlacelightinterlacedarkharborlightharbordarkFloor
destructive on backgrounddestructive tint on the page surface8.31:110.43:17.60:110.03:13.0:1SC 1.4.11
muted-foreground on backgroundsecondary copy9.41:111.32:17.82:19.52:14.5:1SC 1.4.3
destructive on carddestructive tint inside a card8.31:19.66:18.02:19.09:13.0:1SC 1.4.11
muted-foreground on cardsecondary copy in a card9.41:110.48:18.25:18.64:14.5:1SC 1.4.3
primary on backgroundprimary tint on the page surface8.80:111.79:18.39:110.03:13.0:1SC 1.4.11
primary on cardprimary tint inside a card8.80:110.92:18.86:19.10:13.0:1SC 1.4.11

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

A chart's alt text is not a sentence about the chart — the equivalent of the data is the data. This is what a screen reader gets, read out of the source the install writes into your tree.

Label, not a data equivalentShips sr-only copy

Ships sr-only copy for what the visual carries by position, colour or icon alone — a label, not a full data equivalent.

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary
server component

Renders during SSR / RSC with no hydration cost. It can be imported from a server component without pulling the page into the client.

Minimum viewport
MIN_VIEWPORT = 320

Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.

Coverage gate
100% × 4

Inside the v8 gate: lines 100, statements 100, functions 100, branches 100. A threshold under 100 only records how much you stopped caring, so there isn't one.

History

This component is at v1.0.0, first shipped in @interlace/ui 1.1.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

@interlace/ui 1.1.01 entry

  • Addedminor

    Absence becomes a first-class value. DataState grows from four states to nine, and two new primitives consume the union as a contract rather than each re-deriving it from a boolean ladder. The states are loading · error · not-applicable · not-counted · empty · partial · truncated · first-measurement · idle, and that list is also the precedence order — lowest wins. Error beats empty, because a failed fetch is not "no results". Truncated is not empty at all: it qualifies a body that still renders. States co-occur, so resolveDataState returns the winner AND every loser as qualifiers, the wrapper publishes them as data-qualifiers, and the announcement says all of them — a list that is both partially covered and truncated is wrong twice and now says so twice. Each state is drawn distinctly and, more importantly, **announced**. A diagonal hatch means no run happened; a dashed outline means not yet real; the accent is spent on first-measurement alone, because it is the only absence a reader can act on. Every one of those carries a sentence via announceDataState — "Not counted. No measurement was taken; this is not a zero." A hatch that exists only in pixels keeps the distinction for sighted readers and destroys it for everyone else, and axe scores that green. StatStrip is the dense measurement grid that appeared in all six of the audited artifacts, hand-rolled four times: mono micro-label, tabular-nums value, optional note, optional delta, on a <dl> so every number keeps its label. It renders the three-state null honestly — a metric with prior: null shows "first measurement" and the caller's delta node is **not rendered at all**, so there is no path by which a missing prior reaches the DOM as +0%. Meter absorbs three hand-rolled bars (an odds bar, a score meter, a reviewer bar). Magnitude is carried by length AND by the printed number, never by hue, and the number is not optional. value: null hatches by default rather than drawing an empty bar, because an empty bar and a measured zero are the same picture. variant="dead" recedes without vanishing, for a dormant row that still holds its rank. RankedBarList is the repeated-row composition and supports a labelled log scale, so a 10k row and a 10M row can share an axis. Pure logic ships alongside as data-state-model and meter-scale — the union, the precedence, the announcements, the scale maths — with no React import, exported for callers wiring their own state. Skeleton gains meter and stat-strip variants, both composites, so the loading state reserves the real silhouette on the real breakpoints. Not included, deliberately: the domain vocabularies these were extracted from (authority, visibility, dormant, unwritten, ungated) stay in their artifacts as labels a caller passes in. They are subject-matter, not design system — the DS ships the two axes underneath them (does it recede or does it act, and did a run happen) rather than nine nouns it cannot define.

Import

27 named exports — pull the parts you need.

Public API
import { DATA_STATES, DATA_STATE_PRESENTATION, DataStateEmphasis, DataStateName, FILL_WIDTH_CLASSES, HATCH_CLASS, HATCH_CLASS_FAINT, LOG_FLOOR, MIN_VIEWPORT, Meter, MeterScaleKind, MeterTone, MeterVariant, QUALIFYING_STATES, REPLACING_STATES, RankedBarList, announceDataState, clamp01, compactMagnitude, describeMeter, fillWidthClass, meterDomainMax, meterFraction, presentationFor, rankByValue, replacesBody, resolveDataState } from '@/components/ui/meter';

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

MeterProps

Also accepts every <div> attribute.

PropTypeDescription
label*React.ReactNode
value*number | nullThe measurement. `null` means UNMEASURED and renders the hatch — it does NOT render a zero-length bar, because a zero-length bar and a measured zero are the same picture.
maxnumber | nullThe denominator. `null` or omitted means there is no stated maximum, so no fraction can be computed and the bar draws as hatch — a bar without a denominator is a length with no scale behind it.
unitstring
scaleMeterScaleKindLinear (default) or logarithmic. Log must be labelled by the caller.
fractionnumber | nullOverride the computed fill fraction, `0..1`. For the odds-bar case where the ratio being drawn is not `value / max` — e.g. a probability drawn beside an absolute count.
displayReact.ReactNodePrinted magnitude. Defaults to a compact form of `value`.
noteReact.ReactNodeSecond line under the bar — provenance, window, caveat.
variantMeterVariant
toneMeterTone
size'sm' | 'md'
stateDataStateFlagsAbsence flags for this row, over and above the value being `null`.
announceAnnouncementOptions
loadingboolean

RankedBarListProps

Also accepts every <section> attribute.

PropTypeDescription
rows*readonly RankedBarRow[]
captionReact.ReactNodeVisible caption. Also the list's accessible name.
maxnumber | nullThe shared denominator. Omit and it is the largest MEASURED value — `null`s are skipped rather than counted as zero, so an all-unmeasured list yields no domain and every row hatches.
scaleMeterScaleKind
order'descending' | 'given'`descending` (default) sorts by value with unmeasured rows last; `given` keeps the caller's order, for a list whose order is the argument.
size'sm' | 'md'
stateDataStateFlagsList-wide absence. `truncated` is the one to reach for: it is the state that stops a top-10 from being read as a denominator.
announceAnnouncementOptions
loadingboolean
loadingRowsnumberRows to reserve while loading.

Skeleton

Pass loading and the component renders a shape-matched <Skeleton /> in its own place — same box, so nothing reflows when the data lands. Below is the same story with loading={true}.

Meter — loading stateprimitives-meter--loading
Usage
<DATA_STATES loading={isPending} />

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour
Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13)
Not focusable — no focus indicator required.
Reduced motion
No animation to gate.
ARIA in the source
  • role="meter"
  • aria-label
  • aria-valuemax
  • aria-valuemin
  • aria-valuenow
  • aria-valuetext

Examples

9 more states from the same story file.

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

RuleConceptWhere
R4Extends native el`React.ComponentProps<'div'>`
R6data-slot on every part`data-slot="meter" / "-track" / "-fill" / "ranked-bar-list"`
R8No `isXxx`; enums for >2 states`variant` (default/hatch/dead), `tone`, `size`, `scale`
R10Composition seams`note` / `display` ReactNode slots
R11One variable per partthe list owns the domain; a row owns its own tone and state
R14Declares min viewport`data-min-viewport={String(MIN_VIEWPORT)}` + exported const
R18Tailwind onlywidth comes from `fillWidthClass`, never `style={{width}}`
R19Tokens only`bg-secondary`, `bg-primary`, `--viz-positive/-negative`
R20AA contrasttable below
R25Server componentpure render — no hooks
R26A11y`role="meter"` + `aria-valuenow/min/max` + `aria-valuetext`

Minimum viewport

This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.

Opt-in to the dev-mode warning
<body data-interlace-dev>...</body>

Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.

Dependencies

Base UI primitive
Native / no Base UI dependency
Lucide icons
none
NPM dependencies
none

Source

The full implementation — components/ui/meter.tsx once installed.

489 lines · TypeScript
import * as React from 'react';

// @interlace/meter v1.0.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/meter
// What changed since: https://ds.interlace.tools/c/meter#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Meter and RankedBarList
 *
 * ONE inline bar, absorbing three that were hand-rolled separately across the
 * phase-10 corpus: an odds bar, a score meter and a reviewer bar. They differed
 * in tone and in what the denominator meant; they did not differ in anything
 * that justified three components, and each of the three had reinvented the
 * "there is no number here" case slightly differently.
 *
 * ## Length and number. Never hue.
 *
 * Every magnitude is carried twice — by the **length** of the fill and by the
 * **printed value** — and the value is not optional. Colour carries tone

…469 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.