Icon Library

Preview

import { Plus, ChevronDown, CircleAlert } from '@oshon-ai/components/icons';

<Plus size={20} />
<ChevronDown size={16} label="Toggle section" />
<CircleAlert size={24} style={{ color: 'var(--oshon-color-error-600)' }} />

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add icons

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { IconLibrary } from '@oshon-ai/components';

export default function Example() {
  return <IconLibrary />;
}

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<IconLibrary
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-05-20

Do / Don't

import { Plus } from '@oshon-ai/components/icons';
<Plus size={20} />

<ButtonHug tier="primary" style={{ color: 'var(--oshon-color-on-primary)' }}>
  <Plus />
  Add member
</ButtonHug>

<Trash label="Delete row" size={20} onClick={onDelete} />

import { Icon, type IconName } from '@oshon-ai/components/icons';
const names: IconName[] = ['check', 'x', 'info'];
names.map(n => <Icon key={n} name={n} />)

<Plus style={{ fill: 'red', stroke: 'red' }} />

<Icon name="plus" />

<button><Trash label="Delete" /> Delete</button>

Related

• @oshon-ai/components/button
• @oshon-ai/components/badge

Design rationale

Tree-shaking is the dominant constraint — a real icon library lives or dies on bundle impact. Each glyph is its own named React component with no shared mutable state so esbuild / Rollup / Webpack can drop unused icons. The shared `IconBase` is intentionally tiny — just the `<svg>` shell + a11y wiring — so importing one icon pays for ~200 bytes of base plus the icon's own ~50-300 bytes of path data. Color inheritance via `currentColor` (instead of a `color` prop) keeps the API minimal and lets consumers theme icons through normal CSS cascade. The catalog is generated from lucide-static — 1,960 icons in v1.16.0 — by `scripts/generate-from-lucide.mjs`. Lucide is the modern shadcn / Vercel / HeroUI default; its 2-px stroke, 24×24 viewBox, and round caps + joins match `IconBase` exactly. The generator output is deterministic (same Lucide version → byte-identical files) and the public API is unchanged, so swapping to a Figma DS 3.1 export pipeline in a future release is a generator-side refactor with no consumer impact.