@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-app/references/dashboard-page/ENTITY_PAGE_TOOLKIT.md

@@ -0,0 +1,73 @@
+# Entity Page Toolkit — calling `useEntityPage`
+
+[COLLECTION_TOOLKIT.md](COLLECTION_TOOLKIT.md) says a row the user cannot open is a defect, and sends you to `EntityPage` + `useEntityPage` to fix it. This file is the call itself.
+
+## The call
+
+```tsx
+import { useEntityPage, EntityPage } from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+
+interface Shift {
+  id?: string;
+  name?: string;
+}
+
+interface ShiftFormFields {
+  name?: string;
+}
+
+const form = useForm<ShiftFormFields>({ defaultValues: { name: '' } });
+
+const state = useEntityPage<Shift, ShiftFormFields>({
+  fetch: () => api.getShift(shiftId).then((entity) => ({ entity })),
+  onSave: ({ widgetsFormData }) =>
+    api
+      .updateShift(shiftId, { ...form.getValues(), ...widgetsFormData })
+      .then((updatedEntity) => ({ updatedEntity })),
+  form,
+  parentPath: '/shifts',
+});
+```
+
+`EntityPage` and `useEntityPage` are **root** exports. `@wix/patterns/page` holds `CollectionPage` and `WidgetsFormProvider` only, so importing the entity page from there is `TS2305: has no exported member` — the collection page and the entity page do not live in the same place. `Read <pkgRoot>/dist/dts-bundle/exports/page.d.ts` to see what that subpath actually gives you.
+
+## Name both generics
+
+`useEntityPage<T, V extends FieldValues = FieldValues>` takes the entity type **and** the form-values type. `V` does not infer from the `form` argument — it falls back to `FieldValues`, and a `useForm<ShiftFormFields>()` then fails to assign with `Type 'UseFormReturn<ShiftFormFields, …>' is not assignable to type 'UseFormReturn<FieldValues>'`. Naming a single generic only works when the form is untyped.
+
+`useEntityPage<any, ShiftFormFields>` makes that error go away and takes the entity type with it — `state.entity` becomes `any`, and every field access below it stops being checked. Name the entity type.
+
+## `onSave` does not hand you the form values
+
+`OnSaveParams` has exactly one key. `widgetsFormData` carries what the **widget** fields contributed — extended fields, tags — not what the user typed into your own fields. Those come from the form you already own:
+
+```tsx
+onSave: ({ widgetsFormData }) => {
+  const values = form.getValues();                  // your fields
+  const { extendedFields, tags } = widgetsFormData; // widget fields
+  …
+};
+```
+
+Reaching for a `values`-shaped key on the `onSave` argument is the usual first guess, and there isn't one.
+
+## The params are a `Pick`
+
+`UseEntityPageParams` picks a fixed set off `EntityPageStateParams` — `fetch`, `onSave`, `saveSuccessToast`, `saveErrorToast`, `deleteAction`, `transformEntityToCollectionItem`, `isNewEntity`, `form`, `parentPageId`, `parentPath`, `parentReferrer`, `schemaSource`. Anything outside that list is an excess-property error on the object literal. `container` is the common guess and is not one of them: the hook calls `useWixPatternsContainer()` itself.
+
+Confirm the shape rather than guessing — the hook's doc has an empty API section, because props tables only exist for components. `Read <pkgRoot>/dist/dts-bundle/index.json`, then `Read` the bundled `.d.ts` for each of `useEntityPage`, `UseEntityPageParams`, and `OnSaveParams` at exactly the `file` path the index gives.
+
+## Around the call
+
+| Step | What owns it |
+| --- | --- |
+| Getting here from the collection page | `usePatternsNavigate()` → `navigateToEntityPage({ path, entity })` |
+| Registering the route | `PatternsReactRoute` inside `PatternsReactRouter` |
+| Form state and field binding | `useForm` / `useController` from `@wix/patterns/form` |
+| Body layout | `EntityPage.Header`, `.MainContent`, `.AdditionalContent`, `.Card` |
+| The fields inside those cards | `@wix/design-system` (`FormField`, `Input`, `Text`) |
+
+`@wix/patterns/form` re-exports `@wix/bex-core/form`, which wraps `react-hook-form` — so `form.getValues()`, `form.reset()` and the rest are react-hook-form's API, documented there rather than in the patterns docs.
+
+A dialog that creates, updates or displays one listed record is **not** a dashboard modal — a create / "add new" form included, since it writes the record. See [DASHBOARD_MODAL.md](../DASHBOARD_MODAL.md).

