Two commands for tools

The skill relies on two commands that are also useful in your own scripts.

bin/console storia:list --format=json

Lists every view with its type (template, component or form), its YAML file, its variants and the resolved arguments of each variant. Use --filter=components/button or --filter=components/button:large to narrow the list. Without --format=json, the output is a readable summary.

bin/console storia:render components/button plain

Prints the HTML of a variant on the standard output. --format=twig prints the source of the template and --format=include prints the code that includes a component. On error (unknown view or variant, Twig or PHP exception), the message goes to the error output and the exit code is 1.

Mate tools

With Symfony Mate, the catalog is also available as tools, called with vendor/bin/mate tools:call <tool> --<param>=<value>:

The tools run the console of your application, bin/console at the root of the project. Change the path in mate/config.php when it is elsewhere:

// mate/config.php
$container->parameters()->set('ai_mate_storia.console', '%mate.root_dir%/app/bin/console');

storia-test writes the snapshot of a variant that has none, as storia:test does, and never updates an existing one. The results are wrapped under an untrusted_data key, as the data comes from your templates.

Install the skill

The skill is the skills/ui-storia folder of the bundle. It follows the Agent Skills format and is declared in composer.json for Symfony Mate, which discovers it without any copy.

With Symfony Mate

Install Mate in your project, then discover the extensions:

composer require --dev symfony/ai-mate
vendor/bin/mate init
vendor/bin/mate discover

Mate registers the tools of the bundle (see below) and installs its skill as mate-ui-storia in .agents/skills and .claude/skills. It runs the discovery again after each composer install and composer update, so the tools and the skill always match the installed version of the bundle. Commit the generated folders to share them with your team. Use vendor/bin/mate skills:disable ui-storia to turn it off and vendor/bin/mate skills:override ui-storia to adapt a copy to your project.

Without Symfony Mate

Copy the folder to your project, or link it, so your agent finds it in .claude/skills/ui-storia:

mkdir -p .claude/skills
cp -r vendor/iq2i/storia-bundle/skills/ui-storia .claude/skills/ui-storia

# or keep it in sync with the installed version of the bundle
ln -s ../../vendor/iq2i/storia-bundle/skills/ui-storia .claude/skills/ui-storia

The content of the skill follows the version of the bundle: copy it again after an upgrade, or use the link.

What the skill does

• Checks how Storia is installed in the project: configuration, routes, assets of the preview.
• Lists the components and variants of the project, and shows what a variant renders.
• Knows the format of the YAML files and the !data, !repeat and !lorem tags, so it can create a component and its variants, with the conventions of your project.
• Checks a rendering with storia:render, or in a browser on the iframe URL of the variant.
• Runs storia:test after a change and reads its output.

What it does not do

• It does not see the page: it reads HTML and code, not screenshots. It cannot tell you that a component looks wrong.
• It does not decide your design. It follows the components and variants that already exist, so a catalog with few variants gives it little to work with.
• It does not replace a review of the snapshots: an agent can write a variant and its snapshot, a person still decides that the result is right.

The Controls tab, next to Twig, HTML and Include, lets you change the arguments of the current variant and see the result immediately, without editing the YAML file. Controls are deduced automatically:

A component with {% props title = 'Card title', count = 3, highlighted = false %} gets three controls, even if its YAML file describes no argument. An argument written in the YAML file replaces the default value of the prop with the same name.

The widget is deduced from the value or the PHP type:

Some controls are read-only: a prop whose default value is a Twig expression, an argument that resolves to a PHP object, or an array too large to be edited by hand. They are displayed with a badge explaining why. blocks and form types have no controls.

Describing the controls

A documentation comment above a prop gives the control a description, and can pick its widget with @control:

{% props
    ## Title of the card
    title = 'Card title',
    ## Number of items @control range min=0 max=10
    count = 3,
    ## Accent color @control color
    accent = '#0f172a',
    ## Alignment of the content @control radio left|center|right
    align = 'left'
%}

The same comment works in the docblock of a public property or of a mount() parameter of a PHP component, and in the {% types %} tag of a page:

/** CSS modifier of the notice @control select info|warning|danger */
public string $level = 'info';

/**
 * @param int $delay Seconds before the snackbar closes @control range min=1 max=30
 */
public function mount(string $message, int $delay = 5): void

{% types {
    ## Main message of the page @control textarea
    message: 'string',
    ## Number of columns @control range min=1 max=4
    columns?: 'number',
} %}

