Module guard 

Case 1 — contrast guard for text-on-surface pairings.

The client’s requested text color is treated as a suggestion. When it fails AA against the surface, the engine substitutes a guaranteed-readable text color rather than emit unreadable HTML. The rejected color is never destroyed — callers may still place it on a border or divider.

Functions

readable_text

Pick whichever of the two default text colors reads best on surface. Used both as the fallback inside resolve_text_token and as a direct utility for “I just need text that works”.

resolve_text_token

If requested clears AA on surface, return it. Otherwise log a warning and substitute readable_text.