feat: add major new features including 6 color palettes, interactive logo mode, and mobile-first improvements

CLAUDE.md

@@ -13,6 +13,7 @@ This is a static, animated placeholder page for the Shadoll project. It features
 3. **Performance First**: Smooth 60fps animations, minimal resource usage
 4. **Configuration Flexibility**: URL parameters for customization
 5. **Progressive Enhancement**: Works without JavaScript, enhanced with it
+6. **Mobile-First Design**: Unified approach for all devices, optimized for touch and small screens
 
 ## File Structure Rules
 
@@ -40,10 +41,12 @@ This is a static, animated placeholder page for the Shadoll project. It features
 
 ### CSS
 - BEM naming convention for classes
-- CSS custom properties for theming
-- Mobile-first responsive design
+- CSS custom properties for theming (palettes, animation speed)
+- Mobile-first responsive design (single unified solution for all devices)
 - Prefer CSS animations over JavaScript where possible
 - Use `transform` and `opacity` for performant animations
+- Liquid glass UI: `backdrop-filter: blur(40px) saturate(180%)`
+- Never use conflicting transform properties in media queries
 
 ### JavaScript
 - Vanilla JavaScript (no frameworks)
@@ -52,6 +55,10 @@ This is a static, animated placeholder page for the Shadoll project. It features
 - Comments for complex logic
 - URL parameter parsing for configuration
 - Fallbacks for missing parameters
+- Event delegation for touch-enabled controls
+- Clean up event listeners on controller stop
+- Use closures for stateful controllers (interactive tilt)
+- Auto-detection of input methods (cursor vs gyroscope)
 
 ## Animation Guidelines
 
@@ -62,36 +69,71 @@ This is a static, animated placeholder page for the Shadoll project. It features
 - Use `will-change` sparingly for performance hints
 
 ### JavaScript Animations
-- Use `requestAnimationFrame` for smooth animations
+- Use `requestAnimationFrame` for smooth animations (not currently used)
 - Throttle/debounce event handlers
 - Clean up animations on page unload
 - Provide reduced-motion alternatives
+- Interactive animations: Direct style manipulation for real-time responsiveness
+- Idle detection: Use `setTimeout` to return to default state after inactivity
+- Controller pattern: Return object with `start()` and `stop()` methods
 
 ## SVG Logo Structure
 
-The logo consists of two main elements:
-- `#shadoll_l` - The "L" shape (black, `#222`)
-- `#shadoll_s` - The "S" shape (red, `#dc2108`, contains 2 path elements)
+### Logo Design
+The logo represents the letters "s" and "d" extracted from "shadoll" ({s}ha{d}oll), designed as geometric shapes divided into sections:
+- Left element: "s" shape (represented by `#shadoll_s` in SVG)
+- Right element: "d" shape (represented by `#shadoll_l` in SVG)
 
-When animating:
-- Full-body animations apply to the entire SVG container
-- Internal animations target individual paths within the SVG
-- Maintain aspect ratio and viewBox
+**Note**: The naming convention reflects the letter shapes - `l` in the path name comes from "{d}oll", while `s` comes from "{s}ha".
+
+### SVG Elements
+- `#shadoll_l` - Single path element for the right "d" shape (default: `#222` black)
+- `#shadoll_s` - Group containing 2 path elements for the left "s" shape (default: `#dc2108` red)
+
+### Color Guidelines
+- **Two-color scheme** (recommended): The "s" paths (`#shadoll_s`) should use one consistent color, the "d" path (`#shadoll_l`) uses another
+- **Single-color scheme**: Both elements can use the same color for monochrome effect
+- When creating color palettes, maintain color consistency within the "s" element (both paths same color)
+
+### Animation Structure
+- Full-body animations apply to the entire SVG container (`#logo`)
+- Internal animations target individual elements (`#shadoll_s`, `#shadoll_l`)
+- Element animations can target individual paths within `#shadoll_s` group
+- Maintain aspect ratio and viewBox proportions
 - Use CSS classes for animation states
 
+### ViewBox Approach (Mobile-First)
+**CRITICAL**: Logo sizing uses a unified viewBox for all devices:
+- Single `viewBox="-200 -200 900 900"` for all screen sizes
+- Logo paths are ~510 units → 510/900 = ~57% of screen
+- **Never** use CSS `scale()` transforms for sizing (conflicts with animations)
+- **Never** use separate viewBoxes for mobile/tablet/desktop
+- Adjust viewBox size to change logo size: smaller viewBox = larger logo
+- Set viewBox dynamically via JavaScript in `setupViewBox()` function
+
 ## Configuration System
 
 URL parameters should follow this pattern:
 ```
-?bg=animated&gradient=linear&logo=full&logoAnim=shake&elementAnim=neon
+?bg=animated&gradient=linear&palette=default&logo=full&logoAnim=mixed&elementAnim=neon&speed=0.5
 ```
 
 Default values when parameters are missing:
 - `bg`: `animated`
 - `gradient`: `linear`
-- `logo`: `animated`
-- `logoAnim`: `all`
+- `palette`: `default`
+- `logo`: `full`
+- `logoAnim`: `mixed` (changed from `tilt` in v2.0.0)
 - `elementAnim`: `neon`
