From f2940ad956b93e156dcf5815f89a4b9c53369887 Mon Sep 17 00:00:00 2001
From: jwinterm <johnwmurphy@gmail.com>
Date: Sat, 17 Jan 2026 10:32:01 -0500
Subject: [PATCH] Add documentation and fix pnpm start command

- Add README.md with tech stack, project structure, and dev setup
- Add TODO_ACCESS.md with Lighthouse audit results and priority fixes
- Add start script to root package.json
- Add start task to turbo.json
---
 README.md      | 174 +++++++++++++++++++++++++++++++++++++++++++++++++
 TODO_ACCESS.md | 127 ++++++++++++++++++++++++++++++++++++
 package.json   |   1 +
 turbo.json     |   4 ++
 4 files changed, 306 insertions(+)
 create mode 100644 README.md
 create mode 100644 TODO_ACCESS.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f94db20
--- /dev/null
+++ b/README.md
@@ -0,0 +1,174 @@
+# Such Software Website
+
+Corporate website for Such Software LLC, a full-service software provider based in Kennett Square, PA.
+
+## Tech Stack
+
+### Core Framework
+- **Next.js 15** - React framework with App Router
+- **React 18** - UI library
+- **TypeScript 5** - Type safety
+
+### Styling & Animation
+- **Tailwind CSS 3** - Utility-first CSS
+- **Framer Motion 11** - Animations and transitions
+- **tailwind-merge** - Conditional class merging
+- **class-variance-authority** - Component variants
+
+### UI Components
+- **Radix UI** - Accessible primitives
+- **Lucide React** - Icon library
+- **react-icons** - Additional icons (FontAwesome, etc.)
+
+### Theming
+- **next-themes 0.4** - Dark/light mode with system preference detection
+
+### Forms & Validation
+- **Zod** - Schema validation
+- **Cloudflare Turnstile** - Bot protection via `@marsidev/react-turnstile`
+
+### Build & Dev Tools
+- **Turborepo** - Monorepo build system
+- **pnpm 9** - Package manager
+- **ESLint** - Linting
+- **Prettier** - Code formatting
+
+## Project Structure
+
+```
+such-software-site/
+├── apps/
+│   └── web/                    # Next.js website
+│       ├── src/
+│       │   ├── app/            # App Router pages
+│       │   │   ├── page.tsx    # Homepage
+│       │   │   ├── services/   # Services page
+│       │   │   ├── about/      # About page
+│       │   │   └── layout.tsx  # Root layout
+│       │   ├── components/
+│       │   │   ├── about/      # About page components
+│       │   │   ├── contact/    # Contact form
+│       │   │   ├── landing/    # Homepage components
+│       │   │   ├── layout/     # Header, Footer, etc.
+│       │   │   └── portfolio/  # Portfolio grid
+│       │   ├── actions/        # Server actions
+│       │   └── lib/            # Utilities
+│       └── public/             # Static assets
+├── packages/
+│   ├── ui/                     # Shared UI components
+│   │   └── src/
+│   │       ├── components/     # Button, Card, etc.
+│   │       ├── procedural/     # Canvas animations (NebulaField, DataGrid)
+│   │       └── lib/            # Utilities (cn)
+│   └── config/                 # Shared TypeScript/ESLint config
+├── turbo.json                  # Turborepo config
+├── pnpm-workspace.yaml         # pnpm workspace config
+└── package.json                # Root package.json
+```
+
+## Development
+
+### Prerequisites
+- Node.js >= 20.0.0
+- pnpm >= 9.0.0
+
+### Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Start production server
+pnpm start
+```
+
+The dev server runs at `http://localhost:3000`.
+
+## Accessibility & Quality
+
+### Current Status
+See [TODO_ACCESS.md](TODO_ACCESS.md) for detailed audit results.
+
+### Lighthouse Scores (Dev Server)
+| Category | Score |
+|----------|-------|
+| Performance | 51 |
+| Accessibility | 95 |
+| SEO | 91 |
+| Best Practices | 73 |
+
+**Note:** Production builds typically score higher.
+
+### Testing Tools
+
+#### Current
+- **Lighthouse** - Performance, accessibility, SEO, best practices
+  ```bash
+  npx lighthouse http://localhost:3000 --view
+  ```
+
+#### Planned
+- **Playwright + axe-core** - Automated accessibility testing
+  ```bash
+  pnpm add -D @playwright/test @axe-core/playwright
+  npx playwright install
+  ```
+
+### Accessibility Features
+- Skip-to-main-content link
+- Semantic HTML5 structure (`<main>`, `<nav>`, `<header>`, `<footer>`)
+- ARIA labels on interactive elements
+- Keyboard navigation support
+- Dark/light mode with system preference
+- Reduced motion support
+
+### Known Issues
+- Color contrast needs improvement in some areas
+- Heading hierarchy has gaps
+- Canvas animations impact performance (NebulaField)
+
+## Key Components
+
+### DynamicBackground
+Homepage animated nebula background using canvas. Theme-aware with reduced motion support.
+
+### Header
+Shared navigation with skip-to-main link, responsive design, and theme toggle.
+
+### ContactForm
+Server action-powered form with Zod validation and Turnstile bot protection.
+
+### FounderSignature
+Bio section with accessibility credentials and competency cards.
+
+## Environment Variables
+
+Create `.env.local` in `apps/web/`:
+
+```env
+# Cloudflare Turnstile (for contact form)
+NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key
+TURNSTILE_SECRET_KEY=your_secret_key
+
+# Contact form email (optional)
+CONTACT_EMAIL=your@email.com
+```
+
+## Deployment
+
+Built for deployment on Vercel or any Node.js hosting platform.
+
+```bash
+pnpm build
+pnpm start
+```
+
+## License
+
+Proprietary - Such Software LLC
diff --git a/TODO_ACCESS.md b/TODO_ACCESS.md
new file mode 100644
index 0000000..8ea91fd
--- /dev/null
+++ b/TODO_ACCESS.md
@@ -0,0 +1,127 @@
+# Accessibility & Performance Audit
+
+## Lighthouse Scores (Dev Server)
+
+| Category | Score | Target |
+|----------|-------|--------|
+| Performance | 51 | 100 |
+| Accessibility | 95 | 100 |
+| SEO | 91 | 100 |
+| Best Practices | 73 | 100 |
+
+**Note:** Dev server scores are typically lower than production. Run `pnpm build && pnpm start` for accurate production scores.
+
+## Critical Issues (Score: 0%)
+
+### Accessibility
+- [ ] **Color contrast** - Background and foreground colors do not have sufficient contrast ratio
+- [ ] **Heading order** - Heading elements are not in sequentially-descending order
+
+### Performance
+- [ ] **Time to Interactive** - Too slow
+- [ ] **Max Potential First Input Delay** - Too high
+- [ ] **Total Blocking Time** - 9% (needs major improvement)
+- [ ] **Largest Contentful Paint** - 12% (needs major improvement)
+- [ ] **Minimize main-thread work** - Too much JS execution
+- [ ] **Reduce JavaScript execution time** - Too slow
+
+### SEO
+- [ ] **Meta description** - Document does not have a meta description (may be dev-only issue)
+
+### Best Practices
+- [ ] **Browser console errors** - Errors logged to console
+- [ ] **Third-party cookies** - Uses third-party cookies
+- [ ] **Missing source maps** - For large first-party JavaScript
+- [ ] **Unminified JavaScript** - (dev server issue)
+
+## Claims Made on Site (founder-signature.tsx)
+- WCAG 2.2 AA Compliance
+- Section 508 & ADA
+- Semantic HTML5 Architecture
+- Playwright A11y Automation
+
+## Current Status
+
+### WCAG 2.2 AA Compliance - 95% but needs fixes
+
+**What's working:**
+- Skip-to-main link in header.tsx
+- Proper `aria-label` on nav element
+- Form fields have proper `<label>` elements with `htmlFor`
+- `aria-describedby` and `aria-invalid` on form inputs
+- `role="alert"` on error messages
+- `role="status"` and `aria-live="polite"` on success/error notifications
+- `sr-only` classes for screen reader text
+- `lang="en"` on `<html>` element
+
+**Gaps to address:**
+- [ ] **Color contrast issues** - Fix low contrast text
+- [ ] **Heading order** - Fix heading hierarchy (likely h2 before h1 somewhere, or skipping levels)
+- [ ] Theme toggle button missing `aria-label` describing current state
+- [ ] Verify focus indicators are visible in both themes (2.4.7 Focus Visible)
+
+### Semantic HTML5 Architecture - Good but heading order issue
+
+- Uses semantic `<main>`, `<header>`, `<nav>`, `<footer>` elements
+- `<address>` element used correctly on About page
+- Form has proper `<label>` elements
+- **Issue:** Heading hierarchy has gaps or wrong order
+
+### Section 508 & ADA - Partial
+
+Section 508 aligns with WCAG 2.0 AA. Needs:
+- [ ] Fix color contrast issues
+- [ ] Fix heading order
+- [ ] Screen reader testing
+- [ ] Keyboard-only navigation testing
+
+### Playwright A11y Automation - NOT SET UP
+
+There is **no Playwright configuration** in this project. No test files exist.
+
+**To implement:**
+```bash
+pnpm add -D @playwright/test @axe-core/playwright
+npx playwright install
+```
+
+### Core Web Vitals / Performance - FAILING
+
+The NebulaField canvas animation is likely the main culprit for:
+- High Total Blocking Time
+- Slow Largest Contentful Paint
+- High main-thread work
+
+**Recommendations:**
+- [ ] Lazy load NebulaField (only render after initial paint)
+- [ ] Reduce animation complexity or frame rate
+- [ ] Consider CSS-only alternative for initial load
+- [ ] Use `will-change` and GPU acceleration properly
+
+### SEO - 91% (minor issues)
+
+- Proper `<title>` and `description` meta tags per page
+- OpenGraph metadata configured
+- Semantic HTML structure
+- **Issue:** Meta description not detected (check if it's rendering correctly)
+
+## Priority Tasks
+
+### P0 - Critical (before claiming compliance)
+1. [ ] Fix color contrast issues
+2. [ ] Fix heading order (find and fix h-level skips)
+3. [ ] Add `aria-label` to ThemeToggle button
+
+### P1 - High (for performance claims)
+4. [ ] Lazy load NebulaField background
+5. [ ] Fix console errors
+6. [ ] Run production build and re-test Lighthouse
+
+### P2 - Medium (for full compliance)
+7. [ ] Set up Playwright with axe-core
+8. [ ] Manual screen reader testing
+9. [ ] Keyboard navigation testing
+
+### P3 - Low (polish)
+10. [ ] Optimize NebulaField animation performance
+11. [ ] Add preloading for critical assets
diff --git a/package.json b/package.json
index 98ae158..e2a1b33 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,7 @@
   "scripts": {
     "build": "turbo run build",
     "dev": "turbo run dev",
+    "start": "turbo run start",
     "lint": "turbo run lint",
     "clean": "turbo run clean && rm -rf node_modules",
     "format": "prettier --write \"**/*.{ts,tsx,md}\""
diff --git a/turbo.json b/turbo.json
index 7b7b2f7..9983fed 100644
--- a/turbo.json
+++ b/turbo.json
@@ -13,6 +13,10 @@
     "dev": {
       "cache": false,
       "persistent": true
+    },
+    "start": {
+      "cache": false,
+      "persistent": true
     }
   }
 }
\ No newline at end of file