@fragments-sdk/cli 0.5.2 → 0.7.0

package/src/theme/contrast.ts

@@ -0,0 +1,246 @@
+/**
+ * Color Contrast Utilities
+ *
+ * Pure TypeScript WCAG 2.1 color contrast math — zero dependencies.
+ * Handles hex (#rgb, #rrggbb), rgb(), rgba(), hsl(), hsla().
+ */
+
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Parse a CSS color string into an RGB object.
+ * Supports: #rgb, #rrggbb, rgb(), rgba(), hsl(), hsla().
+ */
+export function parseColor(css: string): RGB {
+  const trimmed = css.trim().toLowerCase();
+
+  // Hex: #rgb or #rrggbb
+  const hexMatch = trimmed.match(/^#([0-9a-f]{3,8})$/);
+  if (hexMatch) {
+    const hex = hexMatch[1];
+    if (hex.length === 3) {
+      return {
+        r: parseInt(hex[0] + hex[0], 16),
+        g: parseInt(hex[1] + hex[1], 16),
+        b: parseInt(hex[2] + hex[2], 16),
+      };
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      return {
+        r: parseInt(hex.substring(0, 2), 16),
+        g: parseInt(hex.substring(2, 4), 16),
+        b: parseInt(hex.substring(4, 6), 16),
+      };
+    }
+  }
+
+  // rgb() / rgba()
+  const rgbMatch = trimmed.match(
+    /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/
+  );
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+
+  // hsl() / hsla()
+  const hslMatch = trimmed.match(
+    /^hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%/
+  );
+  if (hslMatch) {
+    return hslToRgb(
+      parseFloat(hslMatch[1]),
+      parseFloat(hslMatch[2]),
+      parseFloat(hslMatch[3])
+    );
+  }
+
+  throw new Error(`Cannot parse color: "${css}"`);
+}
+
+/**
+ * Convert HSL values to RGB.
+ */
+function hslToRgb(h: number, s: number, l: number): RGB {
+  const sNorm = s / 100;
+  const lNorm = l / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const hPrime = (((h % 360) + 360) % 360) / 60;
+  const x = c * (1 - Math.abs((hPrime % 2) - 1));
+  const m = lNorm - c / 2;
+
+  let r1 = 0, g1 = 0, b1 = 0;
+  if (hPrime < 1)      { r1 = c; g1 = x; }
+  else if (hPrime < 2) { r1 = x; g1 = c; }
+  else if (hPrime < 3) { g1 = c; b1 = x; }
+  else if (hPrime < 4) { g1 = x; b1 = c; }
+  else if (hPrime < 5) { r1 = x; b1 = c; }
+  else                 { r1 = c; b1 = x; }
+
+  return {
+    r: Math.round((r1 + m) * 255),
+    g: Math.round((g1 + m) * 255),
+    b: Math.round((b1 + m) * 255),
+  };
+}
+
+/**
+ * Linearize an sRGB channel value (0-255) for luminance calculation.
+ */
+function linearize(channel: number): number {
+  const srgb = channel / 255;
+  return srgb <= 0.04045
+    ? srgb / 12.92
+    : Math.pow((srgb + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Calculate relative luminance per WCAG 2.1.
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/general/G17#procedure
+ */
+export function relativeLuminance(r: number, g: number, b: number): number {
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+/**
+ * Calculate the contrast ratio between two colors.
+ * Returns a value >= 1 (lighter / darker).
+ */
+export function contrastRatio(fg: RGB, bg: RGB): number {
+  const l1 = relativeLuminance(fg.r, fg.g, fg.b);
+  const l2 = relativeLuminance(bg.r, bg.g, bg.b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Check whether a contrast ratio meets WCAG 2.1 AA.
+ * Normal text: 4.5:1. Large text (18pt / 14pt bold): 3:1.
+ */
+export function meetsAA(ratio: number, isLargeText = false): boolean {
+  return ratio >= (isLargeText ? 3.0 : 4.5);
+}
+
+/**
+ * Check whether a contrast ratio meets WCAG 2.1 AAA.
+ * Normal text: 7:1. Large text: 4.5:1.
+ */
+export function meetsAAA(ratio: number, isLargeText = false): boolean {
+  return ratio >= (isLargeText ? 4.5 : 7.0);
+}
+
+/**
+ * Convert an RGB object back to a hex string.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.max(0, Math.min(255, Math.round(v)));
+  const hex = (v: number) => clamp(v).toString(16).padStart(2, '0');
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+/**
+ * Suggest a fixed foreground color that meets the target contrast ratio
+ * against the given background.
+ *
+ * Uses binary search: hold bg fixed, adjust fg luminance until the target
+ * ratio is met. Returns the adjusted foreground hex color.
+ */
+export function suggestFix(
+  fg: RGB,
+  bg: RGB,
+  targetRatio: number
+): string {
+  const bgLum = relativeLuminance(bg.r, bg.g, bg.b);
+  const fgLum = relativeLuminance(fg.r, fg.g, fg.b);
+
+  // Determine whether we need to go darker or lighter
+  const fgIsLighter = fgLum >= bgLum;
+
+  // Target luminance for the foreground to meet the required ratio
+  let targetLum: number;
+  if (fgIsLighter) {
+    // fg is lighter: ratio = (fgLum + 0.05) / (bgLum + 0.05)
+    // Try making fg lighter first
+    targetLum = targetRatio * (bgLum + 0.05) - 0.05;
+    if (targetLum > 1) {
+      // Can't go lighter enough — go darker instead
+      targetLum = (bgLum + 0.05) / targetRatio - 0.05;
+    }
+  } else {
+    // fg is darker: ratio = (bgLum + 0.05) / (fgLum + 0.05)
+    // Try making fg darker first
+    targetLum = (bgLum + 0.05) / targetRatio - 0.05;
+    if (targetLum < 0) {
+      // Can't go darker enough — go lighter instead
+      targetLum = targetRatio * (bgLum + 0.05) - 0.05;
+    }
+  }
+
+  targetLum = Math.max(0, Math.min(1, targetLum));
+
+  // Scale the fg color channels proportionally to reach target luminance
+  return adjustToLuminance(fg, targetLum);
+}
+
+/**
+ * Adjust an RGB color to reach the target relative luminance.
+ * Scales channels proportionally, clamping at boundaries.
+ */
+function adjustToLuminance(color: RGB, targetLum: number): string {
+  const currentLum = relativeLuminance(color.r, color.g, color.b);
+
+  if (currentLum === 0) {
+    // Pure black — can only go to grayscale
+    // Solve: 0.2126*L + 0.7152*L + 0.0722*L = targetLum where L = linearize(v)
+    // => L = targetLum, v = delinearize(targetLum)
+    const v = delinearize(targetLum);
+    const channel = Math.round(v * 255);
+    return rgbToHex(channel, channel, channel);
+  }
+
+  // Binary search for the right scale factor
+  let lo = 0;
+  let hi = 10;
+  let bestHex = rgbToHex(color.r, color.g, color.b);
+  let bestDiff = Infinity;
+
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const r = Math.max(0, Math.min(255, Math.round(color.r * mid)));
+    const g = Math.max(0, Math.min(255, Math.round(color.g * mid)));
+    const b = Math.max(0, Math.min(255, Math.round(color.b * mid)));
+    const lum = relativeLuminance(r, g, b);
+    const diff = Math.abs(lum - targetLum);
+
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      bestHex = rgbToHex(r, g, b);
+    }
+
+    if (lum < targetLum) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+
+  return bestHex;
+}
+
+/**
+ * Reverse sRGB linearization: linear -> sRGB channel (0-1 range).
+ */
+function delinearize(linear: number): number {
+  return linear <= 0.0031308
+    ? linear * 12.92
+    : 1.055 * Math.pow(linear, 1 / 2.4) - 0.055;
+}

package/src/theme/generator.ts

@@ -10,7 +10,16 @@ import type {
   ThemeConfig,
   TokenGeneratorOptions,
   TokenGeneratorResult,
+  ContrastPair,
+  ContrastWarning,
+  ContrastValidationResult,
 } from "./types.js";
+import {
+  parseColor,
+  contrastRatio,
+  meetsAA as checkAA,
+  meetsAAA as checkAAA,
+} from "./contrast.js";
 
 const DEFAULT_FILE_PREFIX = "_theme-tokens";
 
@@ -31,6 +40,10 @@ const TOKEN_MAPPINGS = {
     successBg: "fui-color-success-bg",
     warningBg: "fui-color-warning-bg",
     infoBg: "fui-color-info-bg",
+    dangerText: "fui-color-danger-text",
+    successText: "fui-color-success-text",
+    warningText: "fui-color-warning-text",
+    infoText: "fui-color-info-text",
   },
   surfaces: {
     bgPrimary: "fui-bg-primary",
@@ -100,6 +113,10 @@ const DARK_TOKEN_MAPPINGS = {
   successBg: "fui-dark-color-success-bg",
   warningBg: "fui-dark-color-warning-bg",
   infoBg: "fui-dark-color-info-bg",
+  dangerText: "fui-dark-color-danger-text",
+  successText: "fui-dark-color-success-text",
+  warningText: "fui-dark-color-warning-text",
+  infoText: "fui-dark-color-info-text",
   backdrop: "fui-dark-backdrop",
 } as const;
 
@@ -162,7 +179,7 @@ function generateDarkTokens(
   }
 
   // Handle direct dark mode properties
-  const directProps = ["dangerBg", "successBg", "warningBg", "infoBg", "backdrop"] as const;
+  const directProps = ["dangerBg", "successBg", "warningBg", "infoBg", "dangerText", "successText", "warningText", "infoText", "backdrop"] as const;
   for (const prop of directProps) {
     const value = config.dark[prop];
     if (value !== undefined) {
@@ -180,6 +197,186 @@ function generateDarkTokens(
   return tokens;
 }
 
+/**
+ * Validate contrast across all text/surface token pairs in a theme.
+ *
+ * Returns `ContrastValidationResult` with every evaluated pair plus
+ * errors (fails AA) and warnings (passes AA, fails AAA).
+ */
+export function validateContrast(config: ThemeConfig): ContrastValidationResult {
+  const pairs: ContrastPair[] = [];
+  const warnings: ContrastWarning[] = [];
+  const errors: ContrastWarning[] = [];
+
+  const textTokens = [
+    { key: 'primary', token: 'text.primary' },
+    { key: 'secondary', token: 'text.secondary' },
+    { key: 'tertiary', token: 'text.tertiary' },
+  ] as const;
+
+  const surfaceTokens = [
+    { key: 'bgPrimary', token: 'surfaces.bgPrimary' },
+    { key: 'bgSecondary', token: 'surfaces.bgSecondary' },
+    { key: 'bgTertiary', token: 'surfaces.bgTertiary' },
+    { key: 'bgElevated', token: 'surfaces.bgElevated' },
+  ] as const;
+
+  // -- Light mode matrix --
+  for (const text of textTokens) {
+    const textColor = config.text?.[text.key];
+    if (!textColor) continue;
+
+    for (const surface of surfaceTokens) {
+      const surfaceColor = config.surfaces?.[surface.key];
+      if (!surfaceColor) continue;
+
+      try {
+        const fg = parseColor(textColor);
+        const bg = parseColor(surfaceColor);
+        const ratio = contrastRatio(fg, bg);
+        const aa = checkAA(ratio);
+        const aaa = checkAAA(ratio);
+
+        const pair: ContrastPair = {
+          textToken: text.token,
+          surfaceToken: surface.token,
+          textColor,
+          surfaceColor,
+          ratio: Math.round(ratio * 100) / 100,
+          meetsAA: aa,
+          meetsAAA: aaa,
+          mode: 'light',
+        };
+        pairs.push(pair);
+
+        if (!aa) {
+          errors.push({
+            message: `${text.token} (${textColor}) on ${surface.token} (${surfaceColor}) — ${pair.ratio}:1 — fails AA (need 4.5:1)`,
+            pair,
+            severity: 'error',
+          });
+        } else if (!aaa) {
+          warnings.push({
+            message: `${text.token} (${textColor}) on ${surface.token} (${surfaceColor}) — ${pair.ratio}:1 — passes AA but fails AAA (need 7:1)`,
+            pair,
+            severity: 'warning',
+          });
+        }
+      } catch {
+        // Skip unparseable colors (e.g. rgba with alpha)
+      }
+    }
+  }
+
+  // inverse text on accent
+  if (config.text?.inverse && config.colors?.accent) {
+    try {
+      const fg = parseColor(config.text.inverse);
+      const bg = parseColor(config.colors.accent);
+      const ratio = contrastRatio(fg, bg);
+      const aa = checkAA(ratio);
+      const aaa = checkAAA(ratio);
+
+      const pair: ContrastPair = {
+        textToken: 'text.inverse',
+        surfaceToken: 'colors.accent',
+        textColor: config.text.inverse,
+        surfaceColor: config.colors.accent,
+        ratio: Math.round(ratio * 100) / 100,
+        meetsAA: aa,
+        meetsAAA: aaa,
+        mode: 'light',
+      };
+      pairs.push(pair);
+
+      if (!aa) {
+        errors.push({
+          message: `text.inverse (${config.text.inverse}) on colors.accent (${config.colors.accent}) — ${pair.ratio}:1 — fails AA`,
+          pair,
+          severity: 'error',
+        });
+      } else if (!aaa) {
+        warnings.push({
+          message: `text.inverse (${config.text.inverse}) on colors.accent (${config.colors.accent}) — ${pair.ratio}:1 — passes AA but fails AAA`,
+          pair,
+          severity: 'warning',
+        });
+      }
+    } catch {
+      // skip
+    }
+  }
+
+  // -- Dark mode matrix --
+  if (config.dark) {
+    const darkTextTokens = [
+      { key: 'primary' as const, token: 'dark.text.primary' },
+      { key: 'secondary' as const, token: 'dark.text.secondary' },
+      { key: 'tertiary' as const, token: 'dark.text.tertiary' },
+    ];
+
+    const darkSurfaceTokens = [
+      { key: 'bgPrimary' as const, token: 'dark.surfaces.bgPrimary' },
+      { key: 'bgSecondary' as const, token: 'dark.surfaces.bgSecondary' },
+      { key: 'bgTertiary' as const, token: 'dark.surfaces.bgTertiary' },
+      { key: 'bgElevated' as const, token: 'dark.surfaces.bgElevated' },
+    ];
+
+    for (const text of darkTextTokens) {
+      const textColor = config.dark.text?.[text.key] ?? config.text?.[text.key];
+      if (!textColor) continue;
+
+      for (const surface of darkSurfaceTokens) {
+        const surfaceColor = config.dark.surfaces?.[surface.key] ?? config.surfaces?.[surface.key];
+        if (!surfaceColor) continue;
+
+        try {
+          const fg = parseColor(textColor);
+          const bg = parseColor(surfaceColor);
+          const ratio = contrastRatio(fg, bg);
+          const aa = checkAA(ratio);
+          const aaa = checkAAA(ratio);
+
+          const pair: ContrastPair = {
+            textToken: text.token,
+            surfaceToken: surface.token,
+            textColor,
+            surfaceColor,
+            ratio: Math.round(ratio * 100) / 100,
+            meetsAA: aa,
+            meetsAAA: aaa,
+            mode: 'dark',
+          };
+          pairs.push(pair);
+
+          if (!aa) {
+            errors.push({
+              message: `${text.token} (${textColor}) on ${surface.token} (${surfaceColor}) — ${pair.ratio}:1 — fails AA`,
+              pair,
+              severity: 'error',
+            });
+          } else if (!aaa) {
+            warnings.push({
+              message: `${text.token} (${textColor}) on ${surface.token} (${surfaceColor}) — ${pair.ratio}:1 — passes AA but fails AAA`,
+              pair,
+              severity: 'warning',
+            });
+          }
+        } catch {
+          // skip
+        }
+      }
+    }
+  }
+
+  return {
+    pairs,
+    warnings,
+    errors,
+    passed: errors.length === 0,
+  };
+}
+
 /**
  * Generate SCSS tokens from a theme configuration
  *
@@ -329,6 +526,21 @@ export async function generateTokenFiles(
 
     const result: TokenGeneratorResult = { success: true };
 
+    // Run contrast validation (non-blocking)
+    const contrastResult = validateContrast(config);
+    result.contrastValidation = contrastResult;
+
+    if (contrastResult.errors.length > 0) {
+      for (const err of contrastResult.errors) {
+        console.warn(`[contrast] ERROR: ${err.message}`);
+      }
+    }
+    if (contrastResult.warnings.length > 0) {
+      for (const warn of contrastResult.warnings) {
+        console.warn(`[contrast] WARNING: ${warn.message}`);
+      }
+    }
+
     // Generate SCSS if requested
     if (format === "scss" || format === "both") {
       const scssContent = generateScssTokens(config);

package/src/theme/index.ts

@@ -19,6 +19,9 @@ export type {
   TokenGeneratorOptions,
   TokenGeneratorResult,
   PresetName,
+  ContrastPair,
+  ContrastWarning,
+  ContrastValidationResult,
 } from "./types.js";
 
 // Schema validation
@@ -49,8 +52,21 @@ export {
   generateScssTokens,
   generateCssTokens,
   generateTokenFiles,
+  validateContrast,
 } from "./generator.js";
 
+// Contrast utilities
+export {
+  parseColor,
+  relativeLuminance,
+  contrastRatio,
+  meetsAA,
+  meetsAAA,
+  rgbToHex,
+  suggestFix,
+} from "./contrast.js";
+export type { RGB } from "./contrast.js";
+
 // Presets
 export {
   DEFAULT_PRESET,

package/src/theme/types.ts

@@ -32,6 +32,14 @@ export interface ThemeColors {
   warningBg?: string;
   /** Info background - $fui-color-info-bg */
   infoBg?: string;
+  /** Danger text (WCAG AA safe) - $fui-color-danger-text */
+  dangerText?: string;
+  /** Success text (WCAG AA safe) - $fui-color-success-text */
+  successText?: string;
+  /** Warning text (WCAG AA safe) - $fui-color-warning-text */
+  warningText?: string;
+  /** Info text (WCAG AA safe) - $fui-color-info-text */
+  infoText?: string;
 }
 
 /**
@@ -138,6 +146,14 @@ export interface ThemeDarkMode {
   infoBg?: string;
   /** Backdrop/overlay color for dark mode - $fui-dark-backdrop */
   backdrop?: string;
+  /** Danger text for dark mode (WCAG AA safe) - $fui-dark-color-danger-text */
+  dangerText?: string;
+  /** Success text for dark mode (WCAG AA safe) - $fui-dark-color-success-text */
+  successText?: string;
+  /** Warning text for dark mode (WCAG AA safe) - $fui-dark-color-warning-text */
+  warningText?: string;
+  /** Info text for dark mode (WCAG AA safe) - $fui-dark-color-info-text */
+  infoText?: string;
 }
 
 /**
@@ -202,6 +218,41 @@ export interface TokenGeneratorResult {
   cssPath?: string;
   /** Error message if generation failed */
   error?: string;
+  /** Contrast validation results (if theme has color tokens) */
+  contrastValidation?: ContrastValidationResult;
+}
+
+/**
+ * A text/surface color pair evaluated for contrast compliance
+ */
+export interface ContrastPair {
+  textToken: string;
+  surfaceToken: string;
+  textColor: string;
+  surfaceColor: string;
+  ratio: number;
+  meetsAA: boolean;
+  meetsAAA: boolean;
+  mode: "light" | "dark";
+}
+
+/**
+ * A contrast validation warning or error
+ */
+export interface ContrastWarning {
+  message: string;
+  pair: ContrastPair;
+  severity: "error" | "warning";
+}
+
+/**
+ * Result of validating contrast across all theme token pairs
+ */
+export interface ContrastValidationResult {
+  pairs: ContrastPair[];
+  warnings: ContrastWarning[];
+  errors: ContrastWarning[];
+  passed: boolean;
 }
 
 /**