WordPress & Elementor Pro — Skill Router

A complete procedural guide for producing production-grade WordPress and Elementor Pro code. This file is the router — read it first, then load the relevant sub-file(s) for the task at hand.

---

Sub-file Map — Read the Right File for Each Task

Task type	Read this file
Plugin scaffold, child theme, code placement, CPT, AJAX handler	scaffolding.md
PHP standards, sanitization, escaping, nonces, WP_Error, transients, password hashing	php-standards.md
JavaScript standards, enqueue API, defer/async, wp_add_inline_script	js-css-standards.md
CSS standards, BEM, design tokens, Elementor CSS selectors	js-css-standards.md
Elementor custom widget, Dynamic Tags, Loop Grid, Form actions, Theme Builder conditions	elementor-patterns.md
Elementor extension points — custom form fields, theme locations, injecting controls into native widgets, adding a TAB to the editor's Elements panel, Finder/context-menu, hooks reference, deprecations	elementor-extending.md
WooCommerce HPOS, order API, template overrides, Loop Grid for products	woocommerce.md
REST API endpoints, schema, permission callbacks	rest-api.md
Off-canvas UI, off-canvas accessibility, focus trap	offcanvas-ui.md
Performance checklists (frontend + backend), speculative loading, IE conditional comments	performance.md
Accessibility checklist, WCAG 2.2 AA, ARIA patterns	performance.md
Hard-won production gotchas — widget lifecycle fatals, content_template() escaping, CSS-in-Elementor footguns, transactional email, wp.org review/packaging, embedding apps, AJAX/loop re-rendering, dynamic CSS in loops, Swiper on optimised sites	field-notes.md
wordpress.org submission — the 18 Directory Guidelines, Plugin Check 2.1.0 categories/usage, review process, required headers/readme	wp-org-guidelines.md
Subversion (SVN) — deploying/tagging a release on the wordpress.org plugin/theme SVN (trunk/tags/assets), the daily work cycle, branching/merging, properties, repo admin	svn/svn.md (self-contained sub-bundle; svn/references/ goes deeper)
Debugging & static analysis — PHPCS+WPCS, PHPStan, Plugin Check, WP_DEBUG/Query Monitor, Elementor Safe Mode/cache, symptom→cause table	debugging.md
Common WordPress APIs — admin settings page (Settings + Options API), register_meta, roles/capabilities, WP-Cron, internationalization (i18n)	wordpress-apis.md
Database layer (MariaDB/MySQL) — custom tables + dbDelta(), charsets & the varchar(191) index rule, indexes, EXPLAIN, MariaDB↔MySQL portability, sql_mode, full-text	mariadb.md

Widget Boilerplates — Load when building a widget of that type

Widget type	Read this file
Button / CTA with icon and link	widget-button.md
Container / layout wrapper / section / card shell	widget-container.md
Image with caption, link, lightbox	widget-image.md
Heading / title / HTML tag selector	widget-heading.md
Rich text / WYSIWYG body content	widget-text-editor.md
Video embed (YouTube, Vimeo, self-hosted)	widget-video.md
Widget that renders a saved Elementor template by ID	widget-elementor-template.md (SELECT2, get_builder_content_for_display(), Dynamic Tags context, CSS timing)
Widget whose markup lives in a separate PHP template file	widget-php-template.md (Strategies A/B/C, load_template(), ob_start, path-traversal safety)
Divider / horizontal rule with optional text or icon	widget-divider.md
Spacer / vertical gap	widget-spacer.md
Single standalone icon with optional link	widget-icon.md
Icon + title + description box	widget-icon-box.md
Image + title + description box	widget-image-box.md
Image grid / gallery	widget-image-gallery.md
Image slider / carousel	widget-image-carousel.md
Bullet list with icons per item	widget-icon-list.md
Animated number counter	widget-counter.md
Percentage progress bar	widget-progress.md
Customer quote / testimonial	widget-testimonial.md
Tabbed content panels	widget-tabs.md
Accordion — one panel open at a time	widget-accordion.md
Toggle — multiple panels open simultaneously	widget-toggle.md
Social media icon links row	widget-social-icons.md
Colored alert / notice box	widget-alert.md
Audio player (SoundCloud / self-hosted)	widget-audio.md
WordPress shortcode output	widget-shortcode.md
Raw custom HTML / JS / CSS embed	widget-html.md
Named anchor for in-page navigation	widget-menu-anchor.md
WordPress registered sidebar output	widget-sidebar.md
WordPress read more tag	widget-read-more.md
Google Maps embed	widget-google-maps.md
Decorative star rating display	widget-star-rating.md
Schema-ready structured rating	widget-rating.md
Text following a curved / custom SVG path	widget-text-path.md
Nested Tabs / Nested Accordion (each panel is a Container holding any widgets)	widget-nested.md

