Icon Guide

​

0. Direction A — Final Rules (canonical)

1. Library: Lucide-react only. Render through <AppIcon> from @/shared/ui/icon. Raw <LucideIcon … /> JSX is allowed only inside leaf primitives we don’t own (e.g. shadcn shells); everywhere else use AppIcon.
2. Stroke width: 1.5 (Apple-Minimal Outline). Never set strokeWidth inline on a Lucide tag — use <AppIcon> so the platform default applies, or pass weight="thin" | "regular" | "bold" for the rare exceptions (1.1 / 1.5 / 2.0).
3. Size scale (locked, 4 tiers): xs/14, sm/16, md/20, lg/24. No other sizes. 2xs/12 exists only for legacy dense table chrome and must not be used in new code.
4. Active-state behavior (navigation): the active item swaps the outline glyph for a filled variant — fill="currentColor" and strokeWidth={0} — paired with the text-primary tone. Use the getActiveIconSvgProps(isActive) helper in src/platform/navigation/utils/active-state.ts. Idle items stay outline at text-muted-foreground.
5. Color tokens (allow-list): the only colors permitted on an icon are the semantic tones below — applied via the tone prop, never hex/text-gray-*/text-blue-* literals.

   tone value	CSS class	When to use
   muted	text-muted-foreground	Default for idle nav, secondary chrome
   neutral	text-foreground	Body-level inline icons
   primary	text-primary	Active nav, primary CTAs
   accent	text-accent	Brand-accent surfaces
   onAccent	text-accent-foreground	Icons over bg-accent/bg-primary
   success	text-success	Confirmations, positive deltas
   warning	text-warning	Caution, attention
   destructive	text-destructive	Errors, delete, irreversible
   info	text-info	Info chips, neutral system messages
   current	text-current	Inherit current text color
   inherit	(none)	Caller controls color via parent

   Anything outside this list — including raw palette classes (text-blue-500, #0EA5E9) and per-module hex values — is rejected by the icon audit and PR review.
6. Variants: variant="outline" (default) for the line look, or variant="solid" to fill the glyph with currentColor (zeroes the stroke). The active-state filled treatment in rule 4 is the canonical use of solid.
7. Accessibility: decorative icons (default) get aria-hidden="true" automatically; meaningful icons must pass decorative={false} and a non-empty aria-label (TypeScript enforces this).

// ✅ canonical idle nav item
<AppIcon icon={Inbox} size="sm" tone="muted" />

// ✅ canonical active nav item (filled, primary tone)
<AppIcon icon={Inbox} size="sm" tone="primary" variant="solid" />

// ✅ icon-only button
<AppIcon icon={Trash2} size="sm" tone="destructive" decorative={false} aria-label="Delete row" />

// ❌ raw Lucide with palette color and inline stroke
<Inbox className="h-4 w-4 text-blue-500" strokeWidth={1.75} />

​

1. Quick Reference

​

Size tokens (Tailwind)

​

AppIcon wrapper (preferred for shared/component code)

import { Inbox, Trash2 } from 'lucide-react';
import { AppIcon } from '@/shared/ui/icon';

// Decorative (defaults to aria-hidden="true")
<AppIcon icon={Inbox} size="lg" tone="muted" />

// Meaningful (TypeScript requires aria-label)
<AppIcon icon={Trash2} size="sm" decorative={false} aria-label="Delete row" />

​

Import pattern

import { LayoutDashboard, Users, Building2 } from "lucide-react";

​

Accessibility

• Icon-only buttons: aria-label="Action name".
• Decorative (with visible text): aria-hidden="true" on the icon.

​

1.5 Approved Semantic Icons — Quick Reference

Audit: The standalone audit:icons and audit:icon-approvals scripts were removed. Use npm run audit:appicon-tones to flag className-vs-tone conflicts (APPICON-001..004); raw Lucide / inline-stroke / hardcoded-color and deprecated-import drift are now caught in PR review against the rules in §0.

​

Approved icons by concept

Healthcare copy-paste templates: see examples/wizard-templates/healthcare-icon-keys.json for ready-to-use PF-41 snippets using stethoscope, pill, and syringe.

​

Preferred vs. deprecated variants

​

DO NOT CHANGE mappings

​

Quick example

// ✅ Approved
<AppIcon icon={ShieldCheck} size="sm" className="text-success" />
<AppIcon icon={CheckCircle2} size="sm" decorative={false} aria-label="Approved" />

// ❌ Avoid
<CheckCircle className="h-4 w-4 text-green-500" />   // deprecated icon + raw color
<Shield className="h-4 w-4" />                        // generic, not "compliant"

​

Tone & variant (v1.3.0)

// Before — hand-typed token, easy to drift
<AppIcon icon={CheckCircle2} size="sm" className="text-success" />

// After — tone shorthand, registry-backed
<AppIcon icon={CheckCircle2} size="sm" tone="success" />

// Filled glyph for solid badges
<AppIcon icon={CircleAlert} size="sm" tone="destructive" variant="solid" />

​

Solid variant cookbook

• Toolbar / icon-button affordances (Pencil, Trash2, Search, Filter) — outline is the default app feel.
• Navigation rails and sidebar items — outline keeps the chrome quiet.
• Decorative inline icons next to body text — solid will dominate the line.
• Anything where the icon is larger than lg (24 px) — at hero sizes the filled shape can read as a logo.

// Status badge — solid for terminal/severe states
import { CheckCircle2, XCircle, CircleAlert } from 'lucide-react';
import { createStatusBadge } from '@/shared/components/StatusBadge';

type ClaimStatus = 'paid' | 'pending' | 'denied' | 'overdue';

export const ClaimStatusBadge = createStatusBadge<ClaimStatus>({
  paid:    { label: 'Paid',    variant: 'success',     icon: CheckCircle2, iconTone: 'success',     iconVariant: 'solid' },
  pending: { label: 'Pending', variant: 'warning',     icon: CircleAlert,  iconTone: 'warning'      /* outline */ },
  denied:  { label: 'Denied',  variant: 'destructive', icon: XCircle,      iconTone: 'destructive', iconVariant: 'solid' },
  overdue: { label: 'Overdue', variant: 'destructive', icon: CircleAlert,  iconTone: 'destructive', iconVariant: 'solid' },
});

// Hero icon-in-circle — solid reads as a single anchor inside the tint
<div className="rounded-full bg-destructive/10 p-3">
  <AppIcon icon={CircleAlert} size="lg" tone="destructive" variant="solid" />
</div>

// Sonner toast leading icon
toast.success('Claim submitted', {
  icon: <AppIcon icon={CheckCircle2} size="sm" tone="success" variant="solid" />,
});

// ❌ Don't: solid on a toolbar button — too heavy
<AppIcon icon={Pencil} size="sm" variant="solid" />
// ✅ Do:
<AppIcon icon={Pencil} size="sm" tone="muted" />

• ErrorState — hero icon uses variant="solid" inside the tinted circle wrapper (destructive and warning severities).
• StatusBadge / createStatusBadge<T>() — accepts iconVariant: 'solid' | 'outline' per status key, so domain badges opt in to solid only for the states that warrant the extra weight.

import { semanticStatusToIconTone } from '@/shared/lib/semantic-colors';
<AppIcon icon={Icon} size="xs" tone={semanticStatusToIconTone(status)} />

​

Domain status aliases (v1.4.0)

import { domainStatusToIconTone } from '@/shared/lib/semantic-colors';

// CE lead, PM claim, FW workflow run — all use the same helper.
<AppIcon icon={CheckCircle2} size="sm" tone={domainStatusToIconTone(lead.status)} />
<AppIcon icon={CircleAlert} size="sm" tone={domainStatusToIconTone(claim.status)} variant="solid" />

• Input is normalized (PascalCase, kebab-case, Title Case all work), so DB enums can be passed verbatim.
• Unknown keys fall back to tone="muted" — the UI never breaks on a new/unmapped status, mirroring the wizard-step icon fallback (§5).
• To add a new status, edit DOMAIN_STATUS_TONE and this table only; do not introduce a new AppIconTone value.

​

Cross-references

• Full universal/status/compliance tables → §2 (Assignment Principles).
• Wizard step string keys + resolveStepIcon() contract → §5.
• Module + healthcare icon catalog → §6.
• Anti-patterns and deprecations → §7.

​

2. Assignment Principles

• Semantic consistency: Same concept → same icon across modules.
• Visual differentiation: Similar but distinct concepts → different icons.
• Accessibility: Sufficient contrast; pair with text labels.

​

Universal icons (DO NOT CHANGE)

​

Alert & status (do not interchange)

​

Compliance & security

​

3. Size, color, and usage patterns

// Standard
<Button>
  <Plus className="h-5 w-5 mr-2" />
  Add New
</Button>

// Semantic color
<ShieldCheck className="h-5 w-5 text-success" />
<UserMinus className="h-5 w-5 text-destructive" />

​

4. Accessibility

• Icon-only buttons: Always aria-label (e.g. aria-label="View dashboard").
• Decorative icon next to text: aria-hidden="true" on the icon.
• See UI_UX_STANDARDS.md § Accessibility for focus and ARIA.

<button aria-label="View dashboard">
  <LayoutDashboard className="h-5 w-5" />
</button>

<div>
  <Clock className="h-5 w-5" aria-hidden="true" />
  <span>Time Clock</span>
</div>

​

5. Wizard step icons

​

6. Module-specific patterns (summary)

​

Healthcare & clinical (CL / PM)

​

7. Anti-patterns

• Do not use AlertTriangle for everything; differentiate by context.
• Do not use TrendingDown for negative performance; use AlertOctagon for PIPs.
• Do not use Shield for compliance; use ShieldCheck.
• Do not use icons without labels for interactive elements.
• Do not import * as Icons from "lucide-react"; import only what you use.

​

8. Adding new icons

1. Search Lucide icons.
2. Check if a similar concept exists in this guide.
3. Prefer semantic icons; document the new icon here before use.

​

References

• UI_UX_STANDARDS.md § Icons
• SEMANTIC_COLORS.md
• Lucide React
• WCAG non-text content

​

Lint enforcement

• APPICON-001 (failure) — className carries a semantic color token (e.g. text-success) and tone is set. Pick one.
• APPICON-002 (failure) — className carries a Tailwind palette class (e.g. text-amber-700). Use tone or a semantic token; palette classes don’t react to dark mode or PF-95 tenant theming.
• APPICON-003 (failure) — tone literal isn’t a member of AppIconTone (typos like tone="successful").
• APPICON-004 (warning) — variant="solid" paired with weight=… (weight is ignored when solid forces stroke-width 0).

​

Autofix

​

9. Recent changes (PR-2, PR-3 — 2026-05-24)

​

PR-2 — Color token normalization

• Module color aliases collapsed to canonical short codes. The duplicate --module-clinical, --module-finance, --module-operations, and --module-people aliases (and their @theme mappings) were removed. The full set of supported module identity tokens is now: --module-pf, --module-cl, --module-pm, --module-fm, --module-rh, --module-it, --module-hr, --module-lo, --module-ce, --module-fa, --module-gr, --module-fw, --module-th, --module-qo, --module-da, --module-rpt. Each token resolves to a single canonical HSL triplet per mode with paired *-foreground and *-subtle (background tint) variants.
• Tint balance pass. Finance amber was desaturated so it sits in-band with the rest of the family (no longer the loudest tile). Subtle backgrounds were unified at L:92–94% in light mode and L:20–22% in dark mode so module tiles read as one set on both surfaces.

1. Never use a long-form alias. text-[hsl(var(--module-clinical))] etc. are gone — use the short code (--module-cl) or, preferably, a semantic tone on AppIcon.
2. Module identity tokens are nav/widget chrome only, never data series. Series colors stay on the chart palette (hsl(var(--chart-N)), N = 1–8) per SEMANTIC_COLORS.md.
3. No inline style={{ color: tintColor }} on icons. Module tinting must flow through CSS custom properties on the surrounding tile, with the icon inheriting via tone="current" or tone="onAccent".

// ✅ canonical module tile (Clinical)
<div className="bg-[hsl(var(--module-cl-subtle))] text-[hsl(var(--module-cl))]">
  <AppIcon icon={Stethoscope} size="md" tone="current" />
</div>

// ❌ removed alias + raw inline color
<div style={{ color: 'hsl(var(--module-clinical))' }}>
  <Stethoscope className="h-5 w-5" />
</div>

​

PR-3 — AppIcon migration (raw Lucide → <AppIcon>)

1. No raw <LucideIcon … /> in src/cores/**, src/platform/**, or src/shared/components/**. Render through <AppIcon> from @/shared/ui/icon. The only exception is leaf primitives we don’t own (shadcn shells) — those are tracked in reports/icon-audit-latest.json and must migrate when touched.
2. No className="size-N" / h-N w-N" for sizing an icon. Use size="xs" | "sm" | "md" | "lg" (14 / 16 / 20 / 24 px). The four-tier scale is locked.
3. No inline strokeWidth={…}. The platform default is 1.5. For the rare exceptions use weight="thin" | "regular" | "bold".
4. No palette/hex colors on icons. Use the tone allow-list (§0, rule 5). Status-driven UIs derive tone via semanticStatusToIconTone() or domainStatusToIconTone().
5. Active-nav fill treatment goes through getActiveIconSvgProps(isActive) from src/platform/navigation/utils/active-state.ts, not hand-typed fill/strokeWidth props.

// Before
import { Inbox } from 'lucide-react';
<Inbox className="size-4 text-blue-500" strokeWidth={1.75} />

// 1. Import AppIcon, keep the Lucide import (now used as a value)
import { Inbox } from 'lucide-react';
import { AppIcon } from '@/shared/ui/icon';

// 2. Map size class → size prop
//    size-3.5 / h-3.5 w-3.5 → "xs"
//    size-4   / h-4 w-4     → "sm"
//    size-5   / h-5 w-5     → "md"
//    size-6   / h-6 w-6     → "lg"

// 3. Drop strokeWidth (or convert to weight)

// 4. Convert color className → tone (see APPICON-002 mapping):
//    text-muted-foreground → tone="muted"
//    text-foreground       → tone="neutral"
//    text-primary          → tone="primary"
//    text-success/600 etc. → tone="success"
//    text-destructive/red* → tone="destructive"
//    text-amber-*/yellow*  → tone="warning"
//    text-blue-*/sky-*     → tone="info"

// After
<AppIcon icon={Inbox} size="sm" tone="info" />

<AppIcon icon={Trash2} size="sm" tone="destructive" decorative={false} aria-label="Delete row" />

npm run audit:appicon-tones     # className vs tone conflicts (APPICON-001..004)
npm run audit:appicon-tones:fix # mechanical autofix for 001/002/004