feat(sidebar): implement accessibility audit and reorganize handoff tools

- Add basic-accessibility plugin with WCAG contrast scanning and interactive fixes
- Implement one-click copy functionality in basic-styleguide
- Reorder sidebar to prioritize auditing tools
- Add specialized greenish styling for audit-related accordions
- Refine typography token readability in Style Guide
- Resolve TypeScript lints and global scope declarations

Author: buffos

CHANGELOG.md

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file. We will log
 - **Custom HTML Sandbox**: Added a new sandbox plugin allowing users to test their current theme against custom markup with real-time feedback.
 - **Theme Presets (Personas)**: Introduced a library of "One-Click Personas" (Midnight Pro, Cyberpunk, Corporate Clean, Minimalist) for rapid theme experimentation.
 - **Dev Handoff: Copy to Clipboard**: Added one-click copy functionality to the Style Guide, allowing users to instantly copy design tokens as CSS variables.
+- **Accessibility Master Audit**: Implemented a dedicated audit preview module that scans for WCAG contrast violations across all semantic color pairs and provides one-click "Nudge" fixes.
 
 ### Changed
 

src/app/preview-registry.ts

@@ -1,4 +1,5 @@
 import type { ThemeConfig } from '../compiler/types';
+import { accessibilityPreviewModule } from '../plugins/basic-accessibility';
 import { alertPreviewModule } from '../plugins/basic-alert';
 import { buttonsPreviewModule } from '../plugins/basic-buttons';
 import { cardPreviewModule } from '../plugins/basic-card';
