Atom · stable · v1.0.0 · owner: Site system lead · contract 19 of 20 points (open: figma)
Do and don't
Do: Holding together with its meaning
Rendered by band-word.tsOpen example: Band word · Do: Holding together with its meaning Use the full-page example to follow page links.
Do: Loose threads
Rendered by band-word.tsOpen example: Band word · Do: Loose threads Use the full-page example to follow page links.
Don't: A word that is not a band
Rendered by band-word.tsOpen example: Band word · Don't: A word that is not a band Use the full-page example to follow page links.
Don't: A band colour on the wrong score
Rendered by band-word.tsOpen example: Band word · Don't: A band colour on the wrong score Use the full-page example to follow page links.
Rules
| Rule | Why | Check |
|---|---|---|
| A band mark always carries its word. | Colour alone excludes people who cannot tell dyes apart, and dyes on the site also mark sections. | Automated: tests/unit/site-system.test.ts (rendered text) |
| The band comes from the score by the rubric's thresholds. | One score, one band, everywhere. | Automated: health check scoring tests (tests/unit/health-check-scoring.test.ts) |
API
| Prop | Type | Required | Default | What it does |
|---|---|---|---|---|
band | woven | holding | shape | loose | Yes | The band from the rubric's thresholds (90, 75, 60). | |
word | string | Yes | The band's name (content token band.*). | |
summary | string | No | One line on what the band means. |
Contract details
The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests
Identity
| Aspect | Value |
|---|---|
| Id | band-word |
| Layer | Atoms |
| Category | status |
| Owner | Site system lead |
| Status | stable |
| Version | 1.0.0 |
| Source | apps/showcase/site/system/atoms/band-word.ts (private repository; the contract and the render function are this one module) |
| Version | Date | Change |
|---|---|---|
| 1.0.0 | 2026-10-26 | The health band as a small dyed mark that always carries its word. |
Use when
- Next to a score. Why: The band turns a number into a judgement the reader understands.
- In a report or score card. Why: The same four words and colours everywhere make scores comparable.
Do not use when
- Without its word. Why: Colour alone fails people who cannot tell the dyes apart, and the rule is marks always carry their word (D-SITE-004).
- As decoration or a section colour. Why: A dye mark means health; anything else would make it ambiguous.
Anatomy
| Part | What it is |
|---|---|
| root | p.band holding span.band-chip.band-<id> and the summary. |
| chip | The dyed mark with the band's name. |
| summary | Optional plain-words meaning. |
Made of: tokens:colour, tokens:type.
Used in: finding, cloth-diagram, identity-playground, proof-shift, read-your-stylesheet, score-us, takenote-card.
Variants
| Variant | When | Why |
|---|---|---|
| woven | 90 to 100. | Indigo: the deepest dye for the tightest weave. |
| holding | 75 to 89. | Teal: sound but with room to improve. |
| shape | 60 to 74. | Saffron with dark text: taking shape. |
| loose | 0 to 59. | Madder: trouble, act first. |
States
| State | Rendered or not applicable |
|---|---|
| default | default |
| hover | Not applicable: A band word is not interactive, so it has no hover state. |
| focus-visible | Not applicable: A band word does not take focus; links and buttons inside it carry their own focus ring. |
| active | Not applicable: A band word cannot be pressed. |
| disabled | Not applicable: A band word has nothing to disable. |
| loading | Not applicable: A band word is rendered at build time and is complete when the page loads. |
| empty | Not applicable: A band word is not rendered without content; the builder skips it. |
| error | Not applicable: A band word shows no data that can fail. |
| current | Not applicable: A band word has no current item. |
| visited | Not applicable: A band word is not a link. |
| expanded | Not applicable: A band word does not open or close. |
Tokens
| Part | Token |
|---|---|
| chip.background@woven | --band-woven |
| chip.background@holding | --band-holding |
| chip.background@shape | --saffron |
| chip.background@loose | --band-loose |
| chip.color | --on-dye (on-saffron for shape) |
| chip.font | --type-small-strong |
| --band-word-margin-top-space-5 | var(--space-5) |
| --band-word-color-ink-2 | var(--ink-2) |
| --band-word-margin-right-space-3 | var(--space-3) |
| --band-word-padding-space-1 | var(--space-1) |
| --band-word-padding-space-4 | var(--space-4) |
| --band-word-font-type-small-strong | var(--type-small-strong) |
| --band-word-color-on-dye | var(--on-dye) |
| --band-word-background-band-woven | var(--band-woven) |
| --band-word-border-radius-radius | var(--radius) |
| --band-word-background-band-holding | var(--band-holding) |
| --band-word-background-saffron | var(--saffron) |
| --band-word-color-on-saffron | var(--on-saffron) |
| --band-word-background-band-loose | var(--band-loose) |
| --band-word-gap-space-3 | var(--space-3) |
| --band-word-font-size-fs-small | var(--fs-small) |
| --band-word-margin-bottom-space-4 | var(--space-4) |
| --band-word-font-type-label | var(--type-label) |
Layout
| Aspect | Value |
|---|---|
| breakpoints | Required review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; unchanged. |
| wrapping | The chip never wraps; the summary wraps after it. |
| textExpansion | Japanese band names are short (4 to 6 characters). |
Spacing and rhythm
| Aspect | Value |
|---|---|
| internal | --space-1 by --space-4. |
| external | --space-3 to the summary. |
| rhythm | Inline with its score. |
Motion
| Aspect | Value |
|---|---|
| None | A judgement does not animate. |
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 | text |
| name | The band word |
| keyboard | Not interactive. |
| focus | Not focusable. |
| screenReader | Reads the word, so colour is never the only signal. |
| contrast | Cotton on indigo 11.6:1, on teal 6.6:1, on madder 6.9:1; dark on saffron 9.1:1. |
| target | Not a target. |
Content
| Slot | Length | Voice |
|---|---|---|
| word | 3 words | One of the four band names, exactly |
Good: “Holding together” · “Loose threads”
Bad: “Good” · “Needs work”
Japanese: Band names come from content tokens band.* with reviewed Japanese (緊密に織られている 等).
Icons and illustrations
None: this element uses no icon or illustration of its own.
Decisions and exceptions
Usage
46 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.