@wix/agent-skills 1.31.2 → 1.32.0

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

@@ -1,7 +1,5 @@
 # Accessibility Implementation and Review
 
-Use while authoring; run the review after JSX is complete.
-
 ## Contents
 
 - [Implementation Contract](#implementation-contract)
@@ -28,18 +26,31 @@ Every `a11y` field that reaches the DOM becomes an editor control. Read only the
 field the part needs and write it as its HTML attribute,
 `aria-label={a11y?.ariaLabel}`. Never spread the whole object.
 
-```tsx
+The shared-default rule in `COMPONENT-CONTRACT.md` applies to a11y fields too:
+root defaults go in `defaultProps.a11y`; named-part defaults go in
+`defaultProps.elementProps.<partKey>.a11y`, where the key is the part's global class in camelCase.
+
+```ts
+// toggle.props.ts
 import type { A11y } from '@wix/editor-react-types';
 
-type ToggleProps = {
-  elementProps?: { toggle?: { className?: string; a11y?: A11y } };
+export type ToggleProps = {
+  elementProps?: { toggleButton?: { className?: string; a11y?: A11y } };
 };
 
-function Toggle({ elementProps }: ToggleProps) {
-  const { a11y: toggleA11y, ...toggleProps } = elementProps?.toggle ?? {};
+export const defaultProps = {
+  elementProps: { toggleButton: { a11y: { ariaLabel: 'Toggle details' } } },
+} satisfies ToggleProps;
+```
 
+```tsx
+// toggle.tsx
+import type { ToggleProps } from './toggle.props';
+
+export function Toggle({ elementProps }: ToggleProps) {
+  const { a11y: toggleA11y, ...toggleProps } = elementProps?.toggleButton ?? {};
   return (
-    <button {...toggleProps} aria-label={toggleA11y?.ariaLabel ?? ARIA_LABELS.toggle}>
+    <button {...toggleProps} aria-label={toggleA11y?.ariaLabel}>
       <svg aria-hidden="true" viewBox="0 0 16 16">
         <path d="m3 6 5 5 5-5" fill="none" stroke="currentColor" />
       </svg>
@@ -48,7 +59,7 @@ function Toggle({ elementProps }: ToggleProps) {
 }
 ```
 
-Keep the root's typed `a11y?: A11y` prop even when it reads no field. Destructure
+Keep the root's `a11y?: A11y` prop even when it reads no field. Destructure
 `a11y` out of an `elementProps` entry before spreading the entry; a spread entry
 records the nested object as a whole. Image alt text comes from the `Image`
 type's `alt` field, not from `a11y`.
@@ -64,24 +75,12 @@ Use this priority order:
 
 Never hardcode an `aria-label` string directly in JSX.
 
-```tsx
-// constants.ts
-export const ARIA_LABELS = {
-  toggle: 'Toggle details',
-  playButton: 'Play animation',
-  pauseButton: 'Pause animation',
-} as const;
-
-// component JSX
-<button
-  aria-label={isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton}
->
-  {isPlaying ? <PauseIcon /> : <PlayIcon />}
-</button>;
-```
+For example, a system-owned playback label can use
+`aria-label={isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton}`,
+with those strings defined in `constants.ts`.
 
-Icon-only controls require an accessible name. Controls with visible text,
-including an icon plus visible text, usually do not need another ARIA label.
+Icon-only controls need an accessible name; controls with visible text usually
+do not need another ARIA label.
 
 ### Preserve Semantic Ownership
 
@@ -95,8 +94,8 @@ including an icon plus visible text, usually do not need another ARIA label.
 
 ## Review Scope
 
-Run this review once the JSX is complete and again after each fix pass, at
-most two passes. Do not rerun after a clean result unless JSX changed.
+Review completed JSX and rerun after fixes, at most two passes. After a clean
+result, rerun only if JSX changes.
 
 | Request | Pass to the command |
 | --- | --- |
@@ -105,10 +104,8 @@ most two passes. Do not rerun after a clean result unless JSX changed.
 | Full audit | `src/extensions/site/components/` |
 
 `*.generated.ts` is regenerated from JSX and CSS and is never scanned.
-Imported shared components are inspection context, not automatic edit scope.
-Report a confirmed shared-component issue instead of changing a broadly reused
-primitive unless the requested fix requires that shared change and its impact is
-understood.
+Inspect imported shared components, but edit them only when the requested fix
+requires it and the impact is understood; otherwise report the issue.
 
 ## Automated Review
 
@@ -119,16 +116,12 @@ from the consumer Wix package so dependencies resolve from that project.
 node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>
 ```
 
-One command, one report. It runs the jsx-a11y ESLint rules, a semantic scanner
-that follows imports and checks the per-part `a11y` contract, and a render
-audit: the component is rendered with `defaultProps` in Node (an SSR check),
-loaded into jsdom with its CSS Modules, and audited with axe-core.
-`component.preview.tsx` must render without falling back to the placeholder.
+The command runs jsx-a11y ESLint rules, a semantic scanner that follows imports,
+and an SSR/jsdom/axe-core audit with `defaultProps` and CSS Modules.
+`component.preview.tsx` must render without the placeholder.
 
-The JSON report has `summary.line`, then `findings` grouped by rule with a
-count, locations or DOM target, the scanner message, and the axe help link,
-then `notChecked`. Exit `0` means every scanner ran and found nothing, `1`
-means findings, `2` means the review is inconclusive; never treat `2` as clean.
+Read `summary.line`, `findings`, and `notChecked` in the JSON report.
+Exit `0` means clean, `1` means findings, and `2` means inconclusive, never clean.
 Exit `2` with `render FAILED (missing-deps)` means `jsdom` or `axe-core` is not
 installed: install them (SKILL.md step 2) and rerun. Exit `2` with
 `render FAILED (loader)` means the audit could not load a module the component
@@ -147,25 +140,21 @@ For every finding:
 3. Assign `confirmed`, `false-positive`, or `not-relevant`.
 4. Fix only confirmed findings.
 
-Scanner output is a lead, not permission to edit blindly.
-
 ### Confidence and Action
 
 | Confidence | Evidence | Action |
 | --- | --- | --- |
-| High | The rendered element and static props directly establish the issue. | Confirm and fix when the change is safe and local. |
-| Medium | Props or partial component resolution strongly imply the semantics. | Inspect surrounding code, then confirm or discard. |
-| Low | Heuristics or unresolved runtime spreads are the main evidence. | Trace further and fix only after confirmation. |
-| Unknown | The semantic target cannot be resolved. | Leave unchanged and report the ambiguity when material. |
+| High | Rendered element and static props prove it. | Fix when safe and local. |
+| Medium | Props or partial resolution suggest it. | Inspect, then confirm or discard. |
+| Low | Only heuristics or unresolved spreads. | Trace before fixing. |
+| Unknown | Semantic target unresolved. | Leave unchanged; report material ambiguity. |
 
-Confidence establishes whether a finding is real, not whether its fix is safe.
-Apply confirmed local, behavior-preserving fixes. Leave a confirmed issue
-unchanged only when product intent is unknowable or the fix requires risky,
-non-local behavior changes.
+Apply confirmed local, behavior-preserving fixes. Report issues needing unknown
+product intent or risky, non-local behavior changes.
 
 ### Semantic Resolution Order
 
-Resolve rendered behavior in this order:
+Resolve semantics in this order:
 
 1. Flagged JSX element and static props
 2. Explicit polymorphic props such as `as="a"` or `component="button"`
@@ -174,19 +163,20 @@ Resolve rendered behavior in this order:
 5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
 6. Component-name heuristics
 
-Follow local imports to their rendered root. For package imports, inspect the
-resolved package entry when available. Do not assign more confidence than the
-evidence supports.
+Follow local imports to their rendered root and package imports to their
+resolved entry. Match confidence to evidence.
 
 ## Manual Review
 
-In the default rendered state the command checks names, alt text, ARIA
-validity, nesting, list and heading structure, hidden-but-focusable content,
-the `a11y` contract, and SSR safety. Verify what it cannot see:
+The command audits default-state semantics, names, ARIA, focus visibility,
+the a11y contract, and SSR. Also verify:
 
 - Every meaningful non-default state (expanded, selected, playing, error,
   empty, hover/focus) keeps correct names, focusability, hidden state, and
   structure; the command audits only the default render.
+- Trace each a11y field read, including aliases and inner parts, to its matching
+  `defaultProps` path and meaningful default. An unused `a11y?: A11y` declaration
+  needs no default. Check source; no extra manifest generation is required.
 - Wrappers and polymorphic components preserve their documented semantics;
   extension overrides preserve generated accessibility fields.
 - Accessible names describe the action, and visually hidden text that carries
@@ -202,8 +192,9 @@ the `a11y` contract, and SSR safety. Verify what it cannot see:
 - The root implements the direction contract, and every `ReactNode` slot
   isolates nested content with `dir="ltr"`.
 
-- An auto-rotating set of readable parallel items uses `aria-live="off"` while
-  it is rotating and `aria-live="polite"` while it is stopped.
+- An auto-rotating set of readable parallel items pauses while hovered or
+  focused, uses `aria-live="off"` while rotating and `"polite"` while stopped.
+  Its root hover/focus handlers are required; never remove them for a finding.
 
 ## Pre-Fix Checks for Non-Interactive Controls
 
@@ -232,7 +223,6 @@ The accessibility review is complete only when:
 - the command was rerun after the last fix pass; and
 - the manual review is complete.
 
-After two fix passes, stop and report the remaining findings with their triage.
-Preserve visual and runtime behavior. Fix the semantic owner: root, named inner
-part, shared primitive, or call site. Then return to the main workflow for the
-Wix build, manifest generation, TypeScript check, and relevant project tests.
+After two fix passes, report remaining findings with their triage. Preserve
+visual and runtime behavior. Fix the semantic owner, then resume only the
+build, manifest, TypeScript, and test steps required by the task.

package/skills/wix-app/references/editor-react-component/ANIMATED-COMPONENTS.md

@@ -43,12 +43,11 @@ For carousel-like components that swap readable parallel items, make the item
 wrapper a live region:
 
 - Use `aria-live={isPlaying ? 'off' : 'polite'}` and `aria-atomic="false"`.
-- `isPlaying = isPlayOn && !isHovered && !isStoppedByFocus`. Reduced motion
+- `isPlaying = isPlayOn && !isHovered && !isFocusWithin`. Reduced motion
   starts paused; editor mode, `autoPlay={false}`, and pause set it false.
-  Keyboard focus remains stopped until the rotation control restarts; hover
-  pauses temporarily.
-- Previous/next changes items. Use root `onMouseEnter`/`onMouseLeave`;
-  leaving resumes unless focus has stopped rotation.
+- Root `onMouseEnter`/`onMouseLeave` and `onFocus`/`onBlur` (clear only when
+  `relatedTarget` leaves the root) pause temporarily; prev/next/dot set
+  `isPlayOn` to `false`.
 
 ## 1. Define Props
 
@@ -75,7 +74,7 @@ export interface MyAnimationProps {
   pauseButtonVisibility?: 'showAlways' | 'showOnHover';
 
   elementProps?: {
-    playButton?: { className?: string };
+    myAnimationPlayButton?: { className?: string };
   };
 }
 ```
@@ -126,24 +125,18 @@ do not restart when it turns off. Resume can still override the preference.
 
 Derive runtime playback from `isPlayOn` plus only needed conditions. Without
 another condition, use `const isPlaying = isPlayOn`. A carousel, slideshow,
-slider, or gallery also uses hover and focus-stop state:
+slider, or gallery also uses hover and focus state:
 
 ```tsx
-const isPlaying = isPlayOn && !isHovered && !isStoppedByFocus;
+const isPlaying = isPlayOn && !isHovered && !isFocusWithin;
 ```
 
 Pass `isPlaying` to the renderer. The button uses `isPlayOn` and toggles
-between `handlePause` / `handleResume` on click. In a carousel-like component,
-focus entering anything except that button sets `isPlayOn` to `false` and
-`isStoppedByFocus` to `true`; `handleResume` sets `isPlayOn` to `true` and
-clears `isStoppedByFocus`.
+between `handlePause` / `handleResume` on click.
 
 ## 3. Add the Play/Pause Button
 
-Use inline SVG icons: a triangle for play and two bars for pause. Declare
-`--icon-size` and `--icon-color` on the button. Apply `var(--icon-size)` to the
-SVG's CSS `width` and `height` (or React `style`), not raw SVG attributes;
-set button `color: var(--icon-color)` and SVG `fill: currentColor`.
+Use inline SVG icons: a triangle for play and two bars for pause. Follow SVG Icons in `CSS-GUIDELINES.md` for `--icon-size` and `--icon-color`.
 
 Position the button absolutely so it overlays the content without pushing other elements out of place:
 
@@ -198,11 +191,11 @@ Wire the named part completely:
 ```tsx
 <button
   type="button"
-  {...elementProps?.playButton}
+  {...elementProps?.myAnimationPlayButton}
   className={classNames(
     'my-animation-play-button',
     styles.playButton,
-    elementProps?.playButton?.className,
+    elementProps?.myAnimationPlayButton?.className,
   )}
   onClick={isPlayOn ? handlePause : handleResume}
   aria-label={
@@ -223,7 +216,8 @@ Wire the named part completely:
   pointer-events: none;
 }
 
-.root[data-pause-button-visibility="showOnHover"]:hover .playButton {
+.root[data-pause-button-visibility="showOnHover"]:hover .playButton,
+.root[data-pause-button-visibility="showOnHover"]:focus-within .playButton {
   opacity: 1;
   pointer-events: auto;
 }
@@ -268,9 +262,8 @@ Design mode stops autoplay and exposes the control; preview uses the user's valu
 - [ ] Autoplay and pause-control props use the documented contract; `loop` is
       present only when repeat behavior is supported.
 - [ ] Reduced motion starts paused and never restarts playback automatically.
+- [ ] Hover and focus pause rotation; manual navigation stops it.
 - [ ] The play/pause button is a fully wired named part with a stable accessible name.
-- [ ] Both icons inherit button-owned `--icon-size` for width and height and
-      `--icon-color` via `color` and `currentColor` for fill or stroke.
 - [ ] Hover has a paired editor design state; `:focus-visible` remains a
       standalone keyboard indicator.
 - [ ] Hover-only visibility changes behavior, not the button's editable styling surface.

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

@@ -1,14 +1,13 @@
 # Component Contract
 
-Use this reference when defining props, defaults, named-part wiring, complex data,
-or internal file boundaries.
+Use for props, defaults, named parts, data, and file boundaries.
 
 ## Public Props Contract
 
-Keep identity and platform contracts together with component-specific data and
-behavior. Do not add `children` unless the component is explicitly a container.
+Keep identity, platform props, data, and behavior together. Add `children` only
+for an explicit container.
 
-Use this shape:
+Shape:
 
 ```ts
 import type { A11y, Direction } from '@wix/editor-react-types';
@@ -28,7 +27,7 @@ export type PlanCardProps = {
   onBlur?: (event: React.FocusEvent) => void;
 
   elementProps?: {
-    cta?: { className?: string; href?: string };
+    planCardCta?: { className?: string; href?: string };
   };
 };
 ```
@@ -43,9 +42,8 @@ Rules:
 - Default to common optional SDK callbacks by capability; add specialized ones
   when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
-- A CTA with a real destination is a native link with that `href`. If it only
-  performs an action, use a native button. Never use `href="#"` as a fallback;
-  it creates a focusable link without a meaningful destination.
+- Use a native link for a CTA with a real `href`, or a native button for an
+  action. Never fall back to `href="#"`: it has no meaningful destination.
 
 ## Numeric Range Constraints
 
@@ -68,47 +66,49 @@ Treat an independently editable inner element as a named part. Wiring rules:
 
 - Root receives top-level `id`, `className`, `direction`, `a11y` — no
   `elementProps` entry.
-- Every named inner part has an `elementProps` entry (even if only `className`
-  is needed); structural/decorative non-parts use only a CSS Module class.
+- Every named inner part has an `elementProps` entry (`className` at minimum); structural/decorative non-parts use only a CSS Module class.
 
 On a raw HTML element, spread the entry and explicitly merge its injected
-`className`. Keep the entry key short while prefixing the global class with the
-component name.
+`className`. The key is the part's global class in camelCase, never shortened
+(`plan-card-cta` → `planCardCta`); any other key reads `undefined`.
 
 ```tsx
 <a
-  {...elementProps?.cta}
+  {...elementProps?.planCardCta}
   className={classNames(
     'plan-card-cta',
     styles.cta,
-    elementProps?.cta?.className,
+    elementProps?.planCardCta?.className,
   )}
 >
   {label}
 </a>
 ```
 
-When a named part renders another component built with this skill, spread the
-entry and let that component merge its incoming `className` on its root.
+For a skill-built sub-component, spread the entry; its root merges the incoming
+`className`.
 
 ```tsx
-<PlanRow {...elementProps?.planRow} item={plan} />
+<PlanRow {...elementProps?.planCardPlanRow} item={plan} />
 ```
 
-Do not merge the same class at both the call site and the sub-component root.
+Never merge the class at both the call site and the sub-component root.
 
 ## Content and Data
 
 Compute derived values internally when a small pure expression can derive them
-from props or state (e.g. expose `price` and `quantity`; compute `subtotal`; use
-numeric types when arithmetic is required).
+from props or state (e.g. expose `price`, `quantity`; compute `subtotal`).
+Use numeric types for arithmetic.
 
 ### Data-Driven Components
 
-Export named content props rather than `children` for leaf components — text
-(`label`, `title`, `placeholder`), media (`image`, `video`, `icon`), links
-(`link`, `href`), collections (`items`, `options`, `menuItems`). Internal
-sub-components may still use `children` for composition.
+Export named content props, not `children`, for leaf components — text
+(`label`, `title`), media (`image`, `icon`), links (`link`), collections
+(`items`, `options`). Internal sub-components may use `children`.
+
+Every visible text (eyebrow, subtitle, label) is a text prop with a default in
+its own named part. No JSX text literals (`aria-label`: ACCESSIBILITY.md).
+Computed text (a clock) gets one too.
 
 ### Container Components
 
@@ -184,14 +184,20 @@ optional `uri`, `alt`, `width`, `height`; `Link` has optional `href`, `target`
 
 Do not represent media as a URL/source string or split its metadata across
 primitive props. Preserve the media object through the public contract so the
-component can consume all of its supported data. Inspect the installed media
-type declaration only if a needed field is not covered here or a typecheck
-reports an error.
+component can consume all of its supported data.
+
+Before using fields not documented here, inspect the relevant app-resolved
+`@wix/editor-react-types` declaration and only needed type references. Never
+infer one type's fields from another type's example. Recheck documented fields
+only if a related typecheck error reveals a mismatch; follow the installed
+declaration for the field shape while retaining editor rules. Preserve required
+fields. Do not bypass errors with `any`, casts, or replacement media types.
 
 ## Defaults and Resources
 
-Export `defaultProps` from `<component-name>.props.ts`. Both `component.tsx` and
-the extension consume this object; never duplicate fallbacks in JSX.
+Export `defaultProps` from `<component-name>.props.ts`, including defaults for
+root and nested `a11y` fields. Both `component.tsx` and the extension consume
+this object; never duplicate these defaults in destructuring or JSX.
 
 All rendered media must come from Wix-hosted services, local assets, or props.
 No external hosts or third-party runtime dependencies.
@@ -254,4 +260,5 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 - [ ] Array elements are objects with semantic named fields. No separate `id` field added to item types; React keys use item fields (stable unique → slug → index), not a typed `id`.
 - [ ] Authored media uses the corresponding Wix media type, not URL/source strings or flattened metadata.
 - [ ] Defaults live only in the props file (no JSX fallbacks).
+- [ ] Every visible text is a prop with a named part; no JSX text literals.
 - [ ] Resources are Wix-hosted, prop-supplied, or locally bundled.

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -1,9 +1,7 @@
 # CSS Guidelines
 
 Use these rules for the scaffolded `<component-name>.module.css` file and any
-colocated CSS Modules owned by internal sub-components. These rules keep the component
-editable by zero config, responsive to its Wix-owned container, and safe in
-both LTR and RTL layouts.
+colocated CSS Modules owned by internal sub-components.
 
 **Visual intent.** When the request specifies how the component should look —
 mood, palette, layout style, or a reference — follow that direction. Default to a modern, refined look — intentional layout, pleasing proportions, polished and deliberate styling.
@@ -31,18 +29,18 @@ Apply classes with `classnames`:
 | Structural/decorative non-part | Module class only |
 
 The global class lets zero config create an editor element. Prefix every inner
-part with the component name to prevent collisions between components. The
+part with the component name to avoid collisions. The
 module class carries the component's default CSS. Preserve the scaffolded root
 pattern. For a new named part, add only the wiring the scaffold cannot infer:
 spread its `elementProps` entry and merge the injected class.
 
 ```tsx
 <h2
-  {...elementProps?.heading}
+  {...elementProps?.profileCardHeading}
   className={classNames(
     'profile-card-heading',
     styles.heading,
-    elementProps?.heading?.className,
+    elementProps?.profileCardHeading?.className,
   )}
 >
   {heading}
@@ -96,9 +94,8 @@ height or the requested behavior requires a bounded height. Omit it when the
 extension uses `LAYOUT.SIZING_TYPE.content`; the component's content must then
 establish its block size.
 
-Set `--display` on the root; do not set root `display` directly. The platform
-resolves and overrides this custom property. Inner elements use `display`
-normally.
+Set `--display` on the root; do not set root `display` directly. Inner
+elements use `display` normally.
 
 Choose the simplest root shape that fits the component:
 
@@ -152,8 +149,7 @@ Use logical inline-axis properties so layout flips automatically in RTL:
 ```
 
 Avoid `left`, `right`, `margin-left`, `padding-right`, and similar physical
-inline-axis properties. Physical block-axis properties such as `top` and
-`margin-bottom` are fine.
+inline-axis properties. Physical block-axis properties are fine.
 
 ## Editable Values
 
@@ -161,7 +157,8 @@ Keep static styling in the CSS Module, not JSX `style` objects. Use literal CSS
 values when no interpolation is needed; do not create a React prop or CSS custom
 property for routine values that zero config already surfaces.
 
-Use this pattern:
+Write each spacing value as one `px`, `%`, `vh` or `vw` number (`px` by
+default), not `clamp()`, `calc()`, `min()` or `max()`.
 
 ```css
 .root {
@@ -176,31 +173,50 @@ Use this pattern:
 }
 ```
 
-A dynamic runtime value that cannot be represented statically may use a narrowly
-scoped CSS custom property set from JSX, but keep the actual style rule in CSS
-and do not expose a visual prop solely for that purpose.
+A dynamic runtime value may use a narrowly scoped custom property set from
+JSX; keep the style rule in CSS and expose no visual prop for it.
 
 ```css
-/* Typography: zero config builds the `font` control from both longhands.
-   A part with a size but no family gets a control with no default. */
+/* Typography: set both longhands; a size without a family gives the
+   `font` control no default. */
 .cta {
   font-family: 'Inter', sans-serif;
   font-size: 14px;
   font-weight: 600;
 }
 
-/* Avoid: a module-only wrapper is not an editor element. A size here is
-   uneditable and silently overrides the parent's typography control. */
+/* Avoid: a module-only wrapper isn't editable; its size silently
+   overrides the parent's typography control. */
 .cta-label {
   font-size: 14px;
 }
 ```
 
-The same override risk applies to paintable properties. A layout-only inner
-wrapper must stay visually transparent; if it isn't, promote it to its own
-named part instead of hardcoding an opaque style on an unexposed node, since
-that style would otherwise mask the parent part's own
-`background`/`border`/`box-shadow`.
+The same applies to paint: a layout-only wrapper stays transparent or becomes
+a named part, so it can't mask the parent's `background`/`border`/`box-shadow`.
+
+### SVG Icons
+
+The part owning an icon declares `--icon-size` and `--icon-color`, prefixed
+per icon (`--start-icon-size`), applied via `inline-size`/`block-size` and
+`fill` or `stroke`.
+
+- **Inline** (chevron, play/pause): the `svg` applies them through a module
+  class, its paths carrying no colour attributes; no rotation property, since
+  state and direction own its transform.
+
+```css
+.toggleButton {
+  --icon-size: 16px;
+  --icon-color: #1e293b;
+}
+
+.chevron {
+  inline-size: var(--icon-size);
+  block-size: var(--icon-size);
+  fill: var(--icon-color);
+}
+```
 
 ## Interaction and Motion
 
@@ -232,7 +248,7 @@ request or existing design provides better values:
 
 ### Foreground and Background Ownership
 
-If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. If it is an inline control meant to blend in (link, ghost button, icon button), control may leave the root transparent instead.
+If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. An inline control meant to blend in (link, ghost button, icon button) may leave it transparent.
 
 - On a transparent root, don't hardcode text or icon colors; inherit them from the parent.
 - Set the background and main text/icon color together on the same element. Any secondary text (captions, hints, icons) must still be readable against that same background.
@@ -243,7 +259,6 @@ A neutral owned surface may use a light background with dark primary and
 secondary foregrounds, plus one accessible accent. The exact colors are not a
 contract; the contrast relationship is.
 
-
 ## Checklist
 
 - [ ] The scaffolded component and each extracted internal sub-component own
@@ -261,6 +276,5 @@ contract; the contrast relationship is.
 - [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
 - [ ] Every explicit foreground has a known contrasting background; transparent
       components inherit foregrounds from their host.
-- [ ] No unexposed descendant inside a named part paints its own opaque
-      `background`/`border`/`box-shadow`; a wrapper needing its own surface is
-      promoted to a named part instead.
+- [ ] No unexposed descendant paints an opaque surface; promote it to a named
+      part instead.