--- title: HDR glows description: Glows past SDR white for HDR displays — when Glaze adds an HDR value, how to opt in, and where it can be shown today. --- import Example from '../docs-site/components/Example.astro'; import GlowsPastWhite from '../docs-site/components/shadows-and-glows/GlowsPastWhite.tsx'; import { Preview } from '@tenphi/cookbook/components'; import { hdrHaloPreview } from '../docs-site/components/shadows-and-glows/hdr-preview.ts'; export const hdrTheme = { hue: 280, saturation: 80, config: { glowTuning: { headroom: 1 } }, colors: { surface: { tone: 100 }, 'surface-glow': { type: 'glow', bg: 'surface', intensity: 12 }, near: { tone: 95, saturation: 0, mode: 'static' }, 'near-glow': { type: 'glow', bg: 'near', intensity: 12 }, inverse: { tone: 12, saturation: 0, mode: 'static' }, 'inverse-glow': { type: 'glow', bg: 'inverse', intensity: 12 }, }, }; export const haloTheme = { hue: 280, saturation: 80, config: { glowTuning: { headroom: 1 } }, colors: { page: { tone: 92, saturation: 0.1 }, card: { base: 'page', tone: '+6', saturation: 0.1 }, 'card-glow': { type: 'glow', bg: 'page', fg: 'card', intensity: 20 }, }, }; export const haloPreview = hdrHaloPreview(haloTheme, { page: 'page', card: 'card', glow: 'card-glow', blur: 40, spread: 4, }); A [glow](./shadows-and-glows.mdx) can't go past white in SDR, but an HDR display can show brighter than white. Set `glowTuning.headroom`, and a glow whose step would pass white also resolves an HDR value: an opaque exposure of what SDR already paints there. The SDR value doesn't change, and exporters add the HDR one only when you [opt in](#output-is-opt-in). Everything outside this page is SDR; skip it unless you target HDR displays. ## When a glow gets an HDR value [Tone runs on past 100](./okhst.mdx#tone-above-100) on the same curve: one stop above SDR white (`Y` 2) is tone 121.98, two stops (`Y` 4) tone 144.34, and 12 tones past white is the same `Y + 0.05` ratio as a 12-tone step anywhere. WCAG and APCA end at white, so Glaze makes no contrast claim above 100. A glow can't be a `bg`, `fg`, `base`, or mix input, so an HDR value never reaches the contrast solver. A glow gets an HDR value when three things hold: its `headroom` is above 0, its target tone (the surface's luminance tone plus `intensity × k`) passes 100, and SDR is pinned at its brightest. That means the pigment at full opacity, or a white surface (tone 100) at opacity 0, since no pigment can lift it. Below white nothing changes, dark-scheme glows included. A pigment that can't lift a non-white surface at all (`reach: 0` on a gray surface, say) paints nothing in SDR, gets no HDR value, and keeps the SDR warning. On a chromatic surface a `reach: 0` pigment, a gray at the surface's tone, can be slightly brighter than the surface: it then pins at full opacity and, past white, gets an HDR value like any pinned pigment. The resolved variant gains `hdr: { h, s, t, exposure }`. The base (`h`, `s`, `t`) is the opaque color SDR paints, with a standard (never pastel) OKHSL saturation. The HDR value is that base's linear light times `2^exposure`, the gain that lands the target tone exactly; `variant.t` itself stays at most 1. The value is opaque on purpose: it stays exact whichever way it is composited, and it maps one to one onto native exposure APIs. ## Headroom `headroom` counts stops above SDR white, the doublings of its luminance. It defaults to 0 (no HDR anywhere) and must be a finite number ≥ 0, or Glaze throws. Set it globally (`glaze.configure({ glowTuning: { headroom: 1 } })`), in a theme's config override, on one glow's `tuning`, or on `glaze.glow()`. A glow's `tuning` merges over `glowTuning` field by field. A theme's own `glowTuning` replaces the global one whole, and so does a later `glaze.configure({ glowTuning })`, so pass every field you want kept: `glaze.configure({ glowTuning: { objectInfluence: 0.6, headroom: 1 } })`. A `headroom` on a shadow throws: nothing goes below black. Values above 2 clamp to 2. The warning fires once per field and value, and only after the whole input has validated: ```text glaze: glowTuning.headroom 4 is above the 2-stop maximum; using 2. Headroom counts stops (doublings of SDR white's luminance), not a ratio: 1 stop is 2× white, 2 stops 4×. ``` The gain is capped per channel, so no linear channel of the HDR value passes `2^headroom`. On a neutral glow that caps luminance: a 30-tone glow on white with 1 stop of headroom ends at `color(srgb 1.3533 1.3533 1.3533)` (linear 2 per channel), tone 121.98, and warns (below). A saturated base hits the cap on its brightest channel first, so its HDR tone can stay below 100. How much of that a display shows depends on its headroom at the moment, which falls as the user turns brightness up. Past it, most platforms clip the color, which can move a tinted glow toward white, while Apple's platforms tone-map it. A web page can't read the number. Android suggests about 1.5–2× white for interfaces that are mostly SDR, so 1 stop is a sensible ceiling for UI. With headroom, a glow whose target passes white no longer logs the [unreachable-step warning](./shadows-and-glows.mdx#unreachable-steps): its HDR value lands the step. Only the headroom cap can leave such a step short, and that logs its own warning. A 30-tone glow on white with 1 stop of headroom: ```text glaze: glow "surface-flare" cannot reach a 30.0-tone step in light scheme even with 1 stop of headroom (reached 22.0). Lower the intensity or raise `headroom`. ``` At the 2-stop maximum the second sentence reads "Lower the intensity; `headroom` is already at its 2-stop maximum." A glow without an HDR value keeps the SDR warning. ## Worked example Three 12-tone glows: one on a white `auto` surface, one on a light gray, and one on a dark gray. The same numbers in every scheme: | Glow | SDR | HDR | | --- | --- | --- | | `surface-glow`, light and light HC | White at α 0 | 1.1813 per channel (linear 1.4631), 0.549 stops, tone 112 | | `surface-glow`, dark and dark HC | White at α 0.1237 (α 0.1603 in dark HC) | None: the dark surface has room | | `near-glow`, all four | Opaque white, 5 of 12 tones | 1.1026 per channel (linear 1.2494), 0.321 stops, tone 107 | | `inverse-glow`, all four | White at α 0.1155 | None: the target is tone 24 | `near-glow` shows the split: SDR pins it to opaque white 7 tones short, and its HDR value lands those 7. In dark, `surface` sits at tone 9.25 (luminance tone 8.5, so the glow's target is tone 20.5), and `surface-glow` is an ordinary translucent glow there. ## Crossing white A full-reach glow meets SDR at the boundary. On a gray tone-95 surface (like `near`) a 4.9-tone glow is white at α 0.9794 and a 5-tone glow is opaque white, both without an HDR value. At 5.1 tones it adds `color(srgb 1.0014 1.0014 1.0014)`, 0.0046 stops. A glow with `reach` below 1 doesn't meet it. Its pigment sits below white, so it stays short and warns until its target passes 100, then its HDR value lands the whole step at once. A `reach: 0.5` glow on a gray tone-90 surface paints tone 95 for any step from 5 to 10. Past 10, its HDR value jumps straight to tone 100 (0.2315 stops over the pigment). Keep `reach` at 1 on a glow that may cross white. ## Extended sRGB Glaze writes an HDR value as `color(srgb R G B)` with channels past 1: the sRGB curve continued past SDR white, so `1` is white and one stop above it is `1.3533`. `glaze.formatHdr(variant, 'srgb-linear')` writes the same color in linear light (`color(srgb-linear 1.4631 1.4631 1.4631)` for `surface-glow`), and a browser converts either one into the other exactly. The format doesn't follow `format`: CSS clamps `oklch()` lightness at 1, and `rgb()` / `hsl()` can't go past white. That is all an HDR glow needs. Its value is its SDR base made brighter, so it stays inside the sRGB gamut and is measured against SDR white, the way displays and native APIs measure headroom. The `rec2100-pq` and `rec2100-hlg` spaces from the CSS Color HDR draft would add a conversion, to wider primaries and to an HDR transfer curve pinned to an assumed SDR white, with nothing to gain for a color like this, and browsers don't support them yet. The same numbers are what most HDR APIs take as they are: a WebGPU `'srgb'` canvas, Apple's extended sRGB color space, and Android's `EXTENDED_SRGB`. For numbers instead of a string, `hdrToSrgb(variant.hdr)` returns these channels, and `hdrToLinearSrgb(variant.hdr)` the linear ones, for APIs that take linear light. ## Output is opt-in Resolving fills in `variant.hdr` whenever headroom allows. Exporters leave it out until you turn on `modes.hdr`, so every export is byte-identical until then, headroom or not. Turn it on for the export that needs it: ```ts const theme = glaze(280, 80, { glowTuning: { headroom: 1 } }); theme.colors({ surface: { tone: 100 }, 'surface-glow': { type: 'glow', bg: 'surface', intensity: 12 }, near: { tone: 95, saturation: 0, mode: 'static' }, 'near-glow': { type: 'glow', bg: 'near', intensity: 12 }, }); theme.dtcg({ modes: { hdr: true } }); theme.css({ hdr: true }); // css() has no `modes` // Or for every export: glaze.configure({ modes: { hdr: true } }); ``` Each export then adds the HDR value next to the SDR value it already emits, for the schemes the other `modes` include. `surface-glow` has one in the light schemes only; on the dark surface its step stays below white. `near-glow` has one in all four. HDR values stay literal under `splitHue`, palettes treat them like any other entry (prefixes, the `primary` alias, collisions), and `glaze.color()` tokens are never glows, so the HDR options don't change their output. The data exports (DTCG, `json()`, `tokens()`) are what native apps and WebGPU code read. The CSS exports (`css()`, `tasty()`, Tailwind) are experimental: no browser paints them past white yet ([Browsers](#browsers)), and their shape may change once one does. Prefer turning HDR on per call, so a setup that only needs DTCG doesn't add the CSS tier to every stylesheet. ### CSS blocks `css()` takes `hdr` (default: the global `modes.hdr`) and returns four more blocks in `hdr`. Wire each one after the SDR blocks, under the same selector plus `(dynamic-range: high)`: ```ts const css = theme.css({ hdr: true }); const hdr = css.hdr!; const dark = '(prefers-color-scheme: dark)'; const more = '(prefers-contrast: more)'; const high = '(dynamic-range: high)'; const stylesheet = ` :root { ${css.light} } @media ${dark} { :root { ${css.dark} } } @media ${more} { :root { ${css.lightContrast} } } @media ${dark} and ${more} { :root { ${css.darkContrast} } } @media ${high} { :root { ${hdr.light} } } @media ${dark} and ${high} { :root { ${hdr.dark} } } @media ${more} and ${high} { :root { ${hdr.lightContrast} } } @media ${dark} and ${more} and ${high} { :root { ${hdr.darkContrast} } } `; ``` The blocks are dense. Each lists every color that has an HDR value in any scheme, and repeats a color's SDR declaration where its own scheme has none: ```css /* hdr.light */ --surface-glow-color: color(srgb 1.1813 1.1813 1.1813); --near-glow-color: color(srgb 1.1026 1.1026 1.1026); /* hdr.dark */ --surface-glow-color: oklch(1 0 0 / 0.1237); --near-glow-color: color(srgb 1.1026 1.1026 1.1026); ``` On a dark HDR display, both the light and the dark HDR blocks match. The dark one comes later, so its `surface-glow` line puts the dark SDR value back. A block that listed only HDR values would let the light one leak into dark. When no glow passes white, all four blocks are empty strings. ### Tasty keys `tasty()` adds a key under the `states.hdr` alias (default `'@media(dynamic-range: high)'`) right after each SDR key that has an HDR value: ```ts theme.tasty({ modes: { hdr: true } })['#surface-glow']; // → { // '': 'oklch(1 0 0 / 0)', // '@media(dynamic-range: high)': 'color(srgb 1.1813 1.1813 1.1813)', // '@media(prefers-color-scheme: dark)': 'oklch(1 0 0 / 0.1237)', // } ``` Tasty gives later keys priority, so the order is what keeps the light HDR value out of dark: `''`, hdr, dark, dark & hdr, hc, hc & hdr, dark & hc, dark & hc & hdr, with only the keys that exist. Don't sort the keys if you post-process the map. With your own aliases, set `states.hdr` next to `dark` and `highContrast` (for example `'@hdr'`, which emits keys such as `'@dark & @hdr'`) and register it in Tasty like the others. ### Tailwind blocks `tailwind()` appends the same dense blocks after all its SDR blocks, under `hdrSelector` (default `'@media (dynamic-range: high)'`), around `darkSelector` and `highContrastSelector`: ```css /* ...the @theme and .dark blocks, unchanged... */ @media (dynamic-range: high) { :root { --color-surface-glow: color(srgb 1.1813 1.1813 1.1813); --color-near-glow: color(srgb 1.1026 1.1026 1.1026); } } @media (dynamic-range: high) { .dark { --color-surface-glow: oklch(1 0 0 / 0.1237); --color-near-glow: color(srgb 1.1026 1.1026 1.1026); } } ``` ### JSON and tokens `json()` adds a sparse `Hdr` key after each scheme that has an HDR value. `tokens()` adds a dense `Hdr` map after each scheme it emits, always present and possibly empty: ```ts theme.json({ modes: { hdr: true } })['surface-glow']; // → { // light: 'oklch(1 0 0 / 0)', // lightHdr: 'color(srgb 1.1813 1.1813 1.1813)', // dark: 'oklch(1 0 0 / 0.1237)', // } theme.tokens({ modes: { hdr: true } }).darkHdr; // → { // 'surface-glow': 'oklch(1 0 0 / 0.1237)', // 'near-glow': 'color(srgb 1.1026 1.1026 1.1026)', // } ``` A dense map drops into a cascade the way the CSS blocks do; the sparse JSON keys suit code that reads one color at a time. Both carry only the string, whose numbers are the [extended sRGB](#extended-srgb) channels. Apple's exposure initializers take a base and an exposure, which only DTCG carries. ### DTCG `dtcg()` and `dtcgResolver()` keep `$value` SDR: DTCG color components run from 0 to 1. The HDR value goes in `$extensions`, only in the scheme documents that have one. This is `light['surface-glow']`; `dark['surface-glow']` has no `$extensions`: ```json { "$type": "color", "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff", "alpha": 0 }, "$extensions": { "me.tenphi.glaze": { "hdr": { "exposure": 0.548987, "tone": 112, "base": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }, "value": { "colorSpace": "srgb", "components": [1.181265, 1.181265, 1.181265] } } } } } ``` - `base` is the opaque SDR color the exposure applies to: always a DTCG sRGB color with `hex`, whatever `colorSpace` you export, and never pastel. - `exposure` is the gain over `base` in stops. - `value` is `base × 2^exposure` in linear light, written as extended sRGB: the numbers of the CSS string, to 6 decimals. Only its brightest component is guaranteed above 1. - `tone` is the HDR value's tone: past 100 when the headroom covers the step, though a saturated base that the cap stops early can land below. Style Dictionary and Terrazzo keep `$extensions`, but their built-in color transforms expect components from 0 to 1, so read the extension with a transform of your own. [Native apps](#native-apps) maps each field. ## Outside a theme [`glaze.glow()`](./shadows-and-glows.mdx#outside-a-theme) takes `headroom` in its `tuning` and returns `hdr` when its step passes white: ```ts const flare = glaze.glow({ bg: '#ffffff', intensity: 12, tuning: { headroom: 1 }, }); glaze.formatHdr(flare); // → 'color(srgb 1.1813 1.1813 1.1813)' ``` ## Where it shows ### Browsers No browser paints a CSS color brighter than white yet. The CSS Color 4 spaces, `srgb` included, are SDR by design: values past 1 are valid, but they are fit into SDR when painted. A neutral HDR value paints white, the same as the SDR value of a glow pinned at opaque white (`near-glow`). A tinted one paints a lighter, less saturated tint, or white. And on a white surface, where SDR is transparent, the HDR value covers what is drawn under it ([Fills, not overlays](#fills-not-overlays)). The planned way past white is the CSS Color HDR draft's `hdr-color()` (also written `color-hdr()` there), which blends an SDR and an HDR color by the display's headroom. No browser implements it and its name isn't settled. `@media (dynamic-range: high)` reports what the device can do, not that HDR is on: Low Power Mode and the brightness setting change that. ### WebGPU A WebGPU canvas can paint past white. Chrome and Edge 129+ show an `rgba16float` canvas configured with `toneMapping: { mode: 'extended' }` brighter than white on an HDR display: on Windows, macOS, ChromeOS, and Android, and on Linux since 144 with Intel Gen12+ GPUs only (not in Android WebView). Safari 26 accepts the option, but whether it paints past white is unconfirmed, so check on the device. Firefox has WebGPU without extended tone mapping, so its canvases stay SDR. The preview below is a card on a tone-92 page, its edges glowing with `card-glow`, an `intensity: 20` glow from the card. In the light scheme the glow's target is tone 113, past white, so its SDR value is opaque white and its HDR value is `color(srgb 1.1972 1.1972 1.1972)` (0.593 stops). CSS draws the halo as a `box-shadow` in the SDR value; its 40px blur fades it from about 58% at the card's edge. On an HDR display with HDR canvases, a WebGPU canvas behind the card draws a matching halo in the HDR value instead, so the edge glows brighter than the white card. The canvas's default `colorSpace`, `'srgb'`, takes extended sRGB, so the channels go in as Glaze writes them: ```ts import { hdrToSrgb } from '@tenphi/glaze'; const { hdr } = theme.resolve().get('card-glow')!.light; const [r, g, b] = hdrToSrgb(hdr!); // 1.1972 per channel ``` Check the mode after `configure()`: where a browser doesn't support HDR canvases, `context.getConfiguration().toneMapping?.mode` isn't `'extended'`, and Chrome 129 and 130 have no `getConfiguration()`. `'extended'` means only that the browser supports HDR canvases, not that the screen shows them, so the preview also checks `(dynamic-range: high)` before it replaces the CSS halo. A page can't read the display's headroom, so keep `headroom` modest. ### Native apps Read the [DTCG export](#dtcg), which carries every field these take. - **Apple** (iOS, iPadOS, macOS, tvOS, visionOS 26): `UIColor(red:green:blue:alpha:exposure:)`, or its `NSColor` twin, with `base.components` and `exposure`, reproduces Glaze's value. In SwiftUI, apply `.exposureAdjust(exposure)` to a `Color(.sRGB, …)` made from `base`. A view shows it brighter than white only once its layer opts in: set `layer.preferredDynamicRange` to `.automatic`, `.constrainedHigh`, or `.high`, since the default `.standard` tone-maps it into SDR. Where the system limits headroom it tone-maps the color, which isn't Glaze's SDR value (often translucent), so keep both tokens and switch yourself. - **Android** (14 and later): set the window's color mode to `COLOR_MODE_HDR`, and on Android 15 its `desiredHdrHeadroom` to the brightest linear channel you draw. `Color.pack(r, g, b, 1f, space)` takes `value.components` as they are, with `ColorSpace.get(ColorSpace.Named.EXTENDED_SRGB)` as the space; in Compose, `Color(r, g, b, 1f, ColorSpaces.ExtendedSrgb)`. Int colors, `` resources, and Compose text colors can't carry HDR. - **Windows:** Direct2D, Win2D, and other FP16 scRGB surfaces take linear light where 1 is 80 nits, not SDR white. Multiply the linear channels (`hdrToLinearSrgb()`, or `value.components` decoded) by the display's SDR white level in nits divided by 80, at run time. - Flutter and React Native: no HDR color path in their own drawing has been verified, so use the SDR value there, or draw the glow in a native view with the Apple or Android APIs above. ## Fills, not overlays Where the HDR value clamps, as it does in CSS today, it paints an opaque color: white, for a neutral glow. That matches SDR wherever SDR is already opaque (`near-glow`). On a tone-100 surface it doesn't: SDR is transparent there, and the clamped value covers anything drawn between the surface and the glow. Use HDR glows for fills (a card's or button's own background), edge highlights, and `box-shadow` colors, never for a state layer drawn over a label. ## Power and accessibility - HDR is an enhancement. The design must work in SDR, and it does: the SDR value is what every other display already shows. - Don't animate or flash HDR values. A pulsing glow past white is a large luminance swing, and HDR flash thresholds now appear in the WCAG 2.3.1 Understanding draft and ITU-R BT.1702-3. - Brighter-than-white pixels cost power, and systems fall back to SDR to save it (iOS Low Power Mode does). Keep headroom low and HDR areas small.