hobokenchicken
7323a6f7a8
Some checks failed
CI & Lighthouse / test (push) Has been cancelled
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.
146 lines
6.3 KiB
Markdown
146 lines
6.3 KiB
Markdown
# 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.* |