@antscorp/ui-icons

Monochrome SVG glyphs and React >=19.2 components. This optional icon set has its own release line and no dependency on the UI kit or theme.

bun add @antscorp/ui-icons

Use a glyph with the UI facade's Astryx wrapper for token-based sizing and colour:

import { AccountCircleIcon } from "@antscorp/ui-icons";
import { Icon } from "@antscorp/ui/astryx/Icon";

<Icon icon={AccountCircleIcon} size="sm" color="primary" />;

Install @antscorp/ui separately when using that wrapper. The facade does not re-export this set. Astryx semantic names still use its built-in drawings.

Standalone components inherit currentColor, default to 24 × 24, and accept native SVG props, including React 19 refs. Explicit width and height take precedence over size:

import { AccountCircleIcon } from "@antscorp/ui-icons";

<AccountCircleIcon size="1em" aria-label="Account" role="img" />;

Glyphs are decorative (aria-hidden="true") unless aria-label, aria-labelledby or role is supplied. Explicit caller props win. Each instance owns its clipping and masking ids. The package provides source through antscorp-source and compiled ESM with declarations by default. Modules have no side effects; unused glyphs can be tree-shaken.

Raw normalized SVGs are exported at @antscorp/ui-icons/svg/<kebab-name>.svg, for example @antscorp/ui-icons/svg/account-circle.svg. Non-React hosts can load them through their asset tooling; the same file contents support copy-as-SVG workflows. The host's loader determines whether an SVG import returns a URL or SVG text. There are 410 raw drawings; the animated LoadingIcon is authored separately and has no raw loading.svg export.

The set also restores the monochrome theme drawings removed in 0.3. See the theme glyph mapping for replacement exports; installing the set does not change Astryx's semantic defaults.

Loading

For kit loading states, prefer Astryx Spinner for action feedback or skeletons for known content shapes (ADR 0011). LoadingIcon is for hosts that need the existing 41-unit arc drawing. It rotates and eases its dashes over 1.5 seconds using SVG SMIL, inherits currentColor, and takes the same SVG props as other glyphs.

Reduced-motion preferences show the static arc and respond to live preference changes. Server rendering defaults to animation; hosts without matchMedia still render safely. No stylesheet or import-time browser setup is required. The old backgroundColor track prop is removed: draw a host circle behind the arc, or use Astryx Spinner when a track is needed.

Adding a glyph

In this repository, add svg/<kebab-name>.svg with a viewBox, then run:

bun run --cwd packages/icons generate
bun run --cwd packages/icons test
bun run --cwd packages/icons build

SVG files are the source of truth. The generator uses SVGO's parsed tree to optimize geometry, inline supported styles, validate monochrome paints, preserve none, and replace local ids with per-instance references. It rejects unsafe elements or events, missing view boxes, unresolved references, duplicate names and styles it cannot inline. Check in both SVGs and generated src/icons modules and barrel; do not edit generated TSX manually. src/LoadingIcon.tsx is the sole authored exception; generation preserves its deterministic barrel export and rejects a conflicting loading.svg.

Contrasting details are transparent cut-outs, with meaningful secondary parts rendered in currentColor at opacity 0.4 or higher. Visible geometry accepts only currentColor or none. Only masks may contain #fff/white and #000/black; those masks use luminance for coverage. Masks containing only current-colour geometry use alpha so dark foregrounds remain visible. See MIGRATION.md for every renamed or dropped legacy export and animation notes.

Host drawings

Use createIcon for drawings owned by the consuming application:

import { createIcon } from "@antscorp/ui-icons";

const DiamondIcon = createIcon("DiamondIcon", "0 0 24 24", <path d="M12 2 22 12 12 22 2 12Z" />);

For clipping, masking or reuse, pass (id) => ReactNode as the third argument. Append a distinct suffix to that id for every SVG definition, and use the same value in each href or url(#…) reference. The factory calls useId for every instance, including hidden ones.

See the repository README for development and releases.