[Feature] Contrast multiplier (--contrast) for accessibility-tunable translucent UI

[aosmcleod]

Feature description

A --contrast CSS custom property that acts as a global multiplier for translucent/semi-transparent UI elements — focus rings, soft backgrounds, tinted overlays, and hover states. Raising it makes these elements more visible for users with low vision; lowering it produces a subtler, more muted aesthetic.

This is an accessibility-first feature: it gives end users (or app developers) a single knob to improve the visibility of focus indicators and interactive state feedback without changing the colour palette itself.

How it works

The variable defaults to 1 and is consumed via calc() inside color-mix percentages:

:root {
  --contrast: 1;
}

/* Example: focus ring outer halo */
--focus-ring-color: color-mix(
  in oklch,
  var(--accent) calc(25% * var(--contrast)),
  transparent
);

/* Example: soft background (accent-soft) */
--accent-soft: color-mix(
  in oklab,
  var(--accent) calc(15% * var(--contrast)),
  transparent
);

When --contrast is 1, the percentages are unchanged (25%, 15%). When raised to 1.5, they become 37.5% and 22.5% — noticeably more visible. When lowered to 0.7, they become 17.5% and 10.5% — subtler.

What it scales

• Focus ring outer halo opacity
• Soft/tinted background fills (accent-soft, status-soft variants)
• Field shadows (primary hairline drop, secondary inset)
• Hover state tints on fields and rows

What it does NOT scale

• Solid fills (primary buttons, selected states)
• Text colour
• Border colour
• Component sizing or spacing

Accessibility value

WCAG 2.1 SC 1.4.11 (Non-text Contrast) requires 3:1 contrast for UI components and graphical objects. Focus rings and soft backgrounds are the most common failure points. A --contrast multiplier lets:

1. App developers ship a higher default for enterprise/accessibility-focused products
2. End users raise contrast in a settings dialog without switching to a high-contrast theme
3. Theme authors tune the visual weight of translucent elements per-theme

Scope

This is a CSS-only addition — a single variable in :root plus modifications to existing color-mix expressions. No new React components or props needed. The variable could be exposed via a future applyTheme() API or simply documented as a CSS override.

Recommended range

0.5 – 2.0. Values below 0.5 make focus rings nearly invisible; values above 2.0 make soft backgrounds look like solid fills.