@control accepts text, textarea, color, date, number, range (min, max and step options), select and radio (choices separated by |), checkbox and json. A widget that does not fit the value, such as a range on a string, is ignored and the control says so. For an enum, select and radio only pick the widget: the choices stay the cases of the enum.

Documentation comments need Twig 3.29: before that version, a ## comment inside a tag is a syntax error, so only write them once your project runs Twig 3.29 or later. Reading them from {% props %} also needs symfony/ux-twig-component 3.5; with an older version the controls are still deduced, without description nor @control.

Changes are never written to disk. They are kept in the overrides query parameter of the URL, so reloading the page or sharing the link keeps them, and the Reset button removes them. To keep a state, click Copy variant YAML and paste the result in your YAML file. Values coming from !data or from a PHP data provider are copied once resolved, as literal values.

Overridden values are always passed as plain data, never as Twig code and never through !data or the argument resolver: a string like App\Foo::bar stays a string. However, if your template prints an argument with the |raw filter, a crafted link can inject HTML in the preview: only open Storia links you trust.

The static export has no controls: the tab only displays a note explaining that they are not available.

# storia/data/menu.yaml
items:
    - { label: Home, url: / }
    - { label: Shop, url: /shop }

# storia/components/header.yaml
component: Header
variants:
    default:
        args:
            menu: !data menu

# storia/pages/home/home.yaml
variants:
    default:
        args:
            menu: !data menu

Changing storia/data/menu.yaml updates every view that uses it. Files in storia/data/ are not views: they do not appear in the navigation.

Sub-paths

Sub-folders are part of the name (!data shop/catalog), and a dotted path reaches inside the file: !data menu.items.0 or !data shop/product.default.price.

Variants of a piece of data

A file can hold several entries, and with overrides some of their values (mappings are merged, lists are replaced):

# storia/data/product.yaml
default: { name: Chair, price: 49, inStock: true }
expensive: !data { ref: product.default, with: { price: 999 } }
sold_out: !data { ref: product.default, with: { inStock: false } }

Repeating an item: !repeat

!repeat builds a list from a template; {i} is replaced by the position (starting at 1) in every string of the item.

products: !repeat
    count: 4
    item:
        name: 'Product {i}'
        price: 19.99

Filler text: !lorem

!lorem generates a deterministic placeholder text, so the output is stable between two renderings: !lorem 12 (words), !lorem 2 sentences, !lorem 1 paragraph. It works in args and in blocks.

blocks:
    content: !lorem 3

Inside a !repeat, each item gets a different text, so a list of cards does not repeat the same sentence:

articles: !repeat
    count: 3
    item:
        title: !lorem 4
        summary: !lorem 2 sentences

PHP data providers

When the data needs logic (relative dates, computed values, business objects), use the same tag with a PHP method: !data App\Factory\ProductFactory::createDefault.

Tags are resolved in the args and blocks of a variant, and in the options of a form view.

Argument Resolver

UI Storia provides an Argument Resolver feature that allows you to dynamically generate arguments by calling PHP methods directly from your YAML configuration files.

Instead of hardcoding values in your variant arguments, you can reference a PHP class method with !data ClassName::methodName. UI Storia will call the method to generate the argument value.

How it works

The Argument Resolver supports both:

• Static methods: Called directly on the class
• Instance methods: If the class is registered as a service in the Symfony container, UI Storia will retrieve the service and call the method on it

Example

# storia/components/product.yaml

component: Product
variants:
    default:
        args:
            product: !data App\Factory\ProductFactory::createDefault
        blocks:
            content: ''

    expensive:
        args:
            product: !data App\Factory\ProductFactory::createExpensive
        blocks:
            content: ''

    outOfStock:
        args:
            product: !data App\Factory\ProductFactory::createOutOfStock
        blocks:
            content: ''

    static:
        args:
            product:
                id: 99
                name: Static Product
                price: 19.99
                inStock: true
        blocks:
            content: ''

In this example, the first three variants use the Argument Resolver to call methods from ProductFactory, while the static variant uses hardcoded values.

The ProductFactory class could look like this:

<?php

namespace App\Factory;

class ProductFactory
{
    public static function createDefault(): array
    {
        return [
            'id' => 1,
            'name' => 'Default Product',
            'price' => 29.99,
            'inStock' => true,
        ];
    }

    public static function createExpensive(): array
    {
        return [
            'id' => 2,
            'name' => 'Premium Product',
            'price' => 199.99,
            'inStock' => true,
        ];
    }

