Skip to main content
Expression

Icons

Draft

Our icon system is built for clarity and consistency. It aims to be bold, communicative, and functional, complementing typography and fitting naturally within every component.

Common alternative names

Iconography, glyphs, pictograms, symbols

Icon set​

Arch UI includes 474 icons from the @mdi/svg library, wrapped as typed React components in the @arch-ui/icons package. Each icon follows the naming pattern {Name}Icon — for example, SearchIcon, ChevronDownIcon, or AlertTriangleIcon.

The set covers five broad categories:

CategoryExamples
NavigationArrowUpIcon, ChevronLeftIcon, MenuIcon, OpenInNewIcon
ActionsPencilIcon, DeleteIcon, DownloadIcon, UploadIcon, ContentCopyIcon
StatusCheckCircleIcon, AlertIcon, AlertCircleIcon, InformationIcon
ObjectsFileDocumentIcon, FolderIcon, ImageIcon, CalendarIcon, AccountIcon
ControlsPlusIcon, MinusIcon, CloseIcon, FilterIcon, MagnifyIcon

Sizes​

Arch UI supports three icon sizes. Each maps to a specific use case — do not scale icons to arbitrary pixel values.

16pxCompact UI
20pxDefault
24pxNavigation
SizePixelsUse case
size={16}16 × 16Inline with small text, compact UI, table cells
size={20}20 × 20Default for form controls, buttons, input adornments
size={24}24 × 24Navigation, page headers, standalone icon buttons

All icons share a viewBox="0 0 24 24" and are scaled via the width and height attributes, so they remain crisp at every size.

Grid and alignment​

All icons are drawn on a 24-unit grid with 2 units of internal padding, giving a 20-unit live area. Paths use filled shapes (no strokes) for consistent rendering across browsers and pixel densities.

When aligning icons with text, use align-items: center on a flex container. The icons are designed to optically center alongside text set in Inter at the corresponding size.

Accessibility​

Decorative vs. meaningful icons​

Every icon in Arch UI renders with aria-hidden="true" by default. This is correct when the icon accompanies visible text that already communicates the meaning. If the icon is the only element conveying information — for example, an icon-only button — you must provide an aria-label:

{/* Decorative — label is visible */}
<button>
  <TrashIcon /> Delete
</button>

{/* Meaningful — icon is the only content */}
<button aria-label="Delete item">
  <TrashIcon aria-label="Delete" />
</button>

When aria-label is provided, the component automatically sets role="img" and removes aria-hidden, making the icon visible to assistive technology.

Minimum touch target​

Icon-only buttons must meet a 44 × 44 px minimum touch target (WCAG 2.5.8). The icon itself can be 16, 20, or 24 px, so pad the clickable area with spacing or a transparent border to reach the target size.

Do / Don't​

<button aria-label="Close"><CloseIcon /></button>
✓ Do

Wrap interactive icons in a <button> and provide aria-label when there is no visible text.

<CloseIcon onClick={close} />
✕ Don't

Don't attach onClick directly to the icon SVG or rely on a tooltip as the only accessible name.

<Icon size={20} />
✓ Do

Use one of the three supported sizes (16, 20, 24). They are optimized for pixel-perfect rendering.

<Icon size={22} />
✕ Don't

Scaling icons to arbitrary values like 18 or 22 produces blurry edges.

color: var(--color-icon-default);
✓ Do

Let icons inherit currentColor from the parent or pass a semantic color token.

color: #333;
✕ Don't

Hardcoded hex values bypass the color system and break in dark mode.