/craft-site

name: craft-site
description: "Craft 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)."
when_to_use: "Triggers on: {% include ... only %}, {% embed %}, _atoms/_molecules/_organisms/_views/_builders, component--variant.twig, _component--props.twig, collect({}), utilities prop, data-brand theming, hero/card components, Matrix block rendering, craft.vite.script, vite.php, vite.config.ts, buildchain, per-page scripts, Blitz static/page caching, ImageOptimize, Imager-X, responsive images, srcset, image transforms, SEOmatic meta/OpenGraph/JSON-LD, Sprig, htmx, multi-language, hreflang, localization, Formie form styling, login/registration form, RSS/Atom/JSON feeds, XML sitemap, search page, .search(), headless GraphQL, Next.js/Nuxt/Astro integration, example-templates command, render builder, fluent BaseTag {{ tag.render() }}, progressive enhancement. Always use when creating, editing, or reviewing Craft front-end Twig templates, components, layouts, views, builders, buildchain, or front-end auth — including plugin template integration (Blitz, SEOmatic, Sprig, Formie, Imager-X). Do NOT trigger for PHP plugin/module development (craftcms) or content modeling (craft-content-modeling)."

Craft CMS 5 — Front-End Twig (Atomic Design)

Atomic design system patterns for Craft CMS 5 site templates. Vanilla Twig — no module dependency. Works with any Craft 5 project.

This skill is scoped to **front-end template architecture** — component design, routing, composition, theming, and buildchain. For extending Craft (plugins, modules, PHP), see the `craftcms` skill.

Companion Skills — Always Load Together

When this skill triggers, also load:

• **`craft-twig-guidelines`** — Twig coding standards: variable naming, null handling, whitespace control, include isolation, Craft helpers. Required for any Twig code.
• **`craft-content-modeling`** — Sections, entry types, fields, Matrix, relations. Required when deciding what content to query or how templates access data.
• **`ddev`** — All commands run through DDEV. Required for running Vite, npm, and Craft CLI commands.
• **`craft-cloud`** — When the site is hosted on Craft Cloud (detect via `craft-cloud.yaml` at the repo root or `craftcms/cloud` in `composer.json`). Required for edge static caching rules, `cloud.esi(...)` dynamic islands inside cached pages, edge image transform constraints, and the `csrfInput()` requirement on cacheable pages.
• **`servd`** — When the site is hosted on Servd (detect via `servd.yaml` at the repo root or `servd/craft-asset-storage` in `composer.json`). Required for Servd static caching, `{% dynamicInclude %}` islands in cached pages, running Blitz in reverse-proxy mode, and off-server image transforms.
• **`craft-fortrabbit`** — When the site is hosted on fortrabbit (detect via a `.fortrabbit/deploy.yml` deploy file or `FORTRABBIT_*` variables in config). Required for asset volumes and deployments, the queue and image transforms in a worker job, and the site URL from `FORTRABBIT_MAIN_DOMAIN`.

Documentation

• Twig in Craft: https://craftcms.com/docs/5.x/development/twig.html
• Template tags: https://craftcms.com/docs/5.x/reference/twig/tags.html
• Template functions: https://craftcms.com/docs/5.x/reference/twig/functions.html
• Twig 3 docs: https://twig.symfony.com/doc/3.x/

Use `WebFetch` on specific doc pages when a reference file doesn't cover enough detail.

Common Pitfalls (Cross-Cutting)

• Missing `only` on `{% include %}` — ambient variables leak in silently.
• Variant logic via conditionals (`{% if variant == 'x' %}`) instead of extends/block.
• Naming atoms by parent context (`hero-button`) instead of visual treatment (`button--primary`).
• `utilities` prop used as override — it's additive. Override via named-slot merge.
• Queries inside views — views receive data, they don't fetch it.
• Missing `.eagerly()` on relation fields in views — causes N+1 queries.
• Missing `devMode` fallback in builders for unknown block types.
• A CSP nonce, `csrfInput()`, active nav state or language switcher inside `{% cache %}`. The first render is replayed to everyone. See `template-caching.md`.
• Hardcoded Tailwind colors (`bg-yellow-600`) instead of brand tokens (`bg-brand-accent`).
• Mixing buttons and links — buttons are actions (resolve to `<a>`, `<button>`, or `<span>` from props), links are navigation (always `<a>`). Separate atom categories.
• Tracking/analytics inside components — decouple to data attributes at view/page level.
• Forgetting `project-config/touch` after editing YAML outside the CP — Git pulls, manual edits, and merge conflict resolution don't update `dateModified`. Run `ddev craft project-config/touch` then `ddev craft up`, or `craft up` on other environments won't detect the change.

Reference Files

Read the relevant reference file(s) for your task. Multiple files often apply together.

**Task examples:**

• "Build a new card component" → read `atomic-patterns.md` + `composition-patterns.md` + `component-inventory.md` + `tailwind-conventions.md`
• "Set up a new project's template structure" → read `boilerplate-routing.md` + `component-inventory.md`
• "Add a content builder for a Matrix field" → read `boilerplate-routing.md` + `composition-patterns.md`
• "Handle responsive images" → read `image-presets.md` + `plugins/image-optimize.md`
• "Cache the nav/footer with `{% cache %}`" → read `template-caching.md`
• "Scripts blocked by CSP / nonce mismatch after adding `{% cache %}`" → read `template-caching.md` (CSP Nonces)
• "First page view after upload is slow / why are images `generate-transform` URLs" → read `im