Divi 5 Builder Skill

Build modern, VB-editable Divi 5 pages programmatically via MCP tools.

DiviOps harness conventions

Cross-cutting contracts the Divi-builder tools inherit — response envelope ({ ok, data?, error: { code, message, hint?, data? } }), capability handshake / three-layer gating, dry_run plan shape, idempotency conventions, and namespace-prefixed error codes (<ns>.not_configured gate vs <ns>.command_failed runtime) — live in the diviops/ primer skill. SCF coverage lives in diviops-scf/. When this skill references "the standardized envelope" or "the capability handshake," the primer is the source.

Reference Files

Read the right file for the task at hand — don't load everything.

Workflow Best Practices

1. Build incrementally: create_page → section_append × N
2. Always label sections: meta.adminLabel on every section
3. Label key modules: Add admin labels to modules you might edit later
4. Validate before saving: Use diviops_validate_blocks before diviops_page_update_content, diviops_tb_layout_update, or diviops_library_save
5. Use diviops_meta_find_icon: Don't guess icon codes — search by keyword
6. Prefer VB-native: Use Divi attributes over CSS whenever possible; for Divi-owned spacing, sizing, and visibility issues, find the native setting before reaching for CSS
7. Font inheritance: Set global fonts via theme options, skip explicit family on modules
8. Use semantic HTML: Set elementType for SEO/accessibility (header, nav, main, article, footer)
9. Always use section/row/column structure: Wrapperless top-level modules lose styling
10. Cache invalidation: All write tools auto-invalidate Divi's CSS cache. If styles appear stale, hard-refresh the browser.

Verification convention

Skill docs label findings by evidence quality. Runtime acceptance ≠ VB compatibility — a path can render correctly via MCP write but get rewritten or rejected on VB save. When citing or extending these docs, preserve the existing tier:

The two real failure modes this prevents (feedback_schema_canonical_path, feedback_vb_first_verification):

• A path that renders but is not VB-editable — downstream user opens VB, value silently re-resolves to default
• A path that runtime accepts but VB rewrites on save — the very next user save undoes our write

Upgrade tier by VB round-trip: have the user save the shape in VB, then dump the registry/block markup. If the shape is preserved exactly, stamp (VB-verified DATE). If VB rewrote it, document the canonical shape (what VB wrote) and the runtime-permissive variant separately.

Design Quality Checklist

When generating pages, ALWAYS apply:

• Entrance animations on visible modules (fade/slide with staggered delay: 0ms, 150ms, 300ms, 450ms)
• Hover states on cards, buttons, icons (use desktop.hover format)
• Responsive overrides (tablet/phone: padding, font sizes, flexDirection: column)
• Visual mobile check for Group/card grids (verified 2026-05-28) — validation passing only proves block shape, not phone-safe stacking
• Use divi/number-counter for stats — animates counting on scroll (not plain text)
• Use Group flex for multi-column layouts with flexType sizing (not Row with multiple columns)
• Minimum: 8+ animations per page, hover on every interactive element
• See design-guide.md for copy-paste patterns and recipes

Design System Lifecycle

How DiviOps handles styling

Every page you generate uses one of three tiers for any given style value:

DiviOps generates working, design-complete pages at any tier. Tokens and presets are consistency optimizations for projects that need them — they are NOT prerequisites.

First time on a project? Start here

You don't need to set anything up. Page generation works out of the box with inline values using patterns from design-guide.md. Skip the rest of this section unless you want design-system reuse across many pages.

Come back here when:

• You want colors/sizes shared across many pages without duplicating values → bootstrap tokens
• You want a reusable design system with our oa token + preset naming → run the full bootstrap workflow

Runtime resolution cascade (how pages are actually styled)

Every page generation follows this cascade — you'll land at whichever tier your project has set up:

1. Read .claude/design-system.json → look up presets.<role-key>.id (fast path, if the manifest exists)
2. If manifest missing → diviops_preset_audit, match presets by name, build an in-memory map (if oa-prefixed presets exist)
3. If no oa presets found → inline styling from design-guide.md patterns

Most first-time runs hit step 3 and that's fine — output is still polished, animated, responsive, VB-editable.

About the oa convention (optional)

The oa design system uses universal token names (gcid-oa-primary-500, gvid-oa-size-h1) and preset names (oa Heading H1, oa Button Primary) across all projects. What differs per site is the values behind tokens and the UUIDs Divi assigns to presets.

If you prefer different names or no prefix, skip bootstrap entirely — inline styling doesn't need oa or any other convention.

Manifest: .claude/design-system.json

When bootstrap is complete, this per-project file maps preset role keys (e.g. heading-h1, button-primary) to site-specific UUIDs. NOT shipped with the skill — lives in the project's .claude/ dir