mazipan / mazipan/html-tools

feat: add Color Contrast Checker tool

Open
#129 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
HTML
Stars
5
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Summary

Add a contrast-checker.html tool that checks foreground/background color pairs against WCAG 2.1 accessibility standards and suggests fixes when they fail.

Motivation

"WCAG contrast checker" and "color contrast checker" are high-volume accessibility searches. Every team doing accessibility audits needs this. It pairs naturally with the Color Picker tool (issue #122) — and unlike generic contrast checkers, this one can suggest the minimum lightness delta needed to reach a passing ratio, removing the guesswork.

Proposed UX

  • Two color pickers (foreground + background) using .color-btn from the design system; accepts HEX / RGB / HSL paste
  • Swap button to flip the pair
  • Live contrast ratio display: e.g. 4.72 : 1
  • WCAG 2.1 result badges:
    • Normal text AA (≥ 4.5 : 1) ✓ / ✗
    • Normal text AAA (≥ 7 : 1) ✓ / ✗
    • Large text AA (≥ 3 : 1) ✓ / ✗
    • Large text AAA (≥ 4.5 : 1) ✓ / ✗
    • UI components / graphical objects AA (≥ 3 : 1) ✓ / ✗
  • Live preview block: sample heading, body paragraph, and button rendered in the chosen colors so you see the actual visual result
  • Fix suggestion: if failing, show the adjusted foreground and background that each just barely reach AA (minimum luminance shift), as a copy-ready HEX pair
  • Optional: APCA (Advanced Perceptual Contrast Algorithm) score alongside WCAG

Implementation notes

  • Category: Ornaments (sits with Color Picker, Gradients)
  • Slug: contrast-checker
  • Icon: 🔲
  • No npm dependencies — relative luminance and contrast ratio formulas are pure math (WCAG spec §1.4.3), APCA algorithm is ~40 lines inline
  • All logic inline in <script>
  • Follow src/_tool-template.html and run bun run generate:sections, bun run generate:index, bun run generate:favicon after adding to tools.json

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/_tool-template.html and the existing Color Picker tool, then inspect tools.json and the generator commands named in the issue. Add contrast-checker with the specified color inputs, WCAG result badges, live preview, and fix suggestions, then run bun run generate:sections, bun run generate:index, and bun run generate:favicon to verify the generated project output.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, javascript
Domain
accessibility, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.