Semantic Color Reference

​

Overview

What changed in v1.4.1 (2026-04-18): Chart Palette § “Colorblind safety” updated with the first formal audit results from npm run audit:chart-palette-colorblind (Brettel-Viénot-Mollon simulation + CIE76 ΔE in CIELAB). Audit reveals 9 fail / 25 warn pairs across both modes × 3 dichromacy profiles — see the new Known limitations & action items subsection. The mandatory rule “always pair color with shape/pattern/label” is now load-bearing for accessibility, not just defensive practice. What changed in v1.4.0 (2026-04-18): Added the Token Catalog Reference (full surface/role/status/special/sidebar inventory), a Module Identity Tokens section (12 active short codes + reserved + deprecated aliases), an expanded Chart Palette section, a Tenant Theming (PF-95) Mapping Table that documents the gaps between platform tokens and tenant-customizable colors, and a Compliance Theming (PF-91-EN-01) Mapping section. Includes a regression note for the previous info.full dark-mode WCAG defect (now fixed).

​

Typography Token Contract

• Canonical tokens:
  • --font-display: Space Grotesk
  • --font-body: Inter
  • --font-mono: DM Mono (code, monospace data)
• Runtime mappings:
  • font-sans → var(--tenant-font-family, var(--font-body))
  • font-heading → var(--tenant-font-heading, var(--font-display))

• --tenant-font-family overrides body/sans
• --tenant-font-heading overrides heading/display

​

Standard Mappings

Token note (PF-95 update, 2026-04): --color-secondary now maps to hsl(var(--secondary)) (shadcn-canonical) so the tenant bridge --tenant-secondary-hsl actually drives bg-secondary / text-secondary. For the elevated card surface, use bg-card-elevated directly. --color-input resolves to --input, which in :root shares --tenant-border-hsl with --border per shadcn convention — set the tenant border once and inputs follow. See DESIGN_TOKEN_SYNC_POLICY.md.

​

Badge Variants

​

Subtle / Light Badge Variants

​

Specialty Badge Variants

​

Status Badge Pattern

1. Define a config: statusConfig: Record<Status, { label: string; variant: BadgeVariant; icon?: LucideIcon }>.
2. Render: <Badge variant={config.variant}>{config.label}</Badge> or use <StatusBadge status={status} statusConfig={statusConfig} /> from @/shared/components/StatusBadge.
3. Variant mapping: Use the canonical status-to-variant map in @/shared/lib/status-variants: CANONICAL_STATUS_VARIANTS and getCanonicalVariant(status). New status badges SHOULD use these canonical mappings; existing badges will be migrated incrementally. Fallback semantic guidance: success (active, approved, completed), warning (pending, in progress, expiring), destructive (rejected, error, cancelled, failed), info (new, submitted), secondary (draft, inactive, closed).

​

When to Use Semantic vs Categorical Colors

​

Use Semantic Colors For:

• ✅ Status indicators (active, pending, error, complete)
• ✅ Validation feedback (valid, invalid, warning)
• ✅ Health indicators (healthy, at-risk, critical)
• ✅ Action feedback (success, failure)
• ✅ Priority levels (critical, high, medium, low)

​

Keep Categorical Colors For:

• 🎨 Data type indicators (string=blue, number=green, boolean=purple)
• 🎨 Core/module identifiers (hr=blue, rh=green, fa=amber)
• 🎨 Category distinctions that don’t imply status
• 🎨 Brand colors that must remain consistent

​

Utility Functions

import { getStatusColors, type SemanticStatus } from '@/shared/lib/semantic-colors';

// Get all color classes for a status
const colors = getStatusColors('success');
// Returns: { bg, bgSubtle, text, border, full }

// Example usage
<div className={colors.bgSubtle}>
  <span className={colors.text}>Success message</span>
</div>

​

Examples

​

Before (DON’T DO THIS)

// ❌ Hardcoded colors - violates design system
<Badge className="bg-green-100 text-green-800">Active</Badge>
<Badge className="bg-yellow-100 text-yellow-800">Pending</Badge>
<span className="text-red-600">Error message</span>
<div className="bg-blue-500/10 text-blue-700">Info</div>

​

After (DO THIS)

// ✅ Using semantic tokens and Badge variants
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<span className="text-destructive">Error message</span>
<div className="bg-info/10 text-info">Info</div>

​

Status Configuration Pattern