    public static function createOutOfStock(): array
    {
        return [
            'id' => 3,
            'name' => 'Sold Out Product',
            'price' => 49.99,
            'inStock' => false,
        ];
    }
}

Security

Everything in the storia/ folder is treated as code, like the rest of your application:

• !data Class::method calls any public method of any class or service of your project.
• The Markdown notes are rendered without sanitization.
• A block, or a value printed with |raw by your template, is output as HTML. A provider must not return content you do not control.

Never let storia/ be written by someone you do not trust, and never feed a provider with unchecked external data. Values coming from the data files or from the providers are always passed to the component as data, never compiled as Twig.

bin/console storia:export [output-dir]

The export stops at the first view, variant or asset that cannot be exported and tells which one:

Variant "components/badge:default" failed: Unable to find template "ui/badge.html.twig"

Output directory

The default directory is var/storia/export. It is emptied at each export, but only if it was created by a previous export (it contains a .storia-export file). Any other non-empty directory is refused.

index.html
components/badge/default.html           # page with menu, tabs and code
iframe/components/badge/default.html    # the rendered variant
bundles/iq2istoria/                     # UI Storia styles and scripts
css/, img/, ...                         # your assets

Assets

The export copies the assets your pages reference (stylesheets, scripts, images, fonts, import maps), and the assets referenced by those stylesheets. A referenced file is taken from public/ when it exists there; otherwise it is requested from your application, so assets served dynamically (AssetMapper in dev for instance) are exported too. Root-relative URLs (/assets/app.css) are rewritten as relative ones, so the export works from a sub-path or from file://.

Assets that are only referenced by JavaScript can be listed in the configuration. Patterns are relative to the public directory and support * and **:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    export:
        output_dir: '%kernel.project_dir%/var/storia/export'
        public_dir: '%kernel.project_dir%/public'
        assets:
            - 'images/**'

Deployment

The export only uses relative links, so it can be served from a sub-path such as https://user.github.io/my-repo/.

The command boots your application: run it in the environment where the bundle is registered (usually dev), with the development dependencies installed. If your assets are built by a tool such as Webpack Encore or Vite, build them before the export.

GitHub Pages

Set Settings > Pages > Source to GitHub Actions, then add this workflow:

# .github/workflows/storia.yaml

name: Storia

on:
    push:
        branches: [main]

permissions:
    contents: read
    pages: write
    id-token: write

concurrency:
    group: pages
    cancel-in-progress: true

jobs:
    deploy:
        runs-on: ubuntu-latest
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        steps:
            - uses: actions/checkout@v4

            - uses: shivammathur/setup-php@v2
              with:
                  php-version: '8.3'

            - run: composer install --no-interaction --prefer-dist

            - run: php bin/console storia:export var/storia/export
              env:
                  APP_ENV: dev

            - uses: actions/upload-pages-artifact@v3
              with:
                  path: var/storia/export

            - id: deployment
              uses: actions/deploy-pages@v4

GitLab Pages

# .gitlab-ci.yml

pages:
    stage: deploy
    image: php:8.3-cli
    variables:
        APP_ENV: dev
    before_script:
        - apt-get update && apt-get install -y git unzip
        - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
    script:
        - composer install --no-interaction --prefer-dist
        - php bin/console storia:export var/storia/export
    pages:
        publish: var/storia/export
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

The export is not written to public/, which is the default publish directory of GitLab Pages but also your application's public directory.

Limitations

