Shadows and glows

shadow and glow are translucent overlays. Each emits a pigment (black for a shadow, white for a glow) with an opacity Glaze solves so that, once the browser composites it over bg, the surface lands exactly intensity tones darker (shadow) or lighter (glow), scaled by the object when you name one. The step is the same on every surface and in every scheme where the surface has room for it: light, mid, dark, and chromatic.

import { glaze } from '@tenphi/glaze';

const theme = glaze(280, 80);

theme.colors({
  surface: { tone: 97 },
  card: { tone: 100 },
  accent: { tone: 45 },

  // Object-aware drop shadow: `fg` is the element casting it.
  'card-shadow': {
    type: 'shadow',
    bg: 'surface',
    fg: 'card',
    intensity: 8,
  },

  // No `fg`: an exact shade, for state layers and scrims.
  'surface-hover': { type: 'shadow', bg: 'surface', intensity: 5 },
  'accent-pressed': { type: 'shadow', bg: 'accent', intensity: [8, 14] },

  // The mirror: dark-mode elevation, edge highlights, lightening states.
  'accent-highlight': { type: 'glow', bg: 'accent', intensity: 4 },
});

This sample resolves without warnings. In dark high contrast the auto surface sits at tone 3, so card-shadow and surface-hover can’t darken it by their full step and pin to black there. Light high contrast has room for both, so Glaze doesn’t warn. See Unreachable steps.

Every field is listed in Color definitions; this page explains how the overlays behave.

intensity is a step on tone, the WCAG-shaped axis Glaze uses everywhere (see Tone and OKHST). For neutrals a tone step is a fixed WCAG ratio, so 6 tones is about 1.20:1 wherever it lands, and the same number reads the same on any surface. APCA cannot express steps this small, so overlays are always measured in tone.

A fixed opacity cannot do this. Below, each surface carries a shadow with intensity: 6 (top patch) and a black layer at a fixed 8% (bottom patch); the big number is the tone step each one actually paints.

The solved shadow lands 6.0 tones everywhere, at an opacity that climbs as the surface darkens. The fixed layer darkens white by almost 6 tones and a tone-12 surface by little more than one. Glows mirror this:

Browsers composite source-over on gamma-encoded sRGB: 50% black over white paints #808080, not the #bcbcbc that mixing linear light would give. Glaze models exactly that. The composite’s luminance changes monotonically with opacity, so a bisection finds the opacity that lands the step, on chromatic surfaces too.

The required opacity depends heavily on the surface. A 6-tone shadow needs α 0.081 on white, 0.107 on a tone-50 surface, and 0.477 on a tone-10 surface.

There is no opacity cap: when the step is reachable, it is exact. For a lighter overlay, lower intensity.

The output is the pigment with its solved alpha. Shadows and glows appear in every output method (tokens(), tasty(), css(), json(), and the rest) alongside regular colors. The default pigment is neutral, so the values stay clean:

rgb(0 0 0 / 0.0814)       shadow, 6 tones on white
oklch(1 0 0 / 0.0953)     glow, 6 tones on a tone-50 surface

The alpha is only meaningful over the surface it was solved for. Paint the token on top of bg (as a box-shadow color, a state-layer background, or a pseudo-element over the surface).

A shadow darkens in light and dark schemes; a glow lightens in both. Neither flips when the scheme does. Pick the type for the effect you want in each scheme: for example, shadow for light-mode cards and glow for dark-mode elevation. When one component needs a darkening layer in light mode and a lightening one in dark mode, emit both tokens and wire each in the scheme it belongs to. Both still resolve in all four schemes, so each one warns where its surface has no room in your light or dark scheme, even if you don’t use it there (Unreachable steps).

bg and fg are read per scheme, so the solved opacity adapts on its own as the surface moves in dark and high contrast. See Light, dark, and high contrast for how surfaces move between schemes.

fg is the object casting the shadow or emitting the glow, such as the card. It scales the step the way bounce light does. With fg, the step is intensity × k:

k = max(0, 1 + β · d · (t_bg − t_fg) / 100)

t_bg and t_fg are the tones of the surface and the object, d is +1 for a shadow and −1 for a glow, and β is tuning.objectInfluence (0.5 by default).

• An object at the surface’s own tone gives exactly intensity, and so does omitting fg.
• A darker object deepens its shadow; a lighter one softens it.
• For a glow it is the other way round: a lighter object glows stronger.
• k never drops below 0 and tops out at 1 + β (a black object casting a shadow on a white surface). objectInfluence: 0 removes fg’s effect on the step (k = 1); fg still feeds hueBleed.

Each card below casts a hard-edged shadow (offset, no blur) or emits a solid glow ring, both with intensity: 8 and fg pointed at the card:

The same numbers as a table:

Point fg at the element that casts the shadow, never at text: fg is the object, not a contrast reference. Like bg, it must not be another shadow or glow.

Without fg, a shadow or glow is an exact shade or tint of its surface: the right tool for hover and pressed states, which need the same visible change on every fill.

