@trishchuk/coolors-mcp 1.0.0 → 1.1.0

package/src/tools/cohesion.tools.ts

@@ -0,0 +1,380 @@
+/**
+ * Visual cohesion tools
+ *
+ * - generate_tonal_scale: build a Tailwind-style tonal scale (50…950) from a
+ *   seed color using HCT so steps are perceptually even.
+ * - generate_state_colors: derive hover/active/focus/disabled/pressed/selected
+ *   variants from a base color with consistent tonal deltas.
+ * - analyze_palette_consistency: score how visually cohesive a palette is by
+ *   looking at chroma spread, tonal step uniformity, and hue harmony.
+ * - generate_semantic_palette: pick semantic colors (primary/secondary/success/
+ *   warning/error/info) that harmonize with a brand color via HCT hue rotations.
+ */
+
+import { z } from "zod";
+
+import { argbToRgb, rgbToArgb } from "../color/conversions.js";
+import { Hct } from "../color/hct/hct-class.js";
+import {
+  colorDistance,
+  parseColor,
+  rgbToHex,
+  rgbToHsl,
+} from "../color/index.js";
+
+const TONAL_STOPS = [
+  50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950,
+] as const;
+
+function hctFromColor(input: string): Hct | null {
+  const rgb = parseColor(input);
+  if (!rgb) return null;
+  return Hct.fromInt(rgbToArgb(rgb));
+}
+
+function hctToHex(h: number, c: number, t: number): string {
+  const hct = Hct.from(h, c, t);
+  return rgbToHex(argbToRgb(hct.toInt()));
+}
+
+// --- generate_tonal_scale -----------------------------------------------------
+
+export const generateTonalScaleTool = {
+  description:
+    "Generate a complete tonal scale (Tailwind-style 50/100/.../900/950) from a seed color. Uses Google's HCT color space so each step is perceptually even — ideal for building shadable design-system colors.",
+  execute: async (args: {
+    chromaBoost?: number;
+    name?: string;
+    seed: string;
+    stops?: number[];
+  }) => {
+    const hct = hctFromColor(args.seed);
+    if (!hct) return `Invalid color format: ${args.seed}`;
+
+    const stops = args.stops?.length ? args.stops : Array.from(TONAL_STOPS);
+    const chromaBoost = args.chromaBoost ?? 1;
+    const name = (args.name ?? "color").toLowerCase();
+
+    // Map Tailwind-style stops to HCT tones (50 -> tone 95, 950 -> tone 5).
+    const tones = stops.map((s) => Math.max(0, Math.min(100, 100 - s / 10)));
+
+    let output = `# Tonal scale for ${args.seed}\n`;
+    output += `Seed HCT: H=${hct.hue.toFixed(1)}° C=${hct.chroma.toFixed(1)} T=${hct.tone.toFixed(1)}\n\n`;
+    output += `| stop | tone | hex |\n|---|---|---|\n`;
+
+    const rows: { hex: string; stop: number; tone: number }[] = [];
+    for (let i = 0; i < stops.length; i++) {
+      const tone = tones[i];
+      // Reduce chroma near the extremes (very light / very dark) for legibility.
+      const edge = Math.abs(50 - tone) / 50; // 0 at mid, 1 at extremes
+      const chroma = hct.chroma * chromaBoost * (1 - 0.35 * edge);
+      const hex = hctToHex(hct.hue, chroma, tone);
+      rows.push({ hex, stop: stops[i], tone });
+      output += `| ${stops[i]} | ${tone.toFixed(0)} | ${hex} |\n`;
+    }
+
+    output += `\n## CSS\n\`\`\`css\n:root {\n`;
+    for (const r of rows) output += `  --${name}-${r.stop}: ${r.hex};\n`;
+    output += `}\n\`\`\`\n`;
+
+    return output;
+  },
+  name: "generate_tonal_scale",
+  parameters: z.object({
+    chromaBoost: z
+      .number()
+      .min(0)
+      .max(2)
+      .optional()
+      .default(1)
+      .describe("Multiplier on seed chroma (1 = preserve, <1 = muted)"),
+    name: z
+      .string()
+      .optional()
+      .describe("CSS variable base name (default: 'color')"),
+    seed: z.string().describe("Seed color (hex, rgb, hsl)"),
+    stops: z
+      .array(z.number().min(0).max(1000))
+      .optional()
+      .describe(
+        "Custom stops. Default: [50,100,200,300,400,500,600,700,800,900,950].",
+      ),
+  }),
+};
+
+// --- generate_state_colors ---------------------------------------------------
+
+export const generateStateColorsTool = {
+  description:
+    "Generate consistent interaction-state colors (hover / active / pressed / focus / disabled / selected) from a base color. Steps are computed in HCT space so they keep equal perceptual weight regardless of base hue.",
+  execute: async (args: { base: string; isDark?: boolean }) => {
+    const hct = hctFromColor(args.base);
+    if (!hct) return `Invalid color format: ${args.base}`;
+
+    const dark = args.isDark ?? false;
+    // In dark mode, "hover" should lighten; in light mode, it should darken.
+    const dir = dark ? +1 : -1;
+
+    const states: { hex: string; note: string; state: string; tone: number }[] =
+      [
+        { hex: "", note: "resting", state: "base", tone: hct.tone },
+        {
+          hex: "",
+          note: "+/- 8 tone",
+          state: "hover",
+          tone: hct.tone + dir * 8,
+        },
+        {
+          hex: "",
+          note: "+/- 16 tone",
+          state: "active",
+          tone: hct.tone + dir * 16,
+        },
+        {
+          hex: "",
+          note: "same as active, alias",
+          state: "pressed",
+          tone: hct.tone + dir * 16,
+        },
+        {
+          hex: "",
+          note: "+/- 4 tone, used as outline",
+          state: "focus",
+          tone: hct.tone + dir * 4,
+        },
+        {
+          hex: "",
+          note: "low chroma, mid tone",
+          state: "disabled",
+          tone: dark ? 30 : 70,
+        },
+        {
+          hex: "",
+          note: "alpha-blend friendly base",
+          state: "selected",
+          tone: dark ? 25 : 90,
+        },
+      ];
+
+    for (const s of states) {
+      const chroma =
+        s.state === "disabled" ? Math.min(hct.chroma, 6) : hct.chroma;
+      const tone = Math.max(0, Math.min(100, s.tone));
+      s.hex = hctToHex(hct.hue, chroma, tone);
+      s.tone = tone;
+    }
+
+    let out = `# Interaction states for ${args.base} (${dark ? "dark" : "light"} mode)\n\n`;
+    out += `| state | tone | hex | notes |\n|---|---|---|---|\n`;
+    for (const s of states)
+      out += `| ${s.state} | ${s.tone.toFixed(0)} | ${s.hex} | ${s.note} |\n`;
+
+    return out;
+  },
+  name: "generate_state_colors",
+  parameters: z.object({
+    base: z.string().describe("Base/resting color (hex, rgb, hsl)"),
+    isDark: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "Whether the base color sits on a dark background. Hover lightens on dark, darkens on light.",
+      ),
+  }),
+};
+
+// --- analyze_palette_consistency --------------------------------------------
+
+export const analyzePaletteConsistencyTool = {
+  description:
+    "Score how visually cohesive a palette is. Reports tonal step uniformity, chroma spread, hue distribution, and a single 0-100 cohesion score, plus targeted suggestions for tightening it up.",
+  execute: async (args: { colors: string[] }) => {
+    if (args.colors.length < 2) {
+      return "Need at least 2 colors to analyze cohesion.";
+    }
+
+    const parsed = args.colors.map((c) => ({ input: c, rgb: parseColor(c) }));
+    if (parsed.some((p) => !p.rgb)) {
+      const bad = parsed.filter((p) => !p.rgb).map((p) => p.input);
+      return `Invalid color format: ${bad.join(", ")}`;
+    }
+
+    const hcts = parsed.map((p) => Hct.fromInt(rgbToArgb(p.rgb!)));
+
+    const tones = hcts.map((h) => h.tone).sort((a, b) => a - b);
+    const chromas = hcts.map((h) => h.chroma);
+    const hues = hcts.map((h) => h.hue);
+
+    // Tonal step uniformity — std-dev of gaps between sorted tones.
+    const gaps: number[] = [];
+    for (let i = 1; i < tones.length; i++) gaps.push(tones[i] - tones[i - 1]);
+    const avgGap = gaps.reduce((a, b) => a + b, 0) / (gaps.length || 1);
+    const gapStd = Math.sqrt(
+      gaps.reduce((a, b) => a + (b - avgGap) ** 2, 0) / (gaps.length || 1),
+    );
+    // Lower std relative to avg = more uniform. Score 100 when std ≈ 0.
+    const toneUniformity = Math.max(
+      0,
+      100 - (gapStd / Math.max(1, avgGap)) * 50,
+    );
+
+    // Chroma cohesion — std-dev of chroma, lower is more cohesive.
+    const avgChroma = chromas.reduce((a, b) => a + b, 0) / chromas.length;
+    const chromaStd = Math.sqrt(
+      chromas.reduce((a, b) => a + (b - avgChroma) ** 2, 0) / chromas.length,
+    );
+    const chromaCohesion = Math.max(0, 100 - chromaStd * 2);
+
+    // Hue harmony — cluster hues; reward palettes whose hues sit within a few
+    // recognized harmonic offsets (0, 30, 60, 90, 120, 150, 180 ±15°).
+    const targets = [0, 30, 60, 90, 120, 150, 180];
+    let harmonyHits = 0;
+    for (let i = 0; i < hues.length; i++) {
+      for (let j = i + 1; j < hues.length; j++) {
+        let d = Math.abs(hues[i] - hues[j]);
+        if (d > 180) d = 360 - d;
+        if (targets.some((t) => Math.abs(d - t) <= 15)) harmonyHits++;
+      }
+    }
+    const totalPairs = (hues.length * (hues.length - 1)) / 2;
+    const hueHarmony = totalPairs ? (harmonyHits / totalPairs) * 100 : 100;
+
+    const cohesion =
+      0.4 * toneUniformity + 0.3 * chromaCohesion + 0.3 * hueHarmony;
+
+    // Find the most "off" color — the one that pushes std the most.
+    let outlier = -1;
+    let outlierGain = 0;
+    for (let i = 0; i < hcts.length; i++) {
+      const reduced = hcts.filter((_, k) => k !== i).map((h) => h.chroma);
+      const m = reduced.reduce((a, b) => a + b, 0) / reduced.length;
+      const std = Math.sqrt(
+        reduced.reduce((a, b) => a + (b - m) ** 2, 0) / reduced.length,
+      );
+      const gain = chromaStd - std;
+      if (gain > outlierGain) {
+        outlierGain = gain;
+        outlier = i;
+      }
+    }
+
+    let out = `# Palette cohesion analysis\n\n`;
+    out += `Colors: ${args.colors.length}\n\n`;
+    out += `| metric | score | detail |\n|---|---|---|\n`;
+    out += `| Tonal step uniformity | ${toneUniformity.toFixed(0)} | gap avg ${avgGap.toFixed(1)} ± ${gapStd.toFixed(1)} |\n`;
+    out += `| Chroma cohesion | ${chromaCohesion.toFixed(0)} | chroma avg ${avgChroma.toFixed(1)} ± ${chromaStd.toFixed(1)} |\n`;
+    out += `| Hue harmony | ${hueHarmony.toFixed(0)} | ${harmonyHits}/${totalPairs} pairs at harmonic angles |\n`;
+    out += `| **Overall cohesion** | **${cohesion.toFixed(0)}** | weighted 0.4 / 0.3 / 0.3 |\n\n`;
+
+    const suggestions: string[] = [];
+    if (toneUniformity < 60)
+      suggestions.push(
+        `Tone gaps are uneven (std ${gapStd.toFixed(1)}). Snap colors to a fixed scale (e.g. tones 10/30/50/70/90).`,
+      );
+    if (chromaCohesion < 60)
+      suggestions.push(
+        `Chroma varies widely (std ${chromaStd.toFixed(1)}). Mute saturated colors or boost flat ones toward chroma ${avgChroma.toFixed(0)}.`,
+      );
+    if (hueHarmony < 50)
+      suggestions.push(
+        `Hues don't sit at harmonic angles (30/60/90/120/180°). Try rotating outliers onto the nearest harmonic.`,
+      );
+    if (outlier >= 0)
+      suggestions.push(
+        `Likely outlier: ${args.colors[outlier]} (chroma ${hcts[outlier].chroma.toFixed(0)} vs avg ${avgChroma.toFixed(0)}).`,
+      );
+
+    if (suggestions.length === 0)
+      out += `✓ Palette is visually cohesive across all three axes.\n`;
+    else {
+      out += `## Suggestions\n`;
+      for (const s of suggestions) out += `- ${s}\n`;
+    }
+
+    return out;
+  },
+  name: "analyze_palette_consistency",
+  parameters: z.object({
+    colors: z.array(z.string()).min(2).describe("Palette colors to analyze"),
+  }),
+};
+
+// --- generate_semantic_palette ----------------------------------------------
+
+const SEMANTIC_OFFSETS: Record<string, number> = {
+  // Hue offsets from brand color (in HCT degrees).
+  // Secondary/tertiary use harmonic rotations; semantic statuses anchor to
+  // conventional hue ranges (red/yellow/blue) but adjust chroma/tone to feel
+  // like they belong to the same family.
+  primary: 0,
+  secondary: -30,
+  tertiary: 60,
+};
+
+const SEMANTIC_ANCHORS: Record<string, { chromaMin: number; hue: number }> = {
+  // Anchored hues for status colors. Chroma is clamped down to whatever the
+  // brand can muster so the status palette doesn't out-shout the brand.
+  error: { chromaMin: 40, hue: 25 }, // red
+  info: { chromaMin: 30, hue: 240 }, // blue
+  success: { chromaMin: 30, hue: 142 }, // green
+  warning: { chromaMin: 50, hue: 80 }, // amber
+};
+
+export const generateSemanticPaletteTool = {
+  description:
+    "From a single brand color, generate a complete visually-cohesive semantic palette: primary, secondary, tertiary, plus success/warning/error/info status colors. Tone and chroma are normalized in HCT space so every color feels like part of the same family.",
+  execute: async (args: { brand: string; isDark?: boolean }) => {
+    const hct = hctFromColor(args.brand);
+    if (!hct) return `Invalid color format: ${args.brand}`;
+
+    const dark = args.isDark ?? false;
+    const targetTone = dark ? 80 : 40;
+    const familyChroma = Math.max(24, Math.min(hct.chroma, 80));
+
+    const entries: { hex: string; hue: number; name: string; tone: number }[] =
+      [];
+
+    for (const [name, offset] of Object.entries(SEMANTIC_OFFSETS)) {
+      const hue = (hct.hue + offset + 360) % 360;
+      const hex = hctToHex(hue, familyChroma, targetTone);
+      entries.push({ hex, hue, name, tone: targetTone });
+    }
+
+    for (const [name, anchor] of Object.entries(SEMANTIC_ANCHORS)) {
+      const chroma = Math.max(anchor.chromaMin, Math.min(familyChroma, 90));
+      const hex = hctToHex(anchor.hue, chroma, targetTone);
+      entries.push({ hex, hue: anchor.hue, name, tone: targetTone });
+    }
+
+    // Quick sanity check: how close are the status hues to the brand? Report
+    // the perceptual distance so the user knows what they're getting.
+    const brandRgb = parseColor(args.brand)!;
+
+    let out = `# Semantic palette derived from ${args.brand}\n`;
+    out += `Mode: ${dark ? "dark" : "light"} (target tone ${targetTone})\n`;
+    out += `Family chroma: ${familyChroma.toFixed(0)} (brand was ${hct.chroma.toFixed(0)})\n\n`;
+    out += `| role | hue | hex | ΔE2000 from brand | hsl |\n|---|---|---|---|---|\n`;
+    for (const e of entries) {
+      const rgb = parseColor(e.hex)!;
+      const delta = colorDistance(brandRgb, rgb, { metric: "deltaE2000" });
+      const hsl = rgbToHsl(rgb);
+      out += `| ${e.name} | ${e.hue.toFixed(0)}° | ${e.hex} | ${delta.toFixed(1)} | hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%) |\n`;
+    }
+
+    out += `\n## CSS\n\`\`\`css\n:root {\n`;
+    for (const e of entries) out += `  --color-${e.name}: ${e.hex};\n`;
+    out += `}\n\`\`\`\n`;
+
+    return out;
+  },
+  name: "generate_semantic_palette",
+  parameters: z.object({
+    brand: z.string().describe("Brand / seed color (hex, rgb, hsl)"),
+    isDark: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Generate the palette for a dark theme background"),
+  }),
+};

