The nucleo-canvas theme

Nucleo 0.2+Free~11 min readUpdated October 31, 2026

nucleo-canvas wraps Nucleo pages and works without the plugin too.

On this page

01Overview

nucleo-canvas is a minimal classic theme. It provides the HTML wrapper of the page: header.php, index.php, footer.php and a base CSS.

With the plugin active, the theme prints the Nucleo layouts of the areas: header, footer, single, archive, search, 404, popup and the areas before and after the content.

Without the plugin, or without a layout for the area, the theme prints a basic markup. The content of Nucleo pages stays readable because the post saves the compiled HTML.

The theme does not register menus or sidebars, and it has no theme.json file on disk. Colors and fonts come from the --nc-* CSS variables published by the plugin, and the published tokens also reach the block editor: see Tokens in the editor.

The theme updates from the server https://updates.nucleowp.dev without a license. The updater loads only in admin, in cron and from WP-CLI.

From the theme, the plugin reads only base.css, for the editor preview and for catalog-get {topic: theme}.

02Installation and requirements

Theme header

What it does: declares name, version, requirements, update host and text domain.

How to use it: install it as a WordPress theme from the zip nucleo-canvas-<version>.zip, produced by nucleo/bin/build.

Parameters: fields of style.css:

Field	Value
`Theme Name`	`Nucleo Canvas`
`Description`	`Minimal shell for the Nucleo plugin. Works without the plugin as a plain fallback.`
`Version`	`0.2.0`
`Requires Nucleo`	`0.2.0`
`Update URI`	`https://updates.nucleowp.dev/nucleo-canvas`
`Requires at least`	`6.9`
`Requires PHP`	`8.2`
`License`	`GPL-2.0-or-later`
`Text Domain`	`nucleo-canvas`
`Domain Path`	`/languages`

Permissions: installing and activating require the WordPress theme capabilities (install_themes, switch_themes).

Edition: Free.

Known limits:

Requires Nucleo is a custom header: WordPress does not enforce it. nucleo/bin/version aligns it at every release together with Version. The local updater does not read it: it uses requires_nucleo from the server response.
The theme slug must be nucleo-canvas. The updater and catalog-get {topic: theme} recognize the theme only with this slug.
The build produces two zips: nucleo-canvas-<v>.zip with the updater and nucleo-canvas-wporg-<v>.zip for WordPress.org, without inc/updates.php, Update URI and Requires Nucleo.

Theme supports

What it does: loads the translations and registers the theme supports on after_setup_theme.

How to use it: automatic on activation.

Parameters: registered supports:

Support	Arguments
`title-tag`	—
`automatic-feed-links`	—
`post-thumbnails`	—
`custom-logo`	height 80, width 240, flexible
`html5`	`search-form`, `comment-form`, `comment-list`, `gallery`, `caption`, `style`, `script`, `navigation-widgets`
`responsive-embeds`	—
`align-wide`	—
`wp-block-styles`	—
`editor-styles`	`base.css` as the editor style
`woocommerce`	—
menu `primary`	`register_nav_menus`

Permissions: none.

Edition: Free.

Known limits: the theme registers no sidebar and no theme.json file. The palette comes from the tokens published by the plugin. The primary menu appears only without a Nucleo layout for the header area: with the plugin, navigation goes through nc/menu.

03Templates

What it does: prints <head> with wp_head(), opens <body> with body_class() and wp_body_open(). It adds the "Skip to content" link to #main. Then it prints the layout of the header area.

How to use it: automatic, with get_header().

Parameters: none.

Permissions: none.

Edition: Free.

Known limits: without a header layout, the theme prints <header class="site-header"> with a link to the home page and the site name. If the area is turned off, that is a document with layout none or the page choice "None" for the header, the theme prints nothing.

Content

What it does: wraps the content and chooses what to print according to the request.

How to use it: automatic. index.php applies to all requests. With WooCommerce active, product, shop and product archives go through woocommerce.php: with a Nucleo layout for the product, single, product-archive or archive area it uses index.php, otherwise it prints woocommerce_content() inside <main id="main">.

Parameters: order of the choices:

Request	What it prints
Every request	`before-content` area at the start, `after-content` area at the end.
Search	Layout of the `search` area; if missing, layout of the `archive` area; if this is missing too, the loop.
404	Layout of the `notfound` area; if missing, the loop.
Archive (`is_archive()`) and posts page (`is_home()`)	Layout of the `product-archive` area, then of the `archive` area; if both are missing, the loop. `product-archive` applies only with WooCommerce active, to the shop archive and to product categories and tags.
Single with a `product` or `single` layout	The `product` layout (only with WooCommerce active and on a product), otherwise the `single` layout, instead of each post of the loop.
Nucleo document	`the_content()`, without the theme title.
Other	`<article>` with title (`<h1>` on single, `<h2>` with link in lists), content or excerpt, then `the_posts_pagination()`.
No results	`Nothing found.`

