@elementor/editor-canvas 3.35.0-340 → 3.35.0-342

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elementor/editor-canvas",
   "description": "Elementor Editor Canvas",
-  "version": "3.35.0-340",
+  "version": "3.35.0-342",
   "private": false,
   "author": "Elementor Team",
   "homepage": "https://elementor.com/",
@@ -37,23 +37,23 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
-    "@elementor/editor": "3.35.0-340",
-    "@elementor/editor-controls": "3.35.0-340",
-    "@elementor/editor-documents": "3.35.0-340",
-    "@elementor/editor-elements": "3.35.0-340",
-    "@elementor/editor-interactions": "3.35.0-340",
-    "@elementor/editor-notifications": "3.35.0-340",
-    "@elementor/editor-props": "3.35.0-340",
-    "@elementor/editor-responsive": "3.35.0-340",
-    "@elementor/editor-styles": "3.35.0-340",
-    "@elementor/editor-styles-repository": "3.35.0-340",
-    "@elementor/editor-v1-adapters": "3.35.0-340",
-    "@elementor/editor-mcp": "3.35.0-340",
-    "@elementor/schema": "3.35.0-340",
-    "@elementor/twing": "3.35.0-340",
+    "@elementor/editor": "3.35.0-342",
+    "@elementor/editor-controls": "3.35.0-342",
+    "@elementor/editor-documents": "3.35.0-342",
+    "@elementor/editor-elements": "3.35.0-342",
+    "@elementor/editor-interactions": "3.35.0-342",
+    "@elementor/editor-notifications": "3.35.0-342",
+    "@elementor/editor-props": "3.35.0-342",
+    "@elementor/editor-responsive": "3.35.0-342",
+    "@elementor/editor-styles": "3.35.0-342",
+    "@elementor/editor-styles-repository": "3.35.0-342",
+    "@elementor/editor-v1-adapters": "3.35.0-342",
+    "@elementor/editor-mcp": "3.35.0-342",
+    "@elementor/schema": "3.35.0-342",
+    "@elementor/twing": "3.35.0-342",
     "@elementor/ui": "1.36.17",
-    "@elementor/utils": "3.35.0-340",
-    "@elementor/wp-media": "3.35.0-340",
+    "@elementor/utils": "3.35.0-342",
+    "@elementor/wp-media": "3.35.0-342",
     "@floating-ui/react": "^0.27.5",
     "@wordpress/i18n": "^5.13.0"
   },

package/src/index.ts

@@ -1,16 +1,19 @@
+export { BREAKPOINTS_SCHEMA_URI } from './mcp/resources/breakpoints-resource';
+export { STYLE_SCHEMA_URI } from './mcp/resources/widgets-schema-resource';
+
 export { init } from './init';
 
-export { styleTransformersRegistry } from './style-transformers-registry';
-export { settingsTransformersRegistry } from './settings-transformers-registry';
-export { createTransformer } from './transformers/create-transformer';
-export { createTransformersRegistry } from './transformers/create-transformers-registry';
-export { type AnyTransformer } from './transformers/types';
-export { createPropsResolver, type PropsResolver } from './renderers/create-props-resolver';
-export { startDragElementFromPanel, endDragElementFromPanel } from './sync/drag-element-from-panel';
-export { registerElementType } from './legacy/init-legacy-views';
 export {
 	createTemplatedElementView,
 	type CreateTemplatedElementTypeOptions,
 } from './legacy/create-templated-element-type';
-export { getCanvasIframeDocument } from './sync/get-canvas-iframe-document';
+export { registerElementType } from './legacy/init-legacy-views';
 export * from './legacy/types';
+export { createPropsResolver, type PropsResolver } from './renderers/create-props-resolver';
+export { settingsTransformersRegistry } from './settings-transformers-registry';
+export { styleTransformersRegistry } from './style-transformers-registry';
+export { endDragElementFromPanel, startDragElementFromPanel } from './sync/drag-element-from-panel';
+export { getCanvasIframeDocument } from './sync/get-canvas-iframe-document';
+export { createTransformer } from './transformers/create-transformer';
+export { createTransformersRegistry } from './transformers/create-transformers-registry';
+export { type AnyTransformer } from './transformers/types';

