WordPress theme development needs a clear agreement about templates, supporting assets and who may change the finished design. Start by identifying whether the project uses a block theme or a classic theme. For a block theme, record both the files being delivered and the Site Editor changes that may exist in the database before accepting a handover.
A theme folder alone is an incomplete explanation of what an editor can change. The useful deliverable is a small map: which template serves each type of page, which sections are shared, where styles live, and who owns future changes. That map lets a business request a precise correction instead of asking someone to rebuild an entire page.
What belongs in the theme structure?
A block theme needs a style.css file containing its identifying theme data. The templates/index.html file is the required fallback for a block theme. These are the two required files identified in the WordPress theme structure documentation. A folder containing attractive mock-ups does not establish that either requirement has been met.
WordPress automatically loads functions.php after the theme is initialised. The theme.json file configures settings and styles that integrate with the user interface. Treat those as different responsibilities: one concerns executable PHP, while the other concerns the design settings exposed through the system. In a handover, ask the developer to explain each file that the project actually uses rather than assuming every optional file must exist.
WordPress automatically registers pattern files placed in the patterns folder. An assets folder is a common convention for additional theme CSS, media and JavaScript. The same handbook makes clear that additional folders can have other names. Therefore, an acceptance checklist should verify that an asset can be traced to its source and purpose, rather than rejecting a sensible structure because its folder is named differently.
| Element | Responsibility to describe | Handover evidence |
|---|---|---|
| Default template | Fallback page structure | File location and a page that exercises it |
| Shared header or footer | Repeated navigation and identity | Part name and templates that include it |
| Design settings | Available typography, spacing and colours | Relevant settings and editor demonstration |
| Pattern | Insertable arrangement of blocks | Name, intended use and inserted example |
| Supporting asset | A required stylesheet, script or image | Source, loading context and owner |
| Site Editor change | A saved variation on the supplied design | Database change and reproduction decision |
Keep the map proportional to the site. A small brochure site may need only a few rows. An elaborate diagram that nobody can update is less useful than a concise list that answers which file or saved setting controls the affected page.
How do templates differ from ordinary page content?
Block theme templates are HTML files containing block markup. Template parts are reusable sections within top-level templates. The template introduction explains how WordPress combines these structures with dynamic data to produce the HTML a visitor receives. A template is therefore a rule for presenting content, rather than simply another page of sales copy.
Use that distinction during a review. Ask an editor to change one page’s text and then inspect another page using the same template. Next, change a shared footer in a test copy and inspect both pages again. The intended reach of each action should be clear before a business user receives permission to make it on the live site.
References to third-party blocks must include their namespace. Record any such blocks used in the supplied templates and ask what provides them. A visual section that relies on another component needs an identifiable dependency in the handover. Avoid treating a screenshot as proof that the section will remain editable after that dependency changes.
The ACF content modelling guide covers structured content decisions in more detail. Keep this theme checklist focused on presentation ownership, shared layout and the delivered assets, rather than using it as a substitute for a full content model.
Who controls changes made in the Site Editor?
Site Editor changes to block templates and parts are saved in the database. This documented behaviour creates a practical release question: does the approved design live in theme files, saved site changes, or a deliberate combination? Record the answer for each shared section. Do not assume that copying a theme folder reproduces every editorial adjustment.
Agree a simple division of responsibility. For example, a content owner might edit page wording, a designated design owner might approve shared layout changes, and the developer might maintain the distributable theme files. Those are proposed roles to assign, not permissions that this article claims WordPress has automatically configured.
Ask for a demonstration using the actual account intended for the editor. Can that account reach the controls described in the handover? Does the editor understand whether an action changes one page or a shared template? If the answer is uncertain, adjust the training and access brief before handover rather than relying on a warning buried in technical notes.
Original template-to-editor handover exercise
Use this hypothetical exercise for a small training organisation with a course listing, course detail page and enquiry page. The original artefact is a change reach card for each requested edit. Each card records the requested outcome, controlling layer, affected pages, permitted editor and recovery evidence.
Card A: revise one course description. The desired reach is one course. Identify the content record and ask the content owner to make the change in a test copy. Inspect the listing, detail page and unrelated course. Write down whether the displayed result matches the intended reach. If a shared label also changed, locate the cause before approving the workflow.
Card B: update the footer contact text. The desired reach is every template that includes that footer. Name the shared part and list the sample URLs inspected. Record whether the approved change was saved in the editor or incorporated into the supplied theme files. The handover should say how the same approved result can be reproduced in a fresh test installation.
Card C: add an image to an enquiry section. Record the image source, meaningful alternative text, intended crop and the place where an editor replaces it. Ask the reviewer to inspect a narrow screen as well as the full desktop layout. A successful upload alone does not answer whether the image obscures text or creates an unusable reading order.
Card D: change the site-wide button treatment. Identify the relevant design setting or stylesheet and the owner allowed to approve it. Inspect a normal page, a long-content page and an empty state. Record the result separately from the course-content test so a global design change cannot be mistaken for a routine copy edit.
For every card, keep an expected result and an observed result in separate fields. Mark the outcome accepted, needs correction or needs explanation. This turns vague feedback such as “the theme is difficult” into a specific issue that a developer or editor can resolve.
What should be accepted before the theme is handed over?
Request a reproducible theme package, a dependency list, the change reach cards and a short editor walkthrough. Include an explanation of what was tested with long headings, missing optional images and realistic navigation labels. These cases expose responsibilities that a polished homepage mock-up can hide.
If replacing an existing theme, use the Avada migration discussion for the broader replacement decision. For this handover, insist on a clear account of which presentation decisions move with the files and which need saved site configuration.
The WordPress service overview provides the wider context. To prepare a focused brief, get started with the page types, shared sections and editor tasks that the finished theme must support.
By Spout Team. AI-assisted drafting by Codex using the linked primary documentation.