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

Widget Boilerplates — Load when building a widget of that type

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.

1. 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:

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

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.

1. `__next40pxDefaultSize` is now a no-op on @wordpress/components — remove the prop

entirely; there is no replacement. Form controls render at 40px unconditionally.

1. 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.

1. 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

5. Mandatory Widget Controls — No Hardcoded Visuals (NEVER VIOLATE)

This section is MANDATORY for every custom Elementor widget. Whenever you build a widget, every visual property must be an Elementor control — NEVER a hardcoded CSS value. Users control appearance from the editor panel/toolbar, not by editing source code.

The Rule

NEVER hardcode any of the following in PHP render(), in static CSS, or in content_template() output:

• Colors (text, background, border, shadow)
• Typography (font family, size, weight, line-height, letter-spacing, transform)
• Spacing (padding, margin, gap)
• Sizing (width, height, min/max values)
• Borders (style, width, color, radius)
• Shadows (box-shadow, text-shadow)
• Backgrounds (color, gradient, image)
• Alignment / positioning
• Opacity, transitions, hover effects

ALL of the above must use Elementor controls with selectors that inject CSS dynamically. The only exceptions are structural CSS (display, position, overflow) required for the widget layout to function at all — and even these should use controls when there is a user-facing choice (e.g. flex-direction toggle).

⚠️ "No hardcoded visuals" does NOT mean "put a `default` on every control." Elementor emits a default exactly like a user-set value, so a colour default paints on every install and clearing the swatch only restores it — the user cannot turn it off. Elementor core carries no `default` on colour controls at all (includes/widgets/heading.php: title_color uses a 'global' reference; title_hover_color is entirely empty). Follow that split: - Sizes, spacing, alignment, toggles, tags, labels → give a real 'default'. - Colours → leave empty. Put the resting look in your stylesheet's var(--token, fallback) and let the control override it. For state colours (hover / active / selected / current) also write a direct CSS property, never a custom property, and keep that state colour-free in your CSS — otherwise "empty" still paints the fallback.

>

See field-notes.md §4 for the full trap, plus the theme-specificity and accent-color cases.

Required Controls Checklist — Apply to Every Widget

When building a widget, include ALL controls that apply to its visual elements. Use this checklist as a mandatory gate:

Example — Correct vs Incorrect

// ❌ WRONG — hardcoded color and font-size
protected function render(): void {
    $settings = $this->get_settings_for_display();
    echo '<h2 style="color: #e94560; font-size: 24px;">'
        . esc_html( $settings['title'] ) . '</h2>';
}

// ✅ CORRECT — all visuals controlled from the panel via selectors
protected function register_controls(): void {
    // ... Content section with title TEXT control ...

    $this->start_controls_section( 'section_title_style', [
        'label' => esc_html__( 'Title Style', 'myplugin' ),
        'tab'   => \Elementor\Controls_Manager::TAB_STYLE,
    ] );

    $this->add_control( 'title_color', [
        'label'     => esc_html__( 'Color', 'myplugin' ),
        'type'      => \Elementor\Controls_Manager::COLOR,
        'selectors' => [
            '{{WRAPPER}} .myplugin-widget__title' => 'color: {{VALUE}};',
        ],
    ] );

    $this->add_group_control(
        \Elementor\Group_Control_Typography::get_type(),
        [
            'name'     => 'title_typography',
            'selector' => '{{WRAPPER}} .myplugin-widget__title',
        ]
    );

    $this->add_responsive_control( 'title_align', [
        'label'   => esc_html__( 'Alignment', 'myplugin' ),
        'type'    => \Elementor\Controls_Manager::CHOOSE,
        'options' => [
            'left'   => [ 'title' => esc_html__( 'Left',   'myplugin' ), 'icon' => 'eicon-text-align-left' ],
            'center' => [ 'title' => esc_html__( 'Center', 'myplugin' ), 'icon' => 'eicon-text-align-center' ],
            'right'  => [ 'title' => esc_html__( 'Right',  'myplugin' ), 'icon' => 'eicon-text-align-right' ],
        ],
        'selectors' => [
            '{{WRAPPER}} .myplugin-widget__title' => 'text-align: {{VALUE}};',
        ],
    ] );

    $this->add_responsive_control( 'title_spacing', [
        'label'      => esc_html__( 'Bottom Spacing', 'myplugin' ),
        'type'       => \Elementor\Controls_Manager::SLIDER,
        'size_units' => [ 'px', 'em', 'rem' ],
        'range'      => [ 'px' => [ 'min' => 0, 'max' => 100 ] ],
        'selectors'  => [
            '{{WRAPPER}} .myplugin-widget__title' => 'margin-bottom: {{SIZE}}{{UNIT}};',
        ],
    ] );

    $this->end_controls_section();
}

protected function render(): void {
    $settings = $this->get_settings_for_display();
    // ✅ No inline styles — all visuals come from Elementor's selectors
    $this->add_render_attribute( 'title', 'class', 'myplugin-widget__title' );
    $this->add_inline_editing_attributes( 'title' );
    echo '<h2 ' . $this->get_render_attribute_string( 'title' ) . '>'
        . esc_html( $settings['title'] ) . '</h2>';
}

add_render_attribute() and add_inline_editing_attributes() — Always Use

The official Elementor API for building HTML attributes is $this->add_render_attribute(). Always use it instead of manually concatenating class/id/aria attributes in render(). Pair with $this->add_inline_editing_attributes() for any text field that supports live editing in the Elementor editor panel.

Outputting the built attributes — pick by context: use get_render_attribute_string( 'key' ) when you are concatenating into a string (as in the echo '<h2 ' . ... . '>' example above), and print_render_attribute_string( 'key' ) when you are echoing directly inside a ?> … <?php HTML block (e.g. <h2 <?php $this->print_render_attribute_string( 'title' ); ?>>). Both are correct Elementor APIs — print_* simply echoes what get_* returns. The widget sub-files use the print_* form inside their HTML templates.

Source: developers.elementor.com/docs/widgets/rendering-html-attribute/ Source: developers.elementor.com/docs/widgets/rendering-inline-editing/