refactor(ui): tokenize all design primitives (Phase 0 harmonization) - #338
Merged
Merged
Conversation
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
Single-pass migration of stem's UI to use semantic design tokens instead
of raw Tailwind utilities. Step 1 of the seed/stem/niac harmonization
plan: each repo must use a self-contained semantic token vocabulary,
with shared names (different per-product values) so a shared shell
renders correctly everywhere.
Tokens added to ui/src/index.css
- --color-text-disabled (light + dark)
- --color-surface-deep (gradient terminus for the upcoming shared shell)
- --color-log-{trace,debug,info,warn,error,fatal} (Syslog/RFC 5424,
constant across modes)
- --color-scrim (#000000, constant) — bg-scrim/N for modal/drawer backdrops
- --color-knob (#ffffff, constant) — toggle thumbs, text on saturated brand bg
Migration applied
- Colors: removed every raw palette class and bare bg-white/bg-black.
Routes through brand-*/surface-*/text-*/status-*/log-* tokens.
- Spacing: numeric utilities → semantic (space-y-3 → stack, gap-3 →
gap-default, p-4 → pad, mb-6 → mb-section, etc.).
- Typography: text-2xl font-bold compounds → heading-1/2/3/4; body /
body-small / caption / label / section-title where matched.
- Layout: flex items-center justify-between → flex-between, flex-center.
- Arbitrary-value indirection: text-[var(--color-status-error)] →
text-status-error.
- Button.tsx: solid-tone variants now use bg-status-* / bg-brand-primary
with hover opacity instead of gradient-from-palette pairs.
New tooling
- scripts/migrate-tokens.py — reusable Python migration script (also
used in seed and niac with the same source-of-truth mapping).
- scripts/check-token-discipline.sh — CI gate that fails on raw palette,
bare white/black, raw spacing utilities, heading pairs, var() color
indirection, and flex shortcuts. Wired into ci.yml frontend job.
- ui/src/utils/prefetch.ts — minimal stub for the shared Sidebar's
hover-prefetch call site.
Validated
- Discipline gate, Biome lint, npm run build all green
- Rebased on latest main after merge conflicts
krisarmstrong
force-pushed
the
chore/phase0-tokenize-design-primitives
branch
from
May 27, 2026 19:20
6c3f7ae to
32464c8
Compare
krisarmstrong
enabled auto-merge (squash)
May 27, 2026 19:21
Contributor
License Compliance ReportAll dependencies pass license compliance checksGo Dependencies
npm DependenciesSee full report in workflow artifacts Allowed Licenses: MIT, Apache-2.0, BSD-*, ISC, CC0-1.0, MPL-2.0 |
This was referenced May 27, 2026
krisarmstrong
added a commit
that referenced
this pull request
May 27, 2026
…345) * fix(ci): unblock main — race in sse, lighthouse cert, e2e selectors main ci has been failing since phase 0 tokenization (#338) merged. three independent root causes — none were phase-0 regressions but phase-0 was the first change broad enough to trip the path filters and surface them. backend (race detector): sse broadcaster's publish() released the read lock before sending, so a concurrent unsubscribe could close the channel between the "copy subs" snapshot and the send → write-on-closed-channel race. fix: hold the read lock across the (non-blocking, select-default) sends; the stalled-subscriber cleanup happens after the rlock is released so unsubscribe's write lock can proceed. e2e: - history-page "result snapshot or empty hint": locator `text=/...|history|.../` matched the sidebar "history" label first (hidden on mobile viewport) before reaching the main content. scope to the page section. - language-switch tests asserted on "test modules" / "módulos de prueba" but the i18n key common.sections.modules was never wired into any rendered ui — sidebar tests group was hardcoded `label: 'tests'`. wire sidebar via t() with defaultvalue fallback so existing display strings still work, set tests group label to the i18n key. now the marker actually renders, in both languages. lighthouse audit: treosh/lighthouse-ci-action was called with an inline urls: override but no configpath, so .lighthouserc.json's settings were ignored. workflow targets https://localhost:8444 (stem is https- only post-wave-1) with a mkcert dev cert that the ci runner does not trust → INSECURE_DOCUMENT_REQUEST / ERR_CERT_AUTHORITY_INVALID on every audit, blocking every release-please run for the past several merges. fix: add chromeflags (--ignore-certificate-errors --allow-insecure-localhost) to .lighthouserc.json settings and pass configpath: ./.lighthouserc.json so the action loads them. unblocks release-please for stem. * fix(lint): biome formatting + replace dead noExplicitAny suppressions - Sidebar.tsx: biome format pass after the t() wrapping refactor (re-indentation inside the new `=> { ... }` body) - useLocale.test.ts: the two `biome-ignore lint/suspicious/noExplicitAny` comments stopped suppressing anything after a biome upgrade — the underlying `any` was already type-safe enough that biome no longer flagged it. replace `as any` with explicit cast through `UseTranslationResponse<...>['i18n'|'t']` and drop the dead suppressions. tests still pass (3/3 in useLocale.test.ts). --------- Co-authored-by: Kris Armstrong <kris.armstrong@icloud.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Single-pass migration of stem's UI to use semantic design tokens instead of raw Tailwind utilities. Step 1 of the seed/stem/niac harmonization plan. Each repo will use a self-contained semantic token vocabulary, with shared names (different per-product values) so a future shared shell renders correctly everywhere.
scripts/check-token-discipline.sh)What changed
bg-red-500,text-blue-400/50,bg-whitebg-status-error,text-status-info/50,bg-knobspace-y-3,gap-3,p-4,mb-6stack,gap-default,pad,mb-sectiontext-2xl font-bold text-text-primary leading-tightheading-1text-base text-text-primary leading-relaxedbodyflex items-center justify-betweenflex-betweentext-[var(--color-status-error)]text-status-errorbg-black/60 backdrop-blur-smbg-scrim/60 backdrop-blur-smbg-gradient-to-r from-red-600 to-red-500 shadow-red-500/25bg-status-error hover:bg-status-error/85 shadow-status-error/25Tokens added to
ui/src/index.css--color-text-disabled(light + dark)--color-surface-deep(gradient terminus for the upcoming shared shell)--color-log-{trace,debug,info,warn,error,fatal}(Syslog/RFC 5424, constant across modes — port from NIAC)--color-scrim(#000000, constant) —bg-scrim/Nfor modal/drawer backdrops--color-knob(#ffffff, constant) — toggle thumbs, text on saturated brand bgNew tooling
scripts/migrate-tokens.py— reusable Python migration script. Idempotent; will be re-run in seed and niac with the same source-of-truth mapping.scripts/check-token-discipline.sh— CI gate wired into.github/workflows/ci.ymlfrontend job. Fails on raw palette, bare white/black, raw spacing utilities with semantic replacements, heading pairs that should beheading-N,var()color indirection, and flex shortcuts.ui/src/utils/prefetch.ts— minimal stub so the shared Sidebar's hover-prefetch call site compiles. PopulateROUTE_PREFETCH_MAPwith stem routes as performance wins arise.Why
Three-product harmonization (seed / stem / niac) needs each repo to expose the same token vocabulary by name while owning its own values. This PR is the proof-of-concept and reference implementation. Identical Phase 0 PRs will follow for seed and niac before the shared shell (Sidebar / HeaderBar / PageHeader) is rolled out.
Test plan
./scripts/check-token-discipline.sh— PASSnpm run lint— PASS (2 pre-existing warnings unrelated to this PR)npx tsc --noEmit— PASSnpm run build— PASS, CSS bundle smaller🤖 Generated with Claude Code