fix(a11y): make every text colour clear WCAG AA on every ramp

a11y.md flagged --yj-text-tertiary on --yj-bg-surface as 'borderline
(~4.1:1) but that needs a real measurement', and plan 007 parked it as
'worth measuring before planning'. Measured, against the rendered app
and then across all three background ramps: it failed AA in nine of
twelve text/surface combinations, as low as 2.31:1 on dark's overlay
and 2.55:1 on light's -- the app's most-used secondary text colour,
failing on every view. Not borderline. 110 failing nodes across twelve
views, now 0 of 659.

Three separate mechanisms, and only the first is the finding:

- The ramps. Tertiary is raised per ramp (#a6a6a6 dark, #949494 darker,
  #5c636a light), sized to the lightest surface it actually sits on and
  keeping its hue. Sizing it to bgOverlay too would need a grey lighter
  than secondary, so bgOverlay is documented as not a text surface and
  the one component that put text there uses primary.
- The avatar generator. hsl(hue, 45%, 35%) behind white initials failed
  for 35 of the 360 hues -- the yellow-green band -- so which artists
  were unreadable depended on how their names hashed. The two a sweep
  found were not the finding. 32% clears every hue.
- Jobs' local #ff6b6b, at 4.15:1 on elevated.

Pinned by a unit test over the palette table rather than a DOM sweep:
the ramps are pure data, and checking only what happens to be on screen
is exactly how the light ramp went unexamined. Note that make ui-visual
cannot see any of this -- the component tier renders the fallbacks,
because theme-store sets :root only in the real app.

frontend/src/components/downloads-view/downloads-view.ts

@@ -203,7 +203,11 @@ export class DownloadsView extends ViewLifecycleMixin(LitElement) {
                 border-radius: 6px;
                 font-size: 12px;
                 background: var(--yj-bg-overlay, rgba(255, 255, 255, 0.06));
-                color: var(--yj-text-secondary, #b3b3b3);
+                /* The only place in the app that puts text on bgOverlay,
+                   which is too light on the dark ramp to carry anything
+                   but primary: secondary measured 3.90:1 here. A notice
+                   is the last thing that should be hard to read. */
+                color: var(--yj-text-primary, #fff);
             }
 
             .section-hint {

frontend/src/components/explore-artist-details/explore-artist-details.ts

@@ -1,3 +1,4 @@
+import { avatarBackground } from '@utils/avatar-color';
 import { LitElement, html, css, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { designTokens } from '../../styles/tokens.css';
@@ -60,14 +61,6 @@ const NON_STUDIO_SECONDARY_TYPES = new Set([
 
 /* ── Utility functions (duplicated from explore-view per design decision) ── */
 
-function nameToHue(name: string): number {
-    let hash = 0;
-    for (let i = 0; i < name.length; i++) {
-        hash = name.charCodeAt(i) + ((hash << 5) - hash);
-    }
-    return Math.abs(hash) % 360;
-}
-
 function extractYear(dateStr: string): string {
     if (!dateStr) return '';
     return dateStr.substring(0, 4);
@@ -1884,7 +1877,6 @@ export class ExploreArtistDetails extends LitElement {
     /* ── Render ── */
 
     override render() {
-        const hue = nameToHue(this.artistName);
 
         return html`
             <div class="artist-header">
@@ -1898,7 +1890,7 @@ export class ExploreArtistDetails extends LitElement {
                 </button>
                 <div
                     class="artist-avatar"
-                    style="background: hsl(${hue}, 45%, 35%)"
+                    style="background: ${avatarBackground(this.artistName)}"
                 >
                     ${this.artistImageURL
                         ? html`<img
@@ -2392,7 +2384,6 @@ export class ExploreArtistDetails extends LitElement {
                 <h3 class="section-header">Similar Artists</h3>
                 <div class="similar-row ${collapsed ? 'collapsed' : ''}">
                     ${visible.map((a) => {
-                        const hue = nameToHue(a.name);
                         const imgURL = this.similarImageURLs.get(a.artistMbid);
                         return html`
                             <div
@@ -2412,7 +2403,7 @@ export class ExploreArtistDetails extends LitElement {
                             >
                                 <div
                                     class="similar-avatar"
-                                    style="background: hsl(${hue}, 45%, 35%)"
+                                    style="background: ${avatarBackground(a.name)}"
                                 >
                                     ${imgURL
                                         ? html`<img

frontend/src/components/explore-view/explore-view.ts

@@ -1,3 +1,4 @@
+import { avatarBackground } from '@utils/avatar-color';
 import { LitElement, html, css, nothing } from 'lit';
 import { customElement, state, query as litQuery } from 'lit/decorators.js';
 import '@components/page-header/page-header';
@@ -61,15 +62,6 @@ const MAX_SECTION_RESULTS = 10;
 const THUMBNAIL_CACHE_LIMIT = 96;
 
 
-/** Hash a string to a hue value 0–360 for avatar coloring. */
-function nameToHue(name: string): number {
-    let hash = 0;
-    for (let i = 0; i < name.length; i++) {
-        hash = name.charCodeAt(i) + ((hash << 5) - hash);
-    }
-    return Math.abs(hash) % 360;
-}
-
 /** Format milliseconds as mm:ss. */
 function formatDuration(ms: number): string {
     if (!ms || ms <= 0) return '';
@@ -1734,7 +1726,6 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
                     : nothing}
                 <div class="horizontal-row">
                     ${artists.map((a) => {
-                        const hue = nameToHue(a.name);
                         return html`
                             <div
                                 class="artist-card"
@@ -1750,7 +1741,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
                             >
                                 <div
                                     class="artist-avatar"
-                                    style="background: hsl(${hue}, 45%, 35%)"
+                                    style="background: ${avatarBackground(a.name)}"
                                 >
                                     ${this.artistImageCache.get(a.mbid)
                                         ? html`<img

frontend/src/components/jobs/job-details-drawer.ts

@@ -132,7 +132,7 @@ export class JobDetailsDrawer extends LitElement {
             }
 
             .stage.error {
-                color: #ff6b6b;
+                color: #ff8787;
             }
 
             .stage-count {
@@ -144,7 +144,7 @@ export class JobDetailsDrawer extends LitElement {
             .stage-error {
                 grid-column: 2 / -1;
                 font-size: var(--yj-text-sm);
-                color: #ff6b6b;
+                color: #ff8787;
                 overflow-wrap: anywhere;
             }
 

frontend/src/components/jobs/job-format.ts

@@ -154,7 +154,7 @@ export const jobStateStyles = css`
     }
 
     .tone-danger {
-        --job-tone: #ff6b6b;
+        --job-tone: #ff8787;
     }
 
     .tone-success {

frontend/src/components/jobs/job-indicator.ts

@@ -153,7 +153,7 @@ export class JobIndicator extends LitElement {
                 width: 6px;
                 height: 6px;
                 border-radius: 50%;
-                background: #ff6b6b;
+                background: #ff8787;
                 flex-shrink: 0;
             }
 

frontend/src/components/jobs/job-log-view.ts

@@ -132,7 +132,7 @@ export class JobLogView extends LitElement {
             }
 
             .entry.error .message {
-                color: #ff6b6b;
+                color: #ff8787;
             }
 
             .detail {

frontend/src/components/jobs/job-row.ts

@@ -180,7 +180,7 @@ export class JobRow extends LitElement {
             .error {
                 margin-top: 0.45em;
                 font-size: var(--yj-text-sm);
-                color: #ff6b6b;
+                color: #ff8787;
                 overflow-wrap: anywhere;
             }
 
@@ -214,7 +214,7 @@ export class JobRow extends LitElement {
             }
 
             button.danger:hover:not(:disabled) {
-                color: #ff6b6b;
+                color: #ff8787;
             }
 
             button:disabled {

frontend/src/components/jobs/jobs-view.ts

@@ -201,7 +201,7 @@ export class JobsView extends ViewLifecycleMixin(LitElement) {
             }
 
             button.action.danger {
-                color: #ff6b6b;
+                color: #ff8787;
                 border-color: rgba(255, 107, 107, 0.35);
             }
 

frontend/src/components/smart-playlist-editor/smart-playlist-editor.ts

@@ -287,7 +287,7 @@ export class SmartPlaylistEditor extends LitElement {
             }
 
             .remove-btn:hover {
-                color: #ff6b6b;
+                color: #ff8787;
                 background: rgba(255, 107, 107, 0.1);
             }
 
@@ -411,7 +411,7 @@ export class SmartPlaylistEditor extends LitElement {
 
             .preview-error {
                 font-size: var(--yj-text-sm);
-                color: #ff6b6b;
+                color: #ff8787;
                 padding: 6px 0;
             }
 

frontend/src/store/theme-store.ts

@@ -20,7 +20,7 @@ type Subscriber = () => void;
  * Shade palettes keyed by BackgroundShade.
  * Each defines the base grayscale ramp used throughout the UI.
  */
-interface ShadePalette {
+export interface ShadePalette {
     bgBase: string;
     bgSurface: string;
     bgElevated: string;
@@ -34,7 +34,36 @@ interface ShadePalette {
     selectionBg: string;
 }
 
-const SHADE_PALETTES: Record<BackgroundShade, ShadePalette> = {
+/**
+ * The grayscale ramps, and the one rule that constrains them.
+ *
+ * `textTertiary` used to be `#888888` on both dark ramps and `#868e96`
+ * on the light one, which `a11y.md` flagged as "borderline" from a hand
+ * calculation and parked as "worth measuring before planning".
+ * Measured, against the rendered app and then across all three ramps:
+ * it failed WCAG AA in **nine of twelve** text/surface combinations,
+ * as low as 2.31:1 on dark's overlay and 2.55:1 on light's. Not
+ * borderline — the app's most-used secondary text colour, failing on
+ * every view, and the light ramp (which the audit never considered) was
+ * the worst of the three.
+ *
+ * So: **every text colour clears 4.5:1 against every surface it can sit
+ * on**, and `theme-contrast.test.ts` computes that from this table
+ * rather than trusting it. Two things decided the values.
+ *
+ * `bgOverlay` is not a text surface on the dark ramp. Sizing tertiary
+ * to clear 4.5 against `#495057` needs `#c0c0c0`, which is *lighter
+ * than secondary* — an inverted hierarchy is a worse answer than the
+ * problem. Tertiary is sized to `bgElevated` there, and the one place
+ * that did put text on the overlay (the downloads notice) uses
+ * `textPrimary`, which clears 8.18:1.
+ *
+ * And the hue is kept. The light ramp's tertiary is a blue-grey, so it
+ * darkens along its own hue to `#5c636a` rather than flattening to a
+ * neutral that would have passed just as well and looked like a
+ * different palette.
+ */
+export const SHADE_PALETTES: Record<BackgroundShade, ShadePalette> = {
     darker: {
         bgBase: '#000000',
         bgSurface: '#121212',
@@ -42,7 +71,8 @@ const SHADE_PALETTES: Record<BackgroundShade, ShadePalette> = {
         bgOverlay: '#2a2a2a',
         textPrimary: '#ffffff',
         textSecondary: '#b3b3b3',
-        textTertiary: '#888888',
+        // 4.05:1 on bgOverlay at #888888.
+        textTertiary: '#949494',
         border: '#333333',
         borderSubtle: '#222222',
         hoverOverlay: 'rgba(255, 255, 255, 0.05)',
@@ -55,7 +85,9 @@ const SHADE_PALETTES: Record<BackgroundShade, ShadePalette> = {
         bgOverlay: '#495057',
         textPrimary: '#ffffff',
         textSecondary: '#b3b3b3',
-        textTertiary: '#888888',
+        // 4.35:1 on bgSurface and 3.25:1 on bgElevated at #888888 — the
+        // measured version of the audit's estimate, on every view.
+        textTertiary: '#a6a6a6',
         border: '#444444',
         borderSubtle: '#333333',
         hoverOverlay: 'rgba(255, 255, 255, 0.05)',
@@ -68,7 +100,9 @@ const SHADE_PALETTES: Record<BackgroundShade, ShadePalette> = {
         bgOverlay: '#dee2e6',
         textPrimary: '#212529',
         textSecondary: '#495057',
-        textTertiary: '#868e96',
+        // 3.32:1 at best and 2.55:1 at worst at #868e96 — the light ramp
+        // failed on all four of its own surfaces.
+        textTertiary: '#5c636a',
         border: '#ced4da',
         borderSubtle: '#dee2e6',
         hoverOverlay: 'rgba(0, 0, 0, 0.05)',

frontend/src/utils/avatar-color.ts

@@ -0,0 +1,36 @@
+/**
+ * The background for a letter avatar, derived from a name.
+ *
+ * Three call sites drew `hsl(nameToHue(name), 45%, 35%)` behind white
+ * initials, from two copies of the same hash function. Measured across
+ * all 360 hues: **35 of them** — the yellow-green band from about 53°
+ * to 88° — put white text below 4.5:1, bottoming out at 4.08:1. Which
+ * artists those were depended entirely on how their names hashed, so
+ * the app had a contrast failure that came and went with the search
+ * results, and the two instances that turned up in a sweep were not the
+ * finding.
+ *
+ * 32% lightness clears every hue with a floor of 4.75:1, so the fix is
+ * a property of the generator rather than of any colour it generates.
+ * `avatar-color.test.ts` walks all 360.
+ */
+
+/** Hash a string to a hue value 0–360. */
+export function nameToHue(name: string): number {
+    let hash = 0;
+
+    for (let i = 0; i < name.length; i++) {
+        hash = name.charCodeAt(i) + ((hash << 5) - hash);
+    }
+
+    return Math.abs(hash) % 360;
+}
+
+/** Saturation and lightness are shared so the floor above holds. */
+export const AVATAR_SATURATION = 45;
+export const AVATAR_LIGHTNESS = 32;
+
+/** The `background` value for a name's avatar. */
+export function avatarBackground(name: string): string {
+    return `hsl(${nameToHue(name)}, ${AVATAR_SATURATION}%, ${AVATAR_LIGHTNESS}%)`;
+}

frontend/test/components/avatar-color.test.ts

@@ -0,0 +1,77 @@
+/**
+ * A letter avatar's background clears 4.5:1 against white for *every*
+ * hue it can generate.
+ *
+ * The two failures a rendered sweep found were not the finding. The
+ * generator was `hsl(hue, 45%, 35%)`, and 35 of the 360 hues — the
+ * yellow-green band — put white initials below 4.5:1, bottoming out at
+ * 4.08:1. Which artists those were depended on how their names hashed,
+ * so the failure came and went with the search results.
+ *
+ * So this walks all 360 rather than sampling: a generator's contrast is
+ * a property of the generator, and checking the instances that happened
+ * to be on screen is how it stayed broken.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { avatarBackground, nameToHue } from '@utils/avatar-color';
+
+/** Resolve an `hsl(...)` string to sRGB via the browser's own parser. */
+function toRgb(color: string): [number, number, number] {
+  const probe = document.createElement('div');
+
+  probe.style.color = color;
+  document.body.append(probe);
+
+  const computed = getComputedStyle(probe).color;
+
+  probe.remove();
+
+  const [r, g, b] = computed
+    .slice(computed.indexOf('(') + 1, computed.indexOf(')'))
+    .split(/[,\s/]+/)
+    .filter(Boolean)
+    .map(Number) as [number, number, number];
+
+  return [r, g, b];
+}
+
+function contrastWithWhite(color: string): number {
+  const channels = toRgb(color).map((v) => v / 255);
+
+  const [r, g, b] = channels.map((v) =>
+    v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4,
+  ) as [number, number, number];
+
+  const l = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+  return 1.05 / (l + 0.05);
+}
+
+describe('avatar colours', () => {
+  it('clears 4.5:1 against white at every hue', () => {
+    const ratios = Array.from({ length: 360 }, (_, hue) =>
+      contrastWithWhite(`hsl(${hue}, 45%, 32%)`),
+    );
+
+    expect(Math.min(...ratios)).toBeGreaterThanOrEqual(4.5);
+  });
+
+  // The generator is only safe if every name lands on one of those hues,
+  // which is the half a hue-only sweep cannot see.
+  it('generates only hues in that range', () => {
+    const names = ['Eno', 'BTS', 'Aurora Fields', '', 'ザ・バンド', 'x'.repeat(200)];
+
+    const hues = names.map((n) => nameToHue(n));
+
+    expect(hues.every((h) => Number.isInteger(h) && h >= 0 && h < 360)).toBe(
+      true,
+    );
+  });
+
+  it('is the same colour for the same name', () => {
+    expect(avatarBackground('Aurora Fields')).toBe(
+      avatarBackground('Aurora Fields'),
+    );
+  });
+});

frontend/test/components/theme-contrast.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Every text colour clears WCAG AA against every surface it can sit on,
+ * on all three background ramps.
+ *
+ * `a11y.md` flagged one pair as "borderline (≈4.1:1) but that needs a
+ * real measurement", and plan 007 parked it as "worth measuring before
+ * planning". Measured: it failed in **nine of twelve** combinations,
+ * as low as 2.31:1, and the light ramp — which the audit never looked
+ * at — was the worst of the three.
+ *
+ * This computes the ratios from the palette table rather than trusting
+ * it, because the failure mode is somebody picking a nice-looking hex.
+ * It is a unit test and not a sweep of the rendered app on purpose: the
+ * ramps are pure data, the arithmetic is exact, and a DOM sweep can
+ * only ever check the pairs that happen to be on screen — which is how
+ * the light ramp went unexamined in the first place.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { SHADE_PALETTES } from '@store/theme-store';
+import type { ShadePalette } from '@store/theme-store';
+
+/** WCAG 2.1 relative luminance. */
+function luminance(hex: string): number {
+  const h = hex.replace('#', '');
+  const channels = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+
+  const [r, g, b] = channels.map((v) =>
+    v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4,
+  ) as [number, number, number];
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [
+    number,
+    number,
+  ];
+
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+const TEXT = ['textPrimary', 'textSecondary', 'textTertiary'] as const;
+
+/**
+ * `bgOverlay` is deliberately absent for tertiary on the dark ramp.
+ * Clearing 4.5:1 against `#495057` needs a grey lighter than
+ * `textSecondary`, and an inverted hierarchy is a worse answer than the
+ * problem — so nothing puts tertiary text there, and the one component
+ * that put *secondary* text on an overlay uses primary now.
+ */
+const SURFACES: Record<(typeof TEXT)[number], (keyof ShadePalette)[]> = {
+  textPrimary: ['bgBase', 'bgSurface', 'bgElevated', 'bgOverlay'],
+  textSecondary: ['bgBase', 'bgSurface', 'bgElevated'],
+  textTertiary: ['bgBase', 'bgSurface', 'bgElevated'],
+};
+
+describe('theme contrast', () => {
+  const cases = Object.entries(SHADE_PALETTES).flatMap(([shade, palette]) =>
+    TEXT.flatMap((text) =>
+      SURFACES[text].map((surface) => ({
+        shade,
+        text,
+        surface,
+        ratio: contrast(palette[text], palette[surface]),
+      })),
+    ),
+  );
+
+  it.each(cases)('$shade: $text on $surface clears 4.5:1', ({ ratio }) => {
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+  });
+
+  // Sizing tertiary to clear 4.5:1 on every surface is easy and wrong:
+  // it produces a tertiary lighter than secondary on the dark ramp. The
+  // ramp has to stay a ramp, or "tertiary" stops meaning anything.
+  it.each(Object.entries(SHADE_PALETTES))(
+    '%s keeps the text ramp ordered',
+    (_shade, palette) => {
+      const steps = TEXT.map((t) => contrast(palette[t], palette.bgSurface));
+
+      expect(steps).toEqual([...steps].sort((a, b) => b - a));
+    },
+  );
+});