2 min read
Image Handling
Claude’s default image handling is often basic — images stretch, load all at once, and don’t adapt to screen sizes. Drop this into projects that display images (portfolios, galleries, mood boards) to get proper image treatment.
Filename: image-handling.md
The Skill File
Copy this into a file called image-handling.md in your project root, next to your CLAUDE.md.
# Image Handling Conventions
Follow these conventions for all image display in this project. Images are often the most important visual element — handle them with care.
## Aspect Ratios
- Never distort images. Use `object-fit: cover` or `object-fit: contain`
- Use the CSS `aspect-ratio` property for consistent containers
- For thumbnails, always crop to a consistent ratio (e.g., 4:3, 16:9, 1:1)
## Lazy Loading
- Add `loading="lazy"` to all images below the fold
- First visible images (hero, above-fold) should load eagerly
- Add `width` and `height` attributes to prevent layout shift
## Responsive Images
- Use `srcset` for multiple image sizes when available
- Use the `<picture>` element for art direction (different crops at different sizes)
- Don't serve desktop-sized images to mobile devices
## Placeholders
- Show a subtle background color matching the image's dominant tone while loading
- Use skeleton animations (shimmer effect) for image-heavy layouts
- Never show a broken image icon — always provide a fallback
## Gallery Patterns
- Use CSS Grid for equal-size grids
- Use `columns` or masonry layout for Pinterest-style grids
- Add gap between images (8-16px typical)
- Make images clickable to view full-size
## User Uploads
- Validate file type (accept only image formats)
- Show a preview before saving
- Set reasonable file size limits (5-10MB typical)
- Compress or resize on the client side when possibleWhen to Use This
Add this to any project that displays images — portfolios, mood boards, galleries, or any app where visuals are a key part of the design.