michtio/craftcms-claude-skills / skills/craft-site
craft-site
VerifiedCraft 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| references/atomic-design.md | markdown | 11.1 KB |
| references/atomic-patterns.md | markdown | 12.3 KB |
| references/auth-account.md | markdown | 18.1 KB |
| references/auth-flows.md | markdown | 22.5 KB |
| references/boilerplate-routing.md | markdown | 14.7 KB |
| references/component-inventory.md | markdown | 11.4 KB |
| references/composition-patterns.md | markdown | 14.5 KB |
| references/element-partials.md | markdown | 7.9 KB |
| references/example-templates.md | markdown | 14.2 KB |
| references/feeds.md | markdown | 8.4 KB |
| references/headless.md | markdown | 15.4 KB |
| references/image-presets.md | markdown | 14.0 KB |
| references/javascript-boundaries.md | markdown | 12.4 KB |
| references/multi-site-patterns.md | markdown | 13.2 KB |
| references/search.md | markdown | 10.3 KB |
| references/tailwind-conventions.md | markdown | 6.8 KB |
| references/template-caching.md | markdown | 14.2 KB |
| references/third-party-integration.md | markdown | 8.6 KB |
| references/twig-collections.md | markdown | 8.2 KB |
| references/vite-buildchain.md | markdown | 9.3 KB |
references/tailwind-conventions.md
View on GitHub# Tailwind Conventions Reference
> How Tailwind CSS classes are composed and managed in Twig templates.
> Assumes Tailwind CSS — adapt class patterns to your CSS framework.
> The architectural patterns (named keys, additive utilities) are framework-agnostic.
## Documentation
- Tailwind CSS v4: https://tailwindcss.com/docs
- CSS custom properties: https://developer.mozilla.org/en-US/docs/Web/CSS/--*
## Common Pitfalls
- Hardcoded colors — never `bg-yellow-600`. Always `bg-brand-accent`. Colors
come from tokens (see `design-tokens.md` in the `tailwind-v4` skill).
- Flat class strings — never `class="flex items-center bg-blue-500 ..."`.
Always named-key collections.
- Overriding via utilities — `utilities` is additive. Override via named-slot
merge.
- Duplicate classes — two conflicting classes on one element. Named keys
prevent this by enforcing single occupancy per style concern.
- Missing responsive key — breakpoint classes mixed into other slots. Keep
them in `responsive` or modifier-specific keys.
- Using margins between siblings instead of `gap` — prefer `gap-*` on the
flex/grid parent over individual `mb-*` on children. Fewer classes, no
last-child edge case.
- Missing dark mode variants when the project uses them — if existing
components use `dark:`, new components must too.
## Table of Contents
- [Named-Key Collections](#named-key-collections)
- [Class Conflict Prevention](#class-conflict-prevention)
- [Spacing Preference](#spacing-preference)
- [Dark Mode (Variant-Based)](#dark-mode-variant-based)
- [craft-tailwind Plugin (Future)](#craft-tailwind-plugin-future)
## Named-Key Collections
Classes are built using `collect({})` with **named keys per style concern**.
This is the primary mechanism for preventing class conflicts and maintaining
readability.
```twig
{%- set classes = collect({
layout: 'inline-flex items-center group w-fit',
color: 'bg-brand-accent text-brand-on-accent',
font: 'font-heading font-bold',
size: props.get('size'),
hover: 'hover:bg-brand-accent-hover',
focus: 'focus:ring-2 focus:ring-brand-focus focus:ring-offset-1 focus:outline-none',
radius: 'rounded-lg',
spacing: 'py-2 px-4 gap-2',
transition: 'transition-colors duration-200',
utilities: props.get('utilities'),
}) -%}
```
### Standard Key Names
Use these consistently across all components:
| Key | Contains | Examples |
|-----|----------|---------|
| `layout` | Display, flex, grid, position, overflow | `flex`, `grid`, `relative`, `overflow-hidden` |
| `color` | Background, text color | `bg-brand-accent`, `text-brand-on-accent` |
| `font` | Font family, weight | `font-heading`, `font-bold` |
| `size` | Font size, width, height | `text-base`, `w-full`, `h-64` |
| `hover` | Hover states | `hover:bg-brand-accent-hover` |
| `focus` | Focus ring, outline | `focus:ring-2`, `focus:ring-brand-focus` |
| `radius` | Border radius | `rounded-lg`, `rounded-br-2xl` |
| `spacing` | Padding, margin, gap | `py-2 px-4`, `gap-4` |
| `border` | Border width, color, style | `border`, `border-brand-muted` |
| `shadow` | Box shadow | `shadow-md`, `hover:shadow-lg` |
| `transition` | Transition, animation | `transition-colors`, `duration-200` |
| `responsive` | Breakpoint-specific overrides | `lg:grid-cols-2`, `md:px-8` |
| `utilities` | Additive extension from caller | `props.get('utilities')` |
### The `utilities` Slot
`utilities` is the **extension point** — it adds classes that don't exist in
the base, like a margin or border where there wasn't one. It is **not** for
overriding existing slots.
```twig
{# Caller adds margin — extending, not overriding #}
{% include '_atoms/texts/text--h2' with {
content: 'Section Title',
utilities: 'mt-12 mb-4',
} only %}
```
To override a style concern, override the named slot on the collection:
```twig
{# Inside a variant that needs different colors #}
{%- set classes = classes.merge({ color: 'bg-brand-primary text-brand-on-primary' }) -%}
```
### Rendering
```twig
{# As a class attribute value #}
class="{{ classes.implode(' ') }}"
{# Inside {% tag %} #}
{%- tag element with {
class: classes.implode(' '),
} -%}
{# Inside attr() #}
<div{{ attr({ class: classes.implode(' ') }) }}>
```
## Class Conflict Prevention
### Why Order Doesn't Matter
HTML class attribute order is **irrelevant** for CSS specificity.
`class="bg-red-500 bg-blue-500"` does NOT reliably resolve to blue. The winner
is determined by Tailwind's generated CSS stylesheet order — which is internal
and not intuitive.
**Rule:** Never put two conflicting classes on the same element. Named keys
enforce single-occupancy per concern — that's the prevention mechanism.
### Tailwind v4 Cascade Layers
Tailwind v4 uses native CSS `@layer`. Utilities always beat components. But
**within** the utilities layer, same-specificity conflicts still resolve by
stylesheet order. Named-key collections prevent this.
For the full cascade layer model, see `cascade-layers.md` in the `tailwind-v4`
skill.
## Spacing Preference
Prefer `gap` utilities on flex/grid parents over individual margins on children.
Gap is cleaner — no last-child edge cases, fewer classes, spacing defined once
on the container.
```twig
{# Correct — gap on the parent #}
<div class="flex flex-col gap-4">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</div>
{# Avoid — margins on each child #}
<div class="flex flex-col">
<div class="mb-4">Item 1</div>
<div class="mb-4">Item 2</div>
<div>Item 3</div>
</div>
```
Use margins only for one-off spacing adjustments (e.g., `mt-8` on a section
heading) or when spacing varies between specific children.
## Dark Mode (Variant-Based)
For projects **without** the three-tier token system (single-brand, simple
sites), use Tailwind's `dark:` variant utilities directly.
Dark variants go in the same named key as their light counterpart:
```twig
{%- set classes = collect({
color: 'bg-brand-surface text-brand-heading dark:bg-brand-surface-dark dark:text-brand-heading-dark',
border: 'border-brand-muted dark:border-brand-muted-dark',
}) -%}
```
### Decision: Token-Based vs Variant-Based
| Approach | When to use |
|----------|-------------|
| **Token-based** (CSS custom properties switch) | Project uses multi-brand theming with CSS tokens. Dark mode = another token set. No `dark:` classes needed. See `design-tokens.md` in the `tailwind-v4` skill. |
| **Variant-based** (`dark:` utilities) | Single-brand project or project without CSS token architecture. Use `dark:` directly in class collections. |
Don't mix both approaches in the same project.
## craft-tailwind Plugin (Future)
The `craft-tailwind` plugin will provide:
- `craft.tailwind.merge()` — server-side class deduplication
- `craft.tailwind.classes({})` — named-slot class builder with auto-merge
- Tailwind v3 + v4 auto-detection
Until the plugin exists, named-key collections are the primary mechanism.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |