webdev-site/AGENTS.md

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

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

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