@fragments-sdk/cli 0.5.2 → 0.7.0

package/src/theme/__tests__/contrast-validation.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi } from 'vitest';
+import { validateContrast, generateTokenFiles } from '../generator.js';
+import type { ThemeConfig } from '../types.js';
+import { DEFAULT_PRESET } from '../presets.js';
+
+describe('validateContrast', () => {
+  describe('result shape', () => {
+    it('returns an object with pairs, warnings, errors, and passed', () => {
+      const result = validateContrast({ name: 'empty' });
+      expect(result).toHaveProperty('pairs');
+      expect(result).toHaveProperty('warnings');
+      expect(result).toHaveProperty('errors');
+      expect(result).toHaveProperty('passed');
+    });
+
+    it('returns arrays for pairs, warnings, and errors', () => {
+      const result = validateContrast({ name: 'empty' });
+      expect(Array.isArray(result.pairs)).toBe(true);
+      expect(Array.isArray(result.warnings)).toBe(true);
+      expect(Array.isArray(result.errors)).toBe(true);
+    });
+
+    it('returns boolean for passed', () => {
+      const result = validateContrast({ name: 'empty' });
+      expect(typeof result.passed).toBe('boolean');
+    });
+  });
+
+  describe('default preset — light mode', () => {
+    const result = validateContrast(DEFAULT_PRESET);
+    const lightPairs = result.pairs.filter(p => p.mode === 'light');
+
+    it('produces 13 light mode pairs (3 text x 4 surface + 1 inverse-on-accent)', () => {
+      expect(lightPairs.length).toBe(13);
+    });
+
+    it('includes text.primary on all 4 surfaces', () => {
+      const primaryPairs = lightPairs.filter(p => p.textToken === 'text.primary');
+      expect(primaryPairs.length).toBe(4);
+    });
+
+    it('includes text.secondary on all 4 surfaces', () => {
+      const secondaryPairs = lightPairs.filter(p => p.textToken === 'text.secondary');
+      expect(secondaryPairs.length).toBe(4);
+    });
+
+    it('includes text.tertiary on all 4 surfaces', () => {
+      const tertiaryPairs = lightPairs.filter(p => p.textToken === 'text.tertiary');
+      expect(tertiaryPairs.length).toBe(4);
+    });
+
+    it('includes inverse text on accent', () => {
+      const inversePair = lightPairs.find(
+        p => p.textToken === 'text.inverse' && p.surfaceToken === 'colors.accent'
+      );
+      expect(inversePair).toBeDefined();
+      expect(inversePair!.meetsAA).toBe(false); // ~3.95:1 < 4.5:1
+    });
+
+    it('reports passed as false due to inverse-on-accent failure', () => {
+      expect(result.passed).toBe(false);
+    });
+
+    it('errors have severity "error"', () => {
+      for (const err of result.errors) {
+        expect(err.severity).toBe('error');
+      }
+    });
+  });
+
+  describe('default preset — dark mode', () => {
+    const result = validateContrast(DEFAULT_PRESET);
+    const darkPairs = result.pairs.filter(p => p.mode === 'dark');
+
+    it('produces 12 dark mode pairs (3 text x 4 surface)', () => {
+      expect(darkPairs.length).toBe(12);
+    });
+
+    it('dark token names use dark.text.* prefix', () => {
+      for (const pair of darkPairs) {
+        expect(pair.textToken).toMatch(/^dark\.text\./);
+      }
+    });
+
+    it('dark surface tokens use dark.surfaces.* prefix', () => {
+      for (const pair of darkPairs) {
+        expect(pair.surfaceToken).toMatch(/^dark\.surfaces\./);
+      }
+    });
+  });
+
+  describe('partial config', () => {
+    it('no text tokens → 0 pairs', () => {
+      const config: ThemeConfig = {
+        name: 'no-text',
+        surfaces: { bgPrimary: '#ffffff' },
+      };
+      const result = validateContrast(config);
+      expect(result.pairs.length).toBe(0);
+      expect(result.passed).toBe(true);
+    });
+
+    it('no surfaces → 0 matrix pairs (only inverse-on-accent if present)', () => {
+      const config: ThemeConfig = {
+        name: 'no-surfaces',
+        text: { primary: '#000000' },
+      };
+      const result = validateContrast(config);
+      expect(result.pairs.length).toBe(0);
+    });
+
+    it('no dark mode → light-only pairs', () => {
+      const config: ThemeConfig = {
+        name: 'light-only',
+        text: { primary: '#000000', secondary: '#666666' },
+        surfaces: { bgPrimary: '#ffffff' },
+      };
+      const result = validateContrast(config);
+      const darkPairs = result.pairs.filter(p => p.mode === 'dark');
+      expect(darkPairs.length).toBe(0);
+      expect(result.pairs.length).toBe(2); // 2 text x 1 surface
+    });
+
+    it('high contrast theme passes all checks', () => {
+      const config: ThemeConfig = {
+        name: 'high-contrast',
+        text: { primary: '#000000', secondary: '#333333', tertiary: '#555555', inverse: '#ffffff' },
+        surfaces: { bgPrimary: '#ffffff', bgSecondary: '#f5f5f5', bgTertiary: '#eeeeee', bgElevated: '#ffffff' },
+        colors: { accent: '#000000' }, // white on black = 21:1
+      };
+      const result = validateContrast(config);
+      expect(result.passed).toBe(true);
+      expect(result.errors.length).toBe(0);
+    });
+
+    it('text + surfaces but no colors → no inverse-on-accent pair', () => {
+      const config: ThemeConfig = {
+        name: 'no-colors',
+        text: { primary: '#000000', inverse: '#ffffff' },
+        surfaces: { bgPrimary: '#ffffff' },
+      };
+      const result = validateContrast(config);
+      const inversePair = result.pairs.find(p => p.textToken === 'text.inverse');
+      expect(inversePair).toBeUndefined();
+    });
+  });
+
+  describe('unparseable colors', () => {
+    it('CSS variable text/surface are silently skipped (0 pairs)', () => {
+      const config: ThemeConfig = {
+        name: 'css-vars',
+        text: { primary: 'var(--text-color)' },
+        surfaces: { bgPrimary: 'var(--bg-color)' },
+      };
+      const result = validateContrast(config);
+      expect(result.pairs.length).toBe(0);
+      expect(result.errors.length).toBe(0);
+    });
+
+    it('does not throw on unparseable colors', () => {
+      const config: ThemeConfig = {
+        name: 'mixed',
+        text: { primary: 'invalid-color', secondary: '#333333' },
+        surfaces: { bgPrimary: '#ffffff', bgSecondary: 'not-a-color' },
+      };
+      expect(() => validateContrast(config)).not.toThrow();
+      const result = validateContrast(config);
+      // Only #333333 on #ffffff should produce a pair
+      expect(result.pairs.length).toBe(1);
+    });
+  });
+
+  describe('preset integration', () => {
+    it('neutral preset (partial — colors only) yields inverse-on-accent pair', () => {
+      const config: ThemeConfig = {
+        name: 'Neutral',
+        colors: { accent: '#71717a' },
+        text: { inverse: '#ffffff' },
+      };
+      const result = validateContrast(config);
+      const inversePair = result.pairs.find(p => p.textToken === 'text.inverse');
+      expect(inversePair).toBeDefined();
+    });
+
+    it('merged config works correctly', () => {
+      const config: ThemeConfig = {
+        ...DEFAULT_PRESET,
+        name: 'merged',
+        colors: { ...DEFAULT_PRESET.colors, accent: '#1e40af' }, // darker blue
+      };
+      const result = validateContrast(config);
+      const inversePair = result.pairs.find(
+        p => p.textToken === 'text.inverse' && p.surfaceToken === 'colors.accent'
+      );
+      expect(inversePair).toBeDefined();
+      expect(inversePair!.ratio).toBeGreaterThan(4.5); // white on dark blue passes
+    });
+
+    it('ratios are rounded to 2 decimal places', () => {
+      const result = validateContrast(DEFAULT_PRESET);
+      for (const pair of result.pairs) {
+        const decimals = pair.ratio.toString().split('.')[1];
+        if (decimals) {
+          expect(decimals.length).toBeLessThanOrEqual(2);
+        }
+      }
+    });
+
+    it('slate preset with surfaces produces correct number of pairs', () => {
+      const config: ThemeConfig = {
+        name: 'Slate',
+        colors: { accent: '#64748b' },
+        text: { primary: '#0f172a', inverse: '#ffffff' },
+        surfaces: { bgPrimary: '#ffffff', bgSecondary: '#f1f5f9' },
+      };
+      const result = validateContrast(config);
+      // 1 text x 2 surfaces + 1 inverse-on-accent = 3
+      expect(result.pairs.length).toBe(3);
+    });
+  });
+
+  describe('custom DS themes (BYODS)', () => {
+    it('corporate brand (navy/gold) validates correctly', () => {
+      const config: ThemeConfig = {
+        name: 'CorporateBrand',
+        text: { primary: '#1a1a2e', secondary: '#4a4a6a', tertiary: '#8a8aaa' },
+        surfaces: { bgPrimary: '#f0f0f5', bgSecondary: '#e0e0ea' },
+        colors: { accent: '#c9a62c' },
+      };
+      const result = validateContrast(config);
+      expect(result.pairs.length).toBeGreaterThan(0);
+      // Dark text on light surfaces should mostly pass
+      const primaryPairs = result.pairs.filter(p => p.textToken === 'text.primary');
+      for (const pair of primaryPairs) {
+        expect(pair.meetsAA).toBe(true);
+      }
+    });
+
+    it('high-contrast accessible theme passes AA + AAA', () => {
+      const config: ThemeConfig = {
+        name: 'HighContrastDS',
+        text: { primary: '#000000', secondary: '#1a1a1a', tertiary: '#333333', inverse: '#ffffff' },
+        surfaces: { bgPrimary: '#ffffff', bgSecondary: '#fafafa', bgTertiary: '#f5f5f5', bgElevated: '#ffffff' },
+        colors: { accent: '#000000' },
+      };
+      const result = validateContrast(config);
+      expect(result.passed).toBe(true);
+      expect(result.errors.length).toBe(0);
+      // All pairs should meet AAA
+      for (const pair of result.pairs) {
+        expect(pair.meetsAAA).toBe(true);
+      }
+    });
+
+    it('dark-first theme validates dark mode matrix', () => {
+      const config: ThemeConfig = {
+        name: 'DarkFirstDS',
+        text: { primary: '#e0e0e0' },
+        surfaces: { bgPrimary: '#121212' },
+        dark: {
+          text: { primary: '#f5f5f5', secondary: '#b0b0b0' },
+          surfaces: { bgPrimary: '#0a0a0a', bgSecondary: '#1a1a1a' },
+        },
+      };
+      const result = validateContrast(config);
+      const darkPairs = result.pairs.filter(p => p.mode === 'dark');
+      expect(darkPairs.length).toBe(4); // 2 text x 2 surfaces
+    });
+
+    it('low-contrast brand theme fails with correct errors', () => {
+      const config: ThemeConfig = {
+        name: 'LowContrastBrand',
+        text: { primary: '#aaaaaa' }, // light gray on white = poor contrast
+        surfaces: { bgPrimary: '#ffffff' },
+      };
+      const result = validateContrast(config);
+      expect(result.passed).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0].severity).toBe('error');
+    });
+
+    it('custom theme with HSL colors parses and validates', () => {
+      const config: ThemeConfig = {
+        name: 'HSLTheme',
+        text: { primary: 'hsl(0, 0%, 10%)', secondary: 'hsl(0, 0%, 40%)' },
+        surfaces: { bgPrimary: 'hsl(0, 0%, 100%)', bgSecondary: 'hsl(0, 0%, 95%)' },
+      };
+      const result = validateContrast(config);
+      expect(result.pairs.length).toBe(4); // 2 text x 2 surfaces
+      // Dark text on white should pass
+      const primaryOnWhite = result.pairs.find(
+        p => p.textToken === 'text.primary' && p.surfaceToken === 'surfaces.bgPrimary'
+      );
+      expect(primaryOnWhite?.meetsAA).toBe(true);
+    });
+  });
+
+  describe('generateTokenFiles integration', () => {
+    it('result includes contrastValidation', async () => {
+      const tmpDir = '/tmp/contrast-test-' + Date.now();
+      const result = await generateTokenFiles(DEFAULT_PRESET, {
+        format: 'css',
+        outputDir: tmpDir,
+      });
+      expect(result.success).toBe(true);
+      expect(result.contrastValidation).toBeDefined();
+      expect(result.contrastValidation!.pairs.length).toBeGreaterThan(0);
+    });
+
+    it('console.warn is called when there are contrast errors', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const tmpDir = '/tmp/contrast-warn-test-' + Date.now();
+      await generateTokenFiles(DEFAULT_PRESET, {
+        format: 'css',
+        outputDir: tmpDir,
+      });
+      // Default preset has the inverse-on-accent error
+      expect(warnSpy).toHaveBeenCalled();
+      const errorCalls = warnSpy.mock.calls.filter(
+        call => typeof call[0] === 'string' && call[0].includes('[contrast]')
+      );
+      expect(errorCalls.length).toBeGreaterThan(0);
+      warnSpy.mockRestore();
+    });
+  });
+});

