wix-design-system

A lookup for Wix's own kit of ready-made interface pieces — buttons, cards, modals, icons — with the settings each one takes and code that already works, so a screen ends up looking like the rest of Wix.

WHEN TO USE

SCOPE

USE FOR

Find which Wix Design System component matches a need, like a table, modal, or form input.
Get a component's full list of props and a working example before writing it into a page.
Look up how to write a test against a Wix component using its official testkit driver.
Convert a designer's pixel spacing value into the matching Wix Design System spacing token.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (8)

WDS Documentation Navigator

Prerequisite: @wix/design-system must be installed (npm i @wix/design-system or yarn add @wix/design-system).

Helper Script

This skill bundles scripts/wds.cjs — a Node.js helper that auto-discovers @wix/design-system in node_modules (handles monorepos and workspaces) and provides focused lookups. Run it from the user's project directory using the absolute path to the bundled script:

# WDS is the absolute path to this skill's scripts/wds.cjs
WDS="<this-skill-dir>/scripts/wds.cjs"

node $WDS search <keyword>                 # Find components by keyword
node $WDS component <Name>                 # Get props + example list (one component)
node $WDS components <Name1> <Name2>...    # Same as `component`, but for several at once
node $WDS example <Name> "<ExampleName>"   # Get a specific example
node $WDS testkit <Name> [method]          # Get testkit imports + driver API
node $WDS icons <query>                    # Search for icons

Workflow

Step 1: Find the right component

node $WDS search table
node $WDS search form input validation
node $WDS search modal dialog popup

Multiple keywords are OR-matched. Returns component names, descriptions, and usage guidance.

Step 2: Get props and available examples

node $WDS component Button

Returns the full props list (types and descriptions) plus a list of all available examples. For large prop files (>200 lines), returns a summary with prop names and types.

If you already know which several components you'll need (e.g. after Step 1 returned a shortlist), prefer the batch form to avoid one round-trip per component:

node $WDS components Button Card Table Input Text Thumbnail

Output is each component's props block separated by ---. Missing components are logged to stderr and skipped; the command only fails if every requested component is missing.

Step 3: Get a specific example

node $WDS example Button "Loading state"

Returns the example description and JSX code. Matching is case-insensitive and supports substrings (e.g., "loading" matches "Loading state").

Step 4: Write tests with the component testkit

node $WDS testkit Button             # Imports + full driver API for Button
node $WDS testkit Button click       # Just the click() method details

Returns import snippets for unidriver, vanilla, puppeteer, and playwright flavors plus the driver method API (name, args, return type, description). Method name matching is case-insensitive substring.

Step 5: Find icons

node $WDS icons Add Edit Delete

Icons are from @wix/wix-ui-icons-common. Each icon has a Small variant (e.g., Add + AddSmall).

Fallback: Direct File Access

If the script is unavailable, docs are at node_modules/@wix/design-system/dist/docs/:

