Themes Overview

A theme is a folder under wp-content/themes/<slug>/. The folder name is the theme’s slug (also called its stylesheet name); it is what WP-CLI, the database and the code use, while the human-readable name comes from the Theme Name header in style.css. WordPress represents each installed theme as a WP_Theme object (wp_get_theme( 'lumen' )) and keeps the active one in two options:

The division of labour is the one the Theme Handbook states: a theme handles presentation, plugins handle behaviour. Anything the site would lose when the owner switches to another theme (a custom post type, a shortcode inside posts, an SEO field) does not belong in a theme. That rule is described in detail in Plugin territory below.

Site owners choose a theme and, with a block theme, change its design in the Site Editor; administrators install, update and remove themes (Choosing and Managing Plugins and Themes); theme developers write the files described here and in the rest of the Block Themes and Classic Themes groups.

WordPress supports two theme systems side by side, and a common mix of the two.

A block theme is built entirely from blocks. Its templates contain the same markup the editor saves, so the site owner can open any template in the Site Editor, change it and save the change to the database. Every bundled default theme since Twenty Twenty-Two (5.9) is a block theme. This is the kind the Theme Handbook focuses on and the kind Lumen Press uses for its site (lumen, with lumen-child described in Child Themes).

A classic theme builds its pages with PHP templates that WordPress chooses through the template hierarchy. It is still fully supported, and many commercial themes and older sites use one. Its design surface for the owner is the Customizer, the Menus screen and the Widgets screen. Lumen Press keeps lumen-classic only to teach classic themes and the migration path.

A hybrid theme is a classic theme that adopts some block features: a theme.json file, block template parts rendered with block_template_part(), block patterns in patterns/, or add_theme_support( 'block-template-parts' ) (6.1) so that the owner can edit those parts. The Theme Handbook stresses that hybrid themes are still classic themes: there is no Site Editor and the PHP template hierarchy still renders pages. The road from classic through hybrid to block is described in Hybrid Themes and Migration to Block Themes.

The decision is made by one file. WP_Theme::is_block_theme() (5.9) returns true when the theme folder contains a readable templates/index.html, or the deprecated block-templates/index.html used by early Gutenberg block themes. Nothing else counts: a theme.json file, a parts/ folder or a Tags: full-site-editing header does not make a theme a block theme. For a child theme, the file is looked up in the child first and then in the parent, so a child of a block theme is a block theme even without its own templates/ folder.

Being detected as a block theme switches on a series of behaviours in core:

The theme is also checked when it is read: WP_Theme stores an error, shown under "Broken Themes" at the bottom of Appearance > Themes, when the folder cannot be used.

Activation adds a second check: switch_theme() calls validate_theme_requirements() (5.5), which compares the Requires at least and Requires PHP headers with the running WordPress and PHP and refuses the switch with theme_wp_incompatible, theme_php_incompatible or theme_wp_php_incompatible. Since 6.9 the validate_theme_requirements filter lets an administrator add further checks. Until 5.8 these values could also come from readme.txt; now only style.css is read.

The files and folders a theme can contain, with the page that covers each one:

style.css must start with a comment block of Name: value lines. WordPress reads the first 8 KB of the file with get_file_data(); only Theme Name is needed for the theme to appear in the admin, and the rest are required by the Theme Directory or used by specific features.

WP_Theme also recognizes a legacy Status header. Other headers are allowed (marketplaces add their own) but WordPress ignores them. The values are read with wp_get_theme()->get( 'Version' ), and the translated, escaped versions with wp_get_theme()->display( 'Name' ).

Since a block theme rarely needs hand-written CSS (its styles live in theme.json), its style.css is often only the header. A classic theme usually keeps its main CSS there, and must enqueue the file rather than link it from a template (see the lumen-classic example below).

readme.txt is not read by WordPress at runtime. The Theme Directory requires it, and it is where the theme documents for users what it does, its changelog, the copyright and licence of every bundled resource (fonts, images, icons) and any user data it collects. The format mirrors plugin readmes: a header with the name and the Contributors, Requires at least, Tested up to, Requires PHP, License and License URI fields, a short description of at most 150 characters, then sections such as == Description ==, == Frequently Asked Questions ==, == Changelog ==, == Upgrade Notice == and == Copyright == or == Resources ==.

screenshot.png (or .jpg, .jpeg, .gif, .webp, .avif) in the theme root is the preview in Appearance > Themes and on the directory page. The recommended size is 1200 × 900 pixels; the Theme Directory requires a 4:3 ratio, no larger than 1200 × 900, and a picture of the theme itself rather than an advertisement. A theme without one shows a blank card. wp_get_theme()->get_screenshot() returns its URL.

