Get started

CSS color-mix() for design tokens: derive values without losing authority

Use color-mix() for browser-side derivation, not as automatic design-token authority. Keep a mixture only when its relationship is intentional, its scope is web-specific, and its applied result has been checked for the named component, state, mode, and background.

Updated November 22, 2026

Choose authority before choosing syntax

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 tokenAliasBuild-time transformationRuntime color-mix()
Semantic authorityOwns an approved role or exceptionPoints to an existing governed roleImplements a declared derivation during generationImplements a live browser relationship
Named reuseUse when several consumers share intentUse when another stable name or mapping is neededUse when generated outputs need the same derived valueUse when the formula is local to named web consumers
Cross-platform needBest fit for portable decisionsPortable if every target resolves the referenceSuitable when each platform receives a concrete outputWeb-specific unless another platform separately implements and verifies it
Runtime customizationValues may still be remapped by themeFollows its referenced valueRequires regeneration after an input changesRecomputes when custom-property inputs or scope change
RegenerationSource change regenerates exportsReference remapping regenerates or resolves downstreamRequired whenever source, transform, or output format changesUsually unnecessary for input changes, but CSS changes still ship normally
Verification burdenCheck source, mappings, and representative consumersCheck reference resolution and unintended fan-outCheck transform version, emitted value, and each targetCheck browser support, scope, computed output, background, state, and fallback
Choose it whenExact intent matters beyond one formula or consumerNo new color decision is being madeA reproducible derivation must reach non-CSS targetsThe live relationship is intentional and bounded to the browser
Route the color according to who should control it and where it must work.

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>
Matching markup for two interpolation spaces, two modes, and representative page and raised surfaces.
: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;
}
CSS Color 5 color-mix() syntax as documented by MDN, with explicit ratios, separate theme inputs, and static declarations before @supports enhancements.

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 routeAccept derivation whenAuthor an exception whenFailure condition
Hover backgroundRuntime mixture from the default action backgroundHover is a subtle emphasis change, the formula is intentionally shared, and every named surface is checkedThe brand specifies an exact hover color, a surface needs a different response, or another platform must match exactlyThe change is imperceptible, reverses the intended direction, or fails a required foreground/background check
Pressed backgroundRuntime mixture or authored semantic stateThe stronger change remains suitable in both modes and communicates activation clearlyPressed has distinct product meaning, requires an exact value, or the shared formula collapses near the gamut or backgroundPressed cannot be distinguished from rest or hover under the stated inspection conditions
Disabled foreground and backgroundUsually authored paired roles; derivation only with a narrow contractThe disabled treatment is decorative, remains identifiable, and does not hide required content or state informationOpacity, layering, or different surfaces make the pair unpredictable; policy requires a stable disabled treatmentText or control boundaries become unreadable, or the state relies on color alone where another cue is required
Focus indicatorAuthored semantic focus role, with component CSS owning geometryOne shared ring color and geometry have been verified around the named component on every representative adjacent colorDifferent surroundings require an alternate ring, gap, or two-color treatmentThe indicator is obscured, clipped, indistinguishable, or loses the required visual change on any tested background
Mode-specific variantTheme alias, authored mode value, or scoped runtime mixtureThe mode changes the inputs while preserving the same recorded relationship and consumer intentLight and dark modes need different mixing partners, percentages, roles, or exact valuesOne formula is accepted from one mode's screenshot and merely assumed to work in the other
Example routing matrix for a primary button. These are decision rules, not universal percentages.

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 contentInspectPass evidenceFail when
Rest text: "Save changes"Computed text color against the computed button background in light and dark modesThe recorded pair and measured result meet the applicable text requirementThe named browser, mode, surface, and measurement method are capturedEither mode misses the recorded requirement or the captured background is not the one rendered
Hover and pressed fillComputed state fill, foreground, and visible difference from adjacent statesEach state matches its expected intent and required pair measurementBoth interpolation candidates are evaluated only for the named consumer and surfacesThe state is unsuitable on either representative surface or cannot be distinguished as required
Disabled label and boundaryLabel, icon, fill, border, surrounding surface, and non-color state cuesDisabled status remains understandable and required content remains legibleAny alpha composition is recorded against the background that is actually renderedOpacity or composition produces an unrecorded pair, or the state depends on an unchecked background
Focus indicatorIndicator against adjacent component and page pixels, plus clipping and geometryThe complete indicator remains visible for keyboard focus in each tested mode and surfaceThe ring color, width, offset, selector, and surrounding colors are included in the evidenceAny edge is clipped, obscured, or fails the project's applicable focus criterion
Fallback renderingThe same component states with the @supports enhancement unavailableRecorded static values render and meet the same applicable acceptance checksThe fallback browser condition and applied static values are captured separatelyA state disappears, uses an unintended initial value, or differs without an approved exception
A bounded inspection matrix for the button fixture.

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]
Copyable record. Observation fields remain pending until someone runs the fixture.

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. 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. 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. 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. 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. 5

    Exercise the static path

    Disable or bypass the enhancement boundary in the fixture and repeat the relevant checks against the static declarations.

  6. 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