@tenphi/glaze 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -16,6 +16,16 @@ type MinContrast$1 = number | ContrastPreset;
  * | `'min'`       | 15  | Dividers/decorative; APCA "point of invisibility"    |
  */
 type ApcaPreset = 'preferred' | 'body' | 'content' | 'large' | 'non-text' | 'min';
+declare const APCA_PRESETS: Record<ApcaPreset, number>;
+/**
+ * APCA-W3 "Enhanced Level" delta added to a bare APCA target in high-contrast
+ * mode when no explicit HC value is provided (analogous to WCAG AAA over AA).
+ * Only applied when neither the outer `contrast` pair nor the inner `apca`
+ * pair carries an explicit HC entry.
+ */
+declare const APCA_HC_ENHANCEMENT = 15;
+/** Upper bound for an APCA Lc target after HC enhancement. */
+declare const APCA_MAX_LC = 106;
 /**
  * Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
  * keyword mapped to its Lc value. The magnitude is forced non-negative.
@@ -40,8 +50,18 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * given mode into `{ metric, target }`. Handles the inner metric HC pair and
  * preset resolution. `polarity` is passed through to the result for the APCA
  * branch (it controls argument order in the solver); WCAG ignores it.
+ *
+ * `outerExplicitHC` indicates whether the caller selected this `spec` from an
+ * explicit high-contrast entry of the outer `contrast` pair. Together with the
+ * inner metric pair, it decides whether the HC auto-enhancement fires:
+ *  - APCA: +15 Lc "Enhanced Level" boost when neither level is explicit.
+ *  - WCAG: AA → AAA / AA-large → AAA-large promotion (SC 1.4.3 → 1.4.6) when
+ *    neither level is explicit. AAA-family presets and bare numbers are left
+ *    unchanged (AAA is the top WCAG tier).
+ * Defaults to `false` (correct for direct callers, which pass a single
+ * selected spec rather than an outer pair).
  */
-declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg'): ResolvedContrast;
+declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): ResolvedContrast;
 /**
  * APCA lightness contrast (Lc), signed: positive for dark text on light bg,
  * negative for light text on dark bg. Inputs are screen luminances (0–1).
@@ -445,7 +465,11 @@ interface GlazeConfig {
   darkTone?: ToneWindow;
   /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
   darkDesaturation?: number;
-  /** State alias names for token export. */
+  /**
+   * State alias names for Tasty token export. Default to media-query states
+   * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`)
+   * so tokens react to the OS preference without registering custom states.
+   */
   states?: {
     dark?: string;
     highContrast?: string;
@@ -760,7 +784,7 @@ interface GlazeColorToken {
   token(options?: GlazeTokenOptions): Record<string, string>;
   /**
    * Export as a tasty style-to-state binding (no color name key).
-   * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, string>;
@@ -896,7 +920,7 @@ interface GlazeTheme {
   tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /**
    * Export as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Spread into component styles or register as a recipe via `configure({ recipes })`.
    * @see https://tasty.style/docs
    */
@@ -1214,7 +1238,7 @@ interface GlazePalette {
   tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
   /**
    * Export all themes as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Prefix defaults to `true`. Inherits the palette-level `primary`.
    * @see https://tasty.style/docs
    */
@@ -1543,5 +1567,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -16,6 +16,16 @@ type MinContrast$1 = number | ContrastPreset;
  * | `'min'`       | 15  | Dividers/decorative; APCA "point of invisibility"    |
  */
 type ApcaPreset = 'preferred' | 'body' | 'content' | 'large' | 'non-text' | 'min';
+declare const APCA_PRESETS: Record<ApcaPreset, number>;
+/**
+ * APCA-W3 "Enhanced Level" delta added to a bare APCA target in high-contrast
+ * mode when no explicit HC value is provided (analogous to WCAG AAA over AA).
+ * Only applied when neither the outer `contrast` pair nor the inner `apca`
+ * pair carries an explicit HC entry.
+ */
+declare const APCA_HC_ENHANCEMENT = 15;
+/** Upper bound for an APCA Lc target after HC enhancement. */
+declare const APCA_MAX_LC = 106;
 /**
  * Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
  * keyword mapped to its Lc value. The magnitude is forced non-negative.
@@ -40,8 +50,18 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * given mode into `{ metric, target }`. Handles the inner metric HC pair and
  * preset resolution. `polarity` is passed through to the result for the APCA
  * branch (it controls argument order in the solver); WCAG ignores it.
+ *
+ * `outerExplicitHC` indicates whether the caller selected this `spec` from an
+ * explicit high-contrast entry of the outer `contrast` pair. Together with the
+ * inner metric pair, it decides whether the HC auto-enhancement fires:
+ *  - APCA: +15 Lc "Enhanced Level" boost when neither level is explicit.
+ *  - WCAG: AA → AAA / AA-large → AAA-large promotion (SC 1.4.3 → 1.4.6) when
+ *    neither level is explicit. AAA-family presets and bare numbers are left
+ *    unchanged (AAA is the top WCAG tier).
+ * Defaults to `false` (correct for direct callers, which pass a single
+ * selected spec rather than an outer pair).
  */
-declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg'): ResolvedContrast;
+declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): ResolvedContrast;
 /**
  * APCA lightness contrast (Lc), signed: positive for dark text on light bg,
  * negative for light text on dark bg. Inputs are screen luminances (0–1).
@@ -445,7 +465,11 @@ interface GlazeConfig {
   darkTone?: ToneWindow;
   /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
   darkDesaturation?: number;
-  /** State alias names for token export. */
+  /**
+   * State alias names for Tasty token export. Default to media-query states
+   * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`)
+   * so tokens react to the OS preference without registering custom states.
+   */
   states?: {
     dark?: string;
     highContrast?: string;
@@ -760,7 +784,7 @@ interface GlazeColorToken {
   token(options?: GlazeTokenOptions): Record<string, string>;
   /**
    * Export as a tasty style-to-state binding (no color name key).
-   * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, string>;
@@ -896,7 +920,7 @@ interface GlazeTheme {
   tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /**
    * Export as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Spread into component styles or register as a recipe via `configure({ recipes })`.
    * @see https://tasty.style/docs
    */
@@ -1214,7 +1238,7 @@ interface GlazePalette {
   tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
   /**
    * Export all themes as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Prefix defaults to `true`. Inherits the palette-level `primary`.
    * @see https://tasty.style/docs
    */
@@ -1543,5 +1567,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -688,8 +688,8 @@ function defaultConfig() {
 		},
 		darkDesaturation: .1,
 		states: {
-			dark: "@dark",
-			highContrast: "@high-contrast"
+			dark: "@media(prefers-color-scheme: dark)",
+			highContrast: "@media(prefers-contrast: more)"
 		},
 		modes: {
 			dark: true,
@@ -1085,6 +1085,15 @@ const APCA_PRESETS = {
 	min: 15
 };
 /**
+* APCA-W3 "Enhanced Level" delta added to a bare APCA target in high-contrast
+* mode when no explicit HC value is provided (analogous to WCAG AAA over AA).
+* Only applied when neither the outer `contrast` pair nor the inner `apca`
+* pair carries an explicit HC entry.
+*/
+const APCA_HC_ENHANCEMENT = 15;
+/** Upper bound for an APCA Lc target after HC enhancement. */
+const APCA_MAX_LC = 106;
+/**
 * Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
 * keyword mapped to its Lc value. The magnitude is forced non-negative.
 */
@@ -1098,10 +1107,35 @@ const CONTRAST_PRESETS = {
 	"AA-large": 3,
 	"AAA-large": 4.5
 };
+/**
+* WCAG high-contrast auto-promotion (analog of APCA's Enhanced Level). A bare
+* AA / AA-large preset is promoted to its spec-defined "Enhanced" successor
+* (SC 1.4.3 → SC 1.4.6) in high-contrast mode. AAA / 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
+* (outer or inner pair) always overrides.
+*/
+const WCAG_HC_PROMOTION = {
+	AA: "AAA",
+	"AA-large": "AAA-large"
+};
 function resolveMinContrast(value) {
 	if (typeof value === "number") return Math.max(1, value);
 	return CONTRAST_PRESETS[value];
 }
+/**
+* Resolve a WCAG target (number or preset) for a mode, applying the
+* high-contrast auto-promotion when `explicitHC` is false and the value is an
+* AA-family preset. Bare numbers and AAA-family presets pass through.
+*/
+function resolveWcagTarget(value, isHighContrast, explicitHC) {
+	if (typeof value === "number") return resolveMinContrast(value);
+	if (isHighContrast && !explicitHC) {
+		const promoted = WCAG_HC_PROMOTION[value];
+		if (promoted !== void 0) return resolveMinContrast(promoted);
+	}
+	return resolveMinContrast(value);
+}
 function pickPair(p, isHighContrast) {
 	return Array.isArray(p) ? isHighContrast ? p[1] : p[0] : p;
 }
@@ -1110,20 +1144,35 @@ function pickPair(p, isHighContrast) {
 * given mode into `{ metric, target }`. Handles the inner metric HC pair and
 * preset resolution. `polarity` is passed through to the result for the APCA
 * branch (it controls argument order in the solver); WCAG ignores it.
-*/
-function resolveContrastForMode(spec, isHighContrast, polarity) {
+*
+* `outerExplicitHC` indicates whether the caller selected this `spec` from an
+* explicit high-contrast entry of the outer `contrast` pair. Together with the
+* inner metric pair, it decides whether the HC auto-enhancement fires:
+*  - APCA: +15 Lc "Enhanced Level" boost when neither level is explicit.
+*  - WCAG: AA → AAA / AA-large → AAA-large promotion (SC 1.4.3 → 1.4.6) when
+*    neither level is explicit. AAA-family presets and bare numbers are left
+*    unchanged (AAA is the top WCAG tier).
+* Defaults to `false` (correct for direct callers, which pass a single
+* selected spec rather than an outer pair).
+*/
+function resolveContrastForMode(spec, isHighContrast, polarity, outerExplicitHC) {
 	if (typeof spec === "number" || typeof spec === "string") return {
 		metric: "wcag",
-		target: resolveMinContrast(spec)
-	};
-	if ("apca" in spec) return {
-		metric: "apca",
-		target: resolveApcaTarget(pickPair(spec.apca, isHighContrast)),
-		polarity: polarity ?? "fg"
+		target: resolveWcagTarget(spec, isHighContrast, !!outerExplicitHC)
 	};
+	if ("apca" in spec) {
+		const baseTarget = resolveApcaTarget(pickPair(spec.apca, isHighContrast));
+		const innerExplicitHC = Array.isArray(spec.apca);
+		return {
+			metric: "apca",
+			target: isHighContrast && !outerExplicitHC && !innerExplicitHC ? Math.min(baseTarget + APCA_HC_ENHANCEMENT, APCA_MAX_LC) : baseTarget,
+			polarity: polarity ?? "fg"
+		};
+	}
+	const innerExplicitHC = Array.isArray(spec.wcag);
 	return {
 		metric: "wcag",
-		target: resolveMinContrast(pickPair(spec.wcag, isHighContrast))
+		target: resolveWcagTarget(pickPair(spec.wcag, isHighContrast), isHighContrast, !!outerExplicitHC || innerExplicitHC)
 	};
 }
 const APCA_EXPONENTS = {
@@ -1825,7 +1874,8 @@ function resolveRole(name, def, ctx) {
 	return resolveRoleInMap(name, def, ctx.defs, ctx.config.inferRole, ctx.roles);
 }
 function resolveContrastSpec(spec, isHighContrast, polarity) {
-	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity);
+	const outerExplicitHC = Array.isArray(spec);
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity, outerExplicitHC);
 }
 /**
 * Apply the relative-tone delta against a base, honoring `flip`.
@@ -3717,5 +3767,5 @@ glaze.resetConfig = function resetConfig$1() {
 };
 
 //#endregion
-export { REF_EPS, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, REF_EPS, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.mjs.map