Merge pull request #2 from JustAGhosT/tembo/docs-project-context-design-system

Document Design System

Author: JustAGhosT

.editorconfig

@@ -0,0 +1,21 @@
+# EditorConfig - https://editorconfig.org
+# Helps maintain consistent coding styles across editors
+
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,tsx,js,jsx}]
+indent_size = 2
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
         run: npm ci
 
       - name: Run tests
-        run: npm test || true
+        run: npm test
 
   lint:
     name: Lint
@@ -67,7 +67,7 @@ jobs:
         run: npm ci
 
       - name: Run ESLint
-        run: npm run lint || true
+        run: npm run lint
 
   deploy:
     name: Deploy to Azure Static Web Apps

.storybook/main.ts

@@ -0,0 +1,37 @@
+import type { StorybookConfig } from '@storybook/nextjs';
+
+/**
+ * Storybook Configuration
+ * @audit DEBT-13 - Add Storybook for component documentation
+ *
+ * This configuration sets up Storybook for the Next.js App Router project.
+ * Stories are located alongside components in the app/components directory.
+ */
+const config: StorybookConfig = {
+  stories: [
+    '../app/components/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+  ],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+  ],
+  framework: {
+    name: '@storybook/nextjs',
+    options: {
+      // Next.js App Router configuration
+      builder: {
+        useSWC: true,
+      },
+    },
+  },
+  staticDirs: ['../public'],
+  docs: {
+    autodocs: 'tag',
+  },
+  typescript: {
+    reactDocgen: 'react-docgen-typescript',
+  },
+};
+
+export default config;

.storybook/preview.tsx

@@ -0,0 +1,61 @@
+import type { Preview } from '@storybook/react';
+import '../app/globals.css';
+
+/**
+ * Storybook Preview Configuration
+ * @audit DEBT-13 - Add Storybook for component documentation
+ *
+ * This file configures the preview iframe where stories are rendered.
+ * It imports global CSS and sets up decorators for theme support.
+ */
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        {
+          name: 'light',
+          value: '#f8fafc',
+        },
+        {
+          name: 'dark',
+          value: '#0f172a',
+        },
+      ],
+    },
+    layout: 'centered',
+  },
+  globalTypes: {
+    theme: {
+      description: 'Global theme for components',
+      defaultValue: 'light',
+      toolbar: {
+        title: 'Theme',
+        icon: 'circlehollow',
+        items: ['light', 'dark'],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [
+    (Story, context) => {
+      const theme = context.globals.theme;
+      // Apply theme class to story container
+      return (
+        <div className={theme === 'dark' ? 'dark' : ''}>
+          <div className="p-4 bg-slate-50 dark:bg-slate-900">
+            <Story />
+          </div>
+        </div>
+      );
+    },
+  ],
+};
+
+export default preview;

README.md

@@ -8,15 +8,17 @@ This is the marketing website for CodeFlow AI, providing information about the p
 
 ## Technology Stack
 
-- **Next.js**: React framework
-- **TypeScript**: Type-safe JavaScript
-- **Tailwind CSS**: Utility-first CSS framework
+- **Framework**: [Next.js 16.x](https://nextjs.org/) with App Router
+- **Language**: [TypeScript](https://www.typescriptlang.org/)
+- **Styling**: [Tailwind CSS 4.x](https://tailwindcss.com/)
+- **Testing**: [Vitest](https://vitest.dev/) + [React Testing Library](https://testing-library.com/react)
+- **Deployment**: [Azure Static Web Apps](https://azure.microsoft.com/services/app-service/static/)
 
 ## Development
 
 ### Prerequisites
 
-- Node.js 18+ 
+- Node.js 18+
 - npm or yarn
 
 ### Getting Started
@@ -35,15 +37,81 @@ npm run build
 npm start
 ```
 
+### Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+**Coverage Thresholds**: 60% for statements, branches, functions, and lines.
+
+### Linting
+
+```bash
+# Run ESLint
+npm run lint
+```
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/` directory:
+
+| Document | Description |
+|----------|-------------|
+| [Project Context](docs/project-context.md) | Business goals, target users, and user journeys |
+| [Design System](docs/design-system.md) | Design tokens, typography, colors, and component inventory |
+| [Architecture Overview](docs/architecture-overview.md) | System architecture, data flow, and deployment pipeline |
+| [Tech Stack](docs/tech-stack.md) | Detailed technology breakdown by layer |
+| [Best Practices Benchmark](docs/best-practices-benchmark.md) | Industry standards and evaluation criteria |
+| [Audit Findings](docs/audit-findings.md) | Code audit results and recommendations |
+| [Technical Debt Registry](docs/technical-debt-registry.md) | Tracked issues, priorities, and resolution status |
+
 ## Deployment
 
 The website is deployed to Azure Static Web Apps. See [`codeflow-infrastructure`](https://github.com/JustAGhosT/codeflow-infrastructure) for deployment infrastructure.
 
+### CI/CD Pipeline
+
+The project uses GitHub Actions for continuous integration:
+
+- **Build**: Compiles the Next.js application
+- **Test**: Runs Vitest test suite (blocking)
+- **Lint**: Runs ESLint checks (blocking)
+- **Deploy**: Deploys to Azure Static Web Apps on push to main
+
+## Contributing
+
+### Code Quality Standards
+
+1. **TypeScript**: All code must be properly typed
+2. **Testing**: New features should include unit tests
+3. **Linting**: Code must pass ESLint without errors
+4. **Accessibility**: Follow WCAG 2.1 AA guidelines
+
+### Commit Message Format
+
+Use semantic commit messages:
+
+```text
+feat: add new feature
+fix: resolve bug
+docs: update documentation
+test: add or update tests
+refactor: code improvements without behavior change
+```
+
 ## Related Repositories
 
 - [`codeflow-engine`](https://github.com/JustAGhosT/codeflow-engine) - Core engine
 - [`codeflow-infrastructure`](https://github.com/JustAGhosT/codeflow-infrastructure) - Production infrastructure
-- [`codeflow-desktop`](https://github.com/JustAGhosT/codeflow-desktop) - Desktop application
+- [`codeflow-desktop`](https://github.com/JustAGhosT/codeflow-desktop) - Desktop application (contains shared design system)
 - [`codeflow-vscode-extension`](https://github.com/JustAGhosT/codeflow-vscode-extension) - VS Code extension
 - [`codeflow-azure-setup`](https://github.com/JustAGhosT/codeflow-azure-setup) - Azure bootstrap scripts
 

app/components/AnimatedBackground.tsx

@@ -1,6 +1,26 @@
 'use client';
 
-import { useEffect, useRef, useState, useCallback } from 'react';
+import { useEffect, useRef, useCallback, useSyncExternalStore } from 'react';
+import { debounce } from '../utils/debounce';
+import { useTheme } from './ThemeProvider';
+
+// Hook for subscribing to reduced motion preference
+function useReducedMotion(): boolean {
+  const subscribe = useCallback((callback: () => void) => {
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    mediaQuery.addEventListener('change', callback);
+    return () => mediaQuery.removeEventListener('change', callback);
+  }, []);
+
+  const getSnapshot = useCallback(() => {
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  }, []);
+
+  // Server-side default: true (safe, no animation)
+  const getServerSnapshot = useCallback(() => true, []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
 
 /**
  * AnimatedBackground - Particle animation background using design tokens
@@ -68,20 +88,15 @@ export default function AnimatedBackground() {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const animationFrameRef = useRef<number | null>(null);
   const particlesRef = useRef<Particle[]>([]);
-  const [prefersReducedMotion, setPrefersReducedMotion] = useState(true); // Default to true (safe)
+  const prefersReducedMotion = useReducedMotion();
+  const { resolvedTheme } = useTheme();
+  // Use ref to track theme in animation loop without causing re-renders
+  const isDarkRef = useRef(resolvedTheme === 'dark');
 
-  // Check initial reduced motion preference on mount
+  // Keep ref in sync with theme context
   useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
-    setPrefersReducedMotion(mediaQuery.matches);
-
-    const handleChange = (e: MediaQueryListEvent) => {
-      setPrefersReducedMotion(e.matches);
-    };
-
-    mediaQuery.addEventListener('change', handleChange);
-    return () => mediaQuery.removeEventListener('change', handleChange);
-  }, []);
+    isDarkRef.current = resolvedTheme === 'dark';
+  }, [resolvedTheme]);
 
   const initParticles = useCallback((width: number, height: number) => {
     particlesRef.current = [];
@@ -140,8 +155,12 @@ export default function AnimatedBackground() {
       initParticles(canvas.width, canvas.height);
     };
 
+    // Debounce resize handler to prevent particle re-initialization thrashing
+    const debouncedResize = debounce(resizeCanvas, 250);
+
     const animate = () => {
-      const isDark = document.documentElement.classList.contains('dark');
+      // Use theme from context (via ref) instead of DOM class inspection
+      const isDark = isDarkRef.current;
 
       ctx.clearRect(0, 0, canvas.width, canvas.height);
 
@@ -155,16 +174,18 @@ export default function AnimatedBackground() {
       animationFrameRef.current = requestAnimationFrame(animate);
     };
 
+    // Initial setup (not debounced)
     resizeCanvas();
     animate();
 
-    window.addEventListener('resize', resizeCanvas);
+    window.addEventListener('resize', debouncedResize);
 
     return () => {
       if (animationFrameRef.current) {
         cancelAnimationFrame(animationFrameRef.current);
       }
-      window.removeEventListener('resize', resizeCanvas);
+      debouncedResize.cancel();
+      window.removeEventListener('resize', debouncedResize);
     };
   }, [prefersReducedMotion, initParticles, drawConnections]);