/**
 * Theme configuration for @sil/ui.
 *
 * Pass a `UIThemeConfig` to `defineTheme()` in your Vite plugin setup or
 * call `generateThemeStyles()` to produce a `:root { … }` CSS block you can
 * inject anywhere.
 *
 * @example Vite plugin usage
 * ```ts
 * // vite.config.ts
 * import { defineConfig } from 'vite'
 * import { ui, defineTheme } from '@sil/ui/vite'
 *
 * export default defineConfig({
 *   plugins: [
 *     ui({
 *       theme: defineTheme({
 *         colors: {
 *           dark: '#0d1117',
 *           light: '#ffffff',
 *           primary: '#6366f1',
 *           secondary: '#8b5cf6',
 *         },
 *         fonts: {
 *           body: '"Inter", system-ui, sans-serif',
 *           heading: '"Manrope", "Inter", sans-serif',
 *         },
 *         variables: {
 *           '--border-radius': '0.75rem',
 *           '--space': '1rem',
 *         },
 *       }),
 *     }),
 *   ],
 * })
 * ```
 */
/**
 * Full theme configuration object accepted by `defineTheme()`,
 * `buildThemeConfig()`, and `generateThemeStyles()`.
 *
 * All fields are optional — any value you omit falls back to the library
 * defaults defined in `DEFAULT_THEME_COLORS`, `DEFAULT_THEME_FONTS`, and the
 * base stylesheet.
 */
