---
title: "Feature: A styleguide page"
manual: "Frontend Theme for Extension Development"
version: "main"
source: "Changelog/2.0/Feature-Styleguide.rst"
modified: "2026-09-17T04:52:50+00:00"
---

# Feature: A styleguide page

## Description

The extension now ships a **styleguide**: one page that renders every component
of the [component library](Feature-ComponentLibrary.html#feature-component-library) from its own Fluid
templates, so the whole theme can be looked at in one place, in the appearance
and colour palette currently selected.

The seeded demo tree carries it at `/styleguide`
([Feature: A seeded showcase of every element](Feature-SeededShowcaseTree.html#feature-seeded-showcase-tree)), reachable by URL and hidden from every
menu. It is set to **Page not enabled in menus** rather than disabled: a
disabled page answers 404 in the frontend and needs a backend preview link,
which defeats the point of a page that exists to be opened.

Eight sections, each its own partial:

| Partial | Section | What it shows |
| --- | --- | --- |
| `Styleguide/Tokens.html` | Tokens | All 27 colour tokens as swatches, plus the type scale, weight and family, the spacing scale, radius, shadow and the focus ring. |
| `Styleguide/Typography.html` | Typography | The element baseline every tag gets without a class - headings, running text, inline elements, lists, quotations, preformatted text, rules - and the table component. |
| `Styleguide/Buttons.html` | Buttons | `.theme-button` with every modifier, size and state it ships, the close button, the button group, and `.theme-badge` in both severities and fills. |
| `Styleguide/Boxes.html` | Boxes | Card, panel, teaser, hero, quote, alert, accordion and author, each with every modifier its stylesheet defines. |
| `Styleguide/Interactive.html` | Interactive | Tabs, dialog and tooltip - the components that need JavaScript - and what each of them does without it. |
| `Styleguide/Forms.html` | Forms | The complete form contract: the field wrapper, every input type, select and textarea, fieldsets, checkboxes and radios, the validation states, disabled and read-only. |
| `Styleguide/Navigation.html` | Navigation | Main and sub navigation, breadcrumb, pagination and the content menu. |
| `Styleguide/Media.html` | Media | The gallery in one, two and three columns, and the content element wrapper with its outline switch. |

## The page ignores its own content

Nothing on this page comes from a content element, a record or a data
processor. That is deliberate: a styleguide shows the *contract*, and a
specimen assembled from a record would show whatever that record happened to
contain and would break for reasons that have nothing to do with the component.

Two things implement it. The **Styleguide** backend layout offers a
single column with `colPos 999`, which no TypoScript object in the extension
reads - anything an editor places there is stored and never rendered, inert
rather than broken. And the template contains no `f:cObject` at all, not even
for the main column.

> [!NOTE]
> The layout cannot simply declare no column. TYPO3 registers a backend
> layout only when its `config.backend_layout.` block is non-empty, and a
> `rows` key that is present but empty renders a page module grid with no
> rows and therefore no way to add content at all. One column that nothing
> renders is the outcome that keeps the page module usable.

## Overriding a section

Each section is a partial of its own under
`EXT:theme_extension_development/Resources/Private/Partials/Styleguide/`,
so a site package that wants its own forms section overrides
`Styleguide/Forms.html` and keeps the other seven. That is the same
fine-grained override the rest of the theme follows.

Specimen copy is literal English and is not routed through
`locallang.xlf`. Specimen text exists to be set in a typeface; it has
nothing to localise, and roughly 150 translated labels would make the specimens
unreadable in the source, which is the one place they have to be readable.

## Impact

Importing the showcase with
`vendor/bin/typo3 data-factory:import theme-demo` gives a frontend where
`/styleguide` answers with the whole component library. It is the only place
the design tokens can be seen *resolved* rather than read as values, and
because of that it doubles as a live test of the appearance and palette
settings: change either one behind the cog in the header, and every swatch and every
specimen on the page has to move together. One that does not is a colour that
escaped the token layer.

The **Elements** pages of the demo tree remain complementary rather
than redundant. Those render the same components from real content records, so
they prove the wiring; this page proves the library. A component can break in
one without the other noticing - most of the form contract, for instance, is
reached by no content element at all.

## Three fixes come with it

All three were found by putting a second instance of a component on one page,
which nothing before this did:

-   **Only the first main navigation toggle was bound.** The stylesheet
    collapses *every* `.theme-nav-main` whose toggle is not expanded,
    while the script wired up only the first toggle on the page. A second
    navigation - a footer menu repeating the main one - was collapsed below the
    breakpoint by a control that did nothing, with no way left to open it.
    Every toggle is now bound, scoped to the navigation it belongs to.
-   `.theme-form-summary--error` **matched no rule.** It was part of the
    published markup contract and of the documentation but had never been
    declared. The base rule already carries the danger palette, so it looked
    correct; it is now declared explicitly, symmetric with
    `.theme-form-summary--success`.
-   **The alert markup contract showed the wrong role.** It illustrated
    `role="status"` on a `.theme-alert--warning`, which invites
    copying an assertive severity as a polite one. `--info` and
    `--success` take `role="status"`; `--warning` and
    `--danger` take `role="alert"`.