Skip to content

CLAUDE.md

Latest commit

 

History

History
205 lines (171 loc) · 9.53 KB

CLAUDE.md

File metadata and controls

205 lines (171 loc) · 9.53 KB
Raw

Planet Nix Website - Project Documentation

Important: This file and README.md should always be kept in sync. When updating project information, documentation, or development workflow in one file, make sure to update the other accordingly.

Project Overview

This is a single-page website for Planet Nix, built with simplicity in mind - no build steps required. Optimized for performance with a Lighthouse score of 91/100.

Technology Stack

Core Technologies

  • HTML5: Semantic markup for the single-page structure in index.html
  • Pico CSS: Minimal, elegant CSS framework
    • Classless semantic CSS framework
    • Responsive by default with mobile-first design
    • Built-in dark mode support
    • Beautiful typography out of the box
    • No utility classes needed - uses semantic HTML

Development Tools

  • Flox: Reproducible development environment
    • Handles all environment setup and dependencies
    • Ensures consistent development environment across machines
  • Just: Command runner for common tasks
    • just dev - Start development server
    • just perf - Check performance
    • just lighthouse - Run full audit
  • livereload: Automatic browser refresh during development
  • Lighthouse: Performance monitoring and CI

Project Structure

planetnix-website/
├── index.html              # Main single-page website (with inlined CSS)
├── assets/                 # All website resources
│   ├── css/
│   │   └── pico.min.css   # Pico CSS framework
│   ├── fonts/             # Local fonts (Geist, Geist Mono)
│   ├── images/            # Source images (PNGs, SVGs)
│   │   └── generated/     # Generated images (WebP, responsive sizes)
│   └── js/                # JavaScript files (if needed)
├── Justfile               # Command runner recipes with inline docs
├── .github/workflows/     # CI/CD automation
│   └── lighthouse-pr.yml  # Automated performance testing
├── CLAUDE.md              # Project documentation for AI assistants
└── README.md              # User-facing documentation

Assets Folder

All extra resources needed for the website should be placed in the assets/ folder:

  • assets/css/ - CSS stylesheets (Pico CSS only; custom styles are inlined in index.html for performance)
  • assets/fonts/ - Local font files (Geist 400/700, Geist Mono 400 - only critical weights)
  • assets/images/ - Source images (PNG, SVG) and icons
    • Source PNGs are optimized using pngquant and optipng
    • Total size reduced from 2.3 MB to 556 KB
    • DO NOT manually edit files in generated/ folder
  • assets/images/generated/ - Generated/optimized images (automatically created)
    • WebP versions of all source PNGs
    • Responsive image sizes (480w, 768w, 1024w) for background images
    • Lazy loading for below-the-fold images
    • This folder is regenerated by just regenerate-all-images
  • assets/js/ - JavaScript files for interactivity (minimal)

Development Workflow

Quick Start

# 1. Enter the development environment
flox activate

# 2. Start the development server (managed by Flox services)
flox services start

# 3. Edit index.html - changes reload automatically

# 4. Stop the server when done
flox services stop

Common Tasks

Important: Development server is managed by Flox services, not Just commands.

# Development Server (Flox Services)
flox activate                                   # Enter environment first
flox services start                             # Start dev server (http://localhost:8888)
flox services stop                              # Stop dev server
flox services status                            # Check server status

# Just Commands (run within Flox environment)
flox activate -- just                           # List all available commands
flox activate -- just perf                      # Quick performance check (91/100 current)
flox activate -- just lighthouse                # Full performance audit with HTML report
flox activate -- just lighthouse-mobile         # Mobile performance test
flox activate -- just optimize-images           # Re-optimize source PNG images in-place
flox activate -- just generate-responsive-images # Create responsive image sizes in generated/
flox activate -- just generate-favicons         # Generate all favicon and app icons
flox activate -- just regenerate-all-images     # Regenerate ALL images (WebP + responsive)
flox activate -- just clean                     # Remove generated reports

Alternatively, activate the Flox shell first, then run commands directly:

flox activate
# Shows environment info and available commands automatically

# Now you can run commands directly:
flox services start
just perf
just lighthouse
flox services stop

Performance Testing

  • Local: Start server with flox services start, then use just perf before committing
  • CI/CD: Automated Lighthouse tests on every PR
  • Comparison: CI compares PR performance vs base branch
  • Reports: Posted as PR comments with score deltas
  • Note: Lighthouse commands require the dev server to be running

