Visual accessibility

Color Contrast Validation

Check contrast in both themes so depth, blur, and color never cost readability.

WCAG targets

WCAG 2.x contrast ratios. AA is the common release bar. AAA is a stricter goal.

WCAG contrast targets by content type
Content	AA	AAA
Body text	4.5:1	7:1
Large text (24px, or 19px bold)	3:1	4.5:1
UI components and focus rings	3:1	No AAA target

Token pairs

Ratios computed from the OKLCH values in the tokens package. The color explorer shows the same AA and AAA badges live for any color you pick.

Contrast ratios for core Glin UI token pairs
Pair	Theme	Ratio	AA 4.5	AAA 7
Foreground on background	Light	16.17:1	Passes AA	Passes AAA
Muted on background	Light	5.28:1	Passes AA	Fails Below AAA
Accent on background	Light	5.06:1	Passes AA	Fails Below AAA
Accent foreground on accent	Light	5.12:1	Passes AA	Fails Below AAA
Foreground on background	Dark	16.59:1	Passes AA	Passes AAA
Muted on background	Dark	5.82:1	Passes AA	Fails Below AAA
Accent on background	Dark	9.37:1	Passes AA	Passes AAA
Accent foreground on accent	Dark	9.37:1	Passes AA	Passes AAA

Contrast Checklist

Run this pass for every major visual update.

Body text meets WCAG AA (4.5:1) on every surface, including glass.
Muted labels stay readable in both light and dark themes.
Focus rings and selected states reach 3:1 against their neighbors.
Success, warning, and error states include text or an icon, not color alone.
Disabled controls are still legible enough to be understood.

Testing text on glass

A translucent surface has no single background color. Sample the busiest part of the backdrop behind the text and measure against that, in both themes.

<div className="rounded-xl border border-border/60 bg-[var(--glass-3-surface)] p-4">
  <p className="text-sm text-neutral-700 dark:text-neutral-200">
    Secondary copy keeps AA contrast on glass surfaces.
  </p>
  <a
    href="#"
    className="mt-2 inline-flex text-sm font-medium text-[var(--color-foreground)] underline underline-offset-4"
  >
    Read the full accessibility spec
  </a>
</div>

# Suggested release audit workflow
pnpm --filter @glinui/docs build


# Then validate key routes with browser accessibility tooling:
# - /docs/getting-started
# - /docs/components/radix/button
# - /docs/components/radix/table
# - /docs/forms-accessibility