Skip to content

Semantic color tokens to enable CSS-variable theming#27

Merged
chrysb merged 3 commits intochrysb:mainfrom
keaganstokoe:feat/semantic-theme-tokens
Mar 22, 2026
Merged

Semantic color tokens to enable CSS-variable theming#27
chrysb merged 3 commits intochrysb:mainfrom
keaganstokoe:feat/semantic-theme-tokens

Conversation

@keaganstokoe
Copy link
Copy Markdown
Contributor

@keaganstokoe keaganstokoe commented Mar 17, 2026

Problem

~90 component files use hardcoded Tailwind color classes (text-gray-300, bg-red-950/95, border-yellow-700/80, etc.). Adding a light theme or any other styling means touching every file.

What this does

Adds a semantic token layer between components and colors:

Component class      Tailwind alias       CSS variable              Value
text-body            body                 --text                    #c9d1d9
bg-status-error-bg   status.error-bg      --status-error-bg         rgba(127,29,29,0.95)

Then refactors all component files to use the semantic names instead of raw Tailwind shades.

New CSS variables in theme.css (20 tokens): --text-bright, --overlay, --status-error*, --status-warning*, --status-success*, --status-info*

New Tailwind aliases in tailwind-config.js: body, bright, fg-muted, fg-dim, field, overlay, status.*

Also extracts the inline Tailwind configs from login.html and setup.html into a shared tailwind-config.js file.

What this enables

After this PR, theming the entire UI is one CSS block:

[data-theme="light"] {
  --bg: #ffffff;
  --text: #1f2937;
  --status-error: #dc2626;
  /* ...etc */
}

No component files need to change.

Scope

  • 4 infrastructure files (theme.css, tailwind-config.js, login.html, setup.html)
  • 92 component files
  • All component changes are mechanical class name swaps
  • 95 files changed, ~870 insertions, ~830 deletions

Verification

  • Test suite: 439 passed
  • Login page visually verified before/after

keaganstokoe and others added 3 commits March 21, 2026 21:21
Introduce CSS variables (--text-bright, --status-*, --overlay) and a
shared tailwind-config.js with Tailwind color aliases backed by those
variables. Extract the inline Tailwind configs from login.html and
setup.html into the shared file.

This layer lets themes override colors in one file instead of touching
every component.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Refactor all component files to use semantic color aliases (text-body,
text-bright, text-fg-muted, text-fg-dim, bg-field, bg-overlay,
text-status-*, bg-status-*-bg, border-status-*-border) instead of raw
Tailwind gray/red/yellow/green/cyan classes.

Theming now requires overriding CSS variables in theme.css only.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@chrysb chrysb force-pushed the feat/semantic-theme-tokens branch from 11de752 to 676c834 Compare March 22, 2026 04:25
@chrysb
Copy link
Copy Markdown
Owner

chrysb commented Mar 22, 2026

Courtesy maintainer follow-up: I rebased this branch onto current main, resolved the conflicts, and pushed the updated branch back to keaganstokoe:feat/semantic-theme-tokens. I also added the missing bundled Tailwind config alignment so semantic classes like text-status-error-muted, text-body, and bg-field are generated in tailwind.generated.css on the current build pipeline, plus a small AGENTS.md note to steer future UI work toward the semantic token layer.

@chrysb
Copy link
Copy Markdown
Owner

chrysb commented Mar 22, 2026

Thanks for the thoughtful theming work here - this is a really nice direction for the UI, and I appreciate the care you put into it.

Copy link
Copy Markdown
Owner

@chrysb chrysb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. Thanks again for the thoughtful theming work and for making the UI token layer reusable.

@chrysb chrysb merged commit dfb6eeb into chrysb:main Mar 22, 2026
1 check passed
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.

2 participants