typo3-shadcn-content-elements

What this skill does

# 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.html`; 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 `data-astro-highlight` and the copy control. Keep source text escaped in Fluid and let the runtime decorate tokens after load.
- For forms, use TYPO3 Form Framework definitions under `Resources/Private/Forms`, TypoScript renderers in the Site Set, and `typo3/cms-form` as a Composer runtime dependency. Do not hand-roll mail forms in Fluid templates.
- Configure form mail routing through TYPO3 form finishers and Site Settings (`desiderio.forms.*`). Use a PSR-14 listener, such as `BeforeEmailFinisherInitializedEvent`, only to map site-specific sender/receiver options. Do not invent a `setup.php` mail mapping layer.
- CAPTCHA is opt-in and must be TYPO3 Form-compatible. Prefer honeypot, validation, throttling, and server-side spam checks first. If a real CAPTCHA provider is required, keep provider keys in Site Settings or environment configuration, never in templates, fixtures, or registry items.
- Seed data is part of the design. Every element needs credible English/German demo copy, valid links, meaningful icons, realistic metrics, useful code snippets, structured repeatables, image alt/source data, and select values that match the current `config.yaml`.
- Verify visually in the browser after changes. For Desiderio styleguide work, check the local DDEV site and the relevant page URL, including the full styleguide/catalog pages, not just the element that was edited.
- Finish with project checks: `php scripts/audit-content-elements.php`, PHPUnit/static checks, Tailwind sync, registry build when registry files changed, JS syntax checks when shared JS changed, and a browser pass.

## 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.
   - Do not stop after icon-like fields. Loop through every Content Block element in the catalog and classify each issue as schema, template, CSS/token, JavaScript/include, backend preview, fixture, or seed-fallback work.
   - 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_*` fixtu