> ## 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.

# Foreground Contrast Audit

> Developer tool that evaluates runtime WCAG AA contrast ratios for all semantic foreground/background token pairs and surfaces failing combinations.

Foreground Contrast Audit is a developer-only tool at `/dev/foreground-contrast-audit`. It walks every semantic foreground/background CSS variable token pair in the design system, computes the live contrast ratio from the current theme's CSS variables, and reports pairs that fall below WCAG AA thresholds (4.5:1 for normal text; 3:1 for large text or non-text UI components).

## Overview

The audit reads live CSS variable values from the rendered DOM and computes contrast ratios against WCAG AA standards. Token pairs are drawn from an internal catalog defined in the component. Failing pairs are highlighted with a recommended foreground adjustment (black or white) via the same contrast-picker utility the theming layer uses for tenant overrides (`pickAccessibleForegroundTriplet`).

A refresh action re-evaluates all pairs against the current theme state without a page reload.

## Who it's for

Requires permission `pf.wizards.admin`.

## Before you start

* This tool is intended for platform developers and accessibility reviewers.
* Run the audit after applying any tenant theme customization to confirm WCAG AA compliance.
* Ensure the page is rendered in the target theme (light/dark/tenant override) before triggering the audit.

## Steps

1. Navigate to `/dev/foreground-contrast-audit`.
2. The audit runs automatically on load and displays pass/fail status for each token pair.
3. Review failing rows. Each row shows the foreground token, background token, context description, computed ratio, and threshold.
4. Use the recommended fix displayed in the row as a guide for updating the tenant theme tokens.
5. Click **Refresh** to re-run the audit after making theme changes.

## Key concepts

**WCAG AA (normal text)** — requires a contrast ratio of at least 4.5:1 (constant `WCAG_AA_NORMAL`).

**WCAG AA (large text / non-text)** — requires a contrast ratio of at least 3:1 (constant `WCAG_AA_LARGE`). Token pairs flagged `large: true` use this relaxed threshold.

**Semantic color tokens** — CSS custom properties (e.g., `--foreground`, `--muted-foreground`) that must never be hard-coded to specific color values per the platform's styling rules.

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/dev/pages/ForegroundContrastAuditPage.tsx
  * src/platform/theming/utils/contrast.ts
</Accordion>