Gallery

Six color variants, three fill modifiers. Both primitives share the same vocabulary — the only difference is shape.

When to use each

Two related primitives, one decision. Shape carries semantic meaning: pill says "state"; rectangle says "type".

Fill modifier:soft is the default — colored text on tinted background, doesn't shout. Solid is for when the badge is the focal point of its row (rare — usually overkill). Outline is for badges sitting on busy or saturated backgrounds.

Drift to avoid

Six named anti-patterns. Three of them surfaced in the audit of Titan (see audit/).

• Don't redefine .badge with a different shape

  Principle 2
  Library headers in Titan redefined .badge with --radius-sm instead of --radius-full. Same class, different shape — whichever style block loads last wins. If you need a rectangle, use .tag. They're separate primitives, not interchangeable.
• Don't use badge for category labels

  Principle 4
  The shape is signal. Pill = status (a state that can change). Rect = type (what it is). Using a badge for "Beta" or "PCR plate" confuses the visual grammar — readers can't tell at a glance whether something will change.
• Don't invent custom rgba backgrounds

  Principle 2
  Six files in Titan independently picked rgba(…, 0.08), 0.12, and 0.15 for the same conceptual badge tint. Use --color-{semantic}-subtle — it exists for this. Don't hand-roll opacity values.
• Don't use solid as the default

  Principle 4
  Saturated badges in a list of rows fight every other element for attention. Soft is the default for a reason — color carries signal, fill carries weight, and most of the time you don't need both turned up.
• Don't reuse a color for unrelated meanings

  Principle 4
  Success is positive. Always. Don't reuse green for "selected" or "recommended" — that's primary's job. Color semantics travel; mixing them poisons every page that uses both meanings together.
• Don't stack five badges on one item

  Principle 1
  If an item needs five status badges, it doesn't have a status — it has noise. Pick the canonical state; surface the rest in a detail view or tooltip. (Tags can stack — categories aren't mutually exclusive.)

Composition — plate list

Each row has one badge (status — what state) and zero or more tags (category — what type). The visual grammar makes the data model readable at a glance: scan the right column for state, scan the middle for type.

• badge × 1 per row Ready / Running / Stalled / Offline / Idle — one state at a time, in the same column position
• tag × 1+ PCR plate, 96-well, Tip rack, Draft — what it IS; can stack
• soft fill default No row dominates; the eye scans cleanly through the column
• color semantics consistent Success = positive, error = problem, info = transient — meanings hold across every row