Cursor rules for Elementor sites

---
description: Editability rules for an Elementor site. Load when touching the
  child theme, custom plugins, or anything under wp-content.
globs:
  - "wp-content/themes/**/*.php"
  - "wp-content/plugins/**/*.php"
  - "wp-content/themes/**/*.css"
alwaysApply: false
---

# Elementor: keep the site editable

The client edits this site visually. Any markup that is not a widget is
markup they cannot change. Editability is a requirement, not a preference.

## Never write these

- **Do not hand-edit `wp-content/uploads/elementor/css/**`.** Those files
  (`post-*.css`, `global.css`) are generated. Elementor > Tools >
  Regenerate CSS & Data overwrites them, and your change vanishes.
- **Do not write to the `_elementor_data` postmeta by hand.** It is
  slash-escaped JSON; a naive edit corrupts the layout and the page opens
  empty in the editor.
- **Do not add layout HTML to PHP templates** to satisfy a design request.
  It is invisible in the editor. Build it as a widget or a template part
  the editor can see.
- **Do not use an HTML widget as a layout primitive.** One embed code is
  fine. A three-column grid inside an HTML widget is a section the client
  has lost.
- **No `!important`.** It wins against the editor's own controls, so the
  client changes a colour in the UI and nothing happens.

## Do these instead

- Colours, fonts, and spacing scales go in **Site Settings > Global
  Colors / Global Fonts** so they stay editable and stay consistent.
- Repeated blocks become **saved templates or global widgets**, not copied
  sections.
- Genuine custom CSS goes in the child theme, enqueued after Elementor:

  ```php
  add_action( 'elementor/frontend/after_enqueue_styles', function () {
      wp_enqueue_style(
          'child-overrides',
          get_stylesheet_directory_uri() . '/css/overrides.css',
          [],
          filemtime( get_stylesheet_directory() . '/css/overrides.css' )
      );
  } );
  ```

- Custom functionality becomes a **registered Elementor widget** with
  controls, so the client gets fields instead of hard-coded values.

## Performance still applies

Elementor is not an excuse for a slow site. This build holds 99 Performance
and 0 ms Total Blocking Time on mobile. Do not add a slider plugin, a second
icon library, or a font from a CDN to solve a layout problem.

<?php
use Elementor\Widget_Base;
use Elementor\Controls_Manager;

class Site_Stat_Widget extends Widget_Base {

    public function get_name() { return 'site_stat'; }
    public function get_title() { return __( 'Stat', 'site' ); }
    public function get_icon() { return 'eicon-number-field'; }
    public function get_categories() { return [ 'general' ]; }

    protected function register_controls() {
        $this->start_controls_section( 'content', [
            'label' => __( 'Content', 'site' ),
        ] );

        // Every value the designer chose becomes a field the client owns.
        $this->add_control( 'value', [
            'label'   => __( 'Value', 'site' ),
            'type'    => Controls_Manager::TEXT,
            'default' => '99',
        ] );

        $this->add_control( 'label', [
            'label'   => __( 'Label', 'site' ),
            'type'    => Controls_Manager::TEXT,
            'default' => __( 'Performance', 'site' ),
        ] );

        $this->end_controls_section();
    }

    protected function render() {
        $s = $this->get_settings_for_display();
        printf(
            '<div class="site-stat"><span class="site-stat__value">%s</span>' .
            '<span class="site-stat__label">%s</span></div>',
            esc_html( $s['value'] ),
            esc_html( $s['label'] )
        );
    }
}

#!/usr/bin/env sh

# Elementor's generated CSS is build output. If it is staged, someone either
# edited it by hand or committed a regenerate. Both are wrong.
if git diff --cached --name-only | grep -qE '^wp-content/uploads/elementor/css/'; then
  echo "✗ Generated Elementor CSS is staged (uploads/elementor/css/)."
  echo "  These files are rebuilt by Elementor > Tools > Regenerate CSS & Data."
  echo "  Put real overrides in the child theme instead."
  exit 1
fi

# !important beats the editor's own controls, so the client's UI stops working.
if git diff --cached -- 'wp-content/themes/**/*.css' | grep -qE '^\+.*!important'; then
  echo "✗ !important added to theme CSS — it overrides the Elementor controls"
  echo "  the client uses. Raise specificity instead, or use a Global Style."
  exit 1
fi