// ✅ Use variant mappings instead of className mappings
const statusVariants: Record<Status, BadgeVariant> = {
  active: 'success',
  pending: 'warning',
  error: 'destructive',
  draft: 'secondary',
};

// Usage
<Badge variant={statusVariants[status]}>{status}</Badge>

​

Icon Colors

// ❌ Wrong
<CheckCircle className="h-4 w-4 text-green-600" />
<AlertTriangle className="h-4 w-4 text-yellow-600" />
<XCircle className="h-4 w-4 text-red-600" />

// ✅ Correct
<CheckCircle className="h-4 w-4 text-success" />
<AlertTriangle className="h-4 w-4 text-warning" />
<XCircle className="h-4 w-4 text-destructive" />

​

Alert/Notification Styling

// ❌ Wrong
<Alert className="border-green-200 bg-green-50">
  <CheckCircle className="h-4 w-4 text-green-600" />
</Alert>

// ✅ Correct
<Alert className="border-success/20 bg-success/10">
  <CheckCircle className="h-4 w-4 text-success" />
</Alert>

​

Progress/Score Indicators

// ✅ Semantic color based on value
const getScoreColor = (score: number) => {
  if (score >= 80) return 'text-success';
  if (score >= 50) return 'text-warning';
  return 'text-destructive';
};

// ✅ Progress bar backgrounds
const getProgressBg = (percent: number) => {
  if (percent >= 75) return 'bg-success';
  if (percent >= 50) return 'bg-primary';
  if (percent >= 25) return 'bg-warning';
  return 'bg-destructive';
};

​

Dark Mode Considerations

• text-success → Works in both light and dark mode
• bg-success/10 → Proper opacity in both modes
• border-success/20 → Consistent borders

// ❌ Don't do this
className="bg-green-100 dark:bg-green-900/30 text-green-800 dark:text-green-400"

// ✅ Do this instead
className="bg-success/10 text-success"

​

Common Patterns Reference

​

Chart Colors

• CSS variables: --chart-1 through --chart-8 are defined in src/index.css (light and dark).
• Tailwind: chart.1 … chart.8 are mapped in src/index.css via Tailwind v4 @theme inline; use text-chart-1, bg-chart-2, etc. for UI elements that reference chart colors (e.g. legend labels).
• In chart config: Use hsl(var(--chart-1)), … hsl(var(--chart-8)) for strokes/fills, or pass a ChartContainer config with theme: { light: 'hsl(var(--chart-n))', dark: '...' } so series colors are theme-aware.
• Do not use arbitrary hex or raw HSL in chart configs; use the design tokens above so charts adapt to dark mode.

​

Audit Checklist

• No direct Tailwind colors (green-*, red-*, yellow-*, etc.)
• All status indicators use Badge variants
• Icon colors use semantic tokens
• Alert/notification backgrounds use semantic tokens
• Progress indicators use semantic colors
• Light/dark mode both work correctly

​

Domain-Specific Status Mappings

​

Document Statuses

​

Credential Statuses

​

Workflow Statuses

​

Form Statuses

​

Real-World Usage Examples

​

Employee Status Card

// ✅ CORRECT: Using semantic tokens
function EmployeeStatusCard({ status }: { status: string }) {
  const statusConfig = {
    active: { variant: 'success' as const, icon: CheckCircle, label: 'Active' },
    pending: { variant: 'warning' as const, icon: Clock, label: 'Pending' },
    inactive: { variant: 'muted' as const, icon: UserX, label: 'Inactive' },
    terminated: { variant: 'destructive' as const, icon: XCircle, label: 'Terminated' },
  };

  const config = statusConfig[status] || statusConfig.inactive;
  const Icon = config.icon;

  return (
    <Card className="border-success/20 bg-success/5">
      <CardContent className="flex items-center gap-3 p-4">
        <Icon className="h-5 w-5 text-success" />
        <span className="font-medium">{config.label}</span>
      </CardContent>
    </Card>
  );
}

​

Form Validation Messages

// ✅ CORRECT: Semantic colors for validation
function FormField({ error, warning }: { error?: string; warning?: string }) {
  return (
    <div>
      <Input />
      {error && (
        <p className="text-sm text-destructive mt-1 flex items-center gap-1">
          <AlertCircle size={14} />
          {error}
        </p>
      )}
      {warning && (
        <p className="text-sm text-warning mt-1 flex items-center gap-1">
          <AlertTriangle size={14} />
          {warning}
        </p>
      )}
    </div>
  );
}

