# Theming Systems > Use when building design tokens, adding dark mode or multi-brand theming, wiring a theme switcher, or supporting forced-colors, density, or RTL. - Skill: `yogvidwankhede/theming-systems` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add yogvidwankhede/theming-systems` - Raw SKILL.md: https://api.skillmd.com/api/skills/yogvidwankhede/theming-systems/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: yogvidwankhede (https://skillmd.com/u/yogvidwankhede) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yogvidwankhede/theming-systems --- # Theming Systems A theme is not a palette. It is a **mapping from role to value**, plus the machinery that swaps one mapping for another without the user seeing the seam. Get the mapping wrong and adding a theme means editing components. Get the machinery wrong and every cold load shows the wrong theme for 200ms. ## 1. Three layers ```css --grey-50: oklch(0.97 0.004 260); /* primitive: what it is. Theme-invariant. */ --brand-600: oklch(0.58 0.16 255); --surface: var(--grey-50); /* semantic: what it means. One set per theme. */ --accent: var(--brand-600); --btn-primary-bg: var(--accent); /* component: where it is used. The override seam. */ ``` Primitives are a vocabulary and never appear in a component. The semantic layer *is* the theme — the only layer a theme file rewrites, and the only level at which a contract like "`--fg` clears 4.5:1 on `--surface` in every theme" is statable. The component layer earns its keep for one reason: **it is the only place a one-off can live without a hardcoded value or a polluted global vocabulary.** When the pricing page's primary button must use the success hue, without it you either hardcode `#1f8a4c` or add `--accent-alt` globally — a global name for a local problem. Create component tokens when a second consumer or an override appears, not before, and alias semantic tokens from them, never primitives. A flat set of renamed hex values is the primitive layer with the other two missing, and will not survive dark mode. ## 2. How custom properties resolve, and the trap Custom properties are inherited and substituted at computed-value time, so a `var()` resolves against the element that *declares* it, not the one that *uses* it: ```css :root { --accent: var(--brand-600); --btn-bg: var(--accent); } [data-brand="acme"] { --accent: var(--acme-600); } /* button does not change */ ``` `--btn-bg` computed on `:root`, where `--accent` was still the default, and the subtree inherits that already-substituted value. **A token that must vary per subtree has to be referenced below the override point, not resolved above it** — declare component tokens on the component's own selector, `.btn { background: var(--btn-bg, var(--accent)) }`, or redeclare every derived token in the block that overrides its input. Two further mechanics. A `var()` with no value invalidates the *whole declaration* at computed-value time, so the property resolves to `unset` — for `color`, inherited rather than ignored, which can hand an element a foreground identical to its background. And an `@property` registration with `inherits: false` can never be a theme token. ## 3. Switching without a flash Resolution order is fixed: **explicit stored choice, then system preference, then product default.** Anything else means a user who chose light gets dark at sunset. It must run in a **parser-blocking inline `