package/src/mcp/canvas-mcp.ts

@@ -1,5 +1,6 @@
 import { type MCPRegistryEntry } from '@elementor/editor-mcp';
 
+import { initBreakpointsResource } from './resources/breakpoints-resource';
 import { initWidgetsSchemaResource } from './resources/widgets-schema-resource';
 import { initBuildCompositionsTool } from './tools/build-composition/tool';
 import { initConfigureElementTool } from './tools/configure-element/tool';
@@ -14,4 +15,5 @@ export const initCanvasMcp = ( reg: MCPRegistryEntry ) => {
 	initBuildCompositionsTool( reg );
 	initGetElementConfigTool( reg );
 	initConfigureElementTool( reg );
+	initBreakpointsResource( reg );
 };

package/src/mcp/mcp-description.ts

@@ -1,40 +1,83 @@
 import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from './resources/widgets-schema-resource';
 
-export const mcpDescription = `Canvas MCP - Working with widgets and styles: how to use the PropType schemas and generate PropValue structures
+export const mcpDescription = `Canvas MCP
+This MCP enables everything related to creation, configuration, and styling of elements on the Elementor canvas.
 
-# Elementor's PropValue configuration system
+# Design Systems in Elementor
+- Elementor presents global classes. Each global class is a a set of styles that can be applied to multiple elements. This allows for consistent styling across the design.
+- Elementor also presents global variables, which can be colors, sizes or fonts. These variables can be used in any element's styles, or global classes, allowing for easy updates and consistency across the design.
+- All data is stored in a PropValue structure, which is a wrapper for elementor values. The PropValues are derived from an internal "PropType" schema, which defines the structure and types of the values.
 
