#609 a11y: fix Welcome/Home dashboard contrast for WCAG AA (#565)

User description

Status: root cause found and fixed, evidence attached

Fixes #565.

Root cause

index.css's @media (prefers-reduced-motion: reduce) override for .aurora-blob (continuous 25s background float) and .animate-in (the Dashboard's staggered card fade-in) was declared before those classes' own unconditional base rules. With equal selector specificity and no cascade layers in this file, CSS resolves ties by source order — so the later, unconditional base rules always won. Reduced motion never actually froze either animation, for any user, including those who explicitly requested it.

This matches the original issue's own observation that "the exact failing nodes vary between retries": axe was sampling a page whose background was still perpetually animating (Aurora) and whose Dashboard cards were still mid-fade, producing different composited colors on every scan. It also explains why the flat semantic-token pairs in index.css were already correctly verified AA-compliant on their own — the defect was never in a static color value.

Fix

• Reordered the @media (prefers-reduced-motion: reduce) block to after both base rules, so it actually wins the cascade as originally intended.
• Added a deterministic Light+Sepia and Dark+Sepia Dashboard axe test (the exact combination from the historical report), plus a normal-motion, fully-settled-state test, so this can't silently regress again.
• Folded in a separate, authorized product change: default appearancePreset switched from sepia to default for new sessions (explicit Sepia selections are preserved), with matching persisted-settings migration and updated unit tests.

Evidence

• Before the fix: CI's Light+Sepia and Dark+Sepia Dashboard axe scans failed with color-contrast violations whose fgColor/bgColor/contrastRatio swung significantly between retries of the identical, static (zero-value) project state — e.g. the "Worlds" stat label measured 2.38:1 in one run and 1.71:1 in another for the same DOM node.
• After the fix: the same tests, plus a new normal-motion settled-state scan, pass deterministically on exact-head CI (bf03c783), alongside a full green run (CI Success, CodeQL, Browser Quality/VRT+Lighthouse).
• The first commit on this branch is unrelated housekeeping (CLAUDE.md doctor-trim, folded in per instruction).

Summary by Sourcery

Stabilize dashboard accessibility behavior and standardize the default appearance preset.

Bug Fixes:

• Ensure reduced-motion preferences reliably freeze Aurora and dashboard entrance animations, preventing transient visual states from causing accessibility contrast violations.

Enhancements:

• Make the standard appearance preset the default for new sessions and migrate invalid or removed legacy presets while preserving explicit Sepia selections.
• Improve dashboard accessibility coverage across light and dark Sepia themes and after normal-motion animations settle.

Documentation:

• Update design-system guidance to document the supported Default and Sepia appearance presets.

Tests:

• Update settings migration tests for the new default and add deterministic accessibility checks for loaded dashboards across appearance, theme, and motion states.

Chores:

• Simplify the repository directory map in CLAUDE.md.

Summary by cubic

Makes reduced motion actually freeze the Aurora background and dashboard card animations so the Welcome/Home dashboard renders statically, resolving the flaky contrast violations from #565. Also switches the default appearance preset from Sepia to standard default for new sessions.

Behavior changes

• The prefers-reduced-motion override now wins the cascade, so .aurora-blob and .animate-in stop animating when reduced motion is requested.
• New sessions start on default; legacy invalid stored values migrate to default, and explicit sepia is preserved.
• A11y tests explicitly select Writer's Sepia in light and dark schemes, wait for the lazy-loaded Dashboard to mount before scanning, and verify the fully-settled normal-motion state passes axe after fade-ins complete.

Migration

• VRT writer.png baseline was regenerated from the CI-captured render; the home/characters/settings baselines passed unchanged.

Summary by CodeRabbit

• Appearance

  • The application now uses the Default appearance preset for new and previously unset settings.
  • Existing Writer’s Sepia selections remain supported and can be chosen explicitly.
  • Invalid or unrecognized saved appearance values now fall back to the Default preset.
  • Fantasy and romance appearance options are no longer documented as supported themes.

• Accessibility

  • Improved light and dark Writer’s Sepia coverage across settings and dashboard views.
  • Reduced-motion preferences now suppress Aurora animation while keeping content visible.

CodeAnt-AI Description

Use the standard appearance by default and verify dashboard accessibility across themes

What Changed

• New sessions and invalid or removed saved presets now use the standard appearance instead of Writer’s Sepia, while explicit Sepia selections remain unchanged
• Accessibility checks now cover both light and dark Sepia dashboards after the dashboard content has fully loaded
• Reduced-motion preferences now reliably stop decorative and entrance animations
• Design-system documentation now lists only the supported appearance presets
• Repository guidance and settings tests were updated to reflect the new default and preset migration behavior

Impact

✅ Standard appearance for new sessions
✅ Reliable reduced-motion behavior
✅ Verified light and dark Sepia dashboards

@codeant-ai ask: Your question here

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

@codeant-ai: Your feedback here

@codeant-ai: Do not flag unused imports.

@codeant-ai: review