import { RgbColor } from './color-math';
/**
 * A paired-with surface — the color value the token's rendered output is compared
 * against. Carries an alpha because some tokens (e.g. v2-new-brand `text-on-action` =
 * `252,252,254,0.9`) are themselves semi-transparent and must be composited onto their
 * own background before contrast is measured.
 */
export declare type ContextSurface = {
  rgb: RgbColor;
  a: number;
};
/** Static token catalogue entry — produced by the build-time generator. */
export declare type TokenCheckConfig = {
  tokenName: string;
  /**
   * Name of the token whose rendered surface this check is measured against. Resolved
   * by {@link resolvePairedSurface} — actionColor-derived tokens are looked up in
   * `tokenMap`; static design tokens fall through to the `fixedSurfaces` table.
   */
  pairedWith: string;
  /**
   * Contrast check category — determines which {@link ContrastCheckStrategy} handles the
   * fg/bg computation and which WCAG AA threshold applies:
   *  - `'bg-text'`: token is a background; paired text sits on top (4.5:1).
   *  - `'text-bg'`: token is foreground text; paired surface is behind (4.5:1).
   *  - `'non-text-contrast'`: token is a border/ring/UI element (3:1).
   */
  type: 'bg-text' | 'text-bg' | 'non-text-contrast';
  /**
   * Override the surface the token is alpha-composited onto when computing its rendered
   * color. Normally a semi-transparent `non-text-contrast` token is composited onto its
   * `pairedWith` surface. For box-shadow rings that paint *outside* an element (on the
   * page background) but are compared against the element's fill, set this to
   * `'bg-primary'` so the composite matches what the browser actually renders.
   */
  compositedOn?: string;
};
/** Detail type for failing tokens — used by the validator's public result. */
export declare type ColorContrastDetail = {
  tokenName: string;
  contrastRatio: number;
  requiredRatio: number;
};
/** Contrast computation result including rendered colors. */
export declare type ContrastResult = {
  fg: RgbColor;
  bg: RgbColor;
  contrastRatio: number;
};
/** Per-check fixability record. */
export declare type FixabilityRecord = {
  fixable: boolean;
  maxContrast: number;
};
/**
 * Names of the static design tokens that have no `overrideGetter` — the surfaces every
 * actionColor-derived token may be paired with. Source-of-truth for which static tokens
 * the checker must know about. Kept here (not in the consumer) so adding new pair targets
 * is a one-line change in this package.
 *
 * Each entry's real SCSS consumer is documented in the catalogue's inline comment.
 * `bg-action-tertiary` is α=0 (fully transparent) — composites collapse to `bg-primary`.
 */
export declare const FIXED_PAIRED_SURFACE_TOKENS: readonly string[];
/**
 * Parse the comma-separated `r, g, b, a` shape used by the generated `*-color-tokens.ts` files.
 *
 * @param {string} value - Comma-separated string in `"r, g, b, a"` format (e.g. `"252, 252, 254, 0.9"`).
 * @returns {ContextSurface} Parsed {@link ContextSurface} with `rgb` and `a` fields.
 * @throws {Error} If the string has fewer than 4 parts or contains non-numeric values.
 */
export declare function parseCommaTokenValue(value: string): ContextSurface;
/**
 * Build the fixed paired-surface table from the consumer's static design-token map.
 *
 * @param {Record<string, string>} designTokens - Source design tokens (token name → "r, g, b, a").
 * @returns {Readonly<Record<string, ContextSurface>>} Frozen table for the checker.
 */
export declare function buildFixedPairedSurfaces(designTokens: Record<string, string>): Readonly<Record<string, ContextSurface>>;
/**
 * Resolve a `pairedWith` name to its rendered {@link ContextSurface}.
 *
 * Lookup order:
 *  1. **`tokenMap` (actionColor-derived)** — covers every token that has an
 *     `overrideGetter` and therefore depends on `actionColor`.
 *  2. **`fixedSurfaces`** — covers the static design tokens that have no `overrideGetter`.
 *
 * @param {string} pairedWith - Token name to resolve.
 * @param {Map<string, string>} tokenMap - Resolved token map for dynamic lookups.
 * @param {Readonly<Record<string, ContextSurface>>} fixedSurfaces - Static surface table.
 * @returns {ContextSurface | undefined} Resolved surface, or undefined if not found.
 */
export declare function resolvePairedSurface(pairedWith: string, tokenMap: Map<string, string>, fixedSurfaces: Readonly<Record<string, ContextSurface>>): ContextSurface | undefined;
/**
 * Resolve a paired surface to its rendered foreground RGB when it sits on top of `bg`.
 * For opaque surfaces this is a no-op; for `text-on-action` (α<1) it performs the alpha
 * composite the browser does at paint time, so the contrast ratio we compute matches
 * what axe / Chrome DevTools see.
 *
 * @param {ContextSurface} surface - Surface to resolve.
 * @param {RgbColor} bg - Background color for alpha compositing.
 * @returns {RgbColor} Effective foreground RGB.
 */
export declare function effectiveFgRgb(surface: ContextSurface, bg: RgbColor): RgbColor;
/**
 * Return the WCAG AA required contrast ratio for a check type.
 *
 * @param {TokenCheckConfig['type']} type - Check type.
 * @returns {number} Required contrast ratio.
 */
export declare function requiredRatioFor(type: TokenCheckConfig['type']): number;
/**
 * Compute the contrast ratio + rendered colors for a single token check under a given
 * `actionColor`. Returns null when the token has no override value, the value can't be
 * parsed, or the paired surface fails to resolve (catalogue typo).
 *
 * @param {TokenCheckConfig} checkConfig - Token check configuration.
 * @param {Map<string, string>} tokenMap - Resolved token map for surface lookups.
 * @param {Readonly<Record<string, ContextSurface>>} fixedSurfaces - Static surface table.
 * @returns {ContrastResult | null} Contrast result or null.
 */
export declare function computeTokenContrast(checkConfig: TokenCheckConfig, tokenMap: Map<string, string>, fixedSurfaces: Readonly<Record<string, ContextSurface>>): ContrastResult | null;
