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.

.github/workflows/ci.yml

@@ -1 +1,34 @@
-name: CI & Lighthouse\non:\n  push:\n  pull_request:\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - name: Install deps\n        run: npm ci\n      - name: Build\n        run: npm run build\n      - name: Lighthouse\n        uses: lighthouse-checker/action@v1\n        with:\n          urls: |\n            http://localhost:8080/index.html\n          prComment: true
+name: CI & Lighthouse
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Build project
+        run: npm run build
+        
+      - name: Run Lighthouse audit
+        uses: lighthouse-checker/action@v1
+        with:
+          urls: |
+            http://localhost:8080/
+          prComment: true
+          serverCommand: 'npm run preview -- --port 8080'
+          waitForServer: true

AGENTS.md

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

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to d@n tech Portfolio
+
+Thank you for your interest in contributing to this web development portfolio project! This document provides guidelines for contributing.
+
+## How to Contribute
+
+1. **Fork the Repository** - Click the "Fork" button on GitHub to create your own copy.
+2. **Clone Your Fork** - `git clone https://github.com/YOUR-USERNAME/webdev-site.git`
+3. **Create a Feature Branch** - `git checkout -b feature/your-feature-name`
+4. **Make Your Changes** - Follow the code style guidelines below.
+5. **Test Your Changes** - Ensure the site builds and works across browsers.
+6. **Commit Your Changes** - `git commit -m "Add your descriptive message"`
+7. **Push to Your Fork** - `git push origin feature/your-feature-name`
+8. **Open a Pull Request** - Navigate to the original repository and open a PR.
+
+## Code Style Guidelines
+
+Please adhere to the existing code style to maintain consistency:
+
+### JavaScript
+- Use ES6+ modules with `type="module"` in HTML
+- Prefer `const` over `let`; avoid `var`
+- Arrow functions for callbacks; named functions for top-level declarations
+- CamelCase for variables/functions; PascalCase for classes
+- Check element existence before DOM manipulation
+- Use section headers: `// ===== SECTION NAME =====`
+
+### CSS
+- Use CSS Custom Properties defined in `:root` with semantic names
+- CSS Nesting with `&` for nested selectors (modern browsers)
+- Mobile-first media queries with `min-width`
+- Support `prefers-color-scheme: dark` with variable overrides
+- Kebab-case for class names
+
+### HTML
+- Semantic HTML5 elements (`<header>`, `<main>`, `<section>`)
+- Include ARIA attributes where needed; proper heading hierarchy
+- Use Bootstrap classes alongside custom styles
+- `data-*` attributes for JavaScript hooks
+- Lazy loading for images; defer non-critical scripts
+
+## Testing
+
+Before submitting a pull request, please verify:
+
+1. **Build Success** - Run `npm run build` to ensure no errors
+2. **Cross-Browser Compatibility** - Test in at least Firefox and Chrome
+3. **Responsive Design** - Check mobile (375px) and desktop (1200px) views
+4. **No Console Errors** - Open browser developer tools and ensure no errors
+5. **Lighthouse Audit** - Run `npx lighthouse http://localhost:4173` for performance, accessibility, SEO, and best practices
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- Steps to reproduce the issue
+- Expected vs. actual behavior
+- Browser and operating system information
+- Screenshots if applicable
+
+## Questions?
+
+If you have questions, please open an issue or contact the maintainer via the portfolio site: [dev.dustin.coffee](https://dev.dustin.coffee/)
+
+---
+
+*Thank you for contributing!*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dustin Newkirk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,37 +1,180 @@
-# d@n tech - Modern Web Portfolio (2026 Edition)
+# d@n tech - Modern Web Portfolio (2026 Edition)
-
+
-Welcome to the Web Development Site repository. This project is a simple website designed to showcase basic web development skills.
+A modern, coffee-themed web development portfolio showcasing professional web development services. Built with vanilla JavaScript, CSS, and HTML using Vite for development, Bootstrap 5 foundation, and a responsive design system with light/dark mode support.
-
+
-## Features
+## 🌟 Features
-
+
-- Responsive design
+- **Modern Coffee Theme**: Elegant color palette with CSS custom properties (--color-coffee, --color-cream, --color-gold, --color-teal)
-- Basic HTML, CSS, and JavaScript
+- **Responsive Design**: Mobile-first approach with Bootstrap 5 grid system and container queries
-- Simple and clean layout
+- **Dark/Light Mode**: Automatic theme switching based on system preferences with manual toggle
-
+- **Interactive Elements**:
-## Installation
+  - Particle background canvas animation
-
+  - Typewriter effect for hero section
-1. Clone the repository:
+  - Animated skill bars that trigger on scroll
-    ```bash 
+  - Testimonial carousel with expandable content
-    git clone https://git.dustin.coffee/hobokenchicken/webdev-site.git
+  - Scroll progress indicator
-    ```
+- **Performance Optimized**:
-2. Navigate to the project directory:
+  - Vite-based build with code splitting and minification
-    ```bash
+  - WebP image formats with responsive variants
-    cd web_dev_site
+  - Bootstrap loaded from CDN with fallback
-    ```
+- **Cross-Browser Compatible**: Fully tested on Firefox, WebKit (Safari), and Chromium
-3. Open `index.html` in your web browser to view the website.
+- **Accessibility**: Semantic HTML5, ARIA attributes, proper heading hierarchy
-
+- **Multi-Page Support**: Includes Terms of Service and Privacy Policy pages
-## Usage
+
-
+## 🛠️ Tech Stack
-Feel free to explore the code, modify it, and use it as a reference for your own projects.
+
-
+- **Frontend**: Vanilla JavaScript (ES6+), CSS3, HTML5
-## Contributing
+- **Build Tool**: Vite 7.3.1
-
+- **CSS Framework**: Bootstrap 5.3.3
-Contributions are welcome! Please fork the repository and create a pull request with your changes.
+- **Fonts**: Inter (body), Playfair Display (headings)
-
+- **Development**: npm scripts, Playwright for cross-browser testing
-## License
+- **CI/CD**: GitHub Actions with Lighthouse audits
-
+
-This project is licensed under the MIT License.
+## 📁 Project Structure
-
+
-## Contact
+```
-
+webdev/
-For any questions or feedback, please contact [your email address].
+├── index.html              # Main portfolio page
+├── tos.html               # Terms of Service
+├── privacy.html           # Privacy Policy
+├── main.js                # All JavaScript functionality
+├── styles.css             # Complete CSS with coffee theme
+├── vite.config.js         # Vite multi-page 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
+└── AGENTS.md              # Developer guide for AI agents
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js 18+ and npm
+- Modern web browser
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone https://git.dustin.coffee/hobokenchicken/webdev-site.git
+   cd webdev-site
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Start development server**
+   ```bash
+   npm run dev
+   ```
+   Open [http://localhost:5173](http://localhost:5173) in your browser.
+
+## 📦 Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start Vite development server (localhost:5173) |
+| `npm run build` | Build for production (outputs to `/dist`) |
+| `npm run preview` | Preview production build (localhost:4173) |
+| `npm test` | *Placeholder for future test suite* |
+
+## 🧪 Testing
+
+### Cross-Browser Testing
+Run comprehensive browser compatibility tests using Playwright:
+
+```bash
+# Install Playwright (Python)
+pip install playwright
+playwright install firefox webkit
+
+# Build and preview the site
+npm run build && npm run preview &
+
+# Run cross-browser tests
+python cross_browser_test.py
+pkill -f "vite preview"
+```
+
+### Lighthouse Audit
+Generate performance, accessibility, and SEO reports:
+
+```bash
+npm run build && npm run preview &
+npx lighthouse http://localhost:4173 --output json --output html --output-path=./lighthouse-report
+```
+
+### CI/CD Pipeline
+The project includes GitHub Actions workflow (`.github/workflows/ci.yml`) that runs on every push/PR:
+
+1. `npm ci` - Clean install
+2. `npm run build` - Production build verification
+3. Lighthouse analysis via `lighthouse-checker/action`
+
+## 🎨 Design System
+
+The portfolio follows a consistent design language:
+
+- **Color Palette**: Coffee-themed semantic variables (`--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 using CSS custom properties
+- **Shadows**: `--shadow-soft` and `--shadow-glass` variables
+- **Transitions**: Cubic-bezier easing for natural motion
+- **Reduced Motion**: Respects `prefers-reduced-motion` media query
+
+## 📝 Code Style
+
+### JavaScript
+- ES6+ modules with `type="module"` in HTML
+- `const` over `let`; avoid `var`
+- Arrow functions for callbacks; named functions for top-level declarations
+- CamelCase for variables/functions; PascalCase for classes
+- Early returns and element existence checks before DOM manipulation
+- Section headers: `// ===== SECTION NAME =====`
+
+### CSS
+- CSS Custom Properties defined in `:root` with semantic names
+- CSS Nesting with `&` for nested selectors (modern browsers)
+- Mobile-first media queries with `min-width`
+- Support for `prefers-color-scheme: dark` with variable overrides
+- Kebab-case for class names
+- Modern features: container queries, view transitions, CSS grid, flexbox
+
+### HTML
+- Semantic HTML5 elements (`<header>`, `<main>`, `<section>`)
+- ARIA attributes where needed; proper heading hierarchy
+- Bootstrap classes alongside custom styles
+- `data-*` attributes for JavaScript hooks (e.g., `data-text`, `data-score`)
+- Lazy loading for images; defer non-critical scripts
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please ensure your code follows the existing style conventions and includes appropriate tests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📬 Contact
+
+- **Portfolio**: [dev.dustin.coffee](https://dev.dustin.coffee/)
+- **Email**: [Contact via portfolio](https://dev.dustin.coffee/#contact)
+- **GitHub**: [@hobokenchicken](https://github.com/hobokenchicken)
+
+---
+
+*Built with ☕ by Dustin Newkirk | Last updated: February 2026*

package.json

@@ -1,7 +1,7 @@
 {
   "name": "webdev",
   "version": "1.0.0",
-  "description": "Welcome to the Web Development Site repository. This project is a simple website designed to showcase basic web development skills.",
+  "description": "Modern coffee-themed web development portfolio built with vanilla JavaScript, CSS, and HTML. Uses Vite, Bootstrap 5, and features dark/light mode, particle animations, and cross-browser compatibility.",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -13,9 +13,9 @@
     "type": "git",
     "url": "https://git.dustin.coffee/hobokenchicken/webdev-site.git"
   },
-  "keywords": [],
+  "keywords": ["portfolio", "web development", "coffee theme", "bootstrap", "vite", "vanilla javascript", "dark mode"],
-  "author": "",
+  "author": "Dustin Newkirk",
-  "license": "ISC",
+  "license": "MIT",
   "type": "module",
   "devDependencies": {
     "vite": "^7.3.1"