Icon Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

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: Run npm run audit:icons to find raw Lucide / inline-stroke / hardcoded-color offenders in src/shared/components/** and src/platform/**. Latest snapshot JSON: reports/icon-audit-latest.json. Approval audit: Run npm run audit:icon-approvals (or …:strict to fail CI) to flag deprecated Lucide imports (e.g. CheckCircle, AlertCircle) and DO NOT CHANGE mapping violations (context phrase + wrong icon in same JSX). Report: reports/icon-approvals-latest.json.

​

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