Scope: core (any frontend with theming / dark mode)
Context
A hex literal in a styled-component is a decision that bypasses the design
system: it won’t flip in dark mode, won’t update when the palette evolves, and
encodes what color instead of what it means. Dark-mode parity dies one
hardcoded #fff at a time.
Decision
Semantic colors come from theme tokens, never hex literals. Components
say theme.colors.surface / incomeFg / dangerFg — meaning, not value.
The theme object (src/styles/theme.ts) is the single source of truth,
mirroring the app’s design-system skill
(0015-design-system-as-single-visual-source).
Dark mode is a token swap, not a component concern.darkTheme overrides
the palette; components are written once. A surface that only looks right in
one mode is a bug.
Status colors are semantic pairs (incomeFg/incomeBg, dangerFg, warningFg, …) that adapt per mode — green-means-income is a token, not a
literal.
Transient props use the $ prefix ($active, $variant) so style-only
props never leak to the DOM.
Tolerated literals: values genuinely identical across modes and owned by the
brand (e.g. Expenses’ primary violet gradient) — rare, deliberate, commented.
Theme-aware tints derive from tokens (e.g. color-mix(in oklab, …) over
token colors), not from new hardcoded shades.
Consequences
Palette evolution and dark-mode fixes are theme edits, not component sweeps.
A hex literal in review is an immediate, objective smell.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
// Only this file may name a hex value.const ramp = { cyan400: '#2ed3cf', void800: '#08080b', ice200: '#e7eff8', /* … */ };export const darkTheme = { colors: { bg: ramp.void800, accent: ramp.cyan400, borderAccent: `color-mix(in oklab, ${ramp.cyan400} 42%, transparent)`, // … },};// Typed as the dark theme so the two modes cannot drift apart: a token added to// one is a compile error until it exists in the other.export const lightTheme: typeof darkTheme = { /* same shape, light values */ };
Typing lightTheme as typeof darkTheme is what turns the convention into a
guarantee — forget a token in one mode and the build fails rather than the page
half-working in light.
What the discipline bought, concretely.allsensis.com shows Expenses in its own
violet design system inside a bounded card, while the site chrome stays ion-cyan. That is
a nested ThemeProvider plus an adapter carrying the product’s values in this repo’s
token shape — and not one component changed to make it happen:
StoryBlock, TextLink and LinkRow render violet in that subtree and cyan everywhere
else on the same page, because none of them names a colour. A single hex literal in any
one of them would have broken it.
One sharp edge: CSS custom properties do not follow React context. A color-mix()
texture defined at :root from the site theme keeps painting in site colours inside the
card, so the card republishes those variables locally.