components.md — component catalog (~978 lines, grep only)
components/{Name}Props.md — props per component
components/{Name}Examples.md — examples per component (grep ^### for section list)
components/{Name}Testkit.md — testkit imports + driver API per component (grep ^### for method list)
testkits.md — testkit catalog (list of components with generated testkit docs)
icons.md — icon catalog (~818 lines, grep only)

Don't read these files fully. Grep for keywords, then read specific sections with offset/limit. See references/file-structure.md for the exact docs file layout and section shapes.

Quick Component Mapping (Design to WDS)

Design Element	WDS Component	Notes
Rectangle/container	`<Box>`	Layout wrapper
Text button	`<TextButton>`	Secondary actions
Input with label	`<FormField>` + `<Input>`	Wrap inputs
Toggle	`<ToggleSwitch>`	On/off settings
Modal	`<Modal>` + `<CustomModalLayout>`	Use together
Grid	`<Layout>` + `<Cell>`	Responsive

Spacing (px to SP conversion)

When designer specifies pixels, convert to the nearest SP token:

Token	Classic	Studio
`SP1`	6px	4px
`SP2`	12px	8px
`SP3`	18px	12px
`SP4`	24px	16px
`SP5`	30px	20px
`SP6`	36px	24px

<Box gap="SP2" padding="SP3">

Only use SP tokens for gap, padding, margin — not for width/height.

Imports

import { Button, Card, Image } from "@wix/design-system";
import { Add, Edit, Delete } from "@wix/wix-ui-icons-common";

GUIDELINES

Don't ever override WDS CSS tokens. Only if it's not possible otherwise, mention that very clearly to the prompter, that this is an anti-pattern and should be avoided at all costs.

Troubleshooting

Components render unstyled (plain HTML look, missing WDS spacing/typography): add import "@wix/design-system/styles.global.css"; once to the root/main component (e.g. page.tsx, modal entry) — not child/tab/helper files.

Local tool required

1 FOR THE AGENT

01
Install @wix/design-system in the project
Run npm i @wix/design-system (or yarn add @wix/design-system) so the bundled lookup script can auto-discover the library in node_modules before it can look up any component, prop, or example.
```
npm i @wix/design-system
```
```
yarn add @wix/design-system
```

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

This skill ships inside the Wix Skills plugin. Listed package contents include an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add wix/skills --skill "wix-design-system" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Wix Skills plugin package selected for your AI tool.

PLUGIN MARKETPLACE

Add the marketplace, then install the plugin

Typed inside the agent's own prompt, not in a terminal. The marketplace is called wix, which is the part after the @.

01
```
/plugin marketplace add wix/skills
```
02
```
/plugin install wix@wix
```

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

Same repository

replatform
Routes RePlatform source-to-Wix migrations to the next workflow step by inspecting migration project artifacts. Use when starting, continuing, or recovering a migration run.Read full description
wix-app
Build and review Wix CLI app extensions — dashboard pages, modals, plugins, menu plugins, custom element widgets, Editor React components, site plugins, embedded scripts, backend APIs, backend events, service plugins, data collections, and App Market readiness. Use when building ANY feature or extension for a Wix CLI app or preparing a Wix app for App Market review. Triggers on: add, build, create, implement, help me, dashboard, widget, plugin, backend, API, event, collection, embedded script, service plugin, Editor React component, checkout, shipping, tax, discount, SPI, CMS, schema, tracking, popup, admin panel, menu item, modal, validate, test, verify, register extension, App Market, app review, submission readiness.Read full description
wix-base44-connector
Build on and manage the connected Wix site from a Base44 app: discover and call any Wix API (endpoints, request/response shapes, fields), gather site context, route each call to the right identity, and follow curated recipes for admin tasks.Read full description
wix-docs
Look up the Wix API/SDK documentation to confirm an exact endpoint, HTTP method, request/response shape, field, enum, or error before writing Wix code — never guess a Wix API from memory. A lookup is a short flow: find the right page, then read it. Two ways: (1) plain curl (zero dependencies) — find a page by **semantic search** (POST /mcp-docs-search/v1/docs/search, natural-language { search_term, document_type(s) }, incl. the SKILLS recipe corpus for multi-step workflows) **or by browsing** a docs portal as a menu — a structured, typed, counted browse of the REST, SDK, CLI, Build Apps, and Headless portals (POST /mcp-docs-search/v1/docs/menu/browse), or the .md menu tree from the llms.txt root for any surface — then read the page by appending .md to its URL; (2) the Wix MCP doc tools when present. Triggers: look up a Wix API, find the Wix endpoint/method, confirm a Wix request body or field, verify a Wix API shape, explore Wix docs, which Wix API do I call, read a Wix method schema.Read full description
wix-headless
Connect Wix business services (Stores, Bookings, CMS, Blog, Events, Forms, and more) to a Wix Headless frontend — infer the needed capabilities, install the apps, seed backend content, and produce an SDK-integration guide. For managed (Wix-hosted) projects it can also build the frontend: scaffold a new site (create) or wire an existing/brought-in design (connect), then build and release. Works across managed, self-managed, and stripe project types. Triggers: set up a Wix Headless backend, add Wix business features to my app, build or host a Wix site, connect/implement this design with Wix.Read full description
wix-headless-kit
Build a Wix Headless site fast by wiring SHIPPED, verified @wix/sdk code instead of authoring the integration from recipes. Each Wix business vertical ships a typed, framework-agnostic React core (data layer returning plain DTOs, hooks, headless components) plus an Astro overlay (SSR pages with owner-editable SEO pre-wired) and a build-time REST seed script — the agent scaffolds via the Wix CLI, deploys the shipped code, seeds the backend, designs the presentation layer itself on the shipped hooks (product card/grid, PDP, home, theme), and releases to Wix hosting. Works on Wix-managed Astro (ambient auth, the default) and on any React-based project (Vite, non-Astro) over the public OAuth client id. Verticals: stores/storefront (products, categories, variants, cart, hosted checkout), bookings (services, appointment/class time slots, staff, booking form, checkout-or-place), rentals (rooms, vehicles, gear by the hour or the day: resources, customer-picked length, priced quote, checkout), blog (posts, categories/tags, rich content), cms (structured content collections), forms (schema-driven visitor forms: render, validate, submit), events (listing, RSVP, ticket sales), members (login, gated pages, account), portfolio (project collections, media galleries), pricing-plans (plan grid, hosted purchase), restaurants (menus, online ordering, table reservations), faq (categorized questions and answers, search, a link per question), donations (campaign pages, goal progress, one-time and recurring donations via hosted checkout). Triggers: build me a store/blog/booking/rental/event/restaurant/portfolio/FAQ/donation site fast, take appointments fast, rent out rooms/cars/equipment headless, sell tickets or membership plans headless, collect donations headless, wix headless kit, connect a Wix business app with ready-made SDK code.Read full description