michtio/craftcms-claude-skills/craft-site

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 image-presets.md (Transform Generation Timing) + 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
• "Can't override a plugin's front-end CSS / plugin styles beat mine" → read third-party-integration.md (Plugin CSS Loads After Yours)
• "Replace a plugin's template with my own / plugin widget stopped enhancing" → read third-party-integration.md (Hand-Written Templates for Plugin Widgets)
• "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" → read search.md (Rebuilding)
• "Create an RSS feed" → read feeds.md
• "Build an XML sitemap" → read feeds.md (XML Sitemap)
• "Create a JSON Feed" → read feeds.md (JSON Feed)
• "Set up a headless Craft CMS with Next.js" → read headless.md
• "Fix GraphQL preview tokens" → read headless.md
• "Consume Craft GraphQL API from a front-end framework" → read headless.md
• "Use entry.render() for reusable card components" → read element-partials.md
• "Set up _partials/ templates for entries" → read element-partials.md
• "Render Matrix blocks with partials" → read element-partials.md
• "Ship example templates with a plugin (bundle + install command)" → read example-templates.md
• "Build a fluent front-end render/tag builder (craft.<handle>.thing().render())" → read example-templates.md

Plugin References