Atom · draft · v1.0.0 · owner: Site system lead · contract 19 of 20 points (open: figma)
Do and don't
Do: Review needed
Rendered by state-badge.tsOpen example: Operational state badge · Do: Review needed Use the full-page example to follow page links.
Do: Route a repair
Rendered by state-badge.tsOpen example: Operational state badge · Do: Route a repair Use the full-page example to follow page links.
Do: Recorded healthy state
Rendered by state-badge.tsOpen example: Operational state badge · Do: Recorded healthy state Use the full-page example to follow page links.
Do: Recorded broken state
Rendered by state-badge.tsOpen example: Operational state badge · Do: Recorded broken state Use the full-page example to follow page links.
Don't: Not a measured score
Rendered by state-badge.tsOpen example: Operational state badge · Don't: Not a measured score Use the full-page example to follow page links.
Don't: Not an unlabeled mark
Rendered by state-badge.tsOpen example: Operational state badge · Don't: Not an unlabeled mark Use the full-page example to follow page links.
Generated API variants, rendered live
Generated variants of the first authored example, from selected boolean and enum props. These are API explorations, not authored state declarations or verification results. Hover and focus respond to the pointer and the keyboard in the examples above.
Base authored example
Rendered by state-badge.tsOpen example: Operational state badge · Do: Base authored example Use the full-page example to follow page links.
state: healthy
Rendered by state-badge.tsOpen example: Operational state badge · Do: state: healthy Use the full-page example to follow page links.
state: attention
Rendered by state-badge.tsOpen example: Operational state badge · Do: state: attention Use the full-page example to follow page links.
state: broken
Rendered by state-badge.tsOpen example: Operational state badge · Do: state: broken Use the full-page example to follow page links.
state: action
Rendered by state-badge.tsOpen example: Operational state badge · Do: state: action Use the full-page example to follow page links.
Rules
| Rule | Why | Check |
|---|---|---|
| Positive specimens declare their rendered initial state and document language; each registered visual variant has a positive example. | Machine and Library consumers need the same examples without turning declarations into execution evidence. | Automated: tests/unit/v4-example-coverage.test.ts |
| Use only an explicitly recorded operational state, with its word. | An illustration must never silently infer a product result. | Review: System owner, at composition review |
API
| Prop | Type | Required | Default | What it does |
|---|---|---|---|---|
state | healthy | attention | broken | action | Yes | Explicit state of the record. | |
lang | en | ja | No | "en" | Label language. |
Contract details
The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests
Identity
| Aspect | Value |
|---|---|
| Id | state-badge |
| Layer | Atoms |
| Category | status |
| Owner | Site system lead |
| Status | draft |
| Version | 1.0.0 |
| Source | apps/showcase/site/system/atoms/state-badge.ts (private repository; the contract and the render function are this one module) |
| Version | Date | Change |
|---|---|---|
| 1.0.0 | 2026-10-27 | Created from the owner-selected V4 direction (D-SITE-019). |
Use when
- A record has an explicit operational state. Why: The mark and word let readers distinguish states without relying on colour.
Do not use when
- Inferring a state from an audit score. Why: Scores use Band word and its existing thresholds, not these four workflow meanings.
Anatomy
| Part | What it is |
|---|---|
| root | Labelled badge |
| mark | Circle/check, diamond, split bars or arrow |
| word | Visible state name |
Made of: tokens-component.
Used in: identity-playground.
Variants
| Variant | When | Why |
|---|---|---|
| healthy | The record states healthy. | Geometry and language preserve meaning even in monochrome. |
| attention | The record states attention. | Geometry and language preserve meaning even in monochrome. |
| broken | The record states broken. | Geometry and language preserve meaning even in monochrome. |
| action | The record states action. | Geometry and language preserve meaning even in monochrome. |
States
| State | Rendered or not applicable |
|---|---|
| default | default |
| hover | Not applicable: The operational state badge is not interactive, so it has no hover state. |
| focus-visible | Not applicable: The operational state badge does not take focus; links and buttons inside it carry their own focus ring. |
| active | Not applicable: The operational state badge cannot be pressed. |
| disabled | Not applicable: The operational state badge has nothing to disable. |
| loading | Not applicable: The operational state badge is rendered at build time and is complete when the page loads. |
| empty | Not applicable: The operational state badge is not rendered without content; the builder skips it. |
| error | Not applicable: The operational state badge shows no data that can fail. |
| current | Not applicable: The operational state badge has no current item. |
| visited | Not applicable: The operational state badge is not a link. |
| expanded | Not applicable: The operational state badge does not open or close. |
Tokens
| Part | Token |
|---|---|
| --state-badge-field-ink | var(--field-ink) |
| --state-badge-padding-large | var(--space-6) |
| --state-badge-mark-large | var(--space-12) |
| --state-badge-surface | var(--cotton) |
| --state-badge-ink | var(--ink) |
| --state-badge-healthy | var(--teal-ink) |
| --state-badge-attention | var(--saffron) |
| --state-badge-broken | var(--madder-ink) |
| --state-badge-action | var(--indigo-ink) |
| --state-badge-gap | var(--space-4) |
| --state-badge-caption | var(--type-small) |
| --state-badge-mark | var(--space-11) |
| --state-badge-rule | var(--rule-hair) |
| --state-badge-line | var(--line-strong) |
| --state-badge-padding | var(--space-5) |
Layout
| Aspect | Value |
|---|---|
| breakpoints | Required review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; columns stack under 768 px; the wrap keeps a 16 px gutter on phones. |
| wrapping | Text wraps; nothing scrolls sideways. |
| textExpansion | Japanese runs 20 to 40% longer; headings break between phrases (jaBreaks) and blocks grow downwards. |
Spacing and rhythm
| Aspect | Value |
|---|---|
| internal | --space-4 |
| external | Inline within its record. |
| rhythm | One state per record. |
Motion
| Aspect | Value |
|---|---|
| None | No intrinsic element animation. The optional claude-entrance consumer profile may translate below-fold structure once (20px, --dur-weave, --ease-enter, --stagger); reduced motion disables it. This preserved baseline entrance is separate from element playback. |
Runtime and reuse
Render-only element; mount any registered child enhancements separately. Preserve required Site CSS, fonts, responsive and locale rules from nativeElement.
Accessibility passport
| Aspect | Value |
|---|---|
| role | Static inline state label, without an automatic live-region role |
| name | The visible governed state word |
| keyboard | No keyboard interaction |
| focus | Not focusable |
| screenReader | Reads the explicit state as text. A consumer that updates it must own any live announcement |
| contrast | Meaning has both shape and words; ink on cloth carries the label, with a strong boundary on the saffron diamond |
| target | Not an interactive target |
Content
| Slot | Length | Voice |
|---|---|---|
| state | One governed word | Healthy, Attention, Broken, Action |
Good: “Attention”
Bad: “Everything is perfect”
Japanese: 健全・要確認・破損・対応
Icons and illustrations
None: this element uses no icon or illustration of its own.
Decisions and exceptions
Usage
34 uses across the built pages (measured by npm run site:system).
Tests
| Aspect | Value |
|---|---|
| unit | tests/unit/site-system.test.ts: renders every do and don't example through the registry and checks the classes it owns |
| visual | Not yet: there are no screenshot baselines; the Library page is checked for sideways scroll at 1440 px by tests/site/system.spec.ts |
| a11y | tests/site/system.spec.ts: axe (0 serious or critical) on the element's Library page in light and dark |
| parity | scripts/site/system/check.ts: Library examples are rendered by the same render function the site imports |
Figma
not-yet: The Loom Site Figma library is the last stage of the plan; this element is not mapped yet.