StatusDot

Tiny semantic status indicator: colored dot with visible or sr-only label.

Status: stable. Group: feedback. Markdown version: /design-system/components/status-dot.md

When to use

StatusDot is the lightest way to show state: a tone-colored dot with a label, sized to sit inline in list rows, nav items, and dashboard lines. The dot is decorative; the label (visible children, or sr-only via label) carries the meaning. Use Badge instead when the status needs a chip surface, a count, or removability.

When not to use

Do not use StatusDot for counts, filters, or removable chips; Badge owns those surfaces.

Look-alikes

Badge: Do not use StatusDot for counts, filters, or removable chips; Badge owns those surfaces.

Props

StatusDot props
Prop	Type	Default	Description	Required
`tone`	`"info" \| "success" \| "warning" \| "error" \| "neutral"`	`neutral`	Semantic tone of the status.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Size token.	No
`pulse`	`boolean`	`false`	Animates a soft pulse for live/ongoing states (respects reduced motion).	No
`label`	`string`	none	Accessible label when no visible children are given (e.g. "Online"). Without children or label the dot carries state by colour alone, so a development warning is logged unless the dot is marked aria-hidden.	No
`children`	`React.ReactNode`	none	Visible label text rendered next to the dot.	No

Variants

Available tones: neutral, success, warning, error, info (default neutral).
Available sizes: sm, md, lg (default md).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

StatusDot rules
Level	Rule	How it is checked
MUST	ARIA: Dot is aria-hidden; meaning carried by visible children or sr-only label.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Color is never the sole carrier of state when children or label is passed; with neither, StatusDot renders a bare dot and logs a development warning (once per session) unless the dot itself is marked aria-hidden="true" because a surrounding element already names the state.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Under forced-colors every tone renders as CanvasText, so the label is the only thing that tells tones apart.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Always pass children or label; a bare dot is invisible to assistive tech and ambiguous to everyone.	Not stated in the contract.
SHOULD	Reserve pulse for genuinely live states (recording, deploy in progress); a static dot reads calmer for steady states.	Not stated in the contract.
SHOULD	Use tone semantically: success=healthy, warning=degraded, error=down, info=transitional, neutral=idle/unknown.	Not stated in the contract.
SHOULD	Keep labels to one or two words; StatusDot is a glance signal, not a sentence.	Not stated in the contract.
SHOULD NOT	Do not encode more states than the five tones; if you need custom colors, the state model is too wide for a dot.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { StatusDot } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/identity exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-status-dot>; see the custom elements manifest.