export interface UIThemeConfig {
    /**
     * Named colour tokens used throughout the component library.
     *
     * For every key you provide, the following CSS custom properties are
     * automatically generated and available globally:
     *
     * ```
     * --color-{token}          The raw colour value you supplied.
     * --color-{token}-text     A legible contrast colour (dark or light).
     * --color-{token}-contrast Alias of -text.
     * --color-{token}-light    A 35 % tint toward white.
     * --color-{token}-dark     A 32 % shade toward black.
     * ```
     *
     * When a `palette` is also provided, token values should be palette names
     * (e.g. `'red'`) and the generated CSS will reference the palette custom
     * properties: `--color-primary: var(--color-red);`
     *
     * ### Semantic tokens understood by the component library
     *
     * | Token          | Role                                                  |
     * |----------------|-------------------------------------------------------|
     * | `dark`         | Darkest background / base dark-mode colour            |
     * | `light`        | Lightest background / base light-mode colour          |
     * | `accent-dark`  | Accent used in dark contexts (defaults to black)      |
     * | `accent-light` | Accent used in light contexts (defaults to warm off-white) |
     * | `primary`      | Main brand / action colour                            |
     * | `secondary`    | Supporting brand colour                               |
     * | `tertiary`     | Third brand colour                                    |
     * | `quaternary`   | Fourth brand colour                                   |
     * | `quinary`      | Fifth brand colour                                    |
     * | `success`      | Positive feedback (green by default)                  |
     * | `warning`      | Cautionary feedback (amber by default)                |
     * | `error`        | Error / destructive feedback (red by default)         |
     * | `info`         | Informational feedback (blue by default)              |
     * | `border`       | Default border / divider colour                       |
     *
     * In addition to the tokens above, the library derives:
     * - `--color-background` and `--color-foreground` from the active
     *   light/dark mode state.
     * - `--color-accent` from `accent-dark` / `accent-light` based on mode.
     *
     * @example
     * ```ts
     * colors: {
     *   dark: '#0d1117',
     *   light: '#f6f8fa',
     *   primary: '#6366f1',
     *   secondary: '#8b5cf6',
     *   tertiary: '#06b6d4',
     *   success: '#22c55e',
     *   warning: '#f59e0b',
     *   error: '#ef4444',
     * }
     * ```
     */
    colors?: Record<string, string>;
    /**
     * Palette of named colours that tokens can reference.
     *
     * When provided, `generateThemeStyles()` emits `--color-{name}` and derived
     * variants for every palette entry first. Token colours whose values match
     * a palette name will be rendered as `var(--color-{name})` references
     * instead of raw hex values.
     *
     * @example
     * ```ts
     * palette: {
     *   red: '#f40935',
     *   blue: '#2563eb',
     * },
     * colors: {
     *   primary: 'red',
     *   info: 'blue',
     * }
     * ```
     */
    palette?: Record<string, string>;
    /**
     * Font-family stacks applied via CSS custom properties.
     *
     * Generated custom properties:
     * ```
     * --font-family         Same as body (default font).
     * --font-family-body    Body / prose text.
     * --font-family-heading Headings (h1–h6).
     * --font-family-mono    Code, kbd, pre elements.
     * --font-family-monospace  Alias of --font-family-mono.
     * ```
     *
     * @example System fonts (zero download, best performance)
     * ```ts
     * fonts: {
     *   body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
     *   heading: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
     *   mono: '"SF Mono", Consolas, "Liberation Mono", Menlo, Courier, monospace',
     * }
     * ```
     *
     * @example Google Fonts (load them separately in your HTML/CSS)
     * ```ts
     * fonts: {
     *   body: '"Inter", system-ui, sans-serif',
     *   heading: '"Manrope", "Inter", system-ui, sans-serif',
     *   mono: '"JetBrains Mono", "Fira Code", monospace',
     * }
     * ```
     */
    fonts?: UIThemeFonts;
    /**
     * Arbitrary CSS custom properties injected into `:root`.
     *
     * Keys may include or omit the leading `--` — both forms work:
     * `{ 'border-radius': '0.5rem' }` and `{ '--border-radius': '0.5rem' }`.
     *
     * ### Commonly overridden variables
     *
     * | Variable              | Default    | Description                              |
     * |-----------------------|------------|------------------------------------------|
     * | `--border-radius`     | `0.25em`   | Base corner radius used by all components|
     * | `--border-radius-s`   | `0.15em`   | Small corner radius                      |
     * | `--border-radius-l`   | `0.5em`    | Large corner radius                      |
     * | `--border-radius-xl`  | `0.75em`   | Extra-large corner radius                |
     * | `--border-radius-xxl` | `1rem`     | Extra-extra-large corner radius          |
     * | `--space`             | `1rem`     | Base spacing unit                        |
     * | `--space-xs`          | `0.25rem`  | Extra-small spacing                      |
     * | `--space-s`           | `0.5rem`   | Small spacing                            |
     * | `--space-m`           | `1rem`     | Medium spacing (alias of --space)        |
     * | `--space-l`           | `1.5rem`   | Large spacing                            |
     * | `--space-xl`          | `2rem`     | Extra-large spacing                      |
     * | `--space-xxl`         | `3rem`     | Extra-extra-large spacing                |
     * | `--font-size`         | `1rem`     | Base font size                           |
     * | `--font-size-xs`      | `0.7rem`   | Extra-small font size                    |
     * | `--font-size-s`       | `0.85rem`  | Small font size                          |
     * | `--font-size-m`       | `1rem`     | Medium font size                         |
     * | `--font-size-l`       | `1.15rem`  | Large font size                          |
     * | `--font-size-xl`      | `1.5rem`   | Extra-large font size                    |
     * | `--font-size-xxl`     | `2rem`     | Extra-extra-large font size              |
     * | `--transition`        | `0.2s ease`| Default transition timing                |
     *
     * @example
     * ```ts
     * variables: {
     *   '--border-radius': '0.75rem',
     *   '--space': '1rem',
     *   '--font-size': '16px',
     * }
     * ```
     */
    variables?: Record<string, string | number>;
}
/**
 * Font-family stacks for the three typographic roles used by the library.
 * All fields are optional; omitted values fall back to `DEFAULT_THEME_FONTS`.
 */
export interface UIThemeFonts {
    /**
     * Font stack for body text, paragraphs, and UI labels.
     * Sets `--font-family` and `--font-family-body`.
     */
    body?: string;
    /**
     * Font stack for headings (h1–h6) and display text.
     * Sets `--font-family-heading`.
     */
    heading?: string;
    /**
     * Font stack for code blocks, `<kbd>`, `<pre>`, and monospace contexts.
     * Sets `--font-family-mono` and `--font-family-monospace`.
     */
    mono?: string;
}
/**
 * Fully-resolved theme with all defaults applied.
 * Returned by `buildThemeConfig()` — useful when you need a guaranteed
 * non-optional shape (e.g. when writing a custom style generator).
 */
export interface ResolvedUIThemeConfig {
    colors: Record<string, string>;
    fonts: Required<UIThemeFonts>;
    variables: Record<string, string | number>;
}
/** @internal */
export declare const SYSTEM_SANS_STACK = "system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
/** @internal */
export declare const SYSTEM_MONO_STACK = "\"SF Mono\", Consolas, \"Liberation Mono\", Menlo, Courier, monospace";
/**
 * Default colour tokens shipped with the library.
 * These are merged with (and overridden by) any `colors` you provide in your
 * `UIThemeConfig`.
 */
