Badges

mandatory

Small visual marker attached to another element, signalling presence of notifications, unread count, or status. Material parity (`/components/badges`). Covers small (dot) and large (numeric) variants, anchoring rules, and overflow formatting.

Facet Visual of Koder Design. Material parity: https://m3.material.io/components/badges.

2 variants

Variant Size Content Use
Small (dot) 6 px circle None Presence-only marker
Large (numeric) 16 px height 1-3 digits or text Count or short label

Pick variant by need: dot when count is irrelevant ("you have new messages"); numeric when count itself is information ("3 unread").

Anatomy (large badge on icon button)

        ┌───┐
   ┌─── │ 3 │   ← badge (top-right anchor)
   │    └───┘
   ▼
  ┌─────┐
  │  ✉  │      ← host (icon button)
  └─────┘
  • Dot diameter: 6 px
  • Large height: 16 px
  • Large min-width: 16 px (square at 1 digit); auto-expands
  • Large padding: 4 px horizontal
  • Text: label-small (11/16, weight 600)
  • Background: error color role by default
  • Foreground: on-error
  • Border: 1 px surface background (separation from host)

R1 — Anchor position

Anchor Offset Use
Top-right (default) -2 px x, -2 px y Icon buttons, list items, avatar
Top-left +2 px x, -2 px y RTL mirror of top-right
Inline After text, 4 px gap Inside list row, after label

Never anchor below or center — badge always sits at top corner OR inline after text.

R2 — Numeric formatting

Count Display
0 Hide badge entirely (don't show "0")
1-9 Single digit 3
10-99 Two digits 42
100-999 Three digits 512
1000+ 999+ (cap)

Custom cap allowed per surface: 99+ for notifications, 9+ for inbox folders. Document per surface; pick one.

R3 — Color roles

Meaning Background Foreground
Error / urgent error on-error
Warning warning (extended) on-warning
Info / neutral count primary on-primary
Success / new success (extended) on-success
Status — online success dot —
Status — away warning dot —
Status — offline outline dot —

Default to error for unread/attention counts (matches Material default and user expectation).

R4 — Animation

  • Appear: fade-in + scale 0 → 1 (motion-fast, ~150 ms)
  • Count change: cross-fade old → new digit (motion-fast)
  • Disappear: fade-out (motion-fast)
  • No bouncing / pulsing — distracting and ignored by users after

    habituation

  • Reduced motion: instant appear/disappear, no animation

R5 — Accessibility

  • Badge content is part of host's accessible name:
    • Icon button: aria-label="Inbox, 3 unread" (concat, not separate)
    • Or use aria-describedby referencing a hidden span with badge

      text

  • Dot-only badge: include presence in host label

    ("Profile, online")

  • Color alone never carries meaning — always pair with text or

    icon-shape difference

  • Hit target: badge is decorative; host's hit target stays unchanged

R6 — Hit target

Badge is non-interactive. Tapping it triggers the host's action. Don't add a separate click handler on the badge — defeats user expectation and confuses screen readers.

R7 — Density

Density Dot Large Padding
Compact 4 px 14 px 3 px
Default 6 px 16 px 4 px
Comfortable 8 px 20 px 6 px

Inherits surface density from customization.kmd.

R8 — Per-preset variation

Preset Visual
material3 Rounded pill, no border, error-color default
material2 Circle (numeric), filled background
ios_cupertino Red filled circle, white text, slight gradient
gnome Rectangle with 4 px radius, accent color
windows_11 Pill shape, system accent color, subtle outline
brutalist Sharp square, thick 2 px border, no animation
terminal_classic ASCII suffix (3) next to icon, no shape

R9 — Forbidden patterns

  • ❌ Showing 0 — hide badge entirely instead
  • ❌ Animating count change with bounce/pulse (distracting)
  • ❌ Putting interactive elements (buttons, links) inside a badge
  • ❌ Using badge to display arbitrary long text — use chip instead
  • ❌ Color-only differentiation (status dot WITHOUT label text)
  • ❌ Anchoring at bottom or center of host
  • ❌ Stacking multiple badges on the same host
  • themes/color-roles.kmd — error / success / warning token sources
  • themes/typography.kmd — label-small for numeric text
  • foundations/elements.kmd — Marker family
  • components/chips.kmd — sibling for longer textual labels with interaction