REACT GUIDELINES

Topic reference files:

• PARTS.md — What qualifies as a named part (mandatory filter)
• DESIGN-STATES.md — Which design states a part supports, and how to author them
• ACCESSIBILITY.md — ARIA/a11y rules and patterns
• DIRECTIONALITY.md — RTL/LTR rules and patterns
• PROPS-VS-CSS.md — What should be a React prop vs CSS
• COMPONENT-API.md — Props structure, elementProps, data types, file splitting, containers, array props
• ANIMATED-COMPONENTS.md — Play/pause control and autoplay for animated/playable components
• REACT-PATTERNS.md — SSR-safe patterns, CSS rules, common mistakes

React 18 features are not supported

The Wix runtime does not currently support React 18 features. Stick to React 17-compatible APIs and avoid libraries that depend on React 18 features.

Part 0: Component Behavior Guide

Understand the component and infer its behavior. Extract what is provided; use reasonable defaults for anything not specified.

1. Identity — Component name.
2. Structure — Elect the root element per PARTS.md Step 0, then identify named inner parts by applying the mandatory filter in PARTS.md to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
3. Interactions — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component’s primary content is a playable animation (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow ANIMATED-COMPONENTS.md.
4. States — For every part, decide which design states it supports (native: hover/focus/disabled/invalid; custom: selected/active/open/… ) by applying the heuristic in DESIGN-STATES.md, and record them in the plan. These become the editor’s per-element state styling controls.

Understanding → implementation (checklist): For every part, decide elementProps vs CSS-only and which design states it supports (DESIGN-STATES.md); build the props interface (data + behavior); wire interaction in React (useState, useEffect, refs, native event handlers); give every named inner element an elementProps entry and spread it + merge its className (COMPONENT-API.md); generate TS + CSS. Infer reasonable defaults where anything is unspecified.

Part 1: Standards & Conventions

These are the mandatory patterns and conventions for all components.

1.1 Mandatory Features

Every component MUST include:

Direction Support (RTL/LTR)

Direction support is mandatory — see DIRECTIONALITY.md.

Accessibility ARIA Support

See ACCESSIBILITY.md for full rules and patterns.

TypeScript

• All components must be fully typed
• NO any types
• Export all prop interfaces
• Use proper React types (React.FC, React.ReactNode, etc.)
• Array type syntax: Use Array<T> instead of T[] (e.g., Array<Item> not Item[])
• Array element types: T must be an object with named keys — Array<{ key: ValueType, ... }> or a named interface that is itself a keyed object. Never Array<string>, Array<number>, Array<boolean>, or Array<DataType> (Image, Link, Video, Audio, VectorArt, RichText, etc.). See COMPONENT-API.md for full rules.
• Component function pattern:
  • Use inline arrow functions with export const
  • Accept props as the argument (do NOT destructure in function signature)
  • Destructure props inside the component body

1.2 Implementation Standards

When to Use elementProps

See COMPONENT-API.md for full elementProps rules and the decision tree.

React & Runtime Standards

All components MUST follow these patterns:

1. SSR-Safe Implementation

• NO browser APIs at module scope (window, document, navigator, etc.)
• Guard browser APIs with typeof checks or useEffect
• All browser-dependent logic must run client-side only

See REACT-PATTERNS.md §1.1 for code examples.

2. Clean Code

• NO TypeScript errors
• NO unused variables or imports
• NO comments in React component files — code should be self-documenting through clear naming
• NO TODO comments in generated code
• Remove ALL comments from the final component — including any comments from templates/examples

3. Data-Driven Components (NO children in exported props)

See COMPONENT-API.md for full rules and patterns.

4. Breakpoint-Responsive Properties (NO props for visual variations)

See PROPS-VS-CSS.md for full rules and patterns.

5. Reactive to Prop Changes

• Components MUST react to prop changes
• If state is derived from props, use useEffect with prop dependencies
• State initialized from props should update when props change

6. Event Handler Scope (Internal by Default)

Unless explicitly specified as a component capability/API in the specification, all event handlers are internal and NOT exposed as props.

Internal handlers (default):

• Used for component behavior (autoplay, animations, state management)
• NOT exposed in the component’s props interface

External handlers (only when specified):

• Only expose handlers that are explicitly listed as component capabilities
• Example: If specification says “onClick callback for external control”, then add onClick?: () => void to props

Child component handlers:

• Internal sub-components receive handlers from parent via props
• These are still internal to the main component

1.3 Implementation Workflow

Step 1: Analyze Component Parts

For each part of the component, decide:

CSS class only if:

• ✅ Purely visual/decorative
• ✅ No data or configuration needed
• ✅ No direction override needed
• ✅ No custom behavior needed

Use elementProps if:

• ✅ Needs data/content
• ✅ Needs direction override
• ✅ Has state or behavior
• ✅ Needs event handlers

For the same part, also decide which design states it supports (native + custom) per DESIGN-STATES.md.

See COMPONENT-API.md and PROPS-VS-CSS.md for the decision trees.

Step 2: Build Props Interface

Combine:

1. Data/content props (from specification)
2. Behavior props (from specification)
3. Mandatory React props (direction, a11y, className, id)
4. elementProps (only for parts that need it)

Step 3: Implement

Follow Part 2 templates with mandatory patterns applied. For each part’s supported design states, author the interactive markup / class toggles and the state CSS per DESIGN-STATES.md.

Part 2: CSS Rules

All CSS authoring rules — root layout, naming, RTL, state styles, transitions, etc. — live in CSS-GUIDELINES.md.

See PROPS-VS-CSS.md and COMPONENT-API.md for the prop vs CSS vs elementProps decision trees.

Part 3: Examples & Reference

3.1 Implementation Checklist

Phase 1: Analysis — Parse information, map component structure and supported design states (see Part 0)

Phase 2: Component File — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data (DESIGN-STATES.md)

Phase 3: Styles — Apply Part 2 SCSS rules, including state styles (DESIGN-STATES.md). If the request uses the words branded, themed, or brand-aware, also apply BRANDED-COMPONENTS.md before writing CSS.