Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
37.2 KB
Raw Blame

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 a tooltip, a standalone dot becomes a button named by label inside Tooltip whose press pins the tooltip, adopted once useTooltip's show() and hide() (component:Tooltip DEC-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 canonical status-dot target; the statusdot alias 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). StatusDotVariantMap admits 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-surface INV14 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 accent and neutral dots 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-dot theming 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 tooltip is 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 variant through status-dot without 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, is role="img". Then aria-label → component class and data-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" with label as 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 caller role or aria-label replaces 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-094 FR42); implementation gap: not yet built. A caller tabIndex passes 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 icon or 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-surface owns anatomy qualification, inheritance, canonical target naming, and the extensible variant axis; FR2 records the unthemed fallback.
  • architecture:public-component-api owns ref, passthrough, and styling-input rules; FR6 applies them to the dot.
  • architecture:theme-tokens INV11 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 accent and neutral dots have? (human-design) They are not status roles under architecture:theme-tokens INV11, 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.