From 82e90ec10df8b7c93410eef5d0f9f51fdf2cf89d Mon Sep 17 00:00:00 2001
From: Shannon Lockett <155769623+shazzar00ni@users.noreply.github.com>
Date: Thu, 30 Apr 2026 20:40:52 +0800
Subject: [PATCH 1/5] docs: add KNOWLEDGE.md with codebase patterns and
 conventions

---
 KNOWLEDGE.md | 233 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 233 insertions(+)
 create mode 100644 KNOWLEDGE.md

diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
new file mode 100644
index 00000000..8ce410fc
--- /dev/null
+++ b/KNOWLEDGE.md
@@ -0,0 +1,233 @@
+# Knowledge: DocuGen Patterns & Conventions
+
+This document captures architectural decisions, patterns, and conventions that are implemented in the codebase but not formally documented elsewhere.
+
+---
+
+## 1. Centralized Content Management
+
+All site copy lives in a single file: **`src/data/content.ts`**
+
+- Components import content from this central source rather than containing inline text
+- Export naming convention: uppercase constants (`SITE`, `NAV_LINKS`, `HERO_COPY`, `FEATURES`, `FAQS`, etc.)
+- Content is organized by feature/section
+
+```typescript
+// Example structure
+export const SITE = { name: 'DocuGen', tagline: '...', ... };
+export const HERO_COPY = { headline: '...', subheadline: '...', ... };
+export const FEATURES = [{ icon: '...', title: '...', ... }, ...];
+export const FAQS = [{ question: '...', answer: '...', ... }];
+```
+
+**Rationale:** Enables copy updates without touching component logic. Supports i18n migration.
+
+---
+
+## 2. CSS Class Utility (`cn()`)
+
+**Location:** `src/lib/utils.ts`
+
+```typescript
+cn(...classes: (string | undefined | null | false)[]): string
+```
+
+Filters falsy values and joins class names with spaces.
+
+```tsx
+<button className={cn('base-class', isActive && 'active-class', className)}>
+```
+
+**Used throughout:** All components use this pattern for conditional styling.
+
+---
+
+## 3. Lazy Loading Strategy
+
+**Location:** `src/App.tsx`
+
+- Page-critical sections use static imports: `Hero`, `HowItWorks`, `FAQ`, `Navbar`, `Footer`
+- Heavy sections are lazy-loaded: `Features`, `Testimonials`, `Preview`, `Pricing`, `Newsletter`
+
+```typescript
+const Features = lazy(() =>
+  import('./components/Features').then(module => ({ default: module.Features }))
+);
+```
+
+- Each lazy component wrapped in `<Suspense fallback={<Loading />} />`
+- Custom `Loading` spinner component for consistent loading UI
+
+**Rationale:** Improves initial bundle load time. Critical path content renders immediately.
+
+---
+
+## 4. UI Component Library
+
+**Location:** `src/components/ui/`
+
+### Button
+
+- Variants: `primary` (teal), `secondary` (dark), `ghost` (text)
+- Sizes: `sm`, `md`, `lg`
+- Props: `children`, `variant?`, `size?`, `className?`, `onClick?`, `type?`
+
+### Input
+
+- Dark theme styling with teal focus ring
+- Supports `text` and `email` types
+- Props: `placeholder?`, `type?`, `className?`, `disabled?`, `value?`, `onChange?`, `onBlur?`
+- Supports all standard HTML input attributes via spread
+
+### Container
+
+- Responsive max-width wrapper (`max-w-7xl`)
+- Horizontal padding: `px-4 sm:px-6 lg:px-8`
+- Props: `children`, `className?`
+
+### Skeleton
+
+- Base component with variants: `text`, `circular`, `rectangular`
+- Pre-built composite components:
+  - `SkeletonCard` - user card with avatar
+  - `SkeletonButton` - standard button dimensions
+  - `SkeletonInput` - form input height
+  - `SkeletonFeature` - icon + title + description
+  - `SkeletonTestimonial` - quote + author info
+
+---
+
+## 5. Theme System Architecture
+
+**Location:** `src/lib/ThemeContext.tsx`
+
+### Components
+
+- `ThemeProvider` - wraps app, manages state
+- `useTheme()` - hook for components (throws if used outside provider)
+- Types: `Theme = 'dark' | 'light'`
+
+### Behavior
+
+- Initial theme from `localStorage` key `docugen-theme`, fallback to `prefers-color-scheme`
+- Tailwind dark mode via `document.documentElement.classList.add('dark')` / `remove('dark')`
+- Theme persistence wrapped in try-catch (non-critical)
+
+```typescript
+// In components
+const { theme, toggleTheme } = useTheme();
+```
+
+---
+
+## 6. Testing Patterns
+
+### Test Location
+
+- Tests co-located: `Component.test.tsx` next to `Component.tsx`
+- Glob pattern: `src/**/*.test.{ts,tsx}`
+
+### Test Setup (`src/test/setup.ts`)
+
+- Global mocks:
+  - `IntersectionObserver` - stub implementation
+  - `localStorage` - mocked with `vi.fn()` for `getItem`, `setItem`, `clear`, `removeItem`
+- Reset between tests: `localStorageMock.clear.mockClear()` and `mockReturnValue(null)`
+- Uses `afterEach(cleanup())` from RTL
+
+### Mock Pattern
+
+```typescript
+beforeEach(() => {
+  localStorageMock.clear.mockClear();
+  localStorageMock.getItem.mockClear();
+  localStorageMock.setItem.mockClear();
+  localStorageMock.getItem.mockReturnValue(null);
+});
+```
+
+---
+
+## 7. Analytics Integration
+
+**Location:** `src/components/Analytics.tsx`
+
+- Conditionally injects Plausible analytics
+- Reads domain from `import.meta.env.VITE_PLAUSIBLE_DOMAIN`
+- Script attributes: `defer`, `data-domain`
+- Cleanup: removes script on unmount
+
+```typescript
+// Environment variable
+VITE_PLAUSIBLE_DOMAIN = your - domain.com;
+```
+
+---
+
+## 8. Custom Color Palette
+
+**Location:** `tailwind.config.js`
+
+### Extended Colors
+
+- `light/*` - Light theme palette (50-950)
+- `teal/*` - Brand accent color (50-950)
+- `dark/*` - Dark theme palette (50-950)
+
+### Custom Animations
+
+- `fade-in` - opacity 0→1 over 0.5s
+- `slide-up` - translateY(20px)→0 + fade over 0.6s
+- `slide-up-delayed` - same with 0.2s delay
+
+### Fonts
+
+- Sans: `Inter` + system fallbacks
+- Mono: `JetBrains Mono` + `Fira Code` fallbacks
+
+---
+
+## 9. Environment Variable Conventions
+
+- Uses Vite `import.meta.env` (not `process.env`)
+- Prefix: `VITE_` required for client-side variables
+- Example: `VITE_PLAUSIBLE_DOMAIN`
+
+---
+
+## 10. Error & State Patterns
+
+### ErrorBoundary
+
+- Class component using `getDerivedStateFromError` + `componentDidCatch`
+- Console logs errors with component stack
+- Supports custom `fallback` prop
+- Default fallback includes retry button
+
+### Accordion (FAQ pattern)
+
+- Single-item-open pattern (`openIndex: number | null`)
+- Toggle handler: `setOpenIndex(prev === index ? null : index)`
+- Animations via Framer Motion `AnimatePresence` + `height: auto`
+
+---
+
+## 11. Accessibility Patterns
+
+- `aria-expanded` on collapsible buttons
+- `aria-label` on icon-only buttons
+- `role="dialog"` + `aria-label` + `aria-describedby` on modals
+- `aria-invalid` on form inputs
+- Focus ring styles on all interactive elements
+
+---
+
+## 12. Dev Server
+
+- Vite dev server runs on **port 3000** (configured in `vite.config.ts`)
+- Preview command serves production build on same port
+- E2E tests target `http://localhost:5173` (Playwright default)
+
+---
+
+_Last updated: 2026-04-24_

