Component
ki-badge
A static, non-interactive status pill. The label is the meaning — the tone color only reinforces the text, it never replaces it.
<ki-badge tone="success">Active</ki-badge>Examples
Section titled “Examples”<ki-badge tone="neutral">Draft</ki-badge><ki-badge tone="info">Beta</ki-badge><ki-badge tone="success">Active</ki-badge><ki-badge tone="warning">Expiring</ki-badge><ki-badge tone="danger">Failed</ki-badge><ki-badge size="sm" tone="info">sm</ki-badge><ki-badge size="md" tone="info">md</ki-badge>API reference
Section titled “API reference”When to use: annotate an entity with short status text (a state, a category) whose meaning is carried by the label itself; the tone color only reinforces the text, it never replaces it.
When not to use: feedback that must be announced (that is ki-alert's job — the badge has no live region), an interactive chip, filter or button, empty content (the label IS the meaning), or a notification-counter overlay (a future, separate concern).
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
size | size | "md" | "sm" | 'md' | Metric scale (--ki-badge-{size}-* tokens). An unrecognized value falls back to the md metrics the same way. |
tone | tone | "danger" | "info" | "neutral" | "success" | "warning" | 'neutral' | Semantic intent, never appearance: each tone resolves its colors from the --ki-badge-{tone}-* tokens. An unrecognized value matches no style selector, so the badge keeps the neutral appearance (fallback by CSS construction — no validation code). |
Slots
| Slot | Description |
|---|---|
| (default) | The label: short status text, the sole carrier of meaning. |
CSS parts
| Part | Description |
|---|---|
badge | The pill: background, foreground, border, radius, metrics and typography. |
CSS custom properties
The public styling contract of ki-badge: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-badge-border-width | dimension used by the badge component for border width (MarsUI tone tags carry width 0 in default state; only the neutral glass type draws its 1px bevel via ki.badge.neutral.border-width. material3 keeps its border via its override). |
--ki-badge-danger-bg | color used by the badge component for danger background (MarsUI Surface/danger_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). |
--ki-badge-danger-border | color used by the badge component for danger border. |
--ki-badge-danger-fg | color used by the badge component for danger foreground. |
--ki-badge-font-family | font family used by the badge component for font family. |
--ki-badge-font-weight | font weight used by the badge component for font weight. |
--ki-badge-info-bg | color used by the badge component for info background (MarsUI Surface/info_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). |
--ki-badge-info-border | color used by the badge component for info border. |
--ki-badge-info-fg | color used by the badge component for info foreground. |
--ki-badge-md-font-size | dimension used by the badge component for md font size (MarsUI UI/Caption 2: 12px at both sm and md; only xs drops to Caption 1). |
--ki-badge-md-height | dimension used by the badge component for md height (MarsUI Tag md outer height 28px). |
--ki-badge-md-line-height | dimension used by the badge component for md line height (MarsUI caption_2 16px). |
--ki-badge-md-padding-inline | dimension used by the badge component for md padding inline (MarsUI total text inset 10px; paired with the border-width 0 + border-box change so the badge does not shrink). |
--ki-badge-md-radius | dimension used by the badge component for md radius (MarsUI Tag: Radius/component/radius_sm 8px at both sm and md). |
--ki-badge-neutral-bg | color used by the badge component for neutral background (MarsUI secondary glass Tag: Surface/special/secondary_alpha_base Gray-100 alpha light / Dark-700 blur base dark — the same fill as ki-button secondary; completes the glass bevel/blur/shadow the component already draws. material3 keeps the opaque s2 chip via its override). |
--ki-badge-neutral-border | color used by the badge component for neutral border (MarsUI secondary Tag bevel: Outline/secondary_button_top; drawn at ki.badge.neutral.border-width). |
--ki-badge-neutral-border-width | dimension used by the badge component for the neutral (secondary glass) border width: MarsUI draws the 1px bevel only on this type. |
--ki-badge-neutral-fg | color used by the badge component for neutral foreground. |
--ki-badge-sm-font-size | dimension used by the badge component for sm font size. |
--ki-badge-sm-height | dimension used by the badge component for sm height. |
--ki-badge-sm-line-height | dimension used by the badge component for sm line height. |
--ki-badge-sm-padding-inline | dimension used by the badge component for sm padding inline (MarsUI total text inset 8px; paired with the border-width 0 + border-box change). |
--ki-badge-sm-radius | dimension used by the badge component for sm radius (MarsUI Tag silhouette is an 8px rounded rect — Radius/component/radius_sm — never a pill). |
--ki-badge-success-bg | color used by the badge component for success background (MarsUI Surface/success_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). |
--ki-badge-success-border | color used by the badge component for success border. |
--ki-badge-success-fg | color used by the badge component for success foreground. |
--ki-badge-warning-bg | color used by the badge component for warning background (MarsUI Surface/warning_base_em_alpha: tone-500 at 12% light — the tint composites over any surface and the dark alias adapts automatically). |
--ki-badge-warning-border | color used by the badge component for warning border. |
--ki-badge-warning-fg | color used by the badge component for warning foreground. |
--ki-effect-component-backdrop-blur | MarsUI Blur/24 as the component glass backdrop. Components consume this semantic name for backdrop-filter: blur(...) — never the ki.blur primitive directly (primitive-css-consumption gate). |
--ki-effect-component-secondary-default-shadow | MarsUI Component_effect/secondary_default: drop 0/2/1.5/-0.5 plus inner White/3 0/2/3. Pair with backdrop-filter blur(var(--ki-effect-component-backdrop-blur)). |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-outline-secondary-button-bottom | semantic color for outline secondary button bottom. |
Accessibility
Section titled “Accessibility”The badge has no live region: feedback that must be announced is ki-alert’s job. Never ship an empty badge — the slotted label carries the meaning, so color alone is never the carrier (WCAG 1.4.1). For a state dot with no text of its own, use ki-status.