Gauge
Semi-circle gauge: segments laid end to end, clamped to max; one image to AT, the legend as text.
import { Gauge } from '@ergasti/bricks';Examples
Seat usage
A half-ring split into segments; max is the full scale and center is what sits in the middle.
Code
import { Button, Card, Gauge } from '@ergasti/bricks';
function Seats() {
return (
<div style={{ maxWidth: 420 }}>
<Card>
<Card.Header title="Seat usage" sub="How many creators your plan lets you have" actions={<Button size="sm">Raise limit?</Button>} />
<Card.Body>
<Gauge
label="Seat usage"
max={400}
center={<><b>321<span className="kit-muted" style={{ fontSize: 16 }}> / 400</span></b><span className="kit-muted">seats used</span></>}
segments={[{ value: 304, label: 'Selected', tone: 'rasp' }, { value: 17, label: 'Reserved', tone: 'rasp-soft' }, { value: 79, label: 'Remaining', tone: 'track' }]}
/>
</Card.Body>
</Card>
</div>
);
}Value and caption
Pass value and the gauge draws "321 / 400" itself: the value big, " / max" small and muted, kept left-to-right in Arabic; caption is the small line under it. A free center is still there for anything else.
Code
import { Card, Gauge } from '@ergasti/bricks';
function ValueAndCaption() {
return (
<div style={{ maxWidth: 420 }}>
<Card>
<Card.Header title="Seat usage" />
<Card.Body>
<Gauge
label="Seat usage"
max={400}
value={321}
caption="seats used"
segments={[{ value: 304, label: 'Selected', tone: 'rasp' }, { value: 17, label: 'Reserved', tone: 'rasp-soft' }, { value: 79, label: 'Remaining', tone: 'track' }]}
/>
</Card.Body>
</Card>
</div>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses Gauge. Written in docs/content/components/Gauge.md; the props above are read from the code, which wins where the two disagree.
A semi-circle gauge that lays segments end to end against a maximum, with a big "value / max" in the middle and a legend below; use it for capacity such as seat usage.
Gauge is the mock's seatCard() half-donut on Brand › Home: a 220 × 120 SVG arc (radius 90, 18px round-capped stroke) over a grey track, one coloured arc per segment, clamped so the total never passes max. The centre shows the headline number ("321 / 400", "seats used") and a centred legend lists each segment with its count. Assistive tech gets one image whose name lists every segment.
Anatomy
- Track: the full arc in
--track. - Segment arcs: one per segment with
value > 0, laid end to end from the left, in the segment'stone; a segment withtone: 'track'is not drawn (it is the remaining space). - Centre (
.kit-gauge-v):valuein Jakarta 30/800 with " / max" muted 16/700, andcaptionmuted 12px under it; or the freecenternode. - Legend (
ul.kit-legend--center): a 9px swatch,legend ?? label, and the value, per segment.
Variants
Segment tone (ChartTone):
| Tone | Colour | Use |
|---|---|---|
'rasp' | --rasp | The main quantity ("Selected") |
'rasp-soft' | --rasp-soft | A held or pending share ("Reserved") |
'track' | --track (not drawn on the arc) | What is left ("Remaining"): legend only |
'butter' | --chart-butter | Extra category |
'lime' | --chart-lime | Extra category |
'sky' | --sky-ink | Extra category |
'ink' | --ink | Extra category |
Centre: value (+ caption) for the standard "321 / 400"; center for anything else.
States
| State | Trigger | Look |
|---|---|---|
| Default | segments below max | Arcs cover part of the track |
| Full | segments sum ≥ max | Arc closes the semicircle; overflow is clamped |
| Empty | all coloured segments 0 | Only the grey track |
| No max | max <= 0 | No arcs drawn (avoids division by zero) |
| Negative value | segment value < 0 | Treated as 0 on the arc; the legend still prints the raw value |
Types
GaugeSegment.legend replaces the label in the legend only (a Term with its tooltip).
GaugeSegment (segments): { value: number; label: string; tone: ChartTone; legend?: ReactNode }, in arc order. label is also the React key: keep it unique.
Usage
The Home seat card, with terms in the legend:
<Card>
<Card.Header title="Seat usage" sub="How many creators your plan lets you have"
actions={<Button size="sm">Raise limit?</Button>} />
<Gauge label="Seat usage" max={400} value={321} caption="seats used"
segments={[
{ value: 304, label: 'Selected', tone: 'rasp', legend: <Term tip="Creators in your program now. Each uses a seat.">Selected</Term> },
{ value: 17, label: 'Reserved', tone: 'rasp-soft', legend: <Term tip="Seats held for invites still waiting for a reply">Reserved</Term> },
{ value: 79, label: 'Remaining', tone: 'track', legend: <Term tip="Seats you can still fill">Remaining</Term> },
]} />
</Card>A custom centre:
<Gauge label="Gift stock" max={120} center={<b>All claimed</b>}
segments={[{ value: 120, label: 'Claimed', tone: 'lime' }]} />Where it appears
- Brand › Home › Seat usage card (with "Raise limit?" in the header).
- Screen: Home.
Guidelines
Do
- Make the segments add up to
max, ending with a'track'"Remaining" segment so the legend explains the grey part. - Use
value+captionrather than hand-building the centre: it gets the mock's type and LTR digits. - Keep 2 to 4 segments.
Don't
- Don't give two segments the same
label(it is the key and part of the accessible name). - Don't use it for a trend or a share of revenue: use
StackBar. - Don't squeeze it below 220px wide; the SVG is fixed at 220px.
RTL and Arabic
- The arc does not mirror; it fills left to right in both languages.
- "321 / 400" is
dir="ltr"so the order stays value-first in Arabic. - The legend follows the page direction (swatch at the inline start).
Tokens
--track, --rasp, --rasp-soft, --chart-butter, --chart-lime, --sky-ink, --ink (segments), --font-family-display (value), --ink-3 (max, caption), --ink-2 (legend text).
Accessibility
- The arc and centre are one
role="img"witharia-label="{label}: Selected 304, Reserved 17, Remaining 79"; the SVG itself isaria-hidden. - The legend is a real list and stays readable; a
Terminlegendkeeps its own focusable tooltip. - Colour is never the only cue: each swatch sits next to its label and number.
Found in the source
- Roles in the markup:
img. - ARIA attributes set:
aria-label,aria-hidden.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
StackBar: the same idea as a straight bar (commission status, wallet held/free).Legend: the legend on its own.UsageMeter/UsageBar: linear usage against a limit.
See also: Card · Button · AreaTrend · BarChart · HBars
Source
src/kit/patterns/Gauge.tsx (line 58) on GitHub.