​

Dashboard Metrics

// ✅ CORRECT: Semantic colors for trends
function MetricCard({ value, trend }: { value: number; trend: 'up' | 'down' | 'neutral' }) {
  const trendConfig = {
    up: { color: 'text-success', icon: TrendingUp },
    down: { color: 'text-destructive', icon: TrendingDown },
    neutral: { color: 'text-muted-foreground', icon: Minus },
  };

  const config = trendConfig[trend];
  const Icon = config.icon;

  return (
    <Card>
      <CardContent className="p-4">
        <div className="flex items-center justify-between">
          <span className="text-2xl font-bold">{value}</span>
          <Icon className={`h-5 w-5 ${config.color}`} />
        </div>
      </CardContent>
    </Card>
  );
}

​

Alert Notifications

// ✅ CORRECT: Semantic alert styling
function AlertNotification({ type, message }: { type: 'success' | 'warning' | 'error'; message: string }) {
  const config = {
    success: { bg: 'bg-success/10', border: 'border-success/20', icon: CheckCircle, text: 'text-success' },
    warning: { bg: 'bg-warning/10', border: 'border-warning/20', icon: AlertTriangle, text: 'text-warning' },
    error: { bg: 'bg-destructive/10', border: 'border-destructive/20', icon: XCircle, text: 'text-destructive' },
  };

  const { bg, border, icon: Icon, text } = config[type];

  return (
    <Alert className={`${bg} ${border}`}>
      <Icon className={`h-4 w-4 ${text}`} />
      <AlertDescription className={text}>{message}</AlertDescription>
    </Alert>
  );
}

​

Table Row Status

// ✅ CORRECT: Status indicators in tables
function StatusCell({ status }: { status: string }) {
  const statusMap: Record<string, { variant: BadgeVariant; label: string }> = {
    approved: { variant: 'success', label: 'Approved' },
    pending: { variant: 'warning', label: 'Pending' },
    rejected: { variant: 'destructive', label: 'Rejected' },
    draft: { variant: 'secondary', label: 'Draft' },
  };

  const config = statusMap[status] || statusMap.draft;

  return <Badge variant={config.variant}>{config.label}</Badge>;
}

​

Token Catalog Reference

​

Surfaces & roles (chrome)

​

Brand & action

​

Status

Regression note: Prior to 2026-04-18, semanticColorClasses.info.full paired bg-info with text-primary-foreground. In dark mode --info flips to a light blue and --primary-foreground is also light → light-on-light, WCAG AA fail. Now uses text-info-foreground. Cover with the Vitest in tests/unit/shared/lib/semantic-colors.test.ts.

​

Special & utility

​

Density, Elevation & Encore v2

​

Sidebar slot

​

Encore brand (reserved)

​

Module Identity Tokens

​

Active short codes

​

Reserved (do not use yet)

​

Deprecated legacy aliases

​

Recommended usage

• Sidebar / nav row accent: 4px left border using border-l-4 border-module-{id} for the active module. Reinforces a “color = module” mental model across the 12-core ERP.
• Dashboard widget header underline: border-b border-module-{id} so each module’s hub feels visually anchored.
• Module badges: bg-module-{id}-subtle text-module-{id} for tags that identify which module owns an entity (e.g. cross-cutting reports list).
• Do NOT use module colors for status/state — use semantic status tokens (success, warning, destructive, info) for that.

​

Chart Palette

​

Tokens

​

Mandatory rules

• Always use hsl(var(--chart-N)) in chart configs (Recharts stroke / fill, SVG <rect fill={...}>, etc.). Never hardcode hex literals or raw HSL strings — they break dark mode and tenant rebrand.
• Use Tailwind utilities (text-chart-1, bg-chart-2, …) for legend swatches, KPI tile accents, etc.
• Cap series at 8 categories before introducing a “(other)” bucket. Beyond 8, sequential blending or repetition produces unreadable charts.
• Pair with ChartContainer from shadcn-charts (src/shared/ui/chart.tsx) when possible; pass theme: { light: 'hsl(var(--chart-N))', dark: '...' } so series colors remain theme-aware.

​

Colorblind safety

​

Known problem pairs

​

Action items (deferred to future palette-revision spec)

