typo3-shadcn-content-elements

TYPO3 shadcn Content Elements

Source: https://github.com/dirnbauer/webconsulting-skills

Purpose

Use this skill to build TYPO3 Content Blocks content elements that behave like a coherent shadcn/ui system: preset-driven tokens, shared Fluid atoms/molecules, complete field coverage, useful backend previews, semantic icons, and seed data that fills every editor field.

This skill assumes Content Blocks are the source of truth for schema and TYPO3 owns rendering. shadcn/ui is the source for theme tokens, component class contracts, data attributes, states, spacing, borders, radius, and typography.

The styling rule is strict: content elements should not hardcode colors or theme-specific visual values. Raw oklch(), hsl(), rgb(), hex colors, and fixed light/dark assumptions belong in the committed shadcn theme token source only. Templates, element CSS, backend preview CSS, generated icons, and chart scripts should consume semantic tokens or Tailwind/shadcn utility classes.

Default Workflow

1. Establish the preset source.

   • If a shadcn/create URL or preset id is given, extract the id, for example b4hb38Fyj.
   • Use a scratch app to inspect shadcn output; do not install React components as TYPO3 runtime code.
   • Commit the preset as local CSS variables and Site Settings, for example body[data-shadcn-preset="b4hb38Fyj"]; do not add a runtime preset downloader or binary switcher.
   • Treat :root as the light-mode base and .dark as the dark-mode override, matching shadcn. Do not write content elements that only look correct in one mode.
   • Read references/shadcn-preset-workflow.md before changing theme tokens or primitive class strings.

