Icon

Icons are named React components that render SVG from @by/icons. Import only the glyphs you need from the namespace that owns them (ui, nav, app, or flags). Pair @by/icons with @by/experience-system when you use primitives such as Button, Alert, or InputGroup that expect inline icons.

For broader iconography guidance (namespaces, catalog browsing, and UX principles), see Iconography.

Installation

Icons ship in @by/icons. Add the package with your package manager. When you use Experience System primitives alongside icons, also install @by/experience-system.

pnpm add @by/icons

In this monorepo, reference the workspace packages (for example workspace:* or your catalog) so imports resolve to packages/icons and packages/experience-system.

Composition

Each icon is a single exported component that renders one <svg> element:

Home                    (example: named export from @by/icons/ui)
└── <svg> … </svg>

There is no shared Icon wrapper in @by/experience-system—pick the PascalCase component that matches the asset (for example Home, Search, ArrowChevronDown). File names in the package use kebab-case; the generator maps them to valid React identifiers.

Usage

Import named components from the namespace entry point that owns the glyph:

import { Home, Search, Settings, User } from '@by/icons/ui';

Each icon is a forwardRef component that forwards props to the root <svg>. Defaults are width={24} and height={24}; override size with width / height, Tailwind utilities such as size-4 or size-scaled-10, and color with semantic fill-* tokens (for example fill-neutral-12, fill-accent-9).

<Home />
<User className="size-scaled-10 fill-accent-9" />
<Settings width={40} height={40} className="fill-neutral-12" />

When placing icons in Button, set data-icon="inline-start" or data-icon="inline-end" on the icon (or Spinner) so padding stays balanced—see Button.

Product UX guidance (metaphor, outlined vs filled, and when to use color) is documented on Fractal Icon (Confluence).

When to use

• @by/icons/ui — general actions, status, alerts, and common controls.
• @by/icons/nav — navigation and shell affordances.
• @by/icons/app — product- or app-specific marks.
• @by/icons/flags — country, currency, and region flags.

When not to use

• Do not mix outlined and filled icons arbitrarily; use outlined by default and filled variants for toggled states where product guidance calls for it.
• Do not use semantic color tokens on purely decorative icons—prefer fill-neutral-* unless color conveys meaning.

Examples

Overview

Default size, explicit dimensions, and token-based color on a few common UI icons. The live preview at the top of this page uses the same example (icon-usage).

Browse and search

Search by name, namespace, or tags. Open a tile to inspect an icon, adjust preview size and color, and copy the name, import line, or usage snippet.

API Reference

Icon components are generated in @by/icons from SVG sources. Each named export (for example Home, Search) is a React.forwardRef<SVGSVGElement, React.SVGProps<SVGSVGElement>> that renders a single root <svg>. The tables below describe the shared surface; the full attribute list is defined by MDN’s SVG element reference and React’s SVGProps<SVGSVGElement>.

Icon components (named exports)

Every icon in a namespace follows the same prop contract.

Also accepts all standard SVGProps<SVGSVGElement> attributes (aria-*, role, fill, stroke, viewBox is fixed per asset, and so on).

Metadata

@by/icons/metadata exposes JSON metadata (including tags per icon) for search, catalogs, and tooling.

Accessibility

Treat icons as decorative when nearby text already conveys the same meaning: set aria-hidden on the icon (or rely on the host primitive to hide it). When an icon is the only visible label for an interactive control (for example an icon-only Button), provide an accessible name on the interactive parent with aria-label (and visible text where possible). Do not rely on the glyph alone to communicate critical information.

See Accessibility for broader guidance and Button for icon-only control patterns.

Source in the repo: generated components under packages/icons/output/; build scripts and SVG sources under packages/icons. Agent-oriented contracts: packages/icons/instructions/ (start with index.md and icon-usage.md).