Iconography

Canonical icon library used across the family design system. Every icon is a stroke-based SVG derived from Lucide's open-source set, optimized for inline use. Icons inherit color from currentColor and respect the brand's primary text color when used inside [data-brand] scopes.

Size

Color

… of … icons shown · Click any icon to copy its name

Usage

1. Inline SVG (recommended)

Copy the icon name and inline the SVG. This is what every modal in the playground does.

<span class="ux-icon">
  <!-- icon: rotate-ccw -->
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor"
       stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <polyline points="1 4 1 10 7 10"/>
    <path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/>
  </svg>
</span>

2. Sizing rules

Use case	Size	Stroke width
Inline with body text	`16px`	2
Buttons (sm)	`16px`	2
Buttons (md/lg)	`18–20px`	2
Modal header / nav	`20px`	2
Icon-only button	`20–24px`	2
Empty state	`32–48px`	1.5
Hero / feature highlight	`48–64px`	1.5

3. Color

Icons inherit color from currentColor. Set the parent's color to control them:

<span style="color: var(--brand-primary)">
  <svg ...>...</svg>
</span>

Within a [data-brand] scope, the brand-primary color comes from tokens automatically.

4. Accessibility

If the icon is decorative (text label adjacent), add aria-hidden="true" on the SVG
If the icon is the only label (icon-only button), add aria-label="…" on the button
Never use color alone to convey state — pair with a label or shape change
Stroke-based icons remain legible at high-contrast mode (forced-colors)

5. Adding a new icon

Pick from lucide.dev — match the existing visual style (stroke-based, 24×24 viewBox, rounded caps)
Add an entry to ICONS map in modals-playground.html and ICONS here in icons.html
Open a PR — name the icon by semantic intent (warning not triangle-exclaim)
The token validator will not block this; it's a docs-only change

6. Don't

❌ Don't recolor inside the SVG (no fill="#22c55e" hardcoded — use currentColor)
❌ Don't add filters or effects to icons
❌ Don't use icons smaller than 14px (legibility)
❌ Don't mix stroke-based and fill-based icons in the same surface