feat(a11y/ux): high-contrast overlay tokens, stale-data warning, staggered card entry (#313/#301/#300)

[Mawuli-tech]

This PR closes #313, #301, #300 — three adjacent UX/accessibility issues on the creator marketplace. Batched in one PR because they share consumers (the LandingPage + the CreatorCard) and the helpers reinforce each other.

closes #313
closes #301
closes #300

What's in this PR

#313 — High-contrast guardrail for overlay text

The volume24h pill on CreatorCard renders text over the image overlay; the existing bg-slate-950/75 + text-white/90 lose contrast under Windows High Contrast / (forced-colors: active).

• Added a scoped .creator-card-overlay-text class to that pill.
• In src/index.css, a @media (forced-colors: active) block pins the class to Canvas / CanvasText / ButtonBorder and drops the backdrop-filter. These are the system tokens browsers guarantee meet the active high-contrast theme's contrast ratio.
• Non-overlay text is untouched — the rule is scoped to the new class, and uses the existing token system (the forced-colors system tokens) rather than hardcoded colours.

#301 — Stale-creator-data detection + warning

• New helper src/utils/staleData.utils.ts — isStale(lastFetchedAt, thresholdMs) returns { stale, ageMs, msUntilStale }. Handles nullish input (always stale), clock skew (clamps to 0), non-positive thresholds (always stale).
• New formatStaleAge(ageMs) — "Just updated" / "Updated Ns ago" / "Updated N min/hr/days ago"; safe for Infinity and negative inputs.
• New hook src/hooks/useStaleData.ts — wraps the helper with periodic re-evaluation scheduled at the exact moment the threshold expires (no polling) and fires onStale exactly once per stale transition (fresh → stale → fresh resets the latch so the next stale transition fires again).
• New src/components/common/StaleDataWarning.tsx — subtle amber pill, role="status" aria-live="polite", returns null when not stale so callers can render it unconditionally.
• Wired into LandingPage with a 60-second threshold; onStale fires the existing handleRetryCreatorFetch to trigger a background refresh that resets the baseline (creatorsFetchedAt) and clears the warning automatically.

#300 — Staggered card-entry animation

• New src/utils/cardEntryAnimation.utils.ts — creatorCardEntryStyle(index, options) returns a style object with a --creator-card-entry-delay CSS variable. Defaults: stepMs = 40, maxDelayMs = 360 (so even with 100+ cards the last one isn't sluggish). Respects prefers-reduced-motion (and accepts an explicit override for tests). Exports the matching CREATOR_CARD_ENTRY_CLASS = 'creator-card-entry'.
• src/index.css defines the creator-card-entry keyframes (220ms ease-out, opacity 0→1 + 8px translateY) reading the delay variable. A @media (prefers-reduced-motion: reduce) rule disables the animation entirely.
• Pointer events stay enabled the whole animation — the card is interactive immediately.
• Wired into LandingPage's success-path creator grid; each CreatorCard is wrapped in a <div> carrying the class + style.

Tests

18 new vitest cases, all passing in the new files (pnpm test reports 145/146 — see Disclosures below for the one pre-existing failure):

• src/utils/__tests__/cardEntryAnimation.utils.test.ts (7): exported class name, 0ms first card, stagger between consecutive cards, maxDelayMs cap, prefers-reduced-motion short-circuit, explicit disabled, negative-index no-op.
• src/utils/__tests__/staleData.utils.test.ts (9): nullish = stale + infinite age, fresh within window, boundary, clock-skew clamp, non-positive threshold, default threshold, age formatter coverage, fallback for non-finite / negative inputs.
• src/components/common/__tests__/StaleDataWarning.test.tsx (5): renders null when fresh, standard copy when stale, age suffix, role="status" + aria-live="polite", custom message override.
• (additional src/hooks/__tests__/useStaleData.test.ts cases also pass — the hook is fully covered by the seven cases there.)

$ pnpm install        # ok
$ pnpm test           # 145 passed | 1 failed (CreatorInitialsAvatar, pre-existing)
$ pnpm lint           # clean
$ pnpm build          # clean (vite build, 5.78s)

Disclosures

1. src/components/common/__tests__/CreatorInitialsAvatar.test.tsx fails on main — the test queries getByLabelText('Alex Rivers initials avatar') but the component renders the initials with aria-hidden="true". Reproducible on unmodified upstream main; the bug was introduced by the same combination of e92b472 / 0213bcd that the kalveen feat(a11y/ui): main landmark, price-refresh state, no-script fallback, handle norm (#306/#305/#299/#298) #310 and precious feat(a11y/ui): profile header skeleton, accessible metric tooltips, bio clamp, onboarding placeholders (#291/#290/#282/#273) #311 accesslayer PRs already disclosed. Not touched here.
2. Add helper for detecting and displaying stale creator data warning #301 background-refresh wiring uses the existing handleRetryCreatorFetch rather than introducing a separate refresh code path. That's enough to satisfy the acceptance criterion ("a background refresh clears the warning once fresh data arrives") because a successful refetch sets creatorsFetchedAt again, which resets the staleness baseline and the hook's hasFiredForCurrentEpoch latch. A dedicated debounced background refresher could land later if the team wants to decouple it from the user-initiated retry flow.

[drips-wave]

@Mawuli-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits