Badge
A small square label for a status or a count; every status carries its glyph and its fill, the outline form uses the status border, and an empty badge is a dot with a name.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
status
<j3w1-badge id="example-badge-status"><span class="badge badge-danger"><span class="badge-glyph" aria-hidden="true">✕</span><span class="badge-text">Failed</span></span>
<span class="badge badge-warning"><span class="badge-glyph" aria-hidden="true">!</span><span class="badge-text">Drifted</span></span>
<span class="badge badge-success"><span class="badge-glyph" aria-hidden="true">✓</span><span class="badge-text">Verified</span></span>
<span class="badge badge-info"><span class="badge-glyph" aria-hidden="true">i</span><span class="badge-text">Proposed</span></span>
<span class="badge badge-neutral"><span class="badge-glyph" aria-hidden="true">·</span><span class="badge-text">Deferred</span></span></j3w1-badge>count
<j3w1-badge id="example-badge-count"><span class="badge badge-count"><span class="badge-text">12<span class="badge-unit"> unread</span></span></span></j3w1-badge>outline
<j3w1-badge id="example-badge-outline"><span class="badge badge-outline badge-danger"><span class="badge-glyph" aria-hidden="true">✕</span><span class="badge-text">Failed</span></span>
<span class="badge badge-outline badge-warning"><span class="badge-glyph" aria-hidden="true">!</span><span class="badge-text">Drifted</span></span>
<span class="badge badge-outline badge-success"><span class="badge-glyph" aria-hidden="true">✓</span><span class="badge-text">Verified</span></span>
<span class="badge badge-outline badge-info"><span class="badge-glyph" aria-hidden="true">i</span><span class="badge-text">Proposed</span></span>
<span class="badge badge-outline badge-neutral"><span class="badge-glyph" aria-hidden="true">·</span><span class="badge-text">Deferred</span></span></j3w1-badge>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/badge.css';
import '@j3w1/ui/register/badge';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy badge --out ./vendor/j3w1/badgeThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Badge badge
A small square label for a status or a count; every status carries its glyph and its fill, the outline form uses the status border, and an empty badge is a dot with a name.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
danger.bg | color.status.danger.fillobserveduse | #dc282e | Danger fill. |
danger.text | color.status.danger.on-fillobserveduse | #f9faf9 | Text on the danger fill (4.58:1). |
danger.border | color.status.danger.borderobserveduse | #e53935 | Danger border, 2px on invalid inputs. |
danger.outline-text | color.status.danger.textobserveduse | #f07178 | D-041 readable error text on neutral surfaces and native warning tints. |
warning.bg | color.status.warning.fillapproveduse | #e5c07b | D-041 status.warning.fill: color.primitive.modern.amber. |
warning.text | color.status.warning.on-fillapproveduse | #000000 | Text on the warning fill (7.54:1). |
warning.border | color.status.warning.borderapproveduse | #e5c07b | D-041 status.warning.border: color.primitive.modern.amber. |
warning.outline-text | color.status.warning.textapproveduse | #e5c07b | D-041 status.warning.text: color.primitive.modern.amber. |
success.bg | color.status.success.fillapproveduse | #82d9a0 | D-041 status.success.fill: color.primitive.modern.green. |
success.text | color.status.success.on-fillapproveduse | #000000 | Text on the success fill (7.13:1). |
success.border | color.status.success.borderapproveduse | #82d9a0 | D-041 status.success.border: color.primitive.modern.green. |
success.outline-text | color.status.success.textapproveduse | #82d9a0 | D-041 status.success.text: color.primitive.modern.green. |
info.bg | color.status.info.fillapproveduse | #82b4ff | D-041 status.info.fill: color.primitive.modern.blue. |
info.text | color.status.info.on-fillapproveduse | #000000 | Text on the info fill (7.08:1). |
info.border | color.status.info.borderapproveduse | #82b4ff | D-041 status.info.border: color.primitive.modern.blue. |
info.outline-text | color.status.info.textapproveduse | #82b4ff | D-041 status.info.text: color.primitive.modern.blue. |
neutral.bg | color.status.neutral.fillapproveduse | #986f72 | D-041 status.neutral.fill: color.primitive.modern.control. |
neutral.text | color.status.neutral.on-fillobserveduse | #000000 | Text on the neutral fill (4.71:1). |
neutral.border | color.status.neutral.borderapproveduse | #986f72 | D-041 status.neutral.border: color.primitive.modern.control. |
neutral.outline-text | color.status.neutral.textapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
count.bg | color.action.primary.bgapproveduse | #7d1310 | Primary button fill; D-026 darkened it off color12, which stays fixed as heritage ANSI 12. |
count.text | color.action.primary.textapproveduse | #ffa2a7 | Primary action labels: bright rose across rest, hover and pressed states (D-033). |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Status | Count | Outline |
|---|---|---|---|
default | Failed
Drifted
Verified
Proposed
Deferred | 12 unread | Failed
Drifted
Verified
Proposed
Deferred |
empty |
Purpose
Names a status or shows a count next to the thing it describes. A badge is read-only: it never opens, toggles or removes anything. An interactive label is a chip; a message with a status is an alert.
Anatomy
Parts as listed in the anatomy. The glyphs are ✕ danger, ! warning, ✓ success, i info and · neutral.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | fill, glyph and text for the status; or the outline form | the glyph; the text |
| empty | an 8px square dot in the status fill; glyph and text visually hidden | role="img" with aria-label, or the hidden text; the dot’s position beside its subject |
No hover, focus, pressed or disabled state: a badge is not a control.
Keyboard
None. When a badge summarises something the user can act on, the action lives in the neighbouring control and the badge is part of that control’s name or description.
Accessibility
The text carries the meaning, so a reader hears “Failed”, not “cross Failed”.
The count’s hidden unit reads as “12 unread”. An empty badge may wrap hidden
text instead of aria-label; a dot with no name is decoration and must be
aria-hidden. Text meets 4.5:1; outline borders and dots 3:1 on the panel
surface. Badges are not targets, so no size minimum applies beyond legibility
at 11px caption type.
Portability
Toolkits without background colours on labels use the outline form. Hosts without the glyph characters use the nearest available (x, !, check mark, i, bullet) and record it.
Non-examples
Rounded or pill badges. A clickable badge. A status by colour without its glyph. A count unit hidden from assistive technology. Purple, cyan or magenta statuses. A badge in body type. Wrapping text. A dot without a name.
Contrast report
22 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| badge default text | default | text | color.status.danger.on-fill #f9faf9 | color.status.danger.fill #dc282e | 4.58 | 4.5 | pass |
| badge empty text | empty | text | color.status.danger.on-fill #f9faf9 | color.status.danger.fill #dc282e | 4.58 | 4.5 | pass |
| warning badge | — | text | color.status.warning.on-fill #000000 | color.status.warning.fill #e5c07b | 12.16 | 4.5 | pass |
| success badge | — | text | color.status.success.on-fill #000000 | color.status.success.fill #82d9a0 | 12.38 | 4.5 | pass |
| info badge | — | text | color.status.info.on-fill #000000 | color.status.info.fill #82b4ff | 9.92 | 4.5 | pass |
| neutral badge | — | text | color.status.neutral.on-fill #000000 | color.status.neutral.fill #986f72 | 4.85 | 4.5 | pass |
| count badge | — | text | color.action.primary.text #ffa2a7 | color.action.primary.bg #7d1310 | 5.57 | 4.5 | pass |
| danger outline text | — | text | color.status.danger.text #f07178 | color.surface.default #0d0707 | 6.98 | 4.5 | pass |
| warning outline text | — | text | color.status.warning.text #e5c07b | color.surface.default #0d0707 | 11.57 | 4.5 | pass |
| success outline text | — | text | color.status.success.text #82d9a0 | color.surface.default #0d0707 | 11.79 | 4.5 | pass |
| info outline text | — | text | color.status.info.text #82b4ff | color.surface.default #0d0707 | 9.44 | 4.5 | pass |
| neutral outline text | — | text | color.status.neutral.text #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
| danger outline border | — | ui | color.status.danger.border #e53935 | color.surface.default #0d0707 | 4.73 | 3 | pass |
| warning outline border | — | ui | color.status.warning.border #e5c07b | color.surface.default #0d0707 | 11.57 | 3 | pass |
| success outline border | — | ui | color.status.success.border #82d9a0 | color.surface.default #0d0707 | 11.79 | 3 | pass |
| info outline border | — | ui | color.status.info.border #82b4ff | color.surface.default #0d0707 | 9.44 | 3 | pass |
| neutral outline border | — | ui | color.status.neutral.border #986f72 | color.surface.default #0d0707 | 4.62 | 3 | pass |
| danger dot on the panel surface | empty | ui | color.status.danger.fill #dc282e | color.surface.default #0d0707 | 4.17 | 3 | pass |
| warning dot on the panel surface | empty | ui | color.status.warning.fill #e5c07b | color.surface.default #0d0707 | 11.57 | 3 | pass |
| success dot on the panel surface | empty | ui | color.status.success.fill #82d9a0 | color.surface.default #0d0707 | 11.79 | 3 | pass |
| info dot on the panel surface | empty | ui | color.status.info.fill #82b4ff | color.surface.default #0d0707 | 9.44 | 3 | pass |
| neutral dot on the panel surface | empty | ui | color.status.neutral.fill #986f72 | color.surface.default #0d0707 | 4.62 | 3 | pass |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: chip alert table list
Stress fixtures: FX-I18N FX-RTL FX-ZOOM-200 FX-320 FX-RM FX-HC FX-STATE-MATRIX