components / badge

Badge

Compact status label tuned for tone distinction, compressed layout, and readable emphasis shifts.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Badge gives DK a compact way to label status, environment, or categorization without escalating to full alert or chip behavior.
  • Its value comes from tone distinction and compact fit, not from interaction.

Aliases

pill, status pill

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Badge when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Badge contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Badge label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Badge behind decorative copy or overloaded surface treatments.
  • Do not stretch Badge into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Badge to label state, environment, phase, or system intent in a compressed area.
  • Use soft or outline emphasis when the label should support, not dominate, a larger surface.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Badge as a clickable filter token; use Chip instead.
  • Do not replace longer guidance or system messaging with a terse badge.

Anti-patterns

  • Using Badge as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy badge usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

status shell

root

Carries the tone, emphasis, and compact shape.

supporting slot

leading

Optional symbol or marker before the label.

status text

label

Concise status label.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
tone'neutral' | 'brand' | 'success' | 'warning' | 'danger''neutral'Chooses the semantic status tone.
emphasis'soft' | 'solid' | 'outline''soft'Chooses the visual weight of the badge.
size'sm' | 'md''md'Chooses the compiled size recipe for the component.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultVisible badge label.
leadingOptional symbol before the label.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • soft: Calm filled badge with low visual weight.
  • solid: Higher-emphasis filled badge for stronger status signal.
  • outline: Outlined badge for lower fill weight and clearer edge definition.

Sizes

  • sm: Tight compact label for dense UI.
  • md: Default badge size for dashboards and cards.

States

  • rest: Badges are intentionally non-interactive and mostly static.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Renders as static text content without interactive semantics.

Keyboard

  • No special keyboard model because badges are not interactive.

Screen readers

  • The badge content is announced as ordinary text in document order.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-badge-bg
#d7e9ff
--dk-badge-fg
#000f4d
--dk-badge-border
#2072e4
--dk-badge-border-width
1px
--dk-badge-radius
999px
--dk-badge-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-badge-block-size
30px
--dk-badge-inline-padding
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

leading

--dk-badge-leading-size
0.82rem

label

--dk-badge-label-color
inherit
--dk-badge-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-badge-label-weight
650

Implementation notes

  • Badge is intentionally compact and static; if the user needs interaction, move up to Chip or Button.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: product phase

A compact label for a product phase or environment.

Copy snippet

<Badge tone="brand" emphasis="soft" size="md">Beta</Badge>

Common patterns

1 example

common

Common: system status

A stronger success badge for dashboards and operational summaries.

Copy snippet

<Badge tone="success" emphasis="solid" size="sm">Healthy</Badge>

Edge cases

1 example

edge

Edge: marker plus label

Use a leading marker sparingly when fast scanning matters.

Copy snippet

<Badge tone="warning" emphasis="outline"><svelte:fragment slot="leading">!</svelte:fragment>Needs review</Badge>

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

neutral-soft

pass

emphasis=soft|size=md|tone=neutral

  • Contrast: 90.8 Lc
  • Layout: 105 / 120, 200

neutral-solid

pass

emphasis=solid|size=md|tone=neutral

  • Contrast: 100.1 Lc
  • Layout: 105 / 120, 200

neutral-outline

pass

emphasis=outline|size=md|tone=neutral

  • Contrast: 98.5 Lc
  • Layout: 105 / 120, 200

brand-soft

pass

emphasis=soft|size=md|tone=brand

  • Contrast: 89.9 Lc
  • Layout: 120 / 120, 200

brand-solid

pass

emphasis=solid|size=md|tone=brand

  • Contrast: 89.9 Lc
  • Layout: 120 / 120, 200

brand-outline

pass

emphasis=outline|size=md|tone=brand

  • Contrast: 98.5 Lc
  • Layout: 120 / 120, 200

success-soft

pass

emphasis=soft|size=md|tone=success

  • Contrast: 98.5 Lc
  • Layout: 135 / 120, 200

success-solid

pass

emphasis=solid|size=md|tone=success

  • Contrast: 98.5 Lc
  • Layout: 135 / 120, 200

success-outline

pass

emphasis=outline|size=md|tone=success

  • Contrast: 98.5 Lc
  • Layout: 135 / 120, 200

warning-soft

pass

emphasis=soft|size=md|tone=warning

  • Contrast: 98.5 Lc
  • Layout: 120 / 120, 200

warning-solid

pass

emphasis=solid|size=md|tone=warning

  • Contrast: 59.8 Lc
  • Layout: 120 / 120, 200

warning-outline

pass

emphasis=outline|size=md|tone=warning

  • Contrast: 98.5 Lc
  • Layout: 120 / 120, 200

danger-soft

pass

emphasis=soft|size=md|tone=danger

  • Contrast: 98.5 Lc
  • Layout: 120 / 120, 200

danger-solid

pass

emphasis=solid|size=md|tone=danger

  • Contrast: 80.5 Lc
  • Layout: 120 / 120, 200

danger-outline

pass

emphasis=outline|size=md|tone=danger

  • Contrast: 98.5 Lc
  • Layout: 120 / 120, 200