@tenphi/glaze 0.0.0-snapshot.0fcd6cf → 0.0.0-snapshot.12fd135

package/docs/exporting.mdx

@@ -76,8 +76,8 @@ A few options cut across the shapes:
   `$value` objects, not CSS strings, so they ignore `format`. Use `colorSpace`
   instead: `'srgb'` (the default) or `'oklch'`.
 - **HDR.** `modes: { hdr: true }` (`css({ hdr: true })` for `css()`) adds the
-  values of [HDR glows](./shadows-and-glows.mdx#hdr-glows) next to the SDR
-  ones. It is off by default; see [HDR output](#hdr-output).
+  values of [HDR glows](./hdr.mdx) next to the SDR ones. It is off by
+  default; see [Output is opt-in](./hdr.mdx#output-is-opt-in).
 
 Here is one theme and the CSS custom properties `theme.css()` emits for it.
 Switch to the Output tab to see the declarations, wrapped the way the
@@ -626,222 +626,6 @@ a standalone color's `css()`. The full rules, including which colors stay
 inline, are in the
 [Output formats](./reference/output.md#hue-channel-splitting-splithue) reference.
 
-## HDR output
-
-[HDR glows](./shadows-and-glows.mdx#hdr-glows) carry a second value for
-displays that can show brighter than white. Every export leaves it out until
-you turn on `modes.hdr`. Then each format adds it next to the SDR value it
-already emits, for the schemes the other `modes` include. The examples below
-use this theme:
-
-```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 },
-});
-
-// For every export:
-glaze.configure({ modes: { hdr: true } });
-// Or per call:
-theme.tokens({ modes: { hdr: true } });
-theme.css({ hdr: true });
-```
-
-`surface-glow` has an HDR value in the light schemes only; on the dark
-surface its step stays below white. `near-glow` has one in all four. HDR
-values are always `color(srgb-linear R G B)`, whatever `format` you pass, and
-stay literal under `splitHue`. Palettes apply prefixes, the `primary` alias,
-and collision filtering to them like any other entry. `glaze.color()` tokens
-are never glows, so the HDR options don't change their output.
-
-No browser reliably paints these values past white yet
-([Browsers and native apps](./shadows-and-glows.mdx#browsers-and-native-apps)).
-Safari, and Chrome outside layers that hold HDR images, match
-`dynamic-range: high` on HDR-capable displays and clamp the value, so a
-neutral HDR glow paints opaque white there. That matches SDR for `near-glow`,
-which is already opaque white, but `surface-glow` is transparent in SDR, so
-its clamped value covers anything drawn between the surface and the glow.
-Wire the CSS, Tasty, and Tailwind tiers only for glows used as fills, edge
-highlights, or `box-shadow` colors
-([Fills, not overlays](./shadows-and-glows.mdx#fills-not-overlays)). JSON and
-DTCG feed native apps, which draw HDR today.
-
-### CSS blocks
-
-`css()` has no `modes`, so it 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-linear 1.4631 1.4631 1.4631);
---near-glow-color: color(srgb-linear 1.2494 1.2494 1.2494);
-
-/* hdr.dark */
---surface-glow-color: oklch(1 0 0 / 0.1237);
---near-glow-color: color(srgb-linear 1.2494 1.2494 1.2494);
-```
-
-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-linear 1.4631 1.4631 1.4631)',
-//   '@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-linear 1.4631 1.4631 1.4631);
-    --color-near-glow: color(srgb-linear 1.2494 1.2494 1.2494);
-  }
-}
-
-@media (dynamic-range: high) {
-  .dark {
-    --color-surface-glow: oklch(1 0 0 / 0.1237);
-    --color-near-glow: color(srgb-linear 1.2494 1.2494 1.2494);
-  }
-}
-```
-
-### JSON and tokens
-
-`json()` adds a sparse `<scheme>Hdr` key after each scheme that has an HDR
-value. `tokens()` adds a dense `<scheme>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-linear 1.4631 1.4631 1.4631)',
-//   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-linear 1.2494 1.2494 1.2494)',
-// }
-```
-
-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.
-
-### DTCG and native apps
-
-`dtcg()` and `dtcgResolver()` keep `$value` SDR, since the DTCG color format
-has no HDR space and its components stop at 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-linear",
-          "components": [1.463058, 1.463058, 1.463058]
-        }
-      }
-    }
-  }
-}
-```
-
-- `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` as linear sRGB. 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.
-
-Native platforms take one of the two forms:
-
-- **UIKit and AppKit** (iOS and macOS 26):
-  `UIColor(red:green:blue:alpha:exposure:)`, or its `NSColor` twin, with
-  `base.components` and `exposure`.
-- **SwiftUI:** `Color(.sRGB, red:green:blue:)` from `base.components`, then
-  `.exposureAdjust(exposure)`.
-- **Android:** `Color.pack(r, g, b, 1f, space)` from `value.components`, with
-  `ColorSpace.get(ColorSpace.Named.LINEAR_EXTENDED_SRGB)` as the space, in a
-  window set to `COLOR_MODE_HDR`.
-
 ## Next steps
 
 - [Migration and upgrading](./migration.md): move an existing color system to