@fragments-sdk/viewer 0.2.1

package/src/components/AccessibilityPanel.tsx

@@ -0,0 +1,1457 @@
+// @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 { Badge, Tabs, Dialog, Card, Alert, Text, Stack, Box, Button, Chip, EmptyState, Input } from "@fragments-sdk/ui";
+import { ShieldCheck, XCircle, Wheelchair } from "@phosphor-icons/react";
+import { PanelShell } from "./PanelShell.js";
+import { BRAND } from '@fragments-sdk/core';
+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,
+};
+
+// WCAG level color mapping
+const WCAG_LEVEL_COLORS: Record<string, { bg: string; color: string }> = {
+  A: { bg: 'var(--color-success-bg)', color: 'var(--color-success)' },
+  AA: { bg: 'var(--color-info-bg)', color: 'var(--color-info)' },
+  AAA: { bg: 'var(--color-accent-subtle)', color: 'var(--color-accent)' },
+};
+
+// 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;
+  const isInitialScan = isScanning && !results;
+
+  // Determine empty config for error / no-results states
+  const emptyConfig = (() => {
+    if (!isInitialScan && error) {
+      return {
+        icon: <XCircle size={24} weight="regular" style={{ color: 'var(--color-danger)' }} />,
+        title: "Scan failed",
+        description: error,
+        action: <Button variant="secondary" size="sm" onClick={runScan}>Retry Scan</Button>,
+      };
+    }
+    if (!isInitialScan && !error && !results) {
+      return {
+        icon: <Wheelchair size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />,
+        title: "No scan results",
+        description: "Run an accessibility scan to check this component for WCAG violations.",
+        action: <Button size="sm" onClick={runScan}>Run Scan</Button>,
+      };
+    }
+    return undefined;
+  })();
+
+  // Custom loading skeleton for accessibility scan
+  const loadingSkeleton = (
+    <Stack gap="md">
+      <Box paddingX="md" paddingY="xs" background="secondary" rounded="md">
+        <Stack direction="row" align="center" gap="md">
+          {[0, 1, 2].map((i) => (
+            <div key={i} style={{ width: '90px', height: '28px', borderRadius: '6px', background: 'var(--bg-hover)', animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite', animationDelay: `${i * 100}ms` }} />
+          ))}
+        </Stack>
+      </Box>
+      {[0, 1, 2].map((i) => (
+        <Card key={i}>
+          <Box padding="sm">
+            <Stack direction="row" align="center" gap="sm">
+              <div style={{ width: '16px', height: '16px', borderRadius: '4px', background: 'var(--bg-hover)', animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite', animationDelay: `${i * 150}ms` }} />
+              <div style={{ width: '50px', height: '18px', borderRadius: '9px', background: 'var(--bg-hover)', animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite', animationDelay: `${i * 150 + 50}ms` }} />
+              <div style={{ flex: 1, height: '14px', borderRadius: '4px', background: 'var(--bg-hover)', animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite', animationDelay: `${i * 150 + 100}ms` }} />
+              <div style={{ width: '60px', height: '18px', borderRadius: '9px', background: 'var(--bg-hover)', animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite', animationDelay: `${i * 150 + 150}ms` }} />
+            </Stack>
+          </Box>
+        </Card>
+      ))}
+      <Stack direction="row" align="center" justify="center" gap="xs">
+        <LoadingIcon style={{ width: 14, height: 14, animation: 'spin 1s linear infinite' }} />
+        <Text size="xs" color="tertiary">Running accessibility checks...</Text>
+      </Stack>
+    </Stack>
+  );
+
+  // Toolbar with tabs, rescan badge, and action buttons (only when results exist)
+  const toolbar = results && !error ? (
+    <Stack direction="row" align="center" gap="xs" style={{ width: '100%' }}>
+      <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as TabType)}>
+        <Tabs.List>
+          <Tabs.Tab value="violations">
+            <span style={{ color: 'var(--color-danger)' }}>{counts.violations}</span> Violations
+          </Tabs.Tab>
+          <Tabs.Tab value="passes">
+            <span style={{ color: 'var(--color-success)' }}>{counts.passes}</span> Passes
+          </Tabs.Tab>
+          <Tabs.Tab value="incomplete">
+            <span style={{ color: 'var(--color-warning)' }}>{counts.incomplete}</span> Incomplete
+          </Tabs.Tab>
+        </Tabs.List>
+      </Tabs>
+
+      <Box style={{ flex: 1 }} />
+
+      {isReScanning && (
+        <Badge variant="warning" size="sm">
+          <Stack direction="row" align="center" gap="xs">
+            <LoadingIcon style={{ width: 12, height: 12, animation: 'spin 1s linear infinite' }} />
+            Re-scanning...
+          </Stack>
+        </Badge>
+      )}
+
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={runScan}
+        disabled={isScanning}
+        title="Re-run accessibility scan"
+      >
+        <LoadingIcon
+          style={{
+            width: 12,
+            height: 12,
+            ...(isScanning ? { animation: 'spin 1s linear infinite' } : {}),
+          }}
+        />
+        {isScanning ? "Scanning..." : "Rescan"}
+      </Button>
+
+      <Button
+        variant={aiConfig ? "secondary" : "ghost"}
+        size="sm"
+        onClick={() => setShowAISetup(true)}
+        title={aiConfig ? "AI fixes enabled" : "Configure AI for fix suggestions"}
+      >
+        <WandIcon style={{ width: 12, height: 12 }} />
+        {aiConfig ? "AI Ready" : "Setup AI"}
+      </Button>
+    </Stack>
+  ) : undefined;
+
+  return (
+    <PanelShell
+      loading={isInitialScan}
+      loadingContent={loadingSkeleton}
+      toolbar={toolbar}
+      empty={emptyConfig}
+    >
+      {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"
+            />
+          )}
+        </>
+      )}
+
+      {/* AI Setup Dialog */}
+      <Dialog open={showAISetup} onOpenChange={(open) => !open && setShowAISetup(false)}>
+        <Dialog.Content>
+          <AISetupModalContent
+            onSave={saveAIConfig}
+            onClose={() => setShowAISetup(false)}
+            currentConfig={aiConfig}
+          />
+        </Dialog.Content>
+      </Dialog>
+    </PanelShell>
+  );
+}
+
+// ----- Sub-components -----
+
+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 (
+    <Stack gap="md">
+      {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 (
+          <Card key={rule.id} style={{ borderLeft: `4px solid ${impactColors.borderLeft}` }}>
+            {/* Rule Header */}
+            <Button
+              variant="ghost"
+              fullWidth
+              onClick={() => onToggleRule(rule.id)}
+              style={{ justifyContent: 'flex-start', padding: '10px 12px' }}
+            >
+              <Stack direction="row" align="center" gap="sm" style={{ width: '100%' }}>
+                {isExpanded ? (
+                  <ChevronDownIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)', flexShrink: 0 }} />
+                ) : (
+                  <ChevronRightIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)', flexShrink: 0 }} />
+                )}
+
+                {/* Impact badge */}
+                {rule.impact && (
+                  <Badge variant={impactColors.variant} size="sm">
+                    {rule.impact}
+                  </Badge>
+                )}
+
+                {/* Rule ID */}
+                <Text font="mono" size="xs" color="tertiary">{rule.id}</Text>
+
+                {/* Rule description */}
+                <Text size="xs" style={{
+                  flex: 1,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                }}>
+                  {rule.description}
+                </Text>
+
+                {/* Element count */}
+                <Badge size="sm">
+                  {rule.nodes.length} element{rule.nodes.length !== 1 ? "s" : ""}
+                </Badge>
+              </Stack>
+            </Button>
+
+            {/* Expanded content */}
+            {isExpanded && (
+              <Box borderTop background="secondary">
+                {/* Why it matters + WCAG reference */}
+                {staticFix && (
+                  <Box padding="sm" style={{ borderBottom: '1px solid var(--border-subtle)' }}>
+                    <Stack gap="sm">
+                      <Alert severity="info">
+                        <Alert.Body>
+                          <Alert.Title>Why it matters</Alert.Title>
+                          <Alert.Content>
+                            <Text size="xs">{staticFix.whyItMatters}</Text>
+                          </Alert.Content>
+                        </Alert.Body>
+                      </Alert>
+
+                      {/* WCAG criterion */}
+                      {staticFix.wcagCriterion && (
+                        <Stack direction="row" align="center" gap="sm">
+                          <Badge size="sm" style={{
+                            background: WCAG_LEVEL_COLORS[staticFix.wcagCriterion.level]?.bg || 'var(--bg-hover)',
+                            color: WCAG_LEVEL_COLORS[staticFix.wcagCriterion.level]?.color || 'var(--text-secondary)',
+                          }}>
+                            WCAG {staticFix.wcagCriterion.id} Level {staticFix.wcagCriterion.level}
+                          </Badge>
+                          <Text size="xs" color="secondary">{staticFix.wcagCriterion.name}</Text>
+                          <Button
+                            as="a"
+                            variant="ghost"
+                            size="sm"
+                            href={staticFix.wcagCriterion.url}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            style={{ marginLeft: 'auto', fontSize: 12 }}
+                          >
+                            Learn more
+                          </Button>
+                        </Stack>
+                      )}
+
+                      {/* Before/After examples */}
+                      {(staticFix.badExample || staticFix.goodExample) && (
+                        <Box display="grid" style={{ gridTemplateColumns: '1fr 1fr', gap: 8, marginTop: 8 }}>
+                          {staticFix.badExample && (
+                            <div>
+                              <Text size="xs" weight="medium" style={{ color: 'var(--color-danger)', marginBottom: 4 }}>
+                                Before
+                              </Text>
+                              <Box as="pre" padding="xs" rounded="sm" style={{
+                                fontSize: 10,
+                                fontFamily: 'monospace',
+                                background: 'var(--color-danger-bg)',
+                                color: 'var(--color-danger)',
+                                overflowX: 'auto',
+                                whiteSpace: 'pre-wrap',
+                                margin: 0,
+                              }}>
+                                {staticFix.badExample}
+                              </Box>
+                            </div>
+                          )}
+                          {staticFix.goodExample && (
+                            <div>
+                              <Text size="xs" weight="medium" style={{ color: 'var(--color-success)', marginBottom: 4 }}>
+                                After
+                              </Text>
+                              <Box as="pre" padding="xs" rounded="sm" style={{
+                                fontSize: 10,
+                                fontFamily: 'monospace',
+                                background: 'var(--color-success-bg)',
+                                color: 'var(--color-success)',
+                                overflowX: 'auto',
+                                whiteSpace: 'pre-wrap',
+                                margin: 0,
+                              }}>
+                                {staticFix.goodExample}
+                              </Box>
+                            </div>
+                          )}
+                        </Box>
+                      )}
+                    </Stack>
+                  </Box>
+                )}
+
+                {/* Help info (fallback if no static fix) */}
+                {!staticFix && (
+                  <Box padding="sm" style={{ borderBottom: '1px solid var(--border-subtle)' }}>
+                    <Text size="xs" color="secondary" style={{ marginBottom: 4 }}>{rule.help}</Text>
+                    {rule.helpUrl && (
+                      <Button
+                        as="a"
+                        variant="ghost"
+                        size="sm"
+                        href={rule.helpUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        style={{ fontSize: 12 }}
+                      >
+                        Learn more about {rule.id}
+                      </Button>
+                    )}
+                  </Box>
+                )}
+
+                {/* Affected elements */}
+                <div>
+                  {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 (
+                      <Box
+                        key={i}
+                        padding="sm"
+                        style={{
+                          borderTop: i > 0 ? '1px solid var(--border-subtle)' : undefined,
+                          background: isHighlighted ? 'var(--color-danger-bg)' : undefined,
+                        }}
+                      >
+                        {/* Element selector + actions */}
+                        <Stack direction="row" align="center" gap="sm" style={{ marginBottom: 8 }}>
+                          <Button
+                            variant={isHighlighted ? "primary" : "ghost"}
+                            size="sm"
+                            onClick={() =>
+                              onHighlight(
+                                isHighlighted ? null : node.target.join(", ")
+                              )
+                            }
+                            title={node.target.join(" > ")}
+                            style={{
+                              fontFamily: 'monospace',
+                              fontSize: 10,
+                              maxWidth: 200,
+                              overflow: 'hidden',
+                              textOverflow: 'ellipsis',
+                              whiteSpace: 'nowrap',
+                            }}
+                          >
+                            {isHighlighted ? "Hide" : "Highlight"}: {node.target[node.target.length - 1]}
+                          </Button>
+
+                          {aiEnabled && onGenerateFix && (
+                            <Button
+                              variant="ghost"
+                              size="sm"
+                              onClick={() => onGenerateFix(rule, node)}
+                              disabled={generatingFix === fixKey}
+                              title="Generate AI fix suggestion"
+                            >
+                              <WandIcon
+                                style={{
+                                  width: 12,
+                                  height: 12,
+                                  ...(generatingFix === fixKey ? { animation: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite' } : {}),
+                                }}
+                              />
+                              {generatingFix === fixKey ? "Generating..." : "AI Fix"}
+                            </Button>
+                          )}
+                        </Stack>
+
+                        {/* HTML snippet */}
+                        <Box as="pre" padding="xs" rounded="sm" style={{
+                          fontSize: 10,
+                          fontFamily: 'monospace',
+                          color: 'var(--text-tertiary)',
+                          background: 'var(--bg-primary)',
+                          overflowX: 'auto',
+                          whiteSpace: 'pre-wrap',
+                          border: '1px solid var(--border-subtle)',
+                          margin: 0,
+                        }}>
+                          {node.html}
+                        </Box>
+
+                        {/* Failure summary */}
+                        {node.failureSummary && (
+                          <Text size="xs" color="secondary" style={{ marginTop: 8, lineHeight: 1.6 }}>
+                            {node.failureSummary}
+                          </Text>
+                        )}
+
+                        {/* Static element fix */}
+                        {elementFix && (
+                          <Alert severity="info" style={{ marginTop: 8 }}>
+                            <Alert.Body>
+                              <Stack direction="row" align="center" justify="between" style={{ marginBottom: 4 }}>
+                                <Text size="xs" weight="medium" style={{ color: 'var(--color-info)' }}>
+                                  Suggested Fix
+                                </Text>
+                                <Button
+                                  variant="ghost"
+                                  size="sm"
+                                  onClick={() => onCopyFix(elementFix.fixedHtml, fixKey)}
+                                  style={{ fontSize: 10, color: 'var(--color-info)' }}
+                                >
+                                  {copiedFix === fixKey ? "Copied!" : "Copy"}
+                                </Button>
+                              </Stack>
+                              <Alert.Content>
+                                <Text size="xs" style={{ color: 'var(--color-info)', marginBottom: 8 }}>
+                                  {elementFix.explanation}
+                                </Text>
+                                <Box as="pre" padding="xs" rounded="sm" style={{
+                                  fontSize: 10,
+                                  fontFamily: 'monospace',
+                                  color: 'var(--color-info)',
+                                  background: 'var(--bg-secondary)',
+                                  overflowX: 'auto',
+                                  whiteSpace: 'pre-wrap',
+                                  margin: 0,
+                                }}>
+                                  {elementFix.fixedHtml}
+                                </Box>
+                              </Alert.Content>
+                            </Alert.Body>
+                          </Alert>
+                        )}
+
+                        {/* AI fix suggestion */}
+                        {aiFixes?.[fixKey] && (
+                          <Box padding="xs" rounded="sm" style={{
+                            marginTop: 8,
+                            background: 'var(--color-accent-subtle)',
+                            border: '1px solid var(--color-accent)',
+                          }}>
+                            <Stack direction="row" align="center" gap="xs" style={{ marginBottom: 4 }}>
+                              <WandIcon style={{ width: 12, height: 12, color: 'var(--color-accent)' }} />
+                              <Text size="xs" weight="medium" style={{ color: 'var(--color-accent)' }}>
+                                AI Fix Suggestion
+                              </Text>
+                            </Stack>
+                            <Box as="pre" style={{
+                              fontSize: 10,
+                              fontFamily: 'monospace',
+                              color: 'var(--color-accent)',
+                              whiteSpace: 'pre-wrap',
+                              margin: 0,
+                            }}>
+                              {aiFixes[fixKey]}
+                            </Box>
+                          </Box>
+                        )}
+                      </Box>
+                    );
+                  })}
+                </div>
+
+                {/* Tags */}
+                {rule.tags && rule.tags.length > 0 && (
+                  <Box padding="sm" style={{ borderTop: '1px solid var(--border-subtle)' }}>
+                    <Stack direction="row" gap="xs" style={{ flexWrap: 'wrap' }}>
+                      {rule.tags.slice(0, 8).map((tag) => (
+                        <Chip key={tag} size="sm">{tag}</Chip>
+                      ))}
+                      {rule.tags.length > 8 && (
+                        <Text size="xs" color="tertiary">
+                          +{rule.tags.length - 8} more
+                        </Text>
+                      )}
+                    </Stack>
+                  </Box>
+                )}
+              </Box>
+            )}
+          </Card>
+        );
+      })}
+    </Stack>
+  );
+}
+
+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 (
+    <Stack gap="sm">
+      {rules.map((rule) => {
+        const isExpanded = expandedRules.has(rule.id);
+
+        return (
+          <Card key={rule.id}>
+            {/* Rule Header */}
+            <Button
+              variant="ghost"
+              fullWidth
+              onClick={() => onToggleRule(rule.id)}
+              style={{ justifyContent: 'flex-start', padding: '8px 12px' }}
+            >
+              <Stack direction="row" align="center" gap="sm" style={{ width: '100%' }}>
+                {isExpanded ? (
+                  <ChevronDownIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)', flexShrink: 0 }} />
+                ) : (
+                  <ChevronRightIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)', flexShrink: 0 }} />
+                )}
+
+                {type === "pass" && (
+                  <CheckIcon style={{ width: 16, height: 16, color: 'var(--color-success)', flexShrink: 0 }} />
+                )}
+
+                {type === "incomplete" && (
+                  <Badge variant="warning" size="sm">Review</Badge>
+                )}
+
+                <Text size="xs" style={{
+                  flex: 1,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                }}>
+                  {rule.description}
+                </Text>
+
+                <Text size="xs" color="tertiary" style={{ flexShrink: 0 }}>
+                  {rule.nodes.length} element{rule.nodes.length !== 1 ? "s" : ""}
+                </Text>
+              </Stack>
+            </Button>
+
+            {/* Expanded content */}
+            {isExpanded && (
+              <Box borderTop background="secondary">
+                <Box padding="sm" style={{ borderBottom: '1px solid var(--border-subtle)' }}>
+                  <Text size="xs" color="secondary" style={{ marginBottom: 4 }}>{rule.help}</Text>
+                  {rule.helpUrl && (
+                    <Button
+                      as="a"
+                      variant="ghost"
+                      size="sm"
+                      href={rule.helpUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      style={{ fontSize: 12 }}
+                    >
+                      Learn more about {rule.id}
+                    </Button>
+                  )}
+                </Box>
+
+                <div>
+                  {rule.nodes.map((node, i) => {
+                    const isHighlighted =
+                      highlightedElement === node.target.join(", ");
+
+                    return (
+                      <Box
+                        key={i}
+                        padding="sm"
+                        style={{
+                          borderTop: i > 0 ? '1px solid var(--border-subtle)' : undefined,
+                          background: isHighlighted ? 'var(--color-success-bg)' : undefined,
+                        }}
+                      >
+                        <Button
+                          variant={isHighlighted ? "primary" : "ghost"}
+                          size="sm"
+                          onClick={() =>
+                            onHighlight(
+                              isHighlighted ? null : node.target.join(", ")
+                            )
+                          }
+                          title={node.target.join(" > ")}
+                          style={{
+                            fontFamily: 'monospace',
+                            fontSize: 10,
+                            maxWidth: 200,
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap',
+                            marginBottom: 4,
+                          }}
+                        >
+                          {node.target[node.target.length - 1]}
+                        </Button>
+
+                        <Box as="pre" padding="xs" rounded="sm" style={{
+                          fontSize: 10,
+                          fontFamily: 'monospace',
+                          color: 'var(--text-tertiary)',
+                          background: 'var(--bg-primary)',
+                          overflowX: 'auto',
+                          whiteSpace: 'pre-wrap',
+                          margin: 0,
+                        }}>
+                          {node.html}
+                        </Box>
+                      </Box>
+                    );
+                  })}
+                </div>
+              </Box>
+            )}
+          </Card>
+        );
+      })}
+    </Stack>
+  );
+}
+
+function SuccessMessage({ message }: { message: string }) {
+  return (
+    <EmptyState>
+      <EmptyState.Icon>
+        <Box rounded="full" display="flex" style={{
+          width: 48,
+          height: 48,
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'var(--color-success-bg)',
+        }}>
+          <ShieldCheck size={24} weight="regular" style={{ color: 'var(--color-success)' }} />
+        </Box>
+      </EmptyState.Icon>
+      <EmptyState.Title style={{ color: 'var(--color-success)' }}>{message}</EmptyState.Title>
+      <EmptyState.Description>
+        This component passed all automated accessibility checks.
+      </EmptyState.Description>
+    </EmptyState>
+  );
+}
+
+function EmptyMessage({ message }: { message: string }) {
+  return (
+    <EmptyState>
+      <EmptyState.Icon>
+        <Box rounded="full" display="flex" style={{
+          width: 48,
+          height: 48,
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'var(--bg-hover)',
+        }}>
+          <Wheelchair size={24} weight="regular" style={{ color: 'var(--text-tertiary)' }} />
+        </Box>
+      </EmptyState.Icon>
+      <EmptyState.Description>{message}</EmptyState.Description>
+    </EmptyState>
+  );
+}
+
+interface AISetupModalContentProps {
+  onSave: (config: AIProviderConfig) => void;
+  onClose: () => void;
+  currentConfig: AIProviderConfig | null;
+}
+
+function AISetupModalContent({ onSave, onClose, currentConfig }: AISetupModalContentProps) {
+  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 (
+    <>
+      <Dialog.Header>
+        <Dialog.Title>Configure AI Fix Suggestions</Dialog.Title>
+        <Dialog.Description>
+          Enter your API key to enable AI-powered fix suggestions for
+          accessibility violations. Your key is stored locally and never sent
+          to our servers.
+        </Dialog.Description>
+      </Dialog.Header>
+
+      <Dialog.Body>
+        <form onSubmit={handleSubmit}>
+          <Stack gap="md">
+            <div>
+              <Text size="xs" weight="medium" style={{ marginBottom: 4 }}>Provider</Text>
+              <Stack direction="row" gap="sm">
+                <Button
+                  variant={provider === "anthropic" ? "primary" : "secondary"}
+                  size="sm"
+                  onClick={() => setProvider("anthropic")}
+                  type="button"
+                  style={{ flex: 1 }}
+                >
+                  Anthropic (Claude)
+                </Button>
+                <Button
+                  variant={provider === "openai" ? "primary" : "secondary"}
+                  size="sm"
+                  onClick={() => setProvider("openai")}
+                  type="button"
+                  style={{ flex: 1 }}
+                >
+                  OpenAI (GPT-4)
+                </Button>
+              </Stack>
+            </div>
+
+            <div>
+              <Text size="xs" weight="medium" style={{ marginBottom: 4 }}>API Key</Text>
+              <Input
+                type="password"
+                value={apiKey}
+                onChange={(e) => setApiKey(e.target.value)}
+                placeholder={
+                  provider === "anthropic"
+                    ? "sk-ant-api03-..."
+                    : "sk-..."
+                }
+                size="sm"
+                style={{ width: '100%' }}
+              />
+              <Text size="xs" color="tertiary" style={{ marginTop: 4 }}>
+                Get your API key from{" "}
+                {provider === "anthropic" ? (
+                  <Button
+                    as="a"
+                    variant="ghost"
+                    size="sm"
+                    href="https://console.anthropic.com/settings/keys"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    style={{ display: 'inline', padding: 0, fontSize: 'inherit' }}
+                  >
+                    console.anthropic.com
+                  </Button>
+                ) : (
+                  <Button
+                    as="a"
+                    variant="ghost"
+                    size="sm"
+                    href="https://platform.openai.com/api-keys"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    style={{ display: 'inline', padding: 0, fontSize: 'inherit' }}
+                  >
+                    platform.openai.com
+                  </Button>
+                )}
+              </Text>
+            </div>
+
+            <Dialog.Footer>
+              <Button variant="secondary" size="sm" onClick={onClose} type="button">
+                Cancel
+              </Button>
+              <Button
+                size="sm"
+                type="submit"
+                disabled={!apiKey.trim()}
+              >
+                Save Configuration
+              </Button>
+            </Dialog.Footer>
+          </Stack>
+        </form>
+      </Dialog.Body>
+    </>
+  );
+}
+
+// ----- 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 };