craft-site

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Craft CMS 5 — 前端Twig（原子设计）

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. For Twig coding standards (naming, null handling, whitespace, helpers), see

craft-twig-guidelines

. For PHP standards, see

craft-php-guidelines

. For content architecture (sections, fields, entry types), see

craft-content-modeling

适用于Craft CMS 5站点模板的原子设计系统模式。原生Twig — 无模块依赖，可在任何Craft 5项目中使用。

本技能的范围限定为前端模板架构 — 组件设计、路由、组合、主题化和构建链。如需扩展Craft功能（插件、模块、PHP），请参考

craftcms

技能。如需Twig编码规范（命名、空值处理、空格、辅助方法），请参考

craft-twig-guidelines

。如需PHP规范，请参考

craft-php-guidelines

。如需内容架构（分区、字段、条目类型），请参考

craft-content-modeling

。

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

web_fetch

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

Craft中的Twig：https://craftcms.com/docs/5.x/development/twig.html
模板标签：https://craftcms.com/docs/5.x/reference/twig/tags.html
模板函数：https://craftcms.com/docs/5.x/reference/twig/functions.html
Twig 3官方文档：https://twig.symfony.com/doc/3.x/

当参考文件覆盖的细节不足时，可以对特定文档页面使用

web_fetch

工具。

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.

```
{% include %}
```
缺少
```
only
```
修饰符 — 环境变量会静默泄露。
通过条件判断实现变体逻辑（
```
{% if variant == 'x' %}
```
），而非使用extends/block。
按父级上下文命名原子（如
```
hero-button
```
），而非按视觉样式命名（如
```
button--primary
```
）。
将
```
utilities
```
属性作为覆盖使用 — 它是追加属性，应通过命名插槽合并实现覆盖。
在视图中编写查询逻辑 — 视图只接收数据，不负责拉取数据。
视图中的关联字段缺少
```
.eagerly()
```
方法 — 会导致N+1查询问题。
构建器中缺少针对未知块类型的
```
devMode
```
降级逻辑。
硬编码Tailwind颜色（
```
bg-yellow-600
```
），而非使用品牌令牌（
```
bg-brand-accent
```
）。
混淆按钮和链接 — 按钮是操作元素（根据属性渲染为
```
<a>
```
、
```
<button>
```
或
```
<span>
```
），链接是导航元素（始终渲染为
```
<a>
```
），需分属不同的原子类别。
在组件中内置埋点/分析逻辑 — 应解耦到视图/页面层级的数据属性中。

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

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
```
+
```
atomic-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

Reference	Scope
`references/atomic-design.md`	Methodology: Brad Frost's atomic design principles, 5-to-3 tier compression, composability, context-agnostic naming, classification problem, decompose-downward workflow. Technology-independent.
`references/atomic-patterns.md`	Craft CMS implementation: props/extends/block pattern, button/link/text/icon atoms, molecule and organism composition, structural embed pattern, include/extends/embed decision table
`references/component-inventory.md`	Classification methodology: decision tree, naming conventions, file naming, props design, scaffold guidelines, tier promotion, audit checklist
`references/boilerplate-routing.md`	Template chain: layout hierarchy, Craft section template paths, global variables, routers, views, content builders, directory structure
`references/tailwind-conventions.md`	Class composition: named-key collections, standard key names, `utilities` prop, variant-based dark mode, spacing preference. Assumes Tailwind CSS — adapt patterns to your CSS framework.
`references/vite-buildchain.md`	Craft CMS Vite setup: nystudio107 plugin bridge, `config/vite.php` , `vite.config.ts` , `craft.vite.script()` , conditional per-page loading, Tailwind v4 integration, DDEV configuration
`references/image-presets.md`	Image handling: single atom with presets, srcset/sizes, ImageOptimize vs Craft Cloud, hosting strategies
`references/javascript-boundaries.md`	JS decision tree: Twig → Alpine/DataStar → Vue, mount points, data handoff, coexistence rules
`references/twig-collections.md`	`collect()` method reference: creating, accessing, transforming, filtering, sorting, slicing, arrow functions
`references/third-party-integration.md`	Script loading order, CMP (UserCentrics/CookieBot), GTM/sGTM data layer, analytics (Fathom/Plausible), AWS SES transport, n8n webhooks, Blitz compatibility, full head template example

根据你的任务阅读相关参考文件，通常多个文件会同时适用。

任务示例：

"构建新的卡片组件" → 阅读

atomic-patterns.md

