@rakeyshgidwani/roger-ui-bank-theme-stan-design 0.1.3 → 0.1.5

package/src/themes/validation.ts

@@ -0,0 +1,462 @@
+// Theme Validation System
+// This file provides comprehensive validation for theme configurations
+
+import { 
+  MultiThemeConfig, 
+  ThemeValidationResult, 
+  ThemeValidationError, 
+  ThemeValidationWarning 
+} from './types';
+import { ColorManager } from './colorManager';
+
+export class ThemeValidator {
+  private static readonly REQUIRED_FIELDS = [
+    'fonts.primary.family',
+    'fonts.primary.sizes.md',
+    'colors.primary.500',
+    'colors.semantic.success',
+    'colors.semantic.error',
+    'colors.semantic.warning',
+    'colors.semantic.info',
+    'colors.surface.background',
+    'colors.text.primary',
+    'spacing.scale.md',
+    'shadows.md',
+    'transitions.duration.normal',
+    'transitions.easing.ease',
+    'meta.name',
+    'meta.description',
+    'meta.version'
+  ];
+
+  private static readonly COLOR_FORMATS = {
+    hex: /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/,
+    rgb: /^rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)$/,
+    rgba: /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)$/,
+    hsl: /^hsl\(\s*\d+\s*,\s*\d+%\s*,\s*\d+%\s*\)$/,
+    hsla: /^hsla\(\s*\d+\s*,\s*\d+%\s*,\s*\d+%\s*,\s*[\d.]+\s*\)$/
+  };
+
+  private static readonly FONT_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+
+  /**
+   * Validate a complete theme configuration
+   */
+  static validateTheme(theme: MultiThemeConfig): ThemeValidationResult {
+    const errors: ThemeValidationError[] = [];
+    const warnings: ThemeValidationWarning[] = [];
+
+    // Validate required fields
+    this.validateRequiredFields(theme, errors);
+
+    // Validate color formats
+    this.validateColorFormats(theme, errors, warnings);
+
+    // Validate color contrast
+    this.validateColorContrast(theme, warnings);
+
+    // Validate font configurations
+    this.validateFontConfigurations(theme, warnings);
+
+    // Validate spacing scales
+    this.validateSpacingScales(theme, warnings);
+
+    // Validate navigation configurations
+    this.validateNavigationConfigurations(theme, errors, warnings);
+
+    // Validate metadata
+    this.validateMetadata(theme, errors, warnings);
+
+    // Validate semantic consistency
+    this.validateSemanticConsistency(theme, warnings);
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  /**
+   * Validate that all required fields are present
+   */
+  private static validateRequiredFields(theme: MultiThemeConfig, errors: ThemeValidationError[]): void {
+    for (const fieldPath of this.REQUIRED_FIELDS) {
+      const value = this.getNestedValue(theme, fieldPath);
+      if (value === undefined || value === null || value === '') {
+        errors.push({
+          path: fieldPath,
+          message: `Required field '${fieldPath}' is missing or empty`,
+          severity: 'error'
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate color format consistency
+   */
+  private static validateColorFormats(theme: MultiThemeConfig, errors: ThemeValidationError[], warnings: ThemeValidationWarning[]): void {
+    const colorFields = this.getAllColorFields(theme);
+    const formats = new Set<string>();
+
+    for (const { path, value } of colorFields) {
+      if (typeof value === 'string') {
+        // Use colorManager for validation
+        if (!ColorManager.isValidColor(value)) {
+          errors.push({
+            path,
+            message: `Invalid color format: '${value}'. Expected hex, rgb, hsl, or named color format`,
+            severity: 'error'
+          });
+        } else {
+          const format = this.detectColorFormat(value);
+          if (format) {
+            formats.add(format);
+          }
+        }
+      }
+    }
+
+    // Warn if multiple color formats are used
+    if (formats.size > 1) {
+      warnings.push({
+        path: 'colors',
+        message: `Multiple color formats detected: ${Array.from(formats).join(', ')}. Consider using a consistent format for better maintainability`,
+        severity: 'warning'
+      });
+    }
+  }
+
+  /**
+   * Validate color contrast ratios
+   */
+  private static validateColorContrast(theme: MultiThemeConfig, warnings: ThemeValidationWarning[]): void {
+    const textColors = [
+      theme.colors?.text?.primary,
+      theme.colors?.text?.secondary,
+      theme.colors?.text?.muted
+    ].filter(Boolean);
+
+    const backgroundColors = [
+      theme.colors?.surface?.background,
+      theme.colors?.surface?.surface
+    ].filter(Boolean);
+
+    for (const textColor of textColors) {
+      for (const bgColor of backgroundColors) {
+        if (textColor && bgColor) {
+          // Use colorManager for contrast checking
+          const accessibility = ColorManager.checkColorContrast(textColor, bgColor);
+          
+          if (!accessibility.aa) {
+            warnings.push({
+              path: 'colors',
+              message: `Color contrast ratio ${accessibility.contrastRatio.toFixed(2)}:1 between '${textColor}' and '${bgColor}' is below WCAG AA standard (4.5:1)`,
+              severity: 'warning'
+            });
+          } else if (!accessibility.aaa) {
+            warnings.push({
+              path: 'colors',
+              message: `Color contrast ratio ${accessibility.contrastRatio.toFixed(2)}:1 between '${textColor}' and '${bgColor}' is below WCAG AAA standard (7:1)`,
+              severity: 'info'
+            });
+          }
+
+          // Add accessibility recommendations
+          if (accessibility.recommended.length > 0) {
+            warnings.push({
+              path: 'colors',
+              message: `Accessibility recommendations: ${accessibility.recommended.join('; ')}`,
+              severity: 'info'
+            });
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Validate font configurations
+   */
+  private static validateFontConfigurations(theme: MultiThemeConfig, warnings: ThemeValidationWarning[]): void {
+    // Validate font weights
+    if (theme.fonts?.primary?.weights) {
+      for (const weight of theme.fonts.primary.weights) {
+        if (!this.FONT_WEIGHTS.includes(weight)) {
+          warnings.push({
+            path: 'fonts.primary.weights',
+            message: `Font weight ${weight} is not a standard CSS font weight. Consider using: ${this.FONT_WEIGHTS.join(', ')}`,
+            severity: 'warning'
+          });
+        }
+      }
+    }
+
+    // Validate font size scale
+    if (theme.fonts?.primary?.sizes) {
+      const sizes = Object.values(theme.fonts.primary.sizes);
+      const numericSizes = sizes.map(size => parseFloat(size)).filter(size => !isNaN(size));
+      
+      if (numericSizes.length > 1) {
+        for (let i = 1; i < numericSizes.length; i++) {
+          if (numericSizes[i] <= numericSizes[i - 1]) {
+            warnings.push({
+              path: 'fonts.primary.sizes',
+              message: `Font sizes should be in ascending order. Found: ${numericSizes[i - 1]} followed by ${numericSizes[i]}`,
+              severity: 'warning'
+            });
+          }
+        }
+      }
+    }
+
+    // Validate font family fallbacks
+    if (theme.fonts?.primary?.family) {
+      const family = theme.fonts.primary.family;
+      if (!family.includes(',') && !family.includes('"') && !family.includes("'")) {
+        warnings.push({
+          path: 'fonts.primary.family',
+          message: `Font family '${family}' should include fallback fonts for better cross-platform compatibility`,
+          severity: 'warning'
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate spacing scales
+   */
+  private static validateSpacingScales(theme: MultiThemeConfig, warnings: ThemeValidationWarning[]): void {
+    if (theme.spacing?.scale) {
+      const scales = Object.values(theme.spacing.scale);
+      const numericScales = scales.map(scale => parseFloat(scale)).filter(scale => !isNaN(scale));
+      
+      if (numericScales.length > 1) {
+        // Check if spacing follows a consistent pattern
+        const ratios = [];
+        for (let i = 1; i < numericScales.length; i++) {
+          ratios.push(numericScales[i] / numericScales[i - 1]);
+        }
+        
+        const avgRatio = ratios.reduce((sum, ratio) => sum + ratio, 0) / ratios.length;
+        const variance = ratios.reduce((sum, ratio) => sum + Math.pow(ratio - avgRatio, 2), 0) / ratios.length;
+        
+        if (variance > 0.1) { // High variance indicates inconsistent spacing
+          warnings.push({
+            path: 'spacing.scale',
+            message: `Spacing scale appears inconsistent. Consider using a mathematical scale (e.g., 1.5x or 2x multiplier) for better visual harmony`,
+            severity: 'warning'
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Validate navigation configurations
+   */
+  private static validateNavigationConfigurations(theme: MultiThemeConfig, _errors: ThemeValidationError[], warnings: ThemeValidationWarning[]): void {
+    if (theme.navigation) {
+      // Validate layout and behavior combinations
+      const { layout, behavior } = theme.navigation;
+      
+      if (layout === 'sidebar' && behavior === 'floating') {
+        warnings.push({
+          path: 'navigation',
+          message: 'Sidebar layout with floating behavior may cause usability issues. Consider using static or sticky behavior',
+          severity: 'warning'
+        });
+      }
+
+      if (layout === 'tabs' && behavior === 'overlay') {
+        warnings.push({
+          path: 'navigation',
+          message: 'Tab layout with overlay behavior is unusual. Consider using static or sticky behavior',
+          severity: 'warning'
+        });
+      }
+
+      // Validate responsive behavior
+      if (theme.navigation.responsive === 'desktop-first' && layout === 'horizontal') {
+        warnings.push({
+          path: 'navigation',
+          message: 'Desktop-first responsive approach with horizontal layout may cause mobile usability issues',
+          severity: 'warning'
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate metadata
+   */
+  private static validateMetadata(theme: MultiThemeConfig, errors: ThemeValidationError[], warnings: ThemeValidationWarning[]): void {
+    if (theme.meta) {
+      // Validate version format
+      if (theme.meta.version && !/^\d+\.\d+\.\d+/.test(theme.meta.version)) {
+        warnings.push({
+          path: 'meta.version',
+          message: `Version '${theme.meta.version}' should follow semantic versioning (e.g., 1.0.0)`,
+          severity: 'warning'
+        });
+      }
+
+      // Validate category
+      if (theme.meta.category && !['brand', 'enterprise', 'custom', 'accessibility'].includes(theme.meta.category)) {
+        errors.push({
+          path: 'meta.category',
+          message: `Invalid category '${theme.meta.category}'. Must be one of: brand, enterprise, custom, accessibility`,
+          severity: 'error'
+        });
+      }
+
+      // Validate tags
+      if (theme.meta.tags && theme.meta.tags.length > 10) {
+        warnings.push({
+          path: 'meta.tags',
+          message: `Theme has ${theme.meta.tags.length} tags. Consider limiting to 10 tags for better organization`,
+          severity: 'warning'
+        });
+      }
+    }
+  }
+
+  /**
+   * Validate semantic consistency
+   */
+  private static validateSemanticConsistency(theme: MultiThemeConfig, warnings: ThemeValidationWarning[]): void {
+    // Check if semantic colors are distinct from primary colors
+    if (theme.colors?.semantic && theme.colors?.primary) {
+      const semanticColors = Object.values(theme.colors.semantic);
+      const primaryColors = Object.values(theme.colors.primary);
+      
+      for (const semanticColor of semanticColors) {
+        for (const primaryColor of primaryColors) {
+          if (this.colorsAreSimilar(semanticColor, primaryColor)) {
+            warnings.push({
+              path: 'colors.semantic',
+              message: `Semantic color '${semanticColor}' is too similar to primary color '${primaryColor}'. Consider using more distinct colors for better semantic clarity`,
+              severity: 'warning'
+            });
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Helper: Get nested value from object using dot notation
+   */
+  private static getNestedValue(obj: any, path: string): any {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+  }
+
+  /**
+   * Helper: Get all color fields from theme
+   */
+  private static getAllColorFields(theme: MultiThemeConfig): Array<{ path: string; value: any }> {
+    const fields: Array<{ path: string; value: any }> = [];
+    
+    const traverseColors = (obj: any, path: string) => {
+      if (obj && typeof obj === 'object') {
+        for (const [key, value] of Object.entries(obj)) {
+          const currentPath = path ? `${path}.${key}` : key;
+          if (typeof value === 'string' && this.isColorValue(value)) {
+            fields.push({ path: currentPath, value });
+          } else if (typeof value === 'object') {
+            traverseColors(value, currentPath);
+          }
+        }
+      }
+    };
+
+    traverseColors(theme.colors, 'colors');
+    return fields;
+  }
+
+  /**
+   * Helper: Detect color format
+   */
+  private static detectColorFormat(color: string): string | null {
+    for (const [format, regex] of Object.entries(this.COLOR_FORMATS)) {
+      if (regex.test(color)) {
+        return format;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Helper: Check if value looks like a color
+   */
+  private static isColorValue(value: string): boolean {
+    // Accept any string that might be a color, let detectColorFormat validate it
+    return value.startsWith('#') || 
+           value.startsWith('rgb') || 
+           value.startsWith('hsl') || 
+           value.startsWith('var(--') || 
+           value === 'transparent' || 
+           value === 'currentColor' ||
+           value === 'inherit' ||
+           // Also accept any string that might be a color (for validation)
+           value.includes('color') ||
+           value.includes('invalid');
+  }
+
+  /**
+   * Helper: Calculate color contrast ratio
+   */
+  private static calculateColorContrast(color1: string, color2: string): number {
+    try {
+      const luminance1 = this.getLuminance(color1);
+      const luminance2 = this.getLuminance(color2);
+      
+      const lighter = Math.max(luminance1, luminance2);
+      const darker = Math.min(luminance1, luminance2);
+      
+      return (lighter + 0.05) / (darker + 0.05);
+    } catch {
+      return 1; // Default fallback
+    }
+  }
+
+  /**
+   * Helper: Get luminance of a color
+   */
+  private static getLuminance(color: string): number {
+    // Handle CSS variables and other formats
+    if (color.startsWith('var(--') || color === 'transparent' || color === 'currentColor' || color === 'inherit') {
+      return 0.5; // Default fallback
+    }
+
+    // Convert hex to RGB and calculate luminance
+    try {
+      const hex = color.replace('#', '');
+      const r = parseInt(hex.substr(0, 2), 16) / 255;
+      const g = parseInt(hex.substr(2, 2), 16) / 255;
+      const b = parseInt(hex.substr(4, 2), 16) / 255;
+      
+      const [rs, gs, bs] = [r, g, b].map(c => {
+        if (c <= 0.03928) return c / 12.92;
+        return Math.pow((c + 0.055) / 1.055, 2.4);
+      });
+      
+      return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+    } catch {
+      return 0.5; // Default fallback
+    }
+  }
+
+  /**
+   * Helper: Check if two colors are similar
+   */
+  private static colorsAreSimilar(color1: string, color2: string): boolean {
+    try {
+      const contrast = this.calculateColorContrast(color1, color2);
+      return contrast < 2.0; // Very low contrast indicates similar colors
+    } catch {
+      return false;
+    }
+  }
+}

package/src/tokens/index.ts

@@ -0,0 +1,34 @@
+// Core token types and interfaces
+export type {
+  DesignToken,
+  TokenType,
+  ColorToken,
+  FontToken,
+  SpacingToken,
+  ShadowToken,
+  TransitionToken,
+  TokenGroup,
+  ThemeTokens,
+  TokenExportOptions
+} from './types';
+
+// Token generation
+export { TokenGenerator } from './tokenGenerator';
+
+// Token export functionality
+export { TokenExporter } from './tokenExporter';
+
+// Token validation
+export type { ValidationResult, ValidationError, ValidationWarning } from './tokenValidator';
+export { TokenValidator } from './tokenValidator';
+
+// Main token manager
+export type { TokenManagerOptions } from './tokenManager';
+export { TokenManager } from './tokenManager';
+
+// Convenience functions
+import { TokenManager, type TokenManagerOptions } from './tokenManager';
+export const createTokenManager = (options?: TokenManagerOptions) => new TokenManager(options);
+
+// Default token manager instance
+export const defaultTokenManager = new TokenManager();