An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:StatusDot authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/StatusDot/StatusDot.test.tsx, packages/core/src/theme/themingTargets.test.ts, packages/core/src/theme/extensibleAxes.test.ts, apps/storybook/stories/StatusDot.stories.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:public-component-api, architecture:theme-tokens, ] contributing: []
system_specs: [spec:AST-009, spec:AST-094]
StatusDot component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | A fixed 8px status dot with a required theme-extensible variant and a required label, plus optional isPulsing, tooltip, and icon. |
| Behavior | The dot is an image named by label; a renderable icon paints inside it in the variant's ink and is hidden from assistive technology; a standalone dot with a tooltip is a button named by label whose press pins the tooltip (component:Tooltip DEC-1), so the tooltip is reachable by hover, touch, and keyboard; inside a button, link, menu item, or option, the dot stays an image and the host's accessible name carries the tooltip text (FR5). |
| End-user impact | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. Inside a button, link, menu item, or option, sighted touch users lose the dot's visible tooltip text, and the host's accessible name carries the status for screen readers (FR5). |
| Builder impact | StatusDot decides by placement. A standalone dot with a tooltip is a toggle button; inside a button, link, menu item, or option, the host carries the status in its accessible name, so a control never nests another control (FR5). A host named by aria-label, such as a Tab with isLabelHidden, takes no name from its content, so its caller includes the status in that label. |
| Compatibility/readiness | No API or default change; a standalone dot with a tooltip becomes a button trigger whose press pins the tooltip once useTooltip's show() and hide() (component:Tooltip DEC-1) ship, and a dot inside an interactive element hands its tooltip text to the host (FR5, not yet built). Three gaps are listed under Current-state impact. |
| Review checks | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target. |
| Governing rules | architecture:component-theming-surface/INV2,INV6,INV14; architecture:public-component-api/INV5,INV6,INV8; architecture:theme-tokens/INV11; WCAG 2.2 2.1.1. |
This table is a review projection; the body below is authoritative.
Intent
StatusDot renders a compact painted status signal — presence, health, or severity — beside content that explains it. It owns the dot's size, tones, optional pulse, optional inner mark, and its accessible name.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: no public prop or default change. FR2's status dots
(
success,warning,error) repaint from the strong status fill to the status icon role, with the surface as ink, a visible color change in every theme whose icon and fill roles differ; with atooltip, a standalone dot becomes a button named bylabelinside Tooltip whose press pins the tooltip, adopted onceuseTooltip'sshow()andhide()(component:TooltipDEC-1) ship, and a dot inside a button, link, menu item, or option stays an image whose tooltip text joins the host's accessible name (FR5). The dot emits only the canonicalstatus-dottarget; thestatusdotalias is not emitted - Controlled/uncontrolled behavior: not applicable; StatusDot holds no state
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Theme-added variant without paint (FR2).
StatusDotVariantMapadmits theme-added values, but a value the active theme does not paint renders a transparent dot with no visible signal. The accessible name still carries the status.architecture:component-theming-surfaceINV14 requires an extensible visual axis to have a safe theme-independent baseline. - Tooltip not reachable by keyboard (FR5). The dot has no tab stop, so
Tooltip attaches no focus trigger and sighted keyboard users cannot reveal
the tooltip text, where WCAG 2.2 2.1.1 expects functionality to be keyboard
operable. The accessible name still carries the status. Today a tap opens a
dot's tooltip, because the dot performs no action and Tooltip's default
touch behavior (
touchTrigger="auto") opens on such a tap, and a standalone dot does not yet pin its tooltip on a press, so its tooltip has no pin for touch or keyboard. FR5 changes a dot inside a button, link, menu item, or option to an image whose tooltip previews on hover only, so sighted touch users lose its visible tooltip text there; the host's accessible name carries the status for screen readers. - Accent and neutral dots in forced colors (FR2). The
accentandneutraldots draw no border, so in forced-colors mode they lose their plate and disappear; no current record sets their treatment (OQ1). The accessible name still carries the status.
Ownership boundary
Owns
- The painted dot, its
status-dottheming target, and its fixed size. - The variant's plate and ink pairing.
- The pulse and its reduced-motion suppression.
- The assistive-technology-hidden wrapper that places optional icon content inside the dot.
- The dot's image role, its button role when it is standalone with a tooltip, and its accessible name.
Does not own / non-goals
- The artwork supplied through
icon— owned by the caller. - The tooltip surface and its open triggers when
tooltipis supplied — owned by Tooltip. - A built-in icon per variant — the default dot stays childless.
- The visible label or surrounding text that explains the status — owned by the product callsite.
- The status dot overlaid on an avatar — owned by
component:AvatarStatusDot.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
Tone (variant) |
success, warning, error, accent, neutral; theme additions |
Selects the plate color and the ink an icon paints with. | All dots | Required | component:StatusDot |
Stable | A theme-added value is reflected on status-dot and keeps a safe theme-independent baseline (FR2); TypeScript rejects unregistered values. |
| Pulse | resting; pulsing | Signals ongoing activity by fading the dot in and out. | All tones | resting | component:StatusDot |
Stable | — |
| Status icon | present when icon is renderable; absent |
Adds a non-color mark inside the dot. | All tones | absent | component:StatusDot |
Stable | false, true, null, undefined, and '' render no icon wrapper. |
| Tooltip | present when tooltip is a non-empty string; absent |
Explains the status; a standalone dot becomes a button whose press pins it, reachable by hover, touch, and keyboard; inside an interactive element the host carries the text (FR5). | All tones | absent | component:StatusDot |
Stable | An empty string renders no tooltip. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | StatusDot always renders one inline-flex span dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the status-dot target and only that target. |
Current source and tests |
| FR2 | success, warning, and error are status marks on the page: under architecture:theme-tokens INV11 each paints its status icon role, --color-icon-<status>, with the surface color as ink, and keeps a visible CanvasText border in forced-colors mode. accent paints --color-accent with --color-on-accent ink, and neutral paints --color-icon-secondary with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects variant for every value, and an extensible tone has a safe theme-independent baseline (architecture:component-theming-surface INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). |
Current source and tests |
| FR3 | isPulsing animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under prefers-reduced-motion: reduce the animation is removed and the dot rests. |
Current source and tests |
| FR4 | A renderable icon renders in a wrapper centered inside the dot and filling its 8px field; it paints from currentColor, the variant's ink. A non-renderable value leaves the dot childless. |
Current source and tests |
| FR5 | A non-empty tooltip renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and is a button trigger whose press pins it, named by label, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (component:Tooltip FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the pin through useTooltip's show() and hide() (component:Tooltip FR12), as component:InfoTip does, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the pin, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (architecture:interaction-modality INV4). A host named by aria-label takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). |
Current source and tests; component:Tooltip DEC-1, FR9, FR12 |
| FR6 | ref reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; xstyle, className, and style merge in that order after component styles. |
Current source and tests |
Allowed variation
- AV1 — Theme paint. A theme may change the dot's visual properties per
variantthroughstatus-dotwithout changing its size, name, or anatomy. - AV2 — Icon artwork. Caller-supplied artwork may vary without creating a separate target.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Plain dot | Childless image named by label; not focusable. |
Tone. |
| With icon | Icon inside an aria-hidden wrapper; the dot keeps its role and name. |
Artwork. |
| Pulsing | Opacity pulse runs; with reduced motion requested, it does not. | Tone. |
| With tooltip | A standalone dot is a button named by label with aria-expanded; a press pins the tooltip; Tooltip owns the surface. |
Tooltip text. |
| Inside a control | Inside a button, link, menu item, or option, the dot is an image with no tab stop; the host's accessible name includes the tooltip text. | Host component. |
Transformation and precedence order
- ORD1 — Dot attributes. The role first follows placement: a standalone dot
with a tooltip is the toggle's
button; a dot without a tooltip, or inside a button, link, menu item, or option, isrole="img". Thenaria-label→ component class anddata-variant→ component styles →xstyle→className→style→ caller props.
Performance and resources
- PR1 — CSS-only motion. The pulse is a CSS animation; StatusDot registers no listener, observer, or timer of its own beyond the shared hit-area watch AR2 requires for a standalone dot with a tooltip.
Accessibility contract
- AR1 — Name without hover. The dot exposes
role="img"withlabelas its accessible name for every variant, with or without an icon; standalone with a tooltip it is a button with the same name, and inside an interactive element its tooltip text joins the host's accessible name (FR5). A callerroleoraria-labelreplaces them (FR6). - AR2 — Tab stop. A dot without a tooltip is a static image and adds no
tab stop of its own. A standalone dot with a tooltip is a button in the tab
order whose press pins the tooltip (FR5), and a dot inside an interactive
element never adds a tab stop; today the dot adds no tab stop, which is the
FR5 gap. Under a coarse pointer, a standalone dot with a tooltip reaches 44 px
through an invisible hit area from the shared hit-area watch where its
neighbors leave room: the hit area never overlaps a neighbor's target and is
clamped to half the gap between close neighbors (
spec:AST-094FR42); implementation gap: not yet built. A callertabIndexpasses through (FR6). - AR3 — Decorative icon. The icon wrapper is
aria-hidden, so the label alone names the status. - AR4 — Color is not the only carrier. The accessible name carries the
status for assistive technology. Visually, the default dot is a color-only
signal; a non-color mark comes from a per-status
iconor from the surrounding UI, which the callsite owns. - AR5 — Reduced motion. The pulse stops when the reader asks for reduced motion (FR3).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Dot | Presents the painted semantic-status signal. | Current source and public docs | Supporting | FR1–FR3, AR1, AR2 |
| Status icon | Presents optional caller-supplied artwork inside the dot. | Current source and tests | Supporting | FR4, AR3 |
Theming anatomy
{
"Dot": {"target": "status-dot"},
"Status icon": {"inherits": "status-dot"}
}
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, inheritance, canonical target naming, and the extensiblevariantaxis; FR2 records the unthemed fallback.architecture:public-component-apiowns ref, passthrough, and styling-input rules; FR6 applies them to the dot.architecture:theme-tokensINV11 owns the status color roles and their forced-colors border, which FR2's status plates follow.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR6 | StatusDot.test.tsx render, ref, test-id, and target suites |
Every tone | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in StatusDot.stories.tsx. |
audit:StatusDot/anatomy |
| FR2 | StatusDot.test.tsx variant-ink suite; extensibleAxes.test.ts |
Status plates and ink; map wiring | Dropping variant reflection fails. The variant-ink test pins each status's --color-icon-<status> plate with the surface ink, and the forced-colors test asserts the compiled CanvasText outline. Gap: other tones' paint and the unthemed fallback have no automated check. |
audit:StatusDot/theming |
| FR3, AR5 | StatusDot.stories.tsx in a browser, with and without reduced motion |
Resting and pulsing | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture. | audit:StatusDot/motion |
| FR4, AR3 | StatusDot.test.tsx custom-icon suite |
Icon, falsy values | Exposing the icon or rendering a wrapper for a falsy value fails. | audit:StatusDot/anatomy |
| FR5, AR1, AR2 | StatusDot.test.tsx focusability and accessible-name suites; evidence gap until built: standalone toggle cases and the coarse-pointer hit area; a dot with a tooltip inside a Button and inside a MenuItem |
Every tone, with and without tooltip; a standalone dot with a tooltip; a dot inside a Button and inside a MenuItem | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller role or aria-label override. Once FR5 is built, a standalone dot with a tooltip that is not a named button, that a tap, click, Enter, or Space does not pin, fails. A dot inside a Button or a MenuItem that renders a nested button or tab stop, opens its tooltip on a tap, or whose host's accessible name lacks the status, fails. A standalone dot with a tooltip whose coarse-pointer hit area stays under 44 px where its neighbors leave room, or reaches a neighbor's target, fails. |
audit:StatusDot/a11y |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | audit:StatusDot/theming |
| AR4, PR1 | Source review; StatusDot.stories.tsx |
Plain dot, dot with icon | Gap: no automated check covers the non-color mark guidance or fails if StatusDot adds its own listener, observer, or timer. | audit:StatusDot/a11y |
| AR1, AR3 | Accessibility-tree evidence (spec:AST-009 FR3) |
Every tone, with icon and tooltip | Gap: no accessibility-tree check proves the image role and name or the hidden icon; the unit tests query the DOM. | audit:StatusDot/a11y |
Decision log
None recorded. The tooltip's pin follows component:Tooltip DEC-1.
Open questions
- OQ1 — What forced-colors treatment should the
accentandneutraldots have? (human-design) They are not status roles underarchitecture:theme-tokensINV11, and today they render with no visible plate in forced-colors mode.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.