--- language: "en" title: "Mixes and transparency" canonical: "https://glaze.tenphi.me/mixes/" source: "docs/mixes.mdx" version: "3.1.0" index: true --- # Mixes and transparency A mix color blends a `base` color toward a `target` color by `value`, from `0` (pure base) to `100` (pure target). An **opaque** mix produces a solid color; a **transparent** mix produces the target with an opacity, for the browser to composite over the base. Both read `base` and `target` per scheme, so they adapt to light, dark, and high contrast automatically. ```ts import { glaze } from '@tenphi/glaze'; const theme = glaze(280, 80); theme.colors({ surface: { tone: 95 }, accent: { tone: 30 }, // A solid tint: 30% of the way from surface to accent. 'accent-tint': { type: 'mix', base: 'surface', target: 'accent', value: 30, }, // A translucent wash: accent at 8% opacity, composited over surface. 'accent-hover': { type: 'mix', base: 'surface', target: 'accent', value: 8, blend: 'transparent', }, }); ``` Every field is listed in [Color definitions](/reference/color-definitions/#mixcolordef). ## Opaque mix An opaque mix (the default, `blend: 'opaque'`) interpolates between the resolved base and target and emits a solid color with alpha 1. `value: 0` is the base, `value: 100` is the target. Because base and target are resolved for each scheme first, the mix follows them: a tint of the accent over the surface in light mode is a tint of the dark-mode accent over the dark-mode surface in dark mode. ### Blend space `space` picks where an opaque mix interpolates: | `space` | Behavior | Best for | | ------------------- | ------------------------------------------------------------------------------------------ | ------------------------ | | `'okhsl'` (default) | Perceptually uniform OKHSL interpolation: hue, saturation, and lightness each move evenly. | Design token derivation. | | `'srgb'` | Linear-light sRGB channel interpolation, like CSS `color-mix(in srgb-linear, …)`. | Physical light mixing. | The same two colors, mixed at every tenth of the way in each space: ### Achromatic colors When one side of an `okhsl` mix has a saturation of zero (a color defined with `saturation: 0`, such as a pure white, black, or gray), its hue carries no information, so the mix takes the hue of the color that has saturation. This matches the "missing component" behavior of CSS `color-mix()`: a mix from such a white toward an accent stays in the accent's hue the whole way instead of sweeping through other hues. Only zero counts, along with float noise up to 1e-6. A gray given as a value, such as `'#f5f5f5'` or `rgb(250 250 250)`, parses with a saturation of zero, and so does an `srgb` mix that lands on a gray. A white or black that keeps real saturation, such as `{ tone: 100 }` in a saturated theme, still carries its hue, and a mix toward an accent of another hue sweeps between the two. A mix between two zero-saturation colors stays gray in either space; the spaces differ only in how lightness is spread along the ramp (see black toward white above). ## Transparent mix With `blend: 'transparent'`, the output is the **target** color (its resolved hue, saturation, and tone, in the mix's gamut when their [`pastel` flags](#pastel-mixes) differ) with `alpha = value / 100`. Nothing is blended in Glaze; the browser composites it over whatever is underneath, which should be the `base`. ```ts theme.colors({ surface: { tone: 95 }, black: { tone: 0, saturation: 0 }, hover: { type: 'mix', base: 'surface', target: 'black', value: 8, blend: 'transparent', }, }); // hover → the resolved `black` with alpha 0.08 ``` The target is resolved like any color first. Here `black` uses the default `mode: 'auto'`, so it inverts to a near-white in dark schemes and the same `hover` lightens the dark surface instead of darkening it. `space` is ignored for transparent mixes. Browsers composite `source-over` on gamma-encoded sRGB: 50% black over white paints `#808080`, not the `#bcbcbc` linear light would give. Glaze's contrast solver for transparent mixes models exactly that, so a solved opacity renders at the contrast it was solved for. A transparent mix keeps the opacity you author. That makes it the right tool for a brand-colored wash, but it does not land the same visible step on every surface. For an overlay that does, use a [`shadow` or `glow`](/shadows-and-glows/), whose opacity is solved per surface. ## Contrast on mixes Mixes take the same `contrast` field as regular colors, with a WCAG ratio or preset, or an APCA target (see [Contrast solving](/contrast/)). The floor is measured between the mix and its `base`. The solver keeps your `value` when it already meets the floor; otherwise it moves the mix ratio (opaque) or the opacity (transparent) toward the target until it does, staying as close to your `value` as it can. * Both `value` and `contrast` accept `[normal, highContrast]` pairs, and `value` follows a manual contrast level like other pairs. Contrast presets escalate in high contrast as they do for regular colors ([high contrast](/contrast/#high-contrast)). * For APCA floors, `role` sets the polarity of the mix against its `base`, exactly as on a regular color ([roles](/contrast/#roles-and-apca-polarity)). * When even the pure target cannot meet the floor, the mix settles at the pure target for any `value` below 100. * A `value` of 100 is the pure target already. Glaze keeps it whenever it clears the floor, even inside the solver's safety margin. When it misses, there is no room above, so the mix falls back to `value: 0`: the base itself, and a transparent mix vanishes. That includes a high-contrast entry of 100. Keep `value` below 100 when you set a floor. An unmet floor warns once per scheme, like it does for a regular color. Below, `accent-fill` meets AA in light at about 4.55:1. In dark the pure target reaches only 4.24:1, so the mix settles there. High contrast escalates the floor to 7:1, which the pure target misses (5.72:1 in light high contrast, 5.20:1 in dark), so the high-contrast entry of 100 falls back to the surface: ```ts const theme = glaze(280, 80); theme.colors({ surface: { tone: 95 }, accent: { tone: 40 }, 'accent-fill': { type: 'mix', base: 'surface', target: 'accent', value: [80, 100], contrast: 'AA', }, }); ``` ```text glaze: mix "accent-fill" cannot meet WCAG 7.00 against its base in lightContrast scheme (got 1.00). Even the pure target falls short; try lowering the contrast target or mixing toward a color further from the base. ``` The `darkContrast` warning is the same with its scheme name, and the dark-scheme one names `WCAG 4.50` and `(got 4.24)` instead. The fix is a target further from the base or a lower floor. Here `contrast: ['AA', 'AA']` holds high contrast at 4.5:1, which the pure target clears, so its entry of 100 is kept. See [Warnings](/reference/configuration/#mix-contrast-unmet). ## Mix chaining A mix can use another mix as its `base` or `target`: A mix **cannot** reference a `shadow` or `glow` color, as `base` or as `target`; Glaze throws when the theme resolves. The same restriction applies to a regular color's `base`. Other translucent colors are accepted but lose their alpha. A transparent mix or a color with `opacity`, used as a mix's `base` or `target` (or as a shadow's `bg`), counts as its opaque color: a mix toward a 10% accent wash comes out the same as a mix toward the accent. Chain off opaque colors. ## Pastel mixes A mix's `pastel` sets the gamut of the color it emits. Like any color, a mix takes the theme's `pastel` unless it sets its own. Its base and target keep their own flags, and when a flag differs from the mix's, the mix reads that color in its own gamut through the color it paints: * A standard mix holds every pastel color, so `value: 0` paints the base and `value: 100` the target exactly. * A pastel mix caps a vivid color at the pastel limit, keeping its hue and lightness. A pastel mix toward a vivid brand color ends at the brand with its saturation capped. * A transparent mix's overlay is the target in the mix's gamut, and an `srgb` mix interpolates the colors as painted, then caps the result. ```ts const theme = glaze(280, 80, { pastel: true }); theme.colors({ surface: { tone: 95 }, brand: { tone: 40, pastel: false }, // pastel like the theme: at value 100 it would be the brand, capped 'brand-soft': { type: 'mix', base: 'surface', target: 'brand', value: 60 }, // standard: the brand in full at value 100 'brand-tint': { type: 'mix', base: 'surface', target: 'brand', value: 60, pastel: false, }, }); ``` The contrast solver measures the color the mix paints, so a floor holds on screen. When a pastel mix misses its floor because the cap took the target's saturation, the [warning](/reference/configuration/#mix-contrast-unmet) says so; `pastel: false` on the mix paints the target in full. ## Mix, shadow, glow, or opacity? | You want | Use | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | The same visible darkening or lightening on any surface: state layers, elevation, drop shadows | [`shadow` / `glow`](/shadows-and-glows/) | | A solid color part of the way from one color to another | Opaque mix | | A translucent color over a known base, such as a brand-colored wash | Transparent mix | | A translucent color with a contrast floor against its base | Transparent mix with `contrast` | | One fixed alpha everywhere, such as a 50% scrim | A regular color with [`opacity`](/shadows-and-glows/#fixed-opacity) | Shadows and glows solve opacity for a tone step, transparent mixes keep (or solve, with `contrast`) an opacity against their base, and `opacity` is never solved.