Foundation

Icons

Nerio components consume icons through a small adapter API. Lucide is the default source, but custom SVG React components use the same contract.

Icon adapter contract

@nerio-ui/adapters/icons

Source	Contract
Lucide	Default icon source via `@nerio-ui/adapters/icons`.
Custom SVG	React SVG components implement `IconSvgProps` and use the same `Icon` contract.

Size contract

Size	Token	Default
Extra small	`--n-icon-size-xs`	12px
Small	`--n-icon-size-sm`	14px
Medium	`--n-icon-size-md`	16px
Large	`--n-icon-size-lg`	18px
Extra large	`--n-icon-size-xl`	20px

Role	Token	Default
Inline icon	`--n-icon-inline-size`	`1em`
Button icon	`--n-button-icon-size`	`--n-icon-size-md`
Small icon-only Button	`--n-icon-button-icon-size-sm`	`--n-icon-size-md`
Medium icon-only Button	`--n-icon-button-icon-size-md`	`--n-icon-size-lg`
Large icon-only Button	`--n-icon-button-icon-size-lg`	`--n-icon-size-xl`

Contract

Rule	Reason
Pass React icon components through the icon prop.	Components stay independent from Lucide implementation details.
Use the default decorative mode inside named controls and labelled content.	The renderer sets `aria-hidden` and prevents the SVG from receiving keyboard focus, so the surrounding text remains the accessible name.
Set `decorative={false}` and provide `label` for a standalone meaningful icon.	The renderer exposes an image role and the supplied accessible name.
Icon-only controls require an accessible label.	The visible icon is decorative; the label names the action.
Use semantic color tokens around icons.	Icons inherit text color and stay theme-aware.
Let component aliases set icon size.	Buttons and icon-only controls keep glyphs proportional to their hit area.
Opt into Lucide fixed strokes explicitly.	Use `lucideAbsoluteStrokeWidth` only with Lucide icons. Generic `IconSvgProps` never includes the Lucide-only property, so ordinary custom SVG prop spreads stay warning-free.

Usage

1import { Search } from '@nerio-ui/adapters/icons';2import { Icon } from '@nerio-ui/ui';3import { Button } from '@nerio-ui/ui/client';45<Icon icon={Search} />6<Icon icon={Search} lucideAbsoluteStrokeWidth />7<Button icon={Search} aria-label="Search workspace" tooltip="Search workspace" />

1import type { IconSvgProps } from '@nerio-ui/adapters/icons';23function CustomLogoIcon({ strokeWidth = 2, ...props }: IconSvgProps) {4  return (5    <svg viewBox="0 0 24 24" fill="none" {...props}>6      <path d="M5 17V7l7 10V7l7 10V7" stroke="currentColor" strokeWidth={strokeWidth} />7    </svg>8  );9}1011<Icon decorative={false} icon={CustomLogoIcon} label="Nerio logo" />

Migration

Import IconComponent and IconSvgProps from @nerio-ui/adapters/icons for icon props and custom SVG implementations. The same type names remain re-exported from @nerio-ui/ui as compatible aliases, but new component APIs should use the adapter boundary. Existing LucideIcon imports remain compatible while Lucide is the default source. During the Core 0.1 alpha, replace an explicit absoluteStrokeWidth Icon prop with lucideAbsoluteStrokeWidth; the old name remains as a deprecated alias until the next major version. Custom SVG components should accept and spread only IconSvgProps.

The previous @nerio-ui/adapters root import is intentionally unsupported during the pre-release alpha. Use the explicit icons subpath so UI consumers do not resolve unrelated table, chart, form, or schema integrations.

Do / do not

Guidance	Recommendation
Do	Use icons to clarify compact actions and metadata when text would be repetitive.
Do not	Use brand color for routine icons or rely on an icon without an accessible name.