ki-status

A tiny, non-interactive status dot that marks the state of a nearby item — presence on an avatar, health of a service list entry, connection state in a toolbar.

API gateway

<ki-status tone="success" label="Online"></ki-status>
<span>API gateway</span>

Examples

Tones

<ki-status tone="neutral" label="Idle"></ki-status>
<ki-status tone="info" label="Syncing"></ki-status>
<ki-status tone="success" label="Online"></ki-status>
<ki-status tone="warning" label="Degraded"></ki-status>
<ki-status tone="danger" label="Down"></ki-status>

Ring

ring adds a surface-colored ring so the dot stays legible when overlaid on media such as an avatar:

<ki-status tone="success" ring label="Online"></ki-status>

API reference

When to use: mark a state with minimal footprint adjacent to (or overlaid on) the item it describes: presence on an avatar, health of a service list entry, connection state in a toolbar. Label it (label) or pair it with adjacent visible text — color is never the only carrier of the meaning (WCAG 1.4.1).

When not to use: short labeled status text (that pill is ki-badge — this dot never renders text), notification counters or the overlay attachment mechanism (a future, separate nav-badge concern), messages that need attention or announcement (ki-alert — the dot has no live region), progress or loading (ki-progress). An unlabeled dot without adjacent visible text is an authoring mistake (WCAG 1.4.1).

Properties & attributes

Attribute	Property	Type	Default	Description
label	label	string | undefined	–	Accessible name for the state ("Online", "Build failing"). With a label the dot is exposed to assistive technology as a named non-interactive image (role img); without one it is decorative and contributes nothing to the accessibility tree — the meaning must then live in adjacent visible text (FR-003, FR-008). The label is never rendered visually: visible status text belongs to ki-badge. Runtime changes are not announced (no live region, FR-005).
ring	ring	boolean	false	Draws a separating ring around the dot for placement over media (an avatar photo), keeping it distinguishable from the pixels beneath. A per-instance functional axis — MarsUI ships Outline=True|False as sibling variants under one theme (recorded deviation from the 002 token-only rule) — while ring width and color stay per-theme --ki-status-ring-* tokens. The ring paints outside the dot's box and never shifts layout.
tone	tone	"danger" | "info" | "neutral" | "success" | "warning"	'neutral'	Semantic intent, never appearance: each tone resolves its fill from the per-theme --ki-status-{tone}-color tokens. An unrecognized value matches no style selector, so the dot keeps the neutral appearance (fallback by CSS construction — no validation code, FR-007).

CSS parts

Part	Description
dot	The dot itself: size, tone fill, radius, ring and effects.

CSS custom properties

The public styling contract of ki-status: reassign these tokens at :root or on a subtree — never override internals.

Token	Description
--ki-motion-duration-fast	Fast interaction transition duration.
--ki-motion-easing-emphasized-decelerate	Expressive entrance curve. M3 md.sys.motion.easing.emphasized-decelerate. onmars: the MarsUI decelerate curve (ki.easing.out).
--ki-motion-easing-standard	Standard interaction transition easing curve.
--ki-status-danger-color	color used by the status component for the danger tone fill: Surface/danger_med_em, the exact variable bound to the Type=danger Status variant (Danger/500).
--ki-status-info-color	color used by the status component for the info tone fill: no Figma Status variant ships an info Type, so the fill extrapolates the verified med-em 500 pattern to the Info ramp (001 contract, 010/015 precedent) — declared for founder ratification.
--ki-status-neutral-color	color used by the status component for the neutral tone fill: Surface/disabled_high_em, the exact variable bound to the Type=disabled Status variant (Gray/500 light, White/32 dark) — MarsUI's disabled gray maps to the charter neutral tone (spec Assumptions).
--ki-status-radius	dimension used by the status component for the dot shape: Radius/radius_round bound in Figma — the round dot is a radius token, never an attribute (002 shape precedent).
--ki-status-ring-color	color used by the status component for the separating ring: Outline/inverse_black, the exact variable bound to Outline=True variants — white over light surfaces, black over dark ones, so the ring reads as a cutout from the underlying media (FR-002).
--ki-status-ring-width	dimension used by the status component for the separating ring: the 2px stroke on every Outline=True Status variant (FR-002).
--ki-status-shadow	shadow used by the status component for the dot effects: the exact MarsUI pair on every Status variant — e1 drop (0/1/1/-0.5 in the scheme shadow color) plus inner White/12 highlight (0/3/3), i.e. Component_effect/primary_default's box-shadow layers. The effect's backdrop blur is deliberately NOT applied: a 4px dot has no glass surface to blur (brief §5 perf note, glass restraint).
--ki-status-size	dimension used by the status component for the dot: the MarsUI 4px dot, Space/xs bound to every Status variant (specs/021-ki-status/design-extraction.md). One size per theme, never an attribute (FR-006).
--ki-status-success-color	color used by the status component for the success tone fill: Surface/success_med_em, the exact variable bound to the Type=success Status variant (Success/500).
--ki-status-warning-color	color used by the status component for the warning tone fill: Surface/warning_med_em, the exact variable bound to the Type=warning Status variant (Warning/500).
--ki-typography-family-body	semantic font family for typography family body.

Accessibility

Label it (label) or pair it with adjacent visible text — color is never the only carrier of the meaning (WCAG 1.4.1); an unlabeled dot without adjacent text is an authoring mistake. The dot never renders text (that pill is ki-badge) and has no live region (messages that need announcement are ki-alert).

Workshop

Open ki-status in Storybook