Services

Dark Theme Color Review

Dark-theme color review final summary

Final pass scope#

This document summarizes the dark-theme color review and the follow-up tuning slices reported for the review-colors-for-dark-theme AWAO task.

Final documentation pass evidence:

  • Verified the required review artifact exists with ls -l docs/design/dark-theme-color-review.md.
  • Inspected current checkout state and the reported slice commits/changes before updating this summary.
  • No broad code changes were made in this pass; only this documentation file was updated.

What changed#

Content apps and shared UI theme#

The content slice is present in the current checkout through merge commit e37663eb / implementation commit 00d3c641.

Changes made:

  • Raised shared dark --foreground-muted contrast in packages/ui/build/css/themes/dark.css and packages/ui/build/css/themes/dark-combined.css.
  • Tokenized previously hard-coded selection and documentation colors in docs/content surfaces.
  • Fixed dark destructive foreground/background token pairs for apps/academy and apps/ui-library, including preview dark tokens.
  • Replaced Academy MDX blockquote blue styling with token-driven dark-theme-safe styling.
  • Updated the theme sandbox defaults to use the tuned token values.

Worker verification reported:

  • mise exec -- pnpm turbo run build --filter=docs completed successfully.
  • A broader build was attempted and partially completed before timing out, per worker report.

Studio theme contrast#

The Studio slice is now present in the current checkout through merge commit abad3d8c / implementation commit a52d32f2.

Reported changes:

  • Raised Studio dark --foreground-muted contrast in apps/studio/styles/assistance-theme.css.
  • Raised generated Studio UI dark --foreground-muted values in packages/studio-ui/build/css/themes/dark.css and packages/studio-ui/build/css/themes/dark-combined.css.
  • Switched Studio prose links from --brand-500 to the more readable --brand-link token in packages/studio-config/tailwind.config.js.

Worker verification reported:

  • Static contrast check passed:
    • Assistance muted: 5.13:1
    • Studio UI dark muted: 4.74:1
    • Brand link: 8.24:1
  • mise run typecheck:studio was attempted but blocked by missing node_modules/next in that worker worktree.

Admin, Manager, and SaaS UI semantic state colors#

The Admin/Manager slice is now present in the current checkout through merge commit fdf04bc9 / implementation commit 55bf18bc.

Reported changes:

  • Added semantic state tokens to apps/manager/src/globals.css and apps/admin/src/globals.css.
  • Exposed those tokens through Tailwind v4 @theme inline.
  • Migrated packages/saas-ui/src/shared/status-badge.tsx away from hard-coded status colors to semantic token classes.

Worker verification reported:

  • mise run build:manager passed.
  • mise exec -- node /tmp/verify-status-contrast.mjs passed.
  • The temporary contrast script was removed.

Resolved findings#

  • Content app destructive text-on-fill pairs were tuned away from the original failing dark-mode ratios.
  • Shared/content muted foreground contrast was raised so normal secondary text has a safer dark-mode baseline.
  • Several hard-coded dark colors in content/documentation surfaces were replaced with token usage.
  • Academy blockquote styling now follows the token system instead of a fixed blue treatment.
  • Studio muted text and prose link contrast were addressed in the reported Studio slice.
  • SaaS status badge color drift was addressed in the reported Admin/Manager slice by introducing semantic status tokens.

Unresolved risks and intentionally deferred items#

  • Slice integration status: content, Studio, and Admin/Manager dark-theme tuning slices are now merged into main.
  • Sidebar color-space mismatch remains deferred: shared config still needs a deliberate migration so HSL sidebar triples are not consumed through OKLCH wrappers.
  • Content elevation remains a design follow-up: academy and ui-library dark card/popover/background surfaces are readable, but deeper elevation steps were not redesigned in this pass.
  • Docs/content token forking remains a maintenance risk: docs-specific dark foreground and code-token overrides should be upstreamed or formalized if they are the desired shared content reading baseline.
  • Visual QA was not performed by the final documentation pass: contrast scripts and builds are useful, but they do not replace browser review across the affected dark-mode surfaces.
  1. Open docs, academy, and ui-library in dark mode and inspect:
    • destructive buttons/alerts,
    • selections,
    • code blocks,
    • blockquotes,
    • cards/popovers against the page canvas.
  2. Open manager and admin in dark mode and inspect:
    • active/paid/success badges,
    • pending/warning badges,
    • overdue/danger badges,
    • canceled/neutral badges on both black and elevated gray surfaces.
  3. Open studio in dark mode and inspect:
    • normal secondary text using muted tokens,
    • prose links,
    • sidebar labels,
    • disabled/decorative metadata that intentionally remains lower contrast.
  4. Re-run focused contrast checks against rendered CSS values, not just source tokens, for each affected app.
  5. If sidebar tokens are migrated later, add a focused check that verifies the generated CSS uses the correct color function for each token source.

Final-pass verification#

Commands run by this pass:

bash
1
ls -l docs/design/dark-theme-color-review.md
2
git merge-base --is-ancestor 00d3c641 main
3
git merge-base --is-ancestor 55bf18bc main
4
git merge-base --is-ancestor a52d32f2 main
5
git diff HEAD -- docs/design/dark-theme-color-review.md
6
mise exec -- pnpm prettier --check docs/design/dark-theme-color-review.md
7
git diff --check -- docs/design/dark-theme-color-review.md