michtio/craftcms-claude-skills / skills/craft-site
craft-site
VerifiedCraft CMS 5 front-end Twig development — atomic design, template architecture, components, Vite buildchain. Covers atoms/molecules/organisms, props/extends/block patterns, layout chains, view routing, content builders, image presets, Tailwind named-key collections, multi-brand CSS tokens, JavaScript boundaries (Alpine/DataStar/Vue, tabs, accordions), Vite asset loading, and front-end auth (login, registration, password reset, profiles).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| references/atomic-design.md | markdown | 11.1 KB |
| references/atomic-patterns.md | markdown | 12.3 KB |
| references/auth-account.md | markdown | 18.1 KB |
| references/auth-flows.md | markdown | 22.5 KB |
| references/boilerplate-routing.md | markdown | 14.7 KB |
| references/component-inventory.md | markdown | 11.4 KB |
| references/composition-patterns.md | markdown | 14.5 KB |
| references/element-partials.md | markdown | 7.9 KB |
| references/example-templates.md | markdown | 14.2 KB |
| references/feeds.md | markdown | 8.4 KB |
| references/headless.md | markdown | 15.4 KB |
| references/image-presets.md | markdown | 14.0 KB |
| references/javascript-boundaries.md | markdown | 12.4 KB |
| references/multi-site-patterns.md | markdown | 13.2 KB |
| references/search.md | markdown | 10.3 KB |
| references/tailwind-conventions.md | markdown | 6.8 KB |
| references/template-caching.md | markdown | 14.2 KB |
| references/third-party-integration.md | markdown | 8.6 KB |
| references/twig-collections.md | markdown | 8.2 KB |
| references/vite-buildchain.md | markdown | 9.3 KB |
references/image-presets.md
View on GitHub# Image Presets Reference
> One image atom, many presets. Config-driven responsive images.
## Documentation
- Craft image transforms: https://craftcms.com/docs/5.x/development/image-transforms.html
- `generateTransformsBeforePageLoad`: https://craftcms.com/docs/5.x/reference/config/general.html#generatetransformsbeforepageload
- `runQueueAutomatically`: https://craftcms.com/docs/5.x/reference/config/general.html#runqueueautomatically
- `{% cache %}` and temporary transform URLs: https://craftcms.com/docs/5.x/reference/twig/tags.html#cache
- ImageOptimize plugin: https://nystudio107.com/docs/image-optimize/
- Responsive images (MDN): https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
The transform docs page does not describe when a transform is generated. The timing below comes from the `craftcms/cms` 5.11.5.1 source:
- `ImageTransformer::getTransformUrl()`: https://github.com/craftcms/cms/blob/5.11.5.1/src/imagetransforms/ImageTransformer.php
- `AssetsController::actionGenerateTransform()`: https://github.com/craftcms/cms/blob/5.11.5.1/src/controllers/AssetsController.php
- `GenerateImageTransform` job: https://github.com/craftcms/cms/blob/5.11.5.1/src/queue/jobs/GenerateImageTransform.php
- `Queue::push()` / `handleResponse()`: https://github.com/craftcms/cms/blob/5.11.5.1/src/queue/Queue.php
## Common Pitfalls
- Hardcoded dimensions in templates — never write `width: 800` directly in a view. Always go through presets.
- Missing alt text fallback chain — always: explicit alt → asset alt field → asset title → empty string.
- `loading="eager"` everywhere — only the first visible image (above-fold hero) should be eager. Everything else is lazy.
- Missing `sizes` attribute — without it, the browser downloads the largest srcset image regardless of viewport.
- Provider lock-in — don't call ImageOptimize API directly in views. The image atom abstracts the provider.
- Multiple image variant files — use one atom with presets, not `image--hero.twig`, `image--teaser.twig`, etc.
- Turning on `generateTransformsBeforePageLoad` to "fix" `generate-transform` URLs — it moves every missing transform (and, with ImageOptimize on the Craft transform method, every optimizer and WebP run) into the page request. A preset with 5 widths plus a WebP `<source>` is 10 transforms per image. Leave it `false` on the front end; see [Transform Generation Timing](#transform-generation-timing).
- Treating `generate-transform` URLs in the HTML as a bug — they are Craft's default for transforms that do not exist yet, and they resolve to the real file on the next request.
- A strict CSP with `runQueueAutomatically` on — a page that queues a transform job gets an inline `<script>` with no nonce injected before `</body>`. The CSP blocks it and the queue is not kicked from that page.
## The Single Image Atom
Instead of multiple image variant files, one universal atom with a preset parameter.
### Props File
```twig
{# _atoms/images/_image--props.twig #}
{# Preset definitions — widths, sizes, loading strategy, aspect ratio #}
{%- set presets = {
hero: {
widths: [640, 960, 1280, 1920, 2560],
sizes: '100vw',
loading: 'eager',
ratio: null,
},
teaser: {
widths: [300, 450, 600, 900],
sizes: '(min-width: 1024px) 33vw, 100vw',
loading: 'lazy',
ratio: 'aspect-[16/9]',
},
content: {
widths: [400, 600, 900, 1200],
sizes: '(min-width: 1024px) 50vw, 100vw',
loading: 'lazy',
ratio: null,
},
profile: {
widths: [150, 300, 450],
sizes: '150px',
loading: 'lazy',
ratio: 'aspect-square',
},
branding: {
widths: [200, 400],
sizes: '200px',
loading: 'lazy',
ratio: null,
},
gallery: {
widths: [400, 600, 900, 1200, 1800],
sizes: '(min-width: 1024px) 50vw, 100vw',
loading: 'lazy',
ratio: null,
},
} -%}
{%- set config = presets[preset ?? 'content'] ?? presets.content -%}
{%- set props = collect({
image: image ?? null,
alt: alt ?? null,
config: config,
ratio: ratio ?? config.ratio ?? null,
loading: config.loading,
utilities: utilities ?? null,
}) -%}
{%- block image -%}{%- endblock -%}
```
### Variant File
```twig
{# _atoms/images/image--responsive.twig #}
{%- extends '_atoms/images/_image--props' -%}
{%- block image -%}
{%- set asset = props.get('image') -%}
{%- if asset -%}
{%- set alttext = props.get('alt') ?? asset.alt ?? asset.title -%}
{%- set classes = collect({
display: 'block w-full h-auto',
ratio: props.get('ratio'),
fit: props.get('ratio') ? 'object-cover' : null,
utilities: props.get('utilities'),
}) -%}
{# With ImageOptimize plugin #}
{%- if asset.optimizedImages is defined -%}
<picture>
{%- if asset.optimizedImages.srcsetWebp() -%}
{{ tag('source', {
type: 'image/webp',
srcset: asset.optimizedImages.srcsetWebp(),
sizes: props.get('config').sizes,
}) }}
{%- endif -%}
{{ tag('img', {
class: classes.implode(' '),
src: asset.optimizedImages.src(),
srcset: asset.optimizedImages.srcset(),
sizes: props.get('config').sizes,
alt: alttext,
loading: props.get('loading'),
width: asset.width,
height: asset.height,
style: asset.optimizedImages.placeholderBox() ? {
'background-image': "url('" ~ asset.optimizedImages.placeholderImage() ~ "')",
'background-size': 'cover',
} : false,
}) }}
</picture>
{# With Craft Cloud / native transforms #}
{%- else -%}
{%- set webpSrcset = props.get('config').widths|map(w =>
asset.getUrl({ width: w, format: 'webp' }) ~ ' ' ~ w ~ 'w'
)|join(', ') -%}
{%- set srcset = props.get('config').widths|map(w =>
asset.getUrl({ width: w }) ~ ' ' ~ w ~ 'w'
)|join(', ') -%}
<picture>
{{ tag('source', {
type: 'image/webp',
srcset: webpSrcset,
sizes: props.get('config').sizes,
}) }}
{{ tag('img', {
class: classes.implode(' '),
src: asset.getUrl({ width: props.get('config').widths|last }),
srcset: srcset,
sizes: props.get('config').sizes,
alt: alttext,
loading: props.get('loading'),
width: asset.width,
height: asset.height,
}) }}
</picture>
{%- endif -%}
{%- endif -%}
{%- endblock -%}
```
## Preset Definitions
| Preset | Use Case | Widths | Sizes | Loading |
|--------|----------|--------|-------|---------|
| `hero` | Full-width hero images | 640–2560 | `100vw` | `eager` |
| `teaser` | Card thumbnails, grid items | 300–900 | `33vw` at desktop | `lazy` |
| `content` | Inline content images | 400–1200 | `50vw` at desktop | `lazy` |
| `profile` | Author photos, avatars | 150–450 | `150px` | `lazy` |
| `branding` | Logos, partner logos | 200–400 | `200px` | `lazy` |
| `gallery` | Gallery/lightbox images | 400–1800 | `50vw` at desktop | `lazy` |
### Preset Naming
Lowercase context names: `hero`, `teaser`, `content`, `profile`, `branding`, `gallery`.
### Adding Project-Specific Presets
Add to the `presets` hash in `_image--props.twig`:
```twig
{%- set presets = presets|merge({
floorplan: {
widths: [600, 900, 1200],
sizes: '(min-width: 768px) 50vw, 100vw',
loading: 'lazy',
ratio: null,
},
}) -%}
```
## Calling the Image Atom
```twig
{# Standard usage #}
{%- include '_atoms/images/image--responsive' with {
image: entry.heroImage.eagerly().one(),
preset: 'hero',
} only -%}
{# With alt text override #}
{%- include '_atoms/images/image--responsive' with {
image: entry.teamPhoto.one(),
preset: 'profile',
alt: entry.memberName,
utilities: 'rounded-full',
} only -%}
{# With aspect ratio override #}
{%- include '_atoms/images/image--responsive' with {
image: entry.thumbnail.one(),
preset: 'teaser',
ratio: 'aspect-[4/3]',
} only -%}
```
## Hosting / Transform Strategies
| Strategy | When to use | Notes |
|----------|-------------|-------|
| **ImageOptimize plugin** | VPS / Servd hosting | Full srcset/webp generation at upload. Best quality control. Not compatible with Craft Cloud. |
| **Craft Cloud transforms** | Craft Cloud hosting | Native Craft transforms. Craft Cloud intercepts and serves via Cloudflare Images — no special template syntax needed. See the `craft-cloud` skill's `assets-and-transforms.md` for the edge transform limits (70MB, 100MP, 12,000px max). |
| **Small Pics / Cloudflare Images** | External transform service | URL-based. Best for CDN-first architectures. |
The image atom handles both paths. It checks for the `optimizedImages` field
handle (ImageOptimize plugin) and falls back to native Craft transforms via
`asset.getUrl()`. On Craft Cloud, these native transforms are automatically
served through Cloudflare Images — the template code is identical either way.
## Transform Generation Timing
Applies to native Craft transforms on self-hosted sites (Forge, VPS, shared hosting, fortrabbit, Servd's local transforms). On Craft Cloud the edge generates transforms, so none of this runs on your server.
`generateTransformsBeforePageLoad`: default `false`. The docs say only "Whether image transforms should be generated before page load." What each value does, from `ImageTransformer::getTransformUrl()`:
| | `false` (default) | `true` |
|---|---|---|
| Transform already exists | Real file URL | Real file URL |
| Transform missing, page request | Returns a temporary URL `{actionTrigger}/assets/generate-transform?transformId=N` (default trigger `actions`). Also pushes a `GenerateImageTransform` queue job "in case the temp URL never gets requested" (priority 2048), and sets no-cache headers on the page response. | Generates the file inline before the page renders. If another request is generating the same transform, it polls once a second for up to 30 seconds. |
| Who pays for generation | The first browser request for that image (`AssetsController::actionGenerateTransform()` generates it, then redirects to the file), or the queue job, whichever runs first | The page request |
| First visit to a page with N missing transforms | Page renders quickly. N separate image requests, each running PHP. | Page waits for all N transforms. On a small shared host, a gallery or listing page can hit `max_execution_time`. |
**`false` is the right default for the front end.** Keep it unless something consumes the HTML outside a browser and cannot follow a redirect. Craft already forces it on for those cases: GraphQL responses (`GraphqlController`) and outgoing email (`Mailer`) both switch it on for the duration of the request.
Side effects of `false` to know about:
- **`{% cache %}` will not store a block with a temporary URL in it.** The docs: the tag "holds off caching the template until the next request so those temporary image URLs aren't cached." A cached block with new images renders uncached until its transforms exist. See `template-caching.md`.
- **The page response carries no-cache headers** while any transform on it is missing. Blitz, a CDN or a reverse proxy that honours `Cache-Control` will not store that response. The next request after generation is cacheable.
- **Every missing transform also queues a job.** With `runQueueAutomatically` on (the default), a site request that pushed a job gets an inline script appended before `</body>` that XHRs `actions/queue/run` (`Queue::handleResponse()`). The queue then runs inside a web PHP worker. That script has no nonce, so under a strict CSP it is blocked; the jobs wait for the next CP visit or a CLI runner. See the `craft-plugins` skill's `image-optimize.md`, "Queue Runner", for the cron alternative.
**With ImageOptimize installed on the Craft transform method,** every transform Craft generates also runs ImageOptimize's optimizers and WebP variant creator in the same process. That happens in the page request (`true`), the image request or queue job (`false`), or the queue job that resaves an OptimizedImages field. ImageOptimize also has its own setting with the same name, `generateTransformsBeforePageLoad` (default `true`), which forces Craft's setting on just for the URLs it builds. See the `craft-plugins` skill's `image-optimize.md`, "Request-Time Cost".
**Pre-generating instead of turning it on:** if you want no generate URLs on launch day, create the transforms ahead of time. For OptimizedImages fields, run `ddev craft image-optimize/optimize/create`. For transforms requested from templates, Craft core has no "generate all transforms" console command. Request every page once: a crawler, Blitz's cache warmer, or Cache Igniter. With a CLI queue runner in place, the queued `GenerateImageTransform` jobs finish the rest even if the image URLs are never requested.
## A11y Requirements
- `alt` is always required. Fallback chain: explicit `alt` prop → asset `alt` field → asset `title`.
- Decorative images: pass `alt: ''` explicitly. Never omit.
- `loading="eager"` only on hero/above-fold images. Everything else is `lazy`.
- `width` and `height` always rendered to prevent CLS.
## DS Module Vision (Future)
With the `craft.ds` module, image rendering collapses to:
```twig
{{ craft.ds.image(entry.heroImage.one(), 'hero') }}
```
The PHP service resolves the preset, detects the hosting environment, generates the `<picture>` element, and handles all transform logic server-side. The vanilla Twig approach documented here is the foundation that the module will formalize.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |