Guidelines

Iconography

Icons do interface work: they point, close, open and confirm. Lucide covers the interface; the Builtwell set covers the product surfaces. Neither decorates, and neither stands in for a word the reader needs.

Interface: Lucide

lucide-react, the set shadcn components already use. A 2px stroke on a 24px grid that sits well next to Suisse. Size with size-*; colour follows the text.
  • Search
  • Menu
  • X
  • ArrowRight
  • ArrowUpRight
  • ChevronDown
  • Plus
  • Check
  • Copy
  • Mail
import { ArrowRight } from "lucide-react";

<Button>
  Start a project
  <ArrowRight aria-hidden="true" data-icon="inline-end" />
</Button>

Product: the Builtwell set

From packages/design-system/components/icons, exported from its index. Filled glyphs on a 16px grid, drawn in currentColor, sized with a size prop in px (16 by default). Reach for them in the chat and builder surfaces they were drawn for.
  • ArrowDown
  • Arrow
  • ArrowUp
  • ArrowUpRight
  • Attachment
  • Bot
  • Box
  • CheckCircleFill
  • CheckedSquare
  • ChevronDown
  • Code
  • Copy
  • Cross
  • CrossSmall
  • Delta
  • Download
  • Eye
  • File
  • Fullscreen
  • Globe
  • GPS
  • Home
  • Image
  • Info
  • Invoice
  • LineChart
  • Loader
  • Lock
  • Logs
  • Menu
  • Message
  • MoreHorizontal
  • More
  • Paperclip
  • Pen
  • PencilEdit
  • Play
  • Plus
  • Redo
  • Route
  • Share
  • SidebarLeft
  • Sparkles
  • Stop
  • Summarize
  • Terminal
  • TerminalWindow
  • ThumbDown
  • ThumbUp
  • Trash
  • UncheckedSquare
  • Undo
  • Upload
  • User
  • Warning

Third-party marks in the same folder, for model and platform pickers:

  • Git
  • LogoAnthropic
  • LogoGoogle
  • LogoOpenAI
  • Python
  • Vercel
import { SparklesIcon } from "@repo/design-system/components/icons";

<span aria-hidden="true" className="text-brand">
  <SparklesIcon size={16} />
</span>

Sizes

Four sizes, on the 4px scale. Pick the one that matches the text beside it.
ClasspxSpecimenUse
size-416Inside buttons and inputs. The shadcn default.
size-520Beside p-sm and p-base text, in lists and menus.
size-624Standalone: the menu toggle, a close button.
size-832Feature icons in a card. The largest UI size.

Labels

An icon is either decoration beside a word, or the only label a control has. Mark up each accordingly.
Icon-only: the button carries the name
Beside a word: the icon is hidden
DoSay it, and let the icon point. Icon-only only for universal controls: search, menu, close.
Don'tIcons in place of words people need. Add what? Copy what?

Rules

  • Lucide for interface icons. Don't mix in another outline set.
  • Decorative icons get aria-hidden="true". Icon-only buttons get an aria-label that names the action.
  • Colour comes from the text: text-foreground, text-muted-foreground, text-brand. Never a colour of its own.
  • One icon per control. No icon on every list item or heading.
  • Keep the stroke Lucide ships with. Don't thin it to look elegant at large sizes; use a smaller icon.