typo3-shadcn-content-elements

name	typo3-shadcn-content-elements
description	Produces, audits, and overhauls TYPO3 Content Blocks content elements styled with shadcn/ui presets, semantic tokens, Fluid atoms, backend previews, icons, and seed data. Use when the user asks to create, restyle, review, seed, iconize, or preview TYPO3 Content Blocks with shadcn/ui, Tailwind v4 tokens, no-hardcoded-style rules, or local registry presets.
compatibility	TYPO3 14.x
metadata	{"version":"1.7.0","origin":"webconsulting"}
license	MIT / CC-BY-SA-4.0

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, local shadcn registry items, and seed data that makes the styleguide pages credible.

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.

Desiderio Creation Contract

When creating or overhauling Desiderio shadcn/ui content elements, respect these project-specific rules before general preferences:

• Use TYPO3 14, Content Blocks 2.x, and Fluid 5.3 templates. Frontend entrypoints stay in templates/frontend.fluid.html (the Content Blocks 2.x default since 2.0.4; plain frontend.html is the legacy 1.x name); backend previews stay in templates/backend-preview.fluid.html.
• TYPO3 owns rendering. Do not copy React, Radix, or Astro framework components into the runtime. shadcn/ui is the source for tokens, class contracts, states, radius, spacing, focus rings, and component anatomy.
• Use Desiderio Fluid atoms/molecules/components where they exist, especially d:layout.section, d:layout.container, d:atom.typography, d:atom.icon, buttons, badges, cards, form controls, tabs, accordions, tables, alerts, dialogs, and chart wrappers.
• Respect responsive design in every element: mobile-first grids, stable dimensions for fixed-format UI, no text overflow, no incoherent overlap, and layouts that still read well at narrow and wide widths.
• Keep designs genuinely polished. Prefer clear editorial/product systems with strong hierarchy, deliberate spacing, real media or useful demo content, and restrained shadcn surfaces. Avoid decorative-only gradients, orphan cards, nested cards, and generic placeholder copy.
• Use only semantic tokens and shadcn/Tailwind classes in templates and CSS. Raw color values are allowed only in theme token files and generated Tailwind output.
• Use XLIFF 2.0 labels with modern stable ids such as copy_code, preview.uid, or field.headline. Provide English base labels and German labels for editor-facing strings. Use ICU MessageFormat for variable or pluralized labels instead of concatenating strings.
• Use LLL: references for labels in Content Blocks YAML, backend previews, and templates. Do not hardcode editor-facing labels in Fluid when they belong in XLIFF.
• For behavior that pure HTML, CSS, and shadcn classes cannot cover, use the shared Desiderio Astro runtime in Resources/Public/Js/astro.js. Templates should emit data attributes such as data-astro-counter, data-astro-reveal, data-astro-highlight, data-astro-copy, data-astro-tilt, or data-astro-marquee.
• Do not add inline <script> blocks to content element templates. Add idempotent behavior to shared JS include files, register them through TypoScript or AssetCollector, and make reduced-motion behavior explicit.
• Code examples should use the editorial code-block element with and the copy control. Keep source text escaped in Fluid and let the runtime decorate tokens after load.

Default Workflow

1. Establish the preset source.

   • If a shadcn/create URL or preset id is given, extract the id, for example b4hb38Fyj.
   • Run npx shadcn@latest info --json in the project when components.json exists. If a TYPO3/non-TS repo fails path resolution, add a small tsconfig.json plus scratch aliases so components, ui, lib, utils, and hooks resolve without copying React runtime code into TYPO3.
   • Use shadcn create or https://ui.shadcn.com/create?item=preview as a design-system source. Use an Astro scratch app when the user asks for Astro/include-file JavaScript patterns; use a Vite/React scratch app only to inspect primitive class contracts.
   • Do not install React/Astro components as TYPO3 runtime code. TYPO3 owns rendering; shadcn owns tokens, component contracts, and registry metadata.
   • 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.
   • For Desiderio, also run the project audit script (php scripts/audit-content-elements.php) because it contains repo-specific hard checks for inline styles, raw colors, variant branches, undeclared rendered fields, and seed gaps.
   • If local PHP cannot load Composer because the extension requires PHP 8.3+, run the audit and PHPUnit through DDEV PHP 8.3. Copy the repo to a temporary path inside the DDEV project first so you do not mutate a dirty vendor checkout.
   • 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. fixture_missing_field and collection_child_seed_gap can be soft signals when the project seeder auto-fills missing demo values, but the rendered seeded pages still need a visual pass.

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.