The container is <div id="main"> when the page already has a <main>: the document root has settings.tag main, or a layout of an area contains one. In other cases it is <main id="main">, also for a Nucleo document with a section root.

Permissions: none.

Edition: Free.

Known limits:

The plugin applies before-content and after-content only to single content and archives. On search and 404 pages, the calls to the areas print nothing.
On search the fallback to the archive area never prints anything. The plugin applies archive only to the term_archive, post_type_archive, author_archive and blog types, not to search. Without a search layout the theme uses the loop.

What it does: prints the layout of the footer area, then the layout of the popup area, then wp_footer().

How to use it: automatic, with get_footer().

Parameters: none.

Permissions: none.

Edition: Free.

Pro

The popup area prints something only with Pro: without Pro the plugin skips it.

Known limits: without a footer layout, the theme prints <footer class="site-footer"> with ©, the current year and the site name. If the document or the page turns the area off, the theme prints nothing.

04Working with and without the plugin

Recognizing Nucleo documents

What it does: nucleo_canvas_is_document() tells whether the current request is a single Nucleo document. With the plugin active, it relies on the plugin's check. Without the plugin it uses nucleo_canvas_has_document_meta(), which checks the _nucleo_doc meta of the post.

How to use it: global PHP functions. nucleo_canvas_is_document(): bool, nucleo_canvas_has_document_meta(int $postId): bool.

Parameters:

Name	Type	Allowed values	Default	Notes
`$postId`	int	ID of a post	—	Only for `nucleo_canvas_has_document_meta()`.

Permissions: none.

Edition: Free.

Known limits: outside is_singular() the function always returns false.

Printing the areas

What it does: nucleo_canvas_area(string $area): bool prints the HTML of the Nucleo layout of the area for the current request. It returns false if it prints nothing: the theme then uses the basic markup.

How to use it: global PHP function. Example: if (!nucleo_canvas_area('header')) { /* basic markup */ }.

Parameters:

Name	Type	Allowed values	Default	Notes
`$area`	string	`header`, `footer`, `before-content`, `after-content`, `product`, `product-archive`, `single`, `archive`, `search`, `notfound`, `popup`	—	Values accepted by the plugin. Another value returns `false`. `product` and `product-archive` print only with WooCommerce active.

Permissions: none.

Edition: Free.

Known limits:

Without the plugin it always returns false.
The choice of the layout by area and conditions belongs to the plugin: see Compiler and runtime.
The theme calls the product and product-archive areas in the content template: see the table in Content.

Warning

The theme prints the HTML without escaping. The HTML comes from the plugin renderers, already sanitized.

Fallback without the plugin

What it does: without the plugin the theme works on its own. Header and footer use the basic markup. Nucleo pages show the saved content, which is the compiled HTML with its own <h1> and its own <main>. Classic pages show the theme title.

How to use it: automatic when the plugin is deactivated.

Parameters: none.

Permissions: none.

Edition: Free.

Known limits: without the plugin there are no layouts, published tokens or popups. base.css uses the fallback values.

05Styles and design tokens

Base CSS

