Color Contrast Validator

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/color-contrast-validator/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core-free inline validator that warns the merchant when they choose a foreground/background color pair with insufficient contrast (WCAG AA minimum 4.5:1 for text). Runs in the theme editor and content editor; no enforcement, only warning.

The problem

Merchants use hard-to-read color combinations (e.g., light yellow text on white background). Users with low vision cannot see the site. No immediate feedback when colors are set; merchant discovers the problem only when users complain or an accessibility audit fails.

What it does

• Color contrast ratio calculator (WCAG algorithm: relative luminance per sRGB)
• Real-time validation in theme editor when merchant sets foreground/background colors; displays measured ratio and passes/fails AA (4.5:1) and AAA (7:1) thresholds
• Warning in post/page editor when merchant writes text in a color that does not meet AA contrast against the page background
• Optional global palette mode: pre-approved color pairs (core + theme choose colors that pass)
• Contrast calculator UI/tooltip showing ‘This combination is AA-compliant’ or ‘Insufficient contrast; try [suggested darker/lighter shade]’

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• No automatic color correction — the merchant must choose the new color (reason: color is a design choice, not a bug to fix)
• No color-blindness simulation — the validator checks luminance only (reason: full simulation requires per-user profiles; luminance is the regulatory requirement)
• No image background contrast — images have unknown colors; merchant must test with real screenshots (reason: text-on-photo contrast is not algorithmically solvable)

Data model

None. Settings gain optional theme_palette_mode (boolean) to lock theme to pre-approved colors.

API

• POST /api/color-contrast/calculate { fg, bg } → { ratio, aa: boolean, aaa: boolean, suggestions: [color, …] }

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Theme editor color pickers show a small contrast indicator (pass/fail badge) next to the color value. Post editor shows a warning inline if the merchant assigns a color to text that fails AA. Settings → Color Accessibility: toggle palette mode (if enabled, theme editor only offers pre-approved colors).

The seam — why this is core

Core owns the contrast algorithm and validation. Theme owns the palette (may be locked to core-approved if palette mode is on). Content owner chooses text colors and sees the warning.

Core owns the interface + honest contrast checker; accessibility is infrastructure, not a support commitment or credential.

Dependencies

• Theme editor (core)
• Post editor (core)
• Color picker component (external, e.g. chroma.js)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Color picker for theme background + foreground shows badge ‘AA-compliant (6.8:1)’ or ‘Fails AA (2.1:1)’
• Setting foreground to #FFD700 (gold) and background to #FFFACD (light yellow) shows warning ‘Insufficient contrast: 1.8:1. Try #CCAA00 (suggested darker gold)’
• A post with text color: #FFFF00 (yellow) on a white background shows editor warning ‘Yellow text fails AA contrast on white background’
• The contrast calculation returns correct ratio (within 0.01) for sample color pairs (black/white, gold/yellow, etc.)
• Palette mode enabled: theme editor’s color picker shows only 12 pre-approved colors

Risks

Color picker must not block if the contrast API is slow; use browser-side calculation (chroma.js). Merchant ignores the warning and ships inaccessible site anyway; the validator is advisory only. Contrast calculation must be exact; use official WCAG luminance formula, not approximations.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.