# Icon

## Overview

The icon component renders Material Symbols glyphs through a shared `.icon` element pattern.

The component styles a text element directly, so the icon name can remain in the DOM while the font converts it into the matching symbol.

## When to use

Use an icon as a compact visual cue beside text or as a decorative affordance inside a control that already has an accessible name.

## When not to use

Do not use an icon as the only source of meaning when users would need a visible or accessible text label to understand it.

## Usage

```html
<span class="icon" aria-hidden="true">search</span>
```

Use this component when the interface needs a compact visual symbol alongside text or as a standalone decorative control affordance.

Use visible text instead when the meaning would be unclear without a label.

For filled variants, add the `.fill` class to the same element.

```html
<span class="icon fill" aria-hidden="true">favorite</span>
```

The icon should use the shared `.icon` class so size and Material Symbols variable font settings stay consistent across components.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- ICO-001: Icons should align inline with nearby text and controls without requiring component-specific vertical offsets.
- ICO-002: Icons inherit the surrounding text color by default.
- ICO-003: Icons default to 150% of the default font size.
- ICO-004: Only components that own an icon treatment should expose a component-level icon color token, and that token should alias a theme semantic color by default.
- ICO-005: Filled icons should switch only the `FILL` axis and keep the same base sizing and font settings.
- ICO-006: Size, optical size, grade, and weight should come from the exposed custom properties rather than hardcoded per-instance values.
## Accessibility

- Mark decorative icons with `aria-hidden="true"` so they do not add noise to the accessible name.
- If an icon communicates meaning on its own, provide an accessible name on the interactive parent or add a text alternative.
- Do not rely on the icon alone to communicate critical state or action.
- Keep the source text content to a valid Material Symbols glyph name so the intended icon renders consistently.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--icon-fill` | `<number>` | Sets the Material Symbols fill axis; change it to switch icons between outlined and filled glyph styles. |
| `--icon-font-family` | `Any` | Sets the icon font family used by icon elements and generated symbols; change it only when swapping the icon font system. |
| `--icon-grad` | `<number>` | Sets the Material Symbols grade axis; change it to subtly thicken or lighten icon strokes without changing layout size. |
| `--icon-opsz` | `<number>` | Sets the Material Symbols optical size axis; change it when icons should be optimized for a different rendered size. |
| `--icon-size` | `<length>` | Sets the rendered icon font size; change it when icons should scale independently from surrounding text. |
| `--icon-wght` | `<number>` | Sets the Material Symbols weight axis; change it when icons need heavier or lighter strokes. |

## Depends On

- `--font-size`