package/skills/wix-app/references/dashboard-page/PATTERNS_BUNDLE_READING.md

@@ -0,0 +1,52 @@
+# Reading `@wix/patterns` Bundles and Docs
+
+> **Scope.** You are here because a lookup in `dist/dts-bundle/index.json` or
+> `dist/docs/index.json` gave you an entry and you are about to open the file it names. Getting to that index in the first
+> place — resolving the package root, the version floor, the docs lookup, and the rule
+> against browsing `node_modules` by hand — is in
+> [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md). Nothing here replaces those steps.
+
+## Types the docs don't cover
+
+The docs cover components and props, not the types those props use — `Filter<T>`, `RangeItem<T>`, `CursorQuery`, a `...Props` interface. `Read <pkgRoot>/dist/dts-bundle/index.json`, look up the type name, then `Read <pkgRoot>/dist/dts-bundle/<entry.file>` using exactly the `file` path the index gives — **never reconstruct the path from the name**; bundles are nested one directory per kind (`components/Table.d.ts`, `hooks/useForm.d.ts`, `types/RangeItem.d.ts`, …), so guessing `<Name>.d.ts` at the top level is wrong by construction.
+
+Several of these types (`RangeItem`, `Filter`, `CursorQuery`, the filter factory functions) actually live in `@wix/bex-core` — the bundle already resolves and inlines the real declaration, so you get the full shape with no deep, undeclared `@wix/bex-core/dist/types/...` path to chase. Still always import it from `@wix/patterns`, per the index's `importPath` field, never from wherever the bundle says it's really declared.
+
+That inlining applies to the data shapes you write. State objects you *receive* are a separate case — see the next section.
+
+## A bundle stops where you stop writing code
+
+A bundle carries its own name's declaration plus every shape **you** would write by hand. It deliberately does *not* expand what the library hands you, so two kinds of one-line stub are normal and are answers, not truncation:
+
+```ts
+/**
+ * `TableState` — you receive this, you don't construct it.
+ * Produced by `useTableCollection()` (also `useAmbassadorTable()`, `useTableContext()`).
+ * Look `TableState` up in the bundle index for its own API.
+ */
+declare class TableState<T, F> {
+}
+```
+
+An empty body with a **"Produced by"** note means: call that hook or factory to get one. That is usually the whole answer — `<Table state={...}>` needs `useTableCollection()`, not `TableState`'s internals. If you do need its members (`state.toolbar`, `state.visibleColumns`), it has its own index entry — look the name up and read that bundle, where its body is complete.
+
+A stub saying **"cut here because it has its own bundle"** means the same thing for a shape you *do* write: it wasn't copied in twice, so look the name up and read its own file.
+
+Every bundle fits in a single read; the index's `bytes` field says how big before you open it. So a bundle is never partially shown — if something looks missing, it was cut on purpose and the stub names where to find it.
+
+A handful of names carry `"status": "unreachable"` with a message saying not to import them (the `...BaseProps` interfaces a component's props `extends`). Read those for the props they contribute; don't write an import for them.
+
+## Subpath entry points
+
+`@wix/patterns` is 31 entry points, not one namespace, and `/form` re-exports `@wix/bex-core/form`. To see what's importable from a specific one: `Read <pkgRoot>/dist/dts-bundle/exports/<subpath>.d.ts` directly (`.` is `exports/index.d.ts`; a nested one like `./testkit/backend` is `exports/testkit/backend.d.ts`). This only lists the curated names covered above — a file with nothing in it (a one-line comment) means no curated name lives on that subpath yet, not that the subpath doesn't exist.
+
+## Following cross-references
+
+Docs link to related names as Storybook URLs (`[TableState](./?path=/story/...--tablestate)`) — resolve the link text back to a filename via `dist/docs/index.json`, the same way you found the first doc, and `Read` it if you actually need it. There's no automatic multi-level expansion here; follow only the links you need.
+
+Links to `https://www.docs.wixdesignsystem.com/` are external (Wix Design System) — not part of `@wix/patterns` docs. Likewise, a bundled `.d.ts` that references a deep `@wix/design-system/dist/...` path is pointing at that library's own internals — look the name up via the `wix-design-system` skill's own tool, not by opening the path.
+
+## Tips
+
+- **Compound components** have separate docs per sub-part: `CollectionPage.md`, `CollectionPage.Header.md`, `CollectionPage.Content.md`.
+- **Hook docs** list configuration options as props in the API table.

package/skills/wix-app/references/dashboard-page/UX_SUCCESS_MODEL.md

@@ -0,0 +1,184 @@
+# Dashboard UX Success Model
+
+What makes a generated dashboard page actually *succeed* for the person using it. Use this to turn a vague prompt ("help me manage order exceptions") into concrete requirements, and as the checklist before calling a dashboard done.
+
+Ported from the FeatureVibe dashboard product doc.
+
+> **North Star.** A successful dashboard helps a site owner or collaborator **understand what matters, complete the intended task, and trust the result**. It fulfills the user's prompt through a clear workflow, the right presentation, and trustworthy business data.
+
+This file is about *what to build*. For *how* to build it, see [WDS_LAYOUT.md](WDS_LAYOUT.md) for content layout and [DASHBOARD_PAGE.md](../DASHBOARD_PAGE.md) for the `@wix/patterns` → `@wix/design-system` component order — the workflow stages below are user needs, not an excuse to hand-roll shells, tables, or filter bars.
+
+
+## The Success Model
+
+A generated dashboard succeeds across three connected dimensions.
+
+| Success dimension | What must be true |
+|---|---|
+| Workflow success | The dashboard supports a complete journey from understanding to a confirmed outcome. |
+| Presentation success | Information is shown clearly and in the format that best supports the task. |
+| Data success | Information is accurate and consistent, including when it comes from multiple sources. |
+
+
+## The Workflow Journey
+
+The prompt defines the outcome. The stages define the journey from understanding the situation to confirming the result. They are **user needs**, not necessarily separate screens or a rigid sequence.
+
+| Stage | User outcome |
+|---|---|
+| **Understand** | Know the current situation. |
+| **Focus** | Recognize what matters or requires attention. |
+| **Investigate** | Access the details needed to decide. |
+| **Act** | Complete the intended business task. |
+| **Feedback** | See that the action succeeded and the state changed correctly. |
+
+### 1. Understand
+
+**Intent:** Help the user understand the business area this dashboard supports, what the data represents, and how to interpret it.
+
+- Present the most important totals, trends, and status indicators.
+- Make scope, time range, and freshness clear.
+- Distinguish no data, loading, access, connection, and system problems.
+- Connect summaries to underlying items.
+
+**Success:** The user can explain what is happening now.
+
+### 2. Focus
+
+**Intent:** Help the user recognize what matters or requires attention.
+
+- Choose the view that best supports the task.
+- Reduce noise through hierarchy, search, filters, sorting, saved views, and alerts.
+- Explain empty results and offer a useful next step.
+- Make the most important next action clear.
+
+**Success:** The user knows where to direct attention and what to do next.
+
+### 3. Investigate
+
+**Intent:** Give the user enough context to make a confident decision.
+
+- Reveal detail progressively without making users lose their place.
+- Show related information, history, and meaningful connections.
+- Make missing, unmatched, or uncertain information visible.
+
+**Success:** The user can understand why something happened and decide how to respond.
+
+### 4. Act
+
+**Intent:** Let the user complete the intended business task.
+
+- Provide the actions required by the prompt and allowed by permissions.
+- Support individual and bulk actions when both are useful.
+- Make consequences clear and protect against destructive mistakes.
+
+**Success:** The user can complete the task without leaving the workflow or guessing what to do.
+
+### 5. Feedback
+
+**Intent:** Confirm that the action succeeded and the business state changed correctly.
+
+- Provide immediate feedback after an action.
+- Refresh relevant items, summaries, counts, filters, and views.
+- Keep status and history visible when users may need to return later.
+
+**Success:** The user can see the confirmed result everywhere it matters.
+
+
+## The 5 WHATs
+
+How to gain enough context to ensure a complete workflow. Translate each prompt into concrete journey requirements:
+
+- What outcome is the user trying to achieve?
+- What must they understand before acting?
+- What requires deeper investigation?
+- Which actions must be available?
+- What visible result will confirm success?
+
+> **Example:** "Help me manage order exceptions" requires an overview of open issues, ways to focus on urgent cases, enough order context to decide, actions to resolve each issue, and confirmation that resolved items leave the active list.
+
+
+## Presentation Success
+
+Presentation success applies across all five stages. Choose both the right **representation** and the right **interaction surface**, while keeping hierarchy, meaning, and state consistent.
+
+### Choosing the Right View
+
+| View | Use when… | Success looks like… |
+|---|---|---|
+| **Table** | Users compare many records across several attributes. | Records are easy to scan, compare, filter, select, and act on. |
+| **Gallery** | Visual recognition is central. | Images identify items while key status and actions remain visible. |
+| **List** | Items have one dominant identity and limited supporting detail. | Users scan quickly without unnecessary density. |
+| **Kanban** | Work moves through meaningful stages. | Stage, workload, and valid movement are understandable. |
+| **Timeline or calendar** | Time, sequence, or scheduling matters. | Upcoming activity, conflicts, and timing are clear. |
+| **Chart** | The user needs to understand a trend or relationship. | The visualization answers a specific business question. |
+| **Summary metrics** | The user needs a quick health signal. | Metrics clarify current conditions and where to focus. |
+
+- Choose the default view that best supports the primary task.
+- Offer another view only when it provides distinct value.
+- Keep filters, state, and meaning consistent when users change views.
+- Connect summaries and visualizations back to the relevant records.
+
+### Choosing the Right Drill-In
+
+Choose the smallest interface that gives users enough context and room to complete the task. These are defaults, not rigid rules.
+
+| Interface | Use when… | Success looks like… |
+|---|---|---|
+| **Side panel** | The user should review or update one item while keeping the dashboard visible. | Context is preserved while deeper work remains focused. |
+| **Modal** | The user needs to complete a focused, bounded task or decision. | Attention stays on one task and the user can return cleanly. |
+| **Entity page** | The task involves complex details, multi-section editing, history, or related information. | The user has enough space and structure to complete deeper work. |
+| **Inline or expanded row** | The user needs a quick inspection or simple action. | Detail appears without creating a separate workspace. |
+
+Which Wix primitive builds each of these — and which components serve the summaries, filters and empty states named above — is in [Collection Toolkit](COLLECTION_TOOLKIT.md). Patterns has no side panel; that one is WDS.
+
+
+## Data Success
+
+Data success means giving users a complete and trustworthy view of the business. A dashboard may rely on one source or connect related customer, transaction, payment, and operational data.
+
+### Major Data Sources
+
+| Data source | What it provides |
+|---|---|
+| **CMS** | Custom collections, items, references, and custom business records. |
+| **Stores** | Products, variants, categories, inventory, and locations. |
+| **eCommerce** | Carts, checkouts, orders, line items, and fulfillment. |
+| **Bookings** | Services, appointments, classes, courses, staff, availability, and attendance. |
+| **Contacts and Members** | Customer identity, profiles, labels, roles, and audience context. |
+| **Payments and Pricing Plans** | Transactions, refunds, payouts, plans, subscriptions, and renewals. |
+| **Events** | Events, tickets, registrations, guests, and check-ins. |
+| **Other connected sources** | Restaurants, Forms, Invoices, Programs, and external systems. |
+
+### What Must Succeed Across Sources
+
+| Requirement | User outcome |
+|---|---|
+| **Meaningful relationship** | Sources combine around the business item or decision the user cares about. |
+| **Consistent meaning** | Shared concepts use understandable and consistent language. |
+| **Clear gaps** | Missing or unmatched information is visible rather than silently ignored. |
+| **Trusted actions** | Actions update the correct source and the result appears everywhere relevant. |
+| **Right level of combination** | Related items may be combined; useful but distinct sources remain separate. |
+
+> The goal is not to merge everything. Combine sources when the relationship helps users understand or act; otherwise keep them separate but connected.
+
+### Multi-Source Examples
+
+| Single view | Primary record | Connected sources | User outcome |
+|---|---|---|---|
+| **Order exceptions** | eCommerce order | Payments, Contacts, Stores | Resolve unpaid, delayed, or incorrect orders from one queue. |
+| **Booking follow-up** | Booking or appointment | Bookings, Contacts, Payments | Find missed or unpaid appointments and contact the client. |
+
+
+## Evaluation
+
+Rendering is not enough. A successful dashboard passes every check below.
+
+- [ ] **Prompt fulfilled:** The main result requested by the user is delivered.
+- [ ] **Task completion:** The intended task works from entry to confirmed result.
+- [ ] **Presentation fit:** Layout, actions, and empty states make the task easy to understand and complete.
+- [ ] **Trusted data:** All sources and views form one accurate picture of the business.
+- [ ] **Consistent results:** Actions, filters, views, summaries, and details agree.
+- [ ] **Business fit:** The experience matches the user's context, role, and permissions.
+
+> **Final evaluation question.** Does this dashboard give the user a **clear, trustworthy, and effective** way to accomplish what they asked for?

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

@@ -205,21 +205,21 @@ Wire the named part completely:
 
 ## 4. Suppress Autoplay in `component.preview.tsx`
 
-The Wix CLI scaffold generates `component.preview.tsx`. For animated components,
-modify its passthrough preview component without replacing the generated
-defaults or fallback-placeholder wiring.
+The Wix CLI scaffold generates `component.preview.tsx`. Read the file first,
+then edit only the body of the existing preview component. Do not overwrite
+the file from scratch.
 
-### Adapt the generated `component.preview.tsx`
+### Edit the generated `component.preview.tsx`
 
-Add `useIsEditMode` to the existing `@wix/react-component-utils` import. In the
-generated preview component, replace only the passthrough return with the gated
-props below. Keep the generated `withFallbackPlaceholder`, required-data fields,
-root class, and `withDefaults` export unchanged.
+Add `useIsEditMode` to the existing `@wix/react-component-utils` import. Then
+edit only the body of the existing `ComponentNamePreview` function — add the
+`isEditMode` check and gate the autoplay props. Do not touch the
+`withFallbackPlaceholder` call, the `withDefaults` export, or any other part
+of the file.
 
 ```tsx
-const MyAnimationPreview: FC<ComponentProps<typeof Component>> = (props) => {
+const ComponentNamePreview: FC<ComponentProps<typeof Component>> = (props) => {
   const isEditMode = useIsEditMode();
-
   return (
     <Component
       {...props}
@@ -243,4 +243,5 @@ In preview mode (`isEditMode` is `false`) → both use the user's configured val
 - [ ] 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.
-- [ ] The preview preserves generated wrappers and forces autoplay off in design mode.
+- [ ] The preview exports the adapter with synchronized fallback metadata and
+      disables autoplay in design mode.

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

@@ -26,6 +26,7 @@ using CSS Modules `@value`, then consume with `var()`.
 **Body:** `wst-paragraph-1..3-font` / `wst-paragraph-1..3-color`
 
 - Do not use `var(--wst-*)` directly; import the `@value` alias first.
+- Do not pass a fallback as `var()`'s second argument
 - Do not use `@import`; CSS Modules resolves theme aliases through `@value`.
 - Do not use `wst-base-1-color` for text. Prefer heading/paragraph color tokens,
   or `wst-base-2-color` when a base contrast color is required.

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

@@ -0,0 +1,56 @@
+# Browser Support
+
+Which CSS features and DOM APIs an Editor React Component may use. This is about
+support in the visitor's browser, a separate question from whether an API exists
+during server rendering.
+
+## The rule
+
+**Use only features at Baseline "Widely Available", or ones that fall back to it** —
+supported for 30+ months in every browser [Wix
+supports](https://support.wix.com/en/article/supported-devices-browsers-and-operating-systems):
+Chrome (desktop + Android), Edge, Firefox (desktop + Android), Safari (macOS +
+iOS/iPadOS).
+
+A fallback must genuinely degrade rather than break: the unsupported path still
+has to render a usable component.
+
+## Deciding, without looking it up
+
+These rules resolve nearly everything. Stop at the first step that answers:
+
+1. **Named literally in the skill or repository instructions?** → pre-authorized:
+   use it, no warning. A string test, not a judgment call — `@property` in your
+   instructions authorizes it, a general endorsement of modern CSS authorizes
+   nothing. A feature named only in the *user's* request is **not** pre-authorized;
+   run the steps below, then the [insist protocol](#insist-protocol).
+2. **Date arithmetic.** Subtract 30 months from today's real date. Was it already
+   shipping in every browser above by then? Mobile lags — iOS Safari and Firefox
+   Android are the usual holdouts.
+3. **Smell test**, when that's inconclusive. Widely Available means *boring* for 2.5
+   years. Learned it as "the modern way", or would enjoy showing it off → no. Plain
+   CSS or DOM you'd have written five years ago → yes. Called "now Baseline"
+   anywhere → that phrasing marks *newly* available → no.
+4. **Still unsure → not permitted.** Permitting wrongly ships a component that is
+   broken for real visitors; denying wrongly costs only a slightly plainer
+   implementation the user can ask you to change.
+
+Search only when it earns the cost — the user asks about support directly, or the
+feature is central enough that deny-and-offer would waste a real round trip. Prefer
+fetching an MDN or caniuse page over driving a browser.
+
+**Standing exception:** `@property` is always fine for design tokens, generated or
+hand-written — rewriting a token registration, or warning about one, breaks the
+component.
+
+**Feels new, is not** — run the arithmetic, not the reputation: `:has()`,
+`@container` size queries, `subgrid`, `color-mix()`, `inert`,
+`Array.prototype.toSorted`.
+
+## Insist protocol
+
+1. **Build the widely-supported alternative** by default. Don't ask first, and don't
+   leave the component unbuilt.
+2. **Use the feature only if the user then asks for it explicitly**, and guard it so
+   it degrades rather than breaks — `@supports` for CSS, `CSS.supports()` or a
+   capability check for JS.

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

@@ -1,17 +1,22 @@
 # Editor Preview Entry
 
-Use this reference when `component.preview.tsx` must behave differently in
-Harmony Editor design mode than on the live site.
+Use this when creating a component or changing its data, root, or editor-only
+behavior.
 
-## Preserve the Generated Contract
+## Preserve the Structure, Synchronize the Contract
 
 The Wix CLI scaffold generates `component.preview.tsx` and wires its URL into
 the extension's editor resource. It includes `withDefaults`,
 `withFallbackPlaceholder`, required-data fields, and the root class name.
 
-Do not repeat or replace that boilerplate. Keep the generated wrappers and
-metadata, and change only the preview component when editor behavior must differ
-from live behavior.
+Keep the wrapper structure and synchronize its values:
+
+- Wrap the preview adapter when one exists; otherwise wrap `Component`.
+- In `requiredDataFields`, normally use only the one prop crucial to meaningful
+  rendering, such as `animationUrl`. Use more only when each is essential.
+- Set `rootClassName` to the elected root's exact global class, not `styles.root`.
+
+Never remove `withFallbackPlaceholder`.
 
 ## Detect Editor Design Mode
 
@@ -35,10 +40,13 @@ timers, or network activity while a site owner is designing.
 For autoplaying components, force autoplay off in editor design mode and keep
 the live/preview prop values unchanged.
 
+Export the adapter through `withFallbackPlaceholder` and synchronize its data
+field and root class.
+
 ## Checklist
 
-- [ ] Generated defaults and fallback-placeholder behavior remain intact.
-- [ ] Required data fields and root class metadata are unchanged.
+- [ ] Generated wrappers target the preview adapter when one exists.
+- [ ] Normally one crucial data field and the exact root global class are set.
 - [ ] The extension still loads the preview URL as its editor resource.
 - [ ] `useIsEditMode()` is called inside a component.
 - [ ] Live/preview behavior still receives the site owner's original props.

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

@@ -1,11 +1,13 @@
 # CSS Guidelines
 
 Use these rules for the scaffolded `<component-name>.module.css` file and any
-colocated CSS Modules owned by internal sub-components. Keep existing visual
-decisions outside the request unchanged. These rules keep the component
+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.
 
+**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.
+
 ## Contents
 
 - [Classes and Named Parts](#classes-and-named-parts)
@@ -177,6 +179,22 @@ 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.
 
+```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. */
+.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. */
+.cta-label {
+  font-size: 14px;
+}
+```
+
 ## Interaction and Motion
 
 - Set `pointer-events: auto` on the root and each interactive element.
@@ -194,20 +212,30 @@ and do not expose a visual prop solely for that purpose.
 
 ## Default Visual Quality
 
-When creating a component and the request has no visual direction, use a
-restrained accessible default. When editing an existing component, preserve its
-visual language unless the request changes it.
+Create a clear hierarchy with at least two techniques that fit the component:
+a defined surface, border or soft shadow, type scale or weight, spacing, an
+accent, or visible interaction states. Use these neutral defaults unless the
+request or existing design provides better values:
+
+- 16px or larger body text, 14px or larger labels, and 600–700 weight for titles
+- 8–16px spacing inside controls and 16–32px spacing inside containers
+- 8–12px corner radii for cards and controls; `50%` for circular media
+- a subtle border or soft shadow when a card, panel, or control needs separation
+- touch targets at least 44 by 44px and visible keyboard focus states
+
+### 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.
+
+- 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.
+- If an interactive state changes the background, set the foreground color in that state too. Don't assume a color inherited from a parent or from a previous state will still look right on the new background.
+- In every default and interactive state, meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI controls.
 
-- body text at least 16px and labels at least 14px
-- WCAG AA contrast (4.5:1 body text, 3:1 large text and UI controls)
-- touch targets at least 44 by 44px
-- clear hierarchy and visible focus states
-- generous but consistent spacing
-- transparent root backgrounds unless the design requires a surface
+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.
 
-Avoid prescribing a brand palette in a generic component. Only when the prompt
-explicitly requests branded or themed output, use its named brand tokens rather
-than hardcoded generic color choices.
 
 ## Checklist
 
@@ -220,4 +248,9 @@ than hardcoded generic color choices.
 - [ ] A sizing chain exists only on bounded growing axes.
 - [ ] Layout is container-driven and uses logical inline properties.
 - [ ] Static styling stays in CSS; custom properties exist only when needed.
+- [ ] Every part that sets `font-size` also sets `font-family`, on the part that
+      should own the typography control.
 - [ ] Interactive elements expose pointer events and accessible design states.
+- [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
+- [ ] Every explicit foreground has a known contrasting background; transparent
+      components inherit foregrounds from their host.

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

@@ -66,6 +66,9 @@ state class is the **prefixed** global one.
 ```css
 .cta {
   background: #6366f1;
+  font-family: 'Inter', sans-serif;
+  font-size: 14px;
+  color: #ffffff;
 } /* resting */
 .cta:global(.pricing-card-cta--hover),
 .cta:hover {