Kindly EditDocumentationTry the editor

Native-first build standard

The authoring contract for pages, components, imports, and connected builders.

This is the default contract for every new Kindly Edit site and every component added to one. Read it before generating markup, CSS, JavaScript or a theme. It applies to humans, Claude and other connected coding tools.

Server import/save normalization preserves the priority of existing inline shorthand declarations when a conditional rule competes through a related longhand or logical alias. For example, inline margin:0 auto stays inline beside a custom-media margin-top, and inline font stays inline beside conditional line-height. These faithful exceptions remain visible in Advanced CSS. The PHP normalizer and browser CSS router share the same conservative property-family rules; they do not invent !important priority.

Use the native model first#

Use the component catalog, semantic text, links/buttons, pictures/icons, containers, rows/grids, tabs, accordions, tables, shared parts and registered live sources. Make nested and repeated items selectable through their proper owner. Use the existing content, layout, appearance, state, device, design-token and native application settings for everything those settings represent.

Do not add a block the build contract marks offered: false (for now: progress, social, price-list, animated-headline, toc, text-path, icon-box, price-table, flip-box, taxonomy-filter). They are not offered for adding yet; one already on a page keeps working and may be edited in place.

Do not recreate an existing control through a CSS hack or a separate JavaScript widget. The setting must describe the stored value, change what visitors see, survive Save draft, reload, Publish, duplication and shared-part editing, and reset predictably.

Design defaults belong to named, reusable theme/component rules and registered design tokens. An element's Advanced panel must reveal the theme rules affecting it, including their source, media and state. Reusable layout-dependent defaults must continue to follow Layout choices.

Put exceptions on their owning element#

Presentation that has no native setting belongs in the selected element's Developer > Advanced > CSS section. Use the scoped element-CSS contract in ELEMENT-CSS.md. Store exceptions with the element, including its responsive, state, pseudo-element and descendant rules. A copied element owns its copy. Do not introduce opaque element-id stylesheets, shared hash classes, injected style tags or private source overrides for individual items.

Behavior that the native model cannot represent belongs in Developer > Advanced > Custom JavaScript on its explicit element, page or shared-part owner. Use the element-JavaScript contract and lifecycle API. Keep source visible, editable and removable. Only users with the trusted-code capability may introduce or change code. Code must not run over the editing interface merely because someone selected or inspected an element.

Server presentation code that native settings or registered providers cannot represent belongs in Developer > Advanced > PHP. Read ELEMENT-PHP.md. Source lives in protected immutable resources; the element stores only a signed reference. Apply requires native server file-code permissions, not just page editing or browser-script permission. Ordinary editing, REST, feeds and plain previews never execute it. Native application PHP remains with its registered provider, shown read-only with its native management link.

Keep operational values in their native systems. Form fields, confirmation wording, prices, registration availability, membership rules, private downloads, consent and payment state retain their registered application owners. Visual exceptions may style their registered container, but cannot replace their validation or authorization. Identify the native editor for each generated item.

Normalize and validate automatically#

The build/import/save pipeline must route supported declarations to their native storage and unsupported presentation to scoped element CSS. Custom behavior must use the explicit Custom JavaScript field and lifecycle. Reject out-of-contract or hidden implementations with an actionable error before writing. Never silently discard code, publish a partial conversion, or report an unsupported feature as successful.

Raw script tags, inline event handlers, unscoped injected stylesheets, disconnected settings, anonymous per-element CSS files and behavior that bypasses a native component are not valid new-build output. A registered shared design stylesheet is allowed; a hidden per-instance override is not. Validation must identify the affected element and the correct native setting or Advanced exception owner.

Historical imports need an explicit, reversible migration with source coverage and parity evidence. Preserve unsupported historical data until a verified conversion exists. Do not weaken the validator globally to get one imported page through it.

