Building a style guide page
This page is for theme designers (with a developer, if you do not write templates yourself) who want a page that shows every token and component of the theme, drawn by the theme's own templates and stylesheets. Unlike a style guide in a design tool, this one cannot drift from the code: if a component changes, the page changes. It is the place where reviews start and where editors can see what the design offers.
Contents
- What the page shows
- How it is built
- Step by step
- Showing tokens without inline styles
- Keeping it out of the way
- Using it
What the page shows
- Tokens: the color palette with each role name, the type scale, the spacing scale, the radius.
- Typography: every heading level, body text, lists, quotes and tables, as rich text renders them.
- Components: every entry of the component inventory, in each variant and state that can be shown statically.
- Views: a few real objects in each view mode (line, card, embed).
How it is built
The page is a normal content object (for example a folder named "Style guide") whose full view gets its own template through an override that matches the node's remote id. The override technique is documented in Override a single node; a remote id keeps the rule working when the content is moved to another installation.
Step by step
On the development installation, create a folder "Style guide" in a place visitors do not browse (see Keeping it out of the way). Give it a readable remote id, or ask the developer to create it from the theme's content package with one (Demo content for a theme).
Add the override to your design extension's
settings/override.ini.append.php:[mytheme_style_guide] Source=node/view/full.tpl MatchFile=full/style_guide.tpl Subdir=templates Match[node_remote_id]=mytheme-style-guideWrite
design/mytheme/override/templates/full/style_guide.tpl. Build it from the same template parts the theme uses, so the page shows the real markup:{* Style guide: every component, drawn by the theme's own parts *} <article class="mytheme-styleguide"> <h1>'Style guide'|i18n( 'design/mytheme' )</h1> <section aria-labelledby="sg-buttons"> <h2 id="sg-buttons">'Buttons'|i18n( 'design/mytheme' )</h2> include uri='design:parts/button.tpl' label='Primary' variant='primary' include uri='design:parts/button.tpl' label='Secondary' variant='secondary' </section> <section aria-labelledby="sg-cards"> <h2 id="sg-cards">'Cards'|i18n( 'design/mytheme' )</h2> foreach fetch( 'content', 'list', hash( 'parent_node_id', $node.node_id, 'limit', 6 ) ) as $child node_view_gui content_node=$child view='card' /foreach </section> </article>Put a few stress-set objects under the style guide folder, so the card section shows real extremes (Designing with real content).
Clear the template override cache, because the template file is new (a developer task: Caching for designers), and open the page.
Showing tokens without inline styles
A swatch page is where inline styles creep in (style="background: #0b5cad"). Never do that: it breaks the
no-inline-CSS rule and a strict Content Security Policy. Give each swatch a class instead, in a small stylesheet of
the style guide:
/* design/mytheme/stylesheets/styleguide.css */
.mytheme-swatch { inline-size: 6rem; block-size: 3rem; border: 1px solid var(--site-line);
border-radius: var(--site-radius); }
.mytheme-swatch--ink { background: var(--site-ink); }
.mytheme-swatch--surface { background: var(--site-surface); }
.mytheme-swatch--accent { background: var(--site-accent); }
.mytheme-swatch--muted { background: var(--site-muted); }Because the swatches use the tokens, switching the page to dark shows the dark palette with no extra work. Load
styleguide.css only where it is needed, or accept the few lines in the packed file; do not add a version query to
its link (No version queries on asset links).
Keeping it out of the way
- Place the folder where navigation fetches do not reach, or in a section the main menu skips.
- Hide it from visitors if the site is public: a section with no anonymous read access is the usual choice, decided by the administrator (Sections, roles and policies).
- Keep it out of search results and sitemaps the same way.
Using it
- Start every design review here, in light and dark, at the three widths (Working with clients and reviews).
- Show editors which components and block view types exist.
- Compare against the inventory once per release; anything on the page that is not in the inventory, or the other way round, is drift.
Related pages
- Component inventory
- Design tokens
- Override basics
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.