# Images

## Principles

1. Prefer `next/image` for all meaningful raster images.
2. Reserve space (width/height or sized `fill` parent) to prevent layout shift.
3. Lazy-load below-the-fold images; prioritize true LCP hero assets.
4. Stay within brand radius tokens.

## Aspect ratios

| Use | Ratio | Notes |
| --- | --- | --- |
| Hero atmosphere | fluid / full bleed | `object-cover`, tall crops OK |
| Blog / content figures | intrinsic | `w-full h-auto` in `.blog-content` |
| Cards / thumbnails | `aspect-video` or `aspect-[4/3]` | Keep consistent within a grid |
| Avatars | `1:1` | `rounded-full` |
| Logos (marquee) | intrinsic height | Use `LogoItem` patterns |

Use `AspectRatio` from `@/components/ui/aspect-ratio` when the box must stay stable before load.

## Object-fit

| Value | When |
| --- | --- |
| `object-cover` | Photos filling a fixed frame |
| `object-contain` | Logos, diagrams that must not crop |
| `object-center` / logical positions | Adjust focal point; prefer `object-center` unless art-directed |

## Radius

| Token | Class | Use |
| --- | --- | --- |
| Default | `rounded-md` / `rounded-xl` | UI media |
| Blog | `rounded-blog` | WP images / blockquotes |
| Pill | `rounded-full` | Avatars only |

Marketing image frames use `media-frame` (surface border + brand neon via `--elevation-glow-media`). Prefer that over ad-hoc `border` + `shadow-surface-*` on homepage media.

`.wp-block-image` already applies `rounded-blog overflow-hidden shadow-sm`.

## Lazy loading & placeholders

- Default `next/image` lazy loading for non-priority images.
- Set `priority` only on the primary LCP image.
- Always pass meaningful `sizes` (e.g. `100vw`, `(max-width: 768px) 100vw, 33vw`).
- Blur placeholder: use when a `blurDataURL` exists; otherwise rely on solid surface behind the image.

## Alt text

- Informative images: concise Persian (or English in `/en`) alt describing content.
- Decorative images: `alt=""` and/or `aria-hidden` on wrapper.
- Never put SEO keyword stuffing in alt.

## Floating / decorative images

- Absolute decorative photos must live inside a clipped section (`section-shell` / `overflow-hidden`).
- Do not float images that overlap interactive controls.
- Avoid random rotated polaroid stacks unless an existing block already defines that pattern.

## Forbidden

- Unsized `<img>` causing CLS.
- Inconsistent radii in the same card grid.
- Full-quality 4K backgrounds without `sizes` / quality tuning.

## Related

- [hero.md](./hero.md)
- [cards.md](./cards.md)
- [responsive.md](./responsive.md)