• URLs built in JavaScript, and absolute URLs to a development server (http://localhost:5173), are not rewritten.
• Assets served from an absolute base URL (a CDN, asset() configured with base_urls) are neither rewritten nor copied: the exported pages keep pointing to that host.
• Browsers block ES modules on file:// pages: a project that loads its own modules must serve the folder over HTTP, or be opened with Firefox.
• The static export has no live reload.
• The static export has no controls.

1. Install the bundle

Follow the installation steps: require the package, register the routes and create the storia folder. The bundle is enabled in dev and test.

2. Create an anonymous component

An anonymous component is a Twig template in templates/components, without any PHP class:

{# templates/components/Alert.html.twig #}
{% props type = 'info' %}

<div class="alert alert-{{ type }}" role="alert">
    {% block content %}{% endblock %}
</div>

It is the template your integrators write from a mockup, and the one your pages will use: <twig:Alert type="danger">Something went wrong</twig:Alert>.

3. Describe it with variants

Create the YAML file that lists the states of the component:

# storia/components/alert.yaml

component: Alert

variants:
    info:
        blocks:
            content: Your profile has been saved

    warning:
        args:
            type: warning
        blocks:
            content: Your subscription ends tomorrow

    danger:
        args:
            type: danger
        blocks:
            content: Something went wrong

4. See the result

Open /storia/components/alert. You see the three variants as tabs, the rendered component, its Twig code and its HTML. The Controls tab already lets you change type and watch the result, as it comes from the {% props %} of the template.

Run bin/console storia:watch to reload the preview when you save a file.

5. Use real-looking data

Replace the hard-coded messages with generated text, so the component is also checked with long content:

        blocks:
            content: !lorem 30

See Data to share data between views.

6. Protect it with a test

bin/console storia:test

Every variant is rendered, and its HTML is saved as a snapshot the first time. Commit the snapshots: from now on, the command fails when a variant cannot be rendered or when its HTML changes by accident. See Testing.

What's next

• Read the workflow to see how integrators and developers work on the same files.
• Learn everything the YAML files accept in Interfaces.
• Publish the catalog with the static export.

Add iq2i/storia-bundle to your composer.json file:

composer require iq2i/storia-bundle

Register and configure the bundle

If you are using Symfony Flex, the following steps should be done automatically. Otherwise, follow the instructions.

Register the bundle

Inside config/bundles.php, add the following line:

// config/bundles.php

return [
    // ...
    IQ2i\StoriaBundle\IQ2iStoriaBundle::class => ['all' => true],
];

Add routes

Create a new routing file to add UI Storia's routes:

# config/routes/iq2i_storia.yaml
iq2i_storia:
    resource: '@IQ2iStoriaBundle/config/routes.php'
    prefix: '/storia'

Create folders where YAML files are stored

Create the storia folder at the root of your project, with two subfolders: components and pages.

Configure the bundle

By default, UI Storia will try to read YAML files in the storia folder at the root of your application. You can change this behavior by creating a configuration file config/packages/iq2i_storia.yaml with the following content:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    default_path: '%kernel.project_dir%/new-folder'

When is the bundle enabled?

UI Storia is enabled when kernel.debug is true, like the Symfony profiler: in dev and test, not in prod. Its routes answer with a 404 when it is disabled. The commands (storia:test, storia:export, ...) keep working in every environment.

The content of the storia/ folder is executed by the bundle, see Security.

Force the value with the enabled option when you need to:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    # expose UI Storia on a staging environment that runs with debug disabled
    enabled: true

# config/packages/iq2i_storia.yaml

iq2i_storia:
    # or turn it off everywhere, with an environment variable for easier configuration
    enabled: '%env(bool:IQ2I_STORIA_ENABLED)%'

Load your styles and scripts

UI Storia will render your interfaces without CSS or JavaScript.
To instruct UI Storia to use your styles and scripts, simply override the iframe.html.twig template following the Symfony documentation:

{# templates/bundles/IQ2iStoriaBundle/iframe.html.twig #}

{% extends '@!IQ2iStoria/iframe.html.twig' %}

{# if you use WebpackEncoreBundle #}
{% block stylesheets %}
    {{ encore_entry_link_tags('app') }}
{% endblock %}
{% block javascripts %}
   {{ encore_entry_script_tags('app') }}
{% endblock %}

{# if you use AssetMapper #}
{% block javascripts %}
   {% block importmap %}{{ importmap('app') }}{% endblock %}
{% endblock %}

To describe your interfaces, simply create a YAML file in the storia/components or storia/pages folder as follows:

# storia/components/progress.yaml

template: ui/progress.html.twig
variants:
    small:
        args:
            height: 1.5

    default:
        args:
            height: 2.5

    large:
        args:
            height: 4

    extra_large:
        args:
            height: 6

The difference between the storia/components folder and the storia/pages folder is as follows:
By convention, use the storia/components folder for interfaces related to macro components and the storia/pages folder for interfaces for more complete pages.

Here's the configuration details:

• template: Corresponds to the path to the Twig template of your Symfony application that you want to work with.
• variants: This is the list of different variants you want to create.

Template / Component

The template key is optional because you can also use a Twig template at the same level and with the same name as your YAML file. For example, for your YAML file storia/components/progress.yaml, you can create a file storia/components/progress.html.twig and this file will be used by UI Storia.

UI Storia also provides native support for Twig Component for your interfaces. To do this, simply replace the template key with the component key as shown below:

# storia/components/button.yaml

component: Button
variants:
    plain:
        args:
            class: plain
            label: Plain button

    outline:
        args:
            class: outline
            label: Outline button

Form Types

UI Storia provides native support for Symfony Form Types, allowing you to preview and test form fields in isolation.

To work with a Form Type, use the form key instead of template or component:

# storia/components/form/text.yaml

form: Symfony\Component\Form\Extension\Core\Type\TextType

# storia/components/form/choice.yaml

form: Symfony\Component\Form\Extension\Core\Type\ChoiceType
options:
    choices:
        'In Stock': true
        'Out of Stock': false

Automatic Variants

When using the form key, UI Storia automatically generates three variants for you:

1. default: The form field in its normal state
2. disabled: The form field with disabled: true option
3. error: The form field with a validation error displayed

Custom Variants

Declare your own variants with the variants key. They are added after the three automatic ones, and a variant with the same name as an automatic one replaces it.

A variant of a form accepts two keys instead of args and blocks:

• options: Form options merged over the global options of the file. The variant wins.
• with_errors: Set it to true to display a validation error.

# storia/components/form/choice.yaml

form: Symfony\Component\Form\Extension\Core\Type\ChoiceType
options:
    choices:
        'In Stock': true
        'Out of Stock': false
variants:
    preselected:
        options:
            data: true
    unavailable:
        options:
            data: false
            disabled: true

Options

The options key allows you to pass options to your Form Type constructor, just like you would when creating a form in Symfony:

# storia/components/form/email.yaml

form: Symfony\Component\Form\Extension\Core\Type\EmailType
options:
    required: false
    attr:
        placeholder: 'Enter your email'

Form Theme

You can also specify a custom form theme for rendering your form field using the form_theme key:

# storia/components/form/custom.yaml

form: App\Form\CustomType
form_theme: 'forms/custom_theme.html.twig'
options:
    label: 'Custom Field'

Variants

The variants key lists the different variations of your interface, passing different arguments to your template.

Each variant is described with a name (which can be overridden as shown in the example below) and an array of arguments called args. Twig Component support also brings a blocks key to configure HTML blocks that will be passed to your component. A block is plain HTML: it is printed as is and never compiled as Twig.

# storia/components/button.yaml

component: Button
variants:
    plain:
        args:
            class: plain
        blocks:
            content: Plain button
            svg: '<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="200" height="200" viewBox="0 0 42 42"><path d="M42 20H22V0h-2v20H0v2h20v20h2V22h20z"/></svg>'

    outline:
        name: My outline button 
        args:
            class: outline
        blocks:
            content: Outline button
            svg: '<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="200" height="200" viewBox="0 0 42 42"><path d="M42 20H22V0h-2v20H0v2h20v20h2V22h20z"/></svg>'

Advanced: include and extends

To share data between views, prefer named data. include: and extends: are advanced features meant for sharing YAML structure.

UI Storia supports two directives to avoid duplication across your YAML files: include: for sharing anchor definitions, and extends: for inheriting and overriding a complete configuration.

include: — Shared anchor definitions

The include: directive lets you define YAML anchors in a shared file and reuse them across multiple configuration files.

Create a shared file anywhere in your storia/ folder (conventionally prefixed with _ to indicate it is not a standalone view):

# storia/_shared.yaml

_definitions:
    default_badge: &default_badge
        class: bg-blue-100 text-blue-800 text-xs font-medium px-2.5 py-0.5 rounded

    large_badge: &large_badge
        class: bg-blue-100 text-blue-800 text-sm font-medium px-2.5 py-0.5 rounded

Then include it from any configuration file using include: and reference the anchors with the standard YAML * syntax:

# storia/components/badge.yaml

include: _shared

template: ui/badge.html.twig
variants:
    default:
        args:
            <<: *default_badge

    large:
        args:
            <<: *large_badge

You can include multiple files using a list:

include: [_colors, _sizes]

# or equivalently:
include:
    - _colors
    - _sizes

extends: — Configuration inheritance

The extends: directive allows a configuration file to inherit all settings from a parent file and selectively override only the parts that differ.

# storia/components/badge.yaml

template: ui/badge.html.twig
variants:
    default:
        args:
            class: bg-blue-100 text-blue-800 text-xs font-medium px-2.5 py-0.5 rounded
    large:
        args:
            class: bg-blue-100 text-blue-800 text-sm font-medium px-2.5 py-0.5 rounded
    bordered:
        args:
            class: bg-blue-100 text-blue-800 text-xs font-medium px-2.5 py-0.5 rounded border border-blue-400

# storia/components/badge-red.yaml

extends: components/badge

variants:
    default:
        args:
            class: bg-red-100 text-red-800 text-xs font-medium px-2.5 py-0.5 rounded
    large:
        args:
            class: bg-red-100 text-red-800 text-sm font-medium px-2.5 py-0.5 rounded

In this example, badge-red.yaml inherits the template key and the bordered variant from the parent, and only overrides default and large.

The merge is deep: nested keys (like args within a variant) are merged individually, so you can override a single argument without redefining all the others.

Extensions can be chained — a file that uses extends: can itself be extended by another file.

Notes

A Markdown file next to the YAML file, with the same name, becomes the Notes tab of the view. Use it to document the component: when to use it, accessibility rules, links to the design.

storia/components/button/button.yaml
storia/components/button/button.md

The file is rendered as HTML, and the tab only appears when the file exists.

Requirements

storia:watch runs a small native binary shipped with the bundle in tools/watcher/bin/. It uses the notifications of the operating system, so it is fast and light. The binary is chosen from your system:

The command fails with an explicit error on any other operating system.

If your application runs in Docker, start the command inside the PHP container: the Linux binary is used there, and it watches the files as the container sees them.

docker compose exec php bin/console storia:watch

The live reload is only available in the application. A static export has no live reload.

Starting the watcher

Run the following command to start watching for file changes:

bin/console storia:watch

The watcher will display which directories it is monitoring and log every detected change:

Watching [page]: /path/to/project/storia
Watching [iframe]: /path/to/project/templates
Watching [iframe]: /path/to/project/assets
Watching for changes… (Ctrl+C to stop)
[14:23:07] Change detected: /path/to/project/storia/components/badge.yaml (write) → page reload
[14:23:41] Change detected: /path/to/project/templates/ui/badge.html.twig (write) → iframe reload

Press Ctrl+C to stop the watcher. The browser will automatically disconnect from the live reload stream.

Reload behaviour

UI Storia distinguishes between two types of changes:

• Changes in the storia/ folder (YAML files) trigger a full page reload — the menu and component metadata are refreshed.
• Changes in templates or assets trigger an iframe-only reload — the preview is refreshed without touching the page shell.

Configuring watched paths

By default, UI Storia watches templates/ and assets/ for iframe reloads. You can customise this list in your configuration file:

# config/packages/iq2i_storia.yaml

iq2i_storia:
    watch:
        - '%kernel.project_dir%/templates'
        - '%kernel.project_dir%/assets'
        - '%kernel.project_dir%/src/Twig'

The storia/ folder (defined by default_path) is always watched for page reloads and does not need to be listed here.

View files

A view file is a YAML file in storia/components or storia/pages. The path of the file without its extension is the path of the view.

template, component and form cannot be used together.

Variants

A form view always has the variants default, disabled and error. A variant with the same name replaces the automatic one.

Tags

Available in args, blocks and form options. See Data.

Data files

Files of storia/data are not views. They hold any YAML value, referenced by their path without extension.

Bundle configuration

iq2i_storia:
    default_path: '%kernel.project_dir%/storia'
    enabled: ~          # default: kernel.debug
    watch:              # paths watched for iframe reloads
        - '%kernel.project_dir%/assets'
        - '%kernel.project_dir%/templates'
    export:
        output_dir: '%kernel.project_dir%/var/storia/export'
        public_dir: '%kernel.project_dir%/public'
        assets: []
    test:
        snapshot_path: '%kernel.project_dir%/tests/storia/snapshots'

Commands

PHPUnit

bin/console storia:test

The command renders every variant of every component and page, then compares the HTML with its snapshot:

✓ components/badge:default
≠ components/badge:large
✗ components/product:expensive
    Twig\Error\RuntimeError: Variable "price" does not exist.

41 variants, 39 passed, 0 new, 0 updated, 2 failed

• ✗ the variant cannot be rendered (Twig or PHP error). It always fails the command.
• ≠ the rendering differs from the snapshot. A diff is shown (install sebastian/diff to get it) and the command fails.
• + the variant has no snapshot yet: it is written and the command does not fail, except in CI (see below).
• ↻ the snapshot was rewritten because of --update.
• ? a view defines no variant, or a snapshot has no variant any more: nothing is tested. A view without variant fails the command in CI.

The exit code is 1 as soon as one variant fails, 0 otherwise, so the command can be used as is in a CI job. When the CI environment variable is set (GitHub Actions and GitLab CI set it), or with --ci, a missing snapshot is an error instead of being written: a file written on a runner is lost, and the variant would never be compared.

# .gitlab-ci.yml

storia:
    stage: test
    script:
        - composer install --no-interaction --prefer-dist
        - php bin/console storia:test

Snapshots

A snapshot is the HTML of one variant, without the preview page around it, stored in tests/storia/snapshots/<view>/<variant>.html. Commit them: they are reviewed in your merge requests like any other file. Only line endings and trailing spaces are normalized, nothing else is reformatted. The HTML also depends on the rendering stack: upgrading Symfony or Twig can change a form theme or an attribute, review the diff and accept it with --update.

Snapshots are never rewritten silently. When a change is intended, accept it explicitly:

bin/console storia:test --update

A snapshot whose variant no longer exists is reported with ? but does not fail the command; delete the file.

Snapshots can only be stable if the rendering is. !repeat and !lorem are deterministic, and the CSRF protection of a form view is disabled by UI Storia, so no _token ends up in a snapshot. A PHP data provider is yours to make deterministic: seed Faker, avoid new DateTime() and random values, and give versioned asset URLs a stable value in the test environment. A variant that cannot be stable can be left out with --no-snapshots.

# config/packages/iq2i_storia.yaml

iq2i_storia:
    test:
        snapshot_path: '%kernel.project_dir%/tests/storia/snapshots'

Options

PHPUnit

For custom assertions, expose the variants as a data provider and use the StoriaTestCaseTrait in a KernelTestCase:

use IQ2i\StoriaBundle\Test\PHPUnit\StoriaTestCaseTrait;
use IQ2i\StoriaBundle\Test\PHPUnit\StoriaVariants;
use PHPUnit\Framework\Attributes\DataProvider;
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;

final class StoriaTest extends KernelTestCase
{
    use StoriaTestCaseTrait;

    #[DataProvider('provideVariants')]
    public function testVariant(string $path, string $variant): void
    {
        $view = $this->assertVariantRenders($path, $variant);

        self::assertStringNotContainsString('TODO', (string) $view->getHtmlContent());
    }

    public static function provideVariants(): array
    {
        return StoriaVariants::fromDirectory(__DIR__.'/../storia');
    }
}

StoriaVariants::fromDirectory() reads the YAML files without booting the kernel, as a data provider runs before any test. The StoriaVariants::provide() method can also be used with #[DataProviderExternal]: it reads the directory from the STORIA_PATH environment variable, or ./storia. assertVariantMatchesSnapshot() compares a variant with its snapshot.

Screenshots (Panther) and accessibility checks are not covered yet.

The test suite runs in CI on the lowest and the highest supported versions of PHP and Symfony, and on the next Symfony version in development.

Compatibility policy

UI Storia follows Semantic Versioning. Within a major version, what is stable keeps working, and what is internal can change in any release.

What is stable

• The YAML format of the view files and the data files, as listed in the reference.
• The iq2i_storia configuration of the bundle.
• The commands and their arguments and options: storia:watch, storia:export, storia:test, storia:list, storia:render. The JSON printed by storia:list --format=json only gets new keys.
• The PHPUnit helpers IQ2i\StoriaBundle\Test\PHPUnit\StoriaVariants and IQ2i\StoriaBundle\Test\PHPUnit\StoriaTestCaseTrait.
• The templates and blocks you can override, such as iframe.html.twig.

What is internal

Every other class of the bundle (builders, resolvers, exporter, renderer, controllers, DTOs) is marked @internal. Do not extend or call it: it can change in a minor or a patch release. The HTML of the UI Storia interface and its CSS classes are internal too.

Deprecations and support

• A feature is deprecated in a minor version, with a deprecation notice that tells what to use instead, and removed in the next major version.
• Dropping the support of a PHP or Symfony version is done in a minor version, never in a patch version. A PHP version is supported until its end of life, a Symfony version until the end of its bug fixes.
• A new snapshot format would be a major change: the snapshots written by storia:test are plain HTML files, normalized in the same way for the whole major version.

Upgrade from 0.5 to 0.6

UI Storia is enabled with kernel.debug only

The bundle used to be always enabled. It is now enabled when kernel.debug is true, as the Symfony profiler. If you expose UI Storia on an environment that runs with debug disabled (a staging environment for example), force it:

# config/packages/staging/iq2i_storia.yaml
iq2i_storia:
    enabled: true

Nothing changes in dev and test. The commands work in every environment.

iq2i_storia_menu() is removed

The sidebar is built by the bundle. If you override view.html.twig and call this function, copy the sidebar markup from the new template instead. Most projects only override iframe.html.twig, which is not affected.

Use !data to call PHP

A bare Class::method string in an argument is still resolved, with a deprecation notice. Replace it with the tag:

# before
product: App\Factory\ProductFactory::createDefault

# after
product: !data App\Factory\ProductFactory::createDefault

symfony/form and symfony/ux-twig-component are optional

Both are suggested packages. Install them to preview form types and Twig Components:

composer require symfony/form symfony/ux-twig-component

Form variants

Form views accept custom variants with options and with_errors. The options of a variant now win over the global options of the file. If you relied on a global option overriding an automatic variant, for example disabled: false in options, move it to a declared variant.

Snapshots

storia:test writes its snapshots in tests/storia/snapshots. Commit them, and set iq2i_storia.test.snapshot_path to use another folder. Run storia:test in your CI: a view without variants and a missing snapshot make the command fail there.

Variant names

The name key of a variant is now used as the label of its tab. Remove it from your files if you do not want the label to change.

Blocks are plain HTML

The blocks of a component are printed as is and are no longer compiled as Twig. Move the logic to an argument or to the component template:

# before
blocks:
    content: '<strong>{{ "now"|date("Y") }}</strong>'

# after
blocks:
    content: '<strong>2026</strong>'

Sidebar

The sidebar lists the views found in the storia/components and storia/pages folders. Sub-folders become collapsible groups. Labels are deduced from the file names: buttonGroup.yaml is displayed as "Button group".

Drag the separator between the sidebar and the content to resize it.

Variants

The tabs on top of the preview are the variants of the current view. The selected variant is part of the URL (?variant=large), so you can share a link to it.

Preview actions

The actions on the right of the variants act on the preview:

The preview is rendered in an iframe, with the styles and scripts of your application: see Load your styles and scripts. Drag the vertical separator on its right to test your component at another width.

Code tabs

Under the preview, the tabs show what is rendered for the current variant. Each code block has a button to copy it.

The Controls, Include and Notes tabs only appear when the view has something to show in them. Drag the horizontal separator between the preview and the tabs to give more room to one or the other.

Views without variants

A view that defines no variant is listed in the sidebar, but there is nothing to preview. Add at least one variant: storia:test reports a view without variants as an error in CI.

What a port of Twig breaks

Tools that run on Node cannot call your PHP application. To display a Twig template, they need a JavaScript implementation of Twig, or a bridge to the server. Components then diverge from what your application renders:

• Symfony UX components (<twig:Button>), {% props %}, and anonymous components are not plain Twig.
• Filters, functions and tests written in PHP, or coming from Symfony bundles (path(), asset(), trans, ux_icon()), do not exist on the JavaScript side.
• Form themes and Symfony forms need the PHP form component.
• Each new Twig feature must be supported by the port before you can use it.

UI Storia renders the templates of your project with your Twig environment. If it works in the catalog, it works in the application.

Comparison

Check the current state of each tool before choosing: they evolve, and this table describes the general approach of each.

When another tool is a better fit

• Your design system is written in React, Vue or Web Components: use Storybook.
• You want visual regression testing of screenshots, or interaction tests: UI Storia only compares HTML.
• Your front-end is not a Symfony application.

Integrator first, then developer

1. From the mockup to a component. The integrator creates an anonymous component in templates/components, with Twig and CSS only. No PHP, no controller, no database.
2. Variants. They describe each state of the mockup (default, large, disabled, empty, long text...) as a variant in storia/components. The catalog now documents the component and can be reviewed by the designer.
3. Real data. When the component needs structured data, they write it once in storia/data, with !data, !repeat and !lorem.
4. Behavior in PHP, only when needed. When the component needs logic, the developer replaces the anonymous template with a Twig Component class of the same name. The template and the variants do not change: they are the specification.
5. A safety net. storia:test renders every variant and compares it with its snapshot. Run it in CI: a change of a component that alters another one shows up in the diff of the snapshots.

Why it works

• The integrator never leaves Twig and YAML, but works with the real templates of the application, so what they validate is what ships.
• The developer gets a catalog of every state of every component, without writing stories.
• The snapshots are plain HTML files in tests/storia/snapshots, reviewed in the same pull request as the change.

In practice