Base tag: Neutral gray background with subtle border. The most common variant, used for general-purpose labels and metadata.

Solid tags: Full-color background with white text for high visibility. Use sparingly for tags that need strong visual emphasis.

Subtle tags: Tinted background with colored text and tinted border. Use for semantic labelling where color conveys meaning (e.g., status, category).

Soft tags: Same tinted background as subtle, but without a visible border. Use for softer emphasis where the border adds too much visual noise.

Outline tags: Transparent background with colored border and text. Use for secondary emphasis or lighter visual weight.

Text-only tags: No background or border — just colored text. Use for inline type labels in activity timelines, metadata, or compact UI.

Pill modifier: Add .tag-pill for a fully-rounded capsule shape. Use for status indicators, filter chips, and patterns where a rounder shape is preferred.

Size variants: .tag-sm for compact spaces (table cells), default for standard use, .tag-lg for prominent standalone tags.

Close button: Add a .tag-close button inside the tag. Wire to data-controller="tag" for dismiss animation. Click the close icons below to see the fade-out effect.

Tag group: Use .tag-group to arrange tags in a horizontal flex row with consistent gap-1.5 spacing. Tags wrap automatically.

Interactive modifier: Add .tag-interactive for clickable tags that respond to hover and focus. Use <button> elements for proper keyboard support.

Disabled: Add .tag-disabled for a translucent blue-tinted appearance with no pointer events. Used when tags are read-only or the parent control is disabled.

Modifier: .tw-tag-neutral-text forces text-neutral-800 regardless of the color variant. Useful with outline variants when you want colored borders but readable neutral text.

Composition: Outline tag + .tw-tag-neutral-text with a solid .tw-badge nested inside. Use .tw-badge-rounded for squared tags or default pill badge for .tw-tag-pill.

Use for items with a count or capacity indicator — e.g., class groups with fill counts, categories with totals. Badges are auto-sized when nested inside any tag.

Media: .tw-tag-media holds a leading avatar or icon and sizes it against the tag's text, so it never dictates the row height. The assignee/recipient chip shape.

Not confirmed yet: .tw-tag-dashed swaps the tag's border for a dashed one to mean "pencilled in" — a slot held but not booked, a date proposed but not agreed, a provisional offer. It is a modifier on any variant, not a variant of its own, so keep the colour that already carries the meaning. Pair it with the wording ("Pencilled", "Provisional", "Draft") — a dashed edge alone is invisible to a screen reader, to a colour-blind user scanning quickly, and in print.