Wix Site Component Builder
Creates production-quality React site components with editor manifests for Wix CLI applications. Site components are React components that integrate with the Wix Editor, allowing site owners to customize content, styling, and behavior through a visual interface.
Non-Matching Intents
Do NOT use this skill for:
Dashboard admin interfaces → Use wix-cli-dashboard-page Site widgets with settings panels → Use wix-cli-site-widget Embedded scripts (HTML/JavaScript injection) → Use wix-cli-embedded-script Backend API endpoints → Use wix-cli-backend-api Service plugins (eCommerce SPIs) → Use wix-cli-service-plugin Architecture
Site components consist of four required files:
- Component Manifest (manifest.json)
Defines the contract between the React component and Wix ecosystem:
editorElement: Root element configuration (selector, displayName, archetype, layout) cssProperties: CSS API for styling customization data: Data API for content configuration elements: Nested element definitions for granular editing behaviors: Editor interaction behaviors 2. React Component (component.tsx)
Production-ready React functional component:
Implements props interface matching manifest data structure Applies className and id to root element Handles element removal state via wix.elementsRemovalState Uses sub-component pattern for nested elements Includes proper TypeScript typing and error handling 3. CSS Styles (style.css)
Modern CSS with responsive design:
Synced selectors with manifest and React classNames CSS variables for dynamic styling Responsive design without media queries (flexbox, grid, clamp) Pointer events enabled for editor elements No inline styles for static values Each selector once only, box-sizing: border-box all elements NO transition: all, NO media queries (except prefers-reduced-motion) Root display: Declare --display: [value] CSS variable, then use display: var(--display) on root 4. TypeScript Types (types.ts)
Strict type definitions:
Props interfaces for all components Data type mappings (text → string, image → Image object) Element props structure with optional chaining Wix system types (Wix interface, REMOVED type) Component Manifest Structure
You MUST read MANIFEST_GUIDELINES.md before implementing a site component. It contains the complete manifest structure, all data types, element configurations, and required patterns.
The manifest defines the editor contract using these key sections:
editorElement (Root Configuration) { "selector": ".component-name", "displayName": "Component Name", "archetype": "Container", "layout": { "resizeDirection": "horizontalAndVertical", "contentResizeDirection": "horizontal" }, "cssProperties": { "backgroundColor": { "displayName": "Background Color", "defaultValue": "#ffffff" } }, "data": { "columns": { "dataType": "number", "displayName": "Number of Columns", "number": { "minimum": 1, "maximum": 4 } } }, "elements": { "title": { "elementType": "inlineElement", "inlineElement": { "selector": ".component-name__title", "displayName": "Title", "data": { "titleText": { "dataType": "text", "displayName": "Title Text" } }, "behaviors": { "selectable": true, "removable": true } } } } }
Data Types Reference Type Runtime Value Use Case text string Names, titles, descriptions textEnum string Predefined options number number Quantities, dimensions booleanValue boolean Toggles, flags a11y Object Accessibility attributes link { href, target, rel } Navigation links image { uri, url, alt, width, height } Images video Video object Media content vectorArt Sanitized SVG object Icons, graphics localDate string (YYYY-MM-DD) Date values localTime string (hh:mm) Time values webUrl string External URLs richText string (HTML) Formatted content arrayItems Array Collections, lists direction string HTML dir attribute menuItems Array of menu items Navigation menus CSS Properties Reference
Common CSS properties for styling customization:
Layout: display, gap, padding, margin, width, height Typography: font, fontSize, fontWeight, textAlign, color Background: backgroundColor, backgroundImage Border: border, borderRadius, boxShadow Positioning: alignItems, justifyContent, flexDirection
Complete CSS properties reference: See CSS_GUIDELINES.md for all CSS properties, variable patterns, and styling best practices.
React Component Patterns
Complete reference: See REACT_PATTERNS.md for detailed component architecture, all coding patterns, and implementation examples.
Props Structure interface ComponentProps { // Standard props (always present) className: string; id: string; wix?: Wix;
// Component-level data (from editorElement.data) columns?: number; layout?: string;
// Element props (from elements definitions) elementProps?: { title?: { titleText?: string; wix?: Wix; }; button?: { buttonText?: string; buttonLink?: Link; wix?: Wix; }; }; }
Sub-Component Pattern
Extract every distinct UI element into named sub-components:
// Title sub-component interface TitleProps { titleText?: string; className: string; }
const Title: FC
{titleText}
);
// Main component
const ProductCard: FC
return (
Conditional Rendering
All elements must be conditionally rendered based on removal state:
const removalState = wix?.elementsRemovalState || {};
return (
CSS Guidelines Responsive Design Strategy
Components live in user-resizable containers (300-1200px) within varying viewports:
Root element: width: 100%; height: 100% Layout structure: Use CSS Grid and Flexbox for fluid responsiveness Typography: Use clamp() for fluid scaling Spacing: Fixed or tight clamp spacing (≤50% variation) CSS Variables for Dynamic Styling .component { --display: block; --background-color: #ffffff; --text-color: #333333;
display: var(--display); background-color: var(--background-color); color: var(--text-color); pointer-events: auto; }
Selector Synchronization
CRITICAL: CSS selectors must match manifest selectors and React classNames exactly:
React: className="product-card__title" CSS: .product-card__title { ... } Manifest: "selector": ".product-card__title" Design Guidelines
Complete reference: See DESIGN_SYSTEM.md for visual design principles, creative guidelines, and aesthetic best practices.
Spacing as Communication Relationship Value Use Case Tight (icon + label) 0.25-0.5rem (4-8px) Clustering related items Same category 1-1.5rem (16-24px) Card sections, form fields Different sections 2-3rem (32-48px) Major content blocks Emphasis/Drama 4rem+ (64px+) Hero content, luxury feel Visual Consistency Corner Radius: All similar elements share same radius (0-4px sharp, 6-12px rounded) Shadow Levels: Max 3 levels (rest, hover, floating) Element Heights: Consistent heights for similar elements Color Strategy: Use full palette purposefully for hierarchy and zones Creative Exploration
Push beyond obvious solutions:
Cards: Asymmetric grids, overlapping elements, thick accent borders Lists: Alternating styles, spotlight patterns, color rhythm Interactive Elements: Split buttons, colored icon circles, smooth transitions Content Hierarchy: Large numbers for stats, quote callouts, whitespace dividers Component Elements Guidelines One Element = One Manifest Entry
Each distinct visual part requires a separate manifest element:
✅ 3 buttons → 3 separate elements ✅ Image + text → 2 separate elements ❌ Multiple items grouped as one element Data Scoping Rules
editorElement.data - Component-wide configuration only:
✅ Layout enums, numbers (columns: 3, speed: 500) ❌ Text, links, images (belongs to elements) ❌ show/hide booleans (use removable: true instead)
elements[key].data - Content for that specific element:
✅ Element-specific content (title text, button link, image) Asset Requirements
When components need default images, use this format:
// Import in component import { heroImage } from './assets/defaultImages';
// Usage
Asset specification format:
Rules:
Import as named export from './assets/defaultImages' Width/height: multiples of 64, between 128-2048px NEVER use external URLs Output Structure src/site/components/ └── {component-name}/ ├── manifest.json # Component manifest ├── component.tsx # React component ├── style.css # CSS styles ├── types.ts # TypeScript types └── assets/ # Optional assets └── defaultImages.ts
Examples
Complete working example: See EXAMPLE.md for a full production-ready site component with all patterns, including manifest, React component, CSS, and types.
Product Card Component
Request: "Create a product card component with image, title, price, and buy button"
Output:
Manifest with 4 elements (image, title, price, button) React component with sub-components for each element CSS with responsive grid layout and hover effects TypeScript types for all props and data structures Hero Section Component
Request: "Build a hero section with background image, headline, subtitle, and CTA button"
Output:
Manifest with background image CSS property and 3 text elements React component with overlay design and typography hierarchy CSS with responsive text scaling and dramatic spacing Asset specifications for default hero images Feature List Component
Request: "Create a features component with configurable number of items"
Output:
Manifest with arrayItems data type for feature collection React component mapping over features array with safety checks CSS with flexible grid layout adapting to item count Sub-components for feature icons, titles, and descriptions Extension Registration
Extension registration is MANDATORY and has TWO required steps.
Step 1: Create Component-Specific Extension File
Each site component requires an extensions.ts file in its folder:
import { extensions } from "@wix/astro/builders"; import manifest from "./site/components/my-component/manifest.json";
export const sitecomponentMyComponent = extensions.siteComponent({ ...manifest, id: "{{GENERATE_UUID}}", description: "My Component", type: "platform.builder.{{GENERATE_UUID}}", resources: { client: { component: "./site/components/my-component/component.tsx", componentUrl: "./site/components/my-component/component.tsx", }, }, });
Note: The id and type should use the same UUID.
CRITICAL: UUID Generation
The id must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use randomUUID() or copy UUIDs from examples.
Step 2: Register in Main Extensions File
CRITICAL: After creating the component-specific extension file, you MUST read ../../skills/references/EXTENSIONS.md and follow the "App Registration" section to update src/extensions.ts.
Without completing Step 2, the site component will not be available in the Wix Editor.
Code Quality Requirements
Complete reference: See TYPESCRIPT_QUALITY.md for comprehensive type safety guidelines and code quality standards.
TypeScript Standards Strict TypeScript with no any types Explicit return types for all functions Proper null/undefined handling with optional chaining No @ts-ignore or @ts-expect-error comments React Best Practices Functional components with hooks Proper dependency arrays in useEffect Component must react to prop changes SSR-safe code (no browser APIs at module scope) ESLint Compliance No unused vars/params/imports (@typescript-eslint/no-unused-vars) No external images: img src not https://... (allowed: local imports, wixstatic.com, variables) SSR-safe: No window/document at module scope/constructor, guard browser APIs in useEffect/handlers No dangerouslySetInnerHTML or inline