Consider magic numbers for color tokens

[jonathantneal]

I suggest we provide a grading system to colors, based on relative luminance, in order to significantly improve the likelihood of sufficient and consistent contrast experiences when building with Astro.

Choosing colors, like naming things, can be stressful. Choosing accessible colors? Even more stressful. This is one of the reasons why insufficient text contrast is the most common accessibility issue, affecting 86% of the top one million websites.

The Astro color palettes already divide themselves into numeric grades, demonstrating that numeric grades are an easily digestible format. Providing this higher level of consistency in such a terse and familiar format would provide users a distinct and measurable advantage.

The USWDS has adopted this strategy, and refers to their grading as ‘magic numbers’.

We call the difference in grade between any two colors the magic number. Magic numbers have the following contrast implications:

• A magic number of 40+ results in WCAG 2.0 AA Large Text contrast (example: gray-90 and indigo-warm-50v).
• A magic number of 50+ results in WCAG 2.0 AA contrast or AAA Large Text contrast (example: gray-90 and red-40).
• A magic number of 70+ results in WCAG 2.0 AAA contrast (example: gray-10 and red-80).
• Colors of grade 50 result in Section 508 AA contrast against both pure white (grade 0) and pure black (grade 100).

Magic numbers work because each grade conforms to a specific range of values for relative luminance.

What It Might Look Like

Color	Grade	Variable	Contrast Ratio
DarkBlue	100	--color-palette-darkblue-100	0
DarkBlue	200	--color-palette-darkblue-200	2.2
DarkBlue	300	--color-palette-darkblue-300	2.5
DarkBlue	400	--color-palette-darkblue-400	3
---

Prior Art

This technique has been successfully adopted by IBM, USWDS, and Tailwind.

Additional References

• Designing an accessible color palette with magic numbers
• Open Colors Milestone 2
• Radix UI Palette Composition

[dmcalester]

Would this be a topic that might expand to the larger astro repo for (somewhat) more visibility?

[markacianfrani]

Absolutely but this is a great place to get it out of the ether for now.

This is a 10/10 non negotiable feature we need IMO.

For next steps I imagined we'd draft up a proposal for what the goals are and the problem it solves. Thoughts?

Keep in mind this is a very developer-focused way of thinking about the problem and we may need to distill some of it down into a more accessible language.

[dmcalester]

Goals and problems is perfect.

Is there a value to a small use-case test to demonstrate the benefit of this system? I think the current caution color and our backgrounds are causing us to resort to … not exactly hacks, but sub-optimal decisions to fit within the rigidity of the status colors