@ansh-ui/tokens 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,815 @@
+/**
+ * Primitive design tokens.
+ *
+ * These are the raw values — the vocabulary. Semantic tokens (in `semantic.ts`) map *meaning*
+ * onto them, and that indirection is what makes theming possible: `--ansh-surface` can point
+ * at `slate.50` in light mode and `slate.950` in dark mode without any component changing.
+ *
+ * Every scale here is derived from a rule rather than hand-picked, so extending it is
+ * unambiguous and a designer can predict what step 9 looks like without checking.
+ */
+/**
+ * Spacing — an 8-point grid with half-steps below 8px.
+ *
+ * The half-steps matter: 8px is too coarse for optical adjustments like the gap between an icon
+ * and its label, and every design system that omits them ends up with arbitrary one-off values.
+ * Named by their pixel value at the default root size so `space[4]` is unambiguously 16px.
+ */
+declare const space: {
+    readonly 0: "0";
+    readonly px: "1px";
+    readonly 0.5: "0.125rem";
+    readonly 1: "0.25rem";
+    readonly 1.5: "0.375rem";
+    readonly 2: "0.5rem";
+    readonly 3: "0.75rem";
+    readonly 4: "1rem";
+    readonly 5: "1.25rem";
+    readonly 6: "1.5rem";
+    readonly 8: "2rem";
+    readonly 10: "2.5rem";
+    readonly 12: "3rem";
+    readonly 16: "4rem";
+    readonly 20: "5rem";
+    readonly 24: "6rem";
+    readonly 32: "8rem";
+    readonly 40: "10rem";
+    readonly 48: "12rem";
+    readonly 56: "14rem";
+    readonly 64: "16rem";
+};
+/**
+ * Typography — a modular scale at ratio 1.2 (minor third), rounded to sensible pixel values.
+ *
+ * 1.2 rather than the more common 1.25 or golden ratio: on the wide viewports these components
+ * target, a steeper ratio makes display sizes enormous before the body sizes have room to
+ * differentiate. 1.2 gives eight useful steps between 12px and 60px.
+ *
+ * Each step pairs a size with a line height, because a size without its leading is not a
+ * typographic decision — and line height must *decrease* proportionally as size increases.
+ */
+declare const fontSize: {
+    readonly xs: readonly ["0.75rem", {
+        readonly lineHeight: "1.125rem";
+        readonly letterSpacing: "0.01em";
+    }];
+    readonly sm: readonly ["0.875rem", {
+        readonly lineHeight: "1.375rem";
+        readonly letterSpacing: "0.005em";
+    }];
+    readonly base: readonly ["1rem", {
+        readonly lineHeight: "1.625rem";
+        readonly letterSpacing: "0";
+    }];
+    readonly lg: readonly ["1.125rem", {
+        readonly lineHeight: "1.75rem";
+        readonly letterSpacing: "-0.005em";
+    }];
+    readonly xl: readonly ["1.25rem", {
+        readonly lineHeight: "1.875rem";
+        readonly letterSpacing: "-0.01em";
+    }];
+    readonly '2xl': readonly ["1.5rem", {
+        readonly lineHeight: "2rem";
+        readonly letterSpacing: "-0.015em";
+    }];
+    readonly '3xl': readonly ["1.875rem", {
+        readonly lineHeight: "2.375rem";
+        readonly letterSpacing: "-0.02em";
+    }];
+    readonly '4xl': readonly ["2.25rem", {
+        readonly lineHeight: "2.625rem";
+        readonly letterSpacing: "-0.025em";
+    }];
+    readonly '5xl': readonly ["3rem", {
+        readonly lineHeight: "3.25rem";
+        readonly letterSpacing: "-0.03em";
+    }];
+    readonly '6xl': readonly ["3.75rem", {
+        readonly lineHeight: "3.9rem";
+        readonly letterSpacing: "-0.035em";
+    }];
+    readonly '7xl': readonly ["4.5rem", {
+        readonly lineHeight: "4.6rem";
+        readonly letterSpacing: "-0.04em";
+    }];
+};
+declare const fontWeight: {
+    readonly normal: "400";
+    readonly medium: "500";
+    readonly semibold: "600";
+    readonly bold: "700";
+};
+declare const fontFamily: {
+    /**
+     * The system UI stack. Deliberately not a webfont: the fastest, most legible text on any
+     * platform is the font the user's OS already has loaded, and a design system should not force
+     * a font decision on its consumers.
+     */
+    readonly sans: string;
+    readonly mono: string;
+};
+/** Corner radii. `full` is a large fixed value rather than 50%, so pills stay pill-shaped. */
+declare const radius: {
+    readonly none: "0";
+    readonly xs: "0.25rem";
+    readonly sm: "0.375rem";
+    readonly md: "0.5rem";
+    readonly lg: "0.75rem";
+    readonly xl: "1rem";
+    readonly '2xl': "1.5rem";
+    readonly '3xl': "2rem";
+    readonly full: "9999px";
+};
+/**
+ * Elevation — layered shadows, not single ones.
+ *
+ * A single `box-shadow` cannot describe real light: an object casts both a tight contact shadow
+ * directly beneath it and a broader ambient shadow further out. Every step here composes both,
+ * which is the difference between a card that sits on the page and one that looks pasted onto it.
+ *
+ * Shadow colour is a token so it can shift with the theme — a pure-black shadow on a dark
+ * surface is invisible, so the dark theme uses a deeper, more spread variant.
+ */
+declare const shadow: {
+    readonly none: "none";
+    readonly xs: "0 1px 2px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.05))";
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+    readonly '2xl': "0 25px 50px -12px var(--ansh-shadow-color, rgb(15 23 42 / 0.2))";
+    /** Inset — for pressed states and inputs. */
+    readonly inner: "inset 0 2px 4px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.06))";
+    /**
+     * Glow. Uses `currentColor` so a button's glow automatically matches its own accent without
+     * the author repeating the colour.
+     */
+    readonly glow: "0 0 24px -4px currentColor";
+    readonly glowLg: "0 0 48px -8px currentColor";
+};
+/** Backdrop blur steps, for glass surfaces. */
+declare const blur: {
+    readonly none: "0";
+    readonly xs: "2px";
+    readonly sm: "4px";
+    readonly md: "8px";
+    readonly lg: "16px";
+    readonly xl: "24px";
+    readonly '2xl': "40px";
+    readonly '3xl': "64px";
+};
+/**
+ * Motion durations in seconds.
+ *
+ * Named by intent rather than by number. The values follow a rule of thumb that holds up well:
+ * the distance travelled should determine the duration, so a tooltip appearing in place is
+ * `instant`, a dropdown is `fast`, and a full-screen sheet is `slow`.
+ */
+declare const duration: {
+    readonly instant: "0.1s";
+    readonly fast: "0.2s";
+    readonly normal: "0.3s";
+    readonly moderate: "0.45s";
+    readonly slow: "0.6s";
+    readonly slower: "0.9s";
+    readonly deliberate: "1.2s";
+};
+/**
+ * CSS timing functions matching the engine's `signature` easings exactly.
+ *
+ * Keeping these in lockstep means a CSS transition and a JS animation on the same element move
+ * identically — which matters more than it sounds, because mismatched curves on adjacent
+ * elements is one of those things that reads as "cheap" without the viewer knowing why.
+ */
+declare const easing: {
+    readonly linear: "linear";
+    readonly standard: "cubic-bezier(0.4, 0, 0.2, 1)";
+    readonly emphasized: "cubic-bezier(0.22, 1, 0.36, 1)";
+    readonly enter: "cubic-bezier(0, 0, 0.2, 1)";
+    readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+    readonly overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+    readonly cinematic: "cubic-bezier(0.16, 1, 0.3, 1)";
+};
+/**
+ * Z-index scale.
+ *
+ * Sparse, deliberate values with names. The alternative — `z-index: 9999` scattered through a
+ * codebase — is the single most common source of stacking bugs in a component library.
+ */
+declare const zIndex: {
+    readonly hide: "-1";
+    readonly base: "0";
+    readonly raised: "10";
+    readonly dropdown: "1000";
+    readonly sticky: "1100";
+    readonly overlay: "1200";
+    readonly modal: "1300";
+    readonly popover: "1400";
+    readonly toast: "1500";
+    readonly tooltip: "1600";
+    /** Reserved for skip links and focus traps, which must beat everything. */
+    readonly max: "2147483647";
+};
+/** Breakpoints, matching the widths where real layout decisions occur. */
+declare const breakpoint: {
+    readonly sm: "640px";
+    readonly md: "768px";
+    readonly lg: "1024px";
+    readonly xl: "1280px";
+    readonly '2xl': "1536px";
+};
+/**
+ * Neutral ramp, defined in OKLCH.
+ *
+ * Lightness steps are perceptually even, which a hex-defined grey ramp never is — the usual
+ * result is a scale that looks well-spaced at the light end and bunched at the dark end. A slight
+ * blue chroma (hue 264) keeps it from reading as muddy against saturated accents.
+ */
+declare const neutral: {
+    readonly 50: "oklch(98.5% 0.002 264)";
+    readonly 100: "oklch(96.8% 0.004 264)";
+    readonly 200: "oklch(92.9% 0.007 264)";
+    readonly 300: "oklch(86.9% 0.011 264)";
+    readonly 400: "oklch(70.7% 0.018 264)";
+    readonly 500: "oklch(55.4% 0.022 264)";
+    readonly 600: "oklch(44.6% 0.021 264)";
+    readonly 700: "oklch(37.2% 0.019 264)";
+    readonly 800: "oklch(27.9% 0.017 264)";
+    readonly 900: "oklch(20.8% 0.015 264)";
+    readonly 950: "oklch(13.8% 0.014 264)";
+    readonly 1000: "oklch(8.5% 0.012 264)";
+};
+/** The Ansh brand ramp — the blue the library ships with. */
+declare const brand: {
+    readonly 50: "oklch(97% 0.017 253)";
+    readonly 100: "oklch(93.8% 0.036 253)";
+    readonly 200: "oklch(88.5% 0.069 253)";
+    readonly 300: "oklch(80.9% 0.111 253)";
+    readonly 400: "oklch(71.4% 0.153 253)";
+    readonly 500: "oklch(62.3% 0.188 253)";
+    readonly 600: "oklch(54.6% 0.208 253)";
+    readonly 700: "oklch(46.4% 0.192 253)";
+    readonly 800: "oklch(39.1% 0.16 253)";
+    readonly 900: "oklch(33.5% 0.129 253)";
+    readonly 950: "oklch(23.2% 0.093 253)";
+};
+/** Status ramps. Only the steps that get used are defined, rather than a full 11 for each. */
+declare const status: {
+    readonly success: {
+        readonly subtle: "oklch(95.5% 0.035 155)";
+        readonly default: "oklch(58% 0.15 155)";
+        readonly strong: "oklch(44% 0.12 155)";
+    };
+    readonly warning: {
+        readonly subtle: "oklch(96.5% 0.045 85)";
+        readonly default: "oklch(72% 0.16 75)";
+        readonly strong: "oklch(52% 0.13 65)";
+    };
+    readonly danger: {
+        readonly subtle: "oklch(95.5% 0.03 25)";
+        readonly default: "oklch(58% 0.21 25)";
+        readonly strong: "oklch(46% 0.18 25)";
+    };
+    readonly info: {
+        readonly subtle: "oklch(96% 0.025 240)";
+        readonly default: "oklch(62% 0.17 245)";
+        readonly strong: "oklch(48% 0.15 250)";
+    };
+};
+
+/**
+ * Semantic tokens — meaning mapped onto primitives.
+ *
+ * This layer is why theming works. A component references `surface.raised`, never `neutral.100`.
+ * Switching to dark mode remaps `surface.raised` to `neutral.900`, and every component follows
+ * without a single change. A component that reaches past this layer to a primitive is a bug: it
+ * will look wrong in one theme and nobody will notice until a user reports it.
+ *
+ * The naming follows a consistent pattern:
+ *
+ *  - `surface.*` — backgrounds, ordered by elevation
+ *  - `content.*` — text and icons, ordered by prominence
+ *  - `border.*`  — dividers and outlines, ordered by strength
+ *  - `accent.*`  — the interactive brand colour and its states
+ *  - `state.*`   — success/warning/danger/info
+ */
+interface SemanticTokens {
+    surface: {
+        /** The page background. */
+        canvas: string;
+        /** Cards and panels sitting on the canvas. */
+        raised: string;
+        /** Menus, popovers and anything floating above `raised`. */
+        overlay: string;
+        /** Subtly recessed areas — code blocks, well insets. */
+        sunken: string;
+        /** Translucent glass surface, for use with `backdrop-filter`. */
+        glass: string;
+        /** The scrim behind a modal. */
+        scrim: string;
+    };
+    content: {
+        /** Body text and headings. Must reach 7:1 against `surface.canvas`. */
+        primary: string;
+        /** Supporting text. Must reach 4.5:1. */
+        secondary: string;
+        /** De-emphasised text — timestamps, captions. Must reach 4.5:1 at ≥14px. */
+        tertiary: string;
+        /** Placeholder and disabled text. Exempt from contrast minimums by WCAG. */
+        disabled: string;
+        /** Text placed on top of `accent.default`. */
+        onAccent: string;
+        /** Inverted text, for use on `content.primary` as a background. */
+        inverse: string;
+    };
+    border: {
+        /** Hairline dividers. */
+        subtle: string;
+        /** Input and card outlines. */
+        default: string;
+        /** Hovered or emphasised outlines. */
+        strong: string;
+        /** The focus ring. Must reach 3:1 against both adjacent surfaces. */
+        focus: string;
+    };
+    accent: {
+        subtle: string;
+        muted: string;
+        default: string;
+        hover: string;
+        active: string;
+        /** For text and icons rendered in the accent colour on a neutral surface. */
+        text: string;
+    };
+    state: {
+        successSubtle: string;
+        success: string;
+        warningSubtle: string;
+        warning: string;
+        dangerSubtle: string;
+        danger: string;
+        infoSubtle: string;
+        info: string;
+    };
+    /** The shadow colour the elevation scale multiplies through. */
+    shadowColor: string;
+}
+/**
+ * Light theme.
+ *
+ * Contrast ratios against `surface.canvas` (`neutral.50`):
+ *   `content.primary`   → 15.8:1  (AAA)
+ *   `content.secondary` →  7.4:1  (AAA)
+ *   `content.tertiary`  →  4.7:1  (AA)
+ *   `border.focus`      →  3.4:1  (AA non-text)
+ */
+declare const light: SemanticTokens;
+/**
+ * Dark theme.
+ *
+ * Not an inversion of `light`. Three adjustments that a mechanical inversion misses:
+ *
+ * 1. **Surfaces get lighter as they rise, not darker.** In light mode, elevation is signalled by
+ *    shadow. On a dark background shadow is invisible, so elevation must be signalled by the
+ *    surface itself becoming lighter.
+ * 2. **Chroma is raised.** Saturated colours read as less vivid against dark backgrounds
+ *    (Helmholtz–Kohlrausch), so accents step *lighter* rather than mirroring their light-mode step.
+ * 3. **Body text is not pure white.** `#fff` on a near-black background causes halation — the
+ *    text appears to bleed. `neutral.100` reads as white while staying comfortable.
+ */
+declare const dark: SemanticTokens;
+declare const themes: {
+    readonly light: SemanticTokens;
+    readonly dark: SemanticTokens;
+};
+type ThemeName = keyof typeof themes;
+
+/**
+ * CSS custom property generation.
+ *
+ * Tokens exist twice on purpose — as TypeScript values and as CSS variables — because the two
+ * are consumed differently and neither can serve both jobs:
+ *
+ *  - **TypeScript** values are needed where JavaScript computes with them: passing colours into
+ *    canvas effects, deriving palettes, computing contrast.
+ *  - **CSS variables** are needed for everything the cascade should own: theming a subtree,
+ *    respecting `prefers-color-scheme`, and letting a consumer override a token in their own
+ *    stylesheet without touching a build step.
+ *
+ * This module is the bridge, and it is generated from the same source of truth so the two can't
+ * drift.
+ */
+declare const CSS_PREFIX = "ansh";
+/** Structural tokens — identical in every theme. */
+declare function structuralVariables(): Map<string, string>;
+/** Theme-dependent tokens for one theme. */
+declare function themeVariables(tokens: SemanticTokens): Map<string, string>;
+/**
+ * Emit the complete stylesheet.
+ *
+ * The theming strategy is deliberately layered so it works for every consumer:
+ *
+ * 1. `:root` carries the light theme, so the default works with no configuration.
+ * 2. `@media (prefers-color-scheme: dark)` applies dark automatically — but *only* when the
+ *    document has not opted into manual control, guarded by `:root:not([data-theme])`. Without
+ *    that guard, a user who explicitly chose light mode in an app whose OS is dark would get dark
+ *    anyway, which is the single most common theming bug in the wild.
+ * 3. `[data-theme='dark']` and `[data-theme='light']` allow explicit control at any level of the
+ *    tree, so a single dark card on a light page works with no extra plumbing.
+ */
+declare function generateCss(): string;
+/**
+ * Apply a theme imperatively.
+ *
+ * Sets `data-theme` on the target, which the stylesheet above already understands. Prefer this
+ * over injecting inline styles: it keeps every token in one cascade layer and lets the browser
+ * do the work.
+ *
+ * @param theme  `'light'`, `'dark'`, or `'system'` to hand control back to `prefers-color-scheme`.
+ * @param target Defaults to `document.documentElement`. Pass an element to theme a subtree.
+ */
+declare function applyTheme(theme: 'light' | 'dark' | 'system', target?: HTMLElement): void;
+/**
+ * Read the currently applied theme.
+ *
+ * Resolves `'system'` to whichever theme is actually in effect, because callers generally want to
+ * know what the user is *seeing*, not how it was configured.
+ */
+declare function resolveTheme(target?: HTMLElement): 'light' | 'dark';
+/**
+ * Build an inline `style` object for a subtree override.
+ *
+ * Used by framework `<ThemeProvider>` components that need to apply a theme before the stylesheet
+ * has necessarily loaded — during SSR, most importantly, where a flash of the wrong theme is
+ * otherwise unavoidable.
+ */
+declare function themeStyle(theme: 'light' | 'dark'): Record<string, string>;
+
+/**
+ * @ansh-ui/tokens — the Ansh design language.
+ *
+ * Tokens are exported both as TypeScript values (for code that computes with them) and as CSS
+ * custom properties (for everything the cascade should own). Both are generated from the same
+ * source, so they cannot drift.
+ *
+ * ```ts
+ * import '@ansh-ui/tokens/ansh.css'
+ * import { space, applyTheme } from '@ansh-ui/tokens'
+ * ```
+ */
+
+/**
+ * Every structural token in one object.
+ *
+ * Convenient for a Tailwind preset or a styled-components theme, where the consumer wants the
+ * whole scale rather than individual imports.
+ */
+declare const tokens: {
+    readonly space: {
+        readonly 0: "0";
+        readonly px: "1px";
+        readonly 0.5: "0.125rem";
+        readonly 1: "0.25rem";
+        readonly 1.5: "0.375rem";
+        readonly 2: "0.5rem";
+        readonly 3: "0.75rem";
+        readonly 4: "1rem";
+        readonly 5: "1.25rem";
+        readonly 6: "1.5rem";
+        readonly 8: "2rem";
+        readonly 10: "2.5rem";
+        readonly 12: "3rem";
+        readonly 16: "4rem";
+        readonly 20: "5rem";
+        readonly 24: "6rem";
+        readonly 32: "8rem";
+        readonly 40: "10rem";
+        readonly 48: "12rem";
+        readonly 56: "14rem";
+        readonly 64: "16rem";
+    };
+    readonly radius: {
+        readonly none: "0";
+        readonly xs: "0.25rem";
+        readonly sm: "0.375rem";
+        readonly md: "0.5rem";
+        readonly lg: "0.75rem";
+        readonly xl: "1rem";
+        readonly '2xl': "1.5rem";
+        readonly '3xl': "2rem";
+        readonly full: "9999px";
+    };
+    readonly shadow: {
+        readonly none: "none";
+        readonly xs: "0 1px 2px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.05))";
+        readonly sm: string;
+        readonly md: string;
+        readonly lg: string;
+        readonly xl: string;
+        readonly '2xl': "0 25px 50px -12px var(--ansh-shadow-color, rgb(15 23 42 / 0.2))";
+        readonly inner: "inset 0 2px 4px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.06))";
+        readonly glow: "0 0 24px -4px currentColor";
+        readonly glowLg: "0 0 48px -8px currentColor";
+    };
+    readonly blur: {
+        readonly none: "0";
+        readonly xs: "2px";
+        readonly sm: "4px";
+        readonly md: "8px";
+        readonly lg: "16px";
+        readonly xl: "24px";
+        readonly '2xl': "40px";
+        readonly '3xl': "64px";
+    };
+    readonly duration: {
+        readonly instant: "0.1s";
+        readonly fast: "0.2s";
+        readonly normal: "0.3s";
+        readonly moderate: "0.45s";
+        readonly slow: "0.6s";
+        readonly slower: "0.9s";
+        readonly deliberate: "1.2s";
+    };
+    readonly easing: {
+        readonly linear: "linear";
+        readonly standard: "cubic-bezier(0.4, 0, 0.2, 1)";
+        readonly emphasized: "cubic-bezier(0.22, 1, 0.36, 1)";
+        readonly enter: "cubic-bezier(0, 0, 0.2, 1)";
+        readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+        readonly overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+        readonly cinematic: "cubic-bezier(0.16, 1, 0.3, 1)";
+    };
+    readonly zIndex: {
+        readonly hide: "-1";
+        readonly base: "0";
+        readonly raised: "10";
+        readonly dropdown: "1000";
+        readonly sticky: "1100";
+        readonly overlay: "1200";
+        readonly modal: "1300";
+        readonly popover: "1400";
+        readonly toast: "1500";
+        readonly tooltip: "1600";
+        readonly max: "2147483647";
+    };
+    readonly fontSize: {
+        readonly xs: readonly ["0.75rem", {
+            readonly lineHeight: "1.125rem";
+            readonly letterSpacing: "0.01em";
+        }];
+        readonly sm: readonly ["0.875rem", {
+            readonly lineHeight: "1.375rem";
+            readonly letterSpacing: "0.005em";
+        }];
+        readonly base: readonly ["1rem", {
+            readonly lineHeight: "1.625rem";
+            readonly letterSpacing: "0";
+        }];
+        readonly lg: readonly ["1.125rem", {
+            readonly lineHeight: "1.75rem";
+            readonly letterSpacing: "-0.005em";
+        }];
+        readonly xl: readonly ["1.25rem", {
+            readonly lineHeight: "1.875rem";
+            readonly letterSpacing: "-0.01em";
+        }];
+        readonly '2xl': readonly ["1.5rem", {
+            readonly lineHeight: "2rem";
+            readonly letterSpacing: "-0.015em";
+        }];
+        readonly '3xl': readonly ["1.875rem", {
+            readonly lineHeight: "2.375rem";
+            readonly letterSpacing: "-0.02em";
+        }];
+        readonly '4xl': readonly ["2.25rem", {
+            readonly lineHeight: "2.625rem";
+            readonly letterSpacing: "-0.025em";
+        }];
+        readonly '5xl': readonly ["3rem", {
+            readonly lineHeight: "3.25rem";
+            readonly letterSpacing: "-0.03em";
+        }];
+        readonly '6xl': readonly ["3.75rem", {
+            readonly lineHeight: "3.9rem";
+            readonly letterSpacing: "-0.035em";
+        }];
+        readonly '7xl': readonly ["4.5rem", {
+            readonly lineHeight: "4.6rem";
+            readonly letterSpacing: "-0.04em";
+        }];
+    };
+    readonly fontWeight: {
+        readonly normal: "400";
+        readonly medium: "500";
+        readonly semibold: "600";
+        readonly bold: "700";
+    };
+    readonly fontFamily: {
+        readonly sans: string;
+        readonly mono: string;
+    };
+    readonly breakpoint: {
+        readonly sm: "640px";
+        readonly md: "768px";
+        readonly lg: "1024px";
+        readonly xl: "1280px";
+        readonly '2xl': "1536px";
+    };
+};
+type Tokens = typeof tokens;
+/**
+ * A Tailwind CSS preset that maps Ansh tokens onto Tailwind's theme keys.
+ *
+ * Returned as a plain object rather than importing Tailwind types, so this package stays free of a
+ * Tailwind dependency for the majority of consumers who don't use it.
+ *
+ * ```js
+ * // tailwind.config.js
+ * import { tailwindPreset } from '@ansh-ui/tokens'
+ * export default { presets: [tailwindPreset()] }
+ * ```
+ */
+declare function tailwindPreset(): {
+    theme: {
+        extend: {
+            spacing: {
+                readonly 0: "0";
+                readonly px: "1px";
+                readonly 0.5: "0.125rem";
+                readonly 1: "0.25rem";
+                readonly 1.5: "0.375rem";
+                readonly 2: "0.5rem";
+                readonly 3: "0.75rem";
+                readonly 4: "1rem";
+                readonly 5: "1.25rem";
+                readonly 6: "1.5rem";
+                readonly 8: "2rem";
+                readonly 10: "2.5rem";
+                readonly 12: "3rem";
+                readonly 16: "4rem";
+                readonly 20: "5rem";
+                readonly 24: "6rem";
+                readonly 32: "8rem";
+                readonly 40: "10rem";
+                readonly 48: "12rem";
+                readonly 56: "14rem";
+                readonly 64: "16rem";
+            };
+            borderRadius: {
+                readonly none: "0";
+                readonly xs: "0.25rem";
+                readonly sm: "0.375rem";
+                readonly md: "0.5rem";
+                readonly lg: "0.75rem";
+                readonly xl: "1rem";
+                readonly '2xl': "1.5rem";
+                readonly '3xl': "2rem";
+                readonly full: "9999px";
+            };
+            boxShadow: {
+                readonly none: "none";
+                readonly xs: "0 1px 2px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.05))";
+                readonly sm: string;
+                readonly md: string;
+                readonly lg: string;
+                readonly xl: string;
+                readonly '2xl': "0 25px 50px -12px var(--ansh-shadow-color, rgb(15 23 42 / 0.2))";
+                readonly inner: "inset 0 2px 4px 0 var(--ansh-shadow-color, rgb(15 23 42 / 0.06))";
+                readonly glow: "0 0 24px -4px currentColor";
+                readonly glowLg: "0 0 48px -8px currentColor";
+            };
+            blur: {
+                readonly none: "0";
+                readonly xs: "2px";
+                readonly sm: "4px";
+                readonly md: "8px";
+                readonly lg: "16px";
+                readonly xl: "24px";
+                readonly '2xl': "40px";
+                readonly '3xl': "64px";
+            };
+            fontFamily: {
+                sans: string[];
+                mono: string[];
+            };
+            fontSize: {
+                readonly xs: readonly ["0.75rem", {
+                    readonly lineHeight: "1.125rem";
+                    readonly letterSpacing: "0.01em";
+                }];
+                readonly sm: readonly ["0.875rem", {
+                    readonly lineHeight: "1.375rem";
+                    readonly letterSpacing: "0.005em";
+                }];
+                readonly base: readonly ["1rem", {
+                    readonly lineHeight: "1.625rem";
+                    readonly letterSpacing: "0";
+                }];
+                readonly lg: readonly ["1.125rem", {
+                    readonly lineHeight: "1.75rem";
+                    readonly letterSpacing: "-0.005em";
+                }];
+                readonly xl: readonly ["1.25rem", {
+                    readonly lineHeight: "1.875rem";
+                    readonly letterSpacing: "-0.01em";
+                }];
+                readonly '2xl': readonly ["1.5rem", {
+                    readonly lineHeight: "2rem";
+                    readonly letterSpacing: "-0.015em";
+                }];
+                readonly '3xl': readonly ["1.875rem", {
+                    readonly lineHeight: "2.375rem";
+                    readonly letterSpacing: "-0.02em";
+                }];
+                readonly '4xl': readonly ["2.25rem", {
+                    readonly lineHeight: "2.625rem";
+                    readonly letterSpacing: "-0.025em";
+                }];
+                readonly '5xl': readonly ["3rem", {
+                    readonly lineHeight: "3.25rem";
+                    readonly letterSpacing: "-0.03em";
+                }];
+                readonly '6xl': readonly ["3.75rem", {
+                    readonly lineHeight: "3.9rem";
+                    readonly letterSpacing: "-0.035em";
+                }];
+                readonly '7xl': readonly ["4.5rem", {
+                    readonly lineHeight: "4.6rem";
+                    readonly letterSpacing: "-0.04em";
+                }];
+            };
+            fontWeight: {
+                readonly normal: "400";
+                readonly medium: "500";
+                readonly semibold: "600";
+                readonly bold: "700";
+            };
+            screens: {
+                readonly sm: "640px";
+                readonly md: "768px";
+                readonly lg: "1024px";
+                readonly xl: "1280px";
+                readonly '2xl': "1536px";
+            };
+            zIndex: {
+                readonly hide: "-1";
+                readonly base: "0";
+                readonly raised: "10";
+                readonly dropdown: "1000";
+                readonly sticky: "1100";
+                readonly overlay: "1200";
+                readonly modal: "1300";
+                readonly popover: "1400";
+                readonly toast: "1500";
+                readonly tooltip: "1600";
+                readonly max: "2147483647";
+            };
+            transitionDuration: {
+                [k: string]: "0.1s" | "0.2s" | "0.3s" | "0.45s" | "0.6s" | "0.9s" | "1.2s";
+            };
+            transitionTimingFunction: {
+                readonly linear: "linear";
+                readonly standard: "cubic-bezier(0.4, 0, 0.2, 1)";
+                readonly emphasized: "cubic-bezier(0.22, 1, 0.36, 1)";
+                readonly enter: "cubic-bezier(0, 0, 0.2, 1)";
+                readonly exit: "cubic-bezier(0.4, 0, 1, 1)";
+                readonly overshoot: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+                readonly cinematic: "cubic-bezier(0.16, 1, 0.3, 1)";
+            };
+            colors: {
+                surface: {
+                    canvas: string;
+                    raised: string;
+                    overlay: string;
+                    sunken: string;
+                    glass: string;
+                };
+                content: {
+                    primary: string;
+                    secondary: string;
+                    tertiary: string;
+                    disabled: string;
+                    'on-accent': string;
+                    inverse: string;
+                };
+                line: {
+                    subtle: string;
+                    DEFAULT: string;
+                    strong: string;
+                    focus: string;
+                };
+                accent: {
+                    subtle: string;
+                    muted: string;
+                    DEFAULT: string;
+                    hover: string;
+                    active: string;
+                    text: string;
+                };
+            };
+        };
+    };
+};
+
+export { CSS_PREFIX, type SemanticTokens, type ThemeName, type Tokens, applyTheme, blur, brand, breakpoint, dark, duration, easing, fontFamily, fontSize, fontWeight, generateCss, light, neutral, radius, resolveTheme, shadow, space, status, structuralVariables, tailwindPreset, themeStyle, themeVariables, themes, tokens, zIndex };