@forgehealth/lumen-ui

Visual Governance for Healthcare AI

Drop-in React components that make every AI decision visible, auditable, and defensible — without your team designing governance UI from scratch.

@forgehealth/lumen-ui is the official component library for the LUMEN SDK. It transforms raw governance scores into production-ready UI — inline badges, detail panels, and printable assurance certificates.

Why This Exists

Every AI-powered healthcare application needs to answer: "Why did the system make that decision?"

Most teams building clinical AI tools spend weeks designing governance displays — score visualizations, audit panels, compliance certificates. These components solve that problem in one npm install:

• Clinicians see a clear, non-intrusive score next to every AI recommendation
• Compliance officers get printable, signed assurance certificates
• IT teams get an expandable audit panel with full evaluation breakdown
• Executives get a visual they can understand without technical explanation

Installation

npm install @forgehealth/lumen-ui

Peer dependencies: React 18+ and React DOM 18+.

Quick Start

1. Import styles (once, in your app's entry point):

import '@forgehealth/lumen-ui/styles.css';

2. Use the components:

import { LumenBadge, LumenPanel, LumenCertificate } from '@forgehealth/lumen-ui';

// Inline badge next to any AI output
<LumenBadge score={78} verdict="ALLOW" />

// Expandable detail panel
<LumenPanel result={evaluationResult} />

// Printable assurance certificate
<LumenCertificate result={evaluationResult} />

That's it. Three components. Full governance visualization.

Components

<LumenBadge />

An inline score pill that sits next to AI-generated content. Non-intrusive, instantly recognizable.

<LumenBadge
  score={78}
  verdict="ALLOW"
  tier="T2"
  size="md"
/>

Visual states:

| Verdict | Display | Use Case | |---------|---------|----------| | ALLOW | 🟢 LUMEN 78 | Decision passed governance checks | | REVIEW | 🟡 LUMEN 52 | Decision needs human review | | DENY | 🔴 LUMEN 23 | Decision blocked by policy |

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | score | number | required | LUMEN Score (0–100) | | verdict | 'ALLOW' \| 'REVIEW' \| 'DENY' | required | Governance verdict | | tier | string | — | Risk tier label | | size | 'sm' \| 'md' \| 'lg' | 'md' | Badge size | | showScore | boolean | true | Show numeric score | | onClick | () => void | — | Click handler (adds button role + keyboard support) |

Where to place it: Directly after any AI-generated recommendation, summary, or decision in your UI. The badge answers the immediate question: "Is this output trustworthy?"

<LumenPanel />

An expandable detail panel showing the full evaluation breakdown. Use as a sidebar, inline accordion, or modal.

<LumenPanel
  result={evaluationResult}
  expanded={false}
  onToggle={() => setExpanded(!expanded)}
  theme="light"
/>

Sections displayed:

| Section | What It Shows | |---------|---------------| | Header | Score, verdict, tier — clickable to expand/collapse | | Risk Radar | 7-domain assessment: legal, labour, safety, ethics, cyber, finance, reputation | | Policy Checks | Pass/fail list with severity indicators (CRITICAL → LOW) | | Factor Breakdown | Progress bars showing each scoring factor's contribution | | Audit Trail | Record ID, timestamp, hash — the defensible receipt | | Certificate Preview | Framework badges and non-negotiable verification |

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | result | LumenEvaluationResult | required | Full evaluation result from LUMEN SDK | | expanded | boolean | false | Control expanded/collapsed state | | onToggle | () => void | — | Called when header is clicked | | theme | 'light' \| 'dark' | 'light' | Color theme |

Where to place it: As a sidebar panel in clinical decision support tools, an expandable section below AI-generated content, or a modal triggered by clicking the LumenBadge.

<LumenCertificate />

A formal assurance certificate — printable, exportable. The compliance receipt that answers: "Prove this decision was governed."

<LumenCertificate
  result={evaluationResult}
  showQR={true}
  compact={false}
  onExport={() => window.print()}
/>

Certificate includes:

• Fingerprint — Unique cryptographic identifier
• LUMEN Score — Governance confidence rating
• Verdict & Tier — Decision classification
• Frameworks Evaluated — PHIPA, HIPAA, NIST AI RMF (as jurisdiction badges)
• Non-Negotiables — Verified compliance checklist with ✓/✗
• Timestamp — When the evaluation was signed
• QR Code — Placeholder for audit record verification link

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | result | LumenEvaluationResult | required | Full evaluation result | | showQR | boolean | true | Show QR code placeholder | | compact | boolean | false | Compact single-column layout | | onExport | () => void | — | Export/print button callback |

Where to place it: In audit reports, compliance dashboards, or as a printable page accessible from the detail panel. Includes print-optimized CSS (@media print).

Integration Patterns

Pattern 1: Inline Badge (Most Common)

Place the badge directly in your AI output stream:

function AIRecommendation({ recommendation, governance }) {
  return (
    <div className="p-4 border rounded">
      <p>{recommendation.text}</p>
      <div className="mt-2 flex items-center gap-2">
        <LumenBadge
          score={governance.lumenScore}
          verdict={governance.verdict}
        />
        <span className="text-sm text-gray-500">
          Governance verified
        </span>
      </div>
    </div>
  );
}

Pattern 2: Badge + Expandable Panel

Click the badge to reveal the full evaluation:

function GovernedOutput({ result }) {
  const [showPanel, setShowPanel] = useState(false);

  return (
    <div>
      <LumenBadge
        score={result.lumenScore}
        verdict={result.verdict}
        onClick={() => setShowPanel(!showPanel)}
      />
      {showPanel && (
        <LumenPanel
          result={result}
          expanded={true}
          theme="light"
        />
      )}
    </div>
  );
}

Pattern 3: Executive Dashboard

Aggregate scores across multiple evaluations:

function GovernanceDashboard({ evaluations }) {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
      {evaluations.map(evaluation => (
        <LumenPanel
          key={evaluation.recordId}
          result={evaluation}
          expanded={false}
          onToggle={() => togglePanel(evaluation.recordId)}
        />
      ))}
    </div>
  );
}

