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
--- a/README.md
+++ b/README.md
@@ -1,37 +1,180 @@
-# 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.
-
-## Features
-
- Responsive design
- Basic HTML, CSS, and JavaScript
- Simple and clean layout
-
-## Installation
-
-1. Clone the repository:
-    ```bash 
-    git clone https://git.dustin.coffee/hobokenchicken/webdev-site.git
-    ```
-2. Navigate to the project directory:
-    ```bash
-    cd web_dev_site
-    ```
-3. Open `index.html` in your web browser to view the website.
-
-## Usage
-
-Feel free to explore the code, modify it, and use it as a reference for your own projects.
-
-## Contributing
-
-Contributions are welcome! Please fork the repository and create a pull request with your changes.
-
-## License
-
-This project is licensed under the MIT License.
-
-## Contact
-
-For any questions or feedback, please contact [your email address].
+# d@n tech - Modern Web Portfolio (2026 Edition)
+
+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
+
+- **Modern Coffee Theme**: Elegant color palette with CSS custom properties (--color-coffee, --color-cream, --color-gold, --color-teal)
+- **Responsive Design**: Mobile-first approach with Bootstrap 5 grid system and container queries
+- **Dark/Light Mode**: Automatic theme switching based on system preferences with manual toggle
+- **Interactive Elements**:
+  - Particle background canvas animation
+  - Typewriter effect for hero section
+  - Animated skill bars that trigger on scroll
+  - Testimonial carousel with expandable content
+  - Scroll progress indicator
+- **Performance Optimized**:
+  - Vite-based build with code splitting and minification
+  - WebP image formats with responsive variants
+  - Bootstrap loaded from CDN with fallback
+- **Cross-Browser Compatible**: Fully tested on Firefox, WebKit (Safari), and Chromium
+- **Accessibility**: Semantic HTML5, ARIA attributes, proper heading hierarchy
+- **Multi-Page Support**: Includes Terms of Service and Privacy Policy pages
+
+## 🛠️ Tech Stack
+
+- **Frontend**: Vanilla JavaScript (ES6+), CSS3, HTML5
+- **Build Tool**: Vite 7.3.1
+- **CSS Framework**: Bootstrap 5.3.3
+- **Fonts**: Inter (body), Playfair Display (headings)
+- **Development**: npm scripts, Playwright for cross-browser testing
+- **CI/CD**: GitHub Actions with Lighthouse audits
+
+## 📁 Project Structure
+
+```
+webdev/
+├── 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*