@snagtag/design-system 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,884 @@
+/** HSL colour representation. */
+interface HSL {
+    /** Hue: 0-360 */
+    h: number;
+    /** Saturation: 0-100 */
+    s: number;
+    /** Lightness: 0-100 */
+    l: number;
+}
+/** Colour harmony types for palette suggestions. */
+type HarmonyType = 'complementary' | 'analogous' | 'triadic' | 'split-complementary';
+/** A suggested colour palette based on colour theory. */
+interface ColourSuggestion {
+    type: HarmonyType;
+    colours: string[];
+    label: string;
+    description: string;
+    contrastScore: number;
+}
+/** A saved theme preset (built-in). */
+interface ThemePreset$1 {
+    id: string;
+    name: string;
+    values: Record<string, string>;
+    builtIn: boolean;
+}
+/** A user-created custom preset. */
+interface CustomPreset {
+    id: string;
+    name: string;
+    values: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A snapshot of theme values at a point in time. */
+interface ThemeVersion {
+    id: string;
+    label: string | null;
+    current: Record<string, string>;
+    previous: Record<string, string>;
+    createdAt: string;
+}
+/** Full theme export payload. */
+interface ThemeSnapshot$1 {
+    name: string;
+    version: string;
+    values: Record<string, string>;
+    exportedAt: string;
+}
+/** Theme export with metadata. */
+interface ThemeExport {
+    snapshot: ThemeSnapshot$1;
+    css: string;
+    json: string;
+}
+/** WCAG contrast quality breakdown. */
+interface QualityBreakdown$2 {
+    score: number;
+    maxScore: number;
+    label: string;
+}
+/** A WCAG contrast issue between two theme tokens. */
+interface ContrastIssue$2 {
+    fgKey: string;
+    bgKey: string;
+    fgValue: string;
+    bgValue: string;
+    ratio: number;
+    required: number;
+    level: 'AA' | 'AAA';
+}
+/** Immutable state for the theme editor with undo/redo support. */
+interface ThemeEditorState {
+    current: Record<string, string>;
+    saved: Record<string, string>;
+    undoStack: Record<string, string>[];
+    redoStack: Record<string, string>[];
+    isDirty: boolean;
+}
+/** A group of related design tokens. */
+interface TokenCategory$1 {
+    label: string;
+    keys: string[];
+}
+
+interface DesignSystemAdapter {
+    loadTheme(): Promise<Record<string, string>>;
+    saveTheme(overrides: Record<string, string>): Promise<void>;
+    listPresets(): Promise<CustomPreset[]>;
+    savePreset(name: string, values: Record<string, string>): Promise<CustomPreset>;
+    deletePreset(id: string): Promise<void>;
+    renamePreset(id: string, newName: string): Promise<void>;
+    duplicatePreset(id: string): Promise<CustomPreset>;
+    saveVersion(current: Record<string, string>, previous: Record<string, string>, label?: string): Promise<ThemeVersion>;
+    listVersions(): Promise<ThemeVersion[]>;
+    restoreVersion(versionId: string): Promise<Record<string, string>>;
+}
+
+/**
+ * Colour utilities - pure functions for colour manipulation,
+ * contrast checking, and palette generation.
+ *
+ * Self-contained - no external dependencies.
+ */
+
+/** Lighten a hex colour by mixing with white. `amount` 0-1 (0=original, 1=white). */
+declare function lighten(hex: string, amount: number): string;
+/** Darken a hex colour by mixing with black. `amount` 0-1 (0=original, 1=black). */
+declare function darken(hex: string, amount: number): string;
+/** Relative luminance per WCAG 2.0 definition. */
+declare function luminance(hex: string): number;
+/** Returns true if the background is dark (text should be light). */
+declare function isDark(hex: string): boolean;
+/** WCAG AA contrast ratio between two hex colours. */
+declare function contrastRatio(fg: string, bg: string): number;
+/**
+ * Ensure a colour meets WCAG AA contrast (4.5:1) against white.
+ * If it doesn't, darken it incrementally until it does.
+ */
+declare function ensureContrastOnWhite(hex: string): string;
+/** Convert a hex colour (#rrggbb) to HSL. */
+declare function hexToHSL(hex: string): HSL;
+/** Convert HSL back to hex. */
+declare function hslToHex$1(hsl: HSL): string;
+/** Rotate hue by a given number of degrees. */
+declare function rotateHue(hsl: HSL, degrees: number): HSL;
+/**
+ * Generate a full lightness scale (50-950) from a base colour,
+ * varying lightness while preserving hue and saturation.
+ */
+declare function generateScale(hex: string): string[];
+/**
+ * Given a primary hex colour, generate palette suggestions
+ * using four colour harmony rules.
+ */
+declare function suggestPalettes(primaryHex: string): ColourSuggestion[];
+
+/**
+ * Theme defaults, CSS variable mappings, and token categories.
+ * These are the canonical defaults for the design system package.
+ */
+
+/**
+ * The hardcoded defaults matching a standard design system theme.
+ * These are the "factory" values used when no overrides are set.
+ */
+declare const THEME_DEFAULTS: Record<string, string>;
+/**
+ * Maps theme JSON keys to the CSS custom properties they control.
+ */
+declare const THEME_KEY_TO_CSS: Record<string, string>;
+/**
+ * Grouped theme categories for the editor UI.
+ * Each entry groups related theme keys for display in a settings panel.
+ */
+declare const THEME_CATEGORIES: TokenCategory$1[];
+
+/**
+ * Theme Editor State - pure state management for the design system editor.
+ * Provides undo/redo, dirty detection, and immutable state transitions.
+ */
+
+declare function createThemeEditorState(initial: Record<string, string>): ThemeEditorState;
+declare function applyChange(state: ThemeEditorState, key: string, value: string): ThemeEditorState;
+declare function applyBulkChange(state: ThemeEditorState, changes: Record<string, string>): ThemeEditorState;
+declare function undo(state: ThemeEditorState): ThemeEditorState;
+declare function redo(state: ThemeEditorState): ThemeEditorState;
+declare function markSaved(state: ThemeEditorState): ThemeEditorState;
+declare function resetToDefaults(state: ThemeEditorState, defaults: Record<string, string>): ThemeEditorState;
+
+/**
+ * Token Registry - maps the three-tier token system.
+ *
+ * Primitive: raw values (brand-600 = #2563eb)
+ * Semantic: purpose-bound (btn-primary-bg = brand-600)
+ * Component: specific usage (a specific button instance's background)
+ *
+ * This registry is the source of truth for the inspector to trace
+ * any computed value back through the chain.
+ */
+interface TokenDefinition {
+    /** CSS custom property name (e.g. '--color-btn-primary-bg') */
+    cssVar: string;
+    /** Human-readable label */
+    label: string;
+    /** Token category */
+    category: 'colour' | 'typography' | 'spacing' | 'border' | 'shadow' | 'motion';
+    /** What CSS var it references (if any) - for chain tracing */
+    references?: string;
+    /** Which ThemeProvider key controls this (if themeable) */
+    themeKey?: string;
+    /** Default value (resolved) */
+    defaultValue: string;
+}
+interface TokenCategory {
+    label: string;
+    tokens: TokenDefinition[];
+}
+declare const TOKEN_REGISTRY: TokenCategory[];
+/**
+ * Find a token by its CSS custom property name.
+ */
+declare function findToken(cssVar: string): TokenDefinition | undefined;
+/**
+ * Get the full reference chain for a CSS var.
+ * Returns an array from the given token through to the final primitive.
+ * e.g. --color-btn-primary-bg -> --color-brand-600 -> (primitive, no further reference)
+ */
+declare function getTokenChain(cssVar: string): TokenDefinition[];
+/**
+ * List all tokens that reference the given CSS var (reverse lookup).
+ */
+declare function getDependents(cssVar: string): TokenDefinition[];
+
+/**
+ * Colour blindness simulation - transforms hex colours to simulate
+ * how they appear under different types of colour vision deficiency.
+ *
+ * Uses Brettel/Vienot colour blindness simulation matrices.
+ * Pure functions, no side effects.
+ */
+type ColourBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia' | 'achromatopsia';
+interface ColourBlindnessInfo {
+    type: ColourBlindnessType;
+    label: string;
+    description: string;
+    prevalence: string;
+}
+declare const COLOUR_BLINDNESS_TYPES: ColourBlindnessInfo[];
+/**
+ * Simulate how a hex colour appears under a specific colour blindness type.
+ */
+declare function simulateColourBlindness(hex: string, type: ColourBlindnessType): string;
+/**
+ * Simulate colour blindness across a full theme's colour values.
+ * Returns a new Record with transformed values.
+ */
+declare function simulateThemeColourBlindness(theme: Record<string, string>, type: ColourBlindnessType): Record<string, string>;
+
+/**
+ * Theme Snapshots - auto-captured theme state for the time machine.
+ * Stored in localStorage per tenant. Capped at 50 snapshots.
+ *
+ * Snapshots are captured:
+ * 1. When the editor opens (opening snapshot - guaranteed restore point)
+ * 2. Every 5 minutes if changes have been made
+ * 3. On manual save
+ */
+interface ThemeSnapshot {
+    id: string;
+    timestamp: string;
+    label: 'opening' | 'auto' | 'save';
+    values: Record<string, string>;
+    changedKeysFromPrevious: number;
+}
+/**
+ * Check if two theme objects are identical.
+ */
+declare function themesAreEqual(a: Record<string, string>, b: Record<string, string>): boolean;
+/**
+ * Read all snapshots for a tenant from localStorage.
+ */
+declare function readSnapshots(tenantId: string): ThemeSnapshot[];
+/**
+ * Capture a new snapshot. Returns the snapshot if captured,
+ * null if skipped (no changes since last snapshot).
+ */
+declare function captureSnapshot(tenantId: string, values: Record<string, string>, label: ThemeSnapshot['label']): ThemeSnapshot | null;
+/**
+ * Get a specific snapshot by ID.
+ */
+declare function getSnapshot(tenantId: string, snapshotId: string): ThemeSnapshot | null;
+/**
+ * Clear all snapshots for a tenant (e.g. on editor close).
+ */
+declare function clearSnapshots(tenantId: string): void;
+/**
+ * Get the opening snapshot (first one with label 'opening').
+ */
+declare function getOpeningSnapshot(tenantId: string): ThemeSnapshot | null;
+
+/**
+ * Font Pairing Recommender - curated list of web-safe font pairings
+ * with relevance scoring based on the current font selection.
+ *
+ * Pure functions, no side effects.
+ */
+interface FontPairing {
+    display: string;
+    body: string;
+    label: string;
+    description: string;
+    category: 'sans' | 'serif' | 'mixed';
+}
+/**
+ * Curated web-safe font pairings. Uses system-available and widely
+ * supported fonts only - no external font service dependency.
+ */
+declare const FONT_PAIRINGS: FontPairing[];
+/**
+ * Suggest font pairings sorted by relevance to the current font.
+ */
+declare function suggestPairings(currentFont: string): FontPairing[];
+
+/**
+ * Type Scale Generator - generates a harmonious set of font sizes
+ * from a base size and a ratio.
+ *
+ * Used by the design system manager to produce consistent typography
+ * tokens across the application.
+ */
+type ScaleRatio = 'minor-third' | 'major-third' | 'perfect-fourth' | 'augmented-fourth' | 'perfect-fifth' | 'golden-ratio';
+declare const SCALE_RATIOS: Record<ScaleRatio, {
+    value: number;
+    label: string;
+    description: string;
+}>;
+interface TypeScaleLevel {
+    /** Semantic name, e.g. 'h1', 'body-md' */
+    name: string;
+    /** Size in pixels */
+    size: number;
+    /** Size as a rem string, e.g. '1.875rem' */
+    sizeRem: string;
+    /** Line-height ratio, e.g. 1.2 */
+    lineHeight: number;
+    /** Font weight, e.g. 700 */
+    weight: number;
+}
+interface TypeScale {
+    baseSizePx: number;
+    ratio: ScaleRatio;
+    levels: TypeScaleLevel[];
+}
+/**
+ * Generate a type scale from a base size and ratio.
+ * Returns h1-h4, body-lg, body-md (base), body-sm, caption.
+ */
+declare function generateTypeScale(baseSizePx: number, ratio: ScaleRatio): TypeScale;
+/**
+ * Convert a type scale to CSS custom properties suitable for injection into @theme.
+ * Returns a record like { '--font-size-h1': '2.441rem', '--line-height-h1': '1.15', ... }
+ */
+declare function typeScaleToCSSVars(scale: TypeScale): Record<string, string>;
+
+/**
+ * Bezier Utilities - parse, format, sample, and manipulate cubic-bezier values.
+ */
+/**
+ * Parse a CSS cubic-bezier string into its four control values.
+ * Accepts formats: "cubic-bezier(x1, y1, x2, y2)" or just "x1, y1, x2, y2".
+ * Returns null if the string cannot be parsed.
+ */
+declare function parseCubicBezier(value: string): [number, number, number, number] | null;
+/**
+ * Format four bezier control values into a CSS cubic-bezier() string.
+ */
+declare function formatCubicBezier(x1: number, y1: number, x2: number, y2: number): string;
+/**
+ * Sample points along a cubic bezier curve for SVG path rendering.
+ * Returns an array of { x, y } points from t=0 to t=1.
+ */
+declare function sampleBezierCurve(x1: number, y1: number, x2: number, y2: number, steps?: number): {
+    x: number;
+    y: number;
+}[];
+/**
+ * Clamp a control point value to valid ranges.
+ * X values are clamped to [0, 1], Y values to [-0.5, 1.5] for bounce effects.
+ */
+declare function clampControlPoint(value: number, axis: 'x' | 'y'): number;
+/**
+ * Snap a value to the nearest grid increment.
+ */
+declare function snapToGrid(value: number, gridSize: number): number;
+
+/**
+ * Easing Presets - named easing presets with cubic-bezier values,
+ * grouped by category (basic, material, expressive).
+ */
+interface EasingPreset {
+    label: string;
+    value: string;
+    description: string;
+    category: 'basic' | 'material' | 'expressive';
+}
+declare const EASING_PRESETS: EasingPreset[];
+/**
+ * Get presets grouped by category.
+ */
+declare function getPresetsByCategory(): Record<string, EasingPreset[]>;
+/**
+ * Find a preset by its CSS value.
+ */
+declare function findPresetByValue(value: string): EasingPreset | undefined;
+
+/**
+ * Registry Overlay - layers token reassignment operations on top of the
+ * static TOKEN_REGISTRY without mutating it.
+ *
+ * Supports moving tokens between categories, adding custom categories,
+ * and extracting new tokens.
+ */
+
+interface ExtractedTokenDef {
+    cssVar: string;
+    label: string;
+    category: string;
+    defaultValue: string;
+    referencesVar?: string;
+}
+interface RegistryOverlay {
+    /** cssVar -> new category label */
+    moves: Map<string, string>;
+    /** User-created category names */
+    customCategories: string[];
+    /** Tokens extracted from hardcoded values */
+    extractedTokens: ExtractedTokenDef[];
+}
+declare function createOverlay(): RegistryOverlay;
+declare function moveToken(overlay: RegistryOverlay, cssVar: string, targetCategory: string): RegistryOverlay;
+declare function bulkMoveTokens(overlay: RegistryOverlay, cssVars: string[], targetCategory: string): RegistryOverlay;
+declare function addCustomCategory(overlay: RegistryOverlay, label: string): RegistryOverlay;
+declare function addExtractedToken(overlay: RegistryOverlay, token: ExtractedTokenDef): RegistryOverlay;
+/**
+ * Compute the effective categories by applying overlay moves and extracted
+ * tokens on top of the static registry.
+ */
+declare function getEffectiveCategories(overlay: RegistryOverlay): TokenCategory[];
+/** Get all category labels (static + custom). */
+declare function getAllCategoryLabels(overlay: RegistryOverlay): string[];
+/** Find which category a token currently belongs to (considering moves). */
+declare function getTokenCategory(overlay: RegistryOverlay, cssVar: string): string | undefined;
+
+/**
+ * Token Extraction - validates and creates new token definitions from
+ * hardcoded CSS values.
+ */
+
+/**
+ * Validate a proposed token name (CSS custom property format).
+ * Must be lowercase with hyphens only, starting with --.
+ */
+declare function validateTokenName(name: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Suggest a token name based on the value and target category.
+ */
+declare function suggestTokenName(value: string, category: string): string;
+/**
+ * Extract a hardcoded value into a new named token in the overlay.
+ */
+declare function extractToken(overlay: RegistryOverlay, token: ExtractedTokenDef): RegistryOverlay;
+/**
+ * Check if an overlay already contains an extracted token with the given cssVar.
+ */
+declare function hasExtractedToken(overlay: RegistryOverlay, cssVar: string): boolean;
+
+/**
+ * Reassignment State - undo/redo state management for token reassignment
+ * operations. Follows an immutable pattern.
+ */
+
+interface ReassignmentAction {
+    type: 'move' | 'extract' | 'bulk-move' | 'add-category';
+    before: RegistryOverlay;
+    after: RegistryOverlay;
+    description: string;
+}
+interface ReassignmentState {
+    overlay: RegistryOverlay;
+    undoStack: ReassignmentAction[];
+    redoStack: ReassignmentAction[];
+}
+declare function createReassignmentState(): ReassignmentState;
+declare function applyMove(state: ReassignmentState, cssVar: string, targetCategory: string, tokenLabel?: string): ReassignmentState;
+declare function applyBulkMove(state: ReassignmentState, cssVars: string[], targetCategory: string): ReassignmentState;
+declare function applyExtract(state: ReassignmentState, token: ExtractedTokenDef): ReassignmentState;
+declare function applyAddCategory(state: ReassignmentState, label: string): ReassignmentState;
+declare function undoReassignment(state: ReassignmentState): ReassignmentState;
+declare function redoReassignment(state: ReassignmentState): ReassignmentState;
+
+/**
+ * Token Usage Counter - scans the DOM to determine which CSS custom property
+ * tokens are actively in use and by how many elements.
+ */
+interface TokenUsageResult {
+    cssVar: string;
+    label: string;
+    count: number;
+    /** First 5 elements using this token (for preview) */
+    elements: HTMLElement[];
+}
+/**
+ * Count how many DOM elements use each token.
+ * If cssVar is provided, counts only that token.
+ * Otherwise counts all tokens (expensive - use sparingly).
+ */
+declare function countTokenUsage(cssVar?: string): TokenUsageResult[];
+/**
+ * Get usage count for a single token (uses cache if available).
+ */
+declare function getTokenUsageCount(cssVar: string): number;
+/**
+ * Clear the usage cache to force a fresh scan on next call.
+ */
+declare function clearUsageCache(): void;
+
+/**
+ * Unused Token Scanner - detects design tokens that are defined
+ * but not referenced in any component CSS.
+ *
+ * Uses DOM scanning to find which CSS custom properties are actually
+ * in use. Runs client-side only.
+ */
+
+interface UnusedTokenResult {
+    token: TokenDefinition;
+    /** Whether it's referenced by another token (chain dependency) */
+    isChainDependency: boolean;
+}
+/**
+ * Find tokens that are defined in the registry but not used in any
+ * stylesheet or inline style.
+ */
+declare function findUnusedTokens(): UnusedTokenResult[];
+/**
+ * Get usage statistics for the token registry.
+ */
+declare function getTokenUsageStats(): {
+    total: number;
+    used: number;
+    unused: number;
+    chainDependencies: number;
+    usageRate: number;
+};
+
+/**
+ * Dark Mode - generates dark theme variants by intelligently inverting
+ * colour lightness while preserving hue for semantic colours.
+ *
+ * Strategy:
+ *  - Surface colours: swap lightness (light becomes dark)
+ *  - Text colours: swap lightness (dark becomes light)
+ *  - Semantic colours: keep hue, adjust lightness for dark backgrounds
+ *  - Border colours: lighten for visibility on dark surfaces
+ *  - Brand colours: keep hue, shift lightness range
+ */
+/** Convert hex (#rrggbb) to HSL {h: 0-360, s: 0-100, l: 0-100}. */
+declare function hexToHsl(hex: string): {
+    h: number;
+    s: number;
+    l: number;
+};
+/** Convert HSL {h: 0-360, s: 0-100, l: 0-100} to hex (#rrggbb). */
+declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Invert the lightness of a hex colour.
+ * L: 95 becomes 5, L: 10 becomes 90, etc.
+ */
+declare function invertLightness(hex: string): string;
+/**
+ * Adjust a semantic colour for dark mode - keeps hue, reduces saturation
+ * slightly, and shifts lightness to work on dark backgrounds.
+ */
+declare function adjustSemanticForDark(hex: string, _semanticType?: string): string;
+interface DarkModeConfig {
+    surfaceInversion: Record<string, string>;
+    textInversion: Record<string, string>;
+    semanticAdjustments: Record<string, string>;
+    borderAdjustments: Record<string, string>;
+}
+/**
+ * Generate a complete dark theme from a light theme.
+ * Returns a Record of CSS variable name -> dark hex value.
+ */
+declare function generateDarkTheme(lightTheme?: Record<string, string>): Record<string, string>;
+/** Check whether dark mode is currently active. */
+declare function isDarkMode(): boolean;
+/** Apply or remove the dark mode class from documentElement. */
+declare function setDarkMode(enabled: boolean): void;
+/** Check system colour scheme preference. */
+declare function systemPrefersDark(): boolean;
+/**
+ * Resolve a dark mode preference to a concrete light/dark value.
+ */
+declare function resolveMode(mode: 'light' | 'dark' | 'system'): 'light' | 'dark';
+/**
+ * Apply dark mode to the DOM based on the user preference.
+ */
+declare function applyDarkModeToDOM(mode: 'light' | 'dark' | 'system'): void;
+
+/**
+ * Surface Override System - context-specific theme overrides for different
+ * environments: kiosk (touchscreen), print, outdoor, low-light.
+ *
+ * Each surface is a partial theme override applied on top of the base theme
+ * (and dark mode). Cascade:
+ *   THEME_DEFAULTS < tenant_defaults < profile_overrides < dark_mode < surface
+ */
+type SurfaceType = 'default' | 'kiosk' | 'print' | 'outdoor' | 'low-light';
+interface SurfaceDefinition {
+    id: SurfaceType;
+    name: string;
+    description: string;
+    overrides: Record<string, string>;
+    cssClass: string;
+}
+declare const SURFACE_DEFINITIONS: SurfaceDefinition[];
+/** Get the override map for a given surface type. */
+declare function getSurfaceOverrides(surfaceType: SurfaceType): Record<string, string>;
+/** Get the full definition for a surface type. */
+declare function getSurfaceDefinition(surfaceType: SurfaceType): SurfaceDefinition | undefined;
+/** Apply a surface to the DOM - sets CSS class and variable overrides. */
+declare function applySurface(surfaceType: SurfaceType): void;
+/** Remove all surface overrides from the DOM. */
+declare function clearSurface(): void;
+/** Get the currently active surface from DOM classes. */
+declare function getActiveSurface(): SurfaceType;
+/**
+ * Apply surface to the DOM.
+ */
+declare function applySurfaceToDOM(surface: SurfaceType): void;
+
+/**
+ * Density Modes - compact, default, and comfortable spacing modes.
+ *
+ * Each mode applies a multiplier to spacing tokens and subtle adjustments
+ * to font size and line height via CSS custom properties.
+ */
+type DensityMode = 'compact' | 'default' | 'comfortable';
+interface DensityConfig {
+    mode: DensityMode;
+    label: string;
+    description: string;
+    spacingMultiplier: number;
+    fontSizeAdjust: number;
+    lineHeightAdjust: number;
+}
+declare const DENSITY_CONFIGS: Record<DensityMode, DensityConfig>;
+/**
+ * Get CSS variable overrides for a given density mode.
+ * Returns spacing tokens multiplied by the density factor,
+ * plus font-size and line-height adjustment variables.
+ */
+declare function getDensityCSS(mode: DensityMode): Record<string, string>;
+/** Apply density mode to the DOM. */
+declare function applyDensity(mode: DensityMode): void;
+/** Get the currently active density from DOM classes. */
+declare function getActiveDensity(): DensityMode;
+/**
+ * Apply density to the DOM.
+ */
+declare function applyDensityToDOM(density: DensityMode): void;
+
+/**
+ * Built-in theme presets for the design system editor.
+ * Each preset provides a complete set of theme overrides.
+ */
+interface ThemePreset {
+    id: string;
+    name: string;
+    description: string;
+    category: 'professional' | 'vibrant' | 'dark' | 'warm' | 'custom';
+    values: Record<string, string>;
+    preview: {
+        primary: string;
+        surface: string;
+        text: string;
+        accent: string;
+    };
+}
+/**
+ * Build a full preset by merging overrides onto THEME_DEFAULTS.
+ * Ensures every preset has complete key coverage.
+ */
+declare function makePreset(base: Omit<ThemePreset, 'values'> & {
+    overrides: Record<string, string>;
+}): ThemePreset;
+declare const BUILT_IN_PRESETS: ThemePreset[];
+/** Look up a built-in preset by ID. */
+declare function findPreset(id: string): ThemePreset | undefined;
+
+/**
+ * Theme export/import - JSON file operations for theme sharing.
+ */
+interface ThemeExportPayload {
+    version: 1;
+    name: string;
+    exportedAt: string;
+    values: Record<string, string>;
+    metadata?: {
+        presetId?: string;
+        tenantName?: string;
+    };
+}
+/**
+ * Create a ThemeExportPayload object from the current theme state.
+ */
+declare function exportTheme(current: Record<string, string>, name: string, metadata?: ThemeExportPayload['metadata']): ThemeExportPayload;
+/**
+ * Validate an imported theme JSON structure.
+ * Returns validation result with parsed data or errors.
+ */
+declare function validateImport(data: unknown): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    parsed?: ThemeExportPayload;
+};
+/**
+ * Trigger a browser download of the theme as a JSON file.
+ */
+declare function downloadThemeAsJSON(theme: ThemeExportPayload): void;
+/**
+ * Read a theme from a File object (from file picker).
+ */
+declare function readThemeFromFile(file: File): Promise<ThemeExportPayload>;
+
+/**
+ * W3C Design Tokens Format - exports the token registry to the
+ * W3C Community Group Design Tokens Format specification.
+ *
+ * See: https://design-tokens.github.io/community-group/format/
+ */
+interface W3CToken {
+    $type: string;
+    $value: string;
+    $description?: string;
+    $extensions?: Record<string, unknown>;
+}
+type W3CGroup = {
+    [key: string]: W3CToken | W3CGroup;
+};
+/**
+ * Export the full token registry in W3C Design Tokens format.
+ */
+declare function exportToW3CFormat(overrides?: Record<string, string>): W3CGroup;
+/**
+ * Download the W3C tokens as a JSON file.
+ */
+declare function downloadW3CTokens(overrides?: Record<string, string>): void;
+
+/**
+ * Style Guide Export - generates a comprehensive markdown style guide
+ * from the token registry, theme values, and component patterns.
+ */
+/**
+ * Generate a comprehensive markdown style guide.
+ */
+declare function generateStyleGuide(overrides?: Record<string, string>): string;
+declare function downloadStyleGuide(overrides?: Record<string, string>): void;
+
+/**
+ * Audit Report Generator - produces a structured markdown report
+ * from quality score, contrast checker, and consistency checker.
+ *
+ * NOTE: Session A creates quality-score.ts, contrast-checker.ts, and
+ * consistency-checker.ts. Until those are merged, this file uses local
+ * type stubs and placeholder implementations.
+ */
+interface QualityBreakdown$1 {
+    overall: number;
+    colourHarmony: number;
+    contrastCompliance: number;
+    typographyConsistency: number;
+    spacingRegularity: number;
+}
+interface ContrastIssue$1 {
+    foregroundLabel: string;
+    foregroundHex: string;
+    backgroundLabel: string;
+    backgroundHex: string;
+    ratio: number;
+    requiredRatio: number;
+    suggestedFix: string;
+}
+interface ConsistencyIssue$1 {
+    severity: 'warning' | 'error';
+    category: string;
+    message: string;
+    suggestion: string;
+}
+interface AuditReport {
+    generatedAt: string;
+    quality: QualityBreakdown$1;
+    contrastIssues: ContrastIssue$1[];
+    consistencyIssues: ConsistencyIssue$1[];
+    tokenStats: {
+        total: number;
+        byCategory: Record<string, number>;
+        themeable: number;
+    };
+    summary: string;
+}
+declare function generateAuditReport(overrides?: Record<string, string>): AuditReport;
+declare function auditReportToMarkdown(report: AuditReport): string;
+declare function downloadAuditReport(report: AuditReport): void;
+
+/**
+ * DOM utilities for applying and clearing theme values on the document root.
+ * These functions set/remove CSS custom properties on document.documentElement.
+ */
+/**
+ * Apply a merged theme to the DOM by setting CSS custom properties on :root.
+ * Derives sidebar states and accent variants automatically.
+ */
+declare function applyThemeToDOM(merged: Record<string, string>): void;
+/** Remove all theme overrides from :root, restoring CSS defaults. */
+declare function clearThemeFromDOM(): void;
+
+/**
+ * Contrast Fix Engine - scans colour token pairs for WCAG AA failures
+ * and suggests fixes by adjusting foreground lightness/darkness.
+ *
+ * Pure functions, no side effects.
+ */
+interface ContrastIssue {
+    foregroundVar: string;
+    backgroundVar: string;
+    foregroundLabel: string;
+    backgroundLabel: string;
+    foregroundHex: string;
+    backgroundHex: string;
+    ratio: number;
+    requiredRatio: number;
+    suggestedFix: string;
+    level: 'AA' | 'AAA';
+    themeKey?: string;
+}
+/**
+ * Suggest a fix for a foreground colour that fails contrast against
+ * a background. Adjusts the foreground by darkening or lightening
+ * until the target ratio is met.
+ */
+declare function suggestFix(fg: string, bg: string, targetRatio: number): string;
+/**
+ * Find all contrast issues in the current theme.
+ * Pass overrides to check customised values; defaults to THEME_DEFAULTS.
+ */
+declare function findContrastIssues(overrides?: Record<string, string>): ContrastIssue[];
+
+/**
+ * Border/Shape Consistency Checker - scans token values for
+ * inconsistencies in border radius, border width, and spacing.
+ *
+ * Pure functions, no side effects.
+ */
+interface ConsistencyIssue {
+    severity: 'warning' | 'info';
+    category: 'border' | 'radius' | 'spacing';
+    message: string;
+    affectedTokens: string[];
+    suggestion: string;
+}
+/**
+ * Run all consistency checks and return combined issues.
+ * Optionally pass token overrides to check against modified values.
+ */
+declare function checkConsistency(overrides?: Record<string, string>): ConsistencyIssue[];
+
+/**
+ * Design Quality Score - composite score (0-100) computed from
+ * colour harmony, contrast compliance, typography consistency,
+ * and spacing regularity.
+ *
+ * Pure functions, no side effects.
+ */
+interface QualityBreakdown {
+    overall: number;
+    colourHarmony: number;
+    contrastCompliance: number;
+    typographyConsistency: number;
+    spacingRegularity: number;
+}
+/**
+ * Calculate the overall design quality score and breakdown.
+ * Pass overrides to score customised theme values.
+ */
+declare function calculateQualityScore(overrides?: Record<string, string>): QualityBreakdown;
+
+export { type ConsistencyIssue$1 as AuditConsistencyIssue, type ContrastIssue$1 as AuditContrastIssue, type QualityBreakdown$1 as AuditQualityBreakdown, type AuditReport, BUILT_IN_PRESETS, COLOUR_BLINDNESS_TYPES, type ColourBlindnessInfo, type ColourBlindnessType, type ColourSuggestion, type ConsistencyIssue, type ContrastIssue$2 as ContrastIssue, type CustomPreset, DENSITY_CONFIGS, type DarkModeConfig, type DensityConfig, type DensityMode, type DesignSystemAdapter, type ThemePreset as DesignThemePreset, EASING_PRESETS, type EasingPreset, type ExtractedTokenDef, FONT_PAIRINGS, type FontPairing, type HSL, type HarmonyType, type QualityBreakdown$2 as QualityBreakdown, type ReassignmentAction, type ReassignmentState, type RegistryOverlay, SCALE_RATIOS, SURFACE_DEFINITIONS, type ScaleRatio, type SurfaceDefinition, type SurfaceType, THEME_CATEGORIES, THEME_DEFAULTS, THEME_KEY_TO_CSS, TOKEN_REGISTRY, type ThemeEditorState, type ThemeExport, type ThemeExportPayload, type ThemePreset$1 as ThemePreset, type ThemeSnapshot, type ThemeVersion, type TokenCategory, type TokenDefinition, type TokenUsageResult, type TypeScale, type TypeScaleLevel, type UnusedTokenResult, addCustomCategory, addExtractedToken, adjustSemanticForDark, applyAddCategory, applyBulkChange, applyBulkMove, applyChange, applyDarkModeToDOM, applyDensity, applyDensityToDOM, applyExtract, applyMove, applySurface, applySurfaceToDOM, applyThemeToDOM, auditReportToMarkdown, bulkMoveTokens, calculateQualityScore, captureSnapshot, checkConsistency, clampControlPoint, clearSnapshots, clearSurface, clearThemeFromDOM, clearUsageCache, contrastRatio, countTokenUsage, createOverlay, createReassignmentState, createThemeEditorState, darken, downloadAuditReport, downloadStyleGuide, downloadThemeAsJSON, downloadW3CTokens, ensureContrastOnWhite, exportTheme, exportToW3CFormat, extractToken, findContrastIssues, findPreset, findPresetByValue, findToken, findUnusedTokens, formatCubicBezier, generateAuditReport, generateDarkTheme, generateScale, generateStyleGuide, generateTypeScale, getActiveDensity, getActiveSurface, getAllCategoryLabels, getDensityCSS, getDependents, getEffectiveCategories, getOpeningSnapshot, getPresetsByCategory, getSnapshot, getSurfaceDefinition, getSurfaceOverrides, getTokenCategory, getTokenChain, getTokenUsageCount, getTokenUsageStats, hasExtractedToken, hexToHSL, hexToHsl, hslToHex$1 as hslToHex, hslToHex as hslToHexDark, invertLightness, isDark, isDarkMode, lighten, luminance, makePreset, markSaved, moveToken, parseCubicBezier, readSnapshots, readThemeFromFile, redo, redoReassignment, resetToDefaults, resolveMode, rotateHue, sampleBezierCurve, setDarkMode, simulateColourBlindness, simulateThemeColourBlindness, snapToGrid, suggestFix, suggestPairings, suggestPalettes, suggestTokenName, systemPrefersDark, themesAreEqual, typeScaleToCSSVars, undo, undoReassignment, validateImport, validateTokenName };