color-mix() can produce a tint. The real decision is whether the resulting color represents a governed design decision, a reusable reference, a generated delivery artifact, or behavior that should remain live in the browser.
Semantic tokens name intent. For a web consumer, CSS custom properties and color-mix() can deliver that intent. Trouble starts when the delivery expression quietly replaces the upstream decision. A button hover color that began as a 12% mix of the action color and black can later be mistaken for a cross-platform role, even though another platform cannot execute that formula and nobody has checked the mixture on every surface that consumes it.
| Authored semantic token | Alias | Build-time transformation | Runtime color-mix() | |
|---|---|---|---|---|
| Semantic authority | Owns an approved role or exception | Points to an existing governed role | Implements a declared derivation during generation | Implements a live browser relationship |
| Named reuse | Use when several consumers share intent | Use when another stable name or mapping is needed | Use when generated outputs need the same derived value | Use when the formula is local to named web consumers |
| Cross-platform need | Best fit for portable decisions | Portable if every target resolves the reference | Suitable when each platform receives a concrete output | Web-specific unless another platform separately implements and verifies it |
| Runtime customization | Values may still be remapped by theme | Follows its referenced value | Requires regeneration after an input changes | Recomputes when custom-property inputs or scope change |
| Regeneration | Source change regenerates exports | Reference remapping regenerates or resolves downstream | Required whenever source, transform, or output format changes | Usually unnecessary for input changes, but CSS changes still ship normally |
| Verification burden | Check source, mappings, and representative consumers | Check reference resolution and unintended fan-out | Check transform version, emitted value, and each target | Check browser support, scope, computed output, background, state, and fallback |
| Choose it when | Exact intent matters beyond one formula or consumer | No new color decision is being made | A reproducible derivation must reach non-CSS targets | The live relationship is intentional and bounded to the browser |
Use this routing sequence. First, ask whether the color has independent meaning. Then check whether another governed color already expresses that meaning and whether non-web targets need the same result. Finally, decide whether runtime customization is worth the extra inspection burden. If the color has independent meaning, start with an authored semantic role. If only the name changes, use an alias. When the derivation must travel as a concrete value, transform it during the build. Keep color-mix() at runtime only when recomputation is part of the requirement.
Draft concepts are not implementation authority
The captured Design Tokens Color Module is useful for vocabulary around color representation and interpolation, but it identifies itself as a preview draft and says not to implement or cite it as authoritative. For CSS behavior, use browser documentation and tests from the target environments.
Understand the mechanics that change the decision
color-mix() combines two colors in a declared interpolation space. That space is part of the formula, not an invisible implementation detail. The same inputs and percentages can produce different intermediate colors in sRGB and OKLCH. Neither space is universally correct. Choose one for a named consumer, compare the result with the recorded intent, and retain it only when the applied result passes the checks that matter for that consumer.
- Percentages: each percentage belongs to its adjacent color. If one percentage is omitted, it becomes the remainder to 100%. MDN also documents normalization when the specified total exceeds 100% and an alpha multiplier when the total is below 100%. Write both percentages when an audit shouldn't depend on an implied remainder.
- Alpha: mixing with transparent or using percentages that total less than 100% can change opacity. The visible result then depends on what's behind the element, so record the composited background as well as the computed color.
- Theme scope: custom properties follow the cascade. A formula declared once may receive different inputs under light, dark, application, or subtree scopes. Record the scope that supplied each input.
- Background dependence: a foreground mixture has no standalone contrast result. Measure it against the background actually applied in that mode and state, including overlays or translucent surfaces.
- Missing or invalid inputs: an unresolved var() can invalidate the consuming declaration at computed-value time. Give required inputs a valid fallback inside var(), or keep the derivation behind a boundary where every input is guaranteed.
- Fallback behavior: put an approved static declaration before the enhanced declaration, then place the mixture in @supports. The static value remains the progressive-enhancement boundary for implementations that don't support the tested syntax.
A related-looking color can still fail its job
color-mix() doesn't guarantee contrast, focus visibility, or semantic suitability. A formula that works for a filled button on one surface may fail for text, an outline, a disabled control, or the same component in dark mode.
Run a self-contained light and dark fixture
The fixture below uses invented neutral values, so its provenance is clear. It compares sRGB and OKLCH mixtures from the same sources, places them on two representative surfaces, and gives the enhanced declarations static fallbacks. This is an implementation fixture, not a completed browser benchmark.
<section class="fixture theme-light" data-theme="light">
<h2>Light mode</h2>
<div class="surface surface-page">
<button class="test-button mix-oklch">Save with OKLCH mix</button>
<button class="test-button mix-srgb">Save with sRGB mix</button>
</div>
<div class="surface surface-raised">
<button class="test-button mix-oklch">Save on raised surface</button>
</div>
</section>
<section class="fixture theme-dark" data-theme="dark">
<h2>Dark mode</h2>
<div class="surface surface-page">
<button class="test-button mix-oklch">Save with OKLCH mix</button>
<button class="test-button mix-srgb">Save with sRGB mix</button>
</div>
<div class="surface surface-raised">
<button class="test-button mix-oklch">Save on raised surface</button>
</div>
</section>:root {
/* Governed fixture inputs, revision fixture-2026-11-22 */
--fixture-action-light: #2457d6;
--fixture-on-action-light: #ffffff;
--fixture-page-light: #f7f8fb;
--fixture-raised-light: #ffffff;
--fixture-action-dark: #8eafff;
--fixture-on-action-dark: #10162a;
--fixture-page-dark: #111522;
--fixture-raised-dark: #1b2132;
}
.theme-light {
--action: var(--fixture-action-light, #2457d6);
--on-action: var(--fixture-on-action-light, #ffffff);
--page: var(--fixture-page-light, #f7f8fb);
--raised: var(--fixture-raised-light, #ffffff);
}
.theme-dark {
--action: var(--fixture-action-dark, #8eafff);
--on-action: var(--fixture-on-action-dark, #10162a);
--page: var(--fixture-page-dark, #111522);
--raised: var(--fixture-raised-dark, #1b2132);
}
.surface-page { background-color: var(--page); }
.surface-raised { background-color: var(--raised); }
.surface { padding: 1rem; }
.test-button {
/* Verified static values must replace these fixture fallbacks in a real system. */
--button-rest: #2457d6;
--button-hover: #1f4aba;
--button-pressed: #193d99;
background-color: var(--button-rest);
color: var(--on-action);
border: 2px solid transparent;
padding: 0.65rem 1rem;
}
.theme-dark .test-button {
--button-rest: #8eafff;
--button-hover: #9cb9ff;
--button-pressed: #abc3ff;
}
@supports (background-color: color-mix(in oklch, red 50%, blue 50%)) {
.mix-oklch {
--button-rest: var(--action);
--button-hover: color-mix(in oklch, var(--action, #2457d6) 88%, black 12%);
--button-pressed: color-mix(in oklch, var(--action, #2457d6) 76%, black 24%);
}
.theme-dark .mix-oklch {
--button-hover: color-mix(in oklch, var(--action, #8eafff) 88%, white 12%);
--button-pressed: color-mix(in oklch, var(--action, #8eafff) 76%, white 24%);
}
}
@supports (background-color: color-mix(in srgb, red 50%, blue 50%)) {
.mix-srgb {
--button-rest: var(--action);
--button-hover: color-mix(in srgb, var(--action, #2457d6) 88%, black 12%);
--button-pressed: color-mix(in srgb, var(--action, #2457d6) 76%, black 24%);
}
.theme-dark .mix-srgb {
--button-hover: color-mix(in srgb, var(--action, #8eafff) 88%, white 12%);
--button-pressed: color-mix(in srgb, var(--action, #8eafff) 76%, white 24%);
}
}
.test-button:hover { background-color: var(--button-hover); }
.test-button:active { background-color: var(--button-pressed); }
.test-button:focus-visible {
outline: 3px solid var(--focus-ring, #b42318);
outline-offset: 3px;
}In developer tools, select the button and inspect the applied background-color in its rest, :hover, and :active states. Reading --button-hover alone may show the authored formula rather than the resolved color that background-color uses. Capture the computed foreground and background for every inspected pair. Repeat the check on the page and raised surfaces because identical component CSS doesn't imply identical composited or contrast behavior.
The fixture deliberately doesn't declare either interpolation space the winner. Its job is to make the difference observable under controlled inputs. If both spaces match the recorded intent, choose the one the system owner can explain and maintain. If neither does, author the state color explicitly instead of adjusting percentages until one screenshot looks acceptable.
Start from named color roles
Before deriving states, make sure the source distinguishes roles such as background, foreground, primary, border, and focus ring in each mode. The semantic-token guide explains that upstream layer.
Route each component state separately
A shared percentage is a candidate relationship, not a state policy. Hover, pressed, disabled, and focus communicate different things. Classify each one separately, even when the first implementation happens to use similar formulas.
| Candidate route | Accept derivation when | Author an exception when | Failure condition | |
|---|---|---|---|---|
| Hover background | Runtime mixture from the default action background | Hover is a subtle emphasis change, the formula is intentionally shared, and every named surface is checked | The brand specifies an exact hover color, a surface needs a different response, or another platform must match exactly | The change is imperceptible, reverses the intended direction, or fails a required foreground/background check |
| Pressed background | Runtime mixture or authored semantic state | The stronger change remains suitable in both modes and communicates activation clearly | Pressed has distinct product meaning, requires an exact value, or the shared formula collapses near the gamut or background | Pressed cannot be distinguished from rest or hover under the stated inspection conditions |
| Disabled foreground and background | Usually authored paired roles; derivation only with a narrow contract | The disabled treatment is decorative, remains identifiable, and does not hide required content or state information | Opacity, layering, or different surfaces make the pair unpredictable; policy requires a stable disabled treatment | Text or control boundaries become unreadable, or the state relies on color alone where another cue is required |
| Focus indicator | Authored semantic focus role, with component CSS owning geometry | One shared ring color and geometry have been verified around the named component on every representative adjacent color | Different surroundings require an alternate ring, gap, or two-color treatment | The indicator is obscured, clipped, indistinguishable, or loses the required visual change on any tested background |
| Mode-specific variant | Theme alias, authored mode value, or scoped runtime mixture | The mode changes the inputs while preserving the same recorded relationship and consumer intent | Light and dark modes need different mixing partners, percentages, roles, or exact values | One formula is accepted from one mode's screenshot and merely assumed to work in the other |
Focus needs separate treatment. The reusable focus color may be a semantic token, while outline width, offset, selector behavior, clipping, and component geometry remain CSS or component responsibilities. Deriving a ring from the button fill is risky because the ring must remain visible against both the control and the surrounding page.
Test content that exposes the pair
Use real labels such as "Save changes," "Delete workspace," and "Continue" instead of an empty swatch. Inspect the text, icon, border, fill, and focus indicator that the component actually renders.
Measure the applied pairs, not the formula
Accessibility acceptance belongs to the applied foreground and background pair, not to color-mix() itself. Record the requirement for the element under review, then measure that exact pair with the project's chosen method. Text, graphical controls, state changes, and focus indicators can have different inspection criteria. Don't turn one familiar text ratio into a universal threshold for every case.
| Role and test content | Inspect | Pass evidence | Fail when | |
|---|---|---|---|---|
| Rest text: "Save changes" | Computed text color against the computed button background in light and dark modes | The recorded pair and measured result meet the applicable text requirement | The named browser, mode, surface, and measurement method are captured | Either mode misses the recorded requirement or the captured background is not the one rendered |
| Hover and pressed fill | Computed state fill, foreground, and visible difference from adjacent states | Each state matches its expected intent and required pair measurement | Both interpolation candidates are evaluated only for the named consumer and surfaces | The state is unsuitable on either representative surface or cannot be distinguished as required |
| Disabled label and boundary | Label, icon, fill, border, surrounding surface, and non-color state cues | Disabled status remains understandable and required content remains legible | Any alpha composition is recorded against the background that is actually rendered | Opacity or composition produces an unrecorded pair, or the state depends on an unchecked background |
| Focus indicator | Indicator against adjacent component and page pixels, plus clipping and geometry | The complete indicator remains visible for keyboard focus in each tested mode and surface | The ring color, width, offset, selector, and surrounding colors are included in the evidence | Any edge is clipped, obscured, or fails the project's applicable focus criterion |
| Fallback rendering | The same component states with the @supports enhancement unavailable | Recorded static values render and meet the same applicable acceptance checks | The fallback browser condition and applied static values are captured separately | A state disappears, uses an unintended initial value, or differs without an approved exception |
Keep expectations and observations separate. "Hover should be visibly stronger than rest without changing the action's meaning" is an expectation. A computed color, browser version, measurement, and screenshot reference are observations. If no run has occurred, mark those fields pending. Don't fill them with an assumed hex value or a result copied from another browser.
Copy the source-to-consumer acceptance record
One record should let someone reproduce the decision and identify what needs to be retested. Use one row for every named state, mode, and relevant background. A record for "primary button" without those dimensions hides the exact cases most likely to differ.
Color derivation acceptance record
Decision ID: COLOR-MIX-[number]
Governed source: [repository, token file, or approved kit]
Governed source revision: [commit, release, or immutable identifier]
Source tokens: [exact input token names and resolved source values]
Delivery artifact: [generated CSS file and artifact version]
Project mapping: [source token -> project custom property]
Named consumer: [component, variant, and product surface]
Mode: [light | dark | other named mode]
State: [rest | hover | pressed | disabled | focus]
Foreground role: [token and applied property]
Background role: [token and applied property]
Surrounding background: [token/value or not applicable with reason]
Expected intent: [observable relationship written before inspection]
Serialized formula: [exact color-mix() expression]
Interpolation space: [for example, srgb or oklch]
Percentages: [both explicit percentages]
Alpha or transparency: [none, value, or compositing condition]
Theme scope: [selector or subtree that supplies inputs]
Static fallback: [exact declaration and source]
Browser and version: [to record]
Operating system or rendering condition: [to record if relevant]
Computed foreground: [to record, pending until inspected]
Computed background: [to record, pending until inspected]
Computed surrounding background: [to record if relevant]
Measured result and method: [to record, pending until measured]
State and focus observation: [to record, pending until inspected]
Evidence reference: [screenshot, test output, or issue]
Owner: [role or person responsible for disposition]
Disposition: [accept | author exception | change formula | reject | pending]
Reason: [tie the disposition to the expected intent and evidence]
Retest trigger: [source revision, formula, browser support, theme, component CSS, background, or acceptance-rule change]The chain matters because every layer proves something different. A source revision identifies the governed inputs. Serialized CSS proves what was delivered. Project mapping shows which variables the consumer uses. Computed styles show what one environment resolved. Measurement and visual inspection show whether that result met the recorded requirement. None of these facts can substitute for the others.
Keep the fallback inside the acceptance boundary
Progressive enhancement is credible only when someone reviews the static path too. Put the approved static value first, override it inside a matching @supports rule, and test both paths. If an input custom property might be absent, provide a deliberate var() fallback or don't enable the formula in that scope. Otherwise, the browser may accept color-mix() syntax while the applied declaration still becomes invalid because an input can't resolve.
- 1
Freeze the source and named consumer
Record the source revision, semantic roles, component variant, modes, states, and representative surfaces before tuning a formula.
- 2
Choose one candidate relationship
Write the interpolation space and both percentages explicitly. State why runtime recomputation is needed instead of an authored value, alias, or build output.
- 3
Inspect the applied properties
Capture computed foreground, background, border, or outline values from the element in every required state. Don't treat the custom-property source text as the computed result.
- 4
Measure and inspect each pair
Apply the requirement appropriate to the content or control. Check state distinction, focus visibility, clipping, alpha composition, and background dependence separately.
- 5
Exercise the static path
Disable or bypass the enhancement boundary in the fixture and repeat the relevant checks against the static declarations.
- 6
Record a disposition and trigger
Accept, replace with an authored exception, revise, reject, or leave pending. Name the changes that invalidate the evidence and require a retest.
Where Identity Forge ends and application verification begins
Identity Forge supplies governed design-kit artifacts, including semantic light and dark color tokens and DTCG, CSS, and Tailwind exports. These artifacts can provide the authoritative inputs and mappings for a consuming project. A downstream team still owns any runtime color-mix() formulas it adds, along with the component and theme scopes that consume them, the static fallback, and verification in the rendered application. Don't treat Identity Forge as having generated or validated those downstream mixtures.
Classify one component before keeping any formula
Take one component with visible rest, hover, pressed, disabled, and focus states. Route each color to an authored semantic token, alias, build-time transformation, or runtime mixture. Run the component on its page and raised backgrounds in both modes. Inspect the applied computed properties, then complete one acceptance record for every relevant state. Keep only the derivations whose recorded observations match the intent. Turn the rest into explicit exceptions or leave them unresolved for the owner.
Sources
- color-mix() CSS function - MDN Web Docs - Mozilla: Documents color-mix() syntax, interpolation methods, percentage handling, transparency behavior, and the function's computed color result.
- Design Tokens Color Module 2025.10: Describes proposed color-token and interpolation concepts while explicitly identifying the captured document as a preview draft that must not be treated as implementation authority.
- Leveraging modern CSS color features in your design system: Connects design tokens and CSS custom properties with modern color features, themes, and fallback considerations.
- CSS color-mix() Playground - Mix Colors Across Color Spaces: Demonstrates that the same source colors can produce visibly different mixtures when the interpolation space or ratio changes.
- Theming | Kongponents - Kong Inc.: Shows a production theming architecture in which CSS custom properties can be overridden at application or subtree scope and changed at runtime.
- Color Tokens - Design Glossary - Atmos.style: Explains the distinction between primitive values, semantic roles, cross-platform design tokens, and browser-specific CSS custom properties.
- Semantic color tokens explained: Explains Identity Forge's role-based light and dark color-token model and the need to consider foreground and background roles together.
- Identity Forge: Describes Identity Forge's design-kit pipeline and its delivery of implementation-oriented tokens and related design-system artifacts.