Icon Rules

Installation

pnpm dlx shadcn@latest add @aura/rule-fundation-icons

Icon Library

• MUST: Icons should be from a library, not custom SVGs or inline graphics.
• MUST: By default, use Radix icons (@radix-ui/react-icons).
• MUST: Project must have only one icon library.
• EXCEPTION: If the project has two icon libraries, it should be Radix icons (default) and one other library (e.g., lucide-react).
• MUST: Import icons from the designated library: import { IconName } from "@radix-ui/react-icons".

Icon Sizing

• MUST: Use className="icon" for all icons, never use size prop or width/height attributes.
• MUST: Icons are handled as typography, meaning they inherit font-size from typography classes.
• MUST: To make icons larger, combine icon class with typography classes (e.g., className="icon h1" for large icons).
• EXAMPLES:
  • Small icon: className="icon"
  • Medium icon: className="icon h4"
  • Large icon: className="icon h1"

Icon Spacing

• MUST: Space an icon from its label with gap on the container, never with a margin on the icon.
• NEVER: Add ml-*, mr-*, mx-*, ms-* or me-* to an icon to separate it from text (aura/no-icon-margin reports it).
• MUST: Inside Button and Badge, add nothing—the control already owns the gap (--aura-button-gap, 6.5px, on .button and its button-fill / button-pill / button-link / button-menu variants; gap-0.5 on Badge).
• MUST: When composing your own icon + text row, put gap-0.5 (6.5px) on the flex container. Remember gap-2 is 26px on the 13px grid, not 8px.
• EXCEPTION: ml-auto / mr-auto are layout, not spacing—use them to push a trailing icon (e.g. a chevron) to the end.

Implementation

// Correct
import { CheckIcon } from "@radix-ui/react-icons";
<CheckIcon className="icon" />
<CheckIcon className="icon h1" />
<Button><CheckIcon className="icon" />Save</Button>
<div className="flex items-center gap-0.5"><CheckIcon className="icon" />Saved</div>

// Incorrect
<CheckIcon size={24} />
<CheckIcon width={24} height={24} />
<Button><CheckIcon className="icon mr-1" />Save</Button>