dark-mode-legibility

Dark Mode Legibility

Dark mode isn't a polish-pass nice-to-have — it's a correctness concern. The most common dark-mode bugs:

• Are invisible in light mode (you'll never spot them eyeballing the simulator with default appearance)
• Only show on specific tint colors (often pale pastels, especially cream / yellow / pale orange)
• Slip through code review because the code looks identical to the light-mode case that works

This skill is a checklist for catching them.

When to Use

• Every iteration that touches colors, tints, glass surfaces, or button styles
• Once during the polish phase as a deliberate full-app pass
• After any user reports "this looks wrong" — first question: was it light or dark mode?

The First Rule

Test every screen in BOTH modes every iteration. Toggle dark mode in the simulator (Shift + Cmd + A) before claiming any UI fix is done.

If your verification loop only checks one mode, half your screens are unverified.

The Vibrancy-on-Pale-Tint Pitfall

This one is responsible for more "the Continue button is unreadable in dark mode" bugs than any other cause.

The failure mode:

1. You apply .glassProminent button style with .tint(SomePaleColor) — e.g. cream, pale yellow, pale orange
2. In light mode, the system's vibrancy treatment picks a darker contrast color for the label — looks great
3. In dark mode, the system's vibrancy picks a tinted-white — which against a cream / yellow / pale-orange pill is illegible

The fix is NOT to force .foregroundStyle(.white) everywhere — that kills vibrancy and produces flat painted-on glyphs (see the polish-and-refinement skill's glass-button rules). The fix is to override the foreground in dark mode only:

Group {
    if systemColorScheme == .dark {
        Text("Continue")
            .foregroundStyle(Color.black)
    } else {
        Text("Continue")
        // light mode: no override, system vibrancy handles it
    }
}
.font(.headline)
.frame(maxWidth: .infinity)