package/src/tools/color-blindness.tool.ts

@@ -0,0 +1,168 @@
+/**
+ * Color Blindness Simulation Tool
+ * Simulate how colors appear to viewers with color vision deficiency (CVD)
+ * and audit palette accessibility for common deficiency types.
+ */
+
+import { z } from "zod";
+
+import {
+  CVD_PREVALENCE,
+  CvdType,
+  simulateCvd,
+} from "../color/color-blindness.js";
+import {
+  colorDistance,
+  getContrastRatio,
+  parseColor,
+  rgbToHex,
+} from "../color/index.js";
+
+const CVD_TYPES = [
+  "protanopia",
+  "deuteranopia",
+  "tritanopia",
+  "protanomaly",
+  "deuteranomaly",
+  "tritanomaly",
+  "achromatopsia",
+] as const satisfies readonly CvdType[];
+
+export const simulateColorBlindnessTool = {
+  description:
+    "Simulate how one or more colors appear to viewers with color vision deficiency (protanopia, deuteranopia, tritanopia, their milder anomaly forms, or achromatopsia).",
+  execute: async (args: { colors: string[]; types?: CvdType[] }) => {
+    const types = args.types && args.types.length > 0 ? args.types : CVD_TYPES;
+
+    const parsed = args.colors.map((c) => ({ input: c, rgb: parseColor(c) }));
+    const invalid = parsed.filter((p) => !p.rgb);
+    if (invalid.length) {
+      return `Invalid color format: ${invalid.map((p) => p.input).join(", ")}`;
+    }
+
+    let output = `# Color Blindness Simulation\n\n`;
+    output += `| Original | ${types.join(" | ")} |\n`;
+    output += `|${"---|".repeat(types.length + 1)}\n`;
+
+    for (const { input, rgb } of parsed) {
+      const simulated = types.map((t) => rgbToHex(simulateCvd(rgb!, t)));
+      output += `| ${rgbToHex(rgb!)} (${input}) | ${simulated.join(" | ")} |\n`;
+    }
+
+    output += `\n## Population prevalence\n`;
+    for (const t of types) {
+      output += `- **${t}**: ~${CVD_PREVALENCE[t]}% of population\n`;
+    }
+
+    return output;
+  },
+  name: "simulate_color_blindness",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(1)
+      .describe("Colors to simulate (hex, rgb, hsl)"),
+    types: z
+      .array(z.enum(CVD_TYPES))
+      .optional()
+      .describe(
+        "Deficiency types to simulate. Defaults to all 7 (dichromacy + anomaly + achromatopsia).",
+      ),
+  }),
+};
+
+export const checkPaletteAccessibilityTool = {
+  description:
+    "Audit a color palette for color-blind accessibility. For each pair of colors, reports the perceptual distance (Delta E 2000) under each CVD type and flags pairs that become indistinguishable.",
+  execute: async (args: {
+    colors: string[];
+    indistinguishableThreshold?: number;
+    types?: CvdType[];
+  }) => {
+    const types = args.types && args.types.length > 0 ? args.types : CVD_TYPES;
+    const threshold = args.indistinguishableThreshold ?? 10;
+
+    const parsed = args.colors.map((c) => ({ input: c, rgb: parseColor(c) }));
+    const invalid = parsed.filter((p) => !p.rgb);
+    if (invalid.length) {
+      return `Invalid color format: ${invalid.map((p) => p.input).join(", ")}`;
+    }
+
+    const colors = parsed.map((p) => p.rgb!);
+    const labels = parsed.map((p) => rgbToHex(p.rgb!));
+
+    let output = `# Palette Accessibility Audit\n\n`;
+    output += `Indistinguishable threshold: ΔE2000 < ${threshold}\n\n`;
+
+    const problems: string[] = [];
+
+    for (const type of types) {
+      const simulated = colors.map((c) => simulateCvd(c, type));
+      const collisions: string[] = [];
+
+      for (let i = 0; i < simulated.length; i++) {
+        for (let j = i + 1; j < simulated.length; j++) {
+          const d = colorDistance(simulated[i], simulated[j], {
+            metric: "deltaE2000",
+          });
+          if (d < threshold) {
+            collisions.push(
+              `  - ${labels[i]} ↔ ${labels[j]}: ΔE=${d.toFixed(1)} (sim: ${rgbToHex(
+                simulated[i],
+              )} vs ${rgbToHex(simulated[j])})`,
+            );
+          }
+        }
+      }
+
+      output += `## ${type} (~${CVD_PREVALENCE[type]}% of population)\n`;
+      if (collisions.length === 0) {
+        output += `✓ All ${colors.length} colors remain distinguishable\n\n`;
+      } else {
+        output += `⚠ ${collisions.length} indistinguishable pair${collisions.length === 1 ? "" : "s"}:\n`;
+        output += collisions.join("\n") + "\n\n";
+        problems.push(type);
+      }
+    }
+
+    output += `## Summary\n`;
+    if (problems.length === 0) {
+      output += `✓ Palette is accessible across all tested CVD types.\n`;
+    } else {
+      output += `⚠ Issues detected in: ${problems.join(", ")}.\n`;
+      output += `Consider increasing tonal contrast (vary lightness) or chroma; CVD-friendly palettes rely on lightness differences rather than hue alone.\n`;
+
+      // Quick contrast hint: compute mean luminance contrast within the palette
+      let worst = Infinity;
+      for (let i = 0; i < colors.length; i++) {
+        for (let j = i + 1; j < colors.length; j++) {
+          const r = getContrastRatio(colors[i], colors[j]);
+          if (r < worst) worst = r;
+        }
+      }
+      output += `Lowest WCAG luminance ratio in palette: ${worst.toFixed(2)}:1 (target ≥ 3:1 for adjacent UI swatches).\n`;
+    }
+
+    return output;
+  },
+  name: "check_palette_accessibility",
+  parameters: z.object({
+    colors: z
+      .array(z.string())
+      .min(2)
+      .describe("Palette colors to audit (at least 2)"),
+    indistinguishableThreshold: z
+      .number()
+      .min(1)
+      .max(30)
+      .optional()
+      .default(10)
+      .describe(
+        "ΔE2000 below which two simulated colors are considered indistinguishable (default 10)",
+      ),
+    types: z
+      .array(z.enum(CVD_TYPES))
+      .optional()
+      .describe("CVD types to audit. Defaults to all 7."),
+  }),
+};