component-inventory.md

tailwind-conventions.md

"搭建新项目的模板结构" → 阅读

boilerplate-routing.md

component-inventory.md

"为Matrix字段添加内容构建器" → 阅读
```
boilerplate-routing.md
```
+
```
atomic-patterns.md
```

"处理响应式图片" → 阅读

image-presets.md

plugins/image-optimize.md

"添加多品牌主题能力" → 阅读
```
tailwind-conventions.md
```
"为功能选型Alpine或Vue" → 阅读
```
javascript-boundaries.md
```
"组合Tailwind类避免冲突" → 阅读
```
tailwind-conventions.md
```
+
```
twig-collections.md
```
"了解原子设计方法论" → 阅读
```
atomic-design.md
```
"在新Craft项目中配置Vite + Tailwind" → 阅读
```
vite-buildchain.md
```
"调试生产环境资源加载失败问题" → 阅读
```
vite-buildchain.md
```
"在Craft项目中安装GTM/分析工具/CMP" → 阅读
```
third-party-integration.md
```
"为分区配置SEOMatic" → 阅读
```
plugins/seomatic.md
```
"配置Blitz缓存与Cloudflare集成" → 阅读
```
plugins/blitz.md
```
"为页面添加表单" → 阅读
```
plugins/formie.md
```
"配置支持嵌套条目的CKEditor" → 阅读
```
plugins/ckeditor.md
```
"构建导航菜单" → 阅读
```
plugins/navigation.md
```
"为组件添加链接字段" → 阅读
```
plugins/hyper.md
```
"配置站点重定向规则" → 阅读
```
plugins/retour.md
```
"为条目添加重复日期能力" → 阅读
```
plugins/timeloop.md
```
"创建JSON API端点" → 阅读
```
plugins/element-api.md
```
"调试模板中的N+1查询问题" → 阅读
```
plugins/elements-panel.md
```
"执行安全审计" → 阅读
```
plugins/sherlock.md
```
"将YouTube/Vimeo视频作为资源嵌入" → 阅读
```
plugins/embedded-assets.md
```

"配置SES邮件投递" → 阅读

plugins/amazon-ses.md

third-party-integration.md

参考文件	适用范围
`references/atomic-design.md`	方法论：Brad Frost的原子设计原则、5层到3层压缩、可组合性、上下文无关命名、分类问题、自上而下拆解工作流，技术无关。
`references/atomic-patterns.md`	Craft CMS实现：props/extends/block模式、按钮/链接/文本/图标原子、分子与有机体组合、结构嵌入模式、include/extends/embed选型表
`references/component-inventory.md`	分类方法论：决策树、命名规范、文件命名、属性设计、脚手架指引、层级升级、审核检查清单
`references/boilerplate-routing.md`	模板链：布局层级、Craft分区模板路径、全局变量、路由器、视图、内容构建器、目录结构
`references/tailwind-conventions.md`	类组合：命名键集合、标准键名、 `utilities` 属性、基于变体的深色模式、间距偏好。基于Tailwind CSS编写，可适配你的CSS框架。
`references/vite-buildchain.md`	Craft CMS Vite配置：nystudio107插件桥接、 `config/vite.php` 、 `vite.config.ts` 、 `craft.vite.script()` 、单页条件加载、Tailwind v4集成、DDEV配置
`references/image-presets.md`	图片处理：带预设的单一原子、srcset/sizes、ImageOptimize与Craft Cloud对比、托管策略
`references/javascript-boundaries.md`	JS选型决策树：Twig → Alpine/DataStar → Vue、挂载点、数据传递、共存规则
`references/twig-collections.md`	`collect()` 方法参考：创建、访问、转换、过滤、排序、切片、箭头函数
`references/third-party-integration.md`	脚本加载顺序、CMP（UserCentrics/CookieBot）、GTM/sGTM数据层、分析工具（Fathom/Plausible）、AWS SES传输、n8n webhook、Blitz兼容性、完整头部模板示例

Plugin References

插件参考

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

references/plugins/

