/**
 * Typography design tokens for BeatUI.
 *
 * Defines the complete typographic scale including font sizes, weights, line heights,
 * letter spacing, font families, and semantic font role mappings. All values are
 * converted to CSS custom properties at build time.
 *
 * @module
 */
/**
 * The base font size unit used as the foundation for the font size scale.
 *
 * @default '1rem'
 */
export declare const baseFontSize = "1rem";
/**
 * Font size scale mapping size names to `[fontSize, { lineHeight }]` tuples.
 * Each entry provides a font size derived from `--font-size-base` via `calc()`
 * and its recommended line height. When `--font-size-base` is `1rem` (default),
 * computed values match the pixel sizes shown.
 *
 * | Name | Multiplier | Line Height      | Pixels (at 1rem base) |
 * |------|------------|------------------|-----------------------|
 * | 3xs  | 0.5        | base * 0.75      | 8px                   |
 * | 2xs  | 0.625      | base * 0.75      | 10px                  |
 * | xs   | 0.75       | base             | 12px                  |
 * | sm   | 0.875      | base * 1.25      | 14px                  |
 * | md   | 1          | base * 1.5       | 16px                  |
 * | lg   | 1.125      | base * 1.75      | 18px                  |
 * | xl   | 1.25       | base * 1.75      | 20px                  |
 * | 2xl  | 1.5        | base * 2         | 24px                  |
 * | ...  | ...        | ...              | ...                   |
 * | 9xl  | 8          | 1 (unitless)     | 128px                 |
 */
export declare const fontSize: {
    readonly '3xs': readonly ["calc(var(--font-size-base) * 0.5)", {
        readonly lineHeight: "calc(var(--font-size-base) * 0.75)";
    }];
    readonly '2xs': readonly ["calc(var(--font-size-base) * 0.625)", {
        readonly lineHeight: "calc(var(--font-size-base) * 0.75)";
    }];
    readonly xs: readonly ["calc(var(--font-size-base) * 0.75)", {
        readonly lineHeight: "var(--font-size-base)";
    }];
    readonly sm: readonly ["calc(var(--font-size-base) * 0.875)", {
        readonly lineHeight: "calc(var(--font-size-base) * 1.25)";
    }];
    readonly md: readonly ["var(--font-size-base)", {
        readonly lineHeight: "calc(var(--font-size-base) * 1.5)";
    }];
    readonly lg: readonly ["calc(var(--font-size-base) * 1.125)", {
        readonly lineHeight: "calc(var(--font-size-base) * 1.75)";
    }];
    readonly xl: readonly ["calc(var(--font-size-base) * 1.25)", {
        readonly lineHeight: "calc(var(--font-size-base) * 1.75)";
    }];
    readonly '2xl': readonly ["calc(var(--font-size-base) * 1.5)", {
        readonly lineHeight: "calc(var(--font-size-base) * 2)";
    }];
    readonly '3xl': readonly ["calc(var(--font-size-base) * 1.875)", {
        readonly lineHeight: "calc(var(--font-size-base) * 2.25)";
    }];
    readonly '4xl': readonly ["calc(var(--font-size-base) * 2.25)", {
        readonly lineHeight: "calc(var(--font-size-base) * 2.5)";
    }];
    readonly '5xl': readonly ["calc(var(--font-size-base) * 3)", {
        readonly lineHeight: "1";
    }];
    readonly '6xl': readonly ["calc(var(--font-size-base) * 3.75)", {
        readonly lineHeight: "1";
    }];
    readonly '7xl': readonly ["calc(var(--font-size-base) * 4.5)", {
        readonly lineHeight: "1";
    }];
    readonly '8xl': readonly ["calc(var(--font-size-base) * 6)", {
        readonly lineHeight: "1";
    }];
    readonly '9xl': readonly ["calc(var(--font-size-base) * 8)", {
        readonly lineHeight: "1";
    }];
};
/**
 * Returns a font size that is a given number of steps away from the provided size
 * in the font size scale. Positive steps move toward larger sizes; negative steps
 * move toward smaller sizes. The result is clamped to the available range.
 *
 * @param size - The starting font size name
 * @param steps - Number of steps to move (positive = larger, negative = smaller)
 * @returns The resulting font size name
 * @throws If the provided size is not a valid font size name
 *
 * @example
 * ```ts
 * changeFontSize('md', 1)  // 'lg'
 * changeFontSize('md', -1) // 'sm'
 * changeFontSize('9xl', 5) // '9xl' (clamped)
 * ```
 */
export declare function changeFontSize(size: FontSize, steps: number): "sm" | "md" | "lg" | "xl" | "2xl" | "xs" | "2xs" | "3xl" | "4xl" | "3xs" | "5xl" | "6xl" | "7xl" | "8xl" | "9xl";
/**
 * Union type of all available font size names.
 */
export type FontSize = keyof typeof fontSize;
/**
 * Font weight scale mapping weight names to their numeric CSS values.
 *
 * | Name       | Value |
 * |------------|-------|
 * | thin       | 100   |
 * | extralight | 200   |
 * | light      | 300   |
 * | normal     | 400   |
 * | medium     | 500   |
 * | semibold   | 600   |
 * | bold       | 700   |
 * | extrabold  | 800   |
 * | black      | 900   |
 */
