Wix Design System

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 (opens in a new tab) for the exact docs file layout and section shapes.

Quick Component Mapping (Design to WDS)

Spacing (px to SP conversion)

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

<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

1. 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.