From mockup to theme #

This page is for theme designers who plan a project from the first sketch to a published theme. It describes seven stages, what each stage produces and who usually owns it. The technical steps (writing templates, packaging the extension) are documented elsewhere; this page tells you when they happen and links to them.

Contents #

1. The seven stages
2. Stage 1: inventory
3. Stage 2: foundations
4. Stage 3: components
5. Stage 4: templates of record
6. Stage 5: static prototype
7. Stage 6: the theme extension
8. Stage 7: review and launch
9. When stages overlap

The seven stages #

Stage 1: inventory #

Before drawing, list what exists: content classes and their fields, the view modes each class appears in, the special pages (search, sign-in, errors, forms) and, if the site uses layouts, the block types and view types. On an existing site, the first day plan produces this list. On a new site, it comes from the content model (Designing a content model), so sit with the developer while the classes are decided: a field that is not in the class cannot appear in your design.

Hand-off: the inventory, agreed in writing.

Stage 2: foundations #

Decide the small set of values everything else uses: a type scale, a spacing scale, a color palette with roles, one radius, one accent. Give every value a role name now, because each becomes a CSS custom property (Type scale, Spacing and grid, Color palettes and ramps). Draw the dark values at the same time; adding them later costs twice as much.

Hand-off: a token table (name, light value, dark value, use), see From design tool variables to CSS custom properties.

Stage 3: components #

Draw the reusable pieces (buttons, cards, tags, form fields, pagination, alerts) with all their states: hover, focus, active, disabled, current, error (Designing interactive states). Each component uses only tokens.

Hand-off: the component inventory.

Stage 4: templates of record #

Now draw pages, but think in templates: the frame (header, navigation, footer) once, then one mockup per class and view mode, then the special pages. Use real content at its shortest and longest (Designing with real content). Mark which parts are optional fields, so the developer knows what to hide when a field is empty (Designing for editors).

Hand-off: frame, views per class, special pages, each at three widths, in light and dark.

Stage 5: static prototype #

A static HTML and CSS prototype catches most layout problems before any template exists. Keep it honest:

• one stylesheet for tokens, one for components, no inline styles;
• class names with your theme's prefix, for example mytheme-card;
• no fonts or scripts from third-party hosts (Fonts in a design).

Whoever writes the templates later can then move markup and stylesheets almost unchanged, as the porting tutorial shows step by step.

Hand-off: the prototype in the theme's Git repository, see Working with developers.

Stage 6: the theme extension #

The prototype becomes a design extension: the frame becomes pagelayout.tpl, each mockup a view template, the stylesheets are listed in the design settings and packed. The tutorials cover this: Create a theme extension and Override a full view. Designers who do not write templates review each template against its mockup in this stage.

Stage 7: review and launch #

Review on a preview siteaccess with real content (Working with clients and reviews), run the design QA checklist, then the project's launch, accessibility, dark mode and performance checklists. A theme that will be published continues with Distributing a theme: start here.

When stages overlap #

Stages 2 to 5 often overlap, and that is fine. Two rules keep the overlap safe:

• a token or component changes in the inventory first, then in mockups and code;
• nothing reaches stage 6 that was never seen with real content.

Related pages #

• Handoff checklist
• Theme design review checklist
• Choosing a starting theme
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.