2. Audit before editing.

   • Run php <skill>/scripts/audit-content-elements.php <repo-root> when working on a repo with ContentBlocks/ContentElements.
   • Use the output to prioritize missing previews, undeclared rendered fields, unused configured fields, missing labels, missing icons, and repeatable-field gaps.
   • Treat the audit as a starting point, then manually inspect high-risk templates.
   • Search for structural workaround leftovers before declaring a pass complete: f:split(, pipe-delimited links such as Label|https://..., legacy list fields such as features_list, specs_text, row_data, comma-delimited tier_values, and monolithic shadcn2fluid_* fixture maps.
   • Classify leftovers carefully: compatibility converters in a seed script can remain only when they convert old input into current structured fields; templates, fixtures, Content Blocks schema, tests, and docs should demonstrate the current structured model.
   • Apply the Fluid safety checks from references/content-element-contract.md, especially for date/time formatting, typolink attributes, resource paths, and string-only ViewHelpers.

3. Fix the shared component layer first.

   • Update Resources/Private/Components atoms/molecules from generated shadcn class contracts before editing hundreds of individual templates.
   • Prefer shared Fluid components over bespoke content-element CSS.
   • Keep semantic shadcn tokens such as bg-background, text-foreground, bg-card, border-border, ring-ring, text-muted-foreground, bg-primary, and text-primary-foreground.
   • Read references/styling-token-contract.md before adding or changing element CSS, SVG icon colors, chart colors, shadows, overlays, or backend preview styling.

4. Audit each content element against its contract.

   • Read references/content-element-contract.md.
   • For every element, compare config.yaml, templates/frontend.html, language/labels.xlf, assets/icon.svg, CSS/JS assets, backend preview, and seed coverage.
   • Treat config.yaml:title as an editor-facing product name. Prefer names like Text & Media, Image Call to Action, and Logo Cloud Hero over raw slugs such as textmedia, CTA With Image, or Hero Logo Cloud.
   • Use the typo3-translations skill for XLIFF format choices, English/German localization, ICU MessageFormat strings, LLL: references, and localized wizard group labels.
   • Generate element descriptions from the element purpose and schema so each description explains what editors can build. Do not reuse a single generic sentence across the catalog.
   • Every configured editor field should be rendered or intentionally marked backend-only.
   • Every rendered field should exist in config.yaml.
   • Every Collection child field should be rendered or intentionally omitted.
   • Treat editor Style / variant fields as contracts, not decorative metadata. Keep one only when the value is passed to an existing shadcn-backed Fluid component feature (for example Button/Badge/Alert variants or TabsList default/line) or when the template has a real layout/behavior branch. Do not keep variant fields that only append unused BEM modifier classes.
   • Prefer removing unsupported style fields over inventing bespoke visual variants. If a style option cannot be expressed by the shared shadcn atoms/molecules or existing shadcn class contracts, remove the field from config.yaml, frontend templates, backend previews, and fixtures.
   • If a repo-level test requires every content element to keep assets/frontend.css, use an empty/comment-only marker file when the shared component layer handles all styling. Do not re-add f:asset.css includes or style rules merely to satisfy the file-presence contract.
   • Use nested Collection fields for second-level repeatables when the installed Content Blocks version supports nested Collections; keep seed scripts recursive so child rows are created after their parent IRRE rows.
   • Give every Collection field an explicit table: key. Without it, Content Blocks derives the table from the identifier alone, so unrelated elements that pick the same name (rows, posts, column_items, cells, items, links...) silently share one physical table — schema migrations break, foreign_table_parent_uid drifts to the wrong type, and renames lose data. Names like <contentblock-slug>_<identifier> are safe, for example blog_teasers_posts or feature_matrix_rows. See references/content-element-contract.md "Collection Table Naming".
   • Use TYPO3 Link fields for editor-managed URLs. Keep visible link text in a separate text field and never encode Label|https://... pairs in textareas.
   • File fields need alt text and copyright/source strategy in seed data and previews.
   • Date and time fields must be formatted to strings before they are passed to visual-editor text rendering or HTML attributes.

5. Add backend previews for the page/layout module.

   • Read references/backend-preview-pattern.md.
   • Add templates/backend-preview.fluid.html using Content Blocks Preview layout with Content and optionally Footer.
   • Keep <f:section name="Header"></f:section> empty — never render a duplicate headline above the formatted card. The card itself shows the title inside d-ce-preview__title. Removing the section instead of emptying it triggers TYPO3's InvalidSectionException fallback to the standard renderer, which re-adds the duplicate.
   • Inside d-ce-preview__meta, surface the editor-facing element name, the Content Block identifier, the record uid, and the page pid as small pills. Use <f:translate key="LLL:EXT:desiderio/Resources/Private/Language/labels.xlf:preview.uid"/> and :preview.page — never hardcode the labels.
   • Show the most important data: title/headline, summary, bullets/repeatables, CTA/link, chart metrics, and thumbnails.
   • Never rely on TYPO3’s Core fallback preview for custom Content Blocks.

6. Create or refresh icons.

   • Read references/icon-pattern.md.
   • Each element gets a semantic assets/icon.svg.
   • Use TYPO3-style 16x16 SVGs: transparent background, currentColor primary, var(--icon-color-accent,currentColor) accent, readable in light and dark.
   • For large catalogs, actively prevent look-alike icons: audit normalized SVG bodies with titles removed, inspect same-family groups such as heroes/pricing/nav/footers/features, and add per-element geometry instead of relying on one family template.
   • If the user asks for GPT Image / Image GPT / gpt-image-*, first verify the currently available OpenAI image model and API credentials. Use image generation for metaphor boards or visual direction; redraw the final asset as clean, editable SVG because TYPO3 backend icons need tiny, token-colored vectors.
   • Treat Lucide, Tabler, and TYPO3 backend icons as metaphor references, not as a reason to reuse the same glyph across many content elements.

7. Update seed scripts.

   • Fill all top-level and repeatable fields for every element.
   • Fill nested repeatables as structured arrays; never collapse a second-level list into a newline-separated textarea when an IRRE Collection is available.
   • Add real dummy images from Unsplash or committed demo assets, with alt text and copyright/source fields where available.
   • Seed links as structured data or distinct fields, for example {"label": "Docs", "link": "https://example.com/docs"} or link_1_label plus link_1. Do not generate pipe-delimited link strings.
   • Seed chart/data elements with valid JSON that the frontend template actually parses.
   • Validate seeded Select values against the current config.yaml items before insertion. Stale fixture values from removed style variants should fall back to the configured default instead of seeding inert editor choices.
   • Keep Desiderio fixtures in each ContentBlocks/ContentElements/<element>/fixture.json file. Do not create or restore monolithic shadcn2fluid_* fixture mappings.
   • If old fixture keys must be accepted for migration, convert them at seed time into current fields or nested Collections and keep those aliases out of new fixtures and examples.

8. Verify and commit in reviewable slices.

   • Run CSS build, PHP unit/static checks, and Content Blocks/TYPO3 cache validation.
   • Scan content elements and shared generated preview code for raw color literals; allowed raw preset values should be confined to the shadcn theme token file and generated Tailwind output.
   • For large overhauls, commit by layer: preset/theme, primitives, generated previews, icons, per-element fixes, seed data.
   • Browser-check frontend pages and TYPO3 backend layout module previews.

Critical Rules — Collection Table Naming

This is the single most damaging mistake when authoring Content Blocks. Read this before creating any type: Collection field.

Every type: Collection field generates a separate physical database table. Without an explicit table: key, Content Blocks falls back to using the bare identifier as the table name. That breaks production in three escalating ways:

1. Reserved-word collisions. Identifiers like rows, groups, order, range, system, values, user are MySQL/MariaDB reserved words. Doctrine quotes at runtime so the table works inside TYPO3, but mysqldump, mysqlcheck, ad-hoc CLI queries, schema-diff tools, and IDE introspection all stumble on the unquoted name.
2. Cross-element table sharing. When two Content Blocks both pick a common identifier (posts, column_items, rows, cells, items, links, features, tabs, members, slides, stats, tiers, partners, clients, reviews, routes, metrics, specs, jobs, awards...), Content Blocks merges their schemas into one shared table. The shared table becomes the union of every consuming element's columns, schema migrations get confused, and renaming one block later requires a parent-aware data migration to split records back apart.
3. foreign_table_parent_uid type drift. Older Content Blocks versions created the parent reference column as varchar(255) DEFAULT '' NOT NULL. Newer TCA-driven schema migration wants int unsigned DEFAULT 0 NOT NULL. The migration fails with Truncated incorrect INTEGER value: '' because existing rows hold empty-string values that strict-mode MySQL refuses to coerce. Recovery requires UPDATE <table> SET foreign_table_parent_uid = 0 WHERE foreign_table_parent_uid = '' before the ALTER. Adding table: from the start avoids the legacy column path entirely on fresh tables.

Don't

• Do not declare a type: Collection field without table:.
• Do not use bare names like rows, posts, column_items, cells, items, links, features, tabs, members, slides, stats, tiers, groups, users, range, order, system, values as a table: value — they collide with other extensions or with reserved SQL keywords.
• Do not assume "it works in TYPO3" means it is safe — Doctrine's identifier quoting hides the problem until a dump, restore, or schema migration uncovers it.
• Do not rename a Collection's table: after editor data exists without a parent-aware data migration: dropping a shared table loses every block's content, and renaming without migration orphans the rows.

Do

• Give every type: Collection field an explicit table: directive in the YAML.
• Use the pattern <contentblock-slug-as-snake_case>_<collection-identifier>, for example blog_teasers_posts, feature_matrix_rows, footer_mega_column_items, pricing_plan_features, data_table_cells.
• For nested Collections, fold the parent collection name into the child's table name (pricing_plan_features for a features Collection nested inside plans).
• When auditing or porting an existing extension, add table: to every Collection in the same pass — schema migrations regress as soon as one block falls through.
• Before declaring a Collection sweep complete, run the audit grep below.

Audit

# Every Collection field that lacks an explicit table: directive (should print nothing).
rg -nP '^\s*type: Collection\s*$' --no-heading -A1 ContentBlocks/ContentElements \
  | rg -B1 -v 'table:'

# Bare table names that match MySQL/MariaDB reserved words.
rg -n '^\s+table:\s+(rows|groups|range|order|system|values|user|cross|dense_rank|window)\s*$' \
  ContentBlocks/ContentElements

# Bare unprefixed names — risky for cross-extension collision even if not reserved.
rg -nP '^\s+table:\s+[a-z][a-z0-9_]*\s*$' ContentBlocks/ContentElements \
  | rg -v '_[a-z]'   # everything kept after this filter has no underscore — review by hand.

The full reasoning, migration playbook for an already-shared table, and additional examples live in references/content-element-contract.md "Collection Table Naming".

Quality Bar

• Preset changes must visibly change design through committed tokens and shared component classes.
• Content elements should look like shadcn/ui, not generic Bootstrap or one-off CSS.
• Content elements must be light/dark capable because they consume semantic tokens rather than fixed color values.
• Backend previews should help editors recognize content without opening the form.
• Icons should form a coherent family, not random drawings, and every content element should remain distinguishable in the new content element wizard at 16px.
• Generated or bulk changes need deterministic scripts and tests where possible.
• Active content elements must not depend on shadcn2fluid; allowed mentions are limited to package conflicts, migration notes, and tests/docs that explicitly prevent the old package or fixture map from returning.
• Every type: Collection field has an explicit table: key with a <contentblock-slug>_<identifier> value. No bare names, no reserved SQL words. Audit grep in "Critical Rules — Collection Table Naming" should print nothing.

References

• references/shadcn-preset-workflow.md: scratch-app preset workflow and token expectations.
• references/styling-token-contract.md: no-hardcoded-style rules, light/dark behavior, and verification scans.
• references/content-element-contract.md: field/template/label/seed audit contract.
• references/backend-preview-pattern.md: Content Blocks backend preview pattern.
• references/icon-pattern.md: TYPO3 backend icon rules.
• ../typo3-translations/SKILL.md: XLIFF, localization, ICU MessageFormat, and LLL: label rules.

Scripts

• scripts/audit-content-elements.php <repo-root>: JSON audit for Content Blocks directories.