Theme Accessibility and Releasing

Block themes start with more accessibility built in than classic themes, because core blocks produce the markup:

The theme still decides the colours, link underlines, focus visibility, heading levels and whether every template has a <main>.

Every theme in the Theme Directory must meet two accessibility items: a skip link where there is something to skip (menus, sidebars), and visible keyboard focus on links, menus, form fields and buttons, with every control reachable by keyboard at every screen width. Themes that carry the accessibility-ready tag must meet the full list of eighteen items (next section). The Lumen Press theme targets the full list.

A theme author asks for an accessibility review by adding accessibility-ready to the Tags header before uploading a new theme. Members of the Accessibility team audit it as part of the review, and the theme cannot go live with the tag until it passes; a new theme that fails may still be approved without the tag. For a theme already live, the author requests the review through a form on the handbook page and adds the tag only after approval: adding it unreviewed can lead to suspension. Updates to tagged themes enter an accessibility queue and may be re-reviewed at any time.

Since 2026-06-30 an accessibility-ready theme must ship accessibility.txt in its root, in a fixed format: a statement, quick facts about any audit, how the theme is tested, the screen reader text class, features, and where to ask for help and report problems. The lumen file:

Source: WP Accessibility: Accessibility.txt files

The optional audit date, standard, auditor and conformance report lines are added once a formal audit exists.

Automated tools find only part of the problems (missing names, contrast, landmarks), so they complement keyboard and screen reader testing, but they are cheap enough to run on every change. The following check opens a set of lumen pages in headless Chrome, runs axe-core’s WCAG 2.2 A/AA and best-practice rules, then presses Tab once and verifies that the first focused element is the skip link pointing at <main>:

Source: Playwright: Accessibility testing

The script runs as an ES module (check-a11y.mjs). The test site is the standard local stack from Local Development Environments, with lumen mounted into wp-content/themes/, a published post "Hello" containing a link in its text, and pretty permalinks. PW_HOST_RULES lets the browser reach lumenpress.test on the port the stack publishes (8080 here) without editing the hosts file; PW_CHANNEL=chrome uses an installed Chrome instead of downloading Playwright’s browser (npx playwright install chromium is the alternative):

Source: axe-core-npm: @axe-core/playwright

Source: axe-core: API documentation

To see the check fail, the same templates were copied with the content group’s tagName changed from main to the default div, links set to textDecoration: none and the post titles left as the only headings. The result:

Source: Deque University: landmark-one-main rule

Three lessons come out of these runs. The missing skip link was caught only by the Tab check, not by axe, since bypass passes whenever any landmark or heading exists. The landmark and heading problems are best-practice rules, so a run limited to the wcag2* tags reports zero violations for a theme without <main>. And the order matters: a first version that ran axe after pressing Tab reported a target-size failure, because the focused skip link sits on top of the site title link at the top left. Run axe on the untouched page, then test keyboard behaviour. The same checks fit into an end-to-end suite, as described in Accessibility Checks in E2E Tests.

Manual checks no tool replaces: tab through every template at desktop and mobile widths (overlay menu included), zoom to 200% and 400%, read pages with VoiceOver or NVDA, and repeat for each style variation, using the Theme Unit Test data (WordPress/theme-test-data) that reviewers also use.

Every theme uploaded to wordpress.org/themes is reviewed by volunteers of the Themes Team against the "Required" list in their handbook. A theme with three or more distinct problems may be closed and must be resubmitted after fixing them. The requirements, grouped and summarised:

The process: upload, new-theme queue, a reviewer, findings on a Trac ticket, fixes uploaded as new versions, approval, a final check by a key reviewer, then live. A ticket idle on the author’s side for seven days may be closed; there are no promised timeframes.

readme.txt uses the same format as plugin readmes but different rules. The lumen readme keeps the header, short description and == Description == shown in Themes Overview; version 0.2.0 continues it with (plus a one-question FAQ stating that the theme collects no data):

Source: Themes Team Handbook: Required

The rules the review applies: Contributors holds one WordPress.org username; Requires at least, Tested up to, Requires PHP, License and License URI are present; the short description after the header is at most 150 characters; each upgrade notice is at most 300 characters; the sections cover the description, FAQ, changelog, upgrade notice and resources; and any data collection is documented. Unlike plugin readmes, theme readmes have no Stable tag: the version comes from style.css. Theme Check does not verify all of these, so Lumen Press keeps a small check in its release script:

Source: Theme Handbook: Required Theme Files