export declare const fontWeight: {
    readonly thin: "100";
    readonly extralight: "200";
    readonly light: "300";
    readonly normal: "400";
    readonly medium: "500";
    readonly semibold: "600";
    readonly bold: "700";
    readonly extrabold: "800";
    readonly black: "900";
};
/**
 * Union type of all available font weight names.
 */
export type FontWeight = keyof typeof fontWeight;
/**
 * Line height scale mapping names to unitless multiplier values.
 *
 * | Name    | Value |
 * |---------|-------|
 * | none    | 1     |
 * | tight   | 1.25  |
 * | snug    | 1.375 |
 * | normal  | 1.5   |
 * | relaxed | 1.625 |
 * | loose   | 2     |
 */
export declare const lineHeight: {
    readonly none: "1";
    readonly tight: "1.25";
    readonly snug: "1.375";
    readonly normal: "1.5";
    readonly relaxed: "1.625";
    readonly loose: "2";
};
/**
 * Union type of all available line height names.
 */
export type LineHeight = keyof typeof lineHeight;
/**
 * Letter spacing scale mapping names to `em`-based values.
 *
 * | Name    | Value    |
 * |---------|----------|
 * | tighter | -0.05em  |
 * | tight   | -0.025em |
 * | normal  | 0em      |
 * | wide    | 0.025em  |
 * | wider   | 0.05em   |
 * | widest  | 0.1em    |
 */
export declare const letterSpacing: {
    readonly tighter: "-0.05em";
    readonly tight: "-0.025em";
    readonly normal: "0em";
    readonly wide: "0.025em";
    readonly wider: "0.05em";
    readonly widest: "0.1em";
};
/**
 * Union type of all available letter spacing names.
 */
export type LetterSpacing = keyof typeof letterSpacing;
/**
 * Font family stacks mapping family names to ordered arrays of font names.
 * Each stack provides a comprehensive fallback chain including system fonts and emoji support.
 */
export declare const fontFamily: {
    readonly sans: readonly ["system-ui", "-apple-system", "BlinkMacSystemFont", "\"Segoe UI\"", "Roboto", "\"Helvetica Neue\"", "Arial", "\"Noto Sans\"", "sans-serif", "\"Apple Color Emoji\"", "\"Segoe UI Emoji\"", "\"Segoe UI Symbol\"", "\"Noto Color Emoji\""];
    readonly serif: readonly ["ui-serif", "Georgia", "Cambria", "\"Times New Roman\"", "Times", "serif"];
    readonly mono: readonly ["ui-monospace", "SFMono-Regular", "\"SF Mono\"", "Consolas", "\"Liberation Mono\"", "Menlo", "monospace"];
};
/**
 * Union type of all available font family names.
 */
export type FontFamily = keyof typeof fontFamily;
/**
 * Partial record for overriding default font family stacks.
 * Values can be a single font string or an array of font names.
 *
 * @example
 * ```ts
 * const overrides: FontFamilyOverrides = {
 *   sans: ['Inter', 'system-ui', 'sans-serif'],
 *   mono: '"Fira Code", monospace',
 * }
 * ```
 */
export type FontFamilyOverrides = Partial<Record<FontFamily, string | readonly string[]>>;
/**
 * Tuple of all semantic font role names.
 */
export declare const semanticFontNames: readonly ["body", "heading", "display", "mono", "ui", "prose"];
/**
 * Union type of all semantic font role names.
 */
export type SemanticFontName = (typeof semanticFontNames)[number];
/**
 * Partial record for overriding default semantic font family assignments.
 *
 * @example
 * ```ts
 * const overrides: SemanticFontOverrides = {
 *   heading: 'var(--font-family-serif)',
 * }
 * ```
 */
export type SemanticFontOverrides = Partial<Record<SemanticFontName, string>>;
/**
 * Returns the CSS custom property name for a font size.
 *
 * @param size - The font size name
 * @returns The CSS variable name (e.g., `'--font-size-md'`)
 *
 * @example
 * ```ts
 * getFontSizeVarName('md') // '--font-size-md'
 * ```
 */
export declare function getFontSizeVarName(size: FontSize): string;
/**
 * Returns a CSS `var()` expression referencing the font size custom property.
 *
 * @param size - The font size name
 * @returns A CSS `var()` string (e.g., `'var(--font-size-md)'`)
 *
 * @example
 * ```ts
 * getFontSizeVar('md') // 'var(--font-size-md)'
 * ```
 */
export declare function getFontSizeVar(size: FontSize): string;
/**
 * Returns the CSS custom property name for the base font size.
 *
 * @returns The CSS variable name `'--font-size-base'`
 */
export declare function getBaseFontSizeVarName(): string;
/**
 * Returns a CSS `var()` expression referencing the base font size custom property.
 *
 * @returns A CSS `var()` string `'var(--font-size-base)'`
 */
