# Dark mode

Dark Mode is a mode in the Figma export, so `tokens.css` emits it **verbatim**
under `:root[data-color-mode="dark"]` — the tokens that differ from Light.

**Nothing here is corrected or invented.** The contrast corrections listed in
[foundations.md](foundations.md) are measured against Light Mode surfaces and are
not transferred. Enable it with `data-color-mode="dark"` on the root element.

## Known weaknesses

Reported, not patched — patching would mean changing the tokens.

| Role | Value | Consequence |
|---|---|---|
| `border-primary` = `border-secondary` | both `#262626` | a container edge and a control edge become indistinguishable |
| `text-tertiary` = `text-quarternary` | both `#a3a3a3` | the four-step text ramp collapses to three |
| `icon-tertiary` = `icon-quarternary` = `icon-disabled` | all `#737373` | a disabled icon reads the same as an enabled one |
| `bg-brand-primary` = `bg-secondary` | both `#171717` | a selected nav item disappears against the control surface |
| `bg-brand-primary_hover` = `bg-brand-primary_press` | both `#262626` | pressed is identical to hover |
| `text-placeholder` | `#737373` | measures 3.78:1 on the dark surface — below the 4.5:1 AA minimum |
| Soft status fills | `bg-error` / `bg-warning` / `bg-success` / `bg-info` | exported as translucent overlays, so their contrast changes with whatever sits behind them |
| Added roles | `--focus-ring`, `--ring-*`, `--shadow-*`, `--border-control` | these are not in the export and carry Light Mode values only; they do not adapt |
| Alpha ramp | `alpha-*-accent-*` | resolves to opaque `#ffffff` in Dark — the alpha is lost, so anything using it as a translucent band renders as a solid white fill |
| `bg-dark` | `#171717` | stays dark in Dark Mode, so a surface meant to invert against the canvas disappears — use `bg-alt`, which flips |
| `bg-error-secondary` | `#dc2626` | a *solid* red in Dark, not a soft tint — any component using it as a soft fill puts `text-error` red-on-red; the Button corrects its own content, other components may not |
| Light Mode corrections | `text-error`, `text-warning`, `text-success`, `text-placeholder`, `text-quarternary` | the contrast fixes applied to Light are not applied here, by request |

## What this means in practice

- Treat Dark Mode as **usable but unaudited**. No contrast measurement was run
  against it.
- The collapsed roles are export defects, not implementation choices. A selected
  nav item, a pressed state and a disabled icon each need a second signal —
  a border, a weight change — rather than relying on the surface alone.
- The added roles (`--focus-ring`, `--ring-*`, `--shadow-*`, `--border-control`)
  are not in the export and carry Light values only. They do not adapt.