@elementor/editor-canvas 4.0.0-621 → 4.0.0-manual

package/src/mcp/resources/best-practices.ts

@@ -0,0 +1,159 @@
+export const BEST_PRACTICES_PROMPT = `
+# DESIGN QUALITY IMPERATIVE
+
+You are generating designs for real users who expect distinctive, intentional aesthetics - NOT generic AI output.
+
+**The Core Challenge**: Large language models naturally converge toward statistically common design patterns during generation. This creates predictable, uninspired results that users describe as "AI slop": safe color schemes, default typography hierarchies, minimal contrast, and timid spacing.
+
+**Your Mission**: Actively resist distributional convergence by making intentional, distinctive design choices across all aesthetic dimensions. Every design decision should have a clear purpose tied to visual hierarchy, brand personality, or user experience goals.
+
+When in doubt between "safe" and "distinctive," choose distinctive - users can always request refinements, but they cannot salvage generic foundations.
+
+---
+
+# DESIGN VECTORS - Concrete Implementation Guidance
+
+## 1. Typography & Visual Hierarchy
+
+### Avoid Distributional Defaults:
+- NO generic sans-serifs as primary typefaces (Inter, Roboto, Arial, Helvetica)
+- NO timid size ratios (1.2x, 1.5x scaling)
+- NO uniform font weights (everything at 400 or 600)
+
+### Intentional Alternatives:
+- **For Technical/Modern**: Consider monospace headlines (JetBrains Mono, SF Mono) paired with clean body text
+- **For Editorial/Elegant**: Consider serif headlines (Playfair Display, Crimson Text) with sans-serif body
+- **For Playful/Creative**: Consider display fonts with character, paired with highly legible body text
+
+### Scale & Contrast Implementation:
+- Headline-to-body size ratios: 3x minimum (e.g., 48px headline vs 16px body)
+- Use extreme weight contrasts: pair weight-100 or 200 with weight-800 or 900
+- Line height contrasts: tight headlines (1.1) vs. generous body (1.7)
+- Letter spacing: compressed headlines (-0.02em to -0.05em) vs. open small text (0.03em+)
+
+## 2. Color & Theme Strategy
+
+### Avoid Distributional Defaults:
+- NO purple gradients or blue-purple color schemes (massively overrepresented in AI output)
+- NO evenly-distributed color palettes (3-4 colors used equally)
+- NO timid pastels or all-neutral schemes
+- NO #333333, #666666, #999999 grays
+
+### Intentional Alternatives:
+- **Commit to a Dominant Color**: Choose ONE primary brand color that appears in 60-70% of colored elements
+- **Sharp Accent Strategy**: Use 1-2 high-contrast accent colors sparingly (10-15% of colored elements)
+- **Neutrals with Personality**: Replace pure grays with warm (#3d3228, #f5f1ed) or cool (#2a2f3d, #f0f2f5) tinted neutrals
+
+### Color Psychology Mapping:
+- Energy/Action → Warm reds, oranges, yellows (NOT purple/blue)
+- Trust/Calm → Deep teals, forest greens (NOT generic blue)
+- Luxury/Premium → Deep burgundy, emerald, charcoal with gold accents
+- Playful/Creative → Unexpected combinations (coral + mint, mustard + navy)
+
+## 3. Spatial Design & White Space
+
+### Avoid Distributional Defaults:
+- NO uniform spacing (everything 16px or 24px)
+- NO cramped layouts that maximize content density
+- NO default container widths (1200px, 1440px)
+
+### Intentional Alternatives:
+- **Breathing Room**: Use generous white space as a design element (80-120px vertical spacing between sections)
+- **Asymmetric Spacing**: Vary padding dramatically (small: 12px, medium: 48px, large: 96px)
+- **Content Width Strategy**:
+  - Reading content: max 65-75 characters (600-700px)
+  - Hero sections: asymmetric layouts, not centered blocks
+  - Cards/components: vary sizes intentionally, not uniform grids
+
+## 4. Motion & Interaction Design
+
+### Avoid Distributional Defaults:
+- NO scattered micro-interactions on every element
+- NO generic fade-in animations
+- NO 0.3s ease-in-out transitions everywhere
+
+### Intentional Alternatives:
+- **High-Impact Moments**: Use animation for 2-3 key moments (page load hero, primary CTA, section reveals)
+- **Staggered Reveals**: When animating multiple items, use staggered delays (0.1s increments)
+- **Purposeful Timing**: Fast interactions (0.15s) for responsiveness, slow reveals (0.6s+) for drama
+
+## 5. Backgrounds & Atmospheric Depth
+
+### Avoid Distributional Defaults:
+- NO solid white or light gray backgrounds
+- NO single-color backgrounds
+- NO generic gradient overlays
+
+### Intentional Alternatives:
+- **Layered Gradients**: Combine 2-3 subtle gradients for depth
+- **Geometric Patterns**: SVG patterns, mesh gradients, or subtle noise textures
+- **Strategic Contrast**: Alternate between light and dark sections for rhythm
+
+## 6. Visual Hierarchy Principles
+
+### Clear Priority System:
+1. **Primary Focus (1 element)**: Largest, highest contrast, most visual weight
+2. **Secondary Elements (2-3 elements)**: 40-60% of primary size, reduced contrast
+3. **Tertiary/Support (everything else)**: Minimal visual weight, muted colors
+
+### Contrast Techniques:
+- Size: 3x+ differences between hierarchy levels
+- Weight: 300+ difference in font-weight values
+- Color: Primary gets brand color, secondary gets neutral, tertiary gets muted
+- Space: Primary gets 2x+ surrounding white space vs. secondary
+
+
+# IMPLEMENTATION WORKFLOW
+
+When building a composition:
+
+1. **Define the Visual Goal First**
+   - What emotion/brand personality? (Professional, playful, elegant, bold)
+   - What's the single most important element?
+   - What color family (warm/cool/neutral) supports the goal?
+
+2. **Choose Typography Personality**
+   - Select font pairings that match the personality (NOT defaults)
+   - Define scale (3x+ headline ratio)
+   - Set weight extremes (light/heavy contrast)
+
+3. **Commit to Color Strategy**
+   - Pick ONE dominant color (NOT purple, NOT generic blue)
+   - Choose 1 sharp accent
+   - Define warm or cool neutrals
+
+4. **Design Spatial Rhythm**
+   - Use generous white space (3-6rem between sections)
+   - Create asymmetry (not everything centered)
+   - Vary component sizes intentionally
+
+5. **Add Strategic Motion**
+   - Identify 2-3 high-impact animation moments
+   - Use staggered timing for multiple elements
+   - Keep interactions purposeful, not decorative
+
+6. **Layer Atmospheric Depth**
+   - Use gradient combinations for backgrounds
+   - Add subtle patterns or textures
+   - Alternate light/dark sections for rhythm
+
+
+# CONTEXT-AWARE DESIGN PERSONALITIES
+
+Brand personality should influence your choices:
+
+- **Corporate/Professional**: Deep neutrals, serif headlines, structured spacing
+- **Creative/Agency**: Bold color, display fonts, asymmetric layouts
+- **Tech/Startup**: Monospace accents, sharp colors, modern spacing
+- **Elegant/Luxury**: Serif dominance, muted colors with metallic accents, generous white space
+
+# USER OVERRIDE CAPABILITY
+
+Always respect user specifications:
+
+If user specifies:
+- Specific colors → use them
+- Specific fonts → use them
+- Specific spacing → use it
+- "Minimal/simple" → reduce ornamentation but maintain quality principles
+`;

