AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Contrast Checker Agent Guide

Agent guide for WCAG luminance, contrast ratio, and AA or AAA pass flags.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Contrast Checker in the alexandrai-tools project.

Project overview

This guide covers src/tools/contrast-checker/index.ts. The tool parses hex colors into relative luminance, computes WCAG contrast ratio symmetrically, formats the ratio to two decimals, and reports AA and AAA flags for normal and large text thresholds.

Primary source files

  • src/tools/contrast-checker/index.ts defines meta, hexToLuminance, contrastRatio, ContrastResult, and checkContrast.
  • src/tools/contrast-checker/index.test.ts covers black, white, shorthand hex, invalid input, contrast symmetry, pass flags, and ratio display.
  • src/tools/contrast-checker/Body.astro owns the browser color inputs.
  • src/tools/contrast-checker/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Reject invalid hex before computing luminance.
  • Use the WCAG linearization formula for each RGB channel.
  • Keep contrastRatio order-independent by sorting lighter and darker luminance values.
  • Keep AA normal at 4.5, AA large at 3, AAA normal at 7, and AAA large at 4.5.
  • Return null when either input color is invalid.
  • Do not claim contrast success guarantees full accessibility.
  • When adding alpha or non-hex inputs, define compositing assumptions explicitly.

Testing

Test black-white ratio, same-color ratio, shorthand hex, invalid hex, symmetry, AA and AAA flags, values near thresholds, and alpha behavior if added.

PR checklist

  • npm test passes for contrast-checker.
  • Pure string or color logic stays independent from DOM preview code.
  • Generated CSS remains copy-ready.
  • Browser-local behavior is preserved.