--- name: typo3-fluid-patterns description: Build or maintain TYPO3 v12+ Fluid site packages, regardless of CSS framework. Use for template hierarchy, CMS-first content architecture with lib.dynamicContent, colPos propagation, responsive images, WCAG 2.1 AA patterns, and progressive-enhancement JavaScript. Pair with typo3-playwright-ddev when browser verification needs setup. license: CC-BY-4.0 compatibility: Requires a TYPO3 v12+ site package using Fluid; validate rendered frontend output in the project's supported browser and accessibility workflow. --- # TYPO3 Fluid Template Patterns Reusable patterns for building TYPO3 v14+ site packages with Fluid templates. This skill is **CSS-framework-agnostic** — the patterns apply whether you use Tailwind, Bootstrap, vanilla CSS, or any other approach. > **Companion skill:** Use `typo3-playwright-ddev` to set up browser testing. ## Site Package Directory Structure Standard layout for a TYPO3 site package: ``` packages/theme-name/ ├── Configuration/ │ └── Sets/ │ └── / │ ├── TypoScript/ │ │ ├── page.typoscript # Page rendering (PAGEVIEW, data processors) │ │ └── content.typoscript # Content rendering (lib.dynamicContent, lib.contentElement) │ └── setup.typoscript # Main include file ├── Resources/ │ ├── Private/ │ │ ├── Language/ # XLIFF translation files │ │ └── Templates/ │ │ ├── Content/ # Content element templates (Text, Hero, etc.) │ │ ├── ContentPreviews/ # Backend preview templates │ │ ├── Layouts/ │ │ │ ├── Content/ # Content element layouts (Default, Unwrapped) │ │ │ └── Pages/ # Page layouts (Default — the outer HTML shell) │ │ ├── Pages/ # Page templates (Startpage, Contentpage, Sidebar) │ │ └── Partials/ │ │ ├── Atoms/ # Smallest reusable units (Image, Video) │ │ ├── Components/ # Composed units (Intro, Figure, Person) │ │ ├── Content/ # Content-specific partials (Hero, Textpic) │ │ ├── Header/ # Heading partials (Header, HeaderTag, Subheader) │ │ ├── Icons/ # SVG icon partials │ │ ├── Pages/ # Page-level partials (Header, Footer) │ │ └── Wrapper/ # Wrapper partials (Component, Anchor) │ └── Public/ │ ├── Css/ # Compiled CSS output │ └── JavaScript/ # Client-side JS (single main.js) └── package.json # Build scripts, dependencies ``` ## Template Hierarchy TYPO3 Fluid uses a **3-tier rendering chain** for pages and a parallel chain for content: ### Page Rendering ``` Page Layout (Layouts/Pages/Default.fluid.html) └── The outer HTML shell: , , asset loading, header/footer partials └── Defines sections: Stage, Main └── Page Template (Pages/Contentpage.fluid.html) └── Fills sections with content columns via lib.dynamicContent └── Uses Wrapper partials for consistent component framing ``` ### Content Rendering ``` Content Template (Content/Text.fluid.html) └── Selects a Content Layout (Layouts/Content/Default.fluid.html) └── Content Layout renders: frame classes, anchor, header, main section └── Content Template fills the Main section └── Delegates to Content Partials (Partials/Content/Textpic.fluid.html) └── Partials use Atoms (Atoms/Image.fluid.html) and Components (Components/Intro.fluid.html) ``` ### When to Use Each Level | Level | Purpose | Example | |-------|---------|---------| | **Layout** | Outer shell, shared across pages/content types | ``, ``, asset loading | | **Page Template** | Column structure for a specific backend layout | Main + sidebar grid | | **Content Template** | Entry point for a CType, selects layout | `Text.fluid.html` → `Content/Default` layout | | **Content Partial** | Complex rendering logic for a content type | `Textpic.fluid.html` with orientation handling | | **Component** | Reusable composed unit (heading + text + CTA) | `Components/Intro.fluid.html` | | **Atom** | Smallest reusable unit | `Atoms/Image.fluid.html` with responsive `` | ## CMS-First Content Architecture **Rule:** All editor-managed content must be rendered via `lib.dynamicContent`, never hardcoded in TypoScript settings. ```html

{settings.footer.copyright}

``` See [references/cms-first-content.md](references/cms-first-content.md) for the full `lib.dynamicContent` TypoScript definition, `colPos` conventions, frame class handling, and RTE customization. ## colPos Propagation When content elements need different styling based on their column position (e.g., smaller headings in a sidebar), propagate `colPos` through the template chain: ```html ``` > **Lesson learned:** This pattern touches many files (layout → partial → atom). Plan for it early — missing a layer causes silent rendering issues where sidebar content renders with full-width styles. See [references/colpos-propagation.md](references/colpos-propagation.md) for the complete annotated walkthrough. ## Accessibility Essentials (WCAG 2.1 AA) Every TYPO3 site package must include these from day one: 1. **`lang` attribute** on `` — dynamic via `{site.language.twoLetterIsoCode}` 2. **Skip-to-content link** — first element inside ``, visually hidden until focused 3. **Semantic landmarks** — `
`, `