Component inventory #

This page is for theme designers who want one agreed list of every reusable piece of their theme. A component inventory is a table, not a tool: one row per component, with its states, the tokens it uses, the template that draws it and the CSS class that styles it. It is the contract between design and code, and it is what reviewers check against. The administration has its own shared components (admin4 components), which you reuse and never copy; this page is about the components of a public theme.

Contents #

1. What counts as a component
2. One entry
3. A starter inventory
4. From inventory to code
5. Naming
6. Keeping it current

What counts as a component #

Something is a component when it appears in more than one template, or is likely to. A card that appears in a folder list, a related list and a layout block is a component. A headline style used only in the article full view is not; it belongs to that template.

One entry #

A starter inventory #

Most content sites need about twenty components. Use this list as a start and remove what the site does not use:

Each component has the interactive states from Designing interactive states.

From inventory to code #

• Markup. Components used by several templates live in one template part, included where needed (Include): {include uri='design:parts/card.tpl' node=$child heading_level=3}. One component, one template part, so markup changes in one place.
• Styles. Components go in one components stylesheet of the design, listed in the design's stylesheet settings and packed (Loading stylesheets); never a <style> block or a style="" attribute (No inline CSS).
• Values. Components use tokens only (Design tokens). A component that needs a value with no token is a signal to add a token, with its dark value, not to write the value in.
• Variants. A variant is a modifier class, never an inline style or a per-page stylesheet.

Naming #

• One prefix for the whole theme (mytheme-), so your classes never collide with the kernel's, an extension's or another theme's.
• Name by role: mytheme-card, mytheme-alert--error, not mytheme-blue-box.
• The same name in the inventory, the design tool, the template part and the CSS class. If the design tool calls it "Teaser" and the CSS calls it "card", someone will build it twice.

Keeping it current #

• The inventory lives in the theme's repository next to the code, as a Markdown table or a page in the theme's documentation (Writing the README of a theme).
• A change to a component changes the inventory in the same commit.
• Review it once per release: remove components no template uses, merge near-duplicates.
• A style guide page on a development site shows every entry live, which is the easiest way to see what drifted.

Related pages #

• Building a style guide page
• From mockup to theme
• Template style guide
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.