import { SurfaceRung } from './colors';
/**
 * The custom properties a scope sets. Components read these rather than reading
 * tokens directly, which is what makes them context-sensitive.
 */
export declare const DS_VARS: {
    /** The surface's own background. */
    readonly bg: "--ds-bg";
    /** Fill for an input hosted on this surface: one rung *down*, so it reads inset. */
    readonly field: "--ds-field";
    /** Outline for that input. Carries the work on `page`, where there is no rung below. */
    readonly fieldBorder: "--ds-field-border";
    /** Body text on this surface. */
    readonly text: "--ds-text";
    /** De-emphasised text. Switches tier partway up the ladder — see `textQuiet`. */
    readonly textQuiet: "--ds-text-quiet";
    /** Border/divider legible against this rung. */
    readonly border: "--ds-border";
    /**
     * Row separator (~1.12:1). Lighter than `--ds-border` so table outlines stay
     * the heavier structural edge. A filled header has no underline.
     */
    readonly separator: "--ds-separator";
    /** Hover state fill. */
    readonly hover: "--ds-hover";
    /** Selected state fill — a resolved brand tint, not an alpha. */
    readonly selected: "--ds-selected";
    /** The rung a DOM-nested child surface should take. Clamped at the ceiling. */
    readonly child: "--ds-child";
    /**
     * Fill for a *control* that has to read against a container at its own level:
     * host + 2, clamped at the ceiling.
     *
     * Two rungs, not one, and the reason is that `child` is already taken by
     * containers. A switch track or an avatar sitting at +1 is the same colour as
     * a card on the same surface, so it reads as a panel rather than as something
     * you operate. +2 is the first step that distinguishes a control from a
     * container.
     */
    readonly control: "--ds-control";
    /** The rung a *portalled* child should take: max(raised, host + 1). */
    readonly raised: "--ds-raised";
    /**
     * Table header and row hover, derived from the host rung rather than named
     * as their own palette entries.
     *
     * Body rows read `--ds-bg`. Header is a ~1.08:1 fill that moves *away* from
     * elevation (lighter in dark, darker in light) so it reads recessed. Hover is
     * host + 2, stepping *down* at the ceiling so a nested table does not lose
     * feedback when `--ds-control` saturates.
     */
    readonly tableHeader: "--ds-table-header";
    /**
     * Ink on a *filled* table header. The fill eats the margin `subtle` was tuned
     * for, so filled headers step up a tier (`tertiary` in dark, with `secondary`
     * at the overlay ceiling). Unfilled headers keep `--ds-text-quiet`.
     *
     * Named `--ds-table-header-ink`, not `--ds-table-header-label`: Emotion's
     * class-name generator extracts `/label:\s*([^\s;{]+)/` from serialized CSS,
     * so a custom property whose name ends in `-label` (e.g. `--foo-label:#A3A3A3`)
     * injects the hex into the generated class name. The `#` is then parsed as an
     * ID selector, the rule never matches, and Menu/Popover lose `position:
     * absolute`. See the `DS_VARS` guard in `surfaceScopes.test.ts`.
     */
    readonly tableHeaderLabel: "--ds-table-header-ink";
    readonly tableRowHover: "--ds-table-row-hover";
};
export interface SurfaceScope {
    bg: string;
    field: string;
    fieldBorder: string;
    text: string;
    textQuiet: string;
    border: string;
    separator: string;
    hover: string;
    selected: string;
    child: string;
    control: string;
    raised: string;
    tableHeader: string;
    tableHeaderLabel: string;
    tableRowHover: string;
}
/** Next rung up, saturating at the top. */
export declare function nextRung(rung: SurfaceRung): SurfaceRung;
/** Previous rung down, saturating at the bottom. */
export declare function previousRung(rung: SurfaceRung): SurfaceRung;
/**
 * The rung a portalled element should use: `max(raised, host + 1)`.
 *
 * A portalled element is reparented to `document.body`, so it cannot inherit a
 * rung through the DOM. `raised` is the floor because a tooltip over the app
 * shell still has to read as floating; `host + 1` takes over once the host is
 * already high enough that `raised` would not clear it.
 */
export declare function portalRung(host: SurfaceRung): SurfaceRung;
export declare const surfaceScopes: {
    readonly dark: Record<"page" | "primary" | "widget" | "surface" | "raised" | "overlay", SurfaceScope>;
    readonly light: Record<"page" | "primary" | "widget" | "surface" | "raised" | "overlay", SurfaceScope>;
};
/** Turn a scope into the custom-property declarations for a style object. */
export declare function scopeToCssVars(scope: SurfaceScope): Record<string, string>;
/**
 * `var(--ds-x, fallback)`, so a component works even when it is rendered outside
 * any scope — a bare `<Chip />` in a test, or a portalled element that escaped
 * its scope. Without a fallback those render with no background at all.
 */
export declare function dsVar(name: keyof typeof DS_VARS, fallback: string): string;