--- name: Tag tier: atom status: stable last-updated: 2026-05-06 maintainer: Team 4 source: Almosafer Design System --- # Tag --- ## 1. Overview A tag is a compact label used to categorize, filter, or annotate content. Tags can be static — presenting a label only — or removable, allowing the user to dismiss them. Tags differ from badges in one key way: tags represent user-applied or user-removable labels. Badges represent system-defined status. A tag on a product represents a category the user has assigned or selected. A badge on that same product represents its publication state. Tags appear in filter bars, input fields (multi-select), search refinement, and product categorization. They must always be readable, never truncated without accessible alternatives, and clearly interactive when removable. --- ## 2. When to Use | Context | Description | |---|---| | User-applied labels | Categories, interests, or attributes the user has selected or applied: "Electronics", "On sale", "Size M". | | Filter selections | Active filters in a filter bar. Each selected filter renders as a removable tag. | | Multi-select input values | Selected values inside an input field (e.g., recipient list, tag input). | | Content categorization | Static category markers on product cards, articles, or records. | | Search refinement | Keywords or facets the user has added to narrow results. | --- ## 3. When Not to Use | Context | Use instead | |---|---| | System-defined read-only status | Use a badge. Status is owned by the system, not the user. | | Primary actions | Use a button. Tags do not drive actions. | | Navigation | Use a link or navigation component. | | Long descriptive labels | Tags are constrained to short text. Use a chip or an inline label for longer content. | | Sole indicator of meaning via color | Pair color with a label. Do not rely on variant color alone to convey meaning. | --- ## 4. Anatomy | Part | Required | Description | |---|---|---| | Container | Yes | The bounding shape. Carries background, border, radius, and spacing tokens. Handles hover and active states. | | Label | Yes | The visible text. Short and specific. Carries text color and typography tokens. Never truncated without an accessible alternative. | | Leading icon | No | An optional icon before the label. Reinforces category or type visually. Decorative — carries `aria-hidden="true"`. Must not replace the label. | | Remove action | Conditional | An icon button (`×`) appended inside the container when the tag is removable. It is an independent interactive target with its own accessible label: `aria-label="Remove [tag label]"`. Required when the tag can be dismissed by the user. | --- ## 5. Tokens Used | Token | Role | |---|---| | `color.background.subtle` | Neutral tag background | | `color.background.selected` | Neutral tag hover background | | `color.background.primary` | Brand tag background | | `color.background.success` | Success tag background | | `color.background.warning` | Warning tag background | | `color.background.danger` | Danger tag background | | `color.background.disabled` | Disabled tag background | | `color.text.secondary` | Neutral tag label | | `color.text.inverse` | Brand tag label | | `color.text.success` | Success tag label | | `color.text.warning` | Warning tag label | | `color.text.danger` | Danger tag label | | `color.text.disabled` | Disabled tag label and remove icon | | `color.text.subtle` | Remove icon color (default) | | `color.text.primary` | Remove icon color (hover) | | `color.border.default` | Neutral tag border | | `color.border.selected` | Brand tag border | | `color.status.success` | Success tag border | | `color.status.warning` | Warning tag border | | `color.status.danger` | Danger tag border | | `color.border.disabled` | Disabled tag border | | `color.border.focus` | Focus ring on tag or remove button | | `spacing.xs` | Padding (small size) and gap between parts | | `spacing.sm` | Horizontal padding (medium size) | | `text.caption` | Small tag label font size | | `text.body.sm` | Medium tag label font size | | `font.weight.medium` | Label font weight | | `line-height-normal` | Label line height | | `radius.full` | Pill shape — default for tags | | `radius.sm` | Square-corner shape — for dense or grid-aligned contexts | | `border.width.default` | Tag border width | | `border.width.focus` | Focus ring width (tag and remove button) | | `motion.fast` | Background and border transitions | --- ## 6. Variants ### Neutral Default tag for general categorization with no semantic status meaning. | Property | Token | |---|---| | Background | `color.background.subtle` | | Border | `color.border.default` | | Label | `color.text.secondary` | --- ### Brand High-visibility tag for primary categories, featured labels, or selected active filters. | Property | Token | |---|---| | Background | `color.background.primary` | | Border | `color.border.selected` | | Label | `color.text.inverse` | Rule: Use sparingly. Do not apply brand variant to every tag in a set. Reserve for selected or highlighted state. --- ### Success Tags representing positive classification: Verified, In stock, Approved, Active. | Property | Token | |---|---| | Background | `color.background.success` | | Border | `color.status.success` | | Label | `color.text.success` | --- ### Warning Tags representing cautionary classification: Low stock, Expiring, Under review. | Property | Token | |---|---| | Background | `color.background.warning` | | Border | `color.status.warning` | | Label | `color.text.warning` | --- ### Danger Tags representing critical classification: Out of stock, Discontinued, Rejected, Blocked. | Property | Token | |---|---| | Background | `color.background.danger` | | Border | `color.status.danger` | | Label | `color.text.danger` | --- ## 7. Sizes | Size | Use case | Padding | Font size token | |---|---|---|---| | Small | Dense filter bars, multi-select inputs, compact product cards. | `spacing.xs` (all sides) | `text.caption` | | Medium | Default. Standard filter selections, category labels, search refinement. | `spacing.xs` (vertical) + `spacing.sm` (horizontal) | `text.body.sm` | Both sizes use `radius.full`, `font.weight.medium`, and `line-height-normal`. --- ## 8. States | State | Background | Border | Label | Notes | |---|---|---|---|---| | Default | Variant default | Variant default | Variant default | Static or interactive. | | Hover | `color.background.selected` (neutral) or darkened variant | Unchanged | Unchanged | Applies to the full tag container. Transition: `motion.fast`. | | Focused | Unchanged | `color.border.focus` (2px ring, offset 2px) | Unchanged | Applies when the tag or remove button has keyboard focus. | | Active / Pressed | Slightly elevated from hover | `color.border.selected` | Unchanged | Transition: `motion.fast`. | | Disabled | `color.background.disabled` | `color.border.disabled` | `color.text.disabled` | Remove button also disabled. No interaction. | **Rules:** - Static tags (no remove action, no click behavior) do not render hover, focus, or active states. They must not receive focus or respond to pointer events. - Interactive tags (removable or clickable) must render all states above. - The remove button inside a removable tag has its own independent focus and hover states — it does not share states with the tag container. - All interactive state transitions use `motion.fast`. - Disabled tags use native `disabled` where applicable and are removed from tab order. --- ## 9. Behavior - A static tag is presentational. It does not respond to click, hover, or keyboard events. It does not receive focus. - A removable tag contains a separate remove button (`×`) as an independent interactive element. Clicking the remove button dismisses the tag. Clicking the tag label does not dismiss it. - The remove button's accessible label must name the specific tag: `aria-label="Remove Electronics"`. A generic `aria-label="Remove"` is not sufficient when multiple tags are visible. - When a tag is removed, focus must move to a logical next target: the next tag in the list, the previous tag, or the input field that owns the tag group. Focus must not be lost. - Tags in a filter bar reflect active filter state. Removing a tag deactivates that filter and updates results immediately. - Tags must not wrap their label. If the label exceeds available space, truncate with an ellipsis and expose the full label via `title` or `aria-label`. - In RTL layouts, the remove button appears on the left and the leading icon on the right. Use logical CSS properties for all spacing and positioning. --- ## 10. Accessibility | Requirement | Rule | |---|---| | Color alone is not sufficient | Every tag must carry a text label. Do not use variant color as the sole meaning carrier. | | Contrast | Label-to-background contrast must meet WCAG 2.1 AA: 4.5:1 for normal text. Validate all variant token combinations before use. | | Static tag | Static tags must not receive focus and must not appear in tab order. If presented as list items, wrap in a `