@fragments-sdk/viewer 0.2.1

package/src/types/a11y.ts

@@ -0,0 +1,197 @@
+/**
+ * Accessibility Types
+ *
+ * TypeScript interfaces for the accessibility checking system.
+ */
+
+import type { ImpactValue } from 'axe-core';
+
+/**
+ * Serialized violation node for storage
+ */
+export interface SerializedNode {
+  /** HTML snippet of the affected element */
+  html: string;
+  /** CSS selector path to the element */
+  target: string[];
+  /** Failure summary explaining the issue */
+  failureSummary?: string;
+  /** Any data collected during the check */
+  any?: Array<{
+    id: string;
+    data?: unknown;
+    relatedNodes?: Array<{ html: string; target: string[] }>;
+    impact?: string;
+    message: string;
+  }>;
+  /** All data required for the check to pass */
+  all?: Array<{
+    id: string;
+    data?: unknown;
+    relatedNodes?: Array<{ html: string; target: string[] }>;
+    impact?: string;
+    message: string;
+  }>;
+  /** None data that should not be present */
+  none?: Array<{
+    id: string;
+    data?: unknown;
+    relatedNodes?: Array<{ html: string; target: string[] }>;
+    impact?: string;
+    message: string;
+  }>;
+}
+
+/**
+ * Serialized violation for storage and display
+ */
+export interface SerializedViolation {
+  /** Unique rule identifier (e.g., 'color-contrast') */
+  id: string;
+  /** Impact level of the violation */
+  impact: ImpactValue | null;
+  /** Brief description of the rule */
+  description: string;
+  /** Longer help text explaining how to fix */
+  help: string;
+  /** URL to detailed documentation */
+  helpUrl: string;
+  /** WCAG tags (e.g., 'wcag2a', 'wcag143') */
+  tags: string[];
+  /** Affected elements */
+  nodes: SerializedNode[];
+}
+
+/**
+ * Cached accessibility result for a component
+ */
+export interface CachedA11yResult {
+  /** Component name */
+  componentName: string;
+  /** Variant that was scanned (optional) */
+  variant?: string;
+  /** Full violation details for display */
+  violations: SerializedViolation[];
+  /** Number of passing checks */
+  passes: number;
+  /** Number of incomplete checks */
+  incomplete: number;
+  /** When the scan was performed */
+  scannedAt: number;
+  /** Counts by severity */
+  counts: {
+    critical: number;
+    serious: number;
+    moderate: number;
+    minor: number;
+  };
+}
+
+/**
+ * Summary data derived from cache
+ */
+export interface A11ySummary {
+  /** Components with no critical/serious violations */
+  accessibleComponents: number;
+  /** Total components scanned */
+  totalComponents: number;
+  /** Violations aggregated by impact */
+  violationsByImpact: {
+    critical: number;
+    serious: number;
+    moderate: number;
+    minor: number;
+  };
+  /** Top violations across all components */
+  topViolations: Array<{
+    ruleId: string;
+    description: string;
+    affectedComponents: string[];
+    impact: ImpactValue | null;
+  }>;
+}
+
+/**
+ * Event data for a11y cache invalidation
+ */
+export interface A11yInvalidateEvent {
+  /** Component names to invalidate */
+  components: string[];
+  /** File that changed */
+  file: string;
+  /** Timestamp of the change */
+  timestamp: number;
+}
+
+/**
+ * A11y service configuration
+ */
+export interface A11yServiceConfig {
+  /** Debounce delay after HMR file change (ms) */
+  hmrDebounceMs: number;
+  /** Debounce delay after navigation (ms) */
+  navigationDebounceMs: number;
+  /** Minimum time between same component scans (ms) */
+  scanCooldownMs: number;
+  /** Maximum concurrent scans */
+  maxConcurrentScans: number;
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_A11Y_CONFIG: A11yServiceConfig = {
+  hmrDebounceMs: 500,
+  navigationDebounceMs: 200,
+  scanCooldownMs: 1000,
+  maxConcurrentScans: 2,
+};
+
+/**
+ * Static fix suggestion for a violation
+ */
+export interface StaticFixSuggestion {
+  /** Why this issue matters for users */
+  whyItMatters: string;
+  /** Generic fix description */
+  howToFix: string;
+  /** Example of bad code */
+  badExample?: string;
+  /** Example of good code */
+  goodExample?: string;
+  /** WCAG criterion reference */
+  wcagCriterion?: {
+    id: string;
+    name: string;
+    level: 'A' | 'AA' | 'AAA';
+    url: string;
+  };
+}
+
+/**
+ * Specific fix for an element
+ */
+export interface ElementFix {
+  /** The original HTML */
+  originalHtml: string;
+  /** The suggested fix HTML */
+  fixedHtml: string;
+  /** Explanation of the change */
+  explanation: string;
+  /** Whether this is an auto-fixable change */
+  autoFixable: boolean;
+}
+
+/**
+ * Scan status for tracking progress
+ */
+export type ScanStatus = 'idle' | 'pending' | 'scanning' | 'completed' | 'error';
+
+/**
+ * Component scan state
+ */
+export interface ComponentScanState {
+  status: ScanStatus;
+  lastScanAt?: number;
+  error?: string;
+}

package/src/utils/a11y-fixes.ts

@@ -0,0 +1,509 @@
+/**
+ * A11y Fixes - Static Fix Generators
+ *
+ * Rule-specific fix suggestions without AI. Provides:
+ * - "Why it matters" explanations
+ * - Before/after code examples
+ * - WCAG references
+ * - Specific fixes based on violation data
+ */
+
+import type { ImpactValue } from 'axe-core';
+import type { StaticFixSuggestion, ElementFix, SerializedNode } from '../types/a11y.js';
+import { parseColor, suggestFix, rgbToHex } from './contrast.js';
+
+/**
+ * WCAG criteria references
+ */
+const WCAG_CRITERIA: Record<string, { id: string; name: string; level: 'A' | 'AA' | 'AAA'; url: string }> = {
+  // Level A
+  '1.1.1': {
+    id: '1.1.1',
+    name: 'Non-text Content',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content',
+  },
+  '1.3.1': {
+    id: '1.3.1',
+    name: 'Info and Relationships',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships',
+  },
+  '2.1.1': {
+    id: '2.1.1',
+    name: 'Keyboard',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/keyboard',
+  },
+  '2.4.4': {
+    id: '2.4.4',
+    name: 'Link Purpose (In Context)',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context',
+  },
+  '4.1.2': {
+    id: '4.1.2',
+    name: 'Name, Role, Value',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value',
+  },
+  // Level AA
+  '1.4.3': {
+    id: '1.4.3',
+    name: 'Contrast (Minimum)',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum',
+  },
+  '1.4.4': {
+    id: '1.4.4',
+    name: 'Resize Text',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/resize-text',
+  },
+  '2.4.6': {
+    id: '2.4.6',
+    name: 'Headings and Labels',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels',
+  },
+  '2.5.8': {
+    id: '2.5.8',
+    name: 'Target Size (Minimum)',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum',
+  },
+  // Level AAA
+  '1.4.6': {
+    id: '1.4.6',
+    name: 'Contrast (Enhanced)',
+    level: 'AAA',
+    url: 'https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced',
+  },
+};
+
+/**
+ * Static fix suggestions for common accessibility rules
+ */
+const STATIC_FIXES: Record<string, StaticFixSuggestion> = {
+  'color-contrast': {
+    whyItMatters:
+      'Low contrast text is difficult to read for users with low vision, color blindness, or in bright environments like outdoor settings.',
+    howToFix:
+      'Increase the contrast ratio between text and background colors. Normal text requires 4.5:1, large text (18pt or 14pt bold) requires 3:1.',
+    badExample: '<button style="color: #888; background: #fff">Submit</button>',
+    goodExample: '<button style="color: #333; background: #fff">Submit</button>',
+    wcagCriterion: WCAG_CRITERIA['1.4.3'],
+  },
+  'image-alt': {
+    whyItMatters:
+      'Screen reader users cannot perceive images and rely on alternative text to understand visual content.',
+    howToFix:
+      'Add descriptive alt text that conveys the purpose or content of the image. For decorative images, use alt="".',
+    badExample: '<img src="hero.jpg">',
+    goodExample: '<img src="hero.jpg" alt="Team collaboration in modern office">',
+    wcagCriterion: WCAG_CRITERIA['1.1.1'],
+  },
+  'button-name': {
+    whyItMatters:
+      'Screen reader users need accessible names to understand what a button does. Without a name, they hear "button" with no context.',
+    howToFix:
+      'Add text content, an aria-label, or aria-labelledby attribute to give the button an accessible name.',
+    badExample: '<button><svg>...</svg></button>',
+    goodExample: '<button aria-label="Close dialog"><svg>...</svg></button>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'link-name': {
+    whyItMatters:
+      'Screen reader users navigate by links and need descriptive text to understand each link\'s destination or purpose.',
+    howToFix:
+      'Use descriptive link text instead of generic phrases. Avoid "click here" or "read more" without context.',
+    badExample: '<a href="/docs">Click here</a>',
+    goodExample: '<a href="/docs">View documentation</a>',
+    wcagCriterion: WCAG_CRITERIA['2.4.4'],
+  },
+  'label': {
+    whyItMatters:
+      'Form inputs without labels are difficult for screen reader users to understand and for all users to identify.',
+    howToFix:
+      'Associate a <label> element with the input using the for/id attributes, or wrap the input in a label element.',
+    badExample: '<input type="text" placeholder="Email">',
+    goodExample: '<label for="email">Email</label>\n<input type="text" id="email">',
+    wcagCriterion: WCAG_CRITERIA['1.3.1'],
+  },
+  'aria-valid-attr': {
+    whyItMatters:
+      'Invalid ARIA attributes are ignored by assistive technologies and may indicate other accessibility issues.',
+    howToFix:
+      'Use only valid ARIA attributes from the WAI-ARIA specification. Check spelling and ensure attributes apply to the element type.',
+    badExample: '<button aria-expanded="true" aria-describedby="">Submit</button>',
+    goodExample: '<button aria-expanded="true" aria-describedby="help-text">Submit</button>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'aria-valid-attr-value': {
+    whyItMatters:
+      'ARIA attributes with invalid values are ignored or misinterpreted by assistive technologies.',
+    howToFix:
+      'Ensure ARIA attribute values match the expected format (boolean, ID reference, token, etc.).',
+    badExample: '<div aria-hidden="yes">Hidden content</div>',
+    goodExample: '<div aria-hidden="true">Hidden content</div>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'aria-required-attr': {
+    whyItMatters:
+      'ARIA roles require specific attributes to function correctly with assistive technologies.',
+    howToFix:
+      'Add all required ARIA attributes for the role being used.',
+    badExample: '<div role="checkbox">Accept terms</div>',
+    goodExample: '<div role="checkbox" aria-checked="false">Accept terms</div>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'heading-order': {
+    whyItMatters:
+      'Screen reader users navigate by headings. Skipped heading levels make it harder to understand document structure.',
+    howToFix:
+      'Use headings in sequential order (h1 → h2 → h3). Don\'t skip levels for styling purposes.',
+    badExample: '<h1>Page Title</h1>\n<h4>Section</h4>',
+    goodExample: '<h1>Page Title</h1>\n<h2>Section</h2>',
+    wcagCriterion: WCAG_CRITERIA['1.3.1'],
+  },
+  'tabindex': {
+    whyItMatters:
+      'Positive tabindex values create unexpected keyboard navigation order, confusing keyboard-only users.',
+    howToFix:
+      'Use tabindex="0" to add elements to natural tab order, or tabindex="-1" to remove them. Avoid positive values.',
+    badExample: '<button tabindex="5">First</button>\n<button tabindex="1">Second</button>',
+    goodExample: '<button>First</button>\n<button>Second</button>',
+    wcagCriterion: WCAG_CRITERIA['2.1.1'],
+  },
+  'duplicate-id': {
+    whyItMatters:
+      'Duplicate IDs can cause aria-labelledby, aria-describedby, and label associations to reference the wrong element.',
+    howToFix:
+      'Ensure each id attribute value is unique within the page.',
+    badExample: '<input id="name">\n<input id="name">',
+    goodExample: '<input id="first-name">\n<input id="last-name">',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'target-size-minimum': {
+    whyItMatters:
+      'Small touch targets are difficult to activate for users with motor impairments or when using touch input.',
+    howToFix:
+      'Increase the interactive target to at least 24x24 CSS pixels, or add sufficient padding around the control.',
+    badExample: '<button style="width: 16px; height: 16px">×</button>',
+    goodExample: '<button style="min-width: 24px; min-height: 24px; padding: 4px">×</button>',
+    wcagCriterion: WCAG_CRITERIA['2.5.8'],
+  },
+};
+
+/**
+ * Get static fix suggestion for a rule
+ */
+export function getStaticFix(ruleId: string): StaticFixSuggestion | null {
+  return STATIC_FIXES[ruleId] || null;
+}
+
+/**
+ * Parse contrast ratio data from axe-core node data
+ */
+function parseContrastData(node: SerializedNode): {
+  fgColor?: string;
+  bgColor?: string;
+  contrastRatio?: number;
+  requiredRatio?: number;
+  fontSize?: string;
+  fontWeight?: string;
+} | null {
+  const anyData = node.any?.[0]?.data as Record<string, unknown> | undefined;
+  if (!anyData) return null;
+
+  return {
+    fgColor: anyData.fgColor as string | undefined,
+    bgColor: anyData.bgColor as string | undefined,
+    contrastRatio: anyData.contrastRatio as number | undefined,
+    requiredRatio: anyData.expectedContrastRatio as number | undefined,
+    fontSize: anyData.fontSize as string | undefined,
+    fontWeight: anyData.fontWeight as string | undefined,
+  };
+}
+
+/**
+ * Generate a specific fix for a color-contrast violation
+ */
+function generateContrastFix(node: SerializedNode): ElementFix | null {
+  const data = parseContrastData(node);
+  if (!data?.fgColor || !data?.bgColor) return null;
+
+  const { fgColor, bgColor, contrastRatio: ratio, requiredRatio } = data;
+
+  // Safely convert to number and format
+  const currentRatioNum = typeof ratio === 'number' ? ratio : parseFloat(String(ratio || ''));
+  const requiredRatioNum = typeof requiredRatio === 'number' ? requiredRatio : parseFloat(String(requiredRatio || ''));
+
+  const currentRatio = !isNaN(currentRatioNum) ? currentRatioNum.toFixed(2) : 'unknown';
+  const required = !isNaN(requiredRatioNum) ? requiredRatioNum : 4.5;
+
+  // Use real color math to suggest a corrected foreground color
+  try {
+    const fgRgb = parseColor(fgColor);
+    const bgRgb = parseColor(bgColor);
+    const correctedHex = suggestFix(fgRgb, bgRgb, required);
+
+    return {
+      originalHtml: node.html,
+      fixedHtml: node.html,
+      explanation: `Text color ${fgColor} on background ${bgColor} has insufficient contrast (${currentRatio}:1, need ${required}:1). Suggested foreground: ${correctedHex}`,
+      autoFixable: true,
+    };
+  } catch {
+    // Fall back to non-auto-fixable if color parsing fails
+    return {
+      originalHtml: node.html,
+      fixedHtml: node.html,
+      explanation: `Text color ${fgColor} on background ${bgColor} has insufficient contrast (${currentRatio}:1, need ${required}:1). Adjust the foreground color to meet the required ratio.`,
+      autoFixable: false,
+    };
+  }
+}
+
+/**
+ * Generate a specific fix for an image-alt violation
+ */
+function generateAltTextFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Extract src to help generate meaningful alt text suggestion
+  const srcMatch = html.match(/src=["']([^"']+)["']/);
+  const src = srcMatch?.[1] || '';
+  const filename = src.split('/').pop()?.replace(/\.[^.]+$/, '') || 'image';
+
+  // Generate suggested alt text based on filename
+  const suggestedAlt = filename
+    .replace(/[-_]/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase();
+
+  // Create fixed HTML
+  let fixedHtml = html;
+  if (html.includes('alt=""') || html.includes("alt=''")) {
+    // Decorative image marked correctly, but flagged - might need real alt
+    fixedHtml = html.replace(/alt=["'][^"']*["']/, `alt="${suggestedAlt}"`);
+  } else if (html.includes('alt=')) {
+    // Has alt but it's not descriptive enough
+    fixedHtml = html.replace(/alt=["'][^"']*["']/, `alt="${suggestedAlt}"`);
+  } else {
+    // Missing alt entirely
+    fixedHtml = html.replace(/<img/, `<img alt="${suggestedAlt}"`);
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation: `Add descriptive alt text that describes the image content or purpose. If decorative, use alt="".`,
+    autoFixable: true,
+  };
+}
+
+/**
+ * Generate a specific fix for a button-name violation
+ */
+function generateButtonNameFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Check if it's an icon-only button
+  const hasOnlySvg = /<button[^>]*>[\s]*<svg[^>]*>[\s\S]*<\/svg>[\s]*<\/button>/i.test(html);
+  const hasOnlyImg = /<button[^>]*>[\s]*<img[^>]*\/?>\s*<\/button>/i.test(html);
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (hasOnlySvg || hasOnlyImg) {
+    // Add aria-label for icon buttons
+    fixedHtml = html.replace(/<button/, '<button aria-label="[describe action]"');
+    explanation = 'Add aria-label to describe the button\'s action for screen reader users.';
+  } else {
+    // Add visible text content
+    fixedHtml = html.replace(/<\/button>/, '[Button text]</button>');
+    explanation = 'Add visible text content or aria-label that describes the button\'s purpose.';
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false, // Requires human decision on button purpose
+  };
+}
+
+/**
+ * Generate a specific fix for a link-name violation
+ */
+function generateLinkNameFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Check common patterns
+  const hasOnlySvg = /<a[^>]*>[\s]*<svg[^>]*>[\s\S]*<\/svg>[\s]*<\/a>/i.test(html);
+  const hasOnlyImg = /<a[^>]*>[\s]*<img[^>]*\/?>\s*<\/a>/i.test(html);
+  const isEmpty = /<a[^>]*>\s*<\/a>/i.test(html);
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (hasOnlySvg || hasOnlyImg) {
+    fixedHtml = html.replace(/<a/, '<a aria-label="[describe destination]"');
+    explanation = 'Add aria-label to describe where the link goes.';
+  } else if (isEmpty) {
+    fixedHtml = html.replace(/<\/a>/, '[Link text]</a>');
+    explanation = 'Add descriptive text content that indicates the link\'s destination.';
+  } else {
+    explanation = 'Ensure link text is descriptive. Avoid generic text like "click here" or "read more".';
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false,
+  };
+}
+
+/**
+ * Generate a specific fix for a label violation
+ */
+function generateLabelFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Extract input type and any existing identifiers
+  const typeMatch = html.match(/type=["']([^"']+)["']/);
+  const type = typeMatch?.[1] || 'text';
+  const idMatch = html.match(/id=["']([^"']+)["']/);
+  const id = idMatch?.[1];
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (id) {
+    // Has ID, suggest adding label element
+    const labelText = type.charAt(0).toUpperCase() + type.slice(1);
+    explanation = `Add a <label for="${id}">${labelText}</label> element before this input.`;
+  } else {
+    // No ID, add one and suggest label
+    const suggestedId = `input-${type}-${Date.now()}`;
+    fixedHtml = html.replace(/<input/, `<input id="${suggestedId}"`);
+    explanation = `Add an id attribute and associate with a label: <label for="${suggestedId}">Label text</label>`;
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false,
+  };
+}
+
+/**
+ * Fix generator registry
+ */
+type FixGenerator = (node: SerializedNode) => ElementFix | null;
+
+const FIX_GENERATORS: Record<string, FixGenerator> = {
+  'color-contrast': generateContrastFix,
+  'image-alt': generateAltTextFix,
+  'button-name': generateButtonNameFix,
+  'link-name': generateLinkNameFix,
+  'label': generateLabelFix,
+};
+
+/**
+ * Generate a specific fix for a violation node
+ */
+export function generateElementFix(ruleId: string, node: SerializedNode): ElementFix | null {
+  const generator = FIX_GENERATORS[ruleId];
+  if (!generator) return null;
+  return generator(node);
+}
+
+/**
+ * Get impact description for UI display
+ */
+export function getImpactDescription(impact: ImpactValue | null): string {
+  switch (impact) {
+    case 'critical':
+      return 'Critical issues completely block access for some users';
+    case 'serious':
+      return 'Serious issues make content very difficult to access';
+    case 'moderate':
+      return 'Moderate issues cause some difficulty for users';
+    case 'minor':
+      return 'Minor issues may cause slight inconvenience';
+    default:
+      return 'Impact level not determined';
+  }
+}
+
+/**
+ * Get impact styling for inline styles and Badge variant mapping
+ */
+export function getImpactColorClass(impact: ImpactValue | null): {
+  variant: 'error' | 'warning' | 'info' | 'default';
+  color: string;
+  bg: string;
+  text: string;
+  border: string;
+  borderLeft: string;
+} {
+  switch (impact) {
+    case 'critical':
+      return {
+        variant: 'error',
+        color: 'var(--color-danger)',
+        bg: 'var(--color-danger-bg)',
+        text: 'var(--color-danger)',
+        border: 'var(--color-danger)',
+        borderLeft: 'var(--color-danger)',
+      };
+    case 'serious':
+      return {
+        variant: 'error',
+        color: 'var(--color-danger)',
+        bg: 'var(--color-danger-bg)',
+        text: 'var(--color-danger)',
+        border: 'var(--color-danger)',
+        borderLeft: 'var(--color-danger)',
+      };
+    case 'moderate':
+      return {
+        variant: 'warning',
+        color: 'var(--color-warning)',
+        bg: 'var(--color-warning-bg)',
+        text: 'var(--color-warning)',
+        border: 'var(--color-warning)',
+        borderLeft: 'var(--color-warning)',
+      };
+    case 'minor':
+    default:
+      return {
+        variant: 'info',
+        color: 'var(--color-info)',
+        bg: 'var(--color-info-bg)',
+        text: 'var(--color-info)',
+        border: 'var(--color-info)',
+        borderLeft: 'var(--color-info)',
+      };
+  }
+}
+
+/**
+ * Extract WCAG tags from a violation's tags array
+ */
+export function extractWcagTags(tags: string[]): string[] {
+  return tags.filter(tag => tag.startsWith('wcag'));
+}
+
+/**
+ * Get readable WCAG criterion from tag (e.g., 'wcag143' -> '1.4.3')
+ */
+export function parseWcagTag(tag: string): string | null {
+  const match = tag.match(/wcag(\d)(\d)(\d)/);
+  if (!match) return null;
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}