package/src/mcp/resources/widgets-schema-resource.ts

@@ -28,7 +28,13 @@ Prefer using "em" and "rem" values for text-related sizes, padding and spacing.
 This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema.
 
 When applicable for styles, apply style PropValues using the ${ STYLE_SCHEMA_URI }.
-The css string must follow standard CSS syntax, with properties and values separated by semicolons, no selectors, or nesting rules allowed.`,
+The css string must follow standard CSS syntax, with properties and values separated by semicolons, no selectors, or nesting rules allowed.
+
+** CRITICAL - VARIABLES **
+When using global variables, ensure that the variables are defined in the ${ 'elementor://global-variables' } resource.
+Variables from the user context ARE NOT SUPPORTED AND WILL RESOLVE IN ERROR.
+
+`,
 				},
 			],
 		};

package/src/mcp/tools/build-composition/prompt.ts

@@ -1,167 +1,143 @@
 import { toolPrompts } from '@elementor/editor-mcp';
 
-import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
-
 export const generatePrompt = () => {
 	const buildCompositionsToolPrompt = toolPrompts( 'build-compositions' );
 
 	buildCompositionsToolPrompt.description( `
-# REQUIRED RESOURCES (Read before use)
-1. [${ WIDGET_SCHEMA_URI }] - Widget types, configuration schemas, and PropType definitions
-2. [${ STYLE_SCHEMA_URI }] - Common styles schema shared by all widgets
-3. [elementor://global-classes] - Existing global classes (check FIRST to reuse)
-
-# THREE-PHASE WORKFLOW (MANDATORY)
-
-## Phase 1: Create Global Classes
-1. Analyze requirements → identify reusable patterns (typography, colors, spacing)
-2. Check [elementor://global-classes] for existing classes
-3. Use "create-global-class" tool for NEW reusable styles BEFORE building
-
-## Phase 2: Build Composition (THIS TOOL)
-4. Build valid XML with minimal inline styles (layout/positioning only)
-5. Avoid duplicating styles that should be global classes
-
-## Phase 3: Apply Classes
-6. Use "apply-global-class" tool to apply global classes to elements
-
-# CORE INSTRUCTIONS
-
-**Structure:**
-- Build valid XML using allowed widget tags (e.g., \`<e-button configuration-id="btn1"></e-button>\`)
-- Containers only: "e-flexbox", "e-div-block", "e-tabs"
-- Every element MUST have unique "configuration-id" attribute
+# RESOURCES (Read before use)
+- [elementor://global-classes] - Check FIRST for reusable classes
+- [elementor://global-variables] - ONLY use variables defined here
+
+# WORKFLOW
+1. Check/create global classes via "create-global-class" tool
+2. Build composition (THIS TOOL) - minimal inline styles
+3. Apply classes via "apply-global-class" tool
+
+# XML STRUCTURE
+- Use widget tags: \`<e-button configuration-id="btn1"></e-button>\`
+- Containers: "e-flexbox", "e-div-block", "e-tabs"
+- Every element needs unique "configuration-id"
 - No attributes, classes, IDs, or text nodes in XML
 
-**Configuration:**
-- Map each configuration-id to elementConfig (widget props) and stylesConfig (styles)
-- Follow exact PropType schemas from resources above
-- All PropValues need \`$$type\` property matching schema
-- Keep stylesConfig MINIMAL - layout only, NOT reusable styles
-
-**Validation:**
-- Parse XML before submission
-- Match all PropValues to schema (\`$$type\` required)
-- NO LINKS in any configuration
-- Retry on errors up to 10x, reading error messages carefully
-
-# DESIGN QUALITY: AVOID AI SLOP
-
-**Problem:** LLMs default to generic patterns (purple gradients, #333 grays, 24px headings, uniform spacing)
-**Solution:** Make intentional, distinctive choices. When unsure, choose bold over safe.
-
-## Typography Rules
-❌ AVOID: Inter/Roboto/Arial, small ratios (1.5x), medium weights (500-700)
-✅ USE: 3x+ size ratios, extreme weight contrasts (100/200 vs 800/900), tight headlines (1.1 line-height)
-
-## Color Rules
-❌ AVOID: Purple gradients, pure grays (#333/#666/#999), even distribution
-✅ USE: ONE dominant color (60-70%), 1-2 accent colors (10-15%), tinted neutrals (warm/cool grays)
-
-## Spacing Rules
-❌ AVOID: Uniform spacing (all 16px/24px), cramped layouts, centered everything
-✅ USE: Generous spacing (80-120px sections), dramatic variation (12px/48px/96px), asymmetric layouts
-
-## Background Rules
-❌ AVOID: Solid white/gray, single colors
-✅ USE: Layered gradients (2-3 layers), subtle patterns, alternating light/dark sections
-
-## Visual Hierarchy
-1. **Primary** (1 element): Largest, highest contrast, most space
-2. **Secondary** (2-3 elements): 40-60% of primary size
-3. **Tertiary** (rest): Minimal weight, muted
-
-**Contrast techniques:** 3x size differences, 300+ weight differences, color hierarchy (brand → neutral → muted)
-
-# DESIGN CONSTRAINTS (NEVER VIOLATE)
-
-**Typography:**
-- NEVER use Inter, Roboto, Arial, Helvetica as primary display fonts
-- NEVER use font-size ratios < 2.5x between headlines and body
-- NEVER use font-weight 500-700 for headlines (go lighter or heavier)
-
-**Color:**
-- PREFER not to use pure grays - use tinted neutrals (#2d2622, #faf8f6, not #333/#f5f5f5)
-- NEVER distribute colors evenly - commit to ONE dominant
-- NEVER use more than 3 core colors - except for info/alert/badges
-
-**Spacing:**
-- NEVER use uniform spacing
-- NEVER use < 4rem (64px) padding for major sections
-- NEVER center everything
-- PRIORITIZE rem based values over pixel based
-
-**Background:**
-- NEVER use solid #ffffff or #f5f5f5 without texture/gradients
-- ALWAYS layer 2+ gradient/color elements
-
-# WIDGET NOTES
-- Check \`llm_guidance\` property in widget schemas for context
-- Avoid SVG widgets (require content upload tools) - when must, prior to execution ensure assets uploaded
-- Apply style schema to containers for layout control
-
-# PARAMETERS (ALL MANDATORY)
+# CONFIGURATION
+- Map configuration-id → elementConfig (props) + stylesConfig (layout only)
+- All PropValues require \`$$type\` matching schema
+- NO LINKS in configuration
+- Retry on errors up to 10x
+
+Note about configuration ids: These names are visible to the end-user, make sure they make sense, related and relevant.
+
+# DESIGN PHILOSOPHY: CONTEXT-DRIVEN CREATIVITY
+
+**Use the user's context aggressively.** Business type, brand personality, target audience, and purpose should drive every design decision. A law firm needs gravitas; a children's app needs playfulness. Don't default to generic.
+
+## SIZING: DEFAULT IS NO SIZE (CRITICAL)
+
+**DO NOT specify height or width unless you have a specific visual reason.**
+
+Flexbox and CSS already handle sizing automatically:
+- Containers grow to fit their content
+- Flex children distribute space via flex properties, not width/height
+- Text elements size to their content
+
+WHEN TO SPECIFY SIZE:
+- min-height on ROOT section for viewport-spanning hero (use min-height, NOT height)
+- max-width for contained content areas (e.g., max-width: 60rem)
+- Explicit aspect ratios for media containers
+
+NEVER SPECIFY:
+- height on nested containers (causes overflow)
+- width on flex children (use flex-basis or gap instead)
+- 100vh on anything except root-level sections
+- Any size "just to be safe" - if unsure, OMIT IT
+
+vh units are VIEWPORT-relative. Nested 100vh inside 100vh = 200vh overflow.
+
+GOOD: \`<e-flexbox>content naturally sizes</e-flexbox>\`
+BAD: \`<e-flexbox style="height:100vh"><e-div-block style="height:100vh">overflow</e-div-block></e-flexbox>\`
+
+## Layout Variety (Break the Template)
+- AVOID: Full-width 100vh hero → three columns → testimonials → CTA (every AI does this)
+- VARY heights: Use auto-height sections with generous padding (6rem+). Let content breathe
+- VARY widths: Not everything spans full width. Use contained sections (max-width: 960px) mixed with edge-to-edge
+- ASYMMETRIC grids: 2:1, 1:3, offset layouts. Avoid equal column widths
+- Negative space as design element: Large margins create focus and sophistication
+- Break alignment intentionally: Offset headings, overlapping elements, broken grids
+
+## Visual Depth & Effects
+- Layer elements: Overlapping cards, text over images, floating elements
+- Subtle shadows with color tint (not pure black): \`box-shadow: 0 20px 60px rgba(<brand-color-here>, 0.15)\`
+- Gradient overlays on images for text readability
+- Border radius variation: Mix sharp (0) and soft (1rem+) corners purposefully
+- Backdrop blur for glassmorphism where appropriate
+- Micro-interactions via CSS: hover transforms, transitions (0.3s ease)
+
+## Typography with Character
+- Display fonts for headlines (from user's brand or contextually appropriate)
+- Size contrast: 4rem+ headlines vs 1rem body. Make hierarchy unmistakable
+- Letter-spacing: Tight for large headlines (-0.02em), loose for small caps (0.1em)
+- Line-height: Tight for headlines (1.1), generous for body (1.6-1.8)
+- Text decoration: Underlines, highlights, gradient text for emphasis
+
+## Color with Purpose
+- Extract palette from user context (brand colors, industry norms, mood)
+- 60-30-10 rule: dominant, secondary, accent
+- Tinted neutrals over pure grays: warm (#faf8f5, #2d2a26) or cool (#f5f7fa, #1e2430)
+- Color blocking: Large colored sections create visual rhythm
+- Gradient directions: Diagonal (135deg, 225deg) feel more dynamic than vertical
+
+## Spacing Strategy
+- Section padding: 6rem-10rem vertical, creating breathing room
+- Rhythm variation: Tight groups (2rem) with generous gaps between (6rem)
+- Use rem/em exclusively for responsive scaling
+- Generous padding on CTAs: min 1rem 2.5rem
+
+# HARD CONSTRAINTS
+- Variables ONLY from [elementor://global-variables] (others throw errors)
+- Avoid SVG widgets unless assets are pre-uploaded
+- Check \`llm_guidance\` in widget schemas
+
+# PARAMETERS
 - **xmlStructure**: Valid XML with configuration-id attributes
-- **elementConfig**: Record of configuration-id → widget PropValues
-- **stylesConfig**: Record of configuration-id → style PropValues (layout only)
+- **elementConfig**: configuration-id → widget PropValues
+- **stylesConfig**: configuration-id → style PropValues (layout only)
+- **customCSS**: configuration-id → CSS rules (no selectors, semicolon-separated)
   ` );
 
 	buildCompositionsToolPrompt.example( `
-A Heading and a button inside a flexbox
+Section with heading + button (NO explicit heights - content sizes naturally):
 {
-  xmlStructure: "<e-flexbox configuration-id="flex1"><e-heading configuration-id="heading1"></e-heading><e-button configuration-id="button1"></e-button></e-flexbox>"
+  xmlStructure: "<e-flexbox configuration-id="Main Section"><e-heading configuration-id="Section Title"></e-heading><e-button configuration-id="Call to Action"></e-button></e-flexbox>",
   elementConfig: {
-    "flex1": {
-      "tag": {
-        "$$type": "string",
-        "value": "section"
-      },
+    "section1": { "tag": { "$$type": "string", "value": "section" } }
+  },
+  customCSS: {
+    "Section Title": "padding: 6rem 4rem; background: linear-gradient(135deg, #faf8f5 0%, #f0ebe4 100%);"
   },
   stylesConfig: {
-    "heading1": {
-      "font-size": {
-        "$$type": "size",
-        "value": {
-          "size": { "$$type": "number", "value": 24 },
-          "unit": { "$$type": "string", "value": "px" }
-        }
-      },
-      "color": {
-        "$$type": "color",
-        "value": { "$$type": "string", "value": "#333" }
-      }
+    "Section Title": {
+      "font-size": { "$$type": "size", "value": { "size": { "$$type": "number", "value": 3.5 }, "unit": { "$$type": "string", "value": "rem" } } },
+      "color": { "$$type": "color", "value": { "$$type": "string", "value": "#2d2a26" } }
     }
-  },
+  }
 }
+Note: No height/width specified on any element - flexbox handles layout automatically.
 ` );
 
 	buildCompositionsToolPrompt.parameter(
 		'xmlStructure',
-		`**MANDATORY** A valid XML structure representing the composition to be built, using custom elementor tags, styling and configuration PropValues.`
+		`Valid XML structure with custom elementor tags and configuration-id attributes.`
 	);
 
-	buildCompositionsToolPrompt.parameter(
-		'elementConfig',
-		`**MANDATORY** A record mapping configuration IDs to their corresponding configuration objects, defining the PropValues for each element created.`
-	);
+	buildCompositionsToolPrompt.parameter( 'elementConfig', `Record mapping configuration IDs to widget PropValues.` );
 
 	buildCompositionsToolPrompt.parameter(
 		'stylesConfig',
-		`**MANDATORY** A record mapping style PropTypes to their corresponding style configuration objects, defining the PropValues for styles to be applied to elements.`
+		`Record mapping configuration IDs to style PropValues (layout/positioning only).`
 	);
 
 	buildCompositionsToolPrompt.instruction(
-		`You will be provided the XML structure with element IDs. These IDs represent the actual elementor widgets created on the page/post.
-You should use these IDs as reference for further configuration, styling or changing elements later on.`
-	);
-
-	buildCompositionsToolPrompt.instruction(
-		`**CRITICAL WORKFLOW REMINDER**:
-1. FIRST: Create reusable global classes for typography, colors, spacing patterns using "create-global-class" tool
-2. SECOND: Use THIS tool with minimal inline styles (only layout & unique properties)
-3. THIRD: Apply global classes to elements using "apply-global-class" tool
-
-This ensures maximum reusability and consistency across your design system. ALWAYS check [elementor://global-classes] for existing classes before creating new ones.`
+		`Element IDs in the returned XML represent actual widgets. Use these IDs for subsequent styling or configuration changes.`
 	);
 
 	return buildCompositionsToolPrompt.prompt();

package/src/mcp/tools/build-composition/schema.ts

@@ -1,4 +1,4 @@
-import { z } from '@elementor/schema';
+import { zod as z } from '@elementor/editor-mcp';
 
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
@@ -25,6 +25,13 @@ export const inputSchema = {
 			`A record mapping element IDs to their styles configuration objects. Use the actual styles schema from [${ STYLE_SCHEMA_URI }].`
 		)
 		.default( {} ),
+	customCSS: z
+		.record(
+			z.string().describe( 'The configuration id' ),
+			z.string().describe( 'The custom CSS for the element. MANDATORY' )
+		)
+		.describe( 'A record mapping element IDs to their custom CSS.' )
+		.default( {} ),
 };
 
 export const outputSchema = {

package/src/mcp/tools/build-composition/tool.ts

@@ -32,7 +32,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 			hints: [ { name: 'claude-sonnet-4-5' } ],
 		},
 		handler: async ( params ) => {
-			const { xmlStructure, elementConfig, stylesConfig } = params;
+			const { xmlStructure, elementConfig, stylesConfig, customCSS } = params;
 			let generatedXML: string = '';
 			const errors: Error[] = [];
 			const rootContainers: V1Element[] = [];
@@ -44,6 +44,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 				} );
 				compositionBuilder.setElementConfig( elementConfig );
 				compositionBuilder.setStylesConfig( stylesConfig );