import { glaze } from '@tenphi/glaze';

const theme = glaze(280, 80);

theme.colors({
  surface: { tone: 100, saturation: 0.1 },
  'surface-hover': {
    type: 'shadow',
    bg: 'surface',
    intensity: 4,
  },
  'surface-pressed': {
    type: 'shadow',
    bg: 'surface',
    intensity: [8, 12],
  },
  'accent-surface': { tone: 52, mode: 'fixed' },
  'accent-surface-hover': {
    type: 'shadow',
    bg: 'accent-surface',
    intensity: 4,
  },
  'accent-surface-pressed': {
    type: 'shadow',
    bg: 'accent-surface',
    intensity: [8, 12],
  },
  'accent-surface-highlight': {
    type: 'glow',
    bg: 'accent-surface',
    intensity: 5,
  },
  'inverse-surface': {
    tone: 18,
    saturation: 0.2,
    mode: 'fixed',
  },
  'inverse-surface-hover': {
    type: 'glow',
    bg: 'inverse-surface',
    intensity: 4,
  },
  'inverse-surface-pressed': {
    type: 'glow',
    bg: 'inverse-surface',
    intensity: [8, 12],
  },
});

The accent fill uses mode: 'fixed', so it stays a mid tone in every scheme and its layers land the same steps everywhere. The dark fill uses glows, so its states lighten it. The neutral surface follows the scheme: in dark high contrast it becomes black, and a shadow has nothing left to darken, so surface-hover and surface-pressed stay fully transparent (the figure shows what they reached). They fit light high contrast, so they don’t warn; see Unreachable steps. A glow on this surface fails the other way: it can’t lighten the white surface of the light schemes, and warns in light. No overlay fits a surface that spans the whole tone range. For a state that darkens in light schemes and lightens in dark ones, use a regular color relative to the surface, such as { base: 'surface', tone: '-4' }, which flips with the scheme.

For elevation in light schemes, define one shadow ladder with bg on the page and fg on the card. Equal intensity steps read as evenly spaced on every surface. Use high-contrast pairs for shadows that should deepen in high contrast.

import { glaze } from '@tenphi/glaze';

const theme = glaze(280, 80);

theme.colors({
  surface: { tone: 100, saturation: 0.1 },
  card: { base: 'surface', tone: '-3', saturation: 0.15 },
  'shadow-sm': {
    type: 'shadow',
    bg: 'surface',
    fg: 'card',
    intensity: 3,
  },
  'shadow-md': {
    type: 'shadow',
    bg: 'surface',
    fg: 'card',
    intensity: [6, 9],
  },
  'shadow-lg': {
    type: 'shadow',
    bg: 'surface',
    fg: 'card',
    intensity: [9, 14],
  },
});

A blurred box-shadow fades out from the token’s color, so the step is the darkest the shadow gets, right at the card’s edge. In dark schemes the page sits near black and a dark card shadow has little room: the solved opacity climbs, and in dark high contrast the page is black, so all three shadows stay fully transparent and warn. For elevation in dark schemes, use glows on a surface with room in every scheme, as in the next section.

Glows are the mirror for dark-mode elevation and edge highlights: each level lifts the surface a fixed number of tones. A glow resolves in all four schemes, so it needs room above its surface in each of them. This ladder sits on a light-gray surface, so the same tokens also lift cards toward white in the light scheme.

import { glaze } from '@tenphi/glaze';

const theme = glaze(280, 80);

theme.colors({
  surface: { tone: 92, saturation: 0.1 },
  'elevation-1': { type: 'glow', bg: 'surface', intensity: 3 },
  'elevation-2': { type: 'glow', bg: 'surface', intensity: 5 },
  'elevation-3': { type: 'glow', bg: 'surface', intensity: 7 },
});

A glow on a white light-mode surface has nothing to lighten in SDR, so Glaze warns, even if you only use the token in dark mode. On a tone-100 surface it leaves the glow transparent. A white written as '#ffffff' parses a hair below tone 100, so its glow pins to opaque white instead, which paints the same over it. Give glows a surface with room in every scheme, like the tone-92 surface here.

The pigment is pure black or pure white by default, so the surface keeps its own hue under the overlay and the output stays neutral. A pigment tinted in the surface’s hue (Josh Comeau’s shadow advice) is opt-in through tuning:

• reach sets where the pigment sits: the fraction of the way from the surface’s tone to black (shadow) or white (glow). 1 is pure black or white, the most reach; lower values let a tint show at the cost of reach.
• tint is the pigment’s saturation, in the surface’s hue. It shows only with reach below 1, since pure black and white have no hue. A neutral surface has no hue to give, so there the tint takes the object’s hue when hueBleed is above 0, and the pigment stays neutral otherwise.
• hueBleed pulls the pigment’s hue from the surface’s hue toward the object’s (fg). It needs fg, a tint, and reach below 1 to show.
• objectInfluence is the β in object influence.

