# 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.*