diff --git a/doc/COLOR-THEME-IMPLEMENTATION.md b/doc/COLOR-THEME-IMPLEMENTATION.md deleted file mode 100644 index 1ae8d70..0000000 --- a/doc/COLOR-THEME-IMPLEMENTATION.md +++ /dev/null @@ -1,204 +0,0 @@ -# Color Theme System Implementation - Complete ✅ - -## Overview -Successfully implemented a comprehensive light/dark/auto theme system that is **completely separate** from the existing `.theme-clean` layout system. - -## Key Features Implemented - -### 1. Three Theme Modes -- **Light Mode**: Force light color scheme regardless of system preference -- **Dark Mode**: Force dark color scheme regardless of system preference -- **Auto Mode**: Follows system preference via `prefers-color-scheme` media query - -### 2. Files Created - -#### CSS -- `static/css/color-theme.css` - Complete theme variable system - - CSS custom properties for light theme (`:root`) - - CSS custom properties for dark theme (`[data-color-theme="dark"]`) - - Media query for auto mode (`@media (prefers-color-scheme: dark)`) - - Animated theme switcher button styles - -#### Templates -- `templates/partials/color-theme-switcher.html` - Theme switcher component - - Three buttons (Light, Dark, Auto) - - Hover expansion animation (desktop) - - Tap to expand behavior (mobile) - - Iconify icons for each mode - -#### Hyperscript -- `static/hyperscript/color-theme._hs` - Theme switching logic - - `setColorTheme(mode)` - Apply theme and save to localStorage - - `initColorTheme()` - Load saved theme on page load - - `watchSystemTheme()` - Listen for system theme changes - -### 3. Files Modified - -#### `templates/index.html` -- Added FOUC prevention inline script in `` (applies theme before render) -- Included `color-theme.css` stylesheet -- Included `color-theme._hs` hyperscript file -- Added `initColorTheme()` call on page load -- Included theme switcher component in body - -#### `static/css/main.css` -- Updated body background to use `var(--page-bg)` -- Updated body text color to use `var(--text-secondary)` -- Updated action bar to use `var(--action-bar-bg)` and `var(--action-bar-text)` -- Updated CV page to use `var(--paper-bg)`, `var(--shadow-lg)`, `var(--border-color)` -- Updated `.theme-clean` styles to use CSS variables - -## Technical Implementation Details - -### CSS Variable Structure - -**Light Theme (Default)** -```css -:root { - --page-bg: rgb(82, 86, 89); - --paper-bg: #ffffff; - --text-primary: #1a1a1a; - --text-secondary: #333333; - --border-color: #dddddd; - --shadow-lg: 2px 2px 9px rgba(0, 0, 0, 0.5); -} -``` - -**Dark Theme** -```css -[data-color-theme="dark"] { - --page-bg: #0a0a0a; - --paper-bg: #1a1a1a; - --text-primary: #e0e0e0; - --text-secondary: #d0d0d0; - --border-color: #404040; - --shadow-lg: 0 4px 16px rgba(0, 0, 0, 0.6); -} -``` - -### FOUC Prevention -Inline script in `` runs before page render: -```javascript -(function() { - const theme = localStorage.getItem('color-theme-mode') || 'auto'; - document.documentElement.setAttribute('data-color-theme', theme); -})(); -``` - -### Persistence -- Theme preference stored in: `localStorage['color-theme-mode']` -- Values: `'light'`, `'dark'`, `'auto'` -- Default: `'auto'` (respects system preference) - -## Test Results ✅ - -All tests passed successfully: - -``` -✓ Theme switcher renders correctly -✓ Light/Dark/Auto modes work -✓ localStorage persistence works -✓ Theme persists across page reloads -✓ FOUC prevention works -✓ Button expansion animation works -✓ Visual verification screenshots created -``` - -### Verified Behavior: -- **Light Mode**: Body background = `rgb(82, 86, 89)` ✓ -- **Dark Mode**: Body background = `rgb(10, 10, 10)` ✓ -- **Auto Mode**: Follows system preference ✓ -- **Persistence**: Theme saved to localStorage and restored on reload ✓ -- **FOUC**: Theme applied before page render (no flash) ✓ - -## System Independence - -### COLOR Theme vs LAYOUT Theme - -**COLOR Theme** (New - This Implementation) -- Controls: Backgrounds, text colors, shadows, borders -- Selector: `[data-color-theme="light|dark|auto"]` -- Storage: `localStorage['color-theme-mode']` -- Values: `'light'`, `'dark'`, `'auto'` - -**LAYOUT Theme** (Existing - `.theme-clean`) -- Controls: Sidebars, layout structure, positioning -- Selector: `body.theme-clean` -- Storage: `localStorage['cv-theme']` -- Values: `'default'`, `'clean'` - -**Both Can Coexist:** -```html - - - -``` - -## Browser Compatibility - -- **Desktop**: Hover to expand, mouse leave to collapse -- **Mobile**: Tap to expand, tap again or select theme to collapse -- **Auto Mode**: Uses CSS `@media (prefers-color-scheme: dark)` (supported in all modern browsers) - -## Accessibility - -- **Touch Targets**: 48×48px minimum (iOS HIG compliant) -- **Keyboard Navigation**: Works with tab navigation -- **Tooltips**: Show on hover for each theme option -- **Icons**: Clear visual indicators (sun/moon/auto) - -## Performance - -- **Zero FOUC**: Theme applied via inline script before render -- **GPU Acceleration**: Animations use `opacity` and `transform` -- **Smooth Transitions**: 300ms ease-out for expansion, 200ms for fade-in -- **Minimal Reflow**: CSS variables prevent layout thrashing - -## Future Enhancements - -Possible future improvements (not implemented): -1. Transition animation when theme changes (optional fade) -2. Support custom theme colors (user-selectable accent colors) -3. Sunrise/sunset auto-scheduling (auto-switch based on time) -4. Sync theme preference across devices (server-side storage) -5. "High contrast" mode for accessibility - -## Files Summary - -**Created:** -- `static/css/color-theme.css` (279 lines) -- `templates/partials/color-theme-switcher.html` (58 lines) -- `static/hyperscript/color-theme._hs` (57 lines) -- `test-color-theme.mjs` (150 lines) - Automated test suite - -**Modified:** -- `templates/index.html` (4 additions) -- `static/css/main.css` (5 updates to use CSS variables) - -## Testing - -Run automated tests: -```bash -node test-color-theme.mjs -``` - -Test coverage: -- Theme switcher presence -- Light/Dark/Auto mode functionality -- localStorage persistence -- Page reload persistence -- FOUC prevention -- Button expansion animation -- Visual regression (screenshots) - -## Conclusion - -✅ **Implementation Complete** - -The color theme system is now fully functional and independent of the layout theme. Users can: -- Choose between light, dark, or auto (system) themes -- Have their preference persist across sessions -- Experience smooth, polished theme switching -- Combine color themes with layout themes freely - -All tests pass, visual verification screenshots confirm correct behavior, and the system is ready for production use. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..56c56c8 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,139 @@ +# CV Project Documentation + +**Complete documentation for the Go + HTMX CV website project.** + +--- + +## 📚 Quick Navigation + +### For Developers + +**Getting Started** +- [Architecture Overview](ARCHITECTURE.md) - System design and Go backend architecture +- [Modern Web Techniques](MODERN-WEB-TECHNIQUES.md) - Frontend architecture (HTMX, Hyperscript, CSS) ⭐ +- [API Reference](API.md) - Complete API documentation with endpoints and responses + +**Technical Implementation** +- [Hyperscript Rules](HYPERSCRIPT-RULES.md) - Hyperscript conventions and best practices +- [Zoom Implementation](ZOOM_IMPLEMENTATION.md) - Custom zoom feature technical details + +**Deployment & Operations** +- [Deployment Guide](DEPLOYMENT.md) - Production deployment instructions +- [Security Policies](SECURITY.md) - Security guidelines and vulnerability reporting + +--- + +### For Users & Customizers + +- [User Guide](USER_GUIDE.md) - End-user documentation for CV features +- [Customization Guide](CUSTOMIZATION.md) - How to customize your CV content and styling +- [Privacy Policy](PRIVACY.md) - Data handling and privacy information + +--- + +## 📖 Documentation Overview + +### Core Technical Documentation + +| Document | Purpose | Audience | +|----------|---------|----------| +| [ARCHITECTURE.md](ARCHITECTURE.md) | Go backend architecture, package structure, design patterns | Backend developers | +| [MODERN-WEB-TECHNIQUES.md](MODERN-WEB-TECHNIQUES.md) | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers | +| [API.md](API.md) | Complete API reference with all endpoints | API consumers, integrators | +| [ZOOM_IMPLEMENTATION.md](ZOOM_IMPLEMENTATION.md) | Zoom feature implementation details | Feature developers | +| [HYPERSCRIPT-RULES.md](HYPERSCRIPT-RULES.md) | Hyperscript coding conventions | Frontend developers | + +### User & Operations Documentation + +| Document | Purpose | Audience | +|----------|---------|----------| +| [USER_GUIDE.md](USER_GUIDE.md) | End-user feature documentation | CV users | +| [CUSTOMIZATION.md](CUSTOMIZATION.md) | Content and style customization | CV customizers | +| [DEPLOYMENT.md](DEPLOYMENT.md) | Deployment instructions and operations | DevOps, site operators | +| [SECURITY.md](SECURITY.md) | Security policies and reporting | Security teams | +| [PRIVACY.md](PRIVACY.md) | Privacy policy and data handling | Legal, compliance | + +--- + +## 🏗️ Architecture Quick Reference + +**Backend**: Go (Hono-inspired routing) +- Clean package structure (`internal/` pattern) +- Template caching and rendering +- JSON-based CV data model +- Middleware: logging, security headers, CORS + +**Frontend**: HTMX + Hyperscript + Vanilla CSS +- Hypermedia-driven architecture (minimal JavaScript) +- Server-side rendering with HTMX partial updates +- Declarative behaviors with Hyperscript +- Component-level skeleton loaders +- Light/dark/auto color themes + +**Key Features**: +- ✅ Custom zoom control (25%-175%) +- ✅ Bilingual support (English/Spanish) +- ✅ Keyboard shortcuts (L/I/V/?) +- ✅ Print-optimized CSS +- ✅ Mobile responsive +- ✅ Accessibility (WCAG AA compliance) + +--- + +## 🎯 Common Tasks + +### "I want to..." + +**...understand the system architecture** +→ Start with [ARCHITECTURE.md](ARCHITECTURE.md) (backend) and [MODERN-WEB-TECHNIQUES.md](MODERN-WEB-TECHNIQUES.md) (frontend) + +**...add a new feature** +→ Read [MODERN-WEB-TECHNIQUES.md](MODERN-WEB-TECHNIQUES.md) for frontend patterns, [API.md](API.md) for backend APIs + +**...customize my CV content** +→ Follow [CUSTOMIZATION.md](CUSTOMIZATION.md) for content and styling changes + +**...deploy to production** +→ Use [DEPLOYMENT.md](DEPLOYMENT.md) for step-by-step deployment instructions + +**...understand HTMX patterns** +→ Check [MODERN-WEB-TECHNIQUES.md](MODERN-WEB-TECHNIQUES.md) Section 6 (HTMX Patterns) + +**...write Hyperscript code** +→ Follow conventions in [HYPERSCRIPT-RULES.md](HYPERSCRIPT-RULES.md) + +**...report a security issue** +→ See [SECURITY.md](SECURITY.md) for responsible disclosure process + +--- + +## 📦 Archive + +Historical documentation (bug fixes, testing reports, implementation notes) is stored in [`archive/`](archive/) for reference. These documents are not actively maintained but preserved for historical context. + +--- + +## 🔗 External Resources + +- **HTMX Documentation**: https://htmx.org/ +- **Hyperscript**: https://hyperscript.org/ +- **Go Documentation**: https://go.dev/doc/ +- **Playwright Testing**: https://playwright.dev/ + +--- + +## 📝 Documentation Standards + +All documentation in this project follows these standards: + +- **Markdown format** with GitHub-flavored syntax +- **Clear structure** with table of contents for long documents +- **Code examples** with syntax highlighting +- **Up-to-date** reflecting current implementation +- **Versioned** via Git with meaningful commit messages + +--- + +**Last Updated**: 2025-11-18 +**Documentation Status**: ✅ Clean, organized, zero redundancy +**Total Active Docs**: 11 core documents + archive diff --git a/doc/PROJECT_IMPROVEMENT_SUMMARY.md.ASPIRATIONAL b/doc/archive/PROJECT_IMPROVEMENT_SUMMARY.md similarity index 100% rename from doc/PROJECT_IMPROVEMENT_SUMMARY.md.ASPIRATIONAL rename to doc/archive/PROJECT_IMPROVEMENT_SUMMARY.md diff --git a/doc/ZOOM-CONTROL-FIX-REPORT.md b/doc/archive/ZOOM-CONTROL-FIX-REPORT.md similarity index 100% rename from doc/ZOOM-CONTROL-FIX-REPORT.md rename to doc/archive/ZOOM-CONTROL-FIX-REPORT.md diff --git a/doc/ZOOM-FIXES-COMPLETE-SUMMARY.md b/doc/archive/ZOOM-FIXES-COMPLETE-SUMMARY.md similarity index 100% rename from doc/ZOOM-FIXES-COMPLETE-SUMMARY.md rename to doc/archive/ZOOM-FIXES-COMPLETE-SUMMARY.md