Design tokens: migrate from `--color-*` to the Carol DS token set (light + dark) #138

New issue

Closed

opened 2026-06-19 17:34:02 +00:00 by james · 0 comments

james commented

2026-06-19 17:34:02 +00:00

Owner

The design package (../carol-design/) ships a fuller token set than the current app/themes/. We use --color-fg / --color-bg / --color-accent / --color-border / --color-surface; the DS uses --bg / --surface / --surface-2 / --surface-3 / --inset / --text / --text-secondary / --text-muted / --text-faint / --border / --border-strong / --border-subtle / --accent / --accent-fg / --accent-subtle / --accent-text / --ring, plus the brand blue scale and ink ramp.

Adopting the new aliases is the foundation for the design's three other shifts (component primitives, sidebar shell, per-screen rebuilds).

Scope

Extend app/themes/light.css and app/themes/dark.css with the full DS alias set, values lifted from the design's tokens/colors.css (cited in the PR body).
Keep the existing --color-* names as deprecated aliases pointing at the same values, so existing inline-styled components don't visually regress. They flip per-surface during the screen-rebuild tickets.
Capture the rename + the bridge period in an ADR.
Update CLAUDE.md Stack defaults → themes line to point at the new token surface; keep ADR-0008 cited as the engine (cookie + DB persistence is unchanged).

Acceptance criteria

Both themes ship every DS alias listed in the design's colors.css.
git grep "var(--color-" still returns matches (the bridge), but new code reaches for the DS names.
ADR captured.
No visual regression on any current screen (Profile / Skills / Education / Account / Notes / login / register).

Out of scope

Migrating existing inline-styled components to the new names. They flip per-surface during the screen rebuilds (the Account / Profile / Skills / Education tickets).
Final removal of the --color-* aliases — separate cleanup ticket once every surface has flipped.

Composes with

Design package (../carol-design/), ADR-0008 (theme system), every existing (app) surface as inert until the screen-rebuild tickets pick the new names up.

The design package (`../carol-design/`) ships a fuller token set than the current `app/themes/`. We use `--color-fg / --color-bg / --color-accent / --color-border / --color-surface`; the DS uses `--bg / --surface / --surface-2 / --surface-3 / --inset / --text / --text-secondary / --text-muted / --text-faint / --border / --border-strong / --border-subtle / --accent / --accent-fg / --accent-subtle / --accent-text / --ring`, plus the brand blue scale and ink ramp. Adopting the new aliases is the foundation for the design's three other shifts (component primitives, sidebar shell, per-screen rebuilds). ## Scope - Extend `app/themes/light.css` and `app/themes/dark.css` with the full DS alias set, values lifted from the design's `tokens/colors.css` (cited in the PR body). - Keep the existing `--color-*` names as deprecated aliases pointing at the same values, so existing inline-styled components don't visually regress. They flip per-surface during the screen-rebuild tickets. - Capture the rename + the bridge period in an ADR. - Update `CLAUDE.md` *Stack defaults → themes* line to point at the new token surface; keep ADR-0008 cited as the engine (cookie + DB persistence is unchanged). ## Acceptance criteria - [ ] Both themes ship every DS alias listed in the design's `colors.css`. - [ ] `git grep "var(--color-"` still returns matches (the bridge), but new code reaches for the DS names. - [ ] ADR captured. - [ ] No visual regression on any current screen (Profile / Skills / Education / Account / Notes / login / register). ## Out of scope - Migrating existing inline-styled components to the new names. They flip per-surface during the screen rebuilds (the Account / Profile / Skills / Education tickets). - Final removal of the `--color-*` aliases — separate cleanup ticket once every surface has flipped. ## Composes with Design package (`../carol-design/`), ADR-0008 (theme system), every existing `(app)` surface as inert until the screen-rebuild tickets pick the new names up.

james added the

area:pwa

foundation

labels

2026-06-19 17:36:07 +00:00

james referenced this issue from a commit

2026-06-19 17:46:50 +00:00

feat(themes): adopt Carol DS token surface with --color-* bridge (#138)

james referenced this issue from a pull request that will close it,

2026-06-19 17:47:12 +00:00

feat(themes): adopt Carol DS token surface with --color-* bridge (#138) #147

james closed this issue