Pattern 4: Compliance Audit Export

Generate printable certificates for a compliance review:

function AuditReport({ evaluations }) {
  return (
    <div className="print:break-after-page">
      {evaluations.map(evaluation => (
        <LumenCertificate
          key={evaluation.recordId}
          result={evaluation}
          showQR={true}
          onExport={() => window.print()}
        />
      ))}
    </div>
  );
}

Type Definitions

The library exports full TypeScript definitions. The primary interface mirrors the LUMEN SDK evaluation output:

import type { LumenEvaluationResult } from '@forgehealth/lumen-ui';

interface LumenEvaluationResult {
  recordId: string;              // Unique decision record ID
  lumenScore: number;            // Governance score (0–100)
  tier: number | string;         // Risk tier classification
  verdict: 'ALLOW' | 'REVIEW' | 'DENY';
  citationIntegrity?: number;    // Citation verification score
  passed: boolean;               // Whether evaluation passed
  reasons: string[];             // Human-readable reasons

  riskRadar?: {                  // 7-domain risk assessment
    legal?: 'Green' | 'Amber' | 'Red';
    labour?: 'Green' | 'Amber' | 'Red';
    safety?: 'Green' | 'Amber' | 'Red';
    ethics?: 'Green' | 'Amber' | 'Red';
    cyber?: 'Green' | 'Amber' | 'Red';
    finance?: 'Green' | 'Amber' | 'Red';
    reputation?: 'Green' | 'Amber' | 'Red';
  };

  policyChecks?: Array<{        // Individual policy check results
    checkId: string;
    name: string;
    status: 'PASSED' | 'FAILED' | 'SKIPPED';
    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  }>;

  factorBreakdown?: Array<{     // Scoring factor contributions
    factorName: string;
    score: number;
    weight: number;
    contribution: number;
  }>;

  assuranceCertificate?: {      // Signed assurance certificate
    fingerprint: string;
    signedAt: string;
    frameworks: string[];
    nonNegotiables: Array<{ rule: string; verified: boolean }>;
  };
}

Theming

Dark Mode

Components support dark mode via Tailwind's dark: class strategy:

<div className="dark">
  <LumenPanel result={result} theme="dark" />
</div>

Custom Styling

Components use Tailwind utility classes. Override styles by wrapping in your own container or using Tailwind's @apply directive in your CSS.

Accessibility

All components are built with accessibility as a requirement:

• ARIA labels on all interactive elements
• Keyboard navigation — Tab, Enter, Space support
• Semantic HTML — proper headings, lists, and landmark roles
• Screen reader support — score and verdict announced clearly
• Focus indicators — visible focus rings on interactive elements
• Color + icon — verdicts use both color and emoji (not color alone)

Browser Support

| Browser | Version | |---------|---------| | Chrome | 90+ | | Firefox | 88+ | | Safari | 14+ | | Edge | 90+ |

Package Details

| Property | Value | |----------|-------| | Package | @forgehealth/lumen-ui | | Version | 1.0.0 | | Bundle (CJS) | 17 KB | | Bundle (ESM) | 15 KB | | CSS | 18 KB | | Types | Full TypeScript definitions | | Tree-shakeable | Yes | | Peer deps | React 18+, React DOM 18+ | | License | Apache-2.0 |

Related Packages

| Package | Description | |---------|-------------| | @forgehealth/lumen-sdk | Core governance scoring engine | | @forgehealth/lumen-ui | Visual components (this package) |

Contributing

See CONTRIBUTING.md for guidelines.

Security

Report vulnerabilities to [email protected]. See SECURITY.md for details.

License

Apache-2.0 — See LICENSE

Copyright 2026 Forge Partners Inc.

Built by Forge Health — AI Governance for Healthcare

Documentation · LUMEN SDK · Contact