craft-site
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). 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, nystudio107, buildchain, per-page scripts, Blitz static/page/dynamic 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, |rss, |atom, search page, .search(), headless GraphQL queries, preview tokens, Next.js/Nuxt/Astro integration. Always use when creating, editing, or reviewing Craft front-end Twig templates, components, layouts, views, builders, buildchain configuration, 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).
git clone --depth 1 https://github.com/michtio/craftcms-claude-skills /tmp/craft-site && cp -r /tmp/craft-site/skills/craft-site ~/.claude/skills/craft-siteSKILL.md
# 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.
## 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.
- 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`
- "Add multi-brand theming" → read `tailwind-conventions.md`
- "Decide between Alpine and Vue for a feature" → read `javascript-boundaries.md`
- "Compose Tailwind classes without conflicts" → read `tailwind-conventions.md` + `twig-collections.md`
- "Understand atomic design methodology" → read `atomic-design.md`
- "Set up Vite + Tailwind in a new Craft project" → read `vite-buildchain.md`
- "Debug why assets aren't loading in production" → read `vite-buildchain.md`
- "Look up a `craft.vite.*` Twig function (asset, register, critical CSS)" → read `plugins/vite.md`
- "Install GTM/analytics/CMP in a Craft project" → read `third-party-integration.md`
- "Configure SEOMatic for a section" → read `plugins/seomatic.md`
- "Set up Blitz caching with Cloudflare" → read `plugins/blitz.md`
- "Add a form to a page" → read `plugins/formie.md`
- "Configure CKEditor with nested entries" → read `plugins/ckeditor.md`
- "Build a navigation menu" → read `plugins/navigation.md`
- "Add a link field to a component" → read `plugins/hyper.md`
- "Set up redirects for a site" → read `plugins/retour.md`
- "Add recurring/repeating dates to entries" → read `plugins/timeloop.md`
- "Create a JSON API endpoint" → read `plugins/element-api.md`
- "Debug N+1 queries in templates" → read `plugins/elements-panel.md`
- "Run a security audit" → read `plugins/sherlock.md`
- "Embed a YouTube/Vimeo video as an asset" → read `plugins/embedded-assets.md`
- "Configure email delivery via SES" → read `plugins/amazon-ses.md` + `third-party-integration.md`
- "Build a language switcher" → read `multi-site-patterns.md`
- "Add login/registration to the front end" → read `auth-flows.md`
- "Build a user profile edit page" → read `auth-account.md`
- "Set up password reset flow" → read `auth-flows.md`
- "Set up hreflang tags" → read `multi-site-patterns.md`
- "Plan a multi-language site architecture" → read `multi-site-patterns.md`
- "Add live search without JavaScript" → read `plugins/sprig.md`
- "Build reactive filtering or load-more" → read `plugins/sprig.md`
- "Import data from an external feed" → read `plugins/feed-me.md`
- "Set up responsive images with Imager-X" → read `plugins/imager-x.md`
- "Build a search page" → read `search.md`
- "Configure search settings" → read `search.md` (Search Configuration)
- "Rebuild the search index" →Deep code review on Opus 4.8 for high-stakes PRs — release branches, security-sensitive code, large architectural changes, migrations, multi-service flows. Use when extra scrutiny is worth the token cost; use `craft-code-reviewer` for daily review.
Reviews implemented code for quality, security, and Craft CMS conventions
Tracks down bugs in Craft CMS plugins with systematic investigation
Builds new features in Craft CMS plugins following project architecture
Breaks down large tasks into manageable implementation steps for Craft CMS plugin development
Builds Craft CMS site templates, components, and content architecture
Craft Cloud — Pixel & Tonic's serverless hosting platform for Craft CMS. Covers craft-cloud.yaml configuration, the Build → Migrate → Release deploy pipeline, the craftcms/cloud extension package, edge image transforms via Cloudflare, edge static caching with cache.rules + ESI, Cloud-managed S3 filesystem, MySQL 8 / Postgres 15 databases (no MariaDB, no tablePrefix), Console-based command runner and scheduled cron (once-per-hour minimum), auto-handled queue jobs, custom domains and SSL, preview environments per branch, Cloud limitations (ephemeral filesystem, no SSH, no .htaccess, no built-in mail), plugin development requirements for Cloud compatibility, and self-hosted → Cloud migration. Triggers on: craft-cloud.yaml, craftcms/cloud package, cloud.esi(), php craft cloud/up, php craft cloud/setup, App::isEphemeral(), CRAFT_EPHEMERAL, edge.craft.cloud, preview.craft.cloud, CRAFT_CLOUD_PROJECT_ID, CRAFT_CLOUD_ENVIRONMENT_ID, CRAFT_CLOUD_CDN_BASE_URL, Build → Migrate → Release, Cloud filesystem, Cloud-compatible plugin, Cloudflare Images at edge, AssetsFs, static-caching rules, ESI islands, deploy to Craft Cloud, migrate to Craft Cloud, self-hosted to Cloud, Craft Cloud quotas, Craft Cloud regions. Do NOT trigger for Servd (use the servd skill) or generic Craft deployment on Forge/bare metal (craftcms/deployment.md). Do NOT trigger for general DDEV local dev unrelated to Cloud parity.
Craft CMS 5 content modeling — sections, entry types, fields, Matrix, relations, project config, and content architecture strategy. Covers everything editors and developers need to structure content in Craft: choosing section types, designing entry types and field layouts, selecting field types for specific needs, configuring Matrix and nested entries, setting up relations and eager loading, and planning multi-site propagation. Triggers on: section types (single, channel, structure), entry types, field types, field layout design, field type selection, Matrix configuration, nested entries, relatedTo, eager loading, .with(), .eagerly(), categories, tags, globals, global sets, preloadSingles, propagation, multi-site content, URI format, project config, YAML, content architecture, content strategy, taxonomy, asset volumes, filesystems, image transforms, user groups, content permissions, entries-as-taxonomy, entrify, entrification, CKEditor vs Matrix, CMS editions, site propagation, multi-language, language groups, localization, translation method, field translation, content migration, reserved handles, field instances. Always use when planning content architecture, creating sections/fields, configuring Matrix, setting up relations, choosing field types, designing field layouts, making content modeling decisions, or planning multi-site content propagation. Do NOT trigger for PHP plugin/module development, custom field type code, front-end Twig templates, or buildchain configuration.