From 249a38caf53e3de1896d23eae1fae063d6c8b29b Mon Sep 17 00:00:00 2001
From: Shannon Lockett <shazzarooni@proton.me>
Date: Fri, 1 May 2026 00:36:17 +0800
Subject: [PATCH 2/5] Update KNOWLEDGE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 KNOWLEDGE.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index 8ce410fc..86d86d11 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -6,11 +6,12 @@ This document captures architectural decisions, patterns, and conventions that a
 
 ## 1. Centralized Content Management
 
-All site copy lives in a single file: **`src/data/content.ts`**
+Most marketing copy lives in a single file: **`src/data/content.ts`**
 
-- Components import content from this central source rather than containing inline text
+- Components generally import content from this central source rather than containing inline text
+- Known exceptions currently include inline copy in `src/components/Preview.tsx` and default props/docs in `src/components/ShareButtons.tsx`
 - Export naming convention: uppercase constants (`SITE`, `NAV_LINKS`, `HERO_COPY`, `FEATURES`, `FAQS`, etc.)
-- Content is organized by feature/section
+- Content in `src/data/content.ts` is organized by feature/section
 
 ```typescript
 // Example structure

From 05f858d829e9e9cef7ba0cdbba4044c9e46b6815 Mon Sep 17 00:00:00 2001
From: Shannon Lockett <155769623+shazzar00ni@users.noreply.github.com>
Date: Fri, 1 May 2026 00:39:05 +0800
Subject: [PATCH 3/5] docs: fix KNOWLEDGE.md entries to match actual code

---
 KNOWLEDGE.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index 86d86d11..6d293e7d 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -100,7 +100,7 @@ const Features = lazy(() =>
 
 ## 5. Theme System Architecture
 
-**Location:** `src/lib/ThemeContext.tsx`
+**Locations:** `src/lib/ThemeContext.tsx` (provider), `src/lib/useTheme.ts` (hook)
 
 ### Components
 
@@ -134,7 +134,7 @@ const { theme, toggleTheme } = useTheme();
   - `IntersectionObserver` - stub implementation
   - `localStorage` - mocked with `vi.fn()` for `getItem`, `setItem`, `clear`, `removeItem`
 - Reset between tests: `localStorageMock.clear.mockClear()` and `mockReturnValue(null)`
-- Uses `afterEach(cleanup())` from RTL
+- Uses `afterEach(() => { cleanup(); })` from RTL (wrapped in callback, not passed directly)
 
 ### Mock Pattern
 
@@ -159,8 +159,8 @@ beforeEach(() => {
 - Cleanup: removes script on unmount
 
 ```typescript