package/src/theme/contrast.test.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseColor,
+  relativeLuminance,
+  contrastRatio,
+  meetsAA,
+  meetsAAA,
+  rgbToHex,
+  suggestFix,
+} from './contrast.js';
+import { deriveSemanticText } from '@fragments/seed-derivation';
+
+describe('parseColor', () => {
+  it('parses 6-digit hex', () => {
+    expect(parseColor('#ffffff')).toEqual({ r: 255, g: 255, b: 255 });
+    expect(parseColor('#000000')).toEqual({ r: 0, g: 0, b: 0 });
+    expect(parseColor('#6366f1')).toEqual({ r: 99, g: 102, b: 241 });
+  });
+
+  it('parses 3-digit hex', () => {
+    expect(parseColor('#fff')).toEqual({ r: 255, g: 255, b: 255 });
+    expect(parseColor('#000')).toEqual({ r: 0, g: 0, b: 0 });
+    expect(parseColor('#f00')).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it('parses 8-digit hex (ignores alpha)', () => {
+    expect(parseColor('#ff0000ff')).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it('parses rgb()', () => {
+    expect(parseColor('rgb(255, 255, 255)')).toEqual({ r: 255, g: 255, b: 255 });
+    expect(parseColor('rgb(99, 102, 241)')).toEqual({ r: 99, g: 102, b: 241 });
+  });
+
+  it('parses rgba()', () => {
+    expect(parseColor('rgba(239, 68, 68, 0.1)')).toEqual({ r: 239, g: 68, b: 68 });
+  });
+
+  it('parses hsl()', () => {
+    const red = parseColor('hsl(0, 100%, 50%)');
+    expect(red.r).toBe(255);
+    expect(red.g).toBe(0);
+    expect(red.b).toBe(0);
+
+    const white = parseColor('hsl(0, 0%, 100%)');
+    expect(white).toEqual({ r: 255, g: 255, b: 255 });
+  });
+
+  it('parses hsla()', () => {
+    const blue = parseColor('hsla(240, 100%, 50%, 0.5)');
+    expect(blue.r).toBe(0);
+    expect(blue.g).toBe(0);
+    expect(blue.b).toBe(255);
+  });
+
+  it('is case-insensitive', () => {
+    expect(parseColor('#FFFFFF')).toEqual({ r: 255, g: 255, b: 255 });
+    expect(parseColor('RGB(0, 0, 0)')).toEqual({ r: 0, g: 0, b: 0 });
+  });
+
+  it('trims whitespace', () => {
+    expect(parseColor('  #fff  ')).toEqual({ r: 255, g: 255, b: 255 });
+  });
+
+  it('throws on invalid input', () => {
+    expect(() => parseColor('not-a-color')).toThrow('Cannot parse color');
+    expect(() => parseColor('')).toThrow('Cannot parse color');
+  });
+});
+
+describe('relativeLuminance', () => {
+  it('returns 1 for white', () => {
+    expect(relativeLuminance(255, 255, 255)).toBeCloseTo(1.0, 4);
+  });
+
+  it('returns 0 for black', () => {
+    expect(relativeLuminance(0, 0, 0)).toBeCloseTo(0.0, 4);
+  });
+});
+
+describe('contrastRatio', () => {
+  it('black on white = 21:1', () => {
+    const ratio = contrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 });
+    expect(ratio).toBeCloseTo(21.0, 0);
+  });
+
+  it('white on white = 1:1', () => {
+    const ratio = contrastRatio({ r: 255, g: 255, b: 255 }, { r: 255, g: 255, b: 255 });
+    expect(ratio).toBeCloseTo(1.0, 4);
+  });
+
+  it('#767676 on #ffffff ~ 4.54:1 (AA boundary)', () => {
+    const fg = parseColor('#767676');
+    const bg = parseColor('#ffffff');
+    const ratio = contrastRatio(fg, bg);
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+    expect(ratio).toBeLessThan(4.6);
+  });
+
+  it('is symmetric (order of fg/bg does not change ratio)', () => {
+    const fg = parseColor('#333333');
+    const bg = parseColor('#ffffff');
+    const ratio1 = contrastRatio(fg, bg);
+    const ratio2 = contrastRatio(bg, fg);
+    expect(ratio1).toBeCloseTo(ratio2, 4);
+  });
+});
+
+describe('meetsAA', () => {
+  it('4.5:1 passes for normal text', () => {
+    expect(meetsAA(4.5)).toBe(true);
+  });
+
+  it('4.49:1 fails for normal text', () => {
+    expect(meetsAA(4.49)).toBe(false);
+  });
+
+  it('3:1 passes for large text', () => {
+    expect(meetsAA(3.0, true)).toBe(true);
+  });
+
+  it('2.9:1 fails for large text', () => {
+    expect(meetsAA(2.9, true)).toBe(false);
+  });
+});
+
+describe('meetsAAA', () => {
+  it('7:1 passes for normal text', () => {
+    expect(meetsAAA(7.0)).toBe(true);
+  });
+
+  it('6.9:1 fails for normal text', () => {
+    expect(meetsAAA(6.9)).toBe(false);
+  });
+
+  it('4.5:1 passes for large text', () => {
+    expect(meetsAAA(4.5, true)).toBe(true);
+  });
+
+  it('4.49:1 fails for large text', () => {
+    expect(meetsAAA(4.49, true)).toBe(false);
+  });
+});
+
+describe('rgbToHex', () => {
+  it('converts white', () => {
+    expect(rgbToHex(255, 255, 255)).toBe('#ffffff');
+  });
+
+  it('converts black', () => {
+    expect(rgbToHex(0, 0, 0)).toBe('#000000');
+  });
+
+  it('clamps out-of-range values', () => {
+    expect(rgbToHex(300, -10, 128)).toBe('#ff0080');
+  });
+});
+
+describe('suggestFix', () => {
+  it('suggests a color that meets the target ratio', () => {
+    const fg = parseColor('#888888');
+    const bg = parseColor('#ffffff');
+    const fixed = suggestFix(fg, bg, 4.5);
+    const fixedRgb = parseColor(fixed);
+    const ratio = contrastRatio(fixedRgb, bg);
+    // Allow small rounding tolerance from integer RGB clamping
+    expect(ratio).toBeGreaterThanOrEqual(4.4);
+  });
+
+  it('handles dark bg with light fg', () => {
+    const fg = parseColor('#999999');
+    const bg = parseColor('#1a1a1a');
+    const fixed = suggestFix(fg, bg, 4.5);
+    const fixedRgb = parseColor(fixed);
+    const ratio = contrastRatio(fixedRgb, bg);
+    expect(ratio).toBeGreaterThanOrEqual(4.4);
+  });
+
+  it('returns a valid hex color', () => {
+    const fg = parseColor('#666666');
+    const bg = parseColor('#ffffff');
+    const fixed = suggestFix(fg, bg, 7.0);
+    expect(fixed).toMatch(/^#[0-9a-f]{6}$/);
+  });
+});
+
+describe('default preset color pairs', () => {
+  const passingPairs = [
+    { name: 'primary text on primary bg', fg: '#0f172a', bg: '#ffffff' },
+    { name: 'secondary text on primary bg', fg: '#64748b', bg: '#ffffff' },
+    { name: 'primary text on secondary bg', fg: '#0f172a', bg: '#f8fafc' },
+  ];
+
+  for (const pair of passingPairs) {
+    it(`${pair.name} meets AA`, () => {
+      const fg = parseColor(pair.fg);
+      const bg = parseColor(pair.bg);
+      const ratio = contrastRatio(fg, bg);
+      expect(meetsAA(ratio)).toBe(true);
+    });
+  }
+
+  it('inverse text on accent (#6366f1) fails AA for normal text (known)', () => {
+    // White on indigo-500 is ~3.95:1, below 4.5:1 threshold for normal text.
+    // Passes for large text (3:1). This is a real accessibility finding.
+    const fg = parseColor('#ffffff');
+    const bg = parseColor('#6366f1');
+    const ratio = contrastRatio(fg, bg);
+    expect(meetsAA(ratio)).toBe(false);
+    expect(meetsAA(ratio, true)).toBe(true); // passes for large text
+  });
+});
+
+describe('suggestFix edge cases', () => {
+  it('pure black fg → grayscale result', () => {
+    const fg = parseColor('#000000');
+    const bg = parseColor('#ffffff');
+    const fixed = suggestFix(fg, bg, 4.5);
+    expect(fixed).toMatch(/^#[0-9a-f]{6}$/);
+    const fixedRgb = parseColor(fixed);
+    // Grayscale: all channels should be equal or very close
+    expect(Math.abs(fixedRgb.r - fixedRgb.g)).toBeLessThanOrEqual(1);
+    expect(Math.abs(fixedRgb.g - fixedRgb.b)).toBeLessThanOrEqual(1);
+  });
+
+  it('black on dark bg → lighter result', () => {
+    const fg = parseColor('#000000');
+    const bg = parseColor('#1a1a1a');
+    const fixed = suggestFix(fg, bg, 4.5);
+    const fixedRgb = parseColor(fixed);
+    // Must be lighter than the dark bg to achieve contrast
+    const avgFixed = (fixedRgb.r + fixedRgb.g + fixedRgb.b) / 3;
+    expect(avgFixed).toBeGreaterThan(26); // > #1a1a1a average
+  });
+
+  it('impossible 21:1 target → returns valid hex (best effort)', () => {
+    const fg = parseColor('#888888');
+    const bg = parseColor('#888888');
+    const fixed = suggestFix(fg, bg, 21);
+    expect(fixed).toMatch(/^#[0-9a-f]{6}$/);
+  });
+});
+
+describe('parseColor HSL edge cases', () => {
+  it('h=360 is equivalent to h=0', () => {
+    const h360 = parseColor('hsl(360, 100%, 50%)');
+    const h0 = parseColor('hsl(0, 100%, 50%)');
+    expect(h360.r).toBe(h0.r);
+    expect(h360.g).toBe(h0.g);
+    expect(h360.b).toBe(h0.b);
+  });
+
+  it('s=0% → grayscale', () => {
+    const gray = parseColor('hsl(180, 0%, 50%)');
+    expect(gray.r).toBe(gray.g);
+    expect(gray.g).toBe(gray.b);
+    expect(gray.r).toBe(128);
+  });
+
+  it('l=0% → black', () => {
+    const black = parseColor('hsl(120, 100%, 0%)');
+    expect(black).toEqual({ r: 0, g: 0, b: 0 });
+  });
+
+  it('l=100% → white', () => {
+    const white = parseColor('hsl(240, 100%, 100%)');
+    expect(white).toEqual({ r: 255, g: 255, b: 255 });
+  });
+});
+
+describe('deriveSemanticText (via seed-derivation)', () => {
+  const semanticColors = {
+    danger: '#ef4444',
+    success: '#22c55e',
+    warning: '#f59e0b',
+    info: '#3b82f6',
+  };
+
+  for (const [name, color] of Object.entries(semanticColors)) {
+    it(`light mode: ${name} text meets 6:1 on white (headroom for composited bg)`, () => {
+      const text = deriveSemanticText(color, false);
+      const fg = parseColor(text);
+      const bg = parseColor('#ffffff');
+      const ratio = contrastRatio(fg, bg);
+      expect(ratio).toBeGreaterThanOrEqual(6.0);
+    });
+
+    it(`dark mode: ${name} text meets 6:1 on near-black (headroom for composited bg)`, () => {
+      const text = deriveSemanticText(color, true);
+      const fg = parseColor(text);
+      const bg = parseColor('#0a0a0a');
+      const ratio = contrastRatio(fg, bg);
+      expect(ratio).toBeGreaterThanOrEqual(6.0);
+    });
+  }
+
+  it('returns a valid hex color', () => {
+    const text = deriveSemanticText('#ef4444', false);
+    expect(text).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('already-compliant color is returned with minimal change', () => {
+    // Pure black on white is 21:1 — should not darken further
+    const text = deriveSemanticText('#000000', false);
+    expect(text).toBe('#000000');
+  });
+});
+
+describe('contrastRatio edge cases', () => {
+  it('very similar colors → ratio close to 1.0', () => {
+    const fg = parseColor('#fefefe');
+    const bg = parseColor('#ffffff');
+    const ratio = contrastRatio(fg, bg);
+    expect(ratio).toBeGreaterThanOrEqual(1.0);
+    expect(ratio).toBeLessThan(1.05);
+  });
+
+  it('identical colors → exactly 1', () => {
+    const color = parseColor('#abcdef');
+    const ratio = contrastRatio(color, color);
+    expect(ratio).toBe(1);
+  });
+
+  it('near-white on white → slightly above 1', () => {
+    const fg = parseColor('#f0f0f0');
+    const bg = parseColor('#ffffff');
+    const ratio = contrastRatio(fg, bg);
+    expect(ratio).toBeGreaterThan(1);
+    expect(ratio).toBeLessThan(1.2);
+  });
+});