@fragments-sdk/cli 0.2.2

package/src/viewer/components/AccessibilityPanel.tsx

@@ -0,0 +1,1404 @@
+// @ts-nocheck
+/**
+ * Accessibility Panel - Enhanced a11y testing
+ *
+ * Runs axe-core accessibility checks and displays:
+ * - Violations with severity hierarchy and actionable guidance
+ * - Static fix suggestions with before/after code
+ * - WCAG references and "Why it matters" explanations
+ * - Real-time re-scanning on file changes
+ */
+
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import type { Result, NodeResult, ImpactValue, RunOptions } from "axe-core";
+import clsx from "clsx";
+import { BRAND } from "../../core/index.js";
+import {
+  updateComponentA11yResult,
+  getComponentA11yResult,
+} from "../hooks/useA11yCache.js";
+import { useA11yService } from "../hooks/useA11yService.js";
+import {
+  getStaticFix,
+  generateElementFix,
+  getImpactColorClass,
+  extractWcagTags,
+} from "../utils/a11y-fixes.js";
+import type { SerializedViolation, SerializedNode } from "../types/a11y.js";
+
+// Storage key for AI config
+const AI_CONFIG_STORAGE_KEY = `${BRAND.storagePrefix}ai-config`;
+import {
+  CheckIcon,
+  XIcon,
+  LoadingIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+  WandIcon,
+  AccessibilityIcon,
+} from "./Icons.js";
+
+// Define our own interface for axe results to avoid import issues
+interface AxeResults {
+  violations: Result[];
+  passes: Result[];
+  incomplete: Result[];
+  inapplicable: Result[];
+  timestamp: string;
+  testEngine: { name: string; version: string };
+  testRunner: { name: string };
+  testEnvironment: { userAgent: string; windowWidth: number; windowHeight: number };
+  url: string;
+  toolOptions: RunOptions;
+}
+
+// AI provider configuration
+interface AIProviderConfig {
+  provider: "anthropic" | "openai";
+  apiKey: string;
+}
+
+interface AccessibilityPanelProps {
+  /** Target element to scan (selector or ref data attribute) */
+  targetSelector?: string;
+  /** Callback when scan completes */
+  onScanComplete?: (results: AxeResults) => void;
+  /** Whether to auto-run scan on mount/changes */
+  autoScan?: boolean;
+  /** Preview key for re-scanning when component changes */
+  previewKey?: number;
+  /** Cache key for storing scan results (e.g., componentName-variantName) */
+  cacheKey?: string;
+  /** Component name for shared cache (updates global a11y cache) */
+  componentName?: string;
+  /** Variant name for shared cache */
+  variantName?: string;
+}
+
+type TabType = "violations" | "passes" | "incomplete";
+
+const IMPACT_ORDER: Record<string, number> = {
+  critical: 0,
+  serious: 1,
+  moderate: 2,
+  minor: 3,
+};
+
+// Cache the axe-core module to avoid repeated dynamic imports
+let axeModule: typeof import("axe-core") | null = null;
+
+// Cache scan results to avoid re-scanning the same component
+const scanResultsCache = new Map<string, { timestamp: number; results: AxeResults }>();
+const SCAN_CACHE_TTL = 30000; // 30 seconds cache for scan results
+
+export function AccessibilityPanel({
+  targetSelector = '[data-preview-container="true"]',
+  onScanComplete,
+  autoScan = true,
+  previewKey = 0,
+  cacheKey,
+  componentName,
+  variantName,
+}: AccessibilityPanelProps) {
+  const [results, setResults] = useState<AxeResults | null>(() => {
+    // Check cache on initial render
+    if (cacheKey) {
+      const cached = scanResultsCache.get(cacheKey);
+      if (cached && (Date.now() - cached.timestamp) < SCAN_CACHE_TTL) {
+        return cached.results;
+      }
+    }
+    return null;
+  });
+  const [isScanning, setIsScanning] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState<TabType>("violations");
+  const [expandedRules, setExpandedRules] = useState<Set<string>>(new Set());
+  const [highlightedElement, setHighlightedElement] = useState<string | null>(null);
+  const [aiConfig, setAIConfig] = useState<AIProviderConfig | null>(null);
+  const [showAISetup, setShowAISetup] = useState(false);
+  const [generatingFix, setGeneratingFix] = useState<string | null>(null);
+  const [aiFixes, setAIFixes] = useState<Record<string, string>>({});
+  const [copiedFix, setCopiedFix] = useState<string | null>(null);
+
+  // Ref to track if a scan is in progress (prevents concurrent axe.run calls)
+  const scanInProgressRef = useRef(false);
+
+  // Use the a11y service for HMR integration
+  const { isScanning: serviceScanning, scanStatus } = useA11yService({
+    componentName,
+    targetSelector,
+    variant: variantName,
+    autoScan: false, // We handle scanning manually for more control
+  });
+
+  // Load saved AI config from localStorage
+  useEffect(() => {
+    const saved = localStorage.getItem(AI_CONFIG_STORAGE_KEY);
+    if (saved) {
+      try {
+        setAIConfig(JSON.parse(saved));
+      } catch (e) {
+        // Ignore invalid config
+      }
+    }
+  }, []);
+
+  // Cleanup on unmount - reset scan in progress flag
+  useEffect(() => {
+    return () => {
+      scanInProgressRef.current = false;
+    };
+  }, []);
+
+  // Convert axe-core Result to SerializedViolation
+  const serializeViolation = useCallback((result: Result): SerializedViolation => ({
+    id: result.id,
+    impact: result.impact || null,
+    description: result.description,
+    help: result.help,
+    helpUrl: result.helpUrl,
+    tags: result.tags,
+    nodes: result.nodes.map(node => ({
+      html: node.html,
+      target: node.target as string[],
+      failureSummary: node.failureSummary,
+      any: node.any?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      all: node.all?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      none: node.none?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+    })),
+  }), []);
+
+  // Run accessibility scan
+  const runScan = useCallback(async () => {
+    // Prevent concurrent scans - axe-core throws if run() is called while already running
+    if (scanInProgressRef.current) {
+      return;
+    }
+
+    scanInProgressRef.current = true;
+    setIsScanning(true);
+    setError(null);
+
+    try {
+      // Use cached module or dynamically import axe-core
+      if (!axeModule) {
+        axeModule = await import("axe-core");
+      }
+      // Handle both ESM default export and CommonJS module
+      const axe = (axeModule as { default?: typeof import("axe-core") }).default || axeModule;
+
+      // First, try to find target in the main document
+      let target: Element | null = document.querySelector(targetSelector);
+      let runInIframe = false;
+      let iframeDocument: Document | null = null;
+
+      // If not found, look inside the preview iframe
+      if (!target) {
+        const iframe = document.querySelector('iframe[title^="Preview:"]') as HTMLIFrameElement;
+        if (iframe?.contentDocument) {
+          iframeDocument = iframe.contentDocument;
+          // Try to find #preview-root inside the iframe
+          target = iframe.contentDocument.querySelector('#preview-root');
+
+          // If still no target, try the body
+          if (!target) {
+            target = iframe.contentDocument.body;
+          }
+
+          if (target) {
+            runInIframe = true;
+          }
+        }
+      }
+
+      if (!target) {
+        setError(`Target element not found: ${targetSelector}`);
+        setIsScanning(false);
+        scanInProgressRef.current = false;
+        return;
+      }
+
+      // If running inside iframe, we need to inject and run axe-core there
+      let axeResults: AxeResults;
+
+      if (runInIframe && iframeDocument) {
+        // Inject axe-core into the iframe if not already present
+        const iframeWindow = (iframeDocument.defaultView || iframeDocument.parentWindow) as Window & { axe?: typeof import("axe-core") };
+
+        if (!iframeWindow.axe) {
+          // Get axe-core source and inject it
+          const axeSource = axe.source;
+          const script = iframeDocument.createElement('script');
+          script.textContent = axeSource;
+          iframeDocument.head.appendChild(script);
+        }
+
+        // Wait a tick for the script to execute
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        // Now run axe in the iframe context
+        const iframeAxe = iframeWindow.axe;
+        if (!iframeAxe) {
+          setError('Failed to inject axe-core into iframe');
+          setIsScanning(false);
+          scanInProgressRef.current = false;
+          return;
+        }
+
+        // Configure and run axe in the iframe
+        iframeAxe.configure({
+          rules: [
+            { id: "color-contrast", enabled: true },
+            { id: "image-alt", enabled: true },
+            { id: "button-name", enabled: true },
+            { id: "link-name", enabled: true },
+            { id: "label", enabled: true },
+            { id: "aria-valid-attr", enabled: true },
+            { id: "aria-valid-attr-value", enabled: true },
+          ],
+        });
+
+        axeResults = await iframeAxe.run(target as HTMLElement, {
+          resultTypes: ["violations", "passes", "incomplete", "inapplicable"],
+        });
+      } else {
+        // Running in main document
+        // Configure axe-core
+        axe.configure({
+          rules: [
+            { id: "color-contrast", enabled: true },
+            { id: "image-alt", enabled: true },
+            { id: "button-name", enabled: true },
+            { id: "link-name", enabled: true },
+            { id: "label", enabled: true },
+            { id: "aria-valid-attr", enabled: true },
+            { id: "aria-valid-attr-value", enabled: true },
+          ],
+        });
+
+        // Run the scan
+        axeResults = await axe.run(target as HTMLElement, {
+          resultTypes: ["violations", "passes", "incomplete", "inapplicable"],
+        });
+      }
+
+      setResults(axeResults);
+      onScanComplete?.(axeResults);
+
+      // Cache the results
+      if (cacheKey) {
+        scanResultsCache.set(cacheKey, { timestamp: Date.now(), results: axeResults });
+      }
+
+      // Update shared a11y cache with full violations
+      if (componentName) {
+        const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+        for (const violation of axeResults.violations) {
+          const impact = violation.impact || 'minor';
+          if (impact in counts) {
+            counts[impact as keyof typeof counts]++;
+          }
+        }
+
+        updateComponentA11yResult(componentName, {
+          violations: axeResults.violations.map(serializeViolation),
+          passes: axeResults.passes.length,
+          incomplete: axeResults.incomplete.length,
+          counts,
+          variant: variantName,
+        });
+      }
+
+      // Switch to violations tab if there are any
+      if (axeResults.violations.length > 0) {
+        setActiveTab("violations");
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Accessibility scan failed");
+    } finally {
+      scanInProgressRef.current = false;
+      setIsScanning(false);
+    }
+  }, [targetSelector, onScanComplete, cacheKey, componentName, variantName, serializeViolation]);
+
+  // Auto-scan on mount and when previewKey changes (skip if we have cached results)
+  useEffect(() => {
+    if (autoScan && !results) {
+      const timer = setTimeout(runScan, 200);
+      return () => clearTimeout(timer);
+    }
+  }, [autoScan, runScan, previewKey]);
+
+  // Re-scan when variant changes (cacheKey includes variant)
+  useEffect(() => {
+    if (!cacheKey || !autoScan) return;
+
+    // Check if we have cached results for this variant
+    const cached = scanResultsCache.get(cacheKey);
+    if (cached && (Date.now() - cached.timestamp) < SCAN_CACHE_TTL) {
+      // Use cached results
+      setResults(cached.results);
+      return;
+    }
+
+    // No cache for this variant - clear results and trigger re-scan
+    setResults(null);
+    setError(null);
+    const timer = setTimeout(runScan, 300);
+    return () => clearTimeout(timer);
+  }, [cacheKey, autoScan, runScan]);
+
+  // Listen for HMR invalidation and re-scan
+  useEffect(() => {
+    if (!componentName) return;
+
+    const handleInvalidation = (event: CustomEvent<{ components: string[] }>) => {
+      if (event.detail.components.includes(componentName)) {
+        // Debounce the re-scan
+        const timer = setTimeout(runScan, 500);
+        return () => clearTimeout(timer);
+      }
+    };
+
+    window.addEventListener('a11y-cache-invalidated', handleInvalidation as EventListener);
+    return () => {
+      window.removeEventListener('a11y-cache-invalidated', handleInvalidation as EventListener);
+    };
+  }, [componentName, runScan]);
+
+  // Highlight element in the preview
+  const highlightElement = useCallback((selector: string | null) => {
+    // Helper to clear highlights in a document
+    const clearHighlights = (doc: Document) => {
+      doc.querySelectorAll("[data-a11y-highlight]").forEach((el) => {
+        el.removeAttribute("data-a11y-highlight");
+        (el as HTMLElement).style.outline = "";
+        (el as HTMLElement).style.outlineOffset = "";
+      });
+    };
+
+    // Helper to apply highlights in a document
+    const applyHighlights = (doc: Document, sel: string) => {
+      try {
+        const elements = doc.querySelectorAll(sel);
+        elements.forEach((el) => {
+          el.setAttribute("data-a11y-highlight", "true");
+          (el as HTMLElement).style.outline = "3px solid #ef4444";
+          (el as HTMLElement).style.outlineOffset = "2px";
+        });
+        return elements.length > 0;
+      } catch {
+        return false;
+      }
+    };
+
+    // Clear highlights in main document
+    clearHighlights(document);
+
+    // Also clear highlights in iframe if it exists
+    const iframe = document.querySelector('iframe[title^="Preview:"]') as HTMLIFrameElement;
+    if (iframe?.contentDocument) {
+      clearHighlights(iframe.contentDocument);
+    }
+
+    if (!selector) {
+      setHighlightedElement(null);
+      return;
+    }
+
+    // Try to highlight in main document first
+    let found = applyHighlights(document, selector);
+
+    // If not found in main document, try inside the iframe
+    if (!found && iframe?.contentDocument) {
+      found = applyHighlights(iframe.contentDocument, selector);
+    }
+
+    if (found) {
+      setHighlightedElement(selector);
+    }
+  }, []);
+
+  // Toggle rule expansion
+  const toggleRule = useCallback((ruleId: string) => {
+    setExpandedRules((prev) => {
+      const next = new Set(prev);
+      if (next.has(ruleId)) {
+        next.delete(ruleId);
+      } else {
+        next.add(ruleId);
+      }
+      return next;
+    });
+  }, []);
+
+  // Copy fix to clipboard
+  const copyFix = useCallback(async (fixCode: string, fixKey: string) => {
+    try {
+      await navigator.clipboard.writeText(fixCode);
+      setCopiedFix(fixKey);
+      setTimeout(() => setCopiedFix(null), 2000);
+    } catch (e) {
+      console.error("Failed to copy:", e);
+    }
+  }, []);
+
+  // Generate AI fix suggestion
+  const generateAIFix = useCallback(
+    async (violation: Result, node: NodeResult) => {
+      if (!aiConfig) {
+        setShowAISetup(true);
+        return;
+      }
+
+      const fixKey = `${violation.id}-${node.html}`;
+      setGeneratingFix(fixKey);
+
+      try {
+        const prompt = buildFixPrompt(violation, node);
+
+        if (aiConfig.provider === "anthropic") {
+          const response = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "x-api-key": aiConfig.apiKey,
+              "anthropic-version": "2023-06-01",
+              "anthropic-dangerous-direct-browser-access": "true",
+            },
+            body: JSON.stringify({
+              model: "claude-sonnet-4-20250514",
+              max_tokens: 1024,
+              messages: [{ role: "user", content: prompt }],
+            }),
+          });
+
+          if (!response.ok) {
+            throw new Error("Failed to generate fix");
+          }
+
+          const data = await response.json();
+          const fix = data.content[0].text;
+          setAIFixes((prev) => ({ ...prev, [fixKey]: fix }));
+        } else if (aiConfig.provider === "openai") {
+          const response = await fetch("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${aiConfig.apiKey}`,
+            },
+            body: JSON.stringify({
+              model: "gpt-4o",
+              messages: [{ role: "user", content: prompt }],
+              max_tokens: 1024,
+            }),
+          });
+
+          if (!response.ok) {
+            throw new Error("Failed to generate fix");
+          }
+
+          const data = await response.json();
+          const fix = data.choices[0].message.content;
+          setAIFixes((prev) => ({ ...prev, [fixKey]: fix }));
+        }
+      } catch (err) {
+        setAIFixes((prev) => ({
+          ...prev,
+          [fixKey]: `Error: ${err instanceof Error ? err.message : "Failed to generate fix"}`,
+        }));
+      } finally {
+        setGeneratingFix(null);
+      }
+    },
+    [aiConfig]
+  );
+
+  // Save AI config
+  const saveAIConfig = useCallback((config: AIProviderConfig) => {
+    setAIConfig(config);
+    localStorage.setItem(AI_CONFIG_STORAGE_KEY, JSON.stringify(config));
+    setShowAISetup(false);
+  }, []);
+
+  // Sort violations by impact
+  const sortedViolations = useMemo(() => {
+    if (!results?.violations) return [];
+    return [...results.violations].sort(
+      (a, b) =>
+        IMPACT_ORDER[a.impact || "minor"] - IMPACT_ORDER[b.impact || "minor"]
+    );
+  }, [results]);
+
+  // Count totals
+  const counts = useMemo(
+    () => ({
+      violations: results?.violations.length || 0,
+      passes: results?.passes.length || 0,
+      incomplete: results?.incomplete.length || 0,
+    }),
+    [results]
+  );
+
+  // Check if currently re-scanning due to HMR
+  const isReScanning = isScanning && results !== null;
+
+  // Render loading state
+  if (isScanning && !results) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8 text-tertiary">
+        <LoadingIcon className="w-6 h-6 animate-spin mb-2" />
+        <span className="text-xs">Running accessibility checks...</span>
+      </div>
+    );
+  }
+
+  // Render error state
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8">
+        <XIcon className="w-6 h-6 text-red-500 mb-2" />
+        <span className="text-xs text-red-600 mb-2">{error}</span>
+        <button
+          onClick={runScan}
+          className="text-xs text-[--color-accent] hover:underline"
+        >
+          Retry Scan
+        </button>
+      </div>
+    );
+  }
+
+  // Render no results state
+  if (!results) {
+    return (
+      <div className="flex flex-col items-center justify-center p-8 text-tertiary">
+        <AccessibilityIcon className="w-8 h-8 mb-2 opacity-50" />
+        <span className="text-xs mb-2">No accessibility scan results</span>
+        <button
+          onClick={runScan}
+          className="text-xs px-3 py-1 rounded bg-[--color-accent] text-white hover:opacity-90"
+        >
+          Run Scan
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full overflow-hidden">
+      {/* Tabs */}
+      <div className="flex items-center gap-1 px-4 py-2 border-b border-[--border] bg-[--bg-secondary] flex-shrink-0">
+        <TabButton
+          active={activeTab === "violations"}
+          onClick={() => setActiveTab("violations")}
+          count={counts.violations}
+          label="Violations"
+          variant="error"
+        />
+        <TabButton
+          active={activeTab === "passes"}
+          onClick={() => setActiveTab("passes")}
+          count={counts.passes}
+          label="Passes"
+          variant="success"
+        />
+        <TabButton
+          active={activeTab === "incomplete"}
+          onClick={() => setActiveTab("incomplete")}
+          count={counts.incomplete}
+          label="Incomplete"
+          variant="warning"
+        />
+
+        <div className="flex-1" />
+
+        {/* Re-scanning indicator */}
+        {isReScanning && (
+          <span className="flex items-center gap-1 px-2 py-1 text-xs text-amber-600 dark:text-amber-400 bg-amber-50 dark:bg-amber-950/30 rounded animate-pulse">
+            <LoadingIcon className="w-3 h-3 animate-spin" />
+            Re-scanning...
+          </span>
+        )}
+
+        {/* Rescan button */}
+        <button
+          onClick={runScan}
+          disabled={isScanning}
+          className="flex items-center gap-1 px-2 py-1 text-xs text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded disabled:opacity-50"
+          title="Re-run accessibility scan"
+        >
+          <LoadingIcon
+            className={clsx("w-3 h-3", isScanning && "animate-spin")}
+          />
+          {isScanning ? "Scanning..." : "Rescan"}
+        </button>
+
+        {/* AI Setup button */}
+        <button
+          onClick={() => setShowAISetup(true)}
+          className={clsx(
+            "flex items-center gap-1 px-2 py-1 text-xs rounded",
+            aiConfig
+              ? "text-purple-600 dark:text-purple-400 bg-purple-50 dark:bg-purple-950/30"
+              : "text-tertiary hover:text-primary hover:bg-[--bg-hover]"
+          )}
+          title={aiConfig ? "AI fixes enabled" : "Configure AI for fix suggestions"}
+        >
+          <WandIcon className="w-3 h-3" />
+          {aiConfig ? "AI Ready" : "Setup AI"}
+        </button>
+      </div>
+
+      {/* Content */}
+      <div className="flex-1 overflow-y-auto p-4">
+        {activeTab === "violations" && (
+          <>
+            {counts.violations === 0 ? (
+              <SuccessMessage message="No accessibility violations found." />
+            ) : (
+              <EnhancedRuleList
+                rules={sortedViolations}
+                expandedRules={expandedRules}
+                onToggleRule={toggleRule}
+                onHighlight={highlightElement}
+                highlightedElement={highlightedElement}
+                onGenerateFix={generateAIFix}
+                generatingFix={generatingFix}
+                aiFixes={aiFixes}
+                aiEnabled={!!aiConfig}
+                onCopyFix={copyFix}
+                copiedFix={copiedFix}
+                type="violation"
+              />
+            )}
+          </>
+        )}
+
+        {activeTab === "passes" && (
+          <>
+            {counts.passes === 0 ? (
+              <EmptyMessage message="No passing checks to display." />
+            ) : (
+              <RuleList
+                rules={results.passes}
+                expandedRules={expandedRules}
+                onToggleRule={toggleRule}
+                onHighlight={highlightElement}
+                highlightedElement={highlightedElement}
+                type="pass"
+              />
+            )}
+          </>
+        )}
+
+        {activeTab === "incomplete" && (
+          <>
+            {counts.incomplete === 0 ? (
+              <EmptyMessage message="No incomplete checks requiring manual review." />
+            ) : (
+              <RuleList
+                rules={results.incomplete}
+                expandedRules={expandedRules}
+                onToggleRule={toggleRule}
+                onHighlight={highlightElement}
+                highlightedElement={highlightedElement}
+                type="incomplete"
+              />
+            )}
+          </>
+        )}
+      </div>
+
+      {/* AI Setup Modal */}
+      {showAISetup && (
+        <AISetupModal
+          onSave={saveAIConfig}
+          onClose={() => setShowAISetup(false)}
+          currentConfig={aiConfig}
+        />
+      )}
+    </div>
+  );
+}
+
+// ----- Sub-components -----
+
+interface TabButtonProps {
+  active: boolean;
+  onClick: () => void;
+  count: number;
+  label: string;
+  variant: "error" | "success" | "warning";
+}
+
+function TabButton({ active, onClick, count, label, variant }: TabButtonProps) {
+  const variantStyles = {
+    error: "text-red-600 dark:text-red-400",
+    success: "text-green-600 dark:text-green-400",
+    warning: "text-amber-600 dark:text-amber-400",
+  };
+
+  return (
+    <button
+      onClick={onClick}
+      className={clsx(
+        "flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded transition-colors",
+        active
+          ? "text-primary bg-[--bg-hover]"
+          : "text-tertiary hover:text-secondary"
+      )}
+    >
+      <span className={variantStyles[variant]}>{count}</span>
+      <span>{label}</span>
+    </button>
+  );
+}
+
+interface EnhancedRuleListProps {
+  rules: Result[];
+  expandedRules: Set<string>;
+  onToggleRule: (id: string) => void;
+  onHighlight: (selector: string | null) => void;
+  highlightedElement: string | null;
+  onGenerateFix?: (violation: Result, node: NodeResult) => void;
+  generatingFix?: string | null;
+  aiFixes?: Record<string, string>;
+  aiEnabled?: boolean;
+  onCopyFix: (fixCode: string, fixKey: string) => void;
+  copiedFix: string | null;
+  type: "violation" | "pass" | "incomplete";
+}
+
+function EnhancedRuleList({
+  rules,
+  expandedRules,
+  onToggleRule,
+  onHighlight,
+  highlightedElement,
+  onGenerateFix,
+  generatingFix,
+  aiFixes,
+  aiEnabled,
+  onCopyFix,
+  copiedFix,
+}: EnhancedRuleListProps) {
+  return (
+    <div className="space-y-3">
+      {rules.map((rule) => {
+        const isExpanded = expandedRules.has(rule.id);
+        const impactColors = getImpactColorClass(rule.impact || null);
+        const staticFix = getStaticFix(rule.id);
+        const wcagTags = extractWcagTags(rule.tags);
+
+        return (
+          <div
+            key={rule.id}
+            className={clsx(
+              "rounded-lg border border-[--border] overflow-hidden border-l-4",
+              impactColors.borderLeft
+            )}
+          >
+            {/* Rule Header */}
+            <button
+              onClick={() => onToggleRule(rule.id)}
+              className="w-full flex items-center gap-2 px-3 py-2.5 text-left hover:bg-[--bg-hover] transition-colors"
+            >
+              {isExpanded ? (
+                <ChevronDownIcon className="w-4 h-4 text-tertiary flex-shrink-0" />
+              ) : (
+                <ChevronRightIcon className="w-4 h-4 text-tertiary flex-shrink-0" />
+              )}
+
+              {/* Impact badge */}
+              {rule.impact && (
+                <span
+                  className={clsx(
+                    "text-[10px] font-semibold px-1.5 py-0.5 rounded uppercase tracking-wide",
+                    impactColors.bg,
+                    impactColors.text
+                  )}
+                >
+                  {rule.impact}
+                </span>
+              )}
+
+              {/* Rule ID */}
+              <span className="text-xs font-mono text-tertiary">
+                {rule.id}
+              </span>
+
+              {/* Rule description */}
+              <span className="text-xs text-primary flex-1 truncate">
+                {rule.description}
+              </span>
+
+              {/* Element count */}
+              <span className="text-[10px] text-tertiary flex-shrink-0 bg-[--bg-hover] px-1.5 py-0.5 rounded">
+                {rule.nodes.length} element{rule.nodes.length !== 1 ? "s" : ""}
+              </span>
+            </button>
+
+            {/* Expanded content */}
+            {isExpanded && (
+              <div className="border-t border-[--border] bg-[--bg-secondary]">
+                {/* Why it matters + WCAG reference */}
+                {staticFix && (
+                  <div className="px-3 py-3 border-b border-[--border-subtle] space-y-2">
+                    <div>
+                      <p className="text-[10px] font-semibold text-tertiary uppercase tracking-wide mb-1">
+                        Why it matters
+                      </p>
+                      <p className="text-xs text-secondary leading-relaxed">
+                        {staticFix.whyItMatters}
+                      </p>
+                    </div>
+
+                    {/* WCAG criterion */}
+                    {staticFix.wcagCriterion && (
+                      <div className="flex items-center gap-2">
+                        <span className={clsx(
+                          "text-[10px] px-1.5 py-0.5 rounded font-medium",
+                          staticFix.wcagCriterion.level === 'A' && "bg-green-100 dark:bg-green-950/50 text-green-700 dark:text-green-300",
+                          staticFix.wcagCriterion.level === 'AA' && "bg-blue-100 dark:bg-blue-950/50 text-blue-700 dark:text-blue-300",
+                          staticFix.wcagCriterion.level === 'AAA' && "bg-purple-100 dark:bg-purple-950/50 text-purple-700 dark:text-purple-300",
+                        )}>
+                          WCAG {staticFix.wcagCriterion.id} Level {staticFix.wcagCriterion.level}
+                        </span>
+                        <span className="text-xs text-secondary">
+                          {staticFix.wcagCriterion.name}
+                        </span>
+                        <a
+                          href={staticFix.wcagCriterion.url}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          className="text-xs text-[--color-accent] hover:underline ml-auto"
+                        >
+                          Learn more
+                        </a>
+                      </div>
+                    )}
+
+                    {/* Before/After examples */}
+                    {(staticFix.badExample || staticFix.goodExample) && (
+                      <div className="grid grid-cols-2 gap-2 mt-2">
+                        {staticFix.badExample && (
+                          <div>
+                            <p className="text-[10px] font-medium text-red-600 dark:text-red-400 mb-1">
+                              Before
+                            </p>
+                            <pre className="text-[10px] font-mono p-2 rounded bg-red-50 dark:bg-red-950/30 text-red-800 dark:text-red-200 overflow-x-auto whitespace-pre-wrap">
+                              {staticFix.badExample}
+                            </pre>
+                          </div>
+                        )}
+                        {staticFix.goodExample && (
+                          <div>
+                            <p className="text-[10px] font-medium text-green-600 dark:text-green-400 mb-1">
+                              After
+                            </p>
+                            <pre className="text-[10px] font-mono p-2 rounded bg-green-50 dark:bg-green-950/30 text-green-800 dark:text-green-200 overflow-x-auto whitespace-pre-wrap">
+                              {staticFix.goodExample}
+                            </pre>
+                          </div>
+                        )}
+                      </div>
+                    )}
+                  </div>
+                )}
+
+                {/* Help info (fallback if no static fix) */}
+                {!staticFix && (
+                  <div className="px-3 py-2 border-b border-[--border-subtle]">
+                    <p className="text-xs text-secondary mb-1">{rule.help}</p>
+                    {rule.helpUrl && (
+                      <a
+                        href={rule.helpUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-xs text-[--color-accent] hover:underline"
+                      >
+                        Learn more about {rule.id}
+                      </a>
+                    )}
+                  </div>
+                )}
+
+                {/* Affected elements */}
+                <div className="divide-y divide-[--border-subtle]">
+                  {rule.nodes.map((node, i) => {
+                    const fixKey = `${rule.id}-${node.html}`;
+                    const isHighlighted =
+                      highlightedElement === node.target.join(", ");
+                    const elementFix = generateElementFix(rule.id, node as unknown as SerializedNode);
+
+                    return (
+                      <div
+                        key={i}
+                        className={clsx(
+                          "px-3 py-3",
+                          isHighlighted && "bg-red-50 dark:bg-red-950/30"
+                        )}
+                      >
+                        {/* Element selector + actions */}
+                        <div className="flex items-center gap-2 mb-2">
+                          <button
+                            onClick={() =>
+                              onHighlight(
+                                isHighlighted ? null : node.target.join(", ")
+                              )
+                            }
+                            className={clsx(
+                              "text-[10px] font-mono px-2 py-1 rounded truncate max-w-[200px] transition-colors",
+                              isHighlighted
+                                ? "bg-red-200 dark:bg-red-800 text-red-800 dark:text-red-200"
+                                : "bg-[--bg-hover] text-secondary hover:text-primary hover:bg-[--bg-tertiary]"
+                            )}
+                            title={node.target.join(" > ")}
+                          >
+                            {isHighlighted ? "Hide" : "Highlight"}: {node.target[node.target.length - 1]}
+                          </button>
+
+                          {aiEnabled && onGenerateFix && (
+                            <button
+                              onClick={() => onGenerateFix(rule, node)}
+                              disabled={generatingFix === fixKey}
+                              className={clsx(
+                                "flex items-center gap-1 px-2 py-1 text-[10px] rounded transition-colors",
+                                generatingFix === fixKey
+                                  ? "bg-purple-100 dark:bg-purple-950/50 text-purple-600 dark:text-purple-400"
+                                  : "bg-[--bg-hover] text-tertiary hover:text-primary"
+                              )}
+                              title="Generate AI fix suggestion"
+                            >
+                              <WandIcon
+                                className={clsx(
+                                  "w-3 h-3",
+                                  generatingFix === fixKey && "animate-pulse"
+                                )}
+                              />
+                              {generatingFix === fixKey ? "Generating..." : "AI Fix"}
+                            </button>
+                          )}
+                        </div>
+
+                        {/* HTML snippet */}
+                        <pre className="text-[10px] font-mono text-tertiary bg-[--bg-primary] rounded p-2 overflow-x-auto whitespace-pre-wrap border border-[--border-subtle]">
+                          {node.html}
+                        </pre>
+
+                        {/* Failure summary */}
+                        {node.failureSummary && (
+                          <p className="text-xs text-secondary mt-2 leading-relaxed">
+                            {node.failureSummary}
+                          </p>
+                        )}
+
+                        {/* Static element fix */}
+                        {elementFix && (
+                          <div className="mt-2 p-2 rounded bg-blue-50 dark:bg-blue-950/30 border border-blue-200 dark:border-blue-800">
+                            <div className="flex items-center justify-between mb-1">
+                              <span className="text-[10px] font-medium text-blue-700 dark:text-blue-300">
+                                Suggested Fix
+                              </span>
+                              <button
+                                onClick={() => onCopyFix(elementFix.fixedHtml, fixKey)}
+                                className="text-[10px] text-blue-600 dark:text-blue-400 hover:underline"
+                              >
+                                {copiedFix === fixKey ? "Copied!" : "Copy"}
+                              </button>
+                            </div>
+                            <p className="text-[10px] text-blue-800 dark:text-blue-200 mb-2">
+                              {elementFix.explanation}
+                            </p>
+                            <pre className="text-[10px] font-mono text-blue-800 dark:text-blue-200 bg-blue-100 dark:bg-blue-900/50 rounded p-2 overflow-x-auto whitespace-pre-wrap">
+                              {elementFix.fixedHtml}
+                            </pre>
+                          </div>
+                        )}
+
+                        {/* AI fix suggestion */}
+                        {aiFixes?.[fixKey] && (
+                          <div className="mt-2 p-2 rounded bg-purple-50 dark:bg-purple-950/30 border border-purple-200 dark:border-purple-800">
+                            <div className="flex items-center gap-1 mb-1">
+                              <WandIcon className="w-3 h-3 text-purple-600 dark:text-purple-400" />
+                              <span className="text-[10px] font-medium text-purple-700 dark:text-purple-300">
+                                AI Fix Suggestion
+                              </span>
+                            </div>
+                            <pre className="text-[10px] font-mono text-purple-800 dark:text-purple-200 whitespace-pre-wrap">
+                              {aiFixes[fixKey]}
+                            </pre>
+                          </div>
+                        )}
+                      </div>
+                    );
+                  })}
+                </div>
+
+                {/* Tags */}
+                {rule.tags && rule.tags.length > 0 && (
+                  <div className="px-3 py-2 border-t border-[--border-subtle]">
+                    <div className="flex flex-wrap gap-1">
+                      {rule.tags.slice(0, 8).map((tag) => (
+                        <span
+                          key={tag}
+                          className="text-[10px] px-1.5 py-0.5 rounded bg-[--bg-hover] text-tertiary"
+                        >
+                          {tag}
+                        </span>
+                      ))}
+                      {rule.tags.length > 8 && (
+                        <span className="text-[10px] text-tertiary">
+                          +{rule.tags.length - 8} more
+                        </span>
+                      )}
+                    </div>
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+interface RuleListProps {
+  rules: Result[];
+  expandedRules: Set<string>;
+  onToggleRule: (id: string) => void;
+  onHighlight: (selector: string | null) => void;
+  highlightedElement: string | null;
+  type: "violation" | "pass" | "incomplete";
+}
+
+function RuleList({
+  rules,
+  expandedRules,
+  onToggleRule,
+  onHighlight,
+  highlightedElement,
+  type,
+}: RuleListProps) {
+  return (
+    <div className="space-y-2">
+      {rules.map((rule) => {
+        const isExpanded = expandedRules.has(rule.id);
+
+        return (
+          <div
+            key={rule.id}
+            className="rounded-lg border border-[--border] overflow-hidden"
+          >
+            {/* Rule Header */}
+            <button
+              onClick={() => onToggleRule(rule.id)}
+              className="w-full flex items-center gap-2 px-3 py-2 text-left hover:bg-[--bg-hover] transition-colors"
+            >
+              {isExpanded ? (
+                <ChevronDownIcon className="w-4 h-4 text-tertiary flex-shrink-0" />
+              ) : (
+                <ChevronRightIcon className="w-4 h-4 text-tertiary flex-shrink-0" />
+              )}
+
+              {type === "pass" && (
+                <CheckIcon className="w-4 h-4 text-green-600 flex-shrink-0" />
+              )}
+
+              {type === "incomplete" && (
+                <span className="text-[10px] font-medium px-1.5 py-0.5 rounded uppercase bg-amber-100 dark:bg-amber-950/50 text-amber-700 dark:text-amber-300">
+                  Review
+                </span>
+              )}
+
+              <span className="text-xs text-primary flex-1 truncate">
+                {rule.description}
+              </span>
+
+              <span className="text-[10px] text-tertiary flex-shrink-0">
+                {rule.nodes.length} element{rule.nodes.length !== 1 ? "s" : ""}
+              </span>
+            </button>
+
+            {/* Expanded content */}
+            {isExpanded && (
+              <div className="border-t border-[--border] bg-[--bg-secondary]">
+                <div className="px-3 py-2 border-b border-[--border-subtle]">
+                  <p className="text-xs text-secondary mb-1">{rule.help}</p>
+                  {rule.helpUrl && (
+                    <a
+                      href={rule.helpUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="text-xs text-[--color-accent] hover:underline"
+                    >
+                      Learn more about {rule.id}
+                    </a>
+                  )}
+                </div>
+
+                <div className="divide-y divide-[--border-subtle]">
+                  {rule.nodes.map((node, i) => {
+                    const isHighlighted =
+                      highlightedElement === node.target.join(", ");
+
+                    return (
+                      <div
+                        key={i}
+                        className={clsx(
+                          "px-3 py-2",
+                          isHighlighted && "bg-green-50 dark:bg-green-950/30"
+                        )}
+                      >
+                        <button
+                          onClick={() =>
+                            onHighlight(
+                              isHighlighted ? null : node.target.join(", ")
+                            )
+                          }
+                          className={clsx(
+                            "text-[10px] font-mono px-1.5 py-0.5 rounded truncate max-w-[200px] mb-1",
+                            isHighlighted
+                              ? "bg-green-200 dark:bg-green-800 text-green-800 dark:text-green-200"
+                              : "bg-[--bg-hover] text-secondary hover:text-primary"
+                          )}
+                          title={node.target.join(" > ")}
+                        >
+                          {node.target[node.target.length - 1]}
+                        </button>
+
+                        <pre className="text-[10px] font-mono text-tertiary bg-[--bg-primary] rounded p-2 overflow-x-auto whitespace-pre-wrap">
+                          {node.html}
+                        </pre>
+                      </div>
+                    );
+                  })}
+                </div>
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function SuccessMessage({ message }: { message: string }) {
+  return (
+    <div className="flex flex-col items-center justify-center py-8 text-center">
+      <div className="w-12 h-12 rounded-full bg-green-100 dark:bg-green-950/50 flex items-center justify-center mb-3">
+        <CheckIcon className="w-6 h-6 text-green-600 dark:text-green-400" />
+      </div>
+      <p className="text-sm font-medium text-green-700 dark:text-green-300">
+        {message}
+      </p>
+      <p className="text-xs text-tertiary mt-1">
+        This component passed all automated accessibility checks.
+      </p>
+    </div>
+  );
+}
+
+function EmptyMessage({ message }: { message: string }) {
+  return (
+    <div className="flex flex-col items-center justify-center py-8 text-center">
+      <AccessibilityIcon className="w-8 h-8 text-tertiary mb-2 opacity-50" />
+      <p className="text-xs text-tertiary">{message}</p>
+    </div>
+  );
+}
+
+interface AISetupModalProps {
+  onSave: (config: AIProviderConfig) => void;
+  onClose: () => void;
+  currentConfig: AIProviderConfig | null;
+}
+
+function AISetupModal({ onSave, onClose, currentConfig }: AISetupModalProps) {
+  const [provider, setProvider] = useState<"anthropic" | "openai">(
+    currentConfig?.provider || "anthropic"
+  );
+  const [apiKey, setApiKey] = useState(currentConfig?.apiKey || "");
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (apiKey.trim()) {
+      onSave({ provider, apiKey: apiKey.trim() });
+    }
+  };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+      <div className="bg-[--bg-primary] rounded-lg shadow-xl w-full max-w-md mx-4 overflow-hidden">
+        <div className="flex items-center justify-between px-4 py-3 border-b border-[--border]">
+          <h3 className="text-sm font-medium text-primary">
+            Configure AI Fix Suggestions
+          </h3>
+          <button
+            onClick={onClose}
+            className="p-1 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded"
+          >
+            <XIcon className="w-4 h-4" />
+          </button>
+        </div>
+
+        <form onSubmit={handleSubmit} className="p-4 space-y-4">
+          <p className="text-xs text-secondary">
+            Enter your API key to enable AI-powered fix suggestions for
+            accessibility violations. Your key is stored locally and never sent
+            to our servers.
+          </p>
+
+          <div>
+            <label className="block text-xs font-medium text-primary mb-1">
+              Provider
+            </label>
+            <div className="flex gap-2">
+              <button
+                type="button"
+                onClick={() => setProvider("anthropic")}
+                className={clsx(
+                  "flex-1 px-3 py-2 text-xs rounded border transition-colors",
+                  provider === "anthropic"
+                    ? "bg-[--color-accent] text-white border-[--color-accent]"
+                    : "bg-[--bg-secondary] text-secondary border-[--border] hover:border-[--color-accent]"
+                )}
+              >
+                Anthropic (Claude)
+              </button>
+              <button
+                type="button"
+                onClick={() => setProvider("openai")}
+                className={clsx(
+                  "flex-1 px-3 py-2 text-xs rounded border transition-colors",
+                  provider === "openai"
+                    ? "bg-[--color-accent] text-white border-[--color-accent]"
+                    : "bg-[--bg-secondary] text-secondary border-[--border] hover:border-[--color-accent]"
+                )}
+              >
+                OpenAI (GPT-4)
+              </button>
+            </div>
+          </div>
+
+          <div>
+            <label className="block text-xs font-medium text-primary mb-1">
+              API Key
+            </label>
+            <input
+              type="password"
+              value={apiKey}
+              onChange={(e) => setApiKey(e.target.value)}
+              placeholder={
+                provider === "anthropic"
+                  ? "sk-ant-api03-..."
+                  : "sk-..."
+              }
+              className="w-full px-3 py-2 text-xs rounded border border-[--border] bg-[--bg-secondary] text-primary placeholder:text-tertiary focus:outline-none focus:border-[--color-accent]"
+            />
+            <p className="text-[10px] text-tertiary mt-1">
+              Get your API key from{" "}
+              {provider === "anthropic" ? (
+                <a
+                  href="https://console.anthropic.com/settings/keys"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-[--color-accent] hover:underline"
+                >
+                  console.anthropic.com
+                </a>
+              ) : (
+                <a
+                  href="https://platform.openai.com/api-keys"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-[--color-accent] hover:underline"
+                >
+                  platform.openai.com
+                </a>
+              )}
+            </p>
+          </div>
+
+          <div className="flex justify-end gap-2 pt-2">
+            <button
+              type="button"
+              onClick={onClose}
+              className="px-3 py-1.5 text-xs rounded border border-[--border] text-secondary hover:bg-[--bg-hover]"
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              disabled={!apiKey.trim()}
+              className="px-3 py-1.5 text-xs rounded bg-[--color-accent] text-white hover:opacity-90 disabled:opacity-50"
+            >
+              Save Configuration
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}
+
+// ----- Helper Functions -----
+
+function buildFixPrompt(violation: Result, node: NodeResult): string {
+  return `You are an accessibility expert. Analyze this accessibility violation and provide a concise fix.
+
+**Violation:** ${violation.id}
+**Description:** ${violation.description}
+**Impact:** ${violation.impact}
+**Help:** ${violation.help}
+
+**Affected HTML:**
+\`\`\`html
+${node.html}
+\`\`\`
+
+**Element Path:** ${node.target.join(" > ")}
+
+**Failure Summary:**
+${node.failureSummary || "N/A"}
+
+Provide a brief, actionable fix for this specific accessibility issue. Include:
+1. What's wrong (1 sentence)
+2. The fixed HTML code
+3. Why this fix works (1 sentence)
+
+Keep your response concise and focused on the practical fix.`;
+}
+
+// Export icons used by App.tsx
+export { AccessibilityIcon };