@aurora-ds/theme 1.2.9 → 1.5.0

package/dist/index.d.cts

@@ -2,6 +2,26 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
 export { CSSProperties } from 'react';
 
+/**
+ * Responsive breakpoints for mobile-first design
+ * Based on common device widths
+ *
+ * - xs: Extra small devices (phones in portrait)
+ * - sm: Small devices (phones in landscape, small tablets)
+ * - md: Medium devices (tablets)
+ * - lg: Large devices (desktops)
+ * - xl: Extra large devices (large desktops)
+ * - 2xl: Extra extra large devices (wide screens)
+ */
+type BaseBreakpoints = {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+};
+
 /**
  * Base color tokens following modern design system semantics
  */
@@ -11,15 +31,24 @@ type BaseColors = {
     primaryHover: string;
     primaryActive: string;
     primarySubtle: string;
+    primaryDisabled: string;
     secondary: string;
     onSecondary: string;
     secondaryHover: string;
     secondaryActive: string;
     secondarySubtle: string;
+    secondaryDisabled: string;
     accent: string;
     onAccent: string;
     accentHover: string;
+    accentActive: string;
     accentSubtle: string;
+    tertiary: string;
+    onTertiary: string;
+    tertiaryHover: string;
+    tertiaryActive: string;
+    tertiarySubtle: string;
+    tertiaryDisabled: string;
     background: string;
     surface: string;
     surfaceHover: string;
@@ -52,6 +81,7 @@ type BaseColors = {
     infoSubtle: string;
     link: string;
     linkHover: string;
+    linkActive: string;
     linkVisited: string;
     focus: string;
     disabled: string;
@@ -86,6 +116,7 @@ type BaseRadius = {
     md: string;
     lg: string;
     xl: string;
+    '2xl': string;
     full: string;
 };
 
@@ -99,6 +130,9 @@ type BaseShadows = {
     md: string;
     lg: string;
     xl: string;
+    '2xl': string;
+    inner: string;
+    focus: string;
 };
 
 /**
@@ -136,6 +170,7 @@ type BaseLineHeight = {
     tight: number;
     normal: number;
     relaxed: number;
+    loose: number;
 };
 
 /**
@@ -145,9 +180,12 @@ type BaseZIndex = {
     behind: number;
     base: number;
     dropdown: number;
+    sticky: number;
     overlay: number;
     modal: number;
+    popover: number;
     tooltip: number;
+    toast: number;
 };
 
 /**
@@ -159,6 +197,26 @@ type BaseTransition = {
     slow: string;
 };
 
+/**
+ * Base opacity scale for consistent transparency
+ */
+type BaseOpacity = {
+    /** Fully transparent - 0 */
+    none: number;
+    /** Very low opacity - 0.05 */
+    lowest: number;
+    /** Low opacity - 0.1 */
+    low: number;
+    /** Medium-low opacity - 0.25 */
+    medium: number;
+    /** Medium-high opacity - 0.5 */
+    high: number;
+    /** High opacity - 0.75 */
+    higher: number;
+    /** Fully opaque - 1 */
+    full: number;
+};
+
 /**
  * Standard theme type with all required tokens
  */
@@ -172,6 +230,8 @@ type Theme = {
     lineHeight: BaseLineHeight;
     zIndex: BaseZIndex;
     transition: BaseTransition;
+    opacity: BaseOpacity;
+    breakpoints: BaseBreakpoints;
 };
 
 /**
@@ -357,6 +417,14 @@ declare const defaultZIndex: Theme['zIndex'];
  * Default transition scale
  */
 declare const defaultTransition: Theme['transition'];
+/**
+ * Default opacity scale
+ */
+declare const defaultOpacity: Theme['opacity'];
+/**
+ * Default responsive breakpoints
+ */
+declare const defaultBreakpoints: Theme['breakpoints'];
 /**
  * Default colors (using indigo palette)
  */
@@ -462,108 +530,108 @@ declare const indigoDark: ColorPalette$9;
 
 type ColorPalette$8 = Theme['colors'];
 /**
- * Blue light palette - Modern, accessible color scheme
+ * Blue light palette - Classic, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const blueLight: ColorPalette$8;
 /**
- * Blue dark palette - Modern, accessible color scheme
+ * Blue dark palette - Classic, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const blueDark: ColorPalette$8;
 
 type ColorPalette$7 = Theme['colors'];
 /**
- * Rose light palette - Modern, accessible color scheme
+ * Rose light palette - Elegant, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const roseLight: ColorPalette$7;
 /**
- * Rose dark palette - Modern, accessible color scheme
+ * Rose dark palette - Elegant, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const roseDark: ColorPalette$7;
 
 type ColorPalette$6 = Theme['colors'];
 /**
- * Emerald light palette - Modern, accessible color scheme
+ * Emerald light palette - Fresh, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const emeraldLight: ColorPalette$6;
 /**
- * Emerald dark palette - Modern, accessible color scheme
+ * Emerald dark palette - Fresh, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const emeraldDark: ColorPalette$6;
 
 type ColorPalette$5 = Theme['colors'];
 /**
- * Teal light palette - Modern, accessible color scheme
+ * Teal light palette - Cool, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const tealLight: ColorPalette$5;
 /**
- * Teal dark palette - Modern, accessible color scheme
+ * Teal dark palette - Cool, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const tealDark: ColorPalette$5;
 
 type ColorPalette$4 = Theme['colors'];
 /**
- * Violet light palette - Modern, accessible color scheme
+ * Violet light palette - Creative, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const violetLight: ColorPalette$4;
 /**
- * Violet dark palette - Modern, accessible color scheme
+ * Violet dark palette - Creative, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const violetDark: ColorPalette$4;
 
 type ColorPalette$3 = Theme['colors'];
 /**
- * Amber light palette - Modern, accessible color scheme
+ * Amber light palette - Warm, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const amberLight: ColorPalette$3;
 /**
- * Amber dark palette - Modern, accessible color scheme
+ * Amber dark palette - Warm, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const amberDark: ColorPalette$3;
 
 type ColorPalette$2 = Theme['colors'];
 /**
- * Cyan light palette - Modern, accessible color scheme
+ * Cyan light palette - Fresh, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const cyanLight: ColorPalette$2;
 /**
- * Cyan dark palette - Modern, accessible color scheme
+ * Cyan dark palette - Fresh, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const cyanDark: ColorPalette$2;
 
 type ColorPalette$1 = Theme['colors'];
 /**
- * Slate light palette - Modern, accessible color scheme
+ * Slate light palette - Professional, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const slateLight: ColorPalette$1;
 /**
- * Slate dark palette - Modern, accessible color scheme
+ * Slate dark palette - Professional, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const slateDark: ColorPalette$1;
 
 type ColorPalette = Theme['colors'];
 /**
- * Gray light palette - Modern, accessible color scheme
+ * Gray light palette - Clean, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const grayLight: ColorPalette;
 /**
- * Gray dark palette - Modern, accessible color scheme
+ * Gray dark palette - Clean, accessible color scheme
  * Follows WCAG AA contrast guidelines
  */
 declare const grayDark: ColorPalette;
@@ -788,4 +856,159 @@ declare const insertRule: (rule: string) => void;
  */
 declare const sanitizeCssValue: (value: string) => string;
 
-export { type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeOverride, ThemeProvider, type ThemeProviderProps, amber, amberDark, amberLight, black, blue, blueDark, blueLight, clearSSRRules, colors, createStyles, createTheme, createThemeVariant, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };
+/**
+ * WCAG Contrast Utilities
+ *
+ * Utilities for checking color contrast ratios according to WCAG 2.1 guidelines.
+ *
+ * @example
+ * ```ts
+ * import { getContrastRatio, meetsWCAG, checkThemeContrast } from '@aurora-ds/theme'
+ *
+ * // Check contrast between two colors
+ * const ratio = getContrastRatio('#ffffff', '#000000') // 21
+ *
+ * // Check if colors meet WCAG standards
+ * meetsWCAG('#ffffff', '#767676', 'AA') // true for large text
+ * meetsWCAG('#ffffff', '#767676', 'AAA') // false
+ *
+ * // Check all theme color pairs
+ * const issues = checkThemeContrast(myTheme)
+ * ```
+ */
+/**
+ * WCAG contrast level requirements
+ * - AA: 4.5:1 for normal text, 3:1 for large text
+ * - AAA: 7:1 for normal text, 4.5:1 for large text
+ */
+type WCAGLevel = 'AA' | 'AAA';
+/**
+ * Result of a contrast check
+ */
+type ContrastResult = {
+    /** The two colors being compared */
+    colors: [string, string];
+    /** The contrast ratio (1-21) */
+    ratio: number;
+    /** Whether it passes WCAG AA for normal text (4.5:1) */
+    passesAA: boolean;
+    /** Whether it passes WCAG AA for large text (3:1) */
+    passesAALarge: boolean;
+    /** Whether it passes WCAG AAA for normal text (7:1) */
+    passesAAA: boolean;
+    /** Whether it passes WCAG AAA for large text (4.5:1) */
+    passesAAALarge: boolean;
+};
+/**
+ * Theme contrast check result
+ */
+type ThemeContrastIssue = {
+    /** Name of the color pair (e.g., "primary/onPrimary") */
+    pair: string;
+    /** Foreground color name */
+    foreground: string;
+    /** Background color name */
+    background: string;
+    /** The contrast ratio */
+    ratio: number;
+    /** Required minimum ratio */
+    required: number;
+    /** WCAG level that failed */
+    level: 'AA' | 'AALarge';
+};
+/**
+ * Calculate the contrast ratio between two colors
+ * @see https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+ *
+ * @param foreground - Foreground color (hex)
+ * @param background - Background color (hex)
+ * @returns Contrast ratio (1-21), or null if colors are invalid
+ *
+ * @example
+ * ```ts
+ * getContrastRatio('#ffffff', '#000000') // 21
+ * getContrastRatio('#ffffff', '#ffffff') // 1
+ * getContrastRatio('#6366f1', '#ffffff') // ~4.5
+ * ```
+ */
+declare const getContrastRatio: (foreground: string, background: string) => number | null;
+/**
+ * Check if two colors meet WCAG contrast requirements
+ *
+ * @param foreground - Foreground color (hex)
+ * @param background - Background color (hex)
+ * @param level - WCAG level to check ('AA' or 'AAA')
+ * @param largeText - Whether this is for large text (14pt bold or 18pt+)
+ * @returns Whether the contrast meets the specified WCAG level
+ *
+ * @example
+ * ```ts
+ * meetsWCAG('#ffffff', '#6366f1', 'AA') // true
+ * meetsWCAG('#ffffff', '#6366f1', 'AAA') // false
+ * meetsWCAG('#ffffff', '#94a3b8', 'AA', true) // true (large text)
+ * ```
+ */
+declare const meetsWCAG: (foreground: string, background: string, level?: WCAGLevel, largeText?: boolean) => boolean;
+/**
+ * Get detailed contrast information between two colors
+ *
+ * @param foreground - Foreground color (hex)
+ * @param background - Background color (hex)
+ * @returns Detailed contrast result or null if colors are invalid
+ *
+ * @example
+ * ```ts
+ * const result = checkContrast('#ffffff', '#6366f1')
+ * // {
+ * //   colors: ['#ffffff', '#6366f1'],
+ * //   ratio: 4.54,
+ * //   passesAA: true,
+ * //   passesAALarge: true,
+ * //   passesAAA: false,
+ * //   passesAAALarge: true
+ * // }
+ * ```
+ */
+declare const checkContrast: (foreground: string, background: string) => ContrastResult | null;
+/**
+ * Check all important color pairs in a theme for WCAG compliance
+ *
+ * @param theme - The theme to check
+ * @param level - Minimum WCAG level to require ('AA' or 'AAA')
+ * @returns Array of contrast issues found
+ *
+ * @example
+ * ```ts
+ * import { checkThemeContrast, defaultTheme } from '@aurora-ds/theme'
+ *
+ * const issues = checkThemeContrast(defaultTheme)
+ * if (issues.length > 0) {
+ *   console.warn('Theme has contrast issues:', issues)
+ * }
+ *
+ * // Check for AAA compliance
+ * const strictIssues = checkThemeContrast(defaultTheme, 'AAA')
+ * ```
+ */
+declare const checkThemeContrast: (theme: {
+    colors: Record<string, string>;
+}, level?: WCAGLevel) => ThemeContrastIssue[];
+/**
+ * Get a suggested color that meets WCAG contrast requirements
+ * Adjusts the lightness of the foreground color to meet the target ratio
+ *
+ * @param foreground - Current foreground color (hex)
+ * @param background - Background color (hex)
+ * @param targetRatio - Desired contrast ratio (default 4.5 for AA)
+ * @returns Adjusted foreground color or null if adjustment isn't possible
+ *
+ * @example
+ * ```ts
+ * // If #94a3b8 on #ffffff doesn't meet AA
+ * const suggested = suggestContrastColor('#94a3b8', '#ffffff', 4.5)
+ * // Returns a darker shade that meets the requirement
+ * ```
+ */
+declare const suggestContrastColor: (foreground: string, background: string, targetRatio?: number) => string | null;
+
+export { type BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type ContrastResult, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeContrastIssue, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type WCAGLevel, amber, amberDark, amberLight, black, blue, blueDark, blueLight, checkContrast, checkThemeContrast, clearSSRRules, colors, createStyles, createTheme, createThemeVariant, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultBreakpoints, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getContrastRatio, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, meetsWCAG, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, suggestContrastColor, teal, tealDark, tealLight, transparent, useTheme, violet, violetDark, violetLight, white, yellow };