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 "
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 incantata-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#
- 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/designsays what each role is on the current site.accent-2is 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 acoverlayout it becomesaccent-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. - Layouts change CSS, never markup. Every layout uses the same HTML.
layout-flipmight reorder a grid, andlayout-covermight 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. - Tones are the plugin's classes:
cb-tone-light,cb-tone-tint,cb-tone-darkandcb-tone-accenton the section. Inside a tone,--cb-heading,--cb-ink,--cb-muted,--cb-line,--cb-accentand--cb-surfacealready 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 inTones. 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, andcb-align-left,cb-align-center,cb-align-right. These follow the tone too. A theme can rename or hide those color choices through"textColours"incantata-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. - 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 usealt="". Buttons link to/. Call a words-over-the-photo layoutcover(layout-cover). Then, while its photo is still empty, the plugin drops the photo's overlay (itsfigure::after) so the words sit on the tone's own background. - 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 ash1alone. Added below a page's own title, it becomes anh2(a page has oneh1), and it must look the same. - A part that only some layouts show (a call to action's photo) is
display: nonein 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 (
buttonandbutton2incantata-edit.json). - No inline
style, no<script>, noon*=.
- Words sit in real text elements (
- 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. - 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. - 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
LayoutsorTones, 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 oflayout-flip,layout-centerandlayout-cover. New content useslayout-*.
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.