✨ enable upstream updates

CLAUDE.md

@@ -6,6 +6,106 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Sunday Comics is a Flask-based webcomic website with server-side rendering and client-side navigation. Comics are stored as individual YAML files in `data/comics/`, making them easy to manage without a database. Each comic gets its own file for clean organization and version control.
 
+## Fork-and-Customize Architecture
+
+**IMPORTANT:** Sunday Comics is designed for users to fork and customize for their own webcomics. When making changes, maintain the separation between framework code and user customization to avoid breaking upstream updates.
+
+### File Categories
+
+**Core Framework Files** (Updated by upstream - DO NOT modify unless fixing bugs):
+- `app.py` - Flask application logic
+- `data_loader.py` - YAML loading and caching
+- `templates/*.html` - Jinja2 templates
+- `static/css/style.css` - Core framework styles (references CSS variables)
+- `static/js/*.js` - Client-side navigation and functionality
+- `scripts/*.py` - Utility scripts
+- `version.py`, `VERSION` - Version management
+- `Dockerfile`, `docker-compose.yml` - Deployment configuration
+
+**User Customization Files** (Safe for users to modify):
+- `comics_data.py` - Global configuration settings
+- `static/css/variables.css` - Design variables (colors, fonts, spacing, layout)
+- `data/comics/*.yaml` - Comic metadata (except TEMPLATE.yaml)
+- `content/*.md` - Markdown content (about page, author notes, terms)
+- `static/images/*` - User's images and graphics
+
+**Template Files** (Reference only):
+- `comics_data.py.example` - Configuration template showing all options
+- `data/comics/TEMPLATE.yaml` - Comic file template
+
+**Generated Files** (Auto-created, gitignored):
+- `static/feed.rss`, `static/sitemap.xml` - Generated by scripts
+- `data/comics/.comics_cache.pkl` - Comic cache
+- `__pycache__/`, `*.pyc` - Python bytecode
+
+### CSS Architecture
+
+**Two-file CSS system** to separate customization from framework:
+
+1. **`static/css/variables.css`** (User customization)
+   - Contains all CSS custom properties
+   - Organized by category: Colors, Typography, Spacing, Borders, Layout, Transitions
+   - Users edit this file to customize their design
+   - Loaded first in templates
+
+2. **`static/css/style.css`** (Core framework)
+   - References variables from variables.css
+   - Contains structural styles and layout logic
+   - Should not be modified by users (to allow upstream updates)
+   - Loaded after variables.css
+
+**When modifying styles:**
+- Add new design tokens to `variables.css` (e.g., `--color-accent: #ff0000;`)
+- Reference those variables in `style.css` (e.g., `color: var(--color-accent);`)
+- Never hardcode values in `style.css` that users might want to customize
+
+### Configuration Pattern
+
+**`comics_data.py.example`** serves as a reference:
+- Shows all available configuration options with defaults
+- Updated when new settings are added to the framework
+- Users can check this file when merging upstream updates
+- Never imported - purely documentation
+
+**When adding new configuration options:**
+1. Add the option to `comics_data.py` with a default value
+2. Add the same option to `comics_data.py.example` with documentation
+3. Update `CHANGELOG.md` with migration instructions
+4. Consider backward compatibility (provide sensible defaults)
+
+### Best Practices for Code Changes
+
+**DO:**
+- ✅ Add new features to core framework files (app.py, templates, scripts)
+- ✅ Create new CSS variables in variables.css for customizable values
+- ✅ Update comics_data.py.example when adding new config options
+- ✅ Document breaking changes in CHANGELOG.md with migration steps
+- ✅ Test that user customizations (comics_data.py, variables.css) still work
+- ✅ Keep file structure consistent with the fork-friendly model
+
+**DON'T:**
+- ❌ Hardcode design values in style.css that users might want to change
+- ❌ Modify user content files (data/comics/*.yaml, content/*.md)
+- ❌ Change the purpose or structure of user customization files
+- ❌ Remove configuration options without deprecation warnings
+- ❌ Make changes that require users to edit core framework files
+
+**When adding new features:**
+1. Ask: "Will users want to customize this?"
+2. If yes: Add a variable/config option
+3. If no: Implement in framework code
+4. Always maintain the separation
+
+### Upstream Update Workflow
+
+Users following [UPSTREAM.md](UPSTREAM.md) will:
+1. Fork the repository
+2. Customize `comics_data.py` and `variables.css`
+3. Add their comics and content
+4. Periodically merge upstream updates: `git merge upstream/main`
+5. Resolve conflicts (usually only in .example files)
+6. Benefit from framework improvements without losing customizations
+
 ## Development Commands
 
 **Run the development server:**
@@ -224,6 +324,9 @@ Global context variables injected into all templates:
 
 ## Static Assets
 
+- `static/css/variables.css`: Design variables for user customization (colors, fonts, spacing, etc.)
+- `static/css/style.css`: Core framework styles (references variables.css)
+- `static/js/comic-nav.js`: Client-side navigation
 - `static/images/comics/`: Full-size comic images
 - `static/images/thumbs/`: Thumbnails for archive page (optional, same filename as comic)
 - `static/images/icons/`: Navigation icons (first.png, previous.png, next.png, latest.png) used when `USE_ICON_NAV` is True
@@ -280,7 +383,7 @@ Environment variables:
 Sunday Comics follows WCAG 2.1 Level AA guidelines. When modifying the site, maintain these accessibility features:
 
 ### Keyboard Navigation
-- **Focus indicators**: All interactive elements have visible 3px outlines when focused (defined in `static/css/style.css`)
+- **Focus indicators**: All interactive elements have visible 3px outlines when focused (colors defined in `static/css/variables.css`, styles in `static/css/style.css`)
 - **Skip to main content**: First focusable element on every page, appears at top when focused
 - **Keyboard shortcuts**: Arrow keys (Left/Right), Home, End for comic navigation (handled in `static/js/comic-nav.js`)
 - **Focus management**: After navigation, focus programmatically moves to `#comic-image-focus` element