# Plugin Development Best Practices
> These are the **baseline rules** that apply to every plugin. For *situational*
> solutions (used only when a specific problem shows up — e.g. animated content,
> localizing `mount`-generated text, editor-only hints), see the opt-in companion
> [`plugin-patterns.md`](./plugin-patterns.md). Don't apply those by default.
## Essential Guidelines for Professional Plugins
### 1. Accessibility is Required
Accessibility attributes should be in the HTML structure from the start.
**HTML with Accessibility:**
```html
```
**Editor - Maintain Accessibility When Adding Items:**
```javascript
editor: {
openContentEditor: function(element, builder, onChange) {
//...
const addButton = document.createElement('button');
addButton.textContent = '+ Add Link';
addButton.onclick = () => {
const newLi = document.createElement('li');
newLi.setAttribute('role', 'listitem'); // Maintain accessibility
const newLink = document.createElement('a');
newLink.href = '#new';
newLink.textContent = 'New Link';
newLi.appendChild(newLink);
list.appendChild(newLi);
onChange?.();
};
}
}
```
**Checklist:**
- ✅ Semantic HTML (``, ``, ``)
- ✅ ARIA roles and labels
- ✅ Keyboard navigation (Tab, Enter, Space)
- ✅ Focus indicators
### 2. SEO-Friendly Structure
Content must exist in HTML before JavaScript executes.
**❌ Wrong - JavaScript-Generated Content:**
```javascript
mount: function(element) {
// Bad: Content invisible to search engines
element.innerHTML = `
`;
}
```
**✅ Correct - HTML Structure with JavaScript Behavior:**
```html
```
```javascript
mount: function(element) {
// Good: Only add behavior to existing content
const links = element.querySelectorAll('a');
links.forEach(link => {
link.addEventListener('click', handleClick);
});
}
```
### 3. Editor Builds Structure
Use the custom editor to create, modify, and manage HTML elements.
```javascript
editor: {
openContentEditor: function(element, builder, onChange) {
const container = document.createElement('div');
const list = element.querySelector('.nav-list');
// Create UI to add new items
const addButton = document.createElement('button');
addButton.textContent = '+ Add Link';
addButton.onclick = () => {
// Build new HTML structure
const newItem = document.createElement('li');
const newLink = document.createElement('a');
newLink.href = '#new';
newLink.textContent = 'New Link';
newLink.setAttribute('role', 'listitem');
newItem.appendChild(newLink);
list.appendChild(newItem);
onChange?.();
};
container.appendChild(addButton);
return container;
}
}
```
### 4. Mount Adds Behavior Only
The mount function applies runtime behavior and styling. Never create HTML structure here.
```javascript
mount: function(element, options) {
// Apply dynamic styles from settings
element.style.setProperty('--bg-color', options.backgroundColor);
element.style.setProperty('--text-color', options.textColor);
// Add event listeners
const links = element.querySelectorAll('a');
links.forEach(link => {
link.addEventListener('click', (e) => {
e.preventDefault();
scrollToSection(link.href);
});
});
// Track scroll position
window.addEventListener('scroll', () => {
updateActiveState(links);
});
return {};
}
```
**What mount should do:**
- ✅ Apply CSS custom properties
- ✅ Add event listeners
- ✅ Start animations/timers
- ❌ **Never** create HTML elements
- ❌ **Never** build structure
### 5. Styling: Two Surfaces, Two Rules
A plugin has two distinct styling surfaces. Keep them separate.
#### Surface A — the rendered block (`style.css`)
This is the block your visitors see. Style it however you like — **the only rule is that every selector must be scoped to your plugin's block** so it can't leak into other plugins, the host page, or the editor UI. Prefix the type attribute onto every rule:
```css
/* ✅ scoped — safe */
[data-cb-type="pricing-table"] .plan-name { font-weight: 600; }
/* ❌ global — collides with other plugins and the page */
.plan-name { font-weight: 600; }
```
There are **no shared tokens or base classes to learn** for the rendered block. Scoping is enough.
##### 💡 Suggestion (not a rule): design for flexibility, not one fixed look
*Use judgement — this is a nudge, not a requirement, and many plugins won't need any of it.*
When a block has a strong visual style, consider exposing the **stylistic choices** as options so it adapts to different site designs instead of locking into one aesthetic. A block that only looks right when it's rounded and softly shadowed will feel out of place on a flat/minimal or sharp/editorial site. This matters most for AI-generated plugins, which otherwise tend to bake in a single "nice" default.
Good candidates **when they apply to the block**:
- **Card shadow** on/off (flat vs. elevated)
- **Rounded vs. square** corners
- **Border** on/off, and the accent color
- sometimes density/size or alignment
It's cheap with the patterns you're already using — a `boolean` setting → `data-cb-*` attribute → a scoped CSS override, plus keeping colors as CSS variables (which also makes dark-mode adoption trivial):
```css
[data-cb-type="my-block"][data-cb-shadow="false"] .card { box-shadow: none; }
[data-cb-type="my-block"][data-cb-rounded="false"] .card { border-radius: 0; }
```
Default to your intended look so existing embeds are unchanged, and **only add options that give real design latitude** — skip ones that would just be noise.
**Don't force these onto blocks that are already neutral.** A background-effect or a divider has no "card" to soften. And a block that's already visually restrained — a plain form, an underline tab bar — adapts across designs on its own; leave it alone rather than bolting on flat/square toggles it doesn't need. These options earn their place on strongly-styled blocks (cards with shadows and big radii, like `pricing-table` / `testimonials` — see `data-cb-shadow`, `data-cb-rounded`), not on everything.
##### A `color` setting's `default` must equal the CSS variable it feeds
When a color setting drives a CSS variable (`element.style.setProperty('--x', options.x)`), the setting's `default` and the variable's default in `style.css` **must be the exact same value**. If they differ, the panel's color swatch shows one color while the block renders another — the picker lies about the real color.
```css
[data-cb-type="my-block"] { --card-border: #e5e7eb; } /* stylesheet default */
```
```js
borderColor: { type: 'color', default: '#e5e7eb' } /* ✅ same value — swatch matches the block */
borderColor: { type: 'color', default: '' } /* ❌ swatch shows empty; block still renders #e5e7eb */
```
Two consequences of how the color field works — it stores `toHex(color)`, so it is **hex-only, no alpha**:
- **Keep the variable's default a plain hex** — no `rgb(255 255 255 / 85%)`, `rgba()`, or any alpha. The picker can't represent it, so it would round to the opaque hex and drift out of sync. If you want a translucent fill, that's what a **Glass / opacity** option is for; keep the base solid fill a solid hex.
- **The "inherit the site theme" case is the one place an empty default is right** — e.g. a text color you want to inherit rather than pin (see `animated-stats` Number Color). There, pair `default: ''` with a CSS variable default of `inherit` (not a concrete color) and `setProperty('--x', options.x || '')`. Both sides then say "unset." Never mix an empty default with a *concrete* variable default — that's the mismatch above.
#### Surface B — the settings panel (`openContentEditor` UI)
Your custom editor renders inside the builder's settings panel (`.is-modal.pluginsettings`), which **already styles your controls** — do not fight it:
- `input`, `select`, `textarea`, `button` are **automatically full-width and styled**. Don't set widths/backgrounds on them.
- `label` is block, 13px, medium weight — just use ``.
- `` gives you an inline *checkbox + text* row for free.
- The builder ships an icon sprite — reuse it: `