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

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
• Mobile-first responsive design
• Prefer CSS animations over JavaScript where possible
• Use transform and opacity for performant animations

JavaScript

• Vanilla JavaScript (no frameworks)
• ES6+ syntax
• Modular code organization
• Comments for complex logic
• URL parameter parsing for configuration
• Fallbacks for missing parameters

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
• Throttle/debounce event handlers
• Clean up animations on page unload
• Provide reduced-motion alternatives

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)

When animating:

• Full-body animations apply to the entire SVG container
• Internal animations target individual paths within the SVG
• Maintain aspect ratio and viewBox
• Use CSS classes for animation states

Configuration System

URL parameters should follow this pattern:

?bg=animated&gradient=linear&logo=full&logoAnim=shake&elementAnim=neon

Default values when parameters are missing:

• bg: animated
• gradient: linear
• logo: animated
• logoAnim: all
• elementAnim: neon

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
• Verify smooth 60fps performance
• Check with reduced motion preferences
• Validate HTML/CSS
• Test all URL parameter combinations
• Update documentation

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 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

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

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
• Test changes in browser if possible
• Ask for clarification on ambiguous requirements
• Suggest performance optimizations
• Consider mobile and accessibility
• Keep solutions simple and maintainable