export declare function getBaseFontSizeVar(): string;
/**
 * Returns the CSS custom property name for a font size's paired line height.
 *
 * @param size - The font size name
 * @returns The CSS variable name (e.g., `'--font-size-md-lh'`)
 */
export declare function getFontSizeLineHeightVarName(size: FontSize): string;
/**
 * Returns a CSS `var()` expression referencing the font size line height custom property.
 *
 * @param size - The font size name
 * @returns A CSS `var()` string (e.g., `'var(--font-size-md-lh)'`)
 */
export declare function getFontSizeLineHeightVar(size: FontSize): string;
/**
 * Returns the CSS custom property name for a font weight.
 *
 * @param weight - The font weight name
 * @returns The CSS variable name (e.g., `'--font-weight-bold'`)
 */
export declare function getFontWeightVarName(weight: FontWeight): string;
/**
 * Returns a CSS `var()` expression referencing the font weight custom property.
 *
 * @param weight - The font weight name
 * @returns A CSS `var()` string (e.g., `'var(--font-weight-bold)'`)
 */
export declare function getFontWeightVar(weight: FontWeight): string;
/**
 * Returns the CSS custom property name for a line height.
 *
 * @param height - The line height name
 * @returns The CSS variable name (e.g., `'--line-height-normal'`)
 */
export declare function getLineHeightVarName(height: LineHeight): string;
/**
 * Returns a CSS `var()` expression referencing the line height custom property.
 *
 * @param height - The line height name
 * @returns A CSS `var()` string (e.g., `'var(--line-height-normal)'`)
 */
export declare function getLineHeightVar(height: LineHeight): string;
/**
 * Returns the CSS custom property name for a letter spacing value.
 *
 * @param spacing - The letter spacing name
 * @returns The CSS variable name (e.g., `'--letter-spacing-wide'`)
 */
export declare function getLetterSpacingVarName(spacing: LetterSpacing): string;
/**
 * Returns a CSS `var()` expression referencing the letter spacing custom property.
 *
 * @param spacing - The letter spacing name
 * @returns A CSS `var()` string (e.g., `'var(--letter-spacing-wide)'`)
 */
export declare function getLetterSpacingVar(spacing: LetterSpacing): string;
/**
 * Returns the CSS custom property name for a font family.
 *
 * @param family - The font family name
 * @returns The CSS variable name (e.g., `'--font-family-sans'`)
 */
export declare function getFontFamilyVarName(family: FontFamily): string;
/**
 * Returns a CSS `var()` expression referencing the font family custom property.
 *
 * @param family - The font family name
 * @returns A CSS `var()` string (e.g., `'var(--font-family-sans)'`)
 */
export declare function getFontFamilyVar(family: FontFamily): string;
/**
 * Returns the CSS custom property name for a semantic font role.
 *
 * @param name - The semantic font name
 * @returns The CSS variable name (e.g., `'--font-body'`)
 */
export declare function getSemanticFontVarName(name: SemanticFontName): string;
/**
 * Returns a CSS `var()` expression referencing the semantic font custom property.
 *
 * @param name - The semantic font name
 * @returns A CSS `var()` string (e.g., `'var(--font-body)'`)
 */
export declare function getSemanticFontVar(name: SemanticFontName): string;
/**
 * Generates CSS custom property declarations for all typography tokens, including
 * the base font size, font sizes, per-size line heights, font weights, semantic
 * line heights, letter spacing, and font families.
 *
 * @returns A record mapping CSS variable names to their values
 *
 * @example
 * ```ts
 * const vars = generateTypographyVariables()
 * // vars['--font-size-base'] === '1rem'
 * // vars['--font-size-md'] === 'var(--font-size-base)'
 * // vars['--font-size-md-lh'] === 'calc(var(--font-size-base) * 1.5)'
 * // vars['--font-weight-bold'] === '700'
 * ```
 */
export declare function generateTypographyVariables(): Record<string, string>;
/**
 * Generates CSS custom property declarations for font family overrides.
 * Only produces variables for the families specified in the overrides.
 *
 * @param overrides - Optional font family overrides
 * @returns A record mapping CSS variable names to their values, or an empty record if no overrides
 *
 * @example
 * ```ts
 * const vars = generateFontFamilyOverrideVariables({ sans: ['Inter', 'sans-serif'] })
 * // vars['--font-family-sans'] === 'Inter, sans-serif'
 * ```
 */
export declare function generateFontFamilyOverrideVariables(overrides?: FontFamilyOverrides): Record<string, string>;
/**
 * Generates CSS custom property declarations for semantic font roles and
 * default font family aliases. Merges defaults with any provided overrides.
 *
 * @param overrides - Optional overrides for semantic font role assignments
 * @returns A record mapping CSS variable names to their values
 *
 * @example
 * ```ts
 * const vars = generateSemanticFontVariables({ heading: 'var(--font-family-serif)' })
 * // vars['--font-heading'] === 'var(--font-family-serif)'
 * // vars['--font-family-default'] === 'var(--font-body)'
 * ```
 */
export declare function generateSemanticFontVariables(overrides?: SemanticFontOverrides): Record<string, string>;