-Every widget in Elementor has a set of properties that can be configured, defined in a STRICT SCHEMA we call "PropType".
-All widget configuration values are represented using a structure we call "PropValue".
+# PropValues structure and usage
+\`\`\`json
+{
+  $$type: 'the-prop-type-schema-kind',
+  value: 'the-actual-value-as-defined-for-the-propType'
+}
+\`\`\`
+The "value" property can be an object, string, number, boolean, array, etc. The $$type defines the kind of value, and the value is the actual value.
+It is critical to provide the correct $$type for each value, as it defines how Elementor will interpret the value or reject it.
+
+All widgets properties and configuration is built from sets of PropValues, which can be retreived from the resource [${ WIDGET_SCHEMA_URI }].
+All styles are SHARED ACCROSS widgets, containers and components, and are defined in a common styles schema, retreivable from the resource [${ STYLE_SCHEMA_URI }].
+The style schema also defines the global classes.
+
+To understand the configuration options for an element, refer to the PropType schema for that specific element. For example: "e-heading" configuration schema is available at the resource [${ WIDGET_SCHEMA_URI }/e-heading]
+
+# Modifying elements and styles
+When configuring an element, elementor does a MERGE PROPERTIES operation, which means that only the properties you provide will be updated, and the rest will remain as is.
+For deleting a property, the value must be set to null, instead of a PropValue. When adding a configuration, no need to provide the full configuration, only the properties you want to add or update.
+The same rule applies to styles as well and modifications to global classes.
+
+# Building full compositions
+The "build-composition" tool allows creating multiple elements in a single operation.
+The tool accepts both the structure, the styling and the configuration of each element to be created.
 
-To correctly configure a widget's properties, FOLLOW THE PropType schema defined for that widget. This schema outlines the expected structure and types for each property, ensuring that the values you provide are valid and can be properly interpreted by Elementor.
-Every widget has it's own PropType schema, retreivable from the resource [${ WIDGET_SCHEMA_URI }].
-ALL WIDGETS share a common _styles property with a uniform styles schema, retreivable from the resource [${ STYLE_SCHEMA_URI }].
-The style schema is grouped by categories, such as "typography", "background", "border", etc.
+- First step: Retreive the available widgets by listing the [${ WIDGET_SCHEMA_URI }] dynamic resource.
+- Second step: decide which elements to create, and their configuration and styles.
+  Retrieve the used elements configuration schema from the resource [${ WIDGET_SCHEMA_URI }/element-name]
+- Third step: define the styles for each element, using the common styles schema from the resource [${ STYLE_SCHEMA_URI }]. List the resource to see all available style properties.
+  For background and complicated layered styles, you can use "custom_css" property, which is supported only for ELEMENTOR PRO users ONLY.
+  The custom css is intented to deal with yet unsupported CSS features that ARE NOT PART OF THE STYLE SCHEMA, to enable PRO users to support new CSS features.
 
-# Tools and usage
-- Use the "get-element-configuration-values" tool to retrieve the current configuration of a specific element, including its PropValues and styles. It is recommended to use this tool when you are required to make changes to an existing element, to ensure you have the correct current configuration schema.
-  If a PropValue changes it's type (only on union PropTypes), read the new schema from the resources mentioned above, and adjust the PropValue structure accordingly.
-- Use the "build-composition" tool to create a NEW ELEMENTS in a composition on the page. You can use this tool to also create a new single element.
-- Use the "configure-element" tool to update the configuration of an EXISTING element on the page.
+# Configuring Elements / Adding Style to Elements
+An element configuration can be retrieved using the "get-element-configuration-values" tool.
+Updating an element requires only the UPDATED properties (including in the styles), as Elementor does a MERGE/PATCH operation.
 
-All array types that can receive union types, are typed as mixed array, which means that each item in the array can be of any of the allowed types defined in the PropType schema.
-Example: the "background" can have a background-overlay property, which can contain multiple overlays, such as color, gradient, image, etc. Each item in the array must follow the PropType schema for each overlay type.
-All _style properties are OPTIONAL. When a _style is defined, we MERGE the values with existing styles, so only the properties you define will be changed, and the rest will remain as is.
+<note>
+for PropValue with array as value:
+All array types that can receive union types, are typed as mixed array.
+</note>
 
 # Styling best practices
 Prefer using "em" and "rem" values for text-related sizes, padding and spacing. Use percentages for dynamic sizing relative to parent containers.
 This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema.
 
-Additionaly, some PropTypes have metadata information (meta property) that can help in understaind the PropType usage, such as description or other useful information.
+# Examples:
 
-Example of null values:
-{
-  $$type: 'as-defined-for-propValue',
-  value: null
-}
-
-Example of "image" PropValue structure:
+## e-image PropValue structure:
 {$$type:'image',value:{src:{$$type:'image-src',value:{url:{$$type:'url',value:'https://example.com/image.jpg'}}},size:{$$type:'string',value:'full'}}}
 
+Widgets' sizes MUST be defined using the style schema. Images, for example, have a "size" property, but it DOES NOT AFFECT THE VISUAL size, but rather the image size/resolution to load.
+
+# Working with Global Classes and Variables
+- To get the list of available global classes, use the resource at uri elementor://global-classes
+- To get the list of available global variables, use the resource at uri elementor://global-variables
+- Before creating a global variable or class, refer to the list and see if it already exists.
+- Naming conventions:
+  - Global classes and global variables should have meaningful names that reflect their purpose and usage.
+  - Avoid generic names like "style1" or "classA"; instead, use descriptive names like "primary-button" or "heading-level-1".
+  - Avoid names that reflect colors or values, use only purpose-based names.
+
+# Advanced operations
+You are encouraged to run multiple times multiple tools to achieve the desired result.
+
+An Example scenario of creating fully styled composition:
+1. Get the list of availble widgets using dynamic resource [${ WIDGET_SCHEMA_URI }]
+2. For each element to create, retreive its configuration schema from [${ WIDGET_SCHEMA_URI }/element-name]
+3. Get the list of available global classes using the always up-to-date resource 
+4. Get the list of available global variables using the dynamic resource
+5. Build a composition using the "build-composition" tool, providing the structure, configuration and styles for each element. You may want to style the elements later.
+6. Check you work: as you have the created IDs from the build-composition response, you can retreive each element configuration using the "get-element-configuration-values" tool.
+7. If needed, update styles using the "configure-element" tool, providing only the styles or widget's properties to update.
 `;

package/src/mcp/resources/breakpoints-resource.ts

