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

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.

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

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.

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

• "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" → 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

references/atomic-design.md

references/atomic-patterns.md

references/composition-patterns.md

references/component-inventory.md

references/boilerplate-routing.md

references/tailwind-conventions.md

utilities

references/vite-buildchain.md

config/vite.php

vite.config.ts

craft.vite.script()

references/image-presets.md

references/javascript-boundaries.md

references/twig-collections.md

collect()

references/third-party-integration.md

references/multi-site-patterns.md

references/auth-flows.md

references/auth-account.md

references/search.md

references/feeds.md

references/headless.md

Plugin References

Detailed configuration, Twig API, and pitfalls for Craft plugins. Located in

references/plugins/

references/plugins/seomatic.md

references/plugins/blitz.md

references/plugins/formie.md

references/plugins/image-optimize.md

imgTag()

pictureTag()

references/plugins/ckeditor.md

references/plugins/sprig.md

references/plugins/colour-swatches.md

references/plugins/password-policy.md

references/plugins/hyper.md

getLinkAttributes()

getText()

references/plugins/retour.md

references/plugins/navigation.md

references/plugins/typogrify.md

|typogrify

|widont

|truncateOnWord

references/plugins/cache-igniter.md

references/plugins/knock-knock.md

references/plugins/timeloop.md

craft.timeloop

recurringDates()

references/plugins/element-api.md

references/plugins/elements-panel.md

references/plugins/sherlock.md

references/plugins/embedded-assets.md

craft.embeddedAssets.get()

references/plugins/amazon-ses.md

references/plugins/feed-me.md

references/plugins/imager-x.md

Component System Conventions

One canonical component system across all projects. Atoms are context-agnostic — always named by visual treatment, never by parent. HTML element type is resolved from props (

url

<a>

type

<button>

<span>

External link detection is derived from the URL, never passed as a prop. Components auto-apply

target="_blank"

rel="noopener noreferrer"

FontAwesome is the universal icon system. Icons are passed as FA class strings.

Visual variants use extends/block — base template defines structure, variant overrides classes. Never use conditional logic to switch between variant styles. For structural skeletons with content slots, use

{% embed %}

composition-patterns.md

Image handling uses a single atom with config-driven presets, not separate variant files per context.

CSS & Theming Conventions

This skill assumes Tailwind CSS for class composition examples. Adapt patterns to your CSS framework — the architectural principles (named keys, additive utilities, semantic tokens) are framework-agnostic.

Class collections use named keys per style concern — this is the primary mechanism for preventing conflicts. The

utilities

Multi-brand theming uses CSS custom properties activated by

data-brand="{{ currentSite.handle }}"

<html>

bg-brand-accent

Token naming follows three layers: primitives (

--brand-{color}-{shade}

--brand-{purpose}

--color-brand-{purpose}

Tailwind v4 cascade layers don't fix class conflicts within the same utilities layer. Named-key collections remain necessary.

Routing Conventions

PHP handles data, Twig handles presentation. Views receive data through includes — they never query it themselves.

collect()

The JS boundary follows a decision tree: Twig is the default → Alpine/DataStar for UI state → Vue for application state.