HalfGauge
A semicircular 0-100 dial for a single neutral progress or score value, with a low-to-high gradient sweep and clamped out-of-range input.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/visualizations/HalfGauge/HalfGauge.stories.tsxExport DefaultImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A semicircular 0-100 dial for a single neutral progress or score value, with a low-to-high gradient sweep and clamped out-of-range input.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { HalfGauge } from '@cloakedinc/design-system';HalfGaugeHalfGaugeProps
packages/design-system/src/components/visualizations/HalfGauge/HalfGauge.tsx:15
| Prop | Type | Presence | Notes |
|---|---|---|---|
value | number | Required | Gauge value from 0 to 100. |
ariaLabel | string | undefined | Optional | Accessible label for meaningful gauge values. |
testId | string | undefined | Optional | Optional test selector. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A semicircular 0-100 dial for a single neutral progress or score value — "how far toward complete."
When to use
Use HalfGauge for one bounded value that reads as a share or completion with no severity meaning; values outside 0-100 are clamped.
Reach for RiskMeter instead when the value sits on a severity scale — its track carries a
low-to-high risk gradient and supports a thumb vs pointer marker. Use Progress for a
plain linear bar, and CategoryBars when you are comparing several values rather than showing
one.
Not currently used in the app.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- dial
- Label
- Dial
- Description
- The semicircular SVG that scales to its container.
- Required
- true
- Id
- track
- Label
- Track
- Description
- The unfilled arc behind the value sweep.
- Id
- value-arc
- Label
- Value arc
- Description
- The gradient arc swept from empty to the value.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- The value changes the sweep without changing the dial treatment.
- Sizes
Variants
- Id
- base
- Label
- Base
- Description
- A single gradient semicircle swept to the clamped value.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- max-width
- Label
- Maximum rendered width
- Kind
- example-only
- Token
- --cds-size-120
- Value
- 120
- Unit
- px
- Applies To
- dial
- Notes
- The dial otherwise fills 100% of its container. Its width cap is --cds-size-120 minus --cds-size-8 for optical balance; the arc geometry itself is drawn in SVG view-box units, not tokens, so this is the only token-backed dimension and is example-only.
Layout
- Alignment
- The dial fills its container width up to the cap and keeps its 112-by-62 aspect.
- Flow
- A single arc pair (track plus value) sharing one semicircular SVG.
- Notes
- The arc radius and stroke are SVG view-box units so the dial scales cleanly at any width.
Typography And Color
- Typography
- Label
- Adjacent caption
- Description
- Surrounding value or caption text uses the body-small ramp; the dial draws no text itself.
- Token
- --cds-type-body-small-size
- Colors
- Label
- Track
- Description
- The unfilled arc behind the value.
- Token
- --cds-graph-bg
- Label
- Low value
- Description
- The good end of the gradient sweep.
- Token
- --cds-risk-good
- Label
- Mid value
- Description
- The fair midpoint of the gradient sweep.
- Token
- --cds-risk-fair
- Label
- High value
- Description
- The critical end of the gradient sweep.
- Token
- --cds-risk-critical
States
- Id
- value
- Label
- Value shown
- Description
- The arc sweeps to the clamped 0-100 value and exposes it to assistive technology.
- Id
- empty
- Label
- Empty
- Description
- A zero value shows the track with no swept arc.
- Id
- clamped
- Label
- Clamped
- Description
- Out-of-range values are pinned to 0 or 100 so the arc never overflows.
Behavior
- Label
- Clamped value
- Description
- Values outside 0-100 are clamped so the sweep stays within the arc.
- Label
- Neutral meaning
- Description
- Use HalfGauge for completion or share values with no severity meaning.
- Label
- Scales to width
- Description
- The dial fills its container up to its width cap and keeps a fixed aspect.
Accessibility
- Label
- Meaningful value
- Description
- Pass an accessible label so the dial exposes a progressbar with min, max, and the value.
- Label
- Decorative dial
- Description
- Omit the label to hide the dial from assistive technology when nearby text states the value.
Content Adaptation
- Label
- Neutral vs severity
- Description
- Use HalfGauge for neutral completion; use RiskMeter when the value sits on a severity scale.
- Label
- One value only
- Description
- Use CategoryBars instead when comparing several values rather than showing one.
Motion Haptics
- Motion
- Label
- Sweep transition
- Description
- The value arc eases to a new sweep; honor reduced-motion by letting the platform shorten it.
- Haptics
- Label
- No feedback
- Description
- The dial is a display and requests no haptic feedback.