@@ -27,6 +28,7 @@ export type PreviewModule = {
 export const previewModules = [
   sandboxPreviewModule,
   styleguidePreviewModule,
+  accessibilityPreviewModule,
   layoutPreviewModule,
   dashboardPreviewModule,
   colorsPreviewModule,

src/app/ui.ts

@@ -1,3 +1,4 @@
+import { accessibilityControlModule } from '../plugins/basic-accessibility';
 import { alertControlModule } from '../plugins/basic-alert';
 import { buttonsControlModule } from '../plugins/basic-buttons';
 import { cardControlModule } from '../plugins/basic-card';
@@ -21,11 +22,12 @@ import type { ControlsRegistry } from './registry';
 
 // here we will place all controls we will build
 export const controlsRegistry: ControlsRegistry = {
+  sandbox: sandboxControlModule,
+  accessibility: accessibilityControlModule,
+  styleguide: styleguideControlModule,
   name: themeNameControlModule,
   presets: presetsControlModule,
-  sandbox: sandboxControlModule,
   layout: layoutControlModule,
-  styleguide: styleguideControlModule,
   colors: colorsControlModule,
   typography: typographyControlModule,
   surface: surfaceControlModule,

src/main.ts

@@ -4,6 +4,7 @@ import { createPreview } from './app/preview';
 import { getConfig, subscribe, updateConfig, undo, redo, subscribeHistory } from './app/state';
 import { controlsRegistry } from './app/ui';
 import type { ThemeMode } from './compiler/types';
+import { nudgeContrast, generateScale } from './utils/colors';
 
 const root = document.querySelector<HTMLDivElement>('#app');
 
@@ -86,14 +87,42 @@ const controlApi = {
   subscribe,
   setActivePreview: (ids: string[]) => preview.setActive(ids),
 };
+
+declare global {
+  var auditFix: (key: string, baseBg: string, targetFg: string) => void;
+}
+
+// Global Accessibility Fixer for Preview Modules
+globalThis.auditFix = (key: string, baseBg: string, targetFg: string) => {
+  const fixed = nudgeContrast(baseBg, targetFg);
+  updateConfig(cfg => {
+    const next = { ...cfg };
+    if (!next.colors) return next;
+    
+    // If the key is a semantic scale, regenerate it
+    if (key === 'primary') next.colors.primary = generateScale(fixed);
+    else if (key === 'secondary') next.colors.secondary = generateScale(fixed);
+    else if (key === 'tertiary') next.colors.tertiary = generateScale(fixed);
+    else if (key === 'danger') next.colors.danger = generateScale(fixed);
+    else if (key === 'success') next.colors.success = generateScale(fixed);
+    else if (key === 'warning') next.colors.warning = generateScale(fixed);
+    else if (key === 'neutral-900') next.colors.neutral = { ...next.colors.neutral, 900: fixed };
+    else if (key === 'on-primary') next.colors.primary = generateScale(fixed); // Nudge background to fix on-color
+    
+    return next;
+  });
+};
+
 const controlCleanups: (() => void)[] = [];
 const openIds = new Set<string>();
 const accordions: { details: HTMLDetailsElement; id: string }[] = [];
 
 // Build accordion per control module (single-open behavior)
 Object.values(controlsRegistry).forEach((module, index) => {
   const details = document.createElement('details');
-  details.className = 'control-accordion';
+  const isAudit = ['sandbox', 'accessibility', 'styleguide'].includes(module.id);
+  details.className = isAudit ? 'control-accordion audit-accordion' : 'control-accordion';
+  
   if (index === 0) details.open = true;
   const summary = document.createElement('summary');
   summary.textContent = module.title;

src/plugins/basic-accessibility/index.ts

@@ -0,0 +1,129 @@
+import type { PreviewModule } from '../../app/preview-registry';
+import type { ControlModule } from '../../app/registry';
+import type { ThemeConfig } from '../../compiler/types';
+import { 
+  getContrastRatio, 
+  getWCAGLevel, 
+} from '../../utils/colors';
+
+export const accessibilityControlModule: ControlModule = {
+  id: 'accessibility',
+  title: 'Accessibility Audit',
+  mount: (container) => {
+    container.innerHTML = `
+      <p class="controls-placeholder">
+        The Master Audit scans all semantic color pairs and foundation tokens to ensure WCAG compliance.
+      </p>
+      <div style="padding: 1rem; background: var(--surface-bg); border-radius: 8px; border: 1px solid rgba(128,128,128,0.1); font-size: 11px; opacity: 0.8;">
+        Use the live preview report to identify and fix contrast failures across your design system.
+      </div>
+    `;
+  }
+};
+
+type AuditResult = {
+  key: string;
+  name: string;
+  fg: string;
+  bg: string;
+  ratio: number;
+  level: string;
+  pass: boolean;
+};
+
+const renderAuditRow = (p: AuditResult) => {
+  const statusColor = p.pass ? 'var(--color-success-500)' : 'var(--color-danger-500)';
+  const onStatusColor = p.pass ? 'var(--on-success)' : 'var(--on-danger)';
+  
+  return `
+    <div style="display: grid; grid-template-columns: 2fr 1.5fr 1fr 1fr; align-items: center; gap: 1rem; padding: 1rem; background: var(--surface-card); border-radius: 8px; border: 1px solid ${p.pass ? 'rgba(128,128,128,0.1)' : 'var(--color-danger-500)'};">
+      <div>
+        <div style="font-size: 12px; font-weight: 800;">${p.name}</div>
+        <div style="font-size: 10px; opacity: 0.6; font-family: monospace;">${p.fg} on ${p.bg}</div>
+      </div>
+      
+      <div style="display: flex; align-items: center; gap: 8px;">
+        <div style="width: 24px; height: 24px; border-radius: 4px; border: 1px solid rgba(128,128,128,0.2); background: ${p.bg}; position: relative; display: flex; align-items: center; justify-content: center;">
+          <span style="color: ${p.fg}; font-size: 14px; font-weight: 900;">A</span>
+        </div>
+        <span style="font-size: 11px; font-weight: 700;">${p.ratio.toFixed(2)}:1</span>
+      </div>
+
+      <div>
+        <span style="font-size: 10px; font-weight: 800; padding: 2px 8px; border-radius: 4px; background: ${statusColor}; color: ${onStatusColor};">
+          ${p.level}
+        </span>
+      </div>
+
+      <div style="text-align: right;">
+        ${p.pass ? '<span style="color: var(--color-success-500); font-size: 12px;">✔ Pass</span>' : `
+          <button onclick="window.parent.auditFix('${p.key}', '${p.bg}', '${p.fg}')" 
+                  style="font-size: 10px; padding: 4px 8px; border-radius: 4px; background: var(--color-primary-500); color: var(--on-primary); border: none; cursor: pointer; font-weight: 700;">
+            Nudge Fix
+          </button>
+        `}
+      </div>
+    </div>
+  `;
+};
+
+export const accessibilityPreviewModule: PreviewModule = {
+  id: 'accessibility',
+  title: 'Accessibility Master Audit',
+  render: (config: ThemeConfig) => {
+    const colors = config.colors;
+    if (!colors) return '<p>No color configuration found.</p>';
+
+    const n50 = colors.neutral?.[50] ?? '#fff';
+    const n900 = colors.neutral?.[900] ?? '#000';
+
+    const getOn = (bg: string) => {
+        const r50 = getContrastRatio(bg, n50);
+        const r900 = getContrastRatio(bg, n900);
+        return r900 >= r50 ? n900 : n50;
+    };
+
+    const auditPair = (key: string, name: string, fg: string, bg: string): AuditResult => {
+      const ratio = getContrastRatio(fg, bg);
+      const level = getWCAGLevel(ratio);
+      return { key, name, fg, bg, ratio, level, pass: level !== 'Fail' };
+    };
+
+    const pairs: AuditResult[] = [
+      auditPair('primary', 'Primary vs Surface', colors.primary?.[500] ?? '', n50),
+      auditPair('on-primary', 'Primary vs On-Primary', colors.primary?.[500] ?? '', getOn(colors.primary?.[500] ?? '')),
+      auditPair('neutral-900', 'Text vs Surface', n900, n50), // Check text color vs background
+      auditPair('success', 'Success vs On-Success', colors.success?.[500] ?? '', getOn(colors.success?.[500] ?? '')),
+      auditPair('danger', 'Danger vs On-Danger', colors.danger?.[500] ?? '', getOn(colors.danger?.[500] ?? '')),
+      auditPair('warning', 'Warning vs On-Warning', colors.warning?.[500] ?? '', getOn(colors.warning?.[500] ?? '')),
+    ];
+
+    if (colors.secondary) {
+        pairs.push(auditPair('secondary', 'Secondary vs Surface', colors.secondary[500], n50));
+    }
+    if (colors.tertiary) {
+        pairs.push(auditPair('tertiary', 'Tertiary vs Surface', colors.tertiary[500], n50));
+    }
+
+    const score = Math.round((pairs.filter(p => p.pass).length / pairs.length) * 100);
+    let scoreColor = 'var(--color-danger-500)';
+    if (score === 100) scoreColor = 'var(--color-success-500)';
+    else if (score > 70) scoreColor = 'var(--color-warning-500)';
+
+    return `
+      <div style="color: var(--on-background); font-family: var(--font-family, sans-serif);">
+        <div style="display: flex; align-items: center; justify-content: space-between; margin-bottom: 2rem; padding: 1.5rem; background: var(--surface-card); border-radius: 12px; border: 1px solid rgba(128,128,128,0.1);">
+          <div>
+            <h3 style="margin: 0; font-size: 18px;">Theme Health Score</h3>
+            <p style="margin: 4px 0 0 0; font-size: 12px; opacity: 0.6;">Weighted audit of semantic contrast pairs.</p>
+          </div>
+          <div style="font-size: 32px; font-weight: 800; color: ${scoreColor}">${score}%</div>
+        </div>
+
+        <div style="display: grid; gap: 12px;">
+          ${pairs.map(p => renderAuditRow(p)).join('')}
+        </div>
+      </div>
+    `;
+  }
+};

src/style.css

@@ -127,6 +127,19 @@ body {
   margin-top: 10px;
 }
 
+.control-accordion.audit-accordion {
+  border-color: #1e3a2f;
+  background: #0a1f16;
+}
+
+.control-accordion.audit-accordion > summary {
+  color: #a7f3d0;
+}
+
+.control-accordion.audit-accordion > summary::before {
+  border-color: #34d399;
+}
+
 .control-accordion > summary {
   position: relative;
   list-style: none;