package/src/tools/color-conversion.tool.ts

@@ -41,7 +41,7 @@ export const colorConversionTool = {
         return `lab(${lab.l.toFixed(2)}, ${lab.a.toFixed(2)}, ${lab.b.toFixed(2)})`;
       }
       case "rgb":
-        return `rgb(${Math.round(rgb.r * 255)}, ${Math.round(rgb.g * 255)}, ${Math.round(rgb.b * 255)})`;
+        return `rgb(${Math.round(rgb.r)}, ${Math.round(rgb.g)}, ${Math.round(rgb.b)})`;
       default:
         return `Invalid format: ${args.to}`;
     }

package/src/tools/contrast-checker.tool.ts

@@ -1,15 +1,22 @@
 /**
  * Contrast Checker Tool
- * Check WCAG contrast ratio between two colors
+ * Check contrast between two colors using WCAG 2.x luminance ratio,
+ * APCA (WCAG 3 draft), or both.
  */
 
 import { z } from "zod";
 
+import { apcaContrast, apcaLevel } from "../color/apca.js";
 import { getContrastRatio, parseColor } from "../color/index.js";
 
 export const contrastCheckerTool = {
-  description: "Check WCAG contrast ratio between two colors",
-  execute: async (args: { background: string; foreground: string }) => {
+  description:
+    "Check contrast between two colors. Supports WCAG 2.x luminance ratio (default), APCA Lc (WCAG 3 draft), or both algorithms side-by-side.",
+  execute: async (args: {
+    algorithm?: "apca" | "both" | "wcag";
+    background: string;
+    foreground: string;
+  }) => {
     const fg = parseColor(args.foreground);
     const bg = parseColor(args.background);
 
@@ -17,20 +24,52 @@ export const contrastCheckerTool = {
       return `Invalid color format: ${!fg ? args.foreground : args.background}`;
     }
 
-    const ratio = getContrastRatio(fg, bg);
-    const aa = ratio >= 4.5;
-    const aaLarge = ratio >= 3;
-    const aaa = ratio >= 7;
-    const aaaLarge = ratio >= 4.5;
-
-    return `Contrast Ratio: ${ratio.toFixed(2)}:1
-WCAG AA: ${aa ? "✓ Pass" : "✗ Fail"} (normal text)
-WCAG AA: ${aaLarge ? "✓ Pass" : "✗ Fail"} (large text)
-WCAG AAA: ${aaa ? "✓ Pass" : "✗ Fail"} (normal text)
-WCAG AAA: ${aaaLarge ? "✓ Pass" : "✗ Fail"} (large text)`;
+    const algorithm = args.algorithm ?? "wcag";
+
+    const wcagBlock = () => {
+      const ratio = getContrastRatio(fg, bg);
+      const aaLarge = ratio >= 3;
+      const aa = ratio >= 4.5;
+      const aaaLarge = ratio >= 4.5;
+      const aaa = ratio >= 7;
+      return `## WCAG 2.x luminance ratio
+Contrast Ratio: ${ratio.toFixed(2)}:1
+- AA (normal text):  ${aa ? "✓ Pass" : "✗ Fail"} (need 4.5:1)
+- AA (large text):   ${aaLarge ? "✓ Pass" : "✗ Fail"} (need 3:1)
+- AAA (normal text): ${aaa ? "✓ Pass" : "✗ Fail"} (need 7:1)
+- AAA (large text):  ${aaaLarge ? "✓ Pass" : "✗ Fail"} (need 4.5:1)`;
+    };
+
+    const apcaBlock = () => {
+      const lc = apcaContrast(fg, bg);
+      const level = apcaLevel(lc);
+      const polarity =
+        lc > 0
+          ? "dark text on light bg"
+          : lc < 0
+            ? "light text on dark bg"
+            : "no contrast";
+      return `## APCA (WCAG 3 draft)
+Lc: ${lc.toFixed(1)} (${polarity})
+- Body text (|Lc| ≥ 75):    ${level.body ? "✓ Pass" : "✗ Fail"}
+- Content text (|Lc| ≥ 60): ${level.content ? "✓ Pass" : "✗ Fail"}
+- Large text (|Lc| ≥ 45):   ${level.large ? "✓ Pass" : "✗ Fail"}
+- Spot / non-content (|Lc| ≥ 30): ${level.spot ? "✓ Pass" : "✗ Fail"}`;
+    };
+
+    if (algorithm === "wcag") return wcagBlock();
+    if (algorithm === "apca") return apcaBlock();
+    return `${wcagBlock()}\n\n${apcaBlock()}`;
   },
   name: "check_contrast",
   parameters: z.object({
+    algorithm: z
+      .enum(["wcag", "apca", "both"])
+      .optional()
+      .default("wcag")
+      .describe(
+        "Contrast algorithm: 'wcag' (WCAG 2.x ratio), 'apca' (Lc, WCAG 3 draft), or 'both'",
+      ),
     background: z.string().describe("Background color"),
     foreground: z.string().describe("Foreground/text color"),
   }),