-// Environment variable
-VITE_PLAUSIBLE_DOMAIN = your - domain.com;
+// Environment variable (.env file)
+VITE_PLAUSIBLE_DOMAIN=your-domain.com
 ```
 
 ---
@@ -223,11 +223,14 @@ VITE_PLAUSIBLE_DOMAIN = your - domain.com;
 
 ---
 
-## 12. Dev Server
+## 12. Dev Server & E2E Port Conflict
 
 - Vite dev server runs on **port 3000** (configured in `vite.config.ts`)
-- Preview command serves production build on same port
-- E2E tests target `http://localhost:5173` (Playwright default)
+- Preview command serves production build on same port (3000)
+- **Pre-existing conflict:** Playwright config (`playwright.config.ts`) expects port 5173, but Vite starts on port 3000
+- E2E tests would fail waiting for port 5173 unless resolved by either:
+  - Changing Vite port to 5173 in `vite.config.ts`, OR
+  - Updating Playwright config to use port 3000
 
 ---
 

From 22ad510ac2f354f8c935d1f74bdcd99ce6178a81 Mon Sep 17 00:00:00 2001
From: Shannon Lockett <shazzarooni@proton.me>
Date: Sat, 2 May 2026 08:06:18 +0800
Subject: [PATCH 4/5] Update KNOWLEDGE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 KNOWLEDGE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index 6d293e7d..ede19937 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -208,7 +208,7 @@ VITE_PLAUSIBLE_DOMAIN=your-domain.com
 ### Accordion (FAQ pattern)
 
 - Single-item-open pattern (`openIndex: number | null`)
-- Toggle handler: `setOpenIndex(prev === index ? null : index)`
+- Toggle handler: `setOpenIndex(prev => (prev === index ? null : index))`
 - Animations via Framer Motion `AnimatePresence` + `height: auto`
 
 ---

From 4def0ce71c4ee8d6c3ce6ac69fddd01e1bed9155 Mon Sep 17 00:00:00 2001
From: Shannon Lockett <shazzarooni@proton.me>
Date: Mon, 4 May 2026 17:50:58 +0800
Subject: [PATCH 5/5] Update KNOWLEDGE.md

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 KNOWLEDGE.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/KNOWLEDGE.md b/KNOWLEDGE.md
index ede19937..cb33db89 100644
--- a/KNOWLEDGE.md
+++ b/KNOWLEDGE.md
@@ -227,10 +227,8 @@ VITE_PLAUSIBLE_DOMAIN=your-domain.com
 
 - Vite dev server runs on **port 3000** (configured in `vite.config.ts`)
 - Preview command serves production build on same port (3000)
-- **Pre-existing conflict:** Playwright config (`playwright.config.ts`) expects port 5173, but Vite starts on port 3000
-- E2E tests would fail waiting for port 5173 unless resolved by either:
-  - Changing Vite port to 5173 in `vite.config.ts`, OR
-  - Updating Playwright config to use port 3000
+- **Resolved:** Playwright config (`playwright.config.ts`) was updated to use port 3000, matching the Vite dev server
+- Both `baseURL` and `webServer.port` in Playwright config are set to 3000
 
 ---