Theme contract
Integrate a WordPress theme with built content, editable parts, design tokens, and component libraries.
Build requirement: read the native-first build standard. Use native settings first; keep exceptions in the owning element's visible Developer > Advanced CSS/Custom JavaScript fields. Contract validation and full coverage are required for new builds.
A production Kindly Edit site uses the updateable cantata parent theme plus a standardized client child theme. The
parent owns shared templates, responsive behavior, accessibility, the standard component library and the validated
design-settings system. The child owns the client's initial tokens, parts, assets and only the components it really
replaces or adds. Site functionality belongs in a plugin. How to design components is in COMPONENTS.md.
Starting a client theme#
node tools/new-theme.mjs acme-dental --name "Acme Dental" --tokens acme-tokens.json
The command copies client-child/ to acme-dental/ and makes it the site's own. The generated style.css declares
Template: cantata, so the Kindly Edit Framework must also be installed:
- It renames the theme header and text domain while keeping the
cantataparent relationship. - It puts the site name in the header and footer.
- It merges the initial tokens over the standard child settings and warns about unknown roles.
- It inherits the standard components. Files added under
components/replace a parent file with the same name or add a genuinely client-specific component.
--tokens takes a JSON object of roles, or another theme's cantata-edit.json. The script then checks that the
JSON parses and that the PHP parses (php -l, when PHP is installed; otherwise activate the theme on a Studio site).
After activation, use Kindly Edit > Theme (Theme settings, 0.9.15 and later; the older
Appearance → Kindly Design opens it) for update-safe colors, typography, widths, media references, sections and
style-guide content. AI tools use the same validated document through WordPress Abilities/MCP or wp kindly design.
The legacy starter/ remains for existing standalone builds; new client sites should use the parent/child model.
Files#
| File | Required | What it is |
|---|---|---|
style.css |
yes | Declares Template: cantata; the rest of the metadata names this client child theme. |
functions.php |
yes | Small client setup only. Shared behavior stays in the parent. |
Parent index.php, header.php, footer.php |
inherited | Print built content and editable shared parts. A child overrides one only when the client truly requires different PHP structure. |
parts/*.html |
yes | The default header and footer. The first save in the editor makes an editable copy, and the files stay the default after that. |
components/NN-slug.html |
no | The site's own sections, for "Add section". See COMPONENTS.md. |
components/NN-slug.json |
no | What a component's content is (its fields and repeated items), shown in its Content card in Simple and Developer mode. See Custom elements. |
cantata-edit.json |
yes | Everything below. |
In the HTML files, {{theme}} is the URL of the parent or child that owns that file and {{home}} the site's. {{logo}}
and {{default-image}} use the client design's media IDs (falling back to the placeholder). In components, {{img}} is also
available: the plugin's placeholder picture. All of them become root-relative, so pages keep working when a site moves from its dev address to the
real one.
cantata-edit.json#
| Key | Meaning |
|---|---|
contract |
The contract version the theme was written for: 1. Settings → Kindly Edit warns when a theme needs a newer plugin. |
tokens |
What each role is on this site: bg surface tint dark accent accent-2 accent-bg heading ink muted line on-dark on-dark-muted accent-on-dark on-accent display body radius. Printed as --cb-<role> on :root. The meaning of each role: cantata_edit_token_roles() in includes/tones.php. |
design |
Initial update-safe client settings: layout, media-library assets, AI-readable guide, per-component rules and advanced.css. Once saved, the validated WordPress option overrides these theme defaults. |
tones |
The names editors see for light, tint, dark and accent, or false to hide one. |
textColours |
Rename or hide (false) the text color choices: heading, ink, muted, accent. It can't add new ones. |
sections |
The selector for a page's sections. Default main > section. A single styling wrapper around the complete list is supported automatically and remains intact when the page is saved. |
buttons, button, button2 |
The selector for buttons (a.btn), and the full class lists of the main and second button. The plugin uses them for button styles on dark and accent tones, and when a block adds a button. |
section, head |
The wrapper ({{head}}{{block}}) and the heading row the plugin's own blocks are placed in, so they sit on the site's grid. |
containers |
Optional spacing and page-width tokens for the built-in Developer-mode Container. This customizes the feature; it does not turn it on. |
convert |
How an ordinary WordPress page is laid out when someone chooses "Build this page here": {{title}} and {{content}}. |
styles |
Closed lists of classes an editor can choose from: { match, label, options: { class: "Label" }, hint }. Editors never write CSS. |
icons |
The SVG icons offered for buttons and links, by name. |
kindNames |
From 0.5.0. Rename the picker's groups for this site's editors, by component Kind: { "stats": "Our impact in numbers" }. Kinds left out keep the plugin's names. |
transient |
What the theme's own JavaScript changes while the page runs (open menus...), reset before a save: { selector, removeClasses, setAttributes, removeAttributes, force }. |
Simple and Developer mode#
From 0.5.0 the editor has two modes. Simple, the default for everyone, edits the page in place and adds only
the theme's own components, through a + between sections. Developer mode, an administrator's switch in the
⋯ menu, keeps the full editor. A theme made for Simple mode needs a real set of components with Layouts, Tones,
Keywords and Fixed tone where it applies, and may rename the picker's groups with kindNames. Without
components, Simple mode falls back to the plugin's Basic blocks. The details are in COMPONENTS.md, under
"Simple and Developer mode".
Rules#
- Every color, font and corner comes from a
--cb-*token, so tones and future components fit the site. Put default values in:where(:root)sotokensalways wins. - Parts and components hold no
<script>,on*=or inlinestyle. The save removes them anyway. - A change that stored pages depend on (class names, part slugs) needs a migration, because pages keep the HTML they were saved with.
- When the plugin reads a new shape of this file,
contractgoes up and older themes keep working.
Native interaction source#
Themes can declare nativeBehaviors entries with match, label, a relative public assets/*.js source, and an optional symbol. Supply genuine native controls for every supported choice. Advanced displays the selected native owner and its public source read-only; registration never approves page-provided code. Read docs/NATIVE-BEHAVIORS.md.