@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-app/references/editor-react-component/A11Y-REVIEW.md

@@ -1,143 +0,0 @@
-# Editor React Component A11y Review
-
-Use this reference to audit and fix accessibility issues in an Editor React Component. This complements [`ACCESSIBILITY.md`](ACCESSIBILITY.md), which covers ARIA prop conventions and patterns, with an automated scan and triage workflow over the component's runtime, manifest extension, and shared code.
-
-This is not a separate skill. It runs as part of the Editor React Component workflow described in [`../EDITOR_REACT_COMPONENT.md`](../EDITOR_REACT_COMPONENT.md). Run it after editing the React/CSS sources and before `npx wix build && npx wix generate manifest`.
-
-## Scanner Invocation
-
-Two scanners are bundled under `<SKILL_ROOT>/scripts`, where `<SKILL_ROOT>` is
-the absolute path to the directory containing the active skill's `SKILL.md`:
-
-```bash
-node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...
-node <SKILL_ROOT>/scripts/scan-a11y-code.cjs  <file1> [file2] ...
-```
-
-Replace `<SKILL_ROOT>` with that absolute path, but run the commands from the
-consumer project root (the Wix CLI app's working directory) so dependencies
-resolve from the project's `package.json`. Pass target paths relative to that
-cwd. The dependency preflight is part of the workflow in
-[`../EDITOR_REACT_COMPONENT.md`](../EDITOR_REACT_COMPONENT.md).
-
-The ESLint scanner uses the explicitly declared `eslint-plugin-jsx-a11y` dev dependency. The semantic scanner follows imports up to four levels deep and adds resolution evidence and confidence to its findings.
-
-## When To Run
-
-Run the review when:
-
-- You finished editing an Editor React Component's `.tsx` / `.module.css` files.
-- The user asks for an a11y audit, accessibility review, or a11y fix on an Editor React Component.
-- The user mentions missing alt text, invalid ARIA, broken semantics, direction issues, icon-only controls, or wrappers that hide accessibility issues.
-
-Do not run on generated files (`*.generated.ts`); they are regenerated from JSX and CSS Modules.
-
-## Target Resolution
-
-Resolve scope before scanning:
-
-| User says | Required scope |
-|-----------|----------------|
-| Specific file | That file plus any imported wrappers / shared components it renders |
-| "this component" | `<componentName>.tsx`, `component.tsx`, `<componentName>.extension.ts`, plus shared imports |
-| A component name | All in-component files (excluding `*.generated.ts`) |
-| "full audit" | Every Editor React Component folder under `src/extensions/site/components/`, excluding `*.generated.ts` |
-
-## Workflow
-
-Execute every phase inline while editing. Do not pause for approval or add a separate summary phase.
-
-### Phase 1: Resolve Topology
-
-1. Enumerate in-scope files under `src/extensions/site/components/<componentName>/`.
-2. Include imported shared components or utilities that affect rendered semantics.
-3. Exclude `*.generated.ts`.
-4. Trace the topology from the component through wrappers and shared primitives to the rendered element.
-
-### Phase 2a: ESLint JSX A11y Scan (Tier 0)
-
-```bash
-node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...
-```
-
-Use each finding's rule ID, message, and location as the rule-specific context. Validate the finding against the component implementation before editing.
-
-### Phase 2b: Semantic Scan (Tier 1)
-
-```bash
-node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...
-```
-
-Use the emitted resolution path, evidence, and confidence to trace each finding. The scanner output is the source of rule-specific details; the reference only defines how to evaluate and act on those details.
-
-Neither scanner validates manifest contracts or all Editor React Component patterns. Complete Phase 3 even when both scanners return zero findings.
-
-### Deduplication and Triage
-
-Evaluate every finding before fixing it.
-
-**Deduplicate.** When both scanners flag the same location for the same issue, keep the finding with richer evidence. Prefer the semantic scanner when it resolved the component topology; prefer ESLint when the issue is outside the semantic scanner's scope.
-
-| Verdict | Meaning | Action |
-|---------|---------|--------|
-| `confirmed` | The violation is real | Fix it |
-| `false-positive` | The rule fires but the rendered behavior is correct | Discard it |
-| `not-relevant` | The rule does not apply to this architecture | Discard it |
-
-Use this order to evaluate a finding:
-
-1. Trace the component implementation and confirm that the flagged behavior reaches the rendered element.
-2. Check delegated semantics. Editor React Components route ARIA through the typed `a11y` prop and `convertA11yKeysToHtmlFormat(a11y)` (see [`ACCESSIBILITY.md`](ACCESSIBILITY.md)). If the attributes reach the correct element through a runtime path the scanner cannot see, discard the finding as a false positive.
-3. Check conditional interactivity. When `onClick` is spread conditionally with `role`, `tabIndex`, and `onKeyDown`, discard the finding as a false positive. If only `onClick` is conditional, confirm it.
-4. Apply the semantic checks in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
-5. When uncertain, continue tracing the implementation. Default to `confirmed` only after checking the available code and evidence.
-
-Only confirmed findings proceed to edits.
-
-### Phase 3: Editor React Component Semantic Review
-
-Perform a manual semantic review even when scanners return zero findings.
-
-- All ARIA attributes come through the typed `a11y?: A11y` prop, never individual `ariaLabel?: string`, `role?: string`, and similar props. See [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
-- `a11y` is forwarded to the root via `{...(a11y && convertA11yKeysToHtmlFormat(a11y))}`, or to an inner element via `elementProps.<name>.a11y` when requirements specify.
-- Icon-only interactive elements (icon/emoji/image/svg with no text node) have an accessible name from `constants.ts` or user-configurable `a11y`, never a hardcoded string literal.
-- Direction support is mandatory: props include `direction?: Direction`, the root applies `dir={direction}` and the unconditional `fallbackDirection` class, and CSS defines `.fallbackDirection:not([dir])`. See [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
-- Every `ReactNode` content prop is rendered inside an element with `dir="ltr"` so user-provided nested content does not inherit the component direction.
-- `<componentName>.extension.ts` overrides do not strip a11y-relevant manifest fields generated from the JSX.
-- Decorative-only output is hidden with `aria-hidden` when appropriate.
-- Heading/tag selection, when configurable, reaches the rendered semantic element.
-- Interactive-looking elements expose the required keyboard behavior and roles.
-
-Use the full Tier 2 checklist in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
-
-### Phase 4: Fix
-
-Apply fixes only to findings that survived triage:
-
-- `high`: fix immediately
-- `medium`: read the surrounding code, confirm, then fix
-- `low`: resolve the semantics from code and evidence; fix only when confirmed
-
-Confirmed safe/local fixes must be applied. Leave code unchanged only when the semantics remain ambiguous or the fix requires a risky, non-local behavior change. See [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#confidence-model).
-
-Fix principles:
-
-- Preserve intended visual and runtime behavior.
-- Fix the real semantic owner: component root, inner element via `elementProps`, or shared base.
-- Follow established Editor React Component patterns: route ARIA through `a11y`, use `constants.ts` for required labels, and never hardcode string literals.
-- Before adding `role`, `tabIndex`, or keyboard handlers to a non-interactive element, run the [pre-fix checks](A11Y-REVIEW-REFERENCE.md#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
-
-### Phase 5: Verify
-
-If any `.tsx` / `.jsx` file was edited:
-
-1. Re-run both scanners on the modified files.
-2. Run `npx wix build && npx wix generate manifest` so the manifest reflects any JSX changes.
-3. Run the project's TypeScript check (`npx tsc --noEmit`), which is already part of the wix-app validation flow.
-
-Verification is mandatory after edits. Continue directly from fixes to verification, and do not consider the workflow complete while a required check remains unrun.
-
-## References
-
-- [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md) - triage, confidence, semantic resolution, Tier 2 checks, and pre-fix safeguards
-- [`ACCESSIBILITY.md`](ACCESSIBILITY.md) - ARIA conventions for Editor React Components

package/skills/wix-app/references/editor-react-component/COMPONENT-API.md

@@ -1,516 +0,0 @@
-# Component API
-
-Rules and patterns for props structure, elementProps, data types, file structure, containers, data-driven components, and array props.
-
----
-
-## Should This Use elementProps or CSS?
-
-```
-Is this element a named part (carries a global class string)?
-│
-├─ YES
-│   └─ ✅ It gets an elementProps entry — spread it + merge its className.
-│         Add config fields inside the entry only as needed
-│         (data, direction, event handlers).
-│
-└─ NO → purely visual/decorative non-part
-        (icons, separators, decorations, layout wrappers,
-         elements only hidden/shown via CSS)
-    └─ ❌ CSS class only — no elementProps entry
-```
-
----
-
-## Rules
-
-### Component Props Structure
-
-```typescript
-interface ComponentProps {
-  // Identity
-  id?: string;
-  className?: string;
-
-  // Mandatory features (from @wix/editor-react-types)
-  direction?: Direction;
-  a11y?: A11y; // ALL ARIA attributes come through this (ariaLabel, role, etc.)
-
-  // Component-specific props (NO children unless container-type - see container rules below)
-  label?: string;
-  items?: Array<ItemType>;
-  // ... from specification
-  // NEVER add: ariaLabel, ariaDescribedBy, role, etc. - use a11y prop instead
-
-  // Sub-component configuration (only if needed - see elementProps rules)
-  elementProps?: {
-    [partName]?: {
-      [configProp]?: string | boolean | number; // Only include if element needs config beyond className
-      direction?: Direction;
-    };
-  };
-}
-```
-
-### Propagate `elementProps` to inner elements
-
-`elementProps` is a map keyed by the manifest's inner-element keys; each entry
-carries that element's `className` (the editor sets it — this is how design
-states reach the element) plus any data.
-
-**Every named inner element — every element that carries a global class
-string — gets an `elementProps` entry, and you spread that entry onto the
-element.** This is mandatory, even when the element needs no other config:
-without it the editor cannot style that element or drive its states.
-
-How `className` gets merged depends on what the element is:
-
-- **Raw HTML element** (`<button>`, `<li>`, `<div>`): merge
-  `elementProps?.<key>.className` inline, alongside the global string and module
-  class — there's no component to do it.
-- **Sub-component built with this skill** (`<Inner/>`): the spread alone is
-  enough. `className` rides along inside it, and the sub-component merges it onto
-  its own root (every skill component merges its incoming `className`). Don't
-  merge it again at the call site.
-
-```tsx
-interface PlanCardProps {
-  className?: string;
-  elementProps?: {
-    cta?: { className?: string; href?: string };
-  };
-}
-
-// Raw HTML element — spread + merge className inline.
-// Note: the elementProps key is the short part name (`cta`), while the global
-// class is prefixed with the component name (`plan-card-cta`). Keep them as-is.
-<button {...elementProps?.cta} className={classNames('plan-card-cta', styles.cta, elementProps?.cta?.className)}>
-  {label}
-</button>
-
-// Sub-component built with this skill — spread is enough (it merges className itself):
-<PlanRow {...elementProps?.planRow} />
-```
-
-**Non-parts** (module-class-only elements: icons, decorations, separators,
-layout wrappers — no global class) get no entry. Style them with CSS.
-
-**Inside each entry**, add only the config the element needs (data, direction,
-event handlers). Never add a bare `className?` as the *only* field to decide
-whether an element qualifies — `className` always flows through; the entry
-exists because the element is a named part.
-
-### What Qualifies as a Part
-
-See [`PARTS.md`](PARTS.md) for root election (Step 0), the mandatory filter, and full rules. The root gets no `elementProps` entry — its `className`, `a11y`, and `direction` arrive as top-level props.
-
-### Derived values are not props
-
-If a displayed value can be computed with a simple pure function from
-other props and/or internal state, compute it internally — don't
-expose it as a prop. Expose only the source inputs (use numeric types
-when arithmetic is needed: `price: number`, not `price: string`).
-
-**Example:** subtotal = `price × quantity` → computed inside the component, not a prop.
-
-### Data-Driven Components (NO children in exported props)
-
-- Component's **exported interface** must NOT accept `children` prop
-- ALL content MUST come through explicit named props (see "Derived values" above for what stays internal):
-  - Text (labels, placeholders, messages) → `label`, `text`, `placeholder`, etc.
-  - Media (images, videos, icons) → `imageSrc`, `videoUrl`, `iconName`, etc.
-  - Links (URLs, hrefs) → `link`, `href`, `url`, etc.
-  - Collections (list items, options, menu items) → `items`, `options`, `menuItems`, etc.
-- **Internal implementation** can use children for composition between sub-components
-- Hardcoded values are ONLY for fallback defaults when props are undefined
-
-**Exception — Container-type components:** Components whose purpose is to wrap arbitrary child elements (e.g., BoxContainer) MAY accept `children: React.ReactNode`. This applies only to structural containers — data-driven leaf components (Button, Tabs, Accordion, etc.) must NOT use `children`.
-
-### Array Props: Data on Parent Only
-
-When the parent component defines an array prop (e.g., `items`), child/item components receive a single item directly. They do NOT redeclare the data structure in their own props.
-
-### Active-item components (one body visible at a time)
-
-Apply when the UI shows **one array item body at a time** (tabs, slideshow,
-steps). Skip for always-visible lists, multi-select, or multi-expand accordion.
-
-- Each item needs **`name: string`** — Studio hat labels (not `label` or other keys).
-- Pair the array with **`ActiveItemIndex<'arrayPropName'>`** from
-  `@wix/react-component-utils`; the type param must match the array prop name.
-  Default the index to `0` in `defaultProps`.
-- Render **all** item bodies (`.map`); toggle visibility with `--active` +
-  `display: none` on inactive panels (functional visibility — see
-  [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)), plus `aria-hidden` and `inert` on
-  inactive bodies.
-- Keyboard navigation between triggers; ARIA roles per
-  [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
-
-```typescript
-import type { ActiveItemIndex } from '@wix/react-component-utils';
-
-export type ItemType = { name: string; body: string };
-
-export type MyComponentProps = {
-  items: Array<ItemType>;
-  activeItem: ActiveItemIndex<'items'>;
-};
-
-export const defaultProps = {
-  items: [{ name: 'Item 1', body: '…' }],
-  activeItem: 0,
-} satisfies Omit<MyComponentProps, 'id' | 'className'>;
-```
-
-### Array Element Types: Always Objects with Named Keys
-
-Array elements MUST be objects with named keys. This enables stable item identity (each item can carry its own `id`/`key`), non-breaking extension (new fields can be added later without changing the prop signature), and semantic naming (each value has meaning instead of being an opaque scalar).
-
-**Allowed forms:**
-
-- Inline object literal: `Array<{ key: ValueType, ... }>`
-- Named interface where the interface itself is an object with named keys (e.g. `Array<AccordionItem>` is OK because `AccordionItem` is `{ name, content }`)
-
-**Never allowed as the array element:**
-
-- Primitives: `Array<string>`, `Array<number>`, `Array<boolean>`
-- Leaf data types from `@wix/editor-react-types`: `Array<Image>`, `Array<Link>`, `Array<Video>`, `Array<Audio>`, `Array<VectorArt>`, `Array<RichText>`. Wrap them in an object instead.
-- Nested arrays:  `Array<Array<{cover: image, caption: string}>>` `Array<{items: Array<image>, caption: string}>`
-
-**❌ Wrong:**
-
-```typescript
-tags: Array<string>;
-prices: Array<number>;
-flags: Array<boolean>;
-images: Array<Image>;
-links: Array<Link>;
-nestedArrays: Array<Array<any>>
-```
-
-**✅ Correct:**
-
-```typescript
-tags: Array<{ label: string }>;
-prices: Array<{ amount: number }>;
-flags: Array<{ enabled: boolean }>;
-gallery: Array<{ image: Image, caption?: string }>;
-links: Array<{ link: Link, label: string }>;
-items: Array<AccordionItem>; // AccordionItem is { name, content }
-```
-
-### Container Components (Blackbox Content)
-
-When a component specification indicates a "container" or "slot" area where users can add nested content, use `React.ReactNode` for that content prop.
-
-**When to use `React.ReactNode` for a content prop:**
-
-- The specification describes a "container" or "content area"
-- Users should be able to add arbitrary nested components
-- The component doesn't control what goes inside that area
-
-**RTL Support:** Elements that render `React.ReactNode` content MUST have `dir="ltr"` to prevent RTL inheritance from the parent component. See [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
-
-### Component Data Types
-
-When creating TypeScript interfaces for component props, use types from `@wix/editor-react-types` for more complex types, to see the allowed type from this library, look at the following file `node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts`:
-
-```typescript
-import type { Link } from "@wix/editor-react-types"; // Reference at node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts
-```
-
-For **function event handler props** (`onClick`, `onDblClick`, `onChange`, `onFocus`, `onBlur`, `onMouseIn`, `onMouseOut`) and custom callbacks, follow [`FUNCTION-HANDLERS.md`](FUNCTION-HANDLERS.md). Key rules:
-
-- Use the exact SDK prop names from that file — the manifest system recognizes them
-- Wire them to the correct DOM events (note: `onDblClick` → `onDoubleClick`, `onMouseIn` → `onMouseEnter`, `onMouseOut` → `onMouseLeave`)
-- Custom callbacks not tied to DOM events use `() => void` (no React event parameter)
-
-### External resources are forbidden
-
-All resources rendered or fetched by the component (images, icons, fonts,
-videos, audio, JSON data, etc.) MUST come from Wix services. Never reference
-or call external (non-Wix) hosts — no `unsplash.com`, `placehold.co`,
-`picsum.photos`, third-party CDN icon sets, or any custom backend the user
-hasn't asked for. This rule covers both `src`/`href` attributes and any
-runtime fetching.
-
-Allowed image hosts: `static.wixstatic.com` (and other `*.wixstatic.com`
-subdomains). Allowed data: values supplied through props (populated by the
-editor) or imported local assets bundled with the component.
-
-### Default values for `Image` props
-
-Image defaults belong in the `<componentName>.props.ts` file's exported
-`defaultProps` constant (consumed by `withDefaults(Component, defaultProps)` in
-`component.tsx`). Use a Wix-hosted image from the Free-from-Wix public
-media catalog and populate **only** `uri`, `url`, and `alt` — leave
-`width`, `height`, `focalPoint`, etc. unset so the editor fills them when
-the user picks a real image.
-
-By default, use the canonical fallback URL from the examples below for
-every `Image` default (`url` and `uri` derived from the same `fileName`).
-**Only when the user explicitly asks for different/better default images**,
-fetch candidates from the Wix Free-from-Wix catalog:
-
-```
-GET https://publicmedia.wix.com/public/light_items?guid=bca5cb9f-45d2-4b11-8d6c-c9a7e7bd2873%3Aglobal%3Awix&pageSize=20&pageNumber=1&language=en&tags=free&mediaType=picture
-```
-
-The endpoint is unauthenticated. Pick an item whose `displayTags` /
-`title` fit the component's purpose, then build the `Image` default from
-its `fileName`:
-
-- `url` → `` `https://static.wixstatic.com/media/${fileName}` ``
-- `uri` → `fileName`
-- `alt` → a short human description (use the item's `title` or
-  `displayTags`)
-
-Do not call this endpoint when the user hasn't asked for it — the
-canonical fallback URL is fine for unattended scaffolds.
-
-**Default image pool — use a different image for each slot:**
-
-| # | fileName | Description |
-|---|----------|-------------|
-| 1 | `11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg` | Tropical beach aerial |
-| 2 | `11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg` | Dead Sea landscape |
-| 3 | `11062b_3682ebfcb08e4da5b3168b62819a1e68~mv2.jpg` | Palm tree sunset |
-| 4 | `11062b_45e67783d39c4963ab9e4fc418173233~mv2.jpg` | Abstract pink waves |
-| 5 | `11062b_4c11f014b0d04948b2e6f554076bc40a~mv2.jpg` | Coastal village aerial |
-
-When a component needs **more than one** image default, cycle through
-the pool above so every slot gets a visually distinct image. For a
-single image, use image #1.
-
-**Single `Image` prop:**
-
-```typescript
-export const defaultProps = {
-  image: {
-    url: "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-    uri: "11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-    alt: "Default image",
-  },
-} as const satisfies Omit<ExampleComponentProps, "id" | "className">;
-```
-
-**Array of objects with an `Image` field:**
-
-```typescript
-export const defaultProps = {
-  cards: [
-    {
-      title: "First card",
-      image: {
-        url: "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-        uri: "11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg",
-        alt: "First card image",
-      },
-    },
-    {
-      title: "Second card",
-      image: {
-        url: "https://static.wixstatic.com/media/11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg",
-        uri: "11062b_73f31c7e7d3544c69dc8ecd8d34c5717~mv2.jpg",
-        alt: "Second card image",
-      },
-    },
-  ],
-} as const satisfies Omit<ExampleComponentProps, "id" | "className">;
-```
-
-**Inline fallback for HTML `src` / `href`:** when rendering a raw HTML
-attribute that takes a URL (`<img src>`, `<source src>`, `<video poster>`,
-`<a href>` for an image link, etc.) and the value could be empty, fall
-back to the same Wix-hosted URL — never to an external host or a relative
-path that doesn't exist:
-
-```tsx
-<img
-  src={
-    image?.url ||
-    "https://static.wixstatic.com/media/11062b_2f97b87dcea2446fa48e9ad9c5457ae1~mv2.jpg"
-  }
-  alt={image?.alt || "Default image"}
-/>
-```
-
-### Component File Splitting
-
-Split logical UI pieces into separate named components. Never write inline JSX blocks for distinct complex UI pieces.
-
-**File structure for complex components (many subcomponents):**
-
-```
-ComponentName/
-├── components/                 # Subcomponents folder
-│   ├── SubComponent1/
-│   │   ├── SubComponent1.tsx
-│   │   ├── SubComponent1.module.scss
-│   │   └── index.ts
-│   └── SubComponent2/
-│       ├── SubComponent2.tsx
-│       └── index.ts
-├── hooks/                      # Custom hooks folder
-│   ├── index.ts
-│   └── useCustomHook.ts
-```
-
-**When to extract a sub-component:**
-
-- JSX block represents a logical complex unit (button, control, section, item)
-- Component has its own props interface
-- Logic is reusable or testable independently
-- Block has more than 15-20 lines of JSX
-
----
-
-## Patterns
-
-### Data-Driven Pattern
-
-**❌ Wrong:**
-
-```typescript
-export interface ButtonProps {
-  children: React.ReactNode;  // ❌
-}
-<Button>Click Me</Button>
-```
-
-**✅ Correct:**
-
-```typescript
-export interface ButtonProps {
-  label?: string;
-  icon?: string;
-}
-<Button label={label} icon={icon} />
-```
-
-Component controls rendering internally:
-
-```typescript
-const List = ({ items }) => (
-  <div>
-    {items.map(item => (
-      <ListItem key={item.id}>{item.label}</ListItem>
-    ))}
-  </div>
-);
-```
-
-### Array Props Pattern
-
-Parent defines array structure, child receives single item:
-
-```typescript
-// Parent
-interface ParentProps {
-  items: Array<AccordionItem>;  // Array defined here
-}
-
-interface AccordionItem {
-  name: string;
-  content: React.ReactNode;
-}
-
-// Child receives single item
-interface ChildProps {
-  item: AccordionItem & { id: string };  // Single item
-  isOpen?: boolean;
-}
-
-// Parent maps
-items.map((item, index) => (
-  <Child key={index} item={{ ...item, id: index.toString() }} />
-))
-```
-
-### Container Components Pattern
-
-For "container" or "slot" areas, use `React.ReactNode`:
-
-```typescript
-interface AccordionItem {
-  name: string;
-  content: React.ReactNode;  // Users add any content here
-}
-
-// Render
-{items.map((item, index) => (
-  <div key={index} dir="ltr">
-    {typeof item.content === 'function' ? item.content({}) : item.content}
-  </div>
-))}
-```
-
----
-
-## Common Mistakes
-
-### Using children prop in exported interface
-
-**❌ Wrong:**
-
-```typescript
-export interface CardProps {
-  children: React.ReactNode;  // ❌ children + React.ReactNode both forbidden
-}
-<Card><CardHeader>Title</CardHeader></Card>
-```
-
-**✅ Correct:**
-
-```typescript
-export interface CardProps {
-  title: string;
-  content: React.ReactNode;
-}
-<Card title="Title" content={<div>Content</div>} />
-```
-
-### Adding elementProps for CSS-only elements
-
-**❌ Wrong:**
-
-```typescript
-elementProps?: {
-  icon?: { className?: string; }  // ❌ Only className
-  separator?: { className?: string; }  // ❌ Only className
-}
-```
-
-**✅ Correct:**
-
-```typescript
-// No elementProps for purely visual elements (including conditionally displayed)
-// Style via CSS classes directly
-```
-
-**Why:** Don't declare a `className?:` field — `className` already flows through each named inner element's `elementProps` entry (see "Propagate `elementProps` to inner elements"). Conditional display is controlled via CSS, not React props.
-
-### Using T[] array syntax
-
-Use `Array<T>` over `T[]`.
-
-**❌ Wrong:**
-
-```typescript
-interface ComponentProps {
-  items: Item[]; // ❌ Wrong syntax
-  tags: string[]; // ❌ Wrong syntax
-  tags: Array<string>; // ❌ Element must be an object with named keys
-}
-```
-
-**✅ Correct:**
-
-```typescript
-interface ComponentProps {
-  items: Array<Item>; // ✅ Correct syntax
-  tags: Array<{ label: string }>; // ✅ Element is an object with named keys
-}
-```
-
-See also: [Array Element Types: Always Objects with Named Keys](#array-element-types-always-objects-with-named-keys) — items must be objects with named keys.