The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
description: >- The CSS token system behind every theme: how tokens are defined, how Tailwind uses them and how to write components that follow it. icon: palette
Theming and design tokens
You can re-skin OpenHuman at runtime. CSS variables (the "tokens") drive colors and fonts, so a theme is a set of values for those variables. This page is the contributor reference for the token system.
How it works
Tokens:
app/src/styles/tokens.cssdefines every themeable color as a space-separated RGB channel triple (for example--surface: 255 255 255;), plus font-role variables (--font-title/heading/body/mono/serif). The light palette lives in:rootand the dark palette in:root.dark.Tailwind wiring: the app runs Tailwind v4, so there is no
tailwind.config.js. The@themeblock inapp/src/index.cssexposes each token as a utility color (--color-surface: rgb(var(--surface));and so on). Tailwind's opacity modifiers then handlebg-surface/50andbg-primary-500/10with no extra work. This only works because tokens are RGB triples. A hex string cannot be combined with an opacity modifier this way.Runtime application:
app/src/providers/ThemeProvider.tsxresolves the activeThemeand writes its overrides as inline--tokenand--font-<role>variables on<html>. It toggles.darkfromtheme.isDark. Variables a theme does not override fall back to thetokens.cssdefaults. Variables left over from a previous theme are removed on switch.State:
app/src/store/themeSlice.tsholdsactiveThemeIdandcustomThemes. Built-in presets live inapp/src/lib/theme/presets.ts. Users edit themes in Settings > Theme Studio (app/src/components/settings/panels/ThemeStudioPanel.tsx).
Token taxonomy
| Group | Tokens | Tailwind utilities |
|---|---|---|
| Surfaces | surface, surface-canvas, surface-muted, surface-subtle, surface-strong, surface-hover, surface-overlay |
bg-surface, bg-surface-muted, ... |
| Text | content, content-secondary, content-muted, content-faint, content-inverted |
text-content, text-content-muted, ... |
| Borders | line, line-strong, line-subtle |
border-line, border-line-strong, ... |
| Accents | primary-*, sage-*, amber-*, coral-* (shades 50 to 950) |
bg-primary-500, text-coral-600, ... (backed by variables, themeable) |
| Fonts | font-title, font-heading, font-body, font-mono, font-serif |
font-title, font-heading, font-body, ... |
The legacy --cmd-* and --color-* variable sets are thin aliases over these tokens. Do not add new colors there.
Authoring components
- Use semantic utilities (
bg-surface,text-content,border-line) for neutral surfaces, text and borders instead ofbg-white dark:bg-neutral-900. You rarely needdark:variants, because the token flips for you. - Use the accent palettes (
primary,sage,amber,coral) for semantic color. They are themeable with no extra work. - Avoid hardcoded hex in
classNameor inlinestyle. It bypasses theming.
Color as identity: the four-ramp ceiling
Some lookup tables answer "which thing is this?" with a color. Examples are a skill category, an event-log domain, a notification provider and a catalogue source. Stock Tailwind ramps keep creeping back into these tables, because a table with nine rows wants nine hues and the app ships four.
There are exactly four themeable ramps: primary, sage, amber and coral. Everything else in Tailwind's default palette (emerald, violet, sky, teal, indigo, cyan, rose, pink, purple and more) resolves to a fixed oklch value that ignores the active theme. A table built on those hues looks fine in the default skin and falls apart in every other one.
The rule
Map a stock ramp to its themeable equivalent at the same shade step:
redtocoral,greenandemeraldtosage,orangetoamber,bluetoprimary.bg-emerald-50 text-emerald-700becomesbg-sage-50 text-sage-700.Hues with no equivalent do not get one.
violet,teal,sky,cyan,indigo,pinkandpurpleare not "nearly primary" or "nearly sage". Do not invent a fifth ramp, do not duplicate an existing one under a new name, and do not reach for--accent-lavenderand similar. Those are fixed hexes, not ramps.When a table needs more than four distinct hues, send the surplus rows to the neutral pair the table already defines (
bg-surface-subtle text-content-secondary, or whatever its "unknown" or "other" row uses). Never let two rows share a ramp. Two domains that render identically destroy the distinction the table exists to show, which is worse than rendering one of them in neutral.Decide which rows keep a hue by which distinction a reader acts on. The badge usually prints its own label, so color is a scanning aid, not the information. Spend the four ramps on the readings that change what someone does, and let the rest go neutral. Keep the meaning honest:
coralreads as failure, so an ordinary row painted coral makes routine state look broken. Leaving a ramp unassigned is fine.
Worked examples in the tree:
| Table | Rows | Kept a hue | Why |
|---|---|---|---|
skills/skillIcons.tsx CATEGORY_META |
9 | Built-in (primary), Productivity (sage), Social (coral), Tools & Automation (amber) |
Channels, Chat and Platform share the neutral tone of All / Other |
skills/SkillsExplorerTab.tsx SOURCE_COLORS |
6 | built-in (sage), optional (primary) |
The four remote catalogues print their own name; provenance tier is the distinction that matters |
skills/SkillsExplorerTab.tsx FORMAT_MAP |
5 rows, 3 tones | Hermes family (primary), ClawHub family (sage), legacy (amber) |
Three tones fit under the ceiling, so nothing is lost |
settings/panels/EventLogPanel.tsx DOMAIN_BADGE_COLORS |
11 | tool (primary), agent (sage), approval (amber) |
Who acted, and what waits on a human. Coral stays unassigned, because no domain means failure |
notifications/NotificationCard.tsx provider badge |
6 | none | The importance badge in the same row already spends coral/amber/sage on high/medium/low; a coral provider would read as a failed notification |
Brand tints are a separate question
A few plates use a third party's brand color, not an app hue: Telegram's #249CD8, Discord's #5865F2 and iMessage's #34C759 in skills/skillIcons.tsx. Flattening them to bg-surface-subtle would erase them into the generic badge beside them, so they stay as hex on purpose. Giving them a themeable home means adding brand tokens, which is a product decision, not a cleanup. The same goes for the provider badges in NotificationCard.tsx: reaching for a stock ramp is not the fix.
Do not repaint a primitive's variant
<Button variant="primary" className="bg-violet-500"> is the same bug. The variant already paints the accent ramp, and the override freezes the color and breaks the hover, focus and disabled states. Drop the override and retint the surface around the button instead.
The migration codemod
scripts/theme-codemod/ collapses audited light and dark: Tailwind pairings into the semantic utilities. It is idempotent and runs as a dry run by default:
node scripts/theme-codemod/migrate.mjs # dry-run + report
node scripts/theme-codemod/migrate.mjs --write # apply
node scripts/theme-codemod/migrate.mjs --selftest # fixture assertions
It only rewrites adjacent pairs and never touches opacity-suffixed utilities or test files. The mapping table is scripts/theme-codemod/map.mjs.