docs: comprehensive documentation update

Update README with detailed project overview, features, installation, and usage. Add AGENTS.md developer guide, CONTRIBUTING.md guidelines, MIT LICENSE file, and fix CI workflow configuration.
2026-02-12 10:51:37 -05:00
parent 776188bb5b
commit 7323a6f7a8
6 changed files with 452 additions and 42 deletions
@@ -0,0 +1,146 @@
+# AGENTS.md - Developer Guide for WebDev Portfolio
+
+Essential information for AI agents working on the webdev portfolio project. Covers build commands, code style, testing, and project structure.
+
+## Project Overview
+
+Modern web portfolio built with vanilla JavaScript, CSS, and HTML. Uses Vite for development, Bootstrap 5 foundation, and a coffee-themed design system with light/dark mode support.
+
+## Build & Development Commands
+
+### Package Scripts
+```bash
+npm run dev      # Start Vite dev server (http://localhost:5173)
+npm run build    # Build for production (outputs to /dist)
+npm run preview  # Preview production build (http://localhost:4173)
+```
+
+### Testing Commands
+```bash
+# Cross-browser tests (requires Python & Playwright)
+pip install playwright
+playwright install firefox webkit
+npm run build && npm run preview &
+python cross_browser_test.py
+pkill -f "vite preview"
+
+# Lighthouse audit
+npx lighthouse http://localhost:4173 --output json --output html --output-path=./lighthouse-report
+```
+
+### CI/CD Pipeline (`.github/workflows/ci.yml`)
+Runs on push/PR:
+1. `npm ci` - Clean install
+2. `npm run build` - Production build
+3. Lighthouse analysis via `lighthouse-checker/action`
+
+## Code Style Guidelines
+
+### JavaScript
+- **ES6+ modules**: Use `type="module"` in HTML
+- **Variables**: Prefer `const` over `let`; avoid `var`
+- **Functions**: Arrow functions for callbacks; named functions for top-level declarations
+- **Naming**: camelCase for variables/functions; PascalCase for classes
+- **Error handling**: Check element existence before manipulation; use early returns
+- **Comments**: Use section headers: `// ===== SECTION NAME =====`
+- **DOM manipulation**: Use modern APIs (`querySelector`, `classList`, `dataset`)
+- **Animation**: Respect `prefers-reduced-motion`; use `requestAnimationFrame`
+
+### CSS
+- **CSS Custom Properties**: Define design tokens in `:root`; semantic variable names
+- **CSS Nesting**: Use `&` for nested selectors (modern browsers)
+- **Responsive Design**: Mobile-first media queries with `min-width`
+- **Color Scheme**: Support `prefers-color-scheme: dark` with variable overrides
+- **Naming**: kebab-case for class names
+- **Modern Features**: Container queries, view transitions, CSS grid, flexbox
+- **Performance**: Avoid overly specific selectors; use CSS containment
+
+### HTML
+- **Semantic HTML5**: Use appropriate sectioning elements (`<header>`, `<main>`, `<section>`)
+- **Accessibility**: Include ARIA attributes where needed; proper heading hierarchy
+- **Bootstrap Integration**: Use Bootstrap classes alongside custom styles
+- **Data Attributes**: Use `data-*` for JavaScript hooks (e.g., `data-text`, `data-score`)
+- **Performance**: Lazy loading for images; defer non-critical scripts
+
+### Formatting
+- **Indentation**: 2 spaces (no tabs)
+- **Line length**: Keep under 100 characters
+- **File endings**: LF (Unix)
+- **Trailing whitespace**: Remove
+- **Blank lines**: Separate logical sections
+
+## Project Structure
+
+```
+webdev/
+├── index.html              # Main page
+├── tos.html               # Terms of Service
+├── privacy.html           # Privacy Policy
+├── main.js                # All JavaScript functionality
+├── styles.css             # All CSS styles
+├── vite.config.js         # Vite configuration
+├── package.json           # Dependencies and scripts
+├── assets/                # Static assets (images, fonts)
+├── public/                # Public files served as-is
+├── dist/                  # Production build (generated)
+├── cross_browser_test.py  # Playwright cross-browser tests
+└── .github/workflows/ci.yml # CI/CD pipeline
+```
+
+## Key Files
+- `main.js`: All interactive features (typewriter, particles, skill bars, testimonials, parallax, metrics)
+- `styles.css`: Complete styling with coffee theme, dark mode, animations
+- `vite.config.js`: Configures multi-page build (index.html, tos.html, privacy.html)
+- `cross_browser_test.py`: Validates cross-browser compatibility
+
+## Design System Principles
+- **Coffee theme**: Use defined color palette (`--color-coffee-*`, `--color-cream`, `--color-gold`, `--color-teal`)
+- **Typography**: `--font-sans` (Inter) for body, `--font-display` (Playfair Display) for headings
+- **Spacing**: Consistent padding/margin scales
+- **Shadows**: `--shadow-soft` and `--shadow-glass` variables
+- **Transitions**: Cubic-bezier easing for natural motion
+- **Reduced motion**: Respect `prefers-reduced-motion` media query
+
+## Development Workflow
+
+### Adding New Features
+1. Update HTML with semantic markup
+2. Add CSS styles using existing design tokens
+3. Implement JavaScript in `main.js` with appropriate section
+4. Test across browsers using `cross_browser_test.py`
+5. Run Lighthouse audit for performance/accessibility
+
+### Modifying Existing Code
+- Follow existing patterns and naming conventions
+- Update all related files (HTML/CSS/JS) consistently
+- Test changes in multiple browsers
+- Ensure dark mode compatibility
+
+## Troubleshooting
+
+### Common Issues
+- **CSS variables not working**: Ensure defined in `:root` and referenced correctly
+- **JavaScript errors**: Check element existence before manipulation
+- **Build failures**: Clear `node_modules` and reinstall dependencies
+- **Cross-browser issues**: Run `cross_browser_test.py`
+
+### Performance Optimization
+- Use Vite's built-in optimizations (code splitting, minification)
+- Optimize images in `assets/` directory
+- Minimize layout thrashing in JavaScript animations
+- Use CSS containment for complex components
+
+## Documentation Files
+
+- **README.md**: Primary project documentation with overview, features, installation, and usage instructions
+- **AGENTS.md**: Developer guide for AI agents (this file) - covers build commands, code style, project structure
+- **CROSS_BROWSER_TEST_REPORT.md**: Detailed report from cross-browser compatibility testing
+- **VISUAL_INSPECTION_REPORT.md**: Visual quality assessment across desktop and mobile viewports
+- **TESTING_SUMMARY.txt**: Quick summary of cross-browser test results
+- **.github/workflows/ci.yml**: CI/CD pipeline configuration for automated testing and Lighthouse audits
+
+All documentation should be kept up-to-date with the codebase. Test reports are generated artifacts that may be regenerated as needed.
+
+---
+
+*This document is maintained for AI agents and developers contributing to the webdev portfolio project.*