Styleguide for TYPO3

Why Styleguide is the most important QA extension for TYPO3 template developers

Template development in TYPO3 has a systematic quality problem: developers test their Fluid templates with the data that currently exists on the website. But content elements have dozens of variants - headlines with and without subheadline, text blocks with 3 words or 3 paragraphs, images in portrait and landscape, tables with 2 or 20 columns. Anyone checking only the current page misses the edge cases that surface only after launch.

The Styleguide extension solves this problem by automatically creating a demo page tree that shows every core content element on its own page. The developer immediately sees whether their CSS and templates correctly handle all variants.

Typical use cases

Template development during relaunch projects. A company commissions a TYPO3 relaunch with a new corporate design. The frontend developer creates Fluid templates for all content elements. Without Styleguide, test data must be created manually in the backend for each element - a process that takes hours with 30+ content elements. Styleguide generates all test data automatically: text elements in various lengths, images in different aspect ratios, lists, tables, uploads, forms. The developer clicks through the demo pages and sees every element in the frontend.

Regression tests after TYPO3 updates. A TYPO3 update from v11 to v12 subtly changes the rendering of individual content elements. A textmedia element suddenly renders an additional wrapper div that breaks the CSS layout. Without Styleguide, this is only noticed when an editor reports the error on a live page. With Styleguide, the developer sees immediately after the update which elements have changed.

Alignment between design and development teams. Designers deliver Figma mockups for 10 content elements. But how do the remaining 25 standard elements look in the new design? Styleguide makes this gap visible: every element has its own demo page, missing designs are immediately apparent. Gosign uses Styleguide in every relaunch project as the sign-off tool for the design team.

Technical architecture

Styleguide is an official TYPO3 Core system extension that has lived in the Core repository since v13 but is not part of the source package. It is installed via Composer (typo3/cms-styleguide), up to v12 also from the TER, and then activated.

The extension operates on two levels:

• TCA Generator: Styleguide creates test records for its own demo tables (tx_styleguide_*), which show nearly every TCA field type of the backend. For each field, a meaningful test value is produced - texts in various lengths, images from FAL, relations to other records.
• Backend Module: through the backend module, the administrator can create and delete the test data. The data lives in dedicated page trees (“styleguide TCA demo”, “styleguide frontend demo”) and does not affect regular content.
• Frontend Rendering: a dedicated page tree displays the generated content elements in the frontend layout, one page per content type. The developer sees the elements exactly as they would appear on the live website.

Styleguide has no external dependencies. As a Core extension, it is automatically updated with every TYPO3 update and is always compatible with the respective TYPO3 version.

Important: Styleguide does not generate test data for custom content elements (e.g. Mask or DCE). It covers only the Core content elements. For custom elements, the developer must create their own test data or use a supplementary tool.

Common problems and solutions

Styleguide page shows empty areas. Test data was generated, but the frontend page does not display all elements. Cause: the demo pages run as their own site with their own root template instead of the website’s, or the TypoScript setup for the Styleguide page is missing. Solution: check in the backend module whether the page tree was correctly created and ensure the root template of the Styleguide page uses the same TypoScript as the regular website.

Images missing from generated test data. Styleguide tries to include test images through FAL (File Abstraction Layer). Styleguide ships its own sample images and copies them into the storage with UID 1; if that storage is missing or misconfigured, image fields remain empty. Solution: check the fileadmin storage (UID 1) before generating test data.

Performance issues with the Styleguide page. Creating the demo page trees produces many records at once and, according to the documentation, takes a few seconds. This is acceptable for QA but can strain the server under concurrent access. Solution: activate Styleguide only on the development or staging environment, never on the live system.

Migration and version compatibility

Styleguide has lived in the Core repository since TYPO3 v13 and has been released with every TYPO3 version since. Up to v12 it had its own version numbers, last 12.0.5; since v13 they follow the Core release.

During a TYPO3 upgrade, Styleguide test data should be regenerated after the update. Old test data may be inconsistent on the new system because TCA definitions change between TYPO3 versions. The backend module provides separate buttons for deleting and recreating the demo page trees.

For TYPO3 v12 and v13, Styleguide is available without restrictions. The extension keeps up with new Core features: according to its README, core developers keep it updated when the Core adds or deprecates features.

Gosign integrates Styleguide into every TYPO3 relaunch as a fixed part of the QA process. The Styleguide page is set up on the staging environment as a permanent reference and serves the design team as a sign-off URL. Changes to Fluid templates or CSS are immediately visible there without anyone needing to create test content on individual pages. For enterprise clients with multiple brands or tenants, a separate Styleguide page is generated per tenant to compare brand-specific template variants.