Skip to content

fix(ui): raise dark-mode contrast for faint text and borders - #180

Merged
alltomatos merged 1 commit into
devfrom
design/164-dark-mode-token-contrast
Sep 9, 2026
Merged

alltomatos merged 1 commit into
devfrom
design/164-dark-mode-token-contrast

Conversation

@alltomatos

@alltomatos alltomatos commented Sep 9, 2026 •

Copy link
Copy Markdown
Owner

Issue for this PR

Closes #164

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

packages/ui/src/v2/styles/theme.css defines the --v2-* design tokens for light/dark via [data-color-scheme="light"]/[data-color-scheme="dark"]. I computed WCAG relative-luminance contrast ratios for the dark-mode pairs against every --v2-background-bg-* surface (base/deep/layer-01..04) and found real failures once an elevated surface (layer-03/-04, used by cards/popovers) is involved:

  • --v2-text-text-faint mapped to grey-600, which measures ~2.9:1 against layer-03/-04 — below the 4.5:1 body-text minimum. I moved it to grey-500 (same lightness as --v2-text-text-muted), which holds ≥3:1 against every background surface and ≥4.5:1 against bg-base/-deep, where faint text is used most often.
  • --v2-border-border-muted/-base used alpha-light-8/-10, which composite to only ~1.1-1.3:1 against layer-02/-03 — practically invisible dividers on dark surfaces. Bumped to alpha-light-14/-16 (kept --v2-border-border-strong at -20 so the muted/base/strong ladder stays distinct).
  • --v2-overlay-simple-overlay-hover/-pressed used alpha-light-6/-10, bumped to -10/-16 so hover/pressed feedback stays perceptible on dark surfaces.

I only reused existing --v2-grey-*/--v2-alpha-light-* steps already in packages/ui/src/v2/styles/colors.css — no new tokens were introduced, and the light-theme block (:root and [data-color-scheme="light"]) is untouched. This is the foundation issue for a larger dark-mode/Apple-like design pass (issues #165-#178 depend on it).

How did you verify your code works?

  • bun run typecheck in packages/app passes clean.
  • Contrast ratios computed by hand from the sRGB relative-luminance formula (WCAG 2.x) for each changed token against every --v2-background-bg-* value using the hex values in packages/ui/src/v2/styles/colors.css; the resulting ratios are documented in the commit message.
  • This sandbox can only run the desktop app inside its Electron shell, not a plain browser preview, so I could not capture a rendered screenshot myself — requesting a manual visual check from @alltomatos before merge.

Screenshots / recordings

Not available from this environment (see above) — manual check requested from @alltomatos.

Checklist

  • I have tested my changes locally (typecheck + manual contrast calculation)
  • I have not included unrelated changes in this PR

WCAG contrast math against the existing --v2-grey-* scale showed real
failures once elevated surfaces (--v2-background-bg-layer-03/-04) are
involved:

- text-faint (grey-600) measured ~2.9:1 against layer-03/-04 cards,
  below the 4.5:1 body-text minimum. Moved to grey-500 (same lightness
  as text-muted), which holds >=3:1 against every bg-* surface and
  >=4.5:1 against bg-base/-deep, where faint text is mostly used.
- border-muted/-base (alpha-light-8/-10) composited to ~1.1-1.3:1
  against layer-02/-03 surfaces — practically invisible dividers.
  Bumped to alpha-light-14/-16 (border-strong stays at -20, so the
  muted/base/strong ladder is still distinct).
- overlay hover/pressed (alpha-light-6/-10) bumped to -10/-16 so
  press/hover feedback stays perceptible on dark surfaces.

Only existing --v2-grey-*/--v2-alpha-light-* steps are used, no new
tokens introduced, and the light theme block is untouched.

Part of the dark-mode/Apple-like design pass (opencode#164).

Co-Authored-By: Claude Sonnet 5 <[email protected]>
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown

Thanks for updating your PR! It now meets our contributing guidelines. 👍

@alltomatos
alltomatos merged commit 113831d into dev Sep 9, 2026
12 of 21 checks passed
@alltomatos
alltomatos deleted the design/164-dark-mode-token-contrast branch September 9, 2026 20:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Design] Dark-mode token contrast pass — packages/ui/src/v2/styles/theme.css

1 participant