Kit part · Charts · Progress

Ring meter

The kit’s donut chart as an instrument: a ring of lamps behind dark glass in a spun bezel, lit clockwise from twelve like a studio clock’s seconds, with the value in lit digits in the middle.

Element: <tui-ring>
Needs: kit.css + kit.mjs
Rules: ring.rules.md · 5
Finishes: Aluminium · Graphite · Porcelain · Black
Volumes: Tactile · Quiet

On this page

Variants
Every state, at once
API
Markup
Accessibility
How it’s built
Rules
Related parts

Variants

A share · with an inner ring

Countdown · what is left

Time left · one amber colour

40 lamps · no inner ring

Every state, at once

Both finishes, side by side. Hover, pressed and focus are forced with .is-hover, .is-down and .is-focus; checked and disabled are real.

Aluminium

Part	Empty	Under way	Past warning	Past alarm	Full	No reading
Filling
Countdown

Graphite

Part	Empty	Under way	Past warning	Past alarm	Full	No reading
Filling
Countdown

API

Name	Kind	Values	What it does
<tui-ring>	element	builds its own inside	The meter: bezel with a zero mark, glass, the lamps (and inner dots), the lit reading and its name.
value	attribute · property	number	The reading. Setting it steps the lamps round: a whole turn in about half a second.
min · max	attribute	0 · 100	The scale: the full ring.
label	attribute	required	Printed in the glass under the digits, and the meter’s accessible name.
unit · unit-text	attribute	"%" · "percent"	Beside the digits; the spoken form for aria-valuetext.
warn · alarm	attribute	numbers in the scale’s units	Where every lit lamp turns amber, then red. Alarm under warn means low is bad (a budget left).
lamp	attribute	"green" · "amber" · "red" · "blue" · "white"	The colour below the lines, or the one colour: amber for a run that is still working.
segments	attribute	12–72 · 50, or 60 for time	Lamps round the ring. 50 is 2% a lamp; 60 is a clock’s seconds.
inner · inner-label	attribute · property	number · "Reserved"	A second share on small dots inside, lit in display light, with its own line of words.
mode	attribute	"countdown"	The ring is what is left: lamps go out from twelve, clockwise, as the value runs down.
format	attribute	"time"	The value is seconds, shown as 4:12 and said as “4 minutes 12 seconds”.
decimals	attribute	auto from the range	Decimals in the digits and the words.
--size	CSS property	180px	The meter’s width; it never grows past its container. The digits scale with it.
data-zone · data-lamp · data-state	attribute	written by the part	The line the value is past, the lamps’ colour, and whether the lamps are stepping.
Keyboard	keyboard	none	Nothing in it takes focus: a meter is read, not operated. Its value is in the accessibility tree.

Markup

<tui-ring label="Quota used" unit="%" unit-text="percent"
    value="72" warn="80" alarm="95" inner="85" inner-label="Reserved"></tui-ring>

<!-- What is left: the dark arc grows from twelve -->
<tui-ring label="Error budget left" unit="%" mode="countdown"
    value="38" warn="25" alarm="10"></tui-ring>
<tui-ring label="Run 4f2a · left" mode="countdown" format="time"
    max="600" value="252" lamp="amber"></tui-ring>

import '/kit/kit.mjs';   // defines <tui-ring>

const quota = document.querySelector('tui-ring[label="Quota used"]');
const usage = await fetch('/api/usage').then((r) => r.json());   // { used: 0.74, reserved: 0.86 }
quota.value = Math.round(usage.used * 100);                       // lamps step round to it
quota.inner = Math.round(usage.reserved * 100);

// A run's time left: one reading a second.
const left = document.querySelector('tui-ring[format="time"]');
setInterval(() => { left.value = Math.max(0, (deadline - Date.now()) / 1000); }, 1000);

Needs kit.css and kit.mjs. How to install the kit.

The element is a role="meter" named by its label, with aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext that carries both rings and the line: “72 percent, reserved 85 percent” or “22 percent, down to the warning line at 25”.
Countdown time is said in words, “4 minutes 12 seconds left”, not as “4:12”.
The lamps, the dots and the digits are its picture and are hidden from assistive technology. It takes no focus.
Colour is never alone: the digits give the figure, the arc gives the share, and the words name the line.
Reduced motion: the lamps jump to the reading. Nothing blinks.

How it’s built

Plain DOM. Every lamp is an <i> placed once, by trigonometry, at its share of the ring: never rotated, so each lamp’s highlight stays upper left like every lamp in the kit. A frame toggles is-on only on lamps that change, and the level steps at a steady rate so a whole turn takes about half a second and one lamp about a tenth. The glass is the kit’s display black with a glare fixed upper left; the bezel is the knob’s spun metal with an engraved zero mark at twelve. The digits are Geist Mono in the VFD’s light and sized in container units, so a ring of any size keeps its proportions. The loop sleeps when the lamps arrive, pauses off screen and in a hidden tab, and clamps a frame to 1/30 s.

Rules

ring.rules.mdIn the brain

One share per ring, read from the mark at twelve. The lamps change colour only at the lines the job sets; the digits in the middle carry the figure.

5 rules in this file, with the foundations they rest on and the anti-patterns that break them. Full rules ship in the brain with the Pass.

See the Founder Pass How agents use the brain

Lamp

VFD

Progress