Reference	Plugin	Key Surface
`references/plugins/seomatic.md`	SEOMatic (nystudio107)	Meta cascade, Twig get/set API, JSON-LD, custom element SEO bundles, sitemaps, GraphQL
`references/plugins/blitz.md`	Blitz (putyourlightson)	Refresh modes, Twig dynamic content, driver architecture (storage/purger/deployer), Nginx rewrite, Cloudflare integration
`references/plugins/formie.md`	Formie (verbb)	Form rendering (one-line/granular), theme config for Tailwind, submission querying, hooks, integrations
`references/plugins/image-optimize.md`	ImageOptimize (nystudio107)	OptimizedImages field, `imgTag()` / `pictureTag()` builders, loading strategies, transform methods, console commands
`references/plugins/ckeditor.md`	CKEditor (craftcms)	Toolbar config, nested entries with chunk rendering, HTML Purifier, custom styles, Redactor migration
`references/plugins/colour-swatches.md`	Colour Swatches (craftpulse)	Palette config, multi-colour swatches, Tailwind class mapping, Twig model API
`references/plugins/password-policy.md`	Password Policy (craftpulse)	Validation rules, HIBP check, retention/expiry, console commands, recommended settings
`references/plugins/hyper.md`	Hyper (verbb)	Link types, `getLinkAttributes()` , `getText()` , single/multi-link, element access, button atom integration
`references/plugins/retour.md`	Retour (nystudio107)	Redirect types (exact/regex), 404 tracking, CSV import, auto slug-change redirects, config
`references/plugins/navigation.md`	Navigation (verbb)	Node querying, custom rendering, active states, custom fields on nodes, GraphQL
`references/plugins/typogrify.md`	Typogrify (nystudio107)	`\|typogrify` , `\|widont` , `\|truncateOnWord` , smart quotes, widow prevention
`references/plugins/cache-igniter.md`	Cache Igniter (putyourlightson)	GlobalPing warmer, geographic locations, refresh delay, Blitz companion
`references/plugins/knock-knock.md`	Knock Knock (verbb)	Staging password protection, environment-aware config, URL exclusions
`references/plugins/timeloop.md`	Timeloop (craftpulse)	Repeating date field, `craft.timeloop` variable API, `recurringDates()` function, GraphQL, period frequencies
`references/plugins/element-api.md`	Element API (craftcms)	JSON API via config file, Fractal transformers, endpoint routing, pagination, caching
`references/plugins/elements-panel.md`	Elements Panel (putyourlightson)	Debug toolbar panels for element population counts, duplicate detection, eager-loading opportunities
`references/plugins/sherlock.md`	Sherlock (putyourlightson)	Security scanning, HTTP headers, CMS config checks, scheduled scans, IP restriction, monitoring
`references/plugins/embedded-assets.md`	Embedded Assets (spicyweb)	oEmbed as first-class assets, `craft.embeddedAssets.get()` , iframe customization, GraphQL
`references/plugins/amazon-ses.md`	Amazon SES (putyourlightson)	SES mail transport adapter, AWS credential config, SNS bounce tracking

Craft插件的详细配置、Twig API和常见陷阱，位于

references/plugins/

目录下。

参考文件	插件	核心覆盖范围
`references/plugins/seomatic.md`	SEOMatic (nystudio107)	Meta层叠、Twig get/set API、JSON-LD、自定义元素SEO包、站点地图、GraphQL
`references/plugins/blitz.md`	Blitz (putyourlightson)	刷新模式、Twig动态内容、驱动架构（存储/清除器/部署器）、Nginx重写、Cloudflare集成
`references/plugins/formie.md`	Formie (verbb)	表单渲染（单行/细粒度）、Tailwind主题配置、提交查询、钩子、集成
`references/plugins/image-optimize.md`	ImageOptimize (nystudio107)	OptimizedImages字段、 `imgTag()` / `pictureTag()` 构建器、加载策略、转换方法、控制台命令
`references/plugins/ckeditor.md`	CKEditor (craftcms)	工具栏配置、支持分块渲染的嵌套条目、HTML Purifier、自定义样式、Redactor迁移
`references/plugins/colour-swatches.md`	Colour Swatches (craftpulse)	调色板配置、多色样本、Tailwind类映射、Twig模型API
`references/plugins/password-policy.md`	Password Policy (craftpulse)	校验规则、HIBP检查、留存/过期、控制台命令、推荐设置
`references/plugins/hyper.md`	Hyper (verbb)	链接类型、 `getLinkAttributes()` 、 `getText()` 、单/多链接、元素访问、按钮原子集成
`references/plugins/retour.md`	Retour (nystudio107)	重定向类型（精确/正则）、404追踪、CSV导入、slug变更自动重定向、配置
`references/plugins/navigation.md`	Navigation (verbb)	节点查询、自定义渲染、激活状态、节点自定义字段、GraphQL
`references/plugins/typogrify.md`	Typogrify (nystudio107)	`\|typogrify` 、 `\|widont` 、 `\|truncateOnWord` 、智能引号、孤行预防
`references/plugins/cache-igniter.md`	Cache Igniter (putyourlightson)	GlobalPing预热、地理位置、刷新延迟、Blitz配套工具
`references/plugins/knock-knock.md`	Knock Knock (verbb)	staging环境密码保护、环境感知配置、URL排除
`references/plugins/timeloop.md`	Timeloop (craftpulse)	重复日期字段、 `craft.timeloop` 变量API、 `recurringDates()` 函数、GraphQL、周期频率
`references/plugins/element-api.md`	Element API (craftcms)	基于配置文件的JSON API、Fractal转换器、端点路由、分页、缓存
`references/plugins/elements-panel.md`	Elements Panel (putyourlightson)	调试工具栏面板，支持元素填充计数、重复检测、预加载优化提示
`references/plugins/sherlock.md`	Sherlock (putyourlightson)	安全扫描、HTTP头、CMS配置检查、定时扫描、IP限制、监控
`references/plugins/embedded-assets.md`	Embedded Assets (spicyweb)	oEmbed作为一等资源、 `craft.embeddedAssets.get()` 、iframe自定义、GraphQL
`references/plugins/amazon-ses.md`	Amazon SES (putyourlightson)	SES邮件传输适配器、AWS凭证配置、SNS退信追踪

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>

