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 rendering all content elements of the TYPO3 system in every available configuration on a single 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 opens a URL and sees everything at a glance.

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: all elements are displayed on a single 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 ships with the TYPO3 source code. It only needs to be activated in the Extension Manager - no separate installation is required.

The extension operates on two levels:

• TCA Generator: Styleguide analyzes the Table Configuration Array (TCA) definitions of all registered content elements and generates test records from them. 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 generate, update and delete the test data. The data is stored in a dedicated SysFolder and does not affect regular content.
• Frontend Rendering: a special page in the page tree displays all generated content elements in the frontend layout. 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 SysFolder with the test data is not correctly configured as the starting point, 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). If the fileadmin folder is empty or the default storage configuration is incorrect, image fields remain empty. Solution: manually upload at least one image to fileadmin before generating test data.

Performance issues with the Styleguide page. When all content elements are rendered on a single page, loading time with complex templates can reach 10 to 15 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 been available as a Core system extension since TYPO3 v8 and is automatically updated with every TYPO3 version. There are no separate version numbers or compatibility issues because the extension is part of the Core release process.

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 a “Reset” function that deletes all test data and recreates it.

For TYPO3 v12 and v13, Styleguide is available without restrictions. The extension even benefits from new Core features: in v12, additional content elements (e.g. improved textmedia variants) were introduced that Styleguide automatically covers.

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.