@tenphi/glaze 0.17.0 → 0.19.0

package/docs/api.md

@@ -127,12 +127,12 @@ theme.tokens()
 
 ### `theme.tasty(options?)`
 
-Tasty style-to-state bindings for the [Tasty style system](https://tasty.style/docs). Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+Tasty style-to-state bindings for the [Tasty style system](https://tasty.style/docs). Uses `#name` color token keys and state aliases. By default the dark and high-contrast variants are keyed by media-query states (`'@media(prefers-color-scheme: dark)'`, `'@media(prefers-contrast: more)'`) so tokens work without registering custom states.
 
 ```ts
 theme.tasty()
 // → {
-//   '#surface': { '': 'okhsl(...)', '@dark': 'okhsl(...)' },
+//   '#surface': { '': 'okhsl(...)', '@media(prefers-color-scheme: dark)': 'okhsl(...)' },
 //   ...
 // }
 ```
@@ -143,13 +143,13 @@ theme.tasty()
 |---|---|---|
 | `format` | `'okhsl'` | Output color format. `'okhsl'` and `'okhst'` are supported here (Tasty-only spaces). |
 | `modes` | global config | Which scheme variants to include. |
-| `states.dark` | `'@dark'` (or global config) | State alias for dark mode tokens. |
-| `states.highContrast` | `'@high-contrast'` (or global config) | State alias for high-contrast tokens. |
+| `states.dark` | `'@media(prefers-color-scheme: dark)'` (or global config) | State alias for dark mode tokens. |
+| `states.highContrast` | `'@media(prefers-contrast: more)'` (or global config) | State alias for high-contrast tokens. |
 | `splitHue` | `false` | Emit hue as a separate custom property (`$name-hue` token + `var()` in `oklch` values). Requires `format: 'oklch'` and every color to be pastel. |
 | `name` | `'theme'` | Base name for the theme-level hue var (`$theme-hue` / `--theme-hue`). Palette export auto-derives this from the theme name. |
 | `prefix` | (palette only) | See [Palette](#palette). |
 
-When both `dark` and `highContrast` modes are enabled, dark high-contrast variants are emitted under the combined key `<dark> & <highContrast>` (e.g. `'@dark & @high-contrast'`).
+When both `dark` and `highContrast` modes are enabled, dark high-contrast variants are emitted under the combined key `<dark> & <highContrast>` (e.g. `'@media(prefers-color-scheme: dark) & @media(prefers-contrast: more)'`).
 
 ### `theme.json(options?)`
 
@@ -403,12 +403,29 @@ A bare number or preset means **WCAG**. Use `{ wcag }` / `{ apca }` to pick the
 contrast: 4.5                  // WCAG 4.5
 contrast: 'AAA'                // WCAG 7
 contrast: { wcag: 6 }          // WCAG 6
-contrast: { wcag: [4.5, 7] }   // WCAG 4.5 normal / 7 high-contrast
-contrast: { apca: 60 }         // APCA Lc 60
-contrast: { apca: [45, 60] }   // APCA Lc 45 normal / 60 high-contrast
-contrast: { apca: 'content' }  // APCA preset -> Lc 60
-contrast: { apca: ['content', 'body'] } // Lc 60 normal / 75 high-contrast
-```
+contrast: { wcag: [4.5, 7] }   // WCAG 4.5 normal / 7 high-contrast (explicit)
+contrast: { apca: 60 }         // APCA Lc 60 normal / 75 high-contrast (auto)
+contrast: { apca: [45, 60] }   // APCA Lc 45 normal / 60 high-contrast (explicit)
+contrast: { apca: 'content' }  // APCA preset -> Lc 60 normal / 75 high-contrast (auto)
+contrast: { apca: ['content', 'body'] } // Lc 60 normal / 75 high-contrast (explicit)
+```
+
+**WCAG HC auto-promotion:** a bare WCAG preset (no `[normal, hc]` pair at either
+the outer `contrast` or inner `wcag` level) is automatically promoted to its
+spec-defined "Enhanced" successor in high-contrast mode — `AA` → `AAA` (4.5 → 7)
+and `AA-large` → `AAA-large` (3 → 4.5), per WCAG SC 1.4.3 → 1.4.6. `AAA` and
+`AAA-large` are already the top WCAG tier and are left unchanged; bare numeric
+targets have no successor tier and are also left unchanged. An explicit HC value
+via either pair overrides and skips the promotion.
+
+**APCA Enhanced Level (HC auto-boost):** a bare APCA scalar (no `[normal, hc]`
+pair at either the outer `contrast` or inner `apca` level) is automatically
+boosted by **+15 Lc** in high-contrast mode, the APCA analog of WCAG's
+AAA-over-AA step. On by default; an explicit HC value via either pair
+overrides it and skips the boost. The enhanced target is clamped to 106 Lc.
+For large/bold text (where APCA caps contrast at Lc 90 to avoid glare), pass
+an explicit HC pair to hold that ceiling — see
+[`docs/okhst.md`](okhst.md) §Enhanced Level.
 
 APCA preset keywords (Bronze Simple Mode conformance levels, role-independent):
 `'preferred'` (Lc 90), `'body'` (75), `'content'` (60, ~AA), `'large'` (45, ~3:1),
@@ -1276,8 +1293,8 @@ glaze.configure({
   darkTone: [15, 95],   // [lo, hi]; or { lo, hi, eps } / false to disable clamping
   darkDesaturation: 0.1,
   states: {
-    dark: '@dark',
-    highContrast: '@high-contrast',
+    dark: '@media(prefers-color-scheme: dark)',
+    highContrast: '@media(prefers-contrast: more)',
   },
   modes: {
     dark: true,
@@ -1299,8 +1316,8 @@ A `ToneWindow` is `[lo, hi]` (OKHSL-lightness endpoints, reference eps — the c
 | `lightTone` | `[10, 100]` | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
 | `darkTone` | `[15, 95]` | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
 | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
-| `states.dark` | `'@dark'` | State alias for dark mode tokens (Tasty export). |
-| `states.highContrast` | `'@high-contrast'` | State alias for HC tokens. |
+| `states.dark` | `'@media(prefers-color-scheme: dark)'` | State alias for dark mode tokens (Tasty export). Defaults to a media query so tokens react to the OS preference without registering custom states. |
+| `states.highContrast` | `'@media(prefers-contrast: more)'` | State alias for HC tokens (Tasty export). |
 | `modes.dark` | `true` | Include dark variants in exports. |
 | `modes.highContrast` | `false` | Include HC variants. |
 | `shadowTuning` | `undefined` | Default tuning for all shadow colors. Per-color tuning merges field-by-field. |
@@ -1465,10 +1482,12 @@ import {
 |---|---|
 | `findToneForContrast(opts)` | Binary-search for the tone (0–1) that meets a contrast floor (WCAG or APCA) against a base color. Returns `{ tone, contrast, met, branch, flipped? }`. |
 | `findValueForMixContrast(opts)` | Same, but searches for a mix `value` (0–1) that meets a contrast floor between a base and a target. |
-| `resolveContrastForMode(spec, isHC)` | Resolves a `ContrastSpec` to `{ metric: 'wcag' \| 'apca', target }` for the requested mode (picks the normal or HC entry of any pair). |
+| `resolveContrastForMode(spec, isHC, polarity?, outerExplicitHC?)` | Resolves a `ContrastSpec` to `{ metric: 'wcag' \| 'apca', target }` for the requested mode (picks the normal or HC entry of any pair). In HC, applies the metric's auto-enhancement unless `outerExplicitHC` is set or the inner metric pair carries an explicit HC value: APCA +15 Lc (clamped to 106); WCAG AA → AAA / AA-large → AAA-large (AAA-family and bare numbers unchanged). |
 | `resolveMinContrast(value)` | Resolves a `MinContrast` (WCAG preset or number) to a numeric ratio. |
 | `apcaContrast(yText, yBg)` | APCA Lc magnitude (0–106) for two relative luminances. |
 
+Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Level delta), `APCA_MAX_LC` (`106`).
+
 `findToneForContrast` options:
 
 | Option | Default | Description |

package/docs/migration.md

@@ -106,7 +106,7 @@ Glaze emits the same resolved colors in six shapes. Pick one based on your rende
 
 | Method | Output shape | Use it for |
 |---|---|---|
-| `palette.tasty(options?)` | `{ '#name': { '': value, '@dark': value, '@hc': value } }` | The [Tasty](https://tasty.style/docs) style system. Single object, state aliases keyed inside each token. |
+| `palette.tasty(options?)` | `{ '#name': { '': value, '@media(prefers-color-scheme: dark)': value, '@media(prefers-contrast: more)': value } }` | The [Tasty](https://tasty.style/docs) style system. Single object, state aliases keyed inside each token. |
 | `palette.tokens(options?)` | `{ light: { name: value }, dark: { name: value }, ... }` | Most CSS-in-JS systems. Per-variant flat maps, easy to feed into a `:root { ... }` selector via your framework's globals. |
 | `palette.css(options?)` | `{ light: '--name-color: rgb(...);', dark: '...', ... }` | Framework-free CSS / static stylesheets. Variant-grouped CSS custom property strings ready to wrap in `:root` and `prefers-color-scheme` queries. |
 | `palette.json(options?)` | `{ themeName: { name: { light, dark, ... } } }` | Tooling, JSON pipelines. |
@@ -136,11 +136,14 @@ useGlobalStyles('body', PALETTE_TOKENS);
 tastyStatic('body', PALETTE_TOKENS);
 ```
 
-For the `@dark` / `@hc` state aliases to do anything, your app needs to register what those states *mean*:
+By default the dark / high-contrast variants are keyed by media-query states — `'@media(prefers-color-scheme: dark)'` and `'@media(prefers-contrast: more)'` — so the tokens react to the OS preference out of the box, with no extra Tasty setup.
+
+If you'd rather drive the schemes from custom aliases (e.g. a manual toggle that also falls back to the OS preference), set your own [`glaze.configure({ states })`](api.md#configuration) and register what those states *mean*:
 
 ```ts
 import { setGlobalPredefinedStates } from '@tenphi/tasty';
 
+// glaze.configure({ states: { dark: '@dark', highContrast: '@hc' } });
 setGlobalPredefinedStates({
   '@dark':
     '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',

package/docs/okhst.md

@@ -239,6 +239,55 @@ contrast: { apca: 'content' }          // Lc 60
 contrast: { apca: ['content', 'body'] } // HC pair: 60 normal, 75 high-contrast
 ```
 
+#### Enhanced Level (high-contrast auto-boost)
+
+When an APCA target is given as a **bare scalar** (no `[normal, hc]` pair at
+either the outer `contrast` level or the inner `apca` level), Glaze
+automatically applies the APCA-W3 "Enhanced Level" delta — **+15 Lc** — in
+high-contrast mode, analogous to WCAG's AAA-over-AA step. This is on by
+default; provide an explicit HC value via either pair to override it.
+
+```ts
+contrast: { apca: 60 }          // Lc 60 normal, Lc 75 high-contrast (auto)
+contrast: { apca: 'content' }   // Lc 60 normal, Lc 75 high-contrast (auto)
+contrast: { apca: [60, 90] }    // Lc 60 normal, Lc 90 high-contrast (explicit)
+contrast: [{ apca: 60 }, { apca: 90 }] // outer pair: explicit HC, no boost
+contrast: { apca: 'preferred' } // Lc 90 normal, Lc 105 high-contrast (auto)
+contrast: { apca: 100 }         // Lc 100 normal, Lc 106 high-contrast (clamped)
+```
+
+The enhanced target is clamped to `APCA_MAX_LC` (106).
+
+> **Large-text glare caveat.** APCA-W3 also defines Lc 90 as a *maximum* for
+> very large/bold text (>36px bold) and large areas of color, to prevent
+> excessive glare. The +15 HC boost can therefore push a high baseline (e.g.
+> `preferred` Lc 90 → 105) past that glare ceiling. This is intentional for
+> small/standard text in HC (low-vision readability trumps glare, and small
+> fonts have no APCA maximum), but if your HC tokens serve large/bold text,
+> pass an explicit HC pair (`{ apca: [90, 90] }`) to hold the glare ceiling.
+> Glaze does not model font size, so it can't enforce the large-text cap
+> automatically.
+
+#### WCAG HC auto-promotion
+
+A bare WCAG preset (no `[normal, hc]` pair at either the outer `contrast` or
+inner `wcag` level) is automatically promoted to its spec-defined "Enhanced"
+successor in high-contrast mode — WCAG SC 1.4.3 (Minimum) → SC 1.4.6
+(Enhanced), the direct analog of APCA's Enhanced Level:
+
+```ts
+contrast: 'AA'         // 4.5 normal, 7 high-contrast (auto -> AAA)
+contrast: 'AA-large'   // 3 normal, 4.5 high-contrast (auto -> AAA-large)
+contrast: 'AAA'        // 7 both modes (top tier, unchanged)
+contrast: 'AAA-large'  // 4.5 both modes (top tier, unchanged)
+contrast: 5.5          // 5.5 both modes (bare number, no successor tier)
+contrast: { wcag: ['AA', 'AA'] } // 4.5 both modes (explicit HC, no promotion)
+```
+
+`AAA` and `AAA-large` are already the top WCAG tier and are left unchanged; bare
+numeric targets have no defined successor tier and are also left unchanged. An
+explicit HC value via either pair overrides and skips the promotion.
+
 ## Verification (APCA / WCAG drift)
 
 Because chromatic swatches inherit gray's tone-derived lightness but drift in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/glaze",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "OKHST-based color theme generator with WCAG contrast solving for light, dark, and high-contrast schemes",
   "type": "module",
   "main": "./dist/index.cjs",