@fragments-sdk/cli 0.2.2

package/src/viewer/styles/globals.css

@@ -0,0 +1,355 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ============================================
+ * Fragments Viewer Theme System
+ * ============================================
+ * The viewer shell (sidebar, toolbar, panels) uses these variables.
+ * These are INDEPENDENT from the UI library's --fui-* variables.
+ *
+ * The UI library components are rendered in the preview area which
+ * has its own scoped --fui-* variables (see below).
+ * ============================================ */
+
+/* Light mode (default) */
+:root {
+  --bg-primary: #ffffff;
+  --bg-secondary: #fafafa;
+  --bg-tertiary: #f5f5f5;
+  --bg-elevated: #ffffff;
+  --bg-hover: rgba(0, 0, 0, 0.04);
+  --bg-active: rgba(0, 0, 0, 0.08);
+
+  --text-primary: #171717;
+  --text-secondary: #525252;
+  --text-tertiary: #a3a3a3;
+  --text-muted: #d4d4d4;
+
+  --border: rgba(0, 0, 0, 0.08);
+  --border-subtle: rgba(0, 0, 0, 0.04);
+  --border-strong: rgba(0, 0, 0, 0.12);
+
+  --color-accent: #10a37f;
+  --color-accent-hover: #0d8a6a;
+  --color-accent-subtle: rgba(16, 163, 127, 0.1);
+
+  --color-success: #10a37f;
+  --color-success-bg: rgba(16, 163, 127, 0.1);
+  --color-warning: #f59e0b;
+  --color-warning-bg: rgba(245, 158, 11, 0.1);
+  --color-danger: #ef4444;
+  --color-danger-bg: rgba(239, 68, 68, 0.1);
+  --color-info: #3b82f6;
+  --color-info-bg: rgba(59, 130, 246, 0.1);
+
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.05), 0 2px 4px -2px rgba(0, 0, 0, 0.05);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.05), 0 4px 6px -4px rgba(0, 0, 0, 0.05);
+
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+
+  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-normal: 200ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* Dark mode - applied when .dark class is on html */
+.dark {
+  --bg-primary: #0d0d0d;
+  --bg-secondary: #171717;
+  --bg-tertiary: #1f1f1f;
+  --bg-elevated: #1a1a1a;
+  --bg-hover: rgba(255, 255, 255, 0.04);
+  --bg-active: rgba(255, 255, 255, 0.08);
+
+  --text-primary: #ececec;
+  --text-secondary: #9a9a9a;
+  --text-tertiary: #666666;
+  --text-muted: #404040;
+
+  --border: rgba(255, 255, 255, 0.08);
+  --border-subtle: rgba(255, 255, 255, 0.04);
+  --border-strong: rgba(255, 255, 255, 0.12);
+
+  --color-accent: #10a37f;
+  --color-accent-hover: #1eb894;
+  --color-accent-subtle: rgba(16, 163, 127, 0.15);
+
+  --color-success: #10a37f;
+  --color-success-bg: rgba(16, 163, 127, 0.15);
+  --color-warning: #f59e0b;
+  --color-warning-bg: rgba(245, 158, 11, 0.15);
+  --color-danger: #ef4444;
+  --color-danger-bg: rgba(239, 68, 68, 0.15);
+  --color-info: #60a5fa;
+  --color-info-bg: rgba(96, 165, 250, 0.15);
+
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -2px rgba(0, 0, 0, 0.2);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.4), 0 4px 6px -4px rgba(0, 0, 0, 0.3);
+}
+
+/* ============================================
+ * Base Element Styles
+ * ============================================ */
+
+* {
+  border-color: var(--border);
+}
+
+*::selection {
+  background-color: var(--color-accent-subtle);
+  color: var(--text-primary);
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-feature-settings: "rlig" 1, "calt" 1;
+}
+
+/* ============================================
+ * Scrollbar Styles
+ * ============================================ */
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background-color: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background-color: var(--text-muted);
+  border-radius: 9999px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background-color: var(--text-tertiary);
+}
+
+/* Firefox scrollbar */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--text-muted) transparent;
+}
+
+/* ============================================
+ * Theme-aware Utility Classes
+ * ============================================ */
+
+.bg-primary { background-color: var(--bg-primary); }
+.bg-secondary { background-color: var(--bg-secondary); }
+.bg-tertiary { background-color: var(--bg-tertiary); }
+.bg-elevated { background-color: var(--bg-elevated); }
+
+.text-primary { color: var(--text-primary); }
+.text-secondary { color: var(--text-secondary); }
+.text-tertiary { color: var(--text-tertiary); }
+.text-accent { color: var(--color-accent); }
+
+.border-subtle { border-color: var(--border-subtle); }
+.border-strong { border-color: var(--border-strong); }
+
+/* ============================================
+ * Surface Styles
+ * ============================================ */
+
+.surface {
+  background-color: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+}
+
+.surface-interactive {
+  background-color: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  transition: all var(--transition-fast);
+}
+
+.surface-interactive:hover {
+  border-color: var(--border-strong);
+  box-shadow: var(--shadow-sm);
+}
+
+/* ============================================
+ * Badge Styles
+ * ============================================ */
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 3px 8px;
+  border-radius: var(--radius-sm);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.01em;
+  transition: all var(--transition-fast);
+}
+
+.badge-default {
+  background-color: var(--bg-tertiary);
+  color: var(--text-secondary);
+  border: 1px solid var(--border-subtle);
+}
+
+.badge-success {
+  background-color: var(--color-success-bg);
+  color: var(--color-success);
+}
+
+.badge-warning {
+  background-color: var(--color-warning-bg);
+  color: var(--color-warning);
+}
+
+.badge-danger {
+  background-color: var(--color-danger-bg);
+  color: var(--color-danger);
+}
+
+/* ============================================
+ * Focus Ring
+ * ============================================ */
+
+.focus-ring:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--bg-primary), 0 0 0 4px var(--color-accent);
+}
+
+/* ============================================
+ * Transition Utilities
+ * ============================================ */
+
+.transition-colors {
+  transition: color var(--transition-fast), background-color var(--transition-fast), border-color var(--transition-fast);
+}
+
+.transition-all {
+  transition: all var(--transition-fast);
+}
+
+/* ============================================
+ * Code Styling
+ * ============================================ */
+
+code {
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+  font-size: 0.875em;
+  background-color: var(--bg-tertiary);
+  padding: 2px 6px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-subtle);
+}
+
+pre code {
+  background: none;
+  padding: 0;
+  border: none;
+}
+
+/* ============================================
+ * Table Base Styles
+ * ============================================ */
+
+table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+th {
+  text-align: left;
+  font-weight: 500;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-tertiary);
+}
+
+td {
+  border-top: 1px solid var(--border-subtle);
+}
+
+/* ============================================
+ * Utility Classes
+ * ============================================ */
+
+.divider {
+  height: 1px;
+  background-color: var(--border);
+}
+
+.text-balance {
+  text-wrap: balance;
+}
+
+/* Scroll utilities */
+.scroll-smooth {
+  scroll-behavior: smooth;
+}
+
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}
+
+/* ============================================
+ * Gradient Utilities
+ * ============================================ */
+
+.gradient-fade-b {
+  background: linear-gradient(to bottom, transparent, var(--bg-primary));
+}
+
+.gradient-fade-t {
+  background: linear-gradient(to top, transparent, var(--bg-primary));
+}
+
+/* Subtle glow effect for interactive elements */
+.glow-accent:hover {
+  box-shadow: 0 0 20px rgba(16, 163, 127, 0.15);
+}
+
+/* ============================================
+ * Animations
+ * ============================================ */
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-fadeIn {
+  animation: fadeIn var(--transition-normal) ease-out;
+}
+
+.animate-slideIn {
+  animation: slideIn var(--transition-normal) ease-out;
+}

package/src/viewer/tailwind.config.js

@@ -0,0 +1,37 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    resolve(__dirname, 'index.html'),
+    resolve(__dirname, 'src/**/*.{js,ts,jsx,tsx}'),
+  ],
+  darkMode: 'class',
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: [
+          'Inter',
+          'system-ui',
+          '-apple-system',
+          'BlinkMacSystemFont',
+          'Segoe UI',
+          'Roboto',
+          'sans-serif',
+        ],
+        mono: [
+          'JetBrains Mono',
+          'Fira Code',
+          'Monaco',
+          'Consolas',
+          'Liberation Mono',
+          'monospace',
+        ],
+      },
+    },
+  },
+  plugins: [],
+};

package/src/viewer/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;
+}