Always read the relevant sub-file before writing code. For tasks that span multiple areas (e.g. a WooCommerce widget with custom REST endpoint), read all relevant sub-files. For a widget task, read BOTH the widget boilerplate file AND elementor-patterns.md. For any custom widget, plugin, or wp.org-bound work, also skim field-notes.md — it catches the lint-passing, review-failing, site-down mistakes the topic files don't dwell on.

---

0. Golden Rules (Never Violate)

These override everything in all sub-files:

1. Native APIs first — WordPress core hook before plugin; Elementor API before template override.
2. Sanitize in, escape out — Every input sanitized. Every output escaped. No exceptions.
3. Prefix everything — All functions, classes, constants, hooks, and CSS classes use a project-specific prefix.
4. State your placement — Every code response must declare exactly where the code lives.
5. No over-clarifying — Only ask a clarification question if the missing info would materially change the code output. Otherwise, state your assumption and proceed.
6. NEVER hardcode visual settings in widgets — Every visual property (colors, fonts, sizes, spacing, backgrounds, borders, shadows, alignment) MUST be exposed as a standard Elementor control in the editor panel. Users control appearance via the toolbar — not by editing code. See §5 "Mandatory Widget Controls" below for the required controls checklist.
7. Name for the directory from day one — Naming is decided first and is effectively irreversible, so get it right before writing code. The plugin slug/name must NOT start with a trademark you don't own — "CRM for WooCommerce", never "WooCommerce CRM" (Directory Guideline 17). The text domain must exactly equal the plugin slug. The wp.org slug is permanent, and a widget's get_name() is sticky (stored in every page's _elementor_data — renaming it breaks placed widgets). Choose the public name, slug, text domain, and code prefix (Rule #3) together, once. This is distinct from Rule #3: that governs internal code symbols; this governs the public identity. See wp-org-guidelines.md (Guidelines 12/16/17) and field-notes.md §1 (sticky get_name()).

---

1. Default Assumptions

Quickly assess — only ask if the answer would change the code:

Info needed	Ask only if...
Scope (plugin vs snippet vs child theme)	Context doesn't make it obvious
Elementor tier (Free / Pro / custom widget)	Pro-only APIs are involved
PHP version	Code uses PHP 8.3+ features like typed class constants, or 8.4+ features like property hooks
WooCommerce / ACF / WPML present	Integration with those systems is required

Default stack when not stated (full release-by-release history lives in CHANGELOG.md — keep volatile version-tracking out of this router):

Component	Version	Notes
WordPress	7.1	"Mary Lou", released Aug 19, 2026 (7.0 "Armstrong" was May 20; the 7.0 branch ended at 7.0.4, Aug 12). Minimum PHP 7.4 (7.2/7.3 dropped — sites still on them stay pinned to 6.9.x). No multisite assumed. 7.1 makes the post editor iframe unconditional — see below.
PHP	8.3 recommended	7.4 = minimum. 8.4 / 8.5 = "beta support" (possible deprecation notices). 8.2 fully compatible but no longer the recommended default.
Elementor (free + Pro)	4.2+	Separate plugins with independent version numbers — currently free 4.2.3 / Pro 4.2.2 (both Aug 19, 2026). 4.0.0 (Mar 30, 2026) made the Atomic Editor stable + default for new installs; 4.2.0 (Jul 20) added Atomic Grid (free) and Atomic Loop (Pro). ⚠️ Elementor's header still reads "Tested up to: 7.0.4" — it has not declared WP 7.1 support. V3 Widget_Base remains fully supported — all skill code targets V3 and is production-safe.
WooCommerce	11.0+	11.0 (Aug 4, 2026) REMOVED the product editor beta and bumped to Action Scheduler 4.0.0 (breaking dedup change). HPOS default-on since 8.2; 10.7 disabled HPOS "sync on read"; 10.9 defers Store API draft-order creation — see woocommerce.md.

Note: Elementor core and Elementor Pro have independent version numbers — always check both when diagnosing compatibility issues.

WordPress 7.1 — what changed for plugin / Elementor devs

WP 7.1 "Mary Lou" shipped August 19, 2026 (WordCamp US). Unlike 7.0, this release contains four changes that can break a shipped plugin — they are listed first. No PHP or WordPress minimum changed.

🔴 Breaking — audit your plugin for these:

1. The post editor is now ALWAYS in an iframe — including on sites registering legacy meta boxes, which was the last remaining escape hatch. Editor JavaScript that reaches for the global document / window now targets the wrong document. Use the canvas element's ownerDocument and defaultView instead:

   // ❌ breaks in 7.1 — this is the OUTER document, not the editor canvas
   document.querySelector( '.my-block' ).classList.add( 'ready' );
   
   // ✅ resolve the document from a node you already own inside the canvas
   const doc  = myCanvasNode.ownerDocument;
   const view = doc.defaultView;                   // the iframe's `window`
   doc.querySelector( '.my-block' )?.classList.add( 'ready' );
   view.requestAnimationFrame( … );
   

   Injected <style>/<link> must go into the canvas document too, or it styles nothing. Elementor's own editor is unaffected (it is not the block editor) — this hits block registrations, meta boxes, and any block-editor integration your plugin ships.
2. __next40pxDefaultSize is now a no-op on @wordpress/components — remove the prop entirely; there is no replacement. Form controls render at 40px unconditionally.
3. List-table markup changed: the row header moved from the checkbox column to the title column. Any CSS/JS selector keyed on th.check-column (or assuming the row header's position) breaks — audit custom admin list tables and column callbacks.
4. jQuery UI updated to 1.14.2. Test anything depending on jQuery UI behaviour or styling.

🟢 New and useful:

• SVG Icon API (public in 7.1) — register icons and whole collections, render server-side, read over REST: wp_register_icon_collection(), wp_register_icon(), wp_get_icon(). ⚠️ SVGs pass through a conservative allowlist — only <svg>, <path> and <polygon> survive. A <g>, <circle>, <rect> or <use> in your icon is stripped silently, so convert shapes to paths before registering. (This is a core API — Elementor widgets still ship their own SVGs; see elementor-extending.md §8 and the "don't wp_kses() inline SVG" rule in field-notes.md §6.)
• Abilities API matured: wp_get_abilities() filtering, execution-lifecycle hooks, custom validation, a unified public exposure flag, and client-compatible JSON-Schema preparation. Registration timing rules from 7.0 are unchanged (see the 7.0 section below).
• Global Styles / theme.json: responsive style variations with configurable breakpoints, pseudo-state styling (:hover / :focus / :active), and text-shadow support.
• Media: client-side image processing in the browser via WebAssembly (compression/resizing no longer hit the server), infinite scroll in the Media Library, and registration of multiple image sizes at once. Multisite now enforces upload limits on media sideloading.
• Persistent admin bar across editor screens — review any custom toolbar nodes for behaviour in the editor context.
• Design System: semantic design tokens for theming admin UI (relevant if you build admin or editor panels — compare the Elementor panel tokens in elementor-extending.md §5).
• DataViews / DataForm APIs matured for data-driven admin interfaces.
• React stays on 18.3 — React 19 was deferred again. Don't bundle react/jsx-runtime yourself, and avoid string refs / defaultProps, which fail under the experimental React 19 flag.
• Conditional block-CSS loading can affect remote content pulls — verify if you render blocks outside a normal page request.

Sources: wordpress.org/news/2026/08/mary-lou/ · make.wordpress.org/core/2026/08/05/wordpress-7-1-field-guide/ · developer.wordpress.org/news/2026/08/whats-new-for-developers-august-2026/

WordPress 7.0 — what changed for plugin / Elementor devs

WP 7.0 "Armstrong" shipped May 20, 2026 (delayed from the original April 9 target while the RTC storage layer was redesigned — see below). Everything below is opt-in and non-breaking; most plugin/Elementor work is unaffected. It remains relevant because 7.1 changed none of it.

• Minimum PHP is now 7.4 (7.2/7.3 dropped). The skill's recommended baseline stays PHP 8.3. Bump your plugin's Requires PHP header to 7.4 only once you target WP 7.0+ exclusively. No new DB minimum is enforced; wordpress.org/about/requirements/ recommends MariaDB 10.11+ or MySQL 8.0+ (the MariaDB floor was raised from 10.6; re-verified Aug 2026).
• Real-Time Collaboration (RTC): simultaneous multi-author block editing (CRDT-based, via an HTTP-polling sync provider — not WebRTC). Data is stored in a dedicated core database table; an earlier wp_post_meta / wp_sync_storage design was rejected, and building the table is what pushed the release from April to May. Plugin impact: scope every WP_Query / get_posts() with an explicit post_type so internal core post types never leak into your results — do not hardcode any internal RTC type name. The WP_ALLOW_COLLABORATION constant lets hosts swap the sync transport.
• WP AI Client: provider-agnostic PHP + JS AI API — wp_ai_client_prompt( $prompt )->generate_text(). Guard with function_exists( 'wp_ai_client_prompt' ).
• Abilities API: wp_register_ability() (PHP, since WP 6.9) plus a JS counterpart in 7.0. Use 'meta' => ['show_in_rest' => true] to expose via REST. Register ONLY inside the wp_abilities_api_init hook (core renamed the feature plugin's abilities_api_init; categories go on wp_abilities_api_categories_init) or you get _doing_it_wrong; a category is required and must already be registered. Calling it also sets your real Requires at least floor to 6.9 — Plugin Check errors on the header and function_exists() guards don't count (see debugging.md §1).
• Connectors UI (Settings → Connectors) for managing AI provider credentials, and a Command Palette in wp-admin.
• Iframed editor was still conditional in 7.0 — 7.1 makes it unconditional. See the 7.1 section above; "apiVersion": 3 in block.json is now table stakes, not preparation.

Sources: make.wordpress.org/core/2026/01/09/dropping-support-for-php-7-2-and-7-3/ · make.wordpress.org/core/2026/04/22/wordpress-7-0-release-party-updated-schedule/ · wordpress.org/about/requirements/

📌 PHP support labels (unchanged in WP 7.1): PHP 7.4–8.3 fully compatible; 8.3 recommended; 8.4 (WP 6.7+) and 8.5 (WP 6.9+) carry a "beta support" label (possible deprecation notices). Source: make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/

✅ Elementor 4.x status (current: free 4.2.3 / Pro 4.2.2, both Aug 19, 2026): Elementor 4.0.0 (Mar 30, 2026, free + Pro) made the Atomic Editor stable and the default for new installs and added Atomic Forms, Pro Interactions, and Component creation. Updating to 4.x leaves existing sites untouched — V3 widgets and V4 Atomic Elements coexist on the same page; Atomic features are toggled at WP Admin → Elementor → Editor → Settings.

There is still NO third-party API for building Atomic Elements, and Elementor has said so explicitly — they will not release one soon and advise against integrating with Atomic internals until they announce it (elementor/elementor GitHub Discussion #32950). Atomic Elements are documented only as a data structure (developers.elementor.com/docs/data-structure/atomic-elements). So continue using V3 Widget_Base for all third-party widgets — it is the correct, production-safe API and all skill code targets it. (Re-verified Aug 23, 2026 — unchanged since the July check.)

⚠️ Elementor has not declared WP 7.1 compatibility yet. As of free 4.2.3 / Pro 4.2.2 the Tested up to header reads 7.0.4, three days after WP 7.1 shipped. That is normal lag, not a known incompatibility — but when a client reports editor breakage on a fresh 7.1 site, check Elementor's current Tested up to before debugging your own code.

V4 Atomic Elements that now ship by default (awareness only — not third-party-buildable yet): Div Block & Flexbox Container (layout); Atomic Grid — advanced row/column layouts (free 4.2.0, Jul 20, 2026); Atomic Heading, Paragraph, Image, Button, Video, SVG; Atomic Tabs; Atomic Forms (Pro) with composable fields — Label, Input, Textarea, Checkbox, Submit, plus Radio, Select, Date Picker, Time Picker, and File Upload (added in Pro 4.1.0, May 26, 2026); and Atomic Loop — dynamic content layouts, the V4 counterpart of the Pro Loop Grid (Pro 4.2.0, Jul 20, 2026). These are end-user elements; building custom atomic elements still awaits the finalized V4 extension docs — keep targeting V3 Widget_Base until then. Source: elementor.com/products/website-builder/v4-faq/ · developers.elementor.com/elementor-editor-4-0-developers-update/ · elementor.com/pro/changelog/ · github.com/elementor/elementor/releases

🗓️ Release-by-release history (betas, RCs, point releases) lives in CHANGELOG.md. Keep this router focused on durable guidance; update version facts in the table above and in CHANGELOG.md, not scattered across the sub-files.

---

2. Architecture Decision Tree

Run through this mentally before writing a single line:

Does a WordPress core hook (add_action/add_filter) solve it?
  YES → Use the hook. No plugin needed. Place in child theme functions.php
        or Elementor Custom Code.
  NO  → Does Elementor's PHP/JS API solve it?
          YES → Extend via Elementor hooks, Dynamic Tags, or Widget_Base.
                Register via elementor/widgets/register or elementor/dynamic_tags/register.
          NO  → Is this logic reusable across themes or sites?
                  YES → Scaffold a dedicated plugin (see scaffolding.md).
                  NO  → Child theme functions.php or Elementor Custom Code block.

Is a WooCommerce override needed?
  → Use Elementor Loop Grid + custom query filter BEFORE touching template files.
  → Only override woocommerce/ templates as an absolute last resort.

Is this a REST API endpoint?
  → Always register via register_rest_route() inside a plugin, never in functions.php.

---

3. Mandatory Output Format

Every single code response must follow this structure — no exceptions:

📍 PLACEMENT
Exact file path or Elementor hook location.
e.g. /wp-content/plugins/myplugin/includes/class-myplugin-hooks.php
     Elementor → Site Settings → Custom Code → wp_footer

⚙️ REQUIRES
WordPress X.X+ | PHP X.X+ | Elementor Pro X.X+ | ACF X.X+ | WooCommerce X.X+
(list only what the code actually depends on)

💡 WHY THIS APPROACH
One paragraph: which branch of the §2 decision tree was taken and why.

📋 CODE
Complete, commented, deployment-ready code block — no truncation, no omissions.

🔧 INTEGRATION NOTES (include when relevant)
Any manual steps required: flush rewrite rules, set Query ID in Elementor editor,
activate plugin, clear Elementor cache, etc.

---

4. Quick Reference — Pattern Index