Kindly EditDocumentationTry the editor

Component authoring

Build editable sections with metadata, layouts, tones, tokens, and clear repeated-item ownership.

Every site gets its own components. One site's hero can look nothing like another's. What they share is how they talk to the plugin: colors by role, dummy content, and layouts and tones the editor can switch. This is the brief for whoever builds them, person or AI.

The design bar. A site's components should look like that site: its type, its shapes, its details (a distinctive star glyph, a framed photo, a badge). They should not look like a template with the colors swapped. If a component could sit on any site unchanged, it isn't finished. Anything that reads as a generic mockup gets rejected. The plugin's own blocks/ are a fallback, not a model.

What a component is#

One file in the theme, components/NN-slug.html, holding one <section>. The number orders the "Add section" picker. It arrives on the page with dummy content, and the editor fills it in by clicking, the same way as everything else on the site.


<section class="c-hero"><div class="wrap">
  <div class="c-hero-body">
    <p class="c-eyebrow">A short label</p>
    <h1>A headline that says what you do in a few words</h1>
    <p>One or two sentences that add to the headline and tell a visitor why they should keep reading.</p>
    <p class="c-actions"><a class="btn btn-main" href="/">Main action</a><a class="btn btn-second" href="/">Second action</a></p>
  </div>
  <figure class="c-hero-photo"><img src="{{img}}" alt="" width="1500" height="1200"></figure>
</div></section>

Header fields#

Field Required Meaning
Name yes What the picker calls it: "Hero", "Tabs", "Photo and words".
Kind yes One of pagetop, hero, text, media, columns, cards, tabs, accordion, quote, cta, stats, people, events, timeline, gallery, documents, form, other. It groups the picker, and it tells the AI what already exists.
Description yes One sentence saying what it's for, in plain words.
Layouts no key=Label pairs separated by |. The first one is the default and adds no class. Each other one adds layout-<key> to the section.
Tones no Which of light, tint, dark, accent suit it. all is the default; none means it has one fixed look.
Fixed tone no Layouts that always wear one tone, whatever is chosen: band=dark, cover=dark. The editor then shows only that tone, chosen ("Always … in this layout"), and drops any tone class. cover is always dark without saying so.
Keywords no Extra words people might search the picker for, comma-separated: faq, questions, answers.
Tile no The short name on the visual picker tile when Name is too specific. For example, several photo-and-words components can all use Photo.
Tile-image no A theme-relative image for the tile, such as assets/img/hero-tile.jpg. Without one, the plugin draws a representative tile in the theme's colors.

Simple and Developer mode (from 0.5.0)#

Most people editing a site use Simple mode, the default for everyone. They click words to type, click a button, link or picture to open its settings, and add sections with the + between two sections. The picker they see holds only the theme's components (the " sections" tab) and Live content: no Basic blocks, and no older sections. Developer mode is a switch in the ⋯ menu for administrators, off by default and set per person. It keeps the full structural editor and adds the Content, Style, Layout and Advanced visual inspector.

So in Simple mode the components are all an editor has to build a page with. For Simple mode to work well:

  • Cover what a page needs. Rule 8's set (a page top, a hero, text, photo and words, cards, a call to action…) is what a client picks from. A missing kind can't be made up from Basic blocks in Simple mode.
  • Give each component Layouts and Tones. The section's Style button opens its card, where Look offers exactly these (Layout, and Style for the tones), and they are the only way a client changes a section's look. A component with neither can only be added, moved or removed.
  • Mark layouts that always wear one tone with Fixed tone (band=dark, cover=dark). The editor then shows that one tone, chosen ("Always … in this layout"), instead of choices that do nothing. It also offers only the tones a component's words stay readable on, so check every tone you list.
  • Write Keywords in the words clients use ("sponsors", "board members", "sign up"). Search is how most people find a section.
  • Name the picker's groups for clients, if the defaults don't fit. The picker groups components by Kind, under plain names ("Top of a page", "Opening banner", "Key facts and figures", "Invitation to act"…). A theme can rename any of them in cantata-edit.json: "kindNames": { "stats": "Our impact in numbers" }.
  • A theme with no components still works: Simple mode then offers the plugin's Basic blocks under "Sections", so the picker is never empty. It is a fallback. A client site should have its own set.

Containers#

Developer mode always includes the Container block. A theme can optionally set the presets the Container calls Small, Medium and Large, and its Page width in cantata-edit.json:

"containers": {
  "space": { "s": "12px", "m": "24px", "l": "48px" },
  "wrap": "1280px"
}

Containers store only the plugin's cb-box… classes. The always-loaded defaults come from assets/container.css; a theme can override those classes when its design needs different behavior. Simple mode never exposes containers directly.