• Replace one of chart-2 / chart-6 to break the tritanopia teal/emerald collapse (e.g. swap chart-6 to a yellow-green or olive).
• Replace one of chart-4 / chart-7 to break the amber/orange collapse (e.g. swap chart-7 to a brown or burgundy).
• Replace one of chart-1 / chart-3 to break the sky/violet collapse (e.g. swap chart-3 to a magenta with more red than blue).
• Re-run npm run audit:chart-palette-colorblind --strict after each swap; goal is 0 fail pairs before wiring strict mode into validate:governance.

​

Tenant Theming (PF-95) Mapping Table

​

Gaps (not tenant-customizable today)

​

What tenants always get for free

• Tenant primary / accent are mode-aware: the --tenant-* override applies to both light and dark mode at :root; the platform handles dark-mode adaptation downstream.
• Contrast validation: validateThemeContrast (in src/platform/theming/utils/contrast.ts) enforces WCAG 2.1 AA on text-on-background pairs and 3:1 large-text on accent/destructive at save time.
• Single active theme per org is enforced by partial unique index + DB trigger.

​

Compliance Theming (PF-91-EN-01) Mapping

• Frontend: useComplianceTheme() (src/platform/compliance/) reads the active tenant theme and injects --tenant-* CSS custom properties on the compliance page container. useComplianceContrastValidator flags any tenant color that fails WCAG AA on the regulatory dashboard and shows a <ContrastFallbackIndicator> to admins.
• Immutable text: Apply the compliance-text-immutable class (src/platform/compliance/compliance-immutable.css) to regulatory or legal text that must never re-skin to a tenant brand. The class forces platform-default colors via !important.
• Edge function: _shared/compliance-contrast.ts (Deno) exports PLATFORM_DEFAULTS (HEX) which mirrors DEFAULT_THEME_COLORS (HEX) in src/platform/theming/types.ts. The generate-compliance-evidence edge function uses these for evidence-package metadata (branded: true/false, contrast_validated).
• Parity: All three sources (src/index.css, DEFAULT_THEME_COLORS, PLATFORM_DEFAULTS) MUST resolve to the same semantic palette. The npm run audit:token-parity script (Phase 4 of the color-system review) will enforce this contract.

​

Audit Checklist (extended)

• No raw hex in chart configs — use hsl(var(--chart-N))
• New chart with categorical color encoding pairs each color with a label, shape, or pattern (per the colorblind audit findings above)
• Module colors use short-code tokens (--module-cl), not legacy aliases (--module-clinical)
• Tenant-customizable surfaces use semantic tokens — not encore brand or hex literals — so PF-95 overrides take effect
• If you introduce a new --tenant-* consumer, add it to the PF-95 Mapping Table above
• If you change any --chart-N value, re-run npm run audit:chart-palette-colorblind and update the Known problem pairs table
• If you add a new shadcn-canonical token, register it in REQUIRED_TOKENS in scripts/audit/verify-shadcn-tokens.mjs AND define it under both :root and .dark in src/index.css. Run npm run audit:shadcn-tokens to confirm.

​

Token Coverage Gate

• Surface + foreground pairs: background/foreground, card/card-foreground, popover/popover-foreground, primary/primary-foreground, secondary/secondary-foreground, muted/muted-foreground, accent/accent-foreground, destructive/destructive-foreground
• Singles: border, input, ring
• Chart palette: chart-1 … chart-5
• Sidebar: sidebar-background, sidebar-foreground, sidebar-primary, sidebar-primary-foreground, sidebar-accent, sidebar-accent-foreground, sidebar-border, sidebar-ring
• Radius: radius

​

Related Documentation

• constitution.md §6.7 - UI/UX Guardrails
• docs/development/UI_UX_STANDARDS.md - Full UI/UX Standards
• docs/development/DESIGN_TOKEN_SYNC_POLICY.md - Token governance, parity contract, deprecated/reserved tokens
• src/index.css - Canonical token definitions (:root, .dark, @theme inline)
• src/shared/lib/semantic-colors.ts - Utility functions
• src/shared/ui/badge.tsx - Badge component with variants
• src/platform/theming/ - PF-95 tenant theming (types, hooks, components)
• src/platform/compliance/ - PF-91-EN-01 white-label compliance dashboards
• tests/unit/shared/lib/semantic-colors.test.ts - Regression tests for semantic class set