@almadar/ui 5.128.0 → 5.129.0

package/scripts/theme-contrast-audit.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * WCAG contrast audit for theme CSS files.
+ * Parses each [data-theme="..."] block, resolves var() aliases and rgba
+ * compositing over the theme's own background, then checks the canonical
+ * foreground/background pairs every component relies on.
+ *
+ * Usage:
+ *   node theme-contrast-audit.mjs [--dir <themes-dir>] [file-filter]
+ *
+ * Defaults to this package's own themes/ dir. Apps that ship their own
+ * [data-theme] files (e.g. apps/kflow's design-system/themes) run the same
+ * audit against that dir via --dir so app-local themes stay gated.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+let themesDir = resolve(__dirname, '..', 'themes');
+let filter;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--dir') {
+    themesDir = resolve(process.cwd(), args[++i]);
+  } else {
+    filter = args[i];
+  }
+}
+
+const PAIRS = [
+  ['--color-foreground', '--color-background'],
+  ['--color-card-foreground', '--color-card'],
+  ['--color-primary-foreground', '--color-primary'],
+  ['--color-primary-foreground', '--color-primary-hover'],
+  ['--color-secondary-foreground', '--color-secondary'],
+  ['--color-secondary-foreground', '--color-secondary-hover'],
+  ['--color-accent-foreground', '--color-accent'],
+  ['--color-muted-foreground', '--color-muted'],
+  ['--color-muted-foreground', '--color-card'],
+  ['--color-error-foreground', '--color-error'],
+  ['--color-success-foreground', '--color-success'],
+  ['--color-warning-foreground', '--color-warning'],
+  ['--color-info-foreground', '--color-info'],
+];
+
+function parseColor(raw) {
+  const s = raw.trim();
+  let m = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+  if (m) {
+    let h = m[1];
+    if (h.length === 3) h = h.split('').map(c => c + c).join('');
+    const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
+    const a = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+  m = s.match(/^rgba?\(([^)]+)\)$/i);
+  if (m) {
+    const parts = m[1].split(',').map(p => parseFloat(p));
+    return { r: parts[0], g: parts[1], b: parts[2], a: parts.length > 3 ? parts[3] : 1 };
+  }
+  return null;
+}
+
+function compositeOver(fg, bg) {
+  const a = fg.a + bg.a * (1 - fg.a);
+  if (a === 0) return { r: 0, g: 0, b: 0 };
+  return {
+    r: (fg.r * fg.a + bg.r * bg.a * (1 - fg.a)) / a,
+    g: (fg.g * fg.a + bg.g * bg.a * (1 - fg.a)) / a,
+    b: (fg.b * fg.a + bg.b * bg.a * (1 - fg.a)) / a,
+  };
+}
+
+function luminance({ r, g, b }) {
+  const f = c => {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+
+function contrast(c1, c2) {
+  const l1 = luminance(c1), l2 = luminance(c2);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+
+const files = readdirSync(themesDir).filter(f => f.endsWith('.css') && !f.startsWith('_') && f !== 'index.css' && (!filter || f === filter));
+let violations = 0;
+
+for (const file of files.sort()) {
+  const css = readFileSync(resolve(themesDir, file), 'utf8');
+  const blocks = [...css.matchAll(/\[data-theme="([^"]+)"\]\s*\{([^}]*)\}/gs)];
+  for (const [, themeName, body] of blocks) {
+    const vars = {};
+    for (const decl of body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+      vars[decl[1]] = decl[2].trim();
+    }
+    const resolveVar = (name, depth = 0) => {
+      let v = vars[name];
+      if (v === undefined || depth > 5) return undefined;
+      const ref = v.match(/^var\((--[\w-]+)\)$/);
+      if (ref) return resolveVar(ref[1], depth + 1);
+      return v;
+    };
+    const bgRaw = resolveVar('--color-background');
+    const bg = bgRaw ? parseColor(bgRaw) : null;
+    const results = [];
+    for (const [fgName, bgName] of PAIRS) {
+      const fgRaw = resolveVar(fgName);
+      const bgRaw2 = resolveVar(bgName);
+      if (!fgRaw || !bgRaw2) continue;
+      const fg = parseColor(fgRaw);
+      let bgc = parseColor(bgRaw2);
+      if (!fg || !bgc) continue;
+      // Composite translucent fills over the theme background
+      if (bgc.a < 1 && bg) bgc = { ...compositeOver(bgc, bg), a: 1 };
+      if (fg.a < 1 && bg) { const c = compositeOver(fg, bgc); fg.r = c.r; fg.g = c.g; fg.b = c.b; }
+      const ratio = contrast(fg, bgc);
+      // Text on filled surfaces needs 4.5:1 (WCAG AA normal text)
+      if (ratio < 4.5) results.push({ pair: `${fgName} on ${bgName}`, ratio: ratio.toFixed(2), fg: fgRaw, bg: bgRaw2 });
+    }
+    if (results.length) {
+      violations += results.length;
+      console.log(`\n${themeName}  (${file})`);
+      for (const r of results) console.log(`  FAIL ${r.ratio}:1  ${r.pair}   fg=${r.fg} bg=${r.bg}`);
+    }
+  }
+}
+console.log(violations === 0 ? '\nAll theme pairs pass WCAG AA (4.5:1).' : `\n${violations} violation(s).`);
+process.exit(violations === 0 ? 0 : 1);

package/scripts/types.ts

@@ -0,0 +1,282 @@
+/**
+ * Design System Generator Types
+ *
+ * Input configuration for generating a customized design system
+ * that gets output to a project folder.
+ */
+
+export interface DesignSystemConfig {
+  /** Project/client name (e.g., "winning-11") */
+  projectName: string;
+
+  /** Output directory for the generated design system */
+  outputDir: string;
+
+  /** Theme configuration */
+  theme: ThemeConfig;
+
+  /** Custom components not in the standard library */
+  customComponents?: CustomComponentConfig[];
+
+  /** Which standard components to include (default: all) */
+  includeComponents?: ComponentFilter;
+
+  /** Storybook configuration */
+  storybook?: StorybookConfig;
+}
+
+export interface ThemeConfig {
+  /** Theme name (used in data-design-theme attribute) */
+  name: string;
+
+  /** Theme display name for documentation */
+  displayName?: string;
+
+  /** Design metaphor/style description */
+  metaphor?: string;
+
+  /** Color palette */
+  colors: {
+    primary: string;
+    primaryHover?: string;
+    primaryForeground?: string;
+    secondary: string;
+    secondaryHover?: string;
+    secondaryForeground?: string;
+    accent: string;
+    accentForeground?: string;
+    muted: string;
+    mutedForeground?: string;
+    background: string;
+    foreground: string;
+    card?: string;
+    cardForeground?: string;
+    border: string;
+    input?: string;
+    ring?: string;
+
+    /** Semantic colors */
+    success?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+
+    /** Custom domain-specific colors */
+    custom?: Record<string, string>;
+  };
+
+  /** Shadow style preset or custom shadows */
+  shadows?: 'soft-organic' | 'minimal' | 'corporate' | 'playful' | 'dramatic' | 'soft' | ShadowConfig;
+
+  /** Border radius preset or custom radii */
+  radius?: 'organic' | 'gentle' | 'sharp' | 'rounded' | 'friendly' | RadiusConfig;
+
+  /** Typography overrides */
+  typography?: {
+    fontFamily?: string;
+    fontWeightNormal?: number;
+    fontWeightMedium?: number;
+    fontWeightBold?: number;
+  };
+
+  /** Dark mode variant */
+  darkMode?: Partial<ThemeConfig['colors']>;
+}
+
+export interface ShadowConfig {
+  main: string;
+  sm: string;
+  lg: string;
+  hover: string;
+  inner?: string;
+  active?: string;
+}
+
+export interface RadiusConfig {
+  sm: string;
+  md: string;
+  lg: string;
+  xl: string;
+}
+
+export interface CustomComponentConfig {
+  /** Component name (PascalCase) */
+  name: string;
+
+  /** Component description */
+  description: string;
+
+  /** Category in the component library */
+  category: 'atoms' | 'molecules' | 'organisms' | 'templates';
+
+  /** Component props */
+  props: ComponentProp[];
+
+  /** Why this component is needed */
+  reasoning?: string;
+
+  /** Priority for implementation */
+  priority?: 'high' | 'medium' | 'low';
+
+  /** Optional implementation code */
+  implementation?: string;
+
+  /** Optional Storybook stories */
+  stories?: string;
+}
+
+export interface ComponentProp {
+  name: string;
+  type: string;
+  description: string;
+  required?: boolean;
+  defaultValue?: string;
+}
+
+export interface ComponentFilter {
+  /** Include all components (default: true) */
+  all?: boolean;
+
+  /** Specific categories to include */
+  categories?: ('atoms' | 'molecules' | 'organisms' | 'templates')[];
+
+  /** Specific components to include (by name) */
+  include?: string[];
+
+  /** Specific components to exclude (by name) */
+  exclude?: string[];
+}
+
+export interface StorybookConfig {
+  /** Build Storybook (default: true) */
+  build?: boolean;
+
+  /** Include Storybook source in output (default: true) */
+  includeSource?: boolean;
+
+  /** Custom Storybook title */
+  title?: string;
+}
+
+/**
+ * Example configuration for Winning-11 (Garden theme)
+ */
+export const WINNING_11_CONFIG: DesignSystemConfig = {
+  projectName: 'winning-11',
+  outputDir: '/path/to/winning-11/design-system',
+
+  theme: {
+    name: 'winning-11',
+    displayName: 'Winning 11 Garden Theme',
+    metaphor: 'organic growth, trust, cultivation',
+
+    colors: {
+      primary: '#15803d',
+      primaryHover: '#166534',
+      primaryForeground: '#ffffff',
+      secondary: '#fef7ed',
+      secondaryForeground: '#78350f',
+      accent: '#ca8a04',
+      accentForeground: '#ffffff',
+      muted: '#ecfccb',
+      mutedForeground: '#365314',
+      background: '#fefefe',
+      foreground: '#1a2e05',
+      border: '#bbf7d0',
+
+      success: '#22c55e',
+      warning: '#f59e0b',
+      error: '#dc2626',
+      info: '#0ea5e9',
+
+      custom: {
+        'garden-leaf': '#22c55e',
+        'garden-stem': '#15803d',
+        'garden-soil': '#78350f',
+        'garden-water': '#0ea5e9',
+        'garden-sun': '#fbbf24',
+        'trust-low': '#fbbf24',
+        'trust-medium': '#22c55e',
+        'trust-high': '#15803d',
+        'trust-verified': '#0ea5e9',
+      },
+    },
+
+    shadows: 'soft-organic',
+    radius: 'organic',
+
+    darkMode: {
+      primary: '#4ade80',
+      primaryHover: '#86efac',
+      background: '#0f1a0a',
+      foreground: '#ecfccb',
+      card: '#14532d',
+      border: '#166534',
+    },
+  },
+
+  customComponents: [
+    {
+      name: 'GardenView',
+      description: 'Visual garden layout showing plants in a grid or organic arrangement',
+      category: 'organisms',
+      priority: 'high',
+      props: [
+        { name: 'plants', type: 'Plant[]', description: 'Array of plants to display', required: true },
+        { name: 'layout', type: "'grid' | 'organic'", description: 'Layout style', defaultValue: "'grid'" },
+        { name: 'onPlantClick', type: '(plant: Plant) => void', description: 'Plant selection handler' },
+      ],
+      reasoning: 'Core visualization for garden/agriculture domain',
+    },
+    {
+      name: 'PlantCard',
+      description: 'Card displaying a single plant with growth status and care indicators',
+      category: 'molecules',
+      priority: 'high',
+      props: [
+        { name: 'plant', type: 'Plant', description: 'Plant data to display', required: true },
+        { name: 'showCareIndicators', type: 'boolean', description: 'Show water/sun needs', defaultValue: 'true' },
+        { name: 'onClick', type: '() => void', description: 'Click handler' },
+      ],
+      reasoning: 'Essential card for displaying individual plant information',
+    },
+    {
+      name: 'GrowthMeter',
+      description: 'Progress indicator showing plant growth stage',
+      category: 'atoms',
+      priority: 'high',
+      props: [
+        { name: 'progress', type: 'number', description: 'Growth progress 0-100', required: true },
+        { name: 'stages', type: 'string[]', description: 'Growth stage labels' },
+      ],
+      reasoning: 'Visual feedback for growth/progress - core to garden metaphor',
+    },
+    {
+      name: 'TrustMeter',
+      description: 'Visual indicator for trust/relationship level between entities',
+      category: 'atoms',
+      priority: 'high',
+      props: [
+        { name: 'level', type: "'low' | 'medium' | 'high' | 'verified'", description: 'Trust level', required: true },
+        { name: 'showLabel', type: 'boolean', description: 'Show text label', defaultValue: 'true' },
+      ],
+      reasoning: 'Visualize trust between farmers and buyers in Winning-11',
+    },
+    {
+      name: 'CareIndicator',
+      description: 'Small icon indicator for plant care needs',
+      category: 'atoms',
+      priority: 'medium',
+      props: [
+        { name: 'type', type: "'water' | 'sun' | 'nutrients'", description: 'Care type', required: true },
+        { name: 'level', type: "'low' | 'medium' | 'high'", description: 'Need level', required: true },
+      ],
+      reasoning: 'Quick visual cues for plant care requirements',
+    },
+  ],
+
+  storybook: {
+    build: true,
+    title: 'Winning 11 Design System',
+  },
+};

package/themes/_contract.md

@@ -221,5 +221,5 @@ instantly regardless of theme.
 3. **No raw pixel literals in components**. All dimensional values flow through these tokens or through Tailwind utilities backed by them in `tailwind-preset.cjs`. Components that hardcode `text-[10px]` or `min-w-[44px]` are migration targets.
 4. **Icon family swap is runtime-resolved**. `--icon-family` is read by the icon resolver in `@almadar/ui`; setting the variable in a theme does not require component edits.
 5. **Wireframe and trait-wars exceptions**. Wireframe's `--easing-standard` is `linear` not the default cubic-bezier; trait-wars's iconography may remain `lucide` even if its visual personality diverges. Document any per-theme override at the top of the theme file.
-6. **Contrast is gated.** Every theme's canonical foreground/fill pairs must pass WCAG AA 4.5:1 — enforced by `scripts/theme-contrast-audit.mjs` (`pnpm verify:themes`), which runs in CI and before every npm publish. A new or edited theme that fails the audit blocks the publish.
+6. **Contrast is gated.** Every theme's canonical foreground/fill pairs must pass WCAG AA 4.5:1 — enforced by `scripts/theme-contrast-audit.mjs` (`pnpm verify:themes`), which runs in CI and before every npm publish and exits non-zero on any violation. A new or edited theme that fails the audit blocks the publish. The script also accepts `--dir <themes-dir>` (`scripts/` is published) so another package can audit its own theme dir with the same rules.
 7. **No hardcoded palette colors in components.** Components must consume these tokens only (no `text-white`, `bg-gray-800`, `border-indigo-300`, `text-[#hex]`). Enforced by the `almadar/no-hardcoded-colors` ESLint rule (`@almadar/eslint-plugin`, enabled in this package's `eslint.config.cjs`). The single sanctioned exception is media-overlay chrome (white text / dark scrims painted over images or video), which requires an inline `eslint-disable-next-line almadar/no-hardcoded-colors` comment stating the reason.