Symfony UX Toolkit Kit

Symfony UX Toolkit — Kit Recipe Skill

Author + review recipes for UX Toolkit. Recipes = unit shipped to end-users (Twig components + optional Stimulus controllers). Each recipe carries a README.md — its single doc source (description, live-preview examples, install/API), rendered as-is on ux.symfony.com.

Core Rules

1. One PR per recipe. Never batch multiple recipes single PR. PR title: [Toolkit][<Kit>] Add <recipe> recipe or [Toolkit][<Kit>] Align <recipe> with <upstream> reference.
2. Target 3.x. CHANGELOG entry under active 3.x section in src/Toolkit/CHANGELOG.md.
3. Visual + behavioral parity with upstream reference (Shadcn UI / Flowbite). Verify manually; attach screenshot/video to PR body for animated/interactive components.
4. Reuse all upstream examples. No subset. Read both component source and every upstream example, then inline each as a live-preview block in the recipe README.md (see Examples).
5. No companion PR on symfony/ux.symfony.com. It renders the docs page from the recipe README.md, registers kit Stimulus controllers from a build-time loader, and compiles kit Tailwind classes through @source. Only a new external asset dependency not already vendored there needs one.
6. Regenerate snapshots and screenshots after every recipe change + commit them: bin/update_toolkit_tests.sh <kit>/<recipe> from the repository root (Docker required). CI + reviewers reject stale ones.
7. Use GitHub PR template (Bug fix / Feature / License: MIT / Issues: Part of #3233 for shadcn recipes, the shadcn tracking issue). Fabbot fails otherwise.
8. Prefer Stimulus controller over native browser features (e.g. <details>) when parity needs animations, ARIA sync, coordinated state. Native fine only when matches upstream UX exactly.

Recipe Directory Layout

src/Toolkit/kits/<kit>/<recipe>/
├── manifest.json
├── README.md                              # single doc source: description + inline live-preview examples
├── templates/components/
│   ├── <Component>.html.twig              # root component
│   └── <Component>/<SubName>.html.twig    # e.g. Trigger, Close, Header, Item, Content
└── assets/controllers/                    # optional, only if interactive behavior is needed
    └── <recipe>_controller.js

Sub-component file path Component/SubName.html.twig consumed as <twig:Component:SubName>.

There is no examples/ directory — examples live inline in README.md (see Examples). Recipe copy-files only copies templates/ (+ assets/); the README is doc-only, never shipped to the user's app.

README.md structure

# <Human Name>

<One-sentence description.>    <!-- first paragraph; read by Recipe::getDescription(), the manifest has no description -->

```twig {"preview":true,"height":"300px"}
<!-- hero preview: rich showcase -->
<twig:Recipe ... />
```

## Installation

::: installation    <!-- directive, expanded by the renderer -->

## Usage

```twig
<!-- STATIC block (no preview): minimal API surface -->
<twig:Recipe prop="a | b" />
```

## Examples

### <Variant Name>

<Optional sentence describing the variant.>

```twig {"preview":true,"height":"150px"}
<!-- one live-preview block per upstream example -->
<twig:Recipe ... />
```

### RTL    <!-- always last Examples subsection (see RTL examples) -->

## API Reference

::: api-reference    <!-- directive, expanded by the renderer -->
```

Info-string options on a preview block (JSON after the language):

• "preview":true — required marker that turns the block into a live iframe + Code tab. Without it the block is a plain static snippet.
• "height":"<px>" — iframe height (e.g. "150px", "300px"); default 200px.
• "collapseClass":true — collapse long class="..." attributes in the Code tab (use for examples with long Tailwind class lists, e.g. post-link).

READMEs use exactly two directives: ::: installation and ::: api-reference.

Shadcn UI

Always emit data-slot="<recipe-name>" on root + data-slot="<recipe-name>-<sub>" on every sub-component root. Shadcn-specific convention driven by its CSS selectors.

Upstream sources

Read all source files per recipe: component source carries the structure + data-* surface, the stylesheet carries the classes, examples show usage patterns, MDX drives docs and manifest.

Enumerate every example file for recipe:

gh api "repos/shadcn-ui/ui/git/trees/main?recursive=1" --jq '.tree[].path' \
  | grep "apps/v4/examples/radix/<recipe>"

Fetch each:

https://raw.githubusercontent.com/shadcn-ui/ui/refs/heads/main/apps/v4/examples/radix/<example>.tsx

RTL class variants

Upstream ships no RTL class variants. The .cn-* rules in style-nova.css use physical properties (text-left, mr-1, ml-1). RTL support is therefore authored here, not ported — the upstream classes are the LTR reading, and adapting them is the recipe's job.

Reach for a logical utility first. ms-*, me-*, ps-*, pe-*, start-*, end-*, text-start, text-end already flip with the text direction, so they need no variant prefix at all. Porting mr-1 gives me-1, and text-left gives text-start — one token, correct in both directions.

Never pair a physical class with its own logical equivalent. ltr:text-left rtl:text-start renders exactly like a bare text-start, and ltr:before:mr-1 rtl:before:me-1 exactly like before:me-1. The pair costs two tokens for one rule, has to be kept in sync on every edit, and makes a rtl: grep return noise instead of the handful of places that genuinely differ.

Use rtl: only where no logical property exists — a mirrored glyph or transform, typically. Keep those verbatim:

rtl:rotate-180        # a chevron that must point the other way
rtl:translate-x-1/2   # no logical equivalent for translate

Scope them tightly: an icon inside a vertically-oriented component is not direction-dependent, so rtl:rotate-180 there points the arrow the wrong way.

Flowbite v4

Kit identifier: flowbite-4.

Upstream sources

Flowbite docs page = primary source: ships copy-pasteable HTML with Tailwind classes + lists every variant. Read full page before writing any template.

Local Visual Testing

ux and ux.symfony.com must be on matching branches; mismatch causes assetmap failures:

The asset "./vendor/symfony/ux-toolkit/kits/<kit>/<recipe>/assets/controllers/<recipe>_controller.js" cannot be found in any asset map paths.

cd /path/to/ux             && git checkout feat/toolkit-<kit>-<recipe>
cd /path/to/ux.symfony.com && git checkout main
# In ux.symfony.com:
php ../link
symfony php bin/console tailwind:build
symfony serve -d

manifest.json

Kit-level (src/Toolkit/kits/<kit>/manifest.json)

{
    "$schema": "../../schema-kit-v1.json",
    "name": "<Display Name>",
    "description": "...",
    "license": "MIT",
    "homepage": "https://ux.symfony.com/toolkit/kits/<kit>"
}

Recipe-level (src/Toolkit/kits/<kit>/<recipe>/manifest.json)

{
    "$schema": "../../../schema-kit-recipe-v1.json",
    "type": "component",
    "name": "<Human Name>",
    "version-added": "<Toolkit version the recipe first ships in, e.g. 3.5>",
    "copy-files": {
        "assets/": "assets/",
        "templates/": "templates/"
    },
    "dependencies": {
        "composer": [
            "twig/extra-bundle",
            "twig/html-extra:^3.24.0",
            "symfony/ux-twig-component:^3.5",
            "tales-from-a-dev/twig-tailwind-extra:^1.3.0"
        ],
        "recipe": ["<other-recipe>"]
    }
}

Rules:

• Drop assets/ from copy-files if no Stimulus controller.
• Add "symfony/ux-icons" to composer whenever templates use <twig:ux:icon>.
• Bump twig/html-extra to ^3.24.0 for html_attr_type / tailwind_classes. The tailwind_classes class-merge idiom also needs tales-from-a-dev/twig-tailwind-extra:^1.3.0 and symfony/ux-twig-component:^3.5 (enforced by ComposerSymbolChecker).
• Declare dependencies.recipe only for recipes required by the component templates themselves (e.g. toggle-group depends on toggle). Do NOT declare recipe deps for components used only in examples — examples are demo files, not shipped dependencies.

Twig Component Patterns

1. Prop & block documentation (mandatory)

Document every prop with a ## <type> <Description.> comment on the line above it inside the {% props %} tag, and every rendered block with a {##- <Description.> -#} doc comment on its own line right above it. These are Twig 3.29 documentation comments — Twig attaches them to the following node as metadata, so they carry no runtime cost and the Toolkit reads them natively:

{%- props
    ## string Unique identifier used to generate internal Dialog IDs.
    id,
    ## boolean Whether the dialog is open on initial render.
    open = false
-%}
...
<div ...>
    {##- The dialog structure, typically includes `Dialog:Trigger` and `Dialog:Content`. -#}
    {%- block content %}{% endblock -%}
</div>

Format is enforced by bin/ux-toolkit-kit-lint (CI fails on any warning — see Docblock linting):

• Prop ## <type> <Description.> — one per line, on the line directly above the prop name, inside {% props %}. Type first (camelCase name matches the declared prop), then the description.
• Type = valid PHPDoc/PHPStan type with no spaces: 'default'|'secondary', string|array<string>|null, boolean, number. A space breaks the type/description boundary, so 'a' | 'b' is rejected — write 'a'|'b'.
• No Defaults to in the documentation. Default values live only in {%- props -%} (single source of truth); the linter and ux.symfony.com read them from there.
• Block {##- <Description.> -#} — a doc comment (double #) on its own line directly above a block actually rendered in the template ({% block x %}, block(outerBlocks.x), or block('x')). Mirror the block's whitespace-trim so the rendered output is unchanged: {##- ... -#} when the block opens with {%-/{{-, {## ... -#} when it opens with {%/{{. Never leave a rendered block undocumented.
• Descriptions start with a capital letter and end with a period.
• Reference sub-components by Twig tag name (\Dialog:Trigger``).
• Requires twig/twig >= 3.29 (documentation comments) and symfony/ux-twig-component with PropsNode::getPropDocumentation().

2. Root element

There is one home for each kind of attribute. attributes.defaults({...}) carries the consumer-overridable values: the merged class (as a tailwind_classes mergeable), data-controller, data-action, aria-label, and genuinely overridable HTML defaults (type: 'button', alt: ''). Everything that identifies or reflects the component's state is rendered directly as a literal attribute, so it is always present and can neither be dropped by the merge nor overridden:

• class → merged inside defaults(): class: '<base>'|tailwind_classes (or class: style.apply({...})|tailwind_classes with html_cva). tailwind_classes returns a mergeable value that defaults() merges with the consumer's class (consumer wins). No separate class="..." / render('class').
  • Exception — keep ('<base> ' ~ attributes.render('class'))|tailwind_merge when class and the attributes sink are on different elements (base on an outer element, sink on an inner one), or when class is spread onto an external non-mergeable component — e.g. <twig:ux:icon>, which validates class as a scalar string and rejects the tailwind_classes object. Spreading onto a mergeable Toolkit child (<twig:Button>, <twig:Label>, <twig:Separator>, …) is fine: defaults() chains the mergeables as base < wrapper < caller, matching React/Vue's cn(base, className).
• data-slot → literal attribute (data-slot="<recipe-name>"). Structural Shadcn marker, never overridable.
  • Exception: a component other components pass their own slot to (Button, Input, Textarea, Label, Separator, Field:Group, …, e.g. AlertDialog:Action renders <twig:Button data-slot="alert-dialog-action">, or an asChild bag carries 'data-slot': 'dialog-trigger') reads it first: data-slot="{{ attributes.render('data-slot')|default('button') }}". A second data-slot would be lost, since the browser keeps the first one; render() marks it as rendered, so defaults() does not print it again. A parent style hook on such a component cannot rely on its default slot: give it a dedicated marker, as upstream does with data-sidebar="menu-action". ComponentsRenderingTest fails on any element rendered with two data-slot.
• State data-* and state aria-* → literal attributes, always emitted with an explicit value (never {% if %}-guarded, never x ? 'attr="y"'): data-state, data-open, data-closed, data-active, data-disabled, data-orientation, data-size, data-variant, data-side, data-selected, data-checked; aria-expanded, aria-selected, aria-hidden, aria-disabled, aria-checked, aria-pressed, aria-current. Boolean values render as strings: data-open="{{ open ? 'true' : 'false' }}" (a bare : false renders empty/ambiguous — always use : 'false').
• Stimulus value attrs (data-<recipe>-<key>-value), id, role, ARIA id-refs (aria-controls/aria-labelledby/aria-describedby) → literal attributes.
• aria-label → the one ARIA attribute that belongs inside defaults(): 'aria-label': 'pagination'. It is an accessible name, not a state, so a consumer must be able to replace it to name a landmark more precisely or to translate it. defaults() lets the consumer's value win and emits the attribute only once; written as a literal next to the sink it would be emitted twice, and the browser keeps the first occurrence, so the hard-coded label would always win. Same for a label/ariaLabel prop: pass it through defaults() ('aria-label': label), not as a literal.
• class + data-controller / data-action + aria-label (+ overridable HTML defaults) → attributes.defaults({...}). A bare {{ attributes }} remains only where there is no class base and no default label.

{# WITH a controller/action (interactive component) #}
<div
    id="{{ id }}"
    data-slot="<recipe-name>"
    data-<recipe>-<key>-value="{{ value }}"
    data-orientation="{{ orientation }}"
    aria-labelledby="{{ _<recipe>_title_id }}"
    {{ attributes.defaults({
        class: '<base classes>'|tailwind_classes,
        'data-controller': '<recipe>',
        'data-action': 'click-><recipe>#toggle',
    }) }}
>
    {%- block content %}{% endblock -%}
</div>

{# WITHOUT a controller/action (static component) #}
<div
    data-slot="<recipe-name>"
    {{ attributes.defaults({
        class: '<base classes>'|tailwind_classes,
    }) }}
>
    {%- block content %}{% endblock -%}
</div>

• Do NOT put data-slot, state data-*, state aria-* or Stimulus data-*-value into defaults() — they belong as literal attributes (enforced by AttributesDefaultsChecker). Of the data-*/aria-* keys, only data-controller, data-action and aria-label belong in defaults().
• Do NOT put hardcoded HTML element attributes (like type="checkbox") into defaults() — those are structural, not overridable.
• Structural / config / marker attributes stay conditional (they are not "always render" state): aria-orientation on a decorative separator, data-bs-parent, presence-marker attributes like data-horizontal/data-vertical.
• Non-Tailwind kits (Bootstrap, Common) keep their own idiom: class is merged inside defaults() as a plain string (attributes.defaults({class: '...'}), no tailwind_classes), there is no data-slot, and no tailwind_merge. Only the data-slot rule and the state-attribute rule apply there; the linter's Tailwind-only checks are skipped for them.

3. Variant systems with html_cva

{%- set style = html_cva(
    base: '<base classes>',
    variants: {
        variant: { default: '...', outline: '...' },
        size: { default: '...', sm: '...', lg: '...' },
    },
) -%}
<button {{ attributes.defaults({ class: style.apply({variant: variant, size: size})|tailwind_classes }) }}>

4. Parent → descendant context propagation

Preferred: provide() / inject() (needs symfony/ux-twig-component:^3.1). Parent publishes values, any descendant at any depth reads them. Works for self-closing children, crosses intermediate components without forwarding, replaces brittle outer-scope pattern.

{# parent — InputOtp.html.twig #}
{%- props maxLength = 6 -%}
{%- do provide('inputOtp.maxLength', maxLength) -%}
{%- do provide('inputOtp.id', 'input-otp-' ~ id) -%}
<div ...>{%- block content %}{% endblock -%}</div>

{# descendant — InputOtp/Slot.html.twig (works even self-closing) #}
{%- set _inputOtp_maxLength = inject('inputOtp.maxLength', 6) -%}
{%- set _inputOtp_id = inject('inputOtp.id') -%}

Conventions:

• Key format: '<camelCaseRecipe>.<key>' (e.g. 'inputOtp.maxLength', 'tabs.active', 'toggleGroup.variant'). Prefix avoids collisions across recipes.
• Local variable name for injected values: _<camelCaseRecipe>_<key> (e.g. _tabs_defaultValue, _toggleGroup_variant). The _ prefix + recipe name prevents collision with the child's own props or Twig globals.
• Always pass fallback to inject() when child can render standalone.
• Place provide() at top of parent template, before {% block content %} — descendants only see values published before their render.
• Keys for ID-driven a11y wiring: derive <recipe>.id, <recipe>.titleId, <recipe>.descriptionId, <recipe>.contentId, <recipe>.triggerId from parent's id prop.
• Values flow top-down only; siblings never share state; provides dropped once parent finishes rendering.

Legacy: outer-scope _<recipe>_<key> variables. Older recipes use {%- set _dialog_title_id = ... -%} read by children with ?? fallback. Still works for body-form children but breaks for self-closing components (<twig:X:Item .../> compiles without outer context). Migrate to provide()/inject() when touching such recipes.

5. The <recipe>_<role>_attrs (asChild) pattern

Sub-templates like Trigger.html.twig, Close.html.twig, Cancel.html.twig MUST NOT wrap user's element in own <button>. Instead expose attrs bag consumer spreads onto own element:

{# templates/components/Dialog/Trigger.html.twig #}
{%- set dialog_trigger_attrs = {
    'data-action': 'click->dialog#open'|html_attr_type('sst'),
    'data-dialog-target': 'trigger',
    'aria-haspopup': 'dialog',
} -%}
{##- The trigger element (e.g., a `Button`) that opens the dialog when clicked. -#}
{%- block content %}{% endblock -%}

{# example consumer #}
<twig:Dialog:Trigger>
    <twig:Button {{ ...dialog_trigger_attrs }}>Open</twig:Button>
</twig:Dialog:Trigger>

Rules:

• Variable name: <snake_case_recipe>_<role>_attrs — dialog_trigger_attrs, dialog_close_attrs, tooltip_trigger_attrs, collapsible_trigger_attrs, alert_dialog_trigger_attrs.
• Apply |html_attr_type('sst') to data-action. 'sst' = Stimulus Shorthand Token — marks value appendable, so consumer spreading {{ ...dialog_trigger_attrs }} alongside own data-action gets both merged rather than first overwritten.
• Template body = {%- block content %}{% endblock -%} only — no wrapping element, otherwise variable not visible to outer scope.
• Variant (when wrapping known component acceptable, e.g. AlertDialog:Action):

{%- props
    ## 'default'|'destructive' The visual style variant.
    variant = 'default'
-%}
<twig:Button variant="{{ variant }}" {{ ...attributes }}>
    {##- The action button label. -#}
    {{- block(outerBlocks.content) -}}
</twig:Button>

6. Collapse/expand animation — grid-template-rows, never hidden

hidden (display:none) causes layout jumps. Use grid-template-rows: 0fr + overflow:hidden for smooth transitions:

<div class="grid overflow-hidden transition-[grid-template-rows] duration-300 ease-out"
     style="grid-template-rows: {{ open ? '1fr' : '0fr' }};">
    <div class="min-h-0 min-w-0 overflow-hidden">
        {%- block content %}{% endblock -%}
    </div>
</div>

Stimulus controller toggles style.gridTemplateRows between '1fr' and '0fr' on open/close.

7. ARIA & data-state surfaces

Emit as literal attributes (outside defaults()), always present with an explicit value — never {% if %}-guarded, never x ? 'attr="y"' (see section 2):

• role, aria-haspopup, aria-expanded, aria-controls, aria-labelledby, aria-describedby, aria-disabled, aria-pressed, aria-hidden, aria-current, aria-selected, aria-checked.
• data-state="open|closed|active|inactive", data-orientation="vertical|horizontal", data-variant, data-size, data-disabled, data-open, data-closed, data-active.
• Booleans render as strings: data-open="{{ open ? 'true' : 'false' }}", aria-expanded="{{ open ? 'true' : 'false' }}" (a bare : false renders empty/ambiguous).
• IDs deterministic + shared between trigger/content via parent's id prop (e.g. aria-controls={{ _accordion_item_content_id }}).
• Structural/config attributes that are only valid in one state stay conditional (e.g. aria-orientation only when a separator is not decorative).
• aria-label is not part of this surface: it is an accessible name the consumer must be able to replace, so it goes inside defaults() (see section 2).

Docblock linting

bin/ux-toolkit-kit-lint validates every component's prop and block documentation against the template. CI runs it per kit with --fail-on-warning, so any violation fails the build.

cd src/Toolkit
php bin/ux-toolkit-kit-lint --fail-on-warning kits/<kit>

Checks:

• Prop ## <type> <Description.> — valid spaceless PHPStan type, description Capitalized + ending with a period. Every declared prop in {%- props -%} has a ## ... doc comment above it and vice versa.
• Block {##- <Description.> -#} — description Capitalized + ending with a period. Every rendered block ({% block x %} / block(outerBlocks.x) / block('x')) has a {##- ... -#} doc comment on the line above it.
• Default values are not documented — they are read from {%- props -%}.

Stimulus Controller Conventions

assets/controllers/<recipe>_controller.js:

import { Controller } from '@hotwired/stimulus';

/**
 * @value  open     Whether the component is open on initial render.
 * @target trigger  The element that toggles the component and reflects its expanded state.
 * @target content  The region shown or hidden when the component toggles.
 * @action open     Opens the component.
 * @action close    Closes the component.
 */
export default class extends Controller {
    static targets = ['trigger', 'content'];
    static values = { open: Boolean };

    connect() {
        if (this.openValue) this.open();
    }

    open() { /* ...sync ARIA after transitions... */ }
    close() { /* ... */ }
}

• ESM, default export, @hotwired/stimulus.
• Sync ARIA from JS on state changes (aria-expanded, data-state).
• Respect transitions: if (el.getAnimations().length > 0) el.addEventListener('transitionend', ..., { once: true });.
• Naming: <recipe>_controller.js, controller identifier <recipe> (kebab-case in Twig).
• Keyboard actions — use Stimulus descriptor syntax in Twig, not raw JS keydown listeners:

  data-action="keydown.enter->{{ recipe }}#toggle keydown.space->{{ recipe }}#toggle"

  Pipe through |html_attr_type('sst') when exposing via <recipe>_<role>_attrs so consumers can append own actions.
• Hover/focus-triggered components — never use group-hover + group-focus-within + tabindex=0; use Stimulus controller with openDelay/closeDelay values instead (see anti-patterns).
• Nested open-state — never use in-data-[state=open]:visible on nested components; use named Tailwind groups (group/<recipe>-menu, group/<recipe>-sub) instead (see anti-patterns).