@@ -0,0 +1,47 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+import { type ExtendedWindow } from '@elementor/editor-responsive';
+import { v1ReadyEvent } from '@elementor/editor-v1-adapters';
+
+export const BREAKPOINTS_SCHEMA_URI = 'elementor://breakpoints/list';
+
+export const initBreakpointsResource = ( reg: MCPRegistryEntry ) => {
+	const { mcpServer } = reg;
+
+	const getBreakpointsList = () => {
+		const { breakpoints } = ( window as unknown as ExtendedWindow ).elementor?.config?.responsive || {};
+		if ( ! breakpoints ) {
+			return [];
+		}
+		return Object.values( breakpoints )
+			.filter( ( bp ) => bp.is_enabled )
+			.map( ( bp ) => {
+				const { direction: constraint, label, value } = bp;
+				return {
+					label,
+					constraint,
+					value,
+				};
+			} );
+	};
+
+	const buildResourceResponse = () => ( {
+		contents: [
+			{
+				uri: BREAKPOINTS_SCHEMA_URI,
+				mimeType: 'application/json',
+				text: JSON.stringify( getBreakpointsList() ),
+			},
+		],
+	} );
+
+	mcpServer.resource( 'breakpoints ', BREAKPOINTS_SCHEMA_URI, () => {
+		return buildResourceResponse();
+	} );
+
+	window.addEventListener( v1ReadyEvent().name, () => {
+		mcpServer.server.sendResourceUpdated( {
+			uri: BREAKPOINTS_SCHEMA_URI,
+			...buildResourceResponse(),
+		} );
+	} );
+};

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

