/// Data Display

StatusDot

A small sharp square that encodes a status tone, with an optional live pulse.

import { StatusDot } from "@protocore/pds";

View as Markdown

Basics

A StatusDot next to a text label is the canonical pattern: the label carries the meaning, the dot gives it a fast colour cue. Five tones, matching the Badge palette.

Healthy

Degraded

Offline

Unknown

Live pulse

Add pulse to softly animate the dot for a genuinely live or active state — a streaming feed, an in-progress reindex. Reserve it for real-time signals so the animation stays meaningful.

Streaming events

Reindexing

Idle

Standalone in a grid

In a dense table a bare dot saves horizontal space. When the dot stands alone (no adjacent text), aria-label is required so status is never conveyed by colour alone — the component takes role="img" automatically when labelled.

Node	Region	Health
node-eu-1	eu-central-1
node-eu-2	eu-central-1
node-us-1	us-east-1

When to use it

StatusDot is the most compact way to show a health/status tone — right for tight rows and grids where a full Badge would be too heavy. Reach for a Badge instead when you have room and want a legible word ("Degraded") rather than just a coloured square; reach for MetricDelta when the thing you're signalling is a *direction of change*, not a state.

The hard rule: a StatusDot never communicates on colour alone. Either it sits beside a text label, or it carries an aria-label. Two greens that mean different things must still differ in their adjacent text.

Usage

Pair the dot with a text label wherever space allows.
Give a standalone dot an `aria-label` describing the status in words.
Reserve `pulse` for truly live states so it keeps its signal value.
Keep tone→meaning consistent with Badge across the product.

Don't

Don't rely on colour alone — no label and no `aria-label` is a failure.
Don't pulse static states; a page full of pulsing dots reads as noise.
Don't use a dot where a word would be clearer and there's room for a Badge.
Don't invent tones beyond the five semantic ones.

Accessibility

When given an `aria-label`, StatusDot renders with `role="img"` so assistive tech announces the status as a labelled graphic.
Without a label it is presentational — that mode is only valid when an adjacent visible text label already states the status.
The `pulse` animation is purely decorative; it conveys no information beyond the tone + label and respects the platform's reduced-motion preference.

Mobile (React Native)

Preview. @protocore/pds-mobile ships the React Native sibling of StatusDot. It mirrors the web API where React Native allows; the package is a preview with no device-level QA yet, so pin it and expect small changes.

Import it from the mobile package (not @protocore/pds), inside a <PdsProvider> — there is no stylesheet, so style (a ViewStyle) replaces className and every value comes from the theme:

import { StatusDot } from "@protocore/pds-mobile";

Parity with web. An 8dp sharp tone indicator with an optional pulse.

The pulse is an Animated opacity loop that honours the OS "reduce motion" setting (web uses a CSS keyframe gated by prefers-reduced-motion).
accessibilityLabel is required when the dot stands alone, so status is never color-only; it sets accessibilityRole="image".

<StatusDot tone="success" pulse accessibilityLabel="Service healthy" />

`StatusDot` props

Prop	Type	Default	Description
`aria-label`	`string`	—	Accessible label. Required when the dot stands alone (no adjacent text label), so status is never conveyed by color only.
`className`	`string`	—
`pulse`	`boolean`	`false`	When true, the dot softly pulses to signal a live/active state.
`style`	`CSSProperties`	—
`tone`	`enum`	`neutral`	Status tone that fills the dot.