import type { PlatformBlocksTheme, SurfaceLevel, SurfaceScale, SurfaceToken } from './types';
export type { SurfaceLevel, SurfaceScale, SurfaceToken };
/** Every level, in order — handy for demos and iteration. */
export declare const SURFACE_LEVELS: SurfaceLevel[];
/**
 * Clamp any incoming value onto the ladder. Nested surfaces increment their
 * level, so it's easy to walk off the end of a 4-step scale; saturating at the
 * top is friendlier than throwing or wrapping around to the page background.
 */
export declare function clampSurfaceLevel(level: number): SurfaceLevel;
/**
 * Resolve one step of the elevation ladder.
 *
 * Prefers the theme's explicit `surfaces` scale and falls back to a scale
 * derived from `backgrounds`, filling in per-field so a theme that defines
 * only some levels still resolves the rest.
 */
export declare function resolveSurface(theme: PlatformBlocksTheme, level?: SurfaceLevel | number): SurfaceToken;
/** Convenience accessor for just the fill — the most common single lookup. */
export declare function resolveSurfaceBackground(theme: PlatformBlocksTheme, level?: SurfaceLevel | number): string;
/**
 * `band` is the one non-interactive state: a section header, striped row, or
 * any strip that should read as *part of* its surface rather than as a new one.
 */
export type SurfaceInteractionState = 'band' | 'hover' | 'pressed' | 'selected';
/**
 * Tint for something sitting *on* a surface — hover, pressed, selected, or a
 * banded section.
 *
 * Returned as a translucent overlay rather than an opaque palette shade,
 * because a fixed shade can only be correct at one elevation: `gray[1]` reads
 * as a highlight on a level-1 dark panel but is *darker* than a level-2 dark
 * dropdown, so hovering a menu item used to make it recede. An overlay lightens
 * in dark mode and darkens in light mode at every level.
 */
export declare function surfaceInteractionTint(theme: PlatformBlocksTheme, state?: SurfaceInteractionState): string;