The rules#

  1. Colors, fonts and corners come only from tokens. Use var(--cb-dark) and never #16274F. The roles are: 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. GET /wp-json/cantata-edit/v1/design says what each role is on the current site. accent-2 is the site's second brand color, for marks only (stars, badges, icons, rules), never for body or heading text. On the dark tone and in a cover layout it becomes accent-on-dark, so marks stay visible on dark. If a design needs a color that no role covers, it's a sign the design should use a role instead.
  2. Layouts change CSS, never markup. Every layout uses the same HTML. layout-flip might reorder a grid, and layout-cover might put the photo behind the words. Switching layouts can then never lose what the editor typed. If two arrangements need different HTML, they are two components.
  3. Tones are the plugin's classes: cb-tone-light, cb-tone-tint, cb-tone-dark and cb-tone-accent on the section. Inside a tone, --cb-heading, --cb-ink, --cb-muted, --cb-line, --cb-accent and --cb-surface already hold the right colors for that background. So write the component once with those variables and it works in every tone. Check each tone you list in Tones. Editors can also color and align text inside a component with the plugin's classes: cb-color-heading, cb-color-ink, cb-color-muted, cb-color-accent, and cb-align-left, cb-align-center, cb-align-right. These follow the tone too. A theme can rename or hide those color choices through "textColours" in cantata-edit.json, but it can't add colors there. Don't fight these classes with more specific component CSS. The color classes go on the text element itself, or on a <span> around the selected words.
  4. Dummy content says what goes there. "A headline that says what you do in a few words" and not "Lorem ipsum", and not real client copy. Photos come from the theme's own stock photos if it has any ({{theme}}/assets/img/...), chosen to fit what the component is for rather than picked at random. Otherwise use {{img}}, the plugin's placeholder. It shows as a quiet panel in the site's tint, so don't style it yourself. Either way use alt="". Buttons link to /. Call a words-over-the-photo layout cover (layout-cover). Then, while its photo is still empty, the plugin drops the photo's overlay (its figure::after) so the words sit on the tone's own background.
  5. Build it so the editor can edit it.
    • Words sit in real text elements (h1-h4, p, li, blockquote, figcaption).
    • Style a hero's or page top's title by class or as :is(h1, h2), never as h1 alone. Added below a page's own title, it becomes an h2 (a page has one h1), and it must look the same.
    • A part that only some layouts show (a call to action's photo) is display: none in the others. The editor then leaves it out of the page, and puts it back from the sample when a layout shows it.
    • Pictures are <img>, never CSS backgrounds.
    • Repeating things (cards, tabs, stats) are sibling elements, so "Duplicate" adds another.
    • Buttons use the theme's button classes (button and button2 in cantata-edit.json).
    • No inline style, no <script>, no on*=.
  6. Interactive pieces use the plugin's markup (.cb-tabs, .cb-accordion), so its script and the editor's tab and panel tools work. Style them however the site wants, scoped to the component.
  7. CSS lives in the theme's stylesheet, scoped to the component (.c-hero ...). It must work at phone width (one column below about 860px) and must not depend on the page around it.
  8. Keep the set small. A site needs roughly 10-16 components: a hero, a page top, text, photo and words, columns, cards, tabs, accordion, a quote, a call to action, and whatever that site truly needs (stats, people, events). A variation belongs in Layouts or Tones, not in a new file.

Before calling one done#

  • Add it through ?edit → Add section, and click every piece of text, picture and button. Each one should select and edit.
  • Look at a real render of every layout × every listed tone, on desktop and at phone width. It should look designed for this site, not like a generic mockup.
  • Switch layouts back and forth after changing the words. The words have to survive.
  • Check the text contrast on the dark and accent tones.
  • If it has a JSON definition, open its card from the toolbar in Simple mode and change every field and item there.

Class names that have shipped#

A class name that has been saved into a page never disappears without an alias.

  • cb-hero-flip, cb-hero-center, cb-hero-cover (the plugin's hero before contract v1) are deprecated. They still render, as aliases of layout-flip, layout-center and layout-cover. New content uses layout-*.

Identifying repeated items in adapted markup#

A theme adapter may add data-ce-item="person" to the individual repeated element while the editor is open. Kindly Edit uses the closest named item for Simple mode's “Add another person” and “Remove this person” controls. This is useful when retained markup has repeated rows and columns that would otherwise look like a single item.

Name the smallest complete content unit, such as one card or button. Do not mark the editable root, a whole section, or generated content that the adapter does not own. Block-editor restrictions and the existing item removal/undo checks still apply. An empty name uses the ordinary “item” wording.

The marker is editor metadata: the browser and server strip data-ce-* attributes before saving. Adapters must add it again on each editing session and update their own markers after add/remove/undo without deleting markers owned by another adapter. It does not change the public markup or appearance.

Describing a component's content (custom elements)#

When a component has parts a client must manage as a set (slides, cards, people, a date badge), add components/NN-slug.json beside its HTML (from 0.11.0). It names the component's fields and repeated items, each found by a CSS selector, and the editor shows them in the element's card in Simple and Developer mode, with add, copy, move and remove for items. Items can fill themselves in from a post, such as an event. The page's HTML stays the only copy of the content, so on-page editing keeps working. The full format is in Custom elements.

Management controls for live sources#

A live source may set fixed: true to keep its source selector out of Simple mode. Individual fields may set internal: true to keep their setup values out of Simple mode while retaining their declarations for normalization. Developer mode still exposes both. These are editing affordances; capabilities and server validation remain responsible for permissions.

A slot's rendered output may include data-ce-manage-url and data-ce-manage-label on a descendant. A valid URL on the current origin overrides the source's management destination for that slot. External or malformed URLs are ignored. The slot output is transient and is emptied before save. This supports a single shortcode with different authoritative editors for different records.

About this page

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

Type a word or phrase to search the full documentation.