diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..428c6ea7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,346 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Portfolio website for Adam Jolicoeur (adamjolicoeur.com) built with Eleventy (11ty) static site generator. The site showcases UX/UI design work, development projects, and professional content. Deployed to GitHub Pages from the `docs/` directory. + +**Current Version**: 10.0.2 +**Repository**: https://github.com/AdamJ/adamj.github.io +**Live Site**: https://adamjolicoeur.com +**Node.js**: v25.2.1 required (runs on 20+, see `.nvmrc`) + +## Critical Build Commands + +All commands include expected timings. **NEVER CANCEL** builds—they complete within specified timeouts. + +### Development Workflow +```bash +# Initial setup (first time only) +npm install # 60 seconds - installs dependencies + +# Start development server +npm run start # Starts watchers + BrowserSync on http://localhost:8081 + # NOT port 8080 - this is hardcoded + +# Full production build +npm run build # 20 seconds - runs all build steps in sequence +``` + +### Individual Build Steps +```bash +npm run clean # 1 second - removes docs/ directory +npm run images:optimize # 14 seconds - processes images with Sharp +npm run build:sass # 2 seconds - compiles SCSS to CSS +npm run build:eleventy # 2 seconds - static site generation +npm run postbuild # Auto-runs after build (Autoprefixer + CSSNano) +``` + +### Linting & Validation +```bash +npm run lint # 5 seconds - Stylelint check (expect 176+ legacy errors) +npm run lint:fix # Auto-fix Stylelint issues +npm run webhint # 30 seconds - accessibility/performance audit +``` + +**Expected Build Warnings (Safe to Ignore)**: +- 144 Sass deprecation warnings from Bootstrap's `@import` syntax +- 74+ npm audit vulnerabilities (non-critical for static site) +- 176+ Stylelint errors (legacy code, non-blocking) +- 245+ WebHint warnings (accessibility/compatibility, non-blocking) +- Node version warnings (package requires 22, runs fine on 20+) + +## Architecture + +### Build Pipeline +1. **Content** (Markdown/HTML) → **Templates** (Nunjucks) → **Static HTML** +2. **SCSS** → **Sass compiler** → **PostCSS** (Autoprefixer + minify) → **CSS** +3. **Raw images** → **Sharp processor** → **WebP + JPEG variants** +4. **Output**: `docs/` directory (GitHub Pages requirement) + +### Directory Structure +``` +src/ # Source files (EDIT HERE) +├── pages/ # Markdown pages (31 total) +│ ├── designs/ # Design case studies (5 projects) +│ ├── development/ # Dev projects & code examples +│ ├── about/ # About & resume pages +│ └── *.md # Index pages (portfolio.md, etc.) +├── _includes/ # Nunjucks templates +│ ├── base.njk # HTML5 shell (nav, meta, footer) +│ ├── markdown.njk # Markdown wrapper +│ └── carousel.njk # Image carousel component +├── _data/ +│ └── meta.js # Site metadata & social links +├── assets/ +│ ├── img/ # Processed images (650+ files, ~21MB) +│ ├── img-raw/ # Original high-res images (~66MB) +│ └── AdamJolicoeur-Resume.pdf +├── sass/ # SCSS stylesheets (22 files, ~2000 lines) +│ ├── style.scss # Main (imports Bootstrap + custom) +│ ├── _colors.scss # Color variables +│ ├── _typography.scss # Font & text styles +│ └── *.scss # Component partials +└── js/ # JavaScript files (vanilla JS) + +docs/ # Generated output (DO NOT EDIT) +└── [build artifacts] # 20-30MB, auto-generated + +scripts/ +└── image-optimizer.js # Sharp-based image processor + +.eleventy.js # Eleventy configuration (163 lines) +.github/ +├── workflows/ +│ └── eleventy_build.yml # CI/CD: push to main → build → gh-pages +└── copilot-instructions.md # Comprehensive build guide (190 lines) +``` + +### Template System +- **Base Layout** (`base.njk`): HTML5 shell with navigation, meta tags, OG tags, Service Worker registration, "Go to Top" button +- **Template Hierarchy**: `base.njk` → `page.njk` → `markdown.njk` +- **Markdown Processing**: `markdown-it` with plugins: + - `markdown-it-anchor`: Auto-heading anchors with `#` symbols + - `markdown-it-highlightjs`: Syntax highlighting + - `markdown-it-eleventy-img`: Image optimization + +### Eleventy Plugins Active +1. `@11ty/eleventy-plugin-syntaxhighlight` - Code block highlighting +2. `@11ty/eleventy-plugin-rss` - RSS feed generation +3. `@11ty/eleventy-navigation` - Navigation helper +4. `@11ty/eleventy-plugin-inclusive-language` - Inclusive language linting +5. `@11tyrocks/eleventy-plugin-emoji-readtime` - Reading time + emoji +6. `@11tyrocks/eleventy-plugin-sass-lightningcss` - Sass → Lightning CSS +7. `eleventy-plugin-toc` - Table of contents (h2-h4) +8. `eleventy-plugin-dropcap` - Drop cap styling +9. Custom category collections (development, general, design, portfolio) + +### Styling Architecture +- **Framework**: Bootstrap 5.3.8 (grid + components) +- **Preprocessor**: Sass/SCSS v1.89.2 +- **Post-Processing**: Autoprefixer v10.4.21 + CSSNano v7.0.7 (minification) +- **CSS Methodology**: Standard CSS with element-based naming (`.card`, `.btn-primary`) +- **No utility frameworks** (no Tailwind) +- **Fonts**: Google Fonts (Inter, Pirata One, Playfair Display) +- **Icons**: Font Awesome v6+ (CDN + Kit) + +### Image Processing Pipeline +1. Place originals in `src/assets/img-raw/` (high-res source) +2. Run `npm run images:optimize` (14 seconds) +3. Sharp generates: + - Full-size: 1200px width, WebP (80%) + JPEG (85%) + - Thumbnail: 300px width, WebP (70%) + JPEG (75%) +4. Output to `src/assets/img/` (~650+ files, ~21MB, committed to repo) + +### PWA Features +- **Service Worker**: `src/sw.js` (offline support, cache-polyfill) +- **Web Manifest**: `manifest.json` (installable app metadata) +- **Icons**: Multiple favicon sizes (16, 32, 180, 192, 512px) + +### Collections & Data +**Auto-Generated Collections** (via Eleventy): +- `development` - Articles tagged with design/development +- `general` - General articles +- `design` - Design case studies +- `portfolio` - Portfolio pieces +- `specialCollection` - Items with custom "type" field (Bluesky integration) + +**Site Metadata** (`src/_data/meta.js`): +- Site name, description, URL +- Author info +- Social links (GitHub, LinkedIn, Bluesky, Mastodon, Dev.to, CodePen, Figma) +- Environment detection (dev/prod) + +### Custom Filters & Shortcodes +- **Slug Filter**: Removes emoji, sanitizes for URLs (uses `slugify`) +- **Year Shortcode**: Dynamic copyright year +- **Package Version Shortcode**: Auto-inserted version from package.json + +## Adding Content + +### New Page +Create `.md` file in `src/pages/` with YAML front matter: +```yaml +--- +title: "Page Title" +layout: markdown.njk +eleventyNavigation: + key: unique-key + title: Nav Title + order: 10 +categories: [development, design] +--- +``` + +### New Design Case Study +1. Create subfolder in `src/pages/designs/` +2. Add `index.md` with front matter +3. Place images in `src/assets/img-raw/[project-name]/` +4. Run `npm run images:optimize` + +### Modify Site Navigation +Edit `eleventyNavigation` in page front matter: +- `key`: Unique identifier +- `title`: Display text in nav +- `order`: Menu position (lower numbers first) + +## Working with Styles + +### SCSS File Organization +- **Main**: `src/sass/style.scss` (imports Bootstrap + custom partials) +- **Colors**: `src/sass/_colors.scss` +- **Typography**: `src/sass/_typography.scss` +- **Layout**: `src/sass/_layout.scss` +- **Components**: Individual `_component.scss` files (buttons, cards, gallery, etc.) + +### CSS Build Process +- **Development**: Auto-compiles via `npm run start` watcher +- **Production**: `npm run build:sass` → PostCSS → minified output +- **Output**: `docs/css/style.css` (~98KB) + +## Environment Variables + +- **`ELEVENTY_ENV=prod`**: Excludes `src/posts/` from build (production) +- **`ELEVENTY_ENV=dev`**: Includes all content (development, default) + +## CI/CD Pipeline + +**GitHub Actions** (`.github/workflows/eleventy_build.yml`): +1. **Trigger**: Push to `main` branch +2. **Node.js**: v25.x +3. **Steps**: + - Checkout code + - `npm ci` (with Font Awesome token) + - `npm run build` + - Deploy `docs/` to `gh-pages` branch +4. **Live Site**: Auto-deploys to GitHub Pages + +**Cloudflare**: Creates pull request previews + +## Configuration Files + +### `.eleventy.js` (163 lines) +- Input: `src/`, Output: `docs/` +- Markdown library setup (markdown-it with plugins) +- Plugin registration (9+ plugins) +- Watch targets (monitors SCSS changes) +- Pass-through copy (assets, icons, CNAME, resume PDF, service worker) +- Custom filters (slug, year, packageVersion) +- BrowserSync middleware (404 handling) +- Category collections +- Environment detection + +### `.stylelintrc.json` +- Config: `stylelint-config-standard-scss` +- Plugin: `stylelint-order` (property ordering) +- Custom rules: Disabled empty line requirements, color function notation + +### `.hintrc` +- WebHint rules for accessibility (axe), best practices, security +- Expected: 245+ warnings (non-blocking) + +## Common Development Tasks + +### Add New Images +```bash +# 1. Place original files in src/assets/img-raw/ +# 2. Process with Sharp +npm run images:optimize # 14 seconds + +# 3. Reference in templates with Eleventy Image filter +# Generated files appear in src/assets/img/ +``` + +### Modify Site Metadata +Edit `src/_data/meta.js`: +- Site name, description, URL +- Social links +- Author information + +### Update Navigation Menu +Edit `eleventyNavigation` in page front matter (see "Adding Content" above) + +### Test Responsive Design +```bash +npm run start # Opens BrowserSync on :8081 +# Resize browser window or use DevTools device emulation +``` + +## Validation & Testing + +### Manual Validation Checklist +After changes, ALWAYS test: +1. **Home page**: http://localhost:8081 - verify portfolio cards load +2. **Design portfolio**: http://localhost:8081/designs/ - test case studies +3. **Development showcase**: http://localhost:8081/development/ - verify links +4. **Responsive behavior**: Resize browser, test mobile +5. **Navigation menu**: All links functional +6. **Images**: Load correctly, WebP with JPEG fallbacks + +### Quick Validation Commands +```bash +# Verify site builds and serves +npm run build && npm run start & + +# Check key files exist +ls -la docs/css/style.css # Main CSS (~98KB) +ls -la docs/assets/img/ | wc -l # 650+ images + +# Test pages respond +curl -I http://localhost:8081/ # Should return 200 OK +curl -I http://localhost:8081/designs/ # Should return 200 OK +``` + +## Troubleshooting + +### Common Issues +- **Build hangs during image optimization**: Check `src/assets/img-raw/` for valid images +- **Port 8081 in use**: Kill existing process or change port in `package.json` +- **Missing Sharp module**: Run `npm install` again (CPU architecture specific) +- **CSS not updating**: Clear browser cache, check Sass compilation warnings +- **404 on navigation**: Verify Eleventy generated HTML in `docs/` + +### Recovery Commands +```bash +# Nuclear option - clean restart +npm run clean +rm -rf node_modules +npm install +npm run build + +# Verify build output +ls -la docs/ +ls -la docs/css/ +ls -la docs/assets/img/ +``` + +## Tech Stack Reference + +**Core**: +- Eleventy (11ty) v3.1.2 - Static site generator +- Node.js v25.2.1 (runs on 20+) +- Nunjucks + Liquid - Templating +- Markdown + YAML - Content format + +**Frontend**: +- Bootstrap v5.3.8 - Grid + components +- Sass/SCSS v1.89.2 - Styles +- Vanilla JavaScript - No framework +- Font Awesome v6+ - Icons +- Prism.js - Syntax highlighting + +**Build Tools**: +- Sharp - Image processing +- Autoprefixer v10.4.21 - CSS vendor prefixes +- CSSNano v7.0.7 - CSS minification +- Stylelint v16.20.0 - SCSS linting +- WebHint v7.1.13 - Accessibility audits + +## External Documentation +- **Eleventy**: https://www.11ty.dev/docs/ +- **Bootstrap**: https://getbootstrap.com/docs/5.3/ +- **Sass**: https://sass-lang.com/documentation/ +- **Sharp**: https://sharp.pixelplumbing.com/ +- **11ty Recipes**: https://11ty.recipes/ +- **The 11ty Bundle**: https://11tybundle.dev/ diff --git a/README.md b/README.md index 90ab8e08..917a2984 100755 --- a/README.md +++ b/README.md @@ -1,18 +1,27 @@ ![Static Badge](https://img.shields.io/badge/Bsky-black?style=social&logo=bluesky&link=https%3A%2F%2Fbsky.app%2Fprofile%2Fadamjol.bsky.social) ![Keybase PGP](https://img.shields.io/keybase/pgp/mindreeper2420) ![Mastodon Follow](https://img.shields.io/mastodon/follow/109566572934687761?domain=mastodon.world) -![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/AdamJ/adamj.github.io?style=for-the-badge) ![GitHub last commit](https://img.shields.io/github/last-commit/AdamJ/adamj.github.io?color=%2321476b&style=for-the-badge) ![Static Badge](https://img.shields.io/badge/22-22?style=for-the-badge&logo=NVM&logoColor=%23F4DD4B&label=NVM&color=232147&link=https%3A%2F%2Fgithub.com%2FAdamJ%2FAdamJ.github.io%2Fblob%2Fmain%2F.nvmrc) ![Static Badge](https://img.shields.io/badge/Cloudflare-black?style=for-the-badge&logo=cloudflare&link=https%3A%2F%2Fadamj-github-io.pages.dev) +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/AdamJ/adamj.github.io?style=for-the-badge) ![GitHub last commit](https://img.shields.io/github/last-commit/AdamJ/adamj.github.io?color=%2321476b&style=for-the-badge) ![Static Badge](https://img.shields.io/badge/25-25?style=for-the-badge&logo=NVM&logoColor=%23F4DD4B&label=NVM&color=232147&link=https%3A%2F%2Fgithub.com%2FAdamJ%2FAdamJ.github.io%2Fblob%2Fmain%2F.nvmrc) ![Static Badge](https://img.shields.io/badge/Cloudflare-black?style=for-the-badge&logo=cloudflare&link=https%3A%2F%2Fadamj-github-io.pages.dev) -# Welcome +# Adam Jolicoeur - Portfolio Site -This is the repo for my portfolio site, adamjolicoeur.com, hosted on GitHub. +This repository contains the source code for my personal portfolio website at [adamjolicoeur.com](https://adamjolicoeur.com), built with Eleventy (11ty) and deployed via GitHub Pages. -## Who am I? +## About This Repository -I'm a user experience designer with a passion for creating data-intensive designs. With a background in web development, I enjoy turning my designs into living, usable products. +This is a **personal portfolio site** showcasing my work as a Lead Product Designer and Product Manager. The site features: -## Why here? +- **Design Case Studies** - UX/UI projects from AWS, Red Hat, and Component Assembly Systems +- **Development Projects** - Open source contributions, tools, and code examples +- **Professional Content** - Resume, presentations, and technical articles +- **App Showcases** - iOS/iPadOS apps and web applications -I decided to build my own portfolio site on GitHub, rather than on a less code-oriented platform, in order to keep my skills sharp, up-to-date, and to do everything in the open. +## Usage & Ownership + +**All content, design work, code, and assets in this repository are for my personal use only.** This is a public repository for transparency and to demonstrate my development workflow, but the content is not licensed for reuse. + +## About Me + +I'm a user experience designer with 15+ years of enterprise experience at companies like AWS and Red Hat. With a background in web development, I bridge the gap between design and technical implementation, turning designs into living, usable products. ## Automation & Releases @@ -31,6 +40,3 @@ I decided to build my own portfolio site on GitHub, rather than on a less code-o - [Eleventy Documentation](https://www.11ty.dev/docs/) - [11ty Recipes](https://11ty.recipes/) - [The 11ty Bundle](https://11tybundle.dev/) - -**Carousel pen by Siiron** -- [https://codepen.io/siiron/pen/QWwLoMy](https://codepen.io/siiron/pen/QWwLoMy)