--- name: Icon tier: atom status: draft last-updated: 2026-05-06 maintainer: Team 4 source: Almosafer Design System --- # Icon --- ## 1. Overview An icon is a visual symbol that supports meaning, reinforces an action, or communicates status at a glance. Icons reduce cognitive load by pairing visual recognition with text, but they do not replace text for critical information. Icons are always intentional. Every icon in the system must be clear, simple, and drawn from the approved icon library. Icons that introduce ambiguity or operate without a text label or accessible name are not permitted in production interfaces. --- ## 2. When to Use - Alongside a text label to reinforce the meaning of an action or navigation item. - As a leading or trailing element inside a button or link to add visual context. - As a status indicator paired with a text label (success, warning, danger, info). - As a standalone interactive element when space is constrained — only when the icon metaphor is universally recognizable and an accessible label is provided. - As a decorative element to add visual rhythm or support illustration in empty states or onboarding flows. --- ## 3. When Not to Use - **As the sole indicator of a critical action** — Use a labelled button. Icon-only actions require universal recognition that most product icons do not have. - **As a replacement for text in status communication** — Pair with a badge or label. Color and shape alone do not meet accessibility requirements. - **As a navigation item without a label** — Use a labelled link or navigation component. Icon-only navigation creates ambiguity for new users and screen reader users. - **For decorative illustration in dense data contexts** — Use plain text. Icons in tables or form labels must carry direct semantic relevance. - **To fill visual space without meaning** — Every icon must have a reason to exist. Remove icons that do not add clarity. --- ## 4. Anatomy | Part | Required | Description | |---|---|---| | Icon glyph | Yes | The SVG symbol itself. Drawn on a consistent artboard. Carries the visual metaphor. Rendered inline as an `` element to allow color inheritance via `currentColor`. | | Container | No | An optional bounding box wrapping the glyph. Used when the icon needs a padded touch target (interactive variant) or a background fill (status context). Carries spacing and radius tokens when present. | The glyph uses `currentColor` for fill and stroke so it inherits color from its CSS context. No color is hardcoded inside the SVG markup. --- ## 5. Tokens Used | Part | Token | Role | |---|---|---| | Glyph — default | `color.text.secondary` | Default icon color in body content and supporting UI regions | | Glyph — primary content | `color.text.primary` | Icon accompanying primary text or high-emphasis content | | Glyph — brand / interactive | `color.text.brand` | Interactive icon color; icon inside a link or brand-colored control | | Glyph — subtle | `color.text.subtle` | Low-emphasis decorative or tertiary icons | | Glyph — inverse | `color.text.inverse` | Icon on dark or brand-colored surfaces | | Glyph — success | `color.status.success` | Success status icon | | Glyph — warning | `color.status.warning` | Warning status icon | | Glyph — danger | `color.status.danger` | Danger or error status icon | | Glyph — disabled | `color.text.disabled` | Disabled state icon color | | Container — focus ring | `color.border.focus` | Keyboard focus ring on interactive icon | | Container — hover background | `color.background.subtle` | Background tint on interactive icon hover | | Container — active background | `color.background.selected` | Background tint on interactive icon press | | Container — disabled background | `color.background.disabled` | Disabled state container background | | Container — padding | `spacing.xs` | Internal padding between glyph and container edge | | Container — radius | `radius.full` | Container shape for circular icon button affordance | | Size — small | `spacing.sm` | Width and height of the glyph at small size | | Size — medium | `spacing.md` | Width and height of the glyph at medium size | | Size — large | `spacing.lg` | Width and height of the glyph at large size | | Transition | `motion.fast` | Color and background transitions on interactive state changes | --- ## 6. Variants | Variant | Default | Description | |---|---|---| | Default | Yes | An informative icon that carries semantic meaning and must have an accessible label if used without adjacent visible text. Used for status indicators, leading icons in navigation, and paired icon-label combinations. | | Interactive | No | An icon that is itself a clickable or focusable control. Implemented as a `
` or `` with a click handler. --- ## 7. Sizes | Size | Token | Use case | |---|---|---| | Small | `spacing.sm` | Inline icons alongside caption or body-small text. Dense tables, compact controls, metadata regions. | | Medium | `spacing.md` | Default. Paired with standard body text in buttons, links, navigation items, and form fields. | | Large | `spacing.lg` | Standalone icons in empty states, feature callouts, or high-emphasis UI regions where the icon carries visual prominence. | Icons scale uniformly — width and height reference the same token. Do not scale width and height independently. Do not set icon dimensions in raw values. --- ## 8. States States apply to the interactive variant only. The default and decorative variants are not interactive and render no state changes. | State | Glyph color | Container background | Border / Ring | Transition | |---|---|---|---|---| | Default | `color.text.secondary` | Transparent | None | — | | Hover | `color.text.primary` | `color.background.subtle` | None | `motion.fast` on color and background | | Focused | Unchanged from default | Unchanged | `color.border.focus` (2px ring, 2px offset) | `motion.fast` on ring | | Active | `color.text.primary` | `color.background.selected` | None | `motion.fast` | | Disabled | `color.text.disabled` | `color.background.disabled` | None | None | **Rules:** - Disabled interactive icons must not be keyboard focusable. Use the native `disabled` attribute on the `