Iconography

Lucide-only policy

Lucide is on v1 — brand icons are gone

The version scale jumped from 0.x to 1.x without changing the icon API, which is why the package declares the peer as >=0.540.0. What v1 did change is the catalogue: the third-party brand and logo icons were removed. Importing one is a build error, not a missing glyph.

Some older names survive as deprecated aliases — Loader2 still resolves to LoaderCircle, AlertCircle to CircleAlert. Write the v1 name in new code.

Size grid

Icon size comes from the spacing scale, not the type scale. That is what lets the text-size axis move icons and labels together: at the large step a size-4 icon grows with the 16px label beside it instead of standing still while the label swells.

Automatic sizing

Twenty-one places across eleven component families carry [&_svg:not([class*='size-'])]:size-4— menu and command rows, Select triggers and items, ItemMedia, InputGroup addons, ButtonGroupText, NavigationMenu links, Toggle, and the Dialog close button. An icon dropped into one of those with no size class of its own renders at 16px, so an explicit size-4 is redundant there, while size-5 genuinely overrides.

Button is deliberately not one of them: it sets a gap and a text size but applies nothing to a child svg, so an icon inside a button keeps Lucide's own default of 24px until you size it. Give it a size-* class, or a size prop when it goes through leftIcon / rightIcon.

Icon colour follows the colour contract

Lucide renders with stroke="currentColor", so an icon takes the text colour of whatever contains it. That makes the three-role contract apply unchanged — and it means the wrong choice is invisible to the compiler.

Passing an icon to a component

Shell components that take an icon — nav items, app descriptors, sidebar entries — accept the component reference rather than a rendered element, so they can apply their own size and colour classes to it.

import type { NavItem } from '@comitor/ui/shell'
import { LayoutDashboard } from 'lucide-react'

// The slot takes the COMPONENT, not an element:
//   icon: LayoutDashboard      ✓
//   icon: <LayoutDashboard />  ✗
const item: NavItem = {
  id: 'overview',
  label: 'Overview',
  href: '/tasks',
  icon: LayoutDashboard,
}

// The slot's type is ShellIcon = LucideIcon | ComponentType<{ className?: string }>,
// so a custom SVG wrapper that accepts className fits the same slot.

Sample icons — 16px default

Stroke and usage