theme.colors({
  'shadow-tinted': {
    type: 'shadow',
    bg: 'surface',
    intensity: 8,
    tuning: { tint: 0.3, reach: 0.85 },
  },
});

glaze.configure({
  shadowTuning: { objectInfluence: 0.4 },
  glowTuning: { objectInfluence: 0.6 },
});

shadowTuning and glowTuning set the tuning globally (or per theme or token through the config override); a per-color tuning merges over them field by field. Both take these LightingTuning fields; defaults are in Color definitions and Configuration.

The step is exact in every column. On light and mid surfaces a tint barely changes the composite; on dark surfaces it costs reach and opacity. On the figure’s tone-12 surface, black reaches about 12 tones and needs α 0.545 for the 8-tone shadow; the tint: 0.3, reach: 0.85 pigment reaches about 10 tones and needs α 0.706.

Every surface has limited room: a shadow cannot go below black, and a glow cannot go above white. When the step is out of reach (a glow on white, a deep shadow on near-black), Glaze pins the overlay to the pigment’s strongest composite (full opacity, or fully transparent when the pigment cannot move the surface at all) and emits a deduplicated console.warn. A 6-tone glow on a tone-100 auto surface logs:

glaze: glow "surface-highlight" cannot reach a 6.0-tone step in light
  scheme (reached 0.0 at full strength).
Lower the intensity, move the surface away from white, or raise a
  tuned-down `reach`.

Every shadow and glow resolves in all four schemes on every resolve, whatever modes you emit and wherever you use the token, so the warning fires even for a scheme you never show. Not using a token in a scheme only keeps the pinned value off the screen.

To fix it, lower intensity, or give the overlay a surface with room in every scheme. A tuned-down reach also costs room; raise it back toward 1. Otherwise, expect the warning.

Your tone windows place the surfaces of the light and dark schemes. Two things move them further on their own:

• High contrast bypasses the windows, so a page that is white in light mode becomes black in dark high contrast. A tone-97 page sits at tone 3 there, which leaves room for less than 3 tones.
• A manual contrast level widens the windows toward the full range, and the dark page nears black faster than an interpolated intensity fades. On the default windows, the dark page sits at tone 9.25 at level 0 and about 3.15 at level 50, so intensity: [8, 0] asks for 4 tones there.

No intensity fits every level and both high-contrast schemes, because one high-contrast entry serves a white page in light and a black one in dark. So in these passes the step still pins to the pigment’s strongest composite, but Glaze warns only when it is out of reach in light and dark alike: then the step itself is too big for its surface. When the other scheme has room, the pin is quiet. In the passes your windows place (contrastLevel 'auto' or 0, not high contrast), every shortfall warns as above.

At level 100 the light / dark passes are the high-contrast ones and pair up the same way.

On a display that can show brighter than white, a glow can also go past white: see HDR glows.

intensity accepts a [normal, highContrast] pair, like other numeric fields:

theme.colors({
  'card-shadow': {
    type: 'shadow',
    bg: 'surface',
    fg: 'card',
    intensity: [8, 14],
  },
});

With a manual contrast level, the pair is interpolated like every other pair. See high-contrast pairs and the contrast level. A step the level or high contrast puts out of reach pins quietly unless it is out of reach in light and dark alike; see When Glaze moves the surface.

For one fixed-alpha color with no opacity solve, such as a modal scrim, set opacity on a regular color:

theme.colors({
  scrim: { tone: 0, saturation: 0, mode: 'static', opacity: 0.5 },
});
// scrim → 'oklch(0 0 0 / 0.5)' in every scheme

opacity is applied after the color resolves, so its tone still adapts like any regular color. Without mode: 'static', tone: 0 is lifted by the light tone window and inverted into a light overlay in dark mode. A fixed alpha gives a different step on every surface (an 8% black layer darkens white by about 6 tones and a tone-10 surface by about 1), which is what shadows and glows exist to avoid. For a translucent color with a contrast floor, use a transparent mix.

glaze.shadow() and glaze.glow() compute an overlay without a theme. bg and fg accept any color value Glaze parses (hex, rgb(), okhsl(), value objects, …):

const shade = glaze.shadow({ bg: '#ffffff', intensity: 6 });
// → { h: 0, s: 0, t: 0, alpha: 0.0814… }

glaze.format(shade, 'rgb');
// → 'rgb(0 0 0 / 0.0814)'

const lift = glaze.glow({ bg: '#1e1e22', fg: '#3a3a44', intensity: 4 });

Both accept an optional tuning that merges over the global shadowTuning / glowTuning.

The full input table is in Utilities.

In Glaze 2, intensity went through a curve in OKHSL lightness, so the same number darkened white, mid, and dark surfaces by very different amounts, and fg was a contrast reference that gave a white card on a light page almost no shadow. 3.0 makes intensity an exact tone step, makes fg the object, and adds glow. Upgrade steps are in 3.0 — shadows and glows.