+				compositionBuilder.setCustomCSS( customCSS );
 
 				const {
 					configErrors,
@@ -51,6 +52,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 					rootContainers: generatedRootContainers,
 				} = compositionBuilder.build( documentContainer );
 
+				rootContainers.push( ...generatedRootContainers );
 				generatedXML = new XMLSerializer().serializeToString( compositionBuilder.getXML() );
 
 				if ( configErrors.length ) {
@@ -58,8 +60,6 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 					throw new Error( 'Configuration errors occurred during composition building.' );
 				}
 
-				rootContainers.push( ...generatedRootContainers );
-
 				Object.entries( invalidStyles ).forEach( ( [ elementId, rawCssRules ] ) => {
 					const customCss = {
 						value: rawCssRules.join( ';\n' ),
@@ -113,7 +113,7 @@ export const initBuildCompositionsTool = ( reg: MCPRegistryEntry ) => {
 
 				const errorText = `Failed to build composition with the following errors:\n\n${ errorMessages.join(
 					'\n\n'
-				) }\n\n"Missing $$type" errors indicate that the configuration objects are invalid. Try again and apply **ALL** object entries with correct $$type.\nNow that you have these errors, fix them and try again. Errors regarding configuration objects, please check against the PropType schemas`;
+				) }`;
 				throw new Error( errorText );
 			}
 			return {