npm package: @forgehealth/lumen-ui
Description: React component library for visualizing LUMEN SDK governance scores
Author: Forge Partners Inc.
Latest version: 1.0.0

# @forgehealth/lumen-ui

**Visual Governance for Healthcare AI**

[![npm version](https://badge.fury.io/js/%40forgehealth%2Flumen-ui.svg)](https://www.npmjs.com/package/@forgehealth/lumen-ui)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

> 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](https://github.com/forge-health-ai/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

```bash
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):

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

**2. Use the components:**

```tsx
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.

```tsx
<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.

```tsx
<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."*

```tsx
<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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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:

```typescript
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:

```tsx
<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`](https://github.com/forge-health-ai/lumen-sdk) | Core governance scoring engine |
| `@forgehealth/lumen-ui` | Visual components (this package) |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

Report vulnerabilities to **security@forgehealth.ai**. See [SECURITY.md](SECURITY.md) for details.

## License

Apache-2.0 — See [LICENSE](LICENSE)

Copyright 2026 Forge Partners Inc.

---

**Built by [Forge Health](https://forgehealth.ai)** — AI Governance for Healthcare

[Documentation](https://github.com/forge-health-ai/lumen-ui#readme) · [LUMEN SDK](https://github.com/forge-health-ai/lumen-sdk) · [Contact](mailto:lumen-sdk@forgehealth.ai)