Run on lumen and on a copy with two contributors, no Requires PHP, a 169-character description and a version bump missing from the changelog:

Source: Themes Team Handbook: Required

screenshot.png sits in the theme root. The review accepts any 4:3 image up to 1200 × 900 px; 1200 × 900 is preferred for high-density displays, and older tutorials quoting 880 × 660 or 600 × 450 describe earlier limits. The image shows the theme as it looks with its default settings, not a marketing banner, and must itself be GPL-compatible: a screenshot containing stock photos needs those photos' licences listed under Resources. PNG is the usual choice; core also finds .jpg, .jpeg, .gif, .webp and .avif.

Licensing applies to the whole package: PHP, JavaScript, CSS, fonts, icons and images. A bundled font under the SIL Open Font License or an icon set under MIT is fine, because both are GPL-compatible, but each needs its name, copyright holder, licence and source URL in readme.txt (or a single resources file). Public-domain (CC0) images need only the source. Premium versions of a theme sold elsewhere must also be GPL-compatible, and the selling site must say so. Credits are limited to one footer link to the theme or author page, plus one to WordPress.org.

The Theme Check plugin runs the automated checks the directory runs on every upload; a theme that fails them is rejected before a human sees it. It adds Appearance > Theme Check to the admin and (version 20260901 included) a WP-CLI command. On the Lumen Press test site:

Source: GitHub: WordPress/theme-check

lumen passes: the output is two INFO lines (the accessibility-ready review notice, and a text-domain note with an empty domain, expected while the theme has no PHP strings) and the exit code is 0. A copy named "Lumen WordPress Theme", with no Requires PHP, a 1600 × 900 screenshot and a functions.php that registers lp_book and a shortcode produces REQUIRED results and exit code 1, which is what a release script tests for:

Source: Themes Team Handbook: Theme Check Plugin

The same broken copy also loaded a script from a CDN, lacked Tested up to in readme.txt, had "WordPress" in its name and contained a .DS_Store file, and the WP-CLI run reported none of these. Passing Theme Check is necessary, not sufficient: the human review checks the rest, and the readme check above and a clean packaging step cover some of it. Accessibility is not checked by Theme Check at all beyond the informational line.

The release zip contains one folder named after the slug, with sources but without development files. When the theme lives in Git, git archive with export-ignore rules in .gitattributes is the cleanest way; without Git, zip with exclusions:

Source: Theme Handbook: Submitting Your Theme to WordPress.org

The listing then holds only the theme files, without hidden files, node_modules or package.json. A theme with a build step (Sass, JavaScript bundled with @wordpress/scripts) ships both the built files and their sources, as the review requires, but not node_modules. Before uploading: test with the Theme Unit Test data and WP_DEBUG on, run Theme Check, run the accessibility checks, test against the next WordPress beta (the WordPress Beta Tester plugin or wp core update --version=nightly on a test site), and check that Version in style.css matches the newest changelog entry. The upload form is at wordpress.org/themes/upload and needs a WordPress.org account; the zip goes into the new-theme queue described above.

Lumen Press keeps lumen private; the same checks apply, and the Update URI header (see Themes Overview) stops WordPress.org offering a same-slug theme as an "update".

WordPress compares the Version header of an installed theme with the version the directory reports and offers an update when the directory’s is higher (version_compare() semantics). Versions are X.Y or X.Y.Z, each higher than the last: patch for fixes, minor for new patterns or templates, major for changes to existing layouts.

A live directory theme is updated in one of two ways:

Source: Theme Handbook: Updating Your Theme

Subversion is a release channel, not a development repository: a committed version cannot be changed afterwards, and a mistake is fixed only by releasing a higher version. Development stays in Git; the export steps are described in Create Block Theme and Version Control. Updates to an accessibility-ready theme go through the accessibility queue as well.

On the site side, theme updates replace the whole folder, so local edits to theme files are lost: customisations belong in the Site Editor (stored in the database), a child theme (Child Themes) or a plugin. Templates and styles a user changed in the Site Editor keep winning over the updated files until reset. Since 5.5 administrators can enable automatic updates per theme on Appearance > Themes; the policies and filters are on Updates and Auto-Updates.

Security notes: the review’s code rules double as a security checklist for any theme (escape output, sanitise input, check capabilities on admin pages, no remote code or eval). A theme sold or shared outside WordPress.org gets no review, so the same Theme Check and manual checks are worth running on it before installing, as described in Choosing and Managing Plugins and Themes and Security Hardening.