, fallback →

<span>

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

target="_blank"

rel="noopener noreferrer"

, external icon, and sr-only text when a URL is external.

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 %}

— see

atomic-patterns.md

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

所有项目使用统一的标准组件系统。原子是上下文无关的 — 始终按视觉样式命名，绝不按父级上下文命名。HTML元素类型通过属性推导（

url

→

<a>

、

type

→

<button>

、降级为

<span>

）。

外部链接检测自动通过URL判断，无需作为属性传入。当URL为外部链接时，组件会自动添加

target="_blank"

、

rel="noopener noreferrer"

、外部图标和屏幕阅读器专用文本。

FontAwesome是通用图标系统，图标通过FA类名字符串传入。

视觉变体使用extends/block实现 — 基础模板定义结构，变体覆盖样式类。绝不要使用条件逻辑切换变体样式。对于带内容插槽的结构骨架，使用

{% embed %}

— 参考

atomic-patterns.md

。

图片处理使用单一原子配合配置驱动的预设，而非为每个上下文单独创建变体文件。

CSS & Theming Conventions

CSS与主题规范

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

prop is additive (extending), not overriding. Override specific concerns via named-slot merge.

Multi-brand theming uses CSS custom properties activated by

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

<html>

. Components reference semantic Tailwind classes (

bg-brand-accent

) resolved via CSS variables. Template-level brand overrides only exist when the HTML structure itself differs between brands — not for color/font/spacing differences.

Token naming follows three layers: primitives (

--brand-{color}-{shade}

), semantics (

--brand-{purpose}

), and framework mapping (

--color-brand-{purpose}

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

本技能的类组合示例基于Tailwind CSS编写，你可以将模式适配到你的CSS框架 — 架构原则（命名键、追加工具类、语义令牌）是框架无关的。

类集合按样式维度使用命名键 — 这是避免冲突的核心机制。

utilities

属性是追加（扩展）属性，而非覆盖属性，需通过命名插槽合并覆盖特定维度的样式。

多品牌主题使用CSS自定义属性实现，通过

<html>

标签上的

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

激活。组件引用语义化Tailwind类（

bg-brand-accent

），通过CSS变量解析。仅当不同品牌的HTML结构本身存在差异时，才在模板层级做品牌覆盖 — 颜色/字体/间距差异不需要。

令牌命名遵循三层结构：原语（

--brand-{color}-{shade}

）、语义（

--brand-{purpose}

）、框架映射（

--color-brand-{purpose}

）。

Tailwind v4的级联层无法解决同一工具层内的类冲突，仍需要使用命名键集合。

Routing Conventions

路由规范

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

collect()

is used for both props and class building. The full Collection API is available in Twig via Craft.

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

PHP负责数据处理，Twig负责展示层。视图通过include接收数据 — 绝不自行查询数据。

collect()

同时用于属性和类构建，Twig中可以通过Craft使用完整的Collection API。

JS边界遵循决策树：默认使用Twig → UI状态需求使用Alpine/DataStar → 应用级状态需求使用Vue。