www.shadoll/CLAUDE.md

Claude AI Instructions

This document contains instructions for AI assistants working on this project.

Project Overview

This is a static, animated placeholder page for the Shadoll project. It features configurable gradient backgrounds and SVG logo animations, designed to be deployed on GitHub Pages without any backend infrastructure.

Core Principles

1. Pure Frontend: No backend dependencies, all functionality in HTML/CSS/JavaScript
2. GitHub Pages Compatible: Must work as a static site
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

• index.html - Main entry point, minimal inline code
• css/styles.css - All styles and CSS animations
• js/app.js - Configuration parsing and JavaScript animation logic
• images/ - Static assets (SVG logo)
• *.md files - Documentation (always keep updated)

Documentation Requirements

IMPORTANT: Always update *.md files to reflect actual project state:

• README.md: Update when adding features, changing usage, or modifying deployment process
• TODO.md: Update when completing tasks, adding new tasks, or changing priorities
• CLAUDE.md: Update when adding new coding patterns, architectural decisions, or AI instructions

Code Style Guidelines

HTML

• Semantic HTML5 elements
• Minimal inline styles or scripts
• Accessible markup (ARIA labels where needed)
• Meta tags for SEO and social sharing

CSS

• BEM naming convention for classes
• 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)
• ES6+ syntax
• Modular code organization
• 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

CSS Animations

• Use @keyframes for repeating animations
• Use transition for state changes
• Combine transform properties in single declaration
• Use will-change sparingly for performance hints

JavaScript 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

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)

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&palette=default&logo=full&logoAnim=mixed&elementAnim=neon&speed=0.5

Default values when parameters are missing:

• bg: animated
• gradient: linear
• 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

• Commit related changes together
• Write descriptive commit messages
• Keep commits atomic and focused
• Don't commit generated files or dependencies

Testing Checklist

Before considering a feature complete:

• Test in Chrome, Firefox, Safari
• 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
• 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

• First paint: < 100ms
• Time to interactive: < 500ms
• Animation frame rate: 60fps
• No layout thrashing
• Minimal repaints/reflows

Future Considerations

When adding new features:

• Maintain backwards compatibility with existing URL parameters
• Keep bundle size minimal (no large dependencies)
• Ensure accessibility (keyboard navigation, screen readers)
• Add feature detection/progressive enhancement
• Document new parameters in README.md

Common Tasks

Adding a New Animation

1. Create CSS @keyframes in styles.css
2. Add animation class that applies keyframes
3. Add JavaScript logic in app.js to toggle class based on config
4. Update URL parameter documentation in README.md
5. Add task completion to TODO.md

Adding a New Color Palette

1. Create .palette--name class in 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 keyboard controls
4. Add palette to paletteNames mapping in toast message function
5. Document new palette in README.md and USAGE.md

Adding a New Gradient Type

1. Create CSS custom properties for gradient
2. Add gradient class in styles.css
3. Update configuration logic in app.js
4. Document new gradient type in 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
3. Look for long frames (>16ms)
4. Check for forced reflows/repaints
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 (README, TODO, CHANGELOG, USAGE, CLAUDE)
• Test changes in browser if possible
• Ask for clarification on ambiguous requirements
• Suggest performance optimizations
• 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