What it does: loads base.css on all frontend pages, with handle nucleo-canvas-base. The file sets box-sizing, typography, links, visible focus, fluid images and the .screen-reader-text class. It gives width and padding only to the theme markup (main#main>article, .site-header, .site-footer).

How to use it: automatic, on wp_enqueue_scripts.

Parameters: CSS variables read, with the fallback values:

Variable	Fallback	Use
`--nc-font-body`	`system-ui, sans-serif`	text
`--nc-font-heading`	`inherit`	headings
`--nc-text-base`	`1rem`	text
`--nc-text-sm`	`.875rem`	basic footer
`--nc-text-xl`	`1.25rem`	`h3`
`--nc-text-3xl`	`1.875rem`	`h2`
`--nc-text-5xl`	`2.5rem`	`h1`
`--nc-color-text`	`#1a1a1a`	text
`--nc-color-background`	`#fff`	background
`--nc-color-primary`	`#2563eb`	links, focus outline
`--nc-color-muted`	`#4a4a4a`	basic footer
`--nc-container-md`	`72ch`	width of the theme markup
`--nc-space-4`	`1rem`	padding of the theme markup

Permissions: none.

Edition: Free.

Known limits:

The style version follows the Version of the theme: each release changes the file's URL, so the browser does not reuse the previous one.
The variables have a value only when the plugin publishes the tokens. See Design tokens.

Tokens in the editor

What it does: the theme has no theme.json file on disk. When the plugin publishes the tokens, it saves their theme.json and the theme merges it into the WordPress theme data with the wp_theme_json_data_theme filter: the palette and fonts of the tokens thus reach the block editor. Without the plugin, or without published tokens, the filter changes nothing. The Nucleo editor preview loads the base.css of the active theme and the CSS of the tokens published by the plugin.

How to use it: automatic. In the block editor for palette and fonts; in the Nucleo editor preview (POST /nucleo/v1/preview) for the CSS.

Parameters: none.

Permissions: those of the Nucleo editor for the preview. See Backend.

Edition: Free.

Known limits: the preview loads the base.css of any active theme that has one, not only of nucleo-canvas. Without the plugin the filter does nothing.

Theme description for agents

What it does: catalog-get {topic: theme} returns the rules of the page wrapper and, in data.css, the content of base.css.

How to use it: ability nucleo/catalog-get with {"topic": "theme"}. See Read abilities.

Parameters: none besides topic.

Permissions: current_user_can('edit_posts'). OAuth scope nucleo:read.

Edition: Free.

Known limits: data.css is empty if the active theme does not have the nucleo-canvas slug or if base.css is not readable.

06Updates

Theme updater

What it does: responds to the WordPress filter update_themes_updates.nucleowp.dev. It asks the server whether a new version exists and proposes it on the updates screen.

How to use it: automatic. WordPress applies the filter during the theme update check. The theme loads inc/updates.php only if is_admin(), wp_doing_cron() or WP-CLI.

Parameters: request POST <base>/theme/check, with Content-Type: application/json and a 10-second timeout:

Field sent	Content
`version`	Installed version of the theme.
`site`	`home_url()`.
`nucleo`	`NUCLEO_VERSION`, or `null` without the plugin.

Fields read from the response: version, package, requires, requires_php, requires_nucleo.

Permissions: none from the theme. Installing the update follows the WordPress capabilities (update_themes).

Edition: Free. The request does not contain a license key.

Known limits:

It acts only for the slug nucleo-canvas.
It ignores the response if the HTTP status is not 200, if version does not have the form X.Y.Z or if package does not start with https://.
With the plugin installed, it ignores a version whose requires_nucleo is higher than NUCLEO_VERSION. Without the plugin it applies no constraints.
The frontend does not contact the server.
The name of the filter depends on the host of Update URI: changing the host requires a theme version that declares it.

Filter `nucleo_canvas/updates_api`

What it does: changes the base address of the updates server.

How to use it: add_filter('nucleo_canvas/updates_api', fn () => 'https://esempio.test');

Parameters:

Name	Type	Allowed values	Default	Notes
filtered value	string	URL without a final `/`	`https://updates.nucleowp.dev` (constant `NUCLEO_CANVAS_UPDATES_API`)	An empty or non-string value falls back to the default.

Permissions: none.

Edition: Free.

Known limits: the filter changes only the address of the request. The WordPress filter name stays tied to the host of the constant. The filter must be added before the check, in a context where the updater is loaded.

07Translations

Domain `nucleo-canvas`

What it does: loads the translations from languages/ on after_setup_theme.

How to use it: automatic according to the site language.

Parameters: included languages:

File	Strings
`languages/it_IT.po`, `languages/it_IT.mo`	`Skip to content` → `Vai al contenuto`; `Nothing found.` → `Nessun risultato.`

Permissions: none.

Edition: Free.

Known limits: the theme does not include a .pot file.

08Summary of public names

Name	Type
`nucleo_canvas_is_document()`	function
`nucleo_canvas_has_document_meta()`	function
`nucleo_canvas_area()`	function
`nucleo_canvas_update()`	function, callback of the update filter
`NUCLEO_CANVAS_UPDATES_API`	constant
`nucleo_canvas/updates_api`	filter
`nucleo-canvas-base`	style handle

Was this page helpful?

The nucleo-canvas theme

01Overview

02Installation and requirements

Theme header

Theme supports

03Templates

Header

Content

Footer

04Working with and without the plugin

Recognizing Nucleo documents

Printing the areas

Fallback without the plugin

05Styles and design tokens

Base CSS

Tokens in the editor

Theme description for agents

06Updates

Theme updater

Filter nucleo_canvas/updates_api

07Translations

Domain nucleo-canvas

08Summary of public names

Filter `nucleo_canvas/updates_api`

Domain `nucleo-canvas`