J3W1 / DESIGN SYSTEM
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 · 1.1.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@1.1.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@1.1.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
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
An inline span in caption type with 2px by 8px padding and square corners.
Status badges fill with color.status.<status>.fill and use the matching
on-fill text, preceded by the status glyph: ✕ danger, ! warning, ✓ success,
i info, · neutral. Outline badges have no fill, the text colour and a 1px
border in the same status. The count badge is a number on
color.action.primary.bg in color.action.primary.text with a visually
hidden unit. An empty badge is an 8px square dot in the status fill with a
name.
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; the glyph and text visually hidden | role="img" with aria-label, or the hidden text; the dot’s position beside its subject |
A badge has no hover, focus, pressed or disabled state because it is not a control.
Keyboard
None. A badge is never focusable. 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 glyph is aria-hidden and the text carries the meaning, so a screen
reader hears “Failed”, not “cross Failed”. Count badges include their unit
as visually hidden text (“12 unread”). An empty badge, a dot, carries
role="img" and aria-label or wraps hidden text; a dot with no name is
decoration and must be aria-hidden. Contrast: on-fill text 4.58:1 (danger),
7.54:1 (warning), 7.13:1 (success), 7.08:1 (info), 4.71:1 (neutral); outline
text 5.26:1 to 7.34:1; borders and dots at least 4.04:1 on the panel surface.
Badges are not targets, so no minimum size applies beyond legibility at 11px
caption type.
Portability
A filled or outlined span with a glyph. 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 badge that is clickable. A status shown by colour without its glyph. A count badge that hides its unit from assistive technology. Purple, cyan or magenta statuses. A badge in body type. A badge whose text wraps. A dot without a name.