From 96d818c06d70cd4e401ec1dae1befca87252cd7f Mon Sep 17 00:00:00 2001 From: Yaniv Efraim Date: Mon, 25 May 2026 14:30:22 +0300 Subject: [PATCH] wix-app: trim Editor React Component reference loads; document Link.href MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Editor React Component init runs are paying a high cache-read tax because the parent reference instructs the agent to read all 9 topic files upfront (ACCESSIBILITY, DIRECTIONALITY, PARTS, PROPS-VS-CSS, COMPONENT-CONFIGURATION, plus the three load-always files). On a recent INIT_CODEGEN run for a simple list-of-cards widget, that pushed the per-turn cache-read floor to ~58k and the run cost to $0.81 / 3:21 (SLO: <$0.50 / <3 min). Two changes here, both contained to the wix-app skill: 1. EDITOR_REACT_COMPONENT.md — split the topic references into "read upfront" (REACT-GUIDELINES, COMPONENT-API, CSS-GUIDELINES) and "load on demand" (everything else), with a per-topic trigger table so the agent only pulls ACCESSIBILITY/DIRECTIONALITY/PARTS when the spec actually warrants them. 2. COMPONENT-API.md — add a "Field-name gotchas" callout in the Component Data Types section documenting that Link's URL field is `href` (not `url`). The agent guessed `.url` in the breaching run, blew a tsc cycle, and went grepping node_modules to find the right name. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../references/EDITOR_REACT_COMPONENT.md | 27 ++++++++++++++----- .../editor-react-component/COMPONENT-API.md | 14 ++++++++++ 2 files changed, 35 insertions(+), 6 deletions(-) diff --git a/skills/wix-app/references/EDITOR_REACT_COMPONENT.md b/skills/wix-app/references/EDITOR_REACT_COMPONENT.md index f641fae2..456f05ff 100644 --- a/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +++ b/skills/wix-app/references/EDITOR_REACT_COMPONENT.md @@ -66,14 +66,29 @@ Reference: when modifying an _existing_ component, follow Core rules and workflow: [`editor-react-component/REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md). -Topic-focused references (rules + patterns + common mistakes in one place): +### Read upfront (always) -- [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) — ARIA/a11y rules and patterns -- [`editor-react-component/DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) — RTL/LTR rules and patterns -- [`editor-react-component/PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) — What should be a React prop vs CSS +These three references apply to every Editor React Component — load them before writing code: + +- [`editor-react-component/REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md) — Core rules and workflow - [`editor-react-component/COMPONENT-API.md`](editor-react-component/COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props -- [`editor-react-component/REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, remaining common mistakes +- [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) — CSS authoring rules (root layout, naming, RTL, state styles) + +### Load on demand (only when a signal in the spec matches) + +Do **not** read these upfront. Pull each one only when the component spec has the trigger listed — they add ~5–15k tokens each to your context window and inflate every subsequent tool turn's cache-read cost: + +| Reference | Load when the spec mentions… | +| --- | --- | +| [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) | per-breakpoint visibility, `show*`/`hide*` toggles, orientation/alignment variations, or you're tempted to add a visual-toggle prop | +| [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) | icon-only buttons/links, ARIA attributes, screen-reader behavior, or interactive elements without visible text | +| [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) | non-trivial RTL behavior beyond `dir={direction}` on the root, JS that branches on direction (keyboard nav, animations), or RTL-aware transforms | +| [`PARTS.md`](editor-react-component/PARTS.md) | non-obvious decisions about which elements deserve a named part (lists/grids of items, repeated structural elements, ambiguous wrappers) | +| [`REACT-PATTERNS.md`](editor-react-component/REACT-PATTERNS.md) | SSR-sensitive logic (`window`/`document`/`navigator`), pseudo-class state styling questions, or semantic-HTML choices for collection-style UI | +| [`COMPONENT-CONFIGURATION.md`](editor-react-component/COMPONENT-CONFIGURATION.md) | always when editing `.extension.ts` (sizing type, resize direction, `staticContainer`) — but not before | + +When in doubt, write the code first using the three upfront references and the inline rules above. Pull a topic file only when you hit a question it answers. ## CSS guidelines -Reference: [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md). +Reference: [`editor-react-component/CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) — included in the "Read upfront" set above. diff --git a/skills/wix-app/references/editor-react-component/COMPONENT-API.md b/skills/wix-app/references/editor-react-component/COMPONENT-API.md index e30ef903..9f6ccd0d 100644 --- a/skills/wix-app/references/editor-react-component/COMPONENT-API.md +++ b/skills/wix-app/references/editor-react-component/COMPONENT-API.md @@ -163,6 +163,20 @@ When creating TypeScript interfaces for component props, use types from `@wix/ed import type { Link } from "@wix/editor-react-types"; // Reference at node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts ``` +#### Field-name gotchas + +Don't guess field names — these are the ones agents most often get wrong: + +- **`Link`**: the URL field is **`href`**, not `url`. Shape: `{ href?: string; target?: '_self' | '_blank'; rel?: string }`. + ```tsx + // ✅ Correct + {ctaLabel} + + // ❌ Wrong — `Link.url` doesn't exist; tsc will error + + ``` +- **`Image`**: the source field is **`url`** (the absolute Wix-hosted URL); **`uri`** is the bare `fileName`. Both should be populated together when you author defaults. See the "Default values for `Image` props" section below. + ### External resources are forbidden All resources rendered or fetched by the component (images, icons, fonts,