Git Workflow

Commit Guidelines

  • No Claude attribution: Do not include any Claude-related attribution in commit messages or pull requests
    • No "🤖 Generated with Claude Code" footer
    • No "Co-Authored-By: Claude" lines
    • Keep commit messages clean and professional

Pull Request Guidelines

  • No test plans: Do not include test plans or testing checklists in PR descriptions
    • Keep PR descriptions concise and focused on the changes made
    • Describe what was changed and why, not how to test it

Image Workflow

Source vs Generated Images

  • Source images (assets/images/): Original PNGs and SVGs
    • Edit and optimize these files when you need to change images
    • Use just optimize-images to optimize source PNGs in-place
  • Generated images (assets/images/generated/): Auto-generated WebP and responsive sizes
    • NEVER manually edit files in this folder
    • Regenerate with just regenerate-all-images or just generate-responsive-images
    • These files are referenced in index.html for optimal loading

Adding New Images

  1. Add source PNG/SVG to assets/images/
  2. Optimize it: flox activate -- just optimize-images
  3. Regenerate all optimized versions: flox activate -- just regenerate-all-images
  4. Update index.html to reference the new image (use generated/ for WebP versions)

Updating Favicons

  1. Replace assets/images/planetnix-logo-small.png with your new logo
  2. Regenerate all favicons: flox activate -- just generate-favicons
  3. All favicon and app icons will be updated in assets/images/generated/

Design Philosophy

  • No build process: Direct HTML and CSS for maximum simplicity
  • Single-page design: All content accessible from one page
  • Semantic styling: Pico CSS uses semantic HTML, no utility classes
  • Performance first: Every optimization counts
  • Separation of source and generated: Source images in assets/images/, generated in assets/images/generated/
    • Images: 2.3 MB → 556 KB (76.6% reduction)
    • Initial load: Only 139 KB of images (lazy loading)
    • CSS inlined: Custom styles inlined to eliminate render-blocking requests
    • Lighthouse score: 91/100
  • Reproducible environment: Flox ensures consistent setup across machines
  • Automated quality: CI/CD prevents performance regressions

Performance Optimizations

Implemented

  • ✅ Image optimization: pngquant + optipng (76.6% size reduction)
    • Source images in assets/images/ (PNGs, SVGs)
    • Generated images in assets/images/generated/ (WebP, responsive sizes)
    • Regenerate all with just regenerate-all-images
  • ✅ Responsive images: Multiple sizes (480w, 768w, 1024w, 1280w) for adaptive loading
    • Why responsive? Saves 142 KB on mobile by serving appropriately sized images
    • Background images use srcset to load optimal size based on viewport
    • Generated using just generate-responsive-images command
    • Smaller images for mobile (480w: ~15KB) vs desktop (1280w: ~100KB)
    • All generated files placed in assets/images/generated/
  • ✅ Lazy loading: Below-the-fold images load on demand
  • ✅ Explicit image dimensions: All images have width/height attributes
    • Why? Prevents layout shift (CLS) during page load
    • CSS ensures responsiveness: max-width: 100%; height: auto;
    • Browser calculates aspect ratio from dimensions, CSS controls display size
  • ✅ CSS inlining: Custom styles (11.4 KB) inlined in HTML to eliminate render-blocking request
    • Why inlined? Eliminates 700ms render-blocking network request, improves FCP and LCP
    • Pico CSS (22 KB) remains external as it's cached and essential for semantic styling
  • ✅ Font optimization: Only critical font weights loaded (Geist 400/700, Geist Mono 400)
    • Reduced from 18 font files to 3, eliminating 100+ KB of unused fonts
    • Preloaded with fetchpriority="high" for faster discovery
    • Using font-display: swap to prevent invisible text
  • ✅ LCP optimization: Hero moon image with fetchpriority="high" and preload hint
  • ✅ Zero layout shift (CLS: 0): Inline CSS + explicit image dimensions prevent FOUC
  • ✅ Semantic HTML: No unnecessary divs or classes

Monitoring

  • GitHub Actions: Automated Lighthouse audits on every PR
  • Performance tracking: Score comparisons show impact of changes
  • Just commands: Easy local testing before pushing