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.

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.