@@ -26,7 +26,7 @@ export const initWidgetsSchemaResource = ( reg: MCPRegistryEntry ) => {
 Prefer using "em" and "rem" values for text-related sizes, padding and spacing. Use percentages for dynamic sizing relative to parent containers.
 This flexboxes are by default "flex" with "stretch" alignment. To ensure proper layout, define the "justify-content" and "align-items" as in the schema, or in custom_css, depends on your needs.
 
-When applicable for styles, use the "custom_css" property for free-form CSS styling. This property accepts a string of CSS rules that will be applied directly to the element.
+When applicable for styles, apply style PropValues using the ${ STYLE_SCHEMA_URI }. Custom css is for Elementor PRO users and intended to support only new CSS features not yet available in the UI.
 The css string must follow standard CSS syntax, with properties and values separated by semicolons, no selectors, or nesting rules allowed.`,
 				},
 			],
@@ -56,7 +56,7 @@ The css string must follow standard CSS syntax, with properties and values separ
 					contents: [
 						{
 							uri: uri.toString(),
-							text: 'Free style inline CSS string of properties and their values. Applicable for a single element, only the properties and values are accepted. Use this as a last resort for properties that are not covered with the schema.',
+							text: 'Free style inline CSS string of properties and their values. Applicable for a single element, only the properties and values are accepted. Use this as a last resort for properties that are not covered with the schema. Do not use selectors, only the CSS content',
 						},
 					],
 				};
@@ -65,12 +65,12 @@ The css string must follow standard CSS syntax, with properties and values separ
 			if ( ! stylesSchema ) {
 				throw new Error( `No styles schema found for category: ${ category }` );
 			}
-			const cleanedupPropSchema = cleanupPropType( stylesSchema );
-			const asJson = Schema.propTypeToJsonSchema( cleanedupPropSchema as PropType );
+			const asJson = Schema.propTypeToJsonSchema( stylesSchema as PropType );
 			return {
 				contents: [
 					{
 						uri: uri.toString(),
+						mimeType: 'application/json',
 						text: JSON.stringify( asJson ),
 					},
 				],
@@ -104,9 +104,8 @@ The css string must follow standard CSS syntax, with properties and values separ
 			if ( ! propSchema ) {
 				throw new Error( `No prop schema found for element type: ${ widgetType }` );
 			}
-			const cleanedupPropSchema = cleanupPropSchema( propSchema );
 			const asJson = Object.fromEntries(
-				Object.entries( cleanedupPropSchema ).map( ( [ key, propType ] ) => [
+				Object.entries( propSchema ).map( ( [ key, propType ] ) => [
 					key,
 					Schema.propTypeToJsonSchema( propType ),
 				] )
@@ -120,7 +119,11 @@ The css string must follow standard CSS syntax, with properties and values separ
 				contents: [
 					{
 						uri: uri.toString(),
-						text: JSON.stringify( asJson ),
+						mimeType: 'application/json',
+						text: JSON.stringify( {
+							type: 'object',
+							properties: asJson,
+						} ),
 					},
 				],
 			};

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

@@ -6,12 +6,6 @@ export const generatePrompt = () => {
 	const buildCompositionsToolPrompt = toolPrompts( 'build-compositions' );
 
 	buildCompositionsToolPrompt.description( `
-Build entire elementor widget comositions representing complex structures of nested elements.
-
-# When to use this tool
-Always prefer this tool when the user requires to build a composition of elements, such as cards, heros, or inspired from other pages or HTML compositions.
-Prefer this tool over any other tool for building HTML structure, unless you are specified to use a different tool.
-
 # **CRITICAL - REQUIRED RESOURCES (Must read before using this tool)**
 1. [${ WIDGET_SCHEMA_URI }]
    Required to understand which widgets are available, and what are their configuration schemas.
@@ -20,6 +14,16 @@ Prefer this tool over any other tool for building HTML structure, unless you are
    Required to understand the styles schema for the widgets. All widgets share the same styles schema.
 3. List of allowed custom tags for building the structure is derived from the list of widgets schema resources.
 
+# 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.
+
+# When to use this tool
+Always prefer this tool when the user requires to build a composition of elements, such as cards, heros, or inspired from other pages or HTML compositions.
+Prefer this tool over any other tool for building HTML structure, unless you are specified to use a different tool.
+
 # Instructions
 1. Understand the user requirements carefully.
 2. Build a valid XML structure using only the allowed custom tags provided. For example, if you
@@ -36,20 +40,185 @@ Prefer this tool over any other tool for building HTML structure, unless you are
    Layout properties, such as margin, padding, align, etc. must be applied using the [${ STYLE_SCHEMA_URI }] PropValues.
 7. Some elements allow nesting of other elements, and most of the DO NOT. The allowed elements that can have nested children are "e-div-block" and "e-flexbox".
 8. Make sure that non-container elements do NOT have any nested elements.
-9. Unsless the user specifically requires structure only, BE EXPRESSIVE AND VISUALLY CREATIVE AS POSSIBLE IN APPLYING STYLE CONFIGURATION.
-   In the case of doubt, prefer adding more styles to make the composition visually appealing.
-
-# Additional Guidelines
-- Most users expect the structure to be well designed and visually appealing.
-- Use layout properties, ensure "white space" design approach is followed, and make sure the composition is visually balanced.
-- Use appropriate spacing, alignment, and sizing to create a harmonious layout.
-- Consider the visual hierarchy of elements to guide the user's attention effectively.
-- You are encouraged to use colors, typography, and other style properties to enhance the visual appeal, as long as they are part of the configuration schema for the elements used.
-- Always aim for a clean and professional look that aligns with modern design principles.
-- When you are required to create placeholder texts, use texts that have a length that fits the goal. When long texts are required, use longer placeholder texts. When the user specifies exact texts, use the exact texts.
-- Image size does not affect the actual size on the screen, only which quality to use. If you use images, specifically add _styles PropValues to define the image sizes.
-- Attempt to use layout, margin, padding, size properties from the styles schema.
-- If your elements library is limited, encourage use of nesting containers to achieve complex layouts.
+9. **CRITICAL - CUSTOM CSS PRIORITY**: Prefer using style schema. Custom CSS is ONLY FOR UNSUPPRTED schema styles.
+   ALWAYS PRIORITIZE using the style schema PropValues for styling elements as they provide better user experience in the editor, and UI features for the end-users.
+   - Use custom_css only for style attributes that ARE NOT SUPPORTED via the style schema.
+
+# 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+)
+
+**Hierarchy Mapping:**
+/* Intentional hierarchy example */
+H1: font-size: 3.5rem; font-weight: 900; line-height: 1.1; letter-spacing: -0.03em;
+H2: font-size: 2rem; font-weight: 200; line-height: 1.2;
+Body: font-size: 1rem; font-weight: 400; line-height: 1.7;
+Caption: font-size: 0.75rem; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase;
+
+## 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)
+
+**Implementation:**
+/* Intentional color system example */
+--brand-primary: #d84315;        /* Dominant: Deep orange */
+--brand-accent: #00bfa5;         /* Accent: Teal (complementary) */
+--neutral-dark: #2d2622;         /* Warm dark brown, not #333 */
+--neutral-light: #faf8f6;        /* Warm off-white, not pure white */
+--background: linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%); /* Subtle warmth */
+
+## 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
+
+**Implementation:**
+/* Intentional spacing scale */
+--space-xs: 0.5rem;   /* 8px */
+--space-sm: 1rem;     /* 16px */
+--space-md: 3rem;     /* 48px */
+--space-lg: 6rem;     /* 96px */
+--space-xl: 10rem;    /* 160px */
+
+/* Use in combinations: */
+padding: var(--space-lg) var(--space-md);  /* Not uniform padding */
+margin-bottom: var(--space-xl);            /* Generous section breaks */
+
+## 4. 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
+
+**Implementation:**
+/* Intentional background example */
+background:
+  radial-gradient(circle at 20% 30%, rgba(216, 67, 21, 0.08) 0%, transparent 50%),
+  radial-gradient(circle at 80% 70%, rgba(0, 191, 165, 0.06) 0%, transparent 50%),
+  linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%);
+
+## 5. 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
+
+## 6. EXAMPLES - Intentional vs. Generic Design
+
+### ❌ GENERIC (Distributional Convergence)
+
+{
+  "xmlStructure": "<e-flexbox configuration-id=\"flex1\"><e-heading configuration-id=\"heading1\"></e-heading><e-button configuration-id=\"button1\"></e-button></e-flexbox>",
+  "elementConfig": {
+    "heading1": {
+      "title": { "$$type": "string", "value": "Welcome to Our Site" }
+    }
+  },
+  "stylesConfig": {
+    "heading1": {
+      "font-size": {
+        "$$type": "size",
+        "value": {
+          "size": { "$$type": "number", "value": 24 },
+          "unit": { "$$type": "string", "value": "px" }
+        }
+      },
+    },
+    "button1": {
+      "custom_css": "background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 12px 24px;"
+    }
+  }
+}
+
+**Why Generic**: 24px default size, #333 safe gray, 600 weight (middle-ground), purple gradient (AI cliché), uniform 12/24px padding
+
+### ✅ INTENTIONAL (Resisting Convergence)
+{
+  "xmlStructure": "<e-flexbox configuration-id=\"hero-section\"><e-heading configuration-id=\"hero-title\"></e-heading><e-text configuration-id=\"hero-subtitle\"></e-text><e-button configuration-id=\"hero-cta\"></e-button></e-flexbox>",
+  "elementConfig": {
+    "hero-title": {
+      "title": { "$$type": "string", "value": "Transform Your Workflow" }
+    },
+    "hero-subtitle": {
+      "content": { "$$type": "string", "value": "Built for teams who refuse to compromise on quality" }
+    }
+  },
+  "stylesConfig": {
+    "hero-section": {
+      "custom_css": "display: flex; flex-direction: column; align-items: flex-start; gap: 3rem; background: radial-gradient(circle at 30% 20%, rgba(216, 67, 21, 0.1) 0%, transparent 60%), linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%); padding: 10rem 3rem;"
+    },
+    "hero-title": {
+      "custom_css": "font-size: 4.5rem; font-weight: 900; line-height: 1.05; letter-spacing: -0.04em; color: #2d2622; max-width: 700px;"
+    },
+    "hero-subtitle": {
+      "custom_css": "font-size: 1.25rem; font-weight: 200; line-height: 1.7; letter-spacing: 0.01em; color: #5a534d; max-width: 600px;"
+    },
+    "hero-cta": {
+      "custom_css": "background: #d84315; color: #ffffff; padding: 1.25rem 3rem; font-size: 1rem; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; border-radius: 2px; box-shadow: 0 4px 16px rgba(216, 67, 21, 0.25); transition: transform 0.15s ease-out, box-shadow 0.15s ease-out;"
+    }
+  }
+}
+
+
+**Why Intentional**:
+- Typography: 4.5rem headline (3.6x body), weight 900 vs 200 contrast, tight leading
+- Color: Warm orange primary (#d84315), warm neutrals (#2d2622, #5a534d) NOT #333/#666
+- Spacing: 10rem vertical padding (generous), 3rem gap, asymmetric alignment
+- Background: Layered gradients with subtle brand color accent
 
 # CONSTRAINTS
 When a tool execution fails, retry up to 10 more times, read the error message carefully, and adjust the XML structure or the configurations accordingly.
@@ -60,6 +229,28 @@ NO LINKS ALLOWED. Never apply links to elements, even if they appear in the Prop
 elementConfig values must align with the widget's PropType schema, available at the resource [${ WIDGET_SCHEMA_URI }].
 stylesConfig values must align with the common styles PropType schema, available at the resource [${ STYLE_SCHEMA_URI }].
 
+# DESIGN QUALITY CONSTRAINTS
+
+**Typography Constraints:**
+- NEVER use Inter, Roboto, Arial, or Helvetica as primary display fonts
+- NEVER use font-size ratios smaller than 2.5x between headlines and body
+- NEVER use font-weight values between 500-700 for headlines (go lighter or heavier)
+
+**Color Constraints:**
+- NEVER use purple gradients or blue-purple color schemes
+- NEVER use pure grays (#333, #666, #999) - use tinted neutrals instead
+- NEVER distribute colors evenly - commit to ONE dominant color
+- NEVER use more than 3 core colors (1 dominant, 1-2 accents)
+
+**Spacing Constraints:**
+- NEVER use uniform spacing across all elements
+- NEVER use section padding less than 4rem (64px) for hero/major sections
+- NEVER center everything - use asymmetric layouts for visual interest
+
+**Background Constraints:**
+- NEVER use solid white (#ffffff) or light gray (#f5f5f5) backgrounds without texture/gradients
+- ALWAYS layer at least 2 gradient or color elements for atmospheric depth
+
 # Parameters
 All parameters are MANDATORY.
 - xmlStructure
@@ -68,6 +259,14 @@ All parameters are MANDATORY.
 
 If unsure about the configuration of a specific property, read the schema resources carefully.
 
+# About our widgets
+Most widgets are self-explanatory by their name. Here is some additional information.
+SVG elements are bound to internal content upload. Avoid usage, unless you have tools to upload SVG content.
+e-div-block - By default is ceneterd aligned and vertically stacked. To modify this, apply style configuration.
+e-flexbox - By default is a flex container with row direction. To modify this, apply style configuration.
+
+When working with containers, do not forget to apply style schema for controlling the layout.
+
 
   ` );
 
@@ -83,6 +282,9 @@ A Heading and a button inside a flexbox
       },
   },
   stylesConfig: {
+    "flex1": {
+      "custom_css": "background: radial-gradient(circle at 20% 30%, rgba(216, 67, 21, 0.08) 0%, transparent 50%), radial-gradient(circle at 80% 70%, rgba(0, 191, 165, 0.06) 0%, transparent 50%), linear-gradient(135deg, #faf8f6 0%, #f0ebe6 100%); display: flex; flex-direction: column; align-items: center; padding: 80px 32px; gap: 48px;"
+    },
     "heading1": {
       "font-size": {
         "$$type": "size",

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

@@ -1,21 +1,24 @@
 import { z } from '@elementor/schema';
 
-import { STYLE_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
 
 export const inputSchema = {
 	xmlStructure: z.string().describe( 'The XML structure representing the composition to be built' ),
 	elementConfig: z
 		.record(
 			z.string().describe( 'The configuration id' ),
-			z.record( z.string().describe( 'property name' ), z.any().describe( 'The PropValue for the property' ) )
+			z.record(
+				z.string().describe( 'property name' ),
+				z.any().describe( `The PropValue for the property, refer to ${ WIDGET_SCHEMA_URI }` )
+			)
 		)
 		.describe( 'A record mapping element IDs to their configuration objects. REQUIRED' ),
 	stylesConfig: z
 		.record(
 			z.string().describe( 'The configuration id' ),
 			z.record(
-				z.string().describe( '_styles property name' ),
-				z.any().describe( 'The PropValue for the style property. MANDATORY' )
+				z.string().describe( 'StyleSchema property name' ),
+				z.any().describe( `The PropValue for the style property. MANDATORY, refer to [${ STYLE_SCHEMA_URI }]` )
 			)
 		)
 		.describe(