@wix/agent-skills 1.16.2 → 1.17.0

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

@@ -1,172 +0,0 @@
-# Editor React Component A11y Review Reference
-
-Use this reference for decisions that require code inspection after running the scanners in [`A11Y-REVIEW.md`](A11Y-REVIEW.md). The scanner output owns rule-specific context: rule ID, location, message, resolution path, evidence, and confidence. Do not maintain a separate rule catalog here.
-
-## Scanner Result Handling
-
-Treat every scanner finding as a lead until the component implementation confirms how the flagged behavior reaches the rendered element.
-
-1. Read the full finding, including evidence and confidence when present.
-2. Trace the component topology through local wrappers, shared primitives, and package implementations.
-3. Deduplicate findings that identify the same issue at the same location.
-4. Assign a verdict: `confirmed`, `false-positive`, or `not-relevant`.
-5. Fix confirmed issues inline, then re-run both scanners on changed JSX files.
-
-When both scanners flag the same issue, keep the finding with the strongest semantic evidence. The scanners complement each other; a finding from one scanner is not automatically stronger because of its tier.
-
-## Confidence Model
-
-### High
-
-Use high confidence when the code and scanner evidence unambiguously show the violation, for example:
-
-- the flagged rendered element and static props establish the behavior directly
-- the component implementation resolves to the flagged semantic element
-- an explicit polymorphic prop establishes the rendered element
-
-Fix high-confidence findings immediately.
-
-### Medium
-
-Use medium confidence when:
-
-- props strongly imply the rendered semantics
-- the implementation only partially resolves but preserves likely semantics
-- the component name, props, and surrounding evidence strongly agree
-
-Read the surrounding code. If it confirms the inference, fix the issue. If it contradicts the inference, discard the finding. If the implementation remains unresolved, treat it as low confidence.
-
-### Low
-
-Use low confidence when:
-
-- only weak heuristics support the semantic guess
-- the implementation cannot be resolved
-- runtime props or spreads can materially change the rendered semantics
-
-Continue tracing the code. Fix only after the issue is confirmed; otherwise leave the code unchanged.
-
-### Confidence vs. Actionability
-
-Confidence answers whether the issue is real. It does not decide whether a confirmed fix is safe.
-
-- Confirmed + safe/local fix: fix now.
-- Confirmed + risky behavior change or non-local refactor: leave unchanged.
-- Unconfirmed or ambiguous: leave unchanged.
-
-If the violation is visible in the code and has a localized, behavior-preserving fix, treat it as confirmed and apply the fix.
-
-Valid reasons to leave code unchanged:
-
-- semantics remain ambiguous after reading the available code
-- product intent cannot be derived from the code
-- the fix requires a risky behavior change or a non-local refactor
-
-Do not leave a confirmed safe/local issue unchanged because it is low severity, secondary, shared, or outside the first file in scope.
-
-## Semantic Resolution
-
-Resolve the rendered behavior in this order:
-
-1. The flagged JSX element and its static props
-2. Explicit polymorphic props such as `as="a"` or `component="button"`
-3. The local component implementation
-4. Installed package source or declarations in `node_modules`
-5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
-6. Component-name heuristics
-
-For local imports, follow the exported component's rendered root. Continue through local or package components until the semantics resolve or the evidence becomes too weak.
-
-For package imports, resolve the import from `node_modules` and inspect its exported entry point. If the package hides its rendered semantics, use prop and naming evidence without assigning more confidence than the evidence supports.
-
-## Tier 2 Manual Review Checklist
-
-Run this checklist after scanner findings are triaged. Tier 2 is required even when both scanners return zero findings.
-
-### Semantic Targeting
-
-- Do ARIA attributes land on the semantically correct element instead of a layout wrapper?
-- Do labels, descriptions, and roles reach the actual interactive or landmark element?
-- Do wrappers preserve the semantics exposed by their API?
-
-### Icon-Only and Visual-Only States
-
-- Do icon-only buttons, links, or controls have an accessible name?
-- If visible text is hidden, is it visually hidden in an accessibility-safe way instead of removed from the accessibility tree?
-- Do meaningful icons or images expose accessible text when needed?
-
-### CSS and Hidden Content
-
-- Does `display: none` remove content that should remain available to assistive technology?
-- Are hidden or collapsed states consistent across visuals, focusability, and the accessibility tree?
-- Do conditional classes or CSS variables create states where labels or instructions disappear from assistive technology?
-
-### Decorative vs. Meaningful Content
-
-- Are decorative separators, ornaments, and repeated icons hidden from assistive technology?
-- Are meaningful visuals, status icons, or graphics named appropriately?
-
-### Focus and Interaction Consistency
-
-- Can hidden or collapsed items still receive focus?
-- Do interactive-looking elements expose the correct role and keyboard behavior?
-- Do disabled, inert, or collapsed states behave consistently for keyboard users and assistive technology?
-- Search all in-scope files for `onClick` on elements without built-in interaction (`div`, `span`, `section`, `header`, `footer`, `li`, `td`, and similar tags). Include conditional patterns such as `{...(condition && { onClick: handler })}`. Verify that each match also has the required `role`, `tabIndex`, and keyboard handler (`onKeyDown` or `onKeyUp`). A missing combination is a high-confidence finding.
-- Before fixing missing keyboard semantics, check for nested interactive children, existing focus management, and the condition that enables interaction. Use the [pre-fix checks](#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
-
-### Structural Semantics
-
-- Are landmarks, headings, and list semantics preserved through wrappers and layout components?
-- When the component implements breadcrumbs, tabs, menus, dialogs, or similar patterns, do the expected semantics reach the rendered structure?
-
-### Editor React Component Contracts
-
-- Are ARIA attributes routed through the typed `a11y` prop and converted at the correct element?
-- Do icon-only labels come from `constants.ts` or user-configurable `a11y` instead of hardcoded strings?
-- Does the component preserve direction support and isolate each `ReactNode` content prop with `dir="ltr"`?
-- Do extension overrides preserve a11y-relevant manifest fields generated from JSX?
-
-## Fix Principles
-
-- Use the rule ID, message, and evidence emitted by the scanner as the rule-specific fix context.
-- Read the surrounding code before editing.
-- Preserve visual and runtime behavior.
-- Prefer the smallest correct change and avoid unrelated refactors.
-- Fix the semantic owner: the component root, the correct inner element, a shared base, or the call site that supplies the value.
-- When a wrapper already accepts and forwards a required prop, fix the call site. When it does not, update the wrapper contract and forwarding before fixing the call site.
-- Do not hardcode reusable accessibility values such as alternative text. Accept them through the component API when they depend on consumer content.
-- Route Editor React Component ARIA through `a11y` and `convertA11yKeysToHtmlFormat(a11y)` according to [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
-
-## Pre-Fix Checks for Adding Button Semantics to a Non-Interactive Element
-
-Before adding `role="button"`, `tabIndex`, and keyboard handlers to an element such as `<div>`, verify all four conditions below.
-
-### 1. Interactive Children
-
-Check whether the element conditionally or unconditionally contains `<a>`, `<button>`, `<input>`, `<Link>`, or a component that resolves to an interactive element. Button semantics on the parent would create nested interaction.
-
-If interactive children are possible, either exclude that branch from the parent's interaction condition or use a separate control element.
-
-### 2. Existing Focus Management
-
-Check whether the element already receives `tabIndex` from another source, such as `getTabIndexAttribute`, an a11y prop spread, or an interactions framework. Determine the prop merge order and keep one source authoritative.
-
-When an existing a11y spread should win, place the conditional interaction spread before it so `tabIndex: 0` only acts as a fallback.
-
-### 3. Interaction Condition
-
-Read the full boolean expression that enables interaction. Verify that it:
-
-- excludes states that already render an interactive child
-- excludes editor preview, externally controlled, disabled, or reduced-motion states when required
-- uses explicit comparisons such as `=== undefined` or `=== true` when `true`, `false`, and `undefined` have different meanings
-
-Fix a fragile condition as part of the accessibility change. Correct semantics attached to the wrong state are still incorrect behavior.
-
-### 4. Accessible Name Scope
-
-Decide whether an accessible label names the interaction or the component as a whole. Keep a component-level label outside the interaction condition so it persists in non-interactive states. Apply an action-specific label only while that action is available.
-
-## After Fixing
-
-Re-run both scanners on changed `.tsx` / `.jsx` files. Continue with `npx wix build`, `npx wix generate manifest`, and the project's TypeScript check as required by [`A11Y-REVIEW.md`](A11Y-REVIEW.md#phase-5-verify).

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