visualization · native chart

TuxChartGauge

270° arc gauge for single-target metrics where one value matters and the target zones are qualitative (success/warning/error) or hard limits. Use sparingly — research dashboards rarely need gauges. Good fits: token utilization, SLA uptime, compliance score. Bad fits: anything contextual (use TuxBigStat + TuxSparkline).

Two variants: arc (default, with needle + bands) and progress (single filled arc, no needle).

flagship · arc with needle

On-time delivery

No bands — neutral track with a needle at value. Use when target zones aren't well-defined; the needle position itself is the signal.

0100

On-time delivery

78%

<tux-chart-gauge
  :value="78"
  :min="0"
  :max="100"
  center-label="On-time delivery"
  :center-value="78"
  units="%"
/>

arc with tone bands

Token utilization

Pass bands to mark target zones. Each band has from, to, and either an tone (success / warning / error — status tokens) or a toneIndex (1..8 chart palette). The needle reads against the bands.

0100

Token utilization

72%

<tux-chart-gauge
  :value="72"
  :min="0"
  :max="100"
  :bands="[
    { from: 0,  to: 60,  tone: 'success'    },
    { from: 60, to: 85,  tone: 'warning'  },
    { from: 85, to: 100, tone: 'error' },
  ]"
  center-label="Token utilization"
  :center-value="72"
  units="%"
/>

progress variant

Radial progress

Pass variant="progress" for a single filled arc with no needle and no bands. Better for percent-of-max ("X tokens of Y context") where there are no qualitative zones.

08,000

Context used

6,420 tok

<tux-chart-gauge
  variant="progress"
  :value="6420"
  :min="0"
  :max="8000"
  center-label="Context used"
  :center-value="6420"
  units=" tok"
/>

progress + tone

SLA uptime

Bands work in progress mode too — the fill color picks up the band tone the current value falls into. Here, 99.84% sits in the ok zone (above 99), so the arc draws green.

95100

API uptime

99.84%

<tux-chart-gauge
  variant="progress"
  :value="99.84"
  :min="95"
  :max="100"
  :bands="[
    { from: 0,  to: 95,  tone: 'error' },
    { from: 95, to: 99,  tone: 'warning'  },
    { from: 99, to: 100, tone: 'success'    },
  ]"
  center-label="API uptime"
  :center-value="99.84"
  units="%"
/>

when not to use a gauge

Reach for BigStat instead

If the metric doesn't have a single normative target (e.g. "files ingested per month" — bigger is *usually* better, but the answer is contextual), use TuxBigStat plus TuxSparkline for the trend. Gauges imply normativity that research data often doesn't have.