What the save pipeline does (native-first contract)#

  • Inline declarations that a native control owns stay inline, including --grid-columns (written by the native grid column control). Other inline declarations move into the element's base Advanced CSS rule, replacing the same property there instead of adding a second rule.
  • Faithful inline exceptions: a declaration stays inline, where Developer > Advanced > CSS shows and edits it, when moving it would change what wins: an !important inline declaration, or a property the element's own CSS also sets under a state, media query or other condition. Kindly never adds !important to imitate inline priority. Element CSS is scoped at specificity (1,1,0); a theme rule with two ids, or an id plus more classes, can still beat a moved declaration that inline used to beat. Check such themes before importing.
  • Legacy markup outside the supported model is refused on save, even when the stored page already has it: Kindly's sanitizer could not keep it (it would remove the tag and keep only the words), so the save stops before any write and names the element (cantata_edit_contract_legacy_element when it was already on the page, cantata_edit_contract_element when new). Convert it to a native element first. Script/style tags, handlers, srcdoc, executable URLs, embedded documents (object, embed), SVG animation and foreignObject, and custom elements are refused in every case. Pages that are not built are not converted or checked. CLI checks and new builds are strict (wp kindly contract <file>).
  • Inert bdi and SVG structure (defs, gradients, stop, clipPath, mask, pattern, symbol, use, text, title, desc) are part of the model. <use> may only point to #id in the same document.
  • A <script>, <style>, <noscript> or <template> written inside text or an attribute is refused rather than silently cut out. Ordinary text values are kept as they are.
  • Pages not yet built with Kindly that contain a code block cannot be converted until the block is removed in the WordPress editor; the page is left unchanged.

Deployment guard#

The first contract save of any element marks it data-ke-model="1", which switches a theme's legacy compatibility CSS and JS off for that element. Before activating a plugin build with the contract on an existing site, complete and verify the content migration, then run wp kindly contract --audit: it lists every built record and saved part with unmarked elements (content and drafts) and exits 1 while any remain. Keep authoring.contract at 0 for a site until that check is clean, or accept the listed records explicitly.

Verify the finished result#

Track every page, shared part, component, nested item and generated-content owner. Test real setting changes, resets, Undo, independent duplicates and draft/publish/reload persistence in native WordPress. Compare the rendered design across the breakpoints actually used, including custom media contexts and pseudo-elements. Distinguish static source checks, mocked UI, native PHP, actual browser/HTTP and external-service evidence.

Keep a machine-readable coverage report. A screenshot or a sampled page does not prove full-site coverage. Preserve private preimages and exact rollback ownership for production changes. Publish source, implementation notes and verified limitations. Never call unfinished migrations or unexecuted checks complete.

Instructions for connected Claude builds#

Read AGENTS.md or CLAUDE.md, this file, COMPONENTS.md, THEMES.md, the active theme's paired instructions and its cantata-edit.json before building. Inspect the live component/settings contract instead of inventing controls. Run the contract validator and required checks, fix every rejection, and produce the coverage report before publishing. Include this contract and links to the CSS/JavaScript references in every generated site's Markdown instructions so the next connected session follows the same standard.

Platform support for code fields#

This authoring standard requires WordPress 7.1 or newer. Older HTML APIs can change quote and entity characters in stored code; the supported baseline preserves exact source values. Keep PHP source behind the existing server code-editing permissions. Advanced contains separate PHP, JavaScript and CSS owners. Cantata Site Feedback must not impose submission limits or hidden bot traps. That rule is specific to the feedback plugin. Authorization, validation and safe file handling remain required.

Connected builders use get-build-contract, get-element-code/set-element-code for CSS and browser behavior, and get-element-php/set-element-php for intentional server code. PHP writes require intent server-php, the current owner revision and element index. The server creates the protected resource and saves a draft atomically; it never publishes. Shared parts use the optional part name with the same permissions and native save pipeline.

Native interaction source#

Reusable theme interactions use genuine native settings and declare their public JavaScript owner through nativeBehaviors. Installed applications register their own public plugin JavaScript through the trusted PHP cantata_edit_native_application_behaviors filter instead of moving business behavior into a theme or page snippet. Advanced shows the installed source read-only. Read NATIVE-BEHAVIORS.md. Per-element exceptions continue to require explicit Custom JavaScript approval; native registration never grants arbitrary code authority. Verify that normal editors can duplicate native items.

Native application repeaters must use the authorized scoped-style integration in SCOPED-STYLES.md when inline generated styles would become list, table or sibling nodes. Source registration and markers alone are not granular ownership or behavior evidence. Bind operational values after presentation rendering and verify required structure with the actual native application.

About this page

Documents Kindly Edit 0.9.16. Source: docs/BUILD-STANDARD.md. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.