+- `speed`: `0.5` (range: 0.1-5.0)
+
+### Available Options
+
+**Palettes**: `default`, `blue-yellow`, `dark`, `light`, `fire`, `nature`
+
+**Logo Animations**: `shake`, `rotate`, `tilt`, `interactive`, `mixed`, `all`
+- `interactive`: Logo follows cursor (desktop) or gyroscope (mobile)
+- `mixed`: Auto tilt + interactive on movement (2s idle timeout)
 
 ## Git Workflow
 
@@ -104,12 +146,16 @@ Default values when parameters are missing:
 
 Before considering a feature complete:
 - [ ] Test in Chrome, Firefox, Safari
-- [ ] Test on mobile devices
+- [ ] Test on mobile devices (iOS Safari, Chrome Mobile)
+- [ ] Test gyroscope on real mobile device (not emulator)
+- [ ] Test touch controls (tap kbd buttons in help)
 - [ ] Verify smooth 60fps performance
 - [ ] Check with reduced motion preferences
 - [ ] Validate HTML/CSS
 - [ ] Test all URL parameter combinations
-- [ ] Update documentation
+- [ ] Verify help button is at bottom-right on all screen sizes
+- [ ] Check logo visibility on mobile (~60% of screen)
+- [ ] Update all documentation (README, TODO, CHANGELOG, USAGE, CLAUDE)
 
 ## Performance Targets
 
@@ -137,12 +183,30 @@ When adding new features:
 4. Update URL parameter documentation in [README.md](README.md)
 5. Add task completion to [TODO.md](TODO.md)
 
+### Adding a New Color Palette
+1. Create `.palette--name` class in [styles.css](css/styles.css)
+2. Define 4 CSS custom properties: `--gradient-color-1` through `--gradient-color-4`
+3. Add palette name to `palettes` array in [app.js](js/app.js) keyboard controls
+4. Add palette to `paletteNames` mapping in toast message function
+5. Document new palette in [README.md](README.md) and [USAGE.md](USAGE.md)
+
 ### Adding a New Gradient Type
 1. Create CSS custom properties for gradient
 2. Add gradient class in [styles.css](css/styles.css)
 3. Update configuration logic in [app.js](js/app.js)
 4. Document new gradient type in [README.md](README.md)
 
+### Adding Interactive Controls (Cursor/Gyroscope)
+1. Create controller function with closure pattern (returns `{start, stop}`)
+2. Store state variables: `isActive`, `mode`, timing trackers
+3. Implement auto-switching logic with timeout (1s default)
+4. Add `mousemove` handler for cursor tracking
+5. Add `deviceorientation` handler for gyroscope
+6. Request iOS permission if needed (`DeviceOrientationEvent.requestPermission`)
+7. For mixed mode: Add idle detection with `setTimeout` (2s default)
+8. Clean up all event listeners in `stop()` method
+9. Store controller globally: `window.interactiveTiltController`
+
 ### Debugging Animation Performance
 1. Open Chrome DevTools > Performance
 2. Record animation sequence
@@ -151,14 +215,48 @@ When adding new features:
 5. Optimize by using `transform`/`opacity` only
 6. Add `will-change` if needed
 
+## Architectural Decisions (v2.0.0)
+
+### Mobile-First ViewBox Strategy
+- **Problem**: Logo was tiny on mobile (~10% of screen) with CSS scaling
+- **Solution**: Unified `viewBox="-200 -200 900 900"` for all devices via JavaScript
+- **Why**: CSS `scale()` conflicts with animations; single viewBox simplifies codebase
+- **Result**: Logo at ~57% of screen (510 units / 900 viewBox) on all devices
+
+### Interactive Mode Auto-Switching
+- **Problem**: Need both cursor (desktop) and gyroscope (mobile) in one mode
+- **Solution**: Time-based auto-switching with 1-second timeout
+- **Why**: Detects active input method without manual switching
+- **Implementation**: Track `lastCursorTime` and `lastGyroTime`, switch to most recent
+
+### Mixed Mode Idle Detection
+- **Problem**: Users want auto animation but also interactive control
+- **Solution**: Tilt animation by default, becomes interactive on movement, returns after 2s idle
+- **Why**: Best of both worlds - attractive animation + user engagement
+- **Implementation**: Class toggling (`logo--tilt` ↔ `logo--interactive`) with `setTimeout`
+
+### Touch-Enabled kbd Elements
+- **Problem**: Mobile users can't use keyboard shortcuts
+- **Solution**: Make kbd buttons clickable, dispatch synthetic keyboard events
+- **Why**: Consistent UX across desktop and mobile
+- **Implementation**: `data-key` attributes + click handlers + `KeyboardEvent` dispatch
+
+### Liquid Glass UI Design
+- **Decision**: Apple-style frosted glass for help and toasts
+- **Why**: Modern, premium feel that matches animated aesthetic
+- **Implementation**: `backdrop-filter: blur(40px) saturate(180%)` + gradient backgrounds
+
 ## AI Assistant Best Practices
 
 When working on this project:
 - Always read existing files before suggesting changes
 - Maintain consistency with existing code style
-- Update all relevant documentation
+- Update all relevant documentation (README, TODO, CHANGELOG, USAGE, CLAUDE)
 - Test changes in browser if possible
 - Ask for clarification on ambiguous requirements
 - Suggest performance optimizations
-- Consider mobile and accessibility
+- Consider mobile and accessibility (touch targets, gyroscope, screen readers)
 - Keep solutions simple and maintainable
+- **NEVER** use CSS `scale()` for logo sizing - use viewBox instead
+- **NEVER** add duplicate/conflicting position properties in media queries
+- **ALWAYS** clean up event listeners when stopping controllers