The smallest useful block theme has four files: the header in style.css, theme.json, templates/index.html and readme.txt. WordPress would accept the theme with style.css and templates/index.html alone, but without theme.json the editor offers no theme palette or layout widths, and the Theme Directory requires both theme.json and readme.txt for block themes.

Source: Theme Handbook: Theme Structure

Source: Theme Handbook: Main Stylesheet (style.css)

Requires at least: 6.9 matches the lumen-catalog plugin the theme presents; theme.json version 3 alone would allow 6.6.

Source: Theme Handbook: Global Settings and Styles

The $schema line gives editors autocompletion and validation; version must be 3 to get the current behaviour. Each palette entry becomes a CSS custom property (--wp--preset--color--lumen-red) and a colour choice in the editor. The full set of settings and styles is in theme.json Settings and theme.json Styles.

Source: Theme Handbook: Templates

templates/index.html is a Query Loop that inherits the main query ("inherit":true), so the same file renders the blog, archives and search results until more specific templates are added. A real theme moves the header into parts/header.html and adds single.html, page.html and an archive for lp_book; those steps are on Templates and Template Parts. Hand-written markup must be valid serialized block markup: an unclosed <!-- /wp:group --> or HTML that does not match what the block saves shows as an invalid block in the editor.

Source: Themes Team Handbook: Required

The theme has no functions.php: block themes get their default theme supports from core, and nothing else is needed yet. The catalogue itself (the lp_book post type, its taxonomies and meta) is registered by the lumen-catalog plugin, never by the theme.

The classic counterpart needs style.css and index.php. A functions.php declares theme supports and enqueues the stylesheet, which a block theme would get from theme.json and core.

Source: Theme Handbook: Template Files

Source: Theme Handbook: Main Stylesheet (style.css), classic themes

Source: Theme Handbook: Including Assets

Source: Theme Handbook: The Loop

The PHP template does by hand what the block template’s Query Loop does: it runs The Loop over the main query and prints the title and excerpt. wp_head(), wp_body_open() and wp_footer() are mandatory hooks; without them plugins, the admin bar and enqueued assets (including the theme’s own stylesheet) never reach the page. The title-tag support lets WordPress print the <title> element. Template tags, The Loop and the rest of the classic file set are covered in Classic Theme Anatomy and The Loop.

The Compose file below starts MariaDB and a WP-CLI container, installs WordPress 7.1.3 and copies both theme folders into wp-content/themes/. The standard local stacks (wp-env, Compose with a web server, Playground) are described in Local Development Environments; this one needs no web server because WP-CLI’s wp server serves the front end when it is needed. The passwords are placeholders for a local machine.

Source: Docker Hub: wordpress official image

Source: WP-CLI Commands: wp theme list

The WordPress 7.1.3 package ships three default themes, and a fresh install activates Twenty Twenty-Five. The name column is the slug (the folder name), title the Theme Name header.

Each annual default theme is named after the year it was planned for and is maintained by the core team. The WP_DEFAULT_THEME constant (default twentytwentyfive in 7.1) names the theme activated at install time and used as a fallback when the active theme disappears; it can be overridden in wp-config.php.

Older default themes (Twenty Twenty-One and earlier) are classic themes, still installable from the Theme Directory. Default themes update like any directory theme, so a site customizes them through a child theme, not in place.

"Plugin territory" is the Themes Team’s name for functionality that must not live in a theme. The test is simple: if switching themes would make content disappear or break, the feature belongs to a plugin. The review requirements for the Theme Directory list, among others:

For Lumen Press this means the lp_book post type, the lp_genre and lp_series taxonomies, the book meta, the lumen/v1 REST routes and the lumen/book-card, lumen/latest-books and lumen/wishlist blocks all live in the lumen-catalog plugin, while the lumen theme only provides templates (such as archive-lp_book.html), patterns and styles that present them. The rule applies to private themes too, even though only directory themes are reviewed: it keeps the content independent of the design.

Other requirements that come with the same review and are good practice for any theme:

The full review list and the accessibility requirements are covered in Theme Accessibility and Releasing.

Security notes: a theme’s PHP runs with the full privileges of WordPress, exactly like a plugin, so a theme from an untrusted source (in particular a "nulled" commercial theme) is a common way in for malware; block themes reduce the amount of PHP but functions.php and patterns/*.php still run. Install themes only from the Theme Directory or known vendors, delete themes that are not in use (an inactive theme’s PHP files can still be requested directly), and disable the theme file editor with DISALLOW_FILE_EDIT as described in Security Hardening.