Astro Images Skill Skill

Astro Images Skill

Authority: If any instruction conflicts with this skill, follow this skill.

Core Principle

Pattern = rendered width. Aspect ratio is independent. Browser downloads: sizes CSS px × device DPR

Container queries: approximate using viewport breakpoints. Never omit sizes.

Pattern Reference

| Pattern | Width | widths | sizes | |---------|-------|--------|-------| | FULL | 100vw | [640,750,828,1080,1200,1920,2048,2560] | 100vw | | TWO_THIRDS | 66vw | [384,640,768,1024,1280,1706,2048] | (min-width:1024px) 66vw, 100vw | | LARGE | 60vw | [384,640,768,1024,1280,1536,1920] | (min-width:1024px) 60vw, 100vw | | HALF | 50vw | [320,640,960,1280,1600] | (min-width:1024px) 50vw, 100vw | | SMALL | 40vw | [256,512,640,1024,1280] | (min-width:1024px) 40vw, 100vw | | THIRD | 33vw | [256,512,640,853,1280] | (min-width:1024px) 33vw, (min-width:640px) 50vw, 100vw | | QUARTER | 25vw | [192,384,512,640,960] | (min-width:1024px) 25vw, (min-width:640px) 50vw, 100vw | | FIFTH | 20vw | [160,320,512,640,768] | (min-width:1024px) 20vw, (min-width:640px) 33vw, 50vw | | SIXTH | 16vw | [128,256,427,512,640] | (min-width:1024px) 16vw, (min-width:640px) 33vw, 50vw |

Unknown layout → default to HALF

Layout → Pattern Mapping

| Layout | Pattern | |--------|---------| | Full-bleed hero | FULL | | Split 66/33, 60/40 (image side) | TWO_THIRDS, LARGE | | Split 50/50, checkerboard | HALF | | Split 40/60 (text dominant) | SMALL | | 3-col grid, standing person | THIRD | | 4-col team grid | QUARTER | | 5-col icons, 6-col logos | FIFTH, SIXTH | | Logo, avatar, icon | FIXED |

Aspect ratio is independent — portrait 2:3 at 50% width = HALF pattern.

LCP Priority

Hero (1 only): loading="eager" fetchpriority="high" | Above-fold (2-3): loading="eager" | Below-fold: lazy (default)

Template (Copy-Paste)

<Picture
  src={image}
  widths={[/* from table */]}
  sizes="/* from table */"
  formats={['avif', 'webp']}
  quality={60}
  width={/* intrinsic */}
  height={/* intrinsic */}
  alt="Descriptive text"
  decoding="async"
/>

Add loading="eager" fetchpriority="high" only to ONE hero image (remove decoding on hero).

FIXED Pattern (logos, avatars)

---
import { getImage } from 'astro:assets';
const img1x = await getImage({ src: logo, width: 200, quality: 80 });
const img2x = await getImage({ src: logo, width: 400, quality: 60 });
---
<img src={img1x.src} srcset={`${img1x.src} 1x, ${img2x.src} 2x`} width="200" height="50" alt="Logo" />

Default: 1× + 2× only. 3× allowed only for icons ≥64px where fidelity matters.

Ten Rules

Pattern = rendered width (use table above)
Every <Picture> needs widths + sizes + quality={60} + formats={['avif','webp']}
Every image needs dimensions (explicit or inferred from Astro asset import)
Images in /src/assets/ — never /public/
Only ONE fetchpriority="high" per page — never in loops
sizes must match CSS layout — no defensive 100vw
Use exact arrays from table — no custom/computed/dynamic widths
Preserve aspect ratio — no cropping without art direction
Alt text: descriptive for content, alt="" only for decorative
Unknown layout → HALF pattern

Raw <img> allowed only for: FIXED pattern, SVGs, external URLs.

Pre-Output Checklist

[ ] Pattern matches width? | Width array exact? | sizes matches CSS? | width/height present?
[ ] quality={60}? | fetchpriority="high" max once, not in loop? | Image from /src/assets/?

If any NO → fix before outputting.

Forbidden

<Picture> for SVGs (use <img>) | Animated GIF/APNG (use <video>) | CSS backgrounds for LCP
Images in /public/ | Upscaling sources | Dynamic/computed width arrays

Undersized Source Fallback

If source < pattern minimum: cap widths array at source width, keep sizes unchanged, flag for replacement. Example: 1200px source for HALF → widths={[320,640,960,1200]} (removed 1280,1600) Exception: FULL/LCP images — undersized is ERROR, must provide larger asset.

Source Minimums

Schema Images (Google)

3 versions in /src/assets/schema/: 1:1 (1200×1200), 4:3 (1200×900), 16:9 (1200×675) Reference in schema AND og:image.

Cloudflare Adapter Configuration

Critical: Cloudflare Workers/Pages does NOT support Sharp at runtime. Without proper config, no images will be optimized.

Wrong (no optimization):

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});
// ⚠️ [WARN] Cloudflare does not support sharp at runtime
// Result: Only original JPGs in dist, no AVIF/WebP

Correct (build-time optimization):

export default defineConfig({
  output: 'static',
  adapter: cloudflare({
    imageService: 'compile'
  }),
  image: {
    service: {
      entrypoint: 'astro/assets/services/sharp'
    }
  }
});

Key settings:

output: 'static' → Build-time generation (SSR pages use prerender: false)
imageService: 'compile' → Optimize at build, not runtime
image.service.entrypoint → Use Sharp for build-time processing

Verify after build:

ls dist/_astro/*.avif | head -5  # Should show AVIF files
ls dist/_astro/*.webp | head -5  # Should show WebP files

Validation

find public -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.webp" \) 2>/dev/null
grep -r "<Picture" src --include="*.astro" | grep -v "widths="
grep -r "fetchpriority" src --include="*.astro" | grep -E "\.(map|forEach)\("

Agent Skills: Astro Images Skill

Install this agent skill to your local

Skill Files