Kindly EditDocumentationTry the editor

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 cantata parent 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) so tokens always wins.
  • Parts and components hold no <script>, on*= or inline style. 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, contract goes 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.

About this page

Documents Kindly Edit 0.9.16. Source: THEMES.md. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.