WordPress / Nectar lessons

These preferences were distilled from a client WordPress + Nectarblocks rebuild — a Dockerized WordPress reconstruction of a Workers prototype. This page keeps the concrete, WordPress-specific lessons; read it only when a task actually touches WordPress or Nectarblocks. (Versions: the lab ran the Nectarblocks 2.6.0 bundle, while the sample-markup corpus used for reference was 2.5.4 — defer to the project’s own Nectar skills for exact block markup.)

The WordPress-first pipeline (keep it boring)

• Custom rendering logic lives in a block plugin; page composition lives in WordPress block comments under versioned page-markup files.
• Server-rendered dynamic blocks keep seeded pages compact and repeatable while staying editable as real WordPress blocks.
• Page markup round-trips between the database and the filesystem: pull after editing in WordPress; dry-run before writing filesystem edits back to the database.
• Don’t broaden the sync lane (uploads, menus, posts, global styles) unless one becomes real source-of-truth content.

Block-validity discipline

• Preserve the WordPress block comments around native blocks. Never hand-edit only the rendered HTML and leave stale JSON in the opening <!-- wp:... {...} --> comment.
• Keep blockId, the rendered id, and parent-block-* classes pointing at the same block identity. Generate unique blockIds when copying a section.
• For quick prototypes, keeping a whole section as core/html is fine — just document that it is not editable as native blocks.

Hard-won gotchas

• && entity-encoding: in core/html inline scripts, avoid JavaScript && — WordPress may entity-encode it as && and break the script. Use nested if statements instead.
• Runtime dependency: don’t add data-await-in-view-* attributes unless the page has the Nectar frontend runtime (or a compatibility layer that removes the hidden state), or animated sections stay invisible.
• Real assets: avoid remote demo images in final layouts; prefer real site media.

Nectar motion values (observed)

Distinctive because they run slower than a typical product-motion default (~300ms ceiling) — keep them as the house feel on these pages, and don’t let faster defaults silently override them:

• Entrance motion ~1.0–1.2s with a small 0.05–0.2s stagger between related elements.
• Scroll-position scrubbing and pinning used sparingly, mostly for hero / feature moments.

Fidelity with restraint (the pattern)

From the rebuild’s UI pass — tight fidelity to the prototype, applied with restraint:

• Reduced the hero headline size; kept the primary call-to-action above the fold at laptop dimensions.
• Copied the signature button effect onto exactly one button.
• Made top navigation sticky with section anchors; moved page-route links to the footer.
• Cropped the logo to a centered square for the nav.
• Fixed dark-on-dark text spots found during browser QA.