Components · Work representation
Status Mark
One value on one state axis. A glyph and a label carry its meaning; color reinforces it. Applied describes execution. Verified describes a checked scope. Neither substitutes for the other.
Overview
Use the same status vocabulary in a row, a card and a summary. Supply a legal axis value from the authoritative state. A more specific label may name a target; it must not make a stronger claim (INV-01, INV-16).
These are live component specimens, not running operations. Their presence is not evidence that a request was sent or a remote write was checked.
Anatomy
- Glyph. The symbol reinforces the state and is hidden from assistive technology when the text already names that state.
- Label. The readable state, optionally narrowed to a target. It never disappears when a highlight settles.
- State axis. Execution, verification and epistemic state are different dimensions, not interchangeable badge variants.
- Attention treatment. At rest, glyph and label remain. A just-changed value may be lit briefly; only fill and stroke settle.
States
The table uses real marks. Its lit column is intentionally pinned for comparison; in an interaction, call the shared settling behavior after the 1.1-second breath. A pinned specimen is not a timing demonstration.
Unknown remains still. A spinner belongs only to a target with a request actually in flight. Amber is for a person’s judgment; green is reserved for a verified scope.
Usage and avoid
When to use
Use a mark when the person needs one explicit state value: “Shopify · Applied,” “Amazon · Outcome unknown,” or a scoped verification result. Keep the evidence and scope nearby in the component that owns them.
When not to use
Do not use it as decoration, a category tag or an aggregate success score. Do not relabel a classifier’s 0.82 as “Supported,” or make a partial test count read as global verification.
Separate a write from its verification
Before the checks return, verification is pending. Afterward, the result states what was checked, what was preserved and what could not be observed. The badge alone cannot carry that distinction.
Evidence limits
A mark validates its presentation inputs; it does not establish their truth. The containing component and resolver remain responsible for evidence, permissible wording and exact scope.
Contract
| Semantic inputs | A legal axis, a value on that axis, and an optional label no stronger than that value. |
|---|---|
| Allowed states | Values declared on the chosen axis; at rest or lit. |
| Forbidden states | An undeclared axis value, color-only meaning, or a label that promotes the claim. |
| Evidence requirements | The carrier supplies authoritative state and the evidence behind it. The mark does not infer either. |
| Action scope | None. A mark is not itself an interactive control. |
| Meaning of authority | None. An authority state is displayed, not granted. |
| External effects | None. |
| Verification conditions | A verified mark must refer to a Verification whose exact scope is disclosed by its carrier (INV-02, INV-11). |
| Failure and recovery | Display the supplied failed, partial or unknown state without guessing an outcome. |
| Transitions | A changed mark may light; fill and stroke settle after the breath. The glyph and label do not move (MOT-06). |
| Accessibility | Always provide text. Hide a redundant glyph from assistive technology; do not rely on hue. |
| Observable events | None. The mark does not emit an execution or verification event. |
| Test conditions | Check legal axis values, glyph plus label, bounded wording and unknown-state stillness. Validate the complete carrier against its plan. |
Accessibility
The label must remain readable at rest, in dark mode and with reduced motion. Do not put a non-interactive mark in the tab order. The carrier should announce a meaningful state change once, rather than making every decorative specimen a live region.
Color contrast and assistive-technology behavior still need testing in the actual containing surface. A correctly rendered standalone mark is not a whole-interface accessibility claim.
Code
import { statusMark } from '../../packages/components/src/index.js';
import { settleLit } from '../../packages/morph/src/index.js';
const mark = statusMark({
axis: 'execution',
value: 'applied',
label: 'Shopify · Applied',
});
document.body.append(mark);
settleLit([mark]);
// INV-02: this is a write outcome, not a verification result.
Read status language and the independent axes before adding a new label.