@refraction-ui/tailwind-config 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,549 @@
+/**
+ * Refraction UI Tailwind preset — shared configuration for all projects.
+ * Works with Tailwind v3 (via presets) and v4 (via @import).
+ *
+ * Usage (Tailwind v3):
+ *   const { refractionPreset } = require('@refraction-ui/tailwind-config')
+ *   module.exports = { presets: [refractionPreset] }
+ *
+ * Usage (Tailwind v4):
+ *   @import '@refraction-ui/tailwind-config/css';
+ */
+declare const refractionPreset: {
+    darkMode: "class";
+    theme: {
+        container: {
+            center: boolean;
+            padding: string;
+            screens: {
+                '2xl': string;
+            };
+        };
+        extend: {
+            colors: {
+                background: string;
+                foreground: string;
+                card: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                popover: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                primary: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                secondary: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                muted: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                accent: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                destructive: {
+                    DEFAULT: string;
+                    foreground: string;
+                };
+                border: string;
+                input: string;
+                ring: string;
+                chart: {
+                    1: string;
+                    2: string;
+                    3: string;
+                    4: string;
+                    5: string;
+                };
+                sidebar: {
+                    DEFAULT: string;
+                    foreground: string;
+                    primary: string;
+                    'primary-foreground': string;
+                    accent: string;
+                    'accent-foreground': string;
+                    border: string;
+                    ring: string;
+                };
+            };
+            borderRadius: {
+                lg: string;
+                md: string;
+                sm: string;
+            };
+            fontFamily: {
+                sans: string[];
+                mono: string[];
+                serif: string[];
+                heading: string[];
+            };
+            fontSize: {
+                xs: string;
+                sm: string;
+                base: string;
+                lg: string;
+                xl: string;
+                '2xl': string;
+                '3xl': string;
+                '4xl': string;
+                '5xl': string;
+            };
+            boxShadow: {
+                sm: string;
+                md: string;
+                lg: string;
+                xl: string;
+            };
+            letterSpacing: {
+                tighter: string;
+                tight: string;
+                normal: string;
+                wide: string;
+                wider: string;
+            };
+            lineHeight: {
+                tight: string;
+                normal: string;
+                relaxed: string;
+            };
+            transitionDuration: {
+                DEFAULT: string;
+            };
+            transitionTimingFunction: {
+                DEFAULT: string;
+            };
+            backdropBlur: {
+                DEFAULT: string;
+            };
+            keyframes: {
+                'fade-in': {
+                    from: {
+                        opacity: string;
+                    };
+                    to: {
+                        opacity: string;
+                    };
+                };
+                'fade-in-up': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+                'fade-in-scale': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+                'slide-up': {
+                    from: {
+                        transform: string;
+                    };
+                    to: {
+                        transform: string;
+                    };
+                };
+                'slide-in-right': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+                'toast-in': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+                'toast-out': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+                'accordion-down': {
+                    from: {
+                        height: string;
+                    };
+                    to: {
+                        height: string;
+                    };
+                };
+                'accordion-up': {
+                    from: {
+                        height: string;
+                    };
+                    to: {
+                        height: string;
+                    };
+                };
+                'scale-in': {
+                    from: {
+                        opacity: string;
+                        transform: string;
+                    };
+                    to: {
+                        opacity: string;
+                        transform: string;
+                    };
+                };
+            };
+            animation: {
+                'fade-in': string;
+                'fade-in-up': string;
+                'fade-in-scale': string;
+                'slide-up': string;
+                'slide-in-right': string;
+                'toast-in': string;
+                'toast-out': string;
+                'accordion-down': string;
+                'accordion-up': string;
+                'scale-in': string;
+            };
+        };
+    };
+};
+
+/** Semantic color tokens mapped to CSS custom properties */
+declare const colors: {
+    background: string;
+    foreground: string;
+    card: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    popover: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    primary: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    secondary: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    muted: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    accent: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    destructive: {
+        DEFAULT: string;
+        foreground: string;
+    };
+    border: string;
+    input: string;
+    ring: string;
+    chart: {
+        1: string;
+        2: string;
+        3: string;
+        4: string;
+        5: string;
+    };
+    sidebar: {
+        DEFAULT: string;
+        foreground: string;
+        primary: string;
+        'primary-foreground': string;
+        accent: string;
+        'accent-foreground': string;
+        border: string;
+        ring: string;
+    };
+};
+
+/**
+ * Keyframe definitions consolidated from all elloloop projects.
+ *
+ * Accessibility: Users who prefer reduced motion should see instant transitions.
+ * Apply the `.motion-reduce` utility (from utilities.ts) to animated elements,
+ * or use Tailwind's built-in `motion-reduce:` variant on individual elements.
+ * The `.motion-safe` / `.motion-reduce` utilities in utilities.ts provide
+ * global prefers-reduced-motion support via CSS media queries.
+ */
+declare const keyframes: {
+    'fade-in': {
+        from: {
+            opacity: string;
+        };
+        to: {
+            opacity: string;
+        };
+    };
+    'fade-in-up': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+    'fade-in-scale': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+    'slide-up': {
+        from: {
+            transform: string;
+        };
+        to: {
+            transform: string;
+        };
+    };
+    'slide-in-right': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+    'toast-in': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+    'toast-out': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+    'accordion-down': {
+        from: {
+            height: string;
+        };
+        to: {
+            height: string;
+        };
+    };
+    'accordion-up': {
+        from: {
+            height: string;
+        };
+        to: {
+            height: string;
+        };
+    };
+    'scale-in': {
+        from: {
+            opacity: string;
+            transform: string;
+        };
+        to: {
+            opacity: string;
+            transform: string;
+        };
+    };
+};
+/** Animation utility classes */
+declare const animation: {
+    'fade-in': string;
+    'fade-in-up': string;
+    'fade-in-scale': string;
+    'slide-up': string;
+    'slide-in-right': string;
+    'toast-in': string;
+    'toast-out': string;
+    'accordion-down': string;
+    'accordion-up': string;
+    'scale-in': string;
+};
+
+/**
+ * Minimal Tailwind plugin types — avoids depending on tailwindcss.
+ * Consumers have tailwindcss installed; we just need the shapes for authoring.
+ */
+type PluginCreator = (helpers: {
+    addUtilities: (utilities: Record<string, Record<string, string | Record<string, string>>>) => void;
+}) => void;
+
+/**
+ * Custom Tailwind utility classes consolidated from all projects.
+ * These are registered as a Tailwind plugin.
+ */
+
+declare const utilitiesPlugin: PluginCreator;
+
+/**
+ * Refraction UI Theme System
+ *
+ * Product-inspired themes drawn from real, successful design systems.
+ * Every color is a researched, intentional choice — not arbitrary.
+ *
+ * All color values are HSL (hue saturation% lightness%) without the hsl()
+ * wrapper, because components use them as: hsl(var(--primary))
+ *
+ * Run `validateThemeContrast(theme.colors)` from contrast.ts to verify
+ * WCAG compliance for any theme.
+ *
+ * Inspirations:
+ *   Refraction — Linear.app + Vercel (calm violet, crisp, professional)
+ *   Luxe       — Apple.com product pages (premium blue, spacious, precise)
+ *   Warm       — Airbnb + Notion (coral, inviting, warm off-white)
+ *   Signal     — Slack + Linear (teal, dense, productive)
+ *   Pulse      — Spotify + Discord (blurple, bold, playful)
+ *   Mono       — Stripe docs + GitHub (slate, technical, code-first)
+ */
+interface ThemeDefinition {
+    name: string;
+    displayName: string;
+    description: string;
+    colors: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+    fonts: {
+        sans: string;
+        heading: string;
+        mono: string;
+    };
+    headingWeight: string;
+    headingLetterSpacing: string;
+    headingLineHeight: string;
+    fontSizeBase: string;
+    radius: string;
+    avatarRadius: string;
+    badgeRadius: string;
+    buttonRadius: string;
+    cardRadius: string;
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    cardShadow: string;
+    buttonShadow: string;
+    overlayOpacity: string;
+    backdropBlur: string;
+    glassBackground: string;
+    spacingScale: number;
+    containerMaxWidth: string;
+    cardPadding: string;
+    inputHeight: string;
+    borderWidth: string;
+    inputStyle: 'bordered' | 'filled' | 'underline';
+    buttonStyle: 'filled' | 'outline' | 'ghost-default';
+    hoverEffect: 'darken' | 'lighten' | 'shadow-lift' | 'scale';
+    disabledOpacity: string;
+    linkStyle: 'underline' | 'color-only' | 'underline-on-hover';
+    focusRingStyle: 'ring' | 'outline' | 'shadow';
+    iconStyle: 'outlined' | 'filled' | 'duotone';
+    iconStrokeWidth: string;
+    scrollbarStyle: 'thin' | 'hidden' | 'default';
+    selectionBackground: string;
+    selectionForeground: string;
+    tooltipStyle: 'dark' | 'light' | 'primary';
+    tableStyle: 'striped' | 'clean' | 'bordered';
+}
+declare const refractionTheme: ThemeDefinition;
+declare const luxeTheme: ThemeDefinition;
+declare const warmTheme: ThemeDefinition;
+declare const signalTheme: ThemeDefinition;
+declare const pulseTheme: ThemeDefinition;
+declare const monoTheme: ThemeDefinition;
+declare const THEMES: Record<string, ThemeDefinition>;
+declare const DEFAULT_THEME = "refraction";
+/** @deprecated Use `refractionTheme` or `THEMES.refraction` instead */
+declare const glassaTheme: {
+    readonly name: string;
+    readonly light: Record<string, string>;
+    readonly dark: Record<string, string>;
+};
+/**
+ * Generate a full CSS string from a ThemeDefinition for injection into a
+ * <style> tag or CSS file. Covers colors, typography, layout, shadows,
+ * and all branding tokens.
+ */
+declare function generateThemeCSS(theme?: ThemeDefinition): string;
+/** Get all CSS variable names from the default theme (useful for validation) */
+declare function getThemeVariableNames(): string[];
+
+/**
+ * WCAG contrast ratio utilities for theme validation.
+ * Helps verify that theme colors meet accessibility requirements.
+ *
+ * WCAG 2.1 minimum contrast ratios:
+ *   - AA normal text: 4.5:1
+ *   - AA large text (>=18pt or >=14pt bold): 3:1
+ *   - AAA normal text: 7:1
+ *   - AAA large text: 4.5:1
+ */
+/** Parse HSL string "H S% L%" to {h, s, l} */
+declare function parseHSL(hsl: string): {
+    h: number;
+    s: number;
+    l: number;
+};
+/** Convert HSL to relative luminance (WCAG 2.1 formula) */
+declare function hslToLuminance(h: number, s: number, l: number): number;
+/** Calculate contrast ratio between two relative luminances */
+declare function contrastRatio(l1: number, l2: number): number;
+/** Check if two HSL colors meet WCAG AA (4.5:1 normal, 3:1 large) */
+declare function meetsWCAG_AA(foreground: string, background: string, isLargeText?: boolean): boolean;
+/** Check WCAG AAA (7:1 normal, 4.5:1 large) */
+declare function meetsWCAG_AAA(foreground: string, background: string, isLargeText?: boolean): boolean;
+/** Validate an entire theme's contrast ratios */
+declare function validateThemeContrast(theme: {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}): {
+    pair: string;
+    mode: string;
+    ratio: number;
+    passes: boolean;
+}[];
+
+export { DEFAULT_THEME, THEMES, type ThemeDefinition, animation, colors, contrastRatio, generateThemeCSS, getThemeVariableNames, glassaTheme, hslToLuminance, keyframes, luxeTheme, meetsWCAG_AA, meetsWCAG_AAA, monoTheme, parseHSL, pulseTheme, refractionPreset, refractionTheme, signalTheme, utilitiesPlugin, validateThemeContrast, warmTheme };