export declare const DEFAULT_THEME_COLORS: Record<string, string>;
/**
 * Default font stacks used when no `fonts` config is provided.
 * All three stacks default to the OS system sans-serif or monospace.
 */
export declare const DEFAULT_THEME_FONTS: Required<UIThemeFonts>;
/**
 * Ready-made font-stack presets you can reference in `UIThemeFonts`.
 *
 * | Preset       | Body                  | Heading              |
 * |--------------|-----------------------|----------------------|
 * | `system`     | System sans-serif     | System sans-serif    |
 * | `product`    | Inter                 | Manrope              |
 * | `friendly`   | Nunito Sans           | Avenir Next          |
 * | `editorial`  | Newsreader (serif)    | Fraunces (serif)     |
 *
 * @example
 * ```ts
 * import { UI_THEME_FONT_PRESETS } from '@sil/ui/vite'
 *
 * defineTheme({
 *   fonts: UI_THEME_FONT_PRESETS.product,
 * })
 * ```
 */
export declare const UI_THEME_FONT_PRESETS: Record<string, Required<UIThemeFonts>>;
/**
 * Type-safe helper for authoring a `UIThemeConfig`.
 *
 * This function is a pass-through — it returns its argument unchanged — but
 * it gives TypeScript (and AI tools) enough context to provide accurate
 * auto-complete and validation for every field.
 *
 * @param theme - Your theme configuration.
 * @returns The same object, typed as `UIThemeConfig`.
 *
 * @example Minimal custom theme
 * ```ts
 * import { defineTheme } from '@sil/ui/vite'
 *
 * export default defineTheme({
 *   colors: {
 *     primary: '#6366f1',
 *     secondary: '#8b5cf6',
 *   },
 *   fonts: {
 *     body: '"Inter", system-ui, sans-serif',
 *   },
 * })
 * ```
 *
 * @example Full theme with variables override
 * ```ts
 * import { defineTheme } from '@sil/ui/vite'
 *
 * export default defineTheme({
 *   colors: {
 *     dark: '#0d1117',
 *     light: '#f6f8fa',
 *     primary: '#6366f1',
 *     secondary: '#8b5cf6',
 *     tertiary: '#06b6d4',
 *     success: '#22c55e',
 *     warning: '#f59e0b',
 *     error: '#ef4444',
 *     info: '#3b82f6',
 *     border: '#e2e8f0',
 *   },
 *   fonts: {
 *     body: '"Inter", system-ui, sans-serif',
 *     heading: '"Manrope", "Inter", system-ui, sans-serif',
 *     mono: '"JetBrains Mono", monospace',
 *   },
 *   variables: {
 *     '--border-radius': '0.75rem',
 *     '--space': '1rem',
 *   },
 * })
 * ```
 */
export declare function defineTheme(theme: UIThemeConfig): UIThemeConfig;
/**
 * Merges a partial `UIThemeConfig` with all library defaults, producing a
 * fully-resolved config with no optional fields.
 *
 * @param theme - Partial theme config (defaults to `{}`).
 * @returns A `ResolvedUIThemeConfig` with defaults filled in.
 */
export declare function buildThemeConfig(theme?: UIThemeConfig): ResolvedUIThemeConfig;
/**
 * Alias for `buildThemeConfig`.
 * @see buildThemeConfig
 */
export declare const resolveTheme: typeof buildThemeConfig;
/**
 * Generates a complete `:root { … }` CSS block from a `UIThemeConfig`.
 *
 * The output includes:
 * - `--font-family[-body|-heading|-mono|-monospace]`
 * - `--color-{token}` plus `-text`, `-contrast`, `-light`, `-dark` variants
 *   for every colour token
 * - Any extra entries from `variables`
 *
 * Inject the result into a `<style>` tag or write it to a `.css` file.
 *
 * @param theme - Partial theme config (defaults to `{}`).
 * @returns A CSS string starting with `:root {` and ending with `}`.
 *
 * @example
 * ```ts
 * import { generateThemeStyles } from '@sil/ui/vite'
 *
 * const css = generateThemeStyles({
 *   colors: { primary: '#6366f1' },
 * })
 * // → ":root {\n  --font-family: system-ui…\n  --color-primary: #6366f1;\n  …\n}"
 * ```
 */
export declare function generateThemeStyles(theme?: UIThemeConfig): string;
