Back

WCAG Contrast Checker

WCAG contrast ratio checker built with semantic HTML5, vanilla CSS (native nesting, custom properties, fluid type) and ES modules. Calculates relative luminance per the W3C spec, returning AA and AAA compliance for normal and large text. Pair programmed with Claude as a deliberate, interview-ready, dependency-free front-end demonstration.

  • JavaScript
View on GitHub ↗

A web app for checking colour contrast ratios against WCAG accessibility
standards.

Understanding Colour Contrast and WCAG

Colour contrast is a measure of the difference in brightness between text (or
graphics) and their background. Poor contrast makes content difficult or
impossible for people with colour blindness, low vision, or visual impairments
to perceive. The Web Content Accessibility Guidelines (WCAG) establish minimum
contrast ratios to ensure digital content is accessible to all users.

WCAG defines three conformance levels:

  • AA — the minimum recommended standard for most web content (4.5:1 for
    text)
  • AAA — enhanced accessibility for specialised contexts (7:1 for text)

This tool calculates the contrast ratio between any two colours and shows you
whether they meet AA or AAA standards. It supports real-time ratio calculation,
theme switching, and works offline in your browser.

Quick Start

Installation

Install dependencies:

pnpm install

Running the Development Server

pnpm run dev

Open your browser to the local dev server URL (typically
http://localhost:5173). The app reloads automatically as you edit.

Using the App

  1. Enter colour values as hex codes (e.g. #FFFFFF)
  2. The contrast ratio updates in real time
  3. View the WCAG conformance levels (AA / AAA)
  4. Switch between theme modes: System, Light, Dark, and High Contrast
  5. Use the Swap button to reverse foreground and background colours

Features

  • Real-time contrast ratio calculation — See results instantly as you type
  • WCAG level grading — Check conformance against AA and AAA standards
  • Multiple theme modes — System (respects OS preference), Light, Dark, and
    High Contrast
  • Accessible UI — Built with semantic HTML and tested across themes
  • Offline — Runs entirely in the browser with no server required
  • Tested — Comprehensive unit and end-to-end test coverage

Development

Requirements

  • Node.js >= 18.x
  • pnpm >= 11.x (declared in package.json)

Available Commands

Build for production:

pnpm run build

Preview the production build locally:

pnpm run preview

Testing

This project includes unit tests (Vitest) and end-to-end tests (Playwright).

Run all tests:

pnpm test

Run unit tests only:

pnpm run test:unit

Run end-to-end tests:

pnpm run test:e2e

Run end-to-end tests in UI mode (interactive):

pnpm run test:e2e:ui

Unit tests validate contrast mathematics, WCAG grading logic, and colour
conversion. End-to-end tests validate the user interface behaviour, theme
switching, and real-time updates.

Project Status

This is a pre-release project at version 0.0.1. See
CHANGELOG.md for a detailed history of changes.

Contributing

For now, this is a personal project. Future contribution guidelines will be
documented here.