wix-design-system — Claude Code skill: what it does, how to install
Inspects @wix/design-system components, props, code examples, and testkit drivers directly inside your project.
MIT 218 installs ★ 40 updated 2026-10-24
npx skills add wix/skills --skill wix-design-system -a claude-codeWhat wix-design-system does
The skill bundles scripts/wds.cjs, a Node.js helper that locates @wix/design-system inside node_modules across standard setups and monorepos. Your agent runs this script to search components with keywords, fetch prop definitions, pull JSX usage samples, and look up icons from @wix/wix-ui-icons-common.
For end-to-end testing, the helper extracts driver methods and import snippets for Playwright, Puppeteer, Unidriver, or vanilla DOM. When the helper script cannot run, the skill falls back to reading documentation files stored in node_modules/@wix/design-system/dist/docs/.
Running queries fails if @wix/design-system is not installed in the target repository. If components appear completely unstyled, import @wix/design-system/styles.global.css once at your application root.
What it helps with
- look up component prop types and JSX code snippets
- search UI elements by keyword across @wix/design-system
- retrieve testkit driver methods for Playwright or Puppeteer
- convert pixel values to WDS SP spacing tokens
- find icon names from @wix/wix-ui-icons-common
Example prompts for the agent
- Show me props and a loading state example for the Button component
- Find the right WDS component for a responsive dialog layout
- Get testkit imports and the click driver method for Button in Playwright
How to install wix-design-system
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-design-system -a claude-code2Manually: put the files in place
~/.claude/skills/wix-design-system/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/wix-design-system/
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-design-system -a codex2Manually: put the files in place
.agents/skills/wix-design-system/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-design-system -a cursor2Manually: put the files in place
.cursor/skills/wix-design-system/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wix/skills skills/wix-design-system2Manually: put the files in place
.github/skills/wix-design-system/SKILL.md1Skills CLI (Vercel)
npx skills add wix/skills --skill wix-design-system -a gemini-cli2Platform CLI
gemini skills install https://github.com/wix/skills --path skills/wix-design-systemManually: put the files in place
.devin/skills/wix-design-system/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wix/skills --skill wix-design-system -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about wix-design-system
How to install wix-design-system in Claude Code?
Run npx skills add wix/skills --skill wix-design-system -a claude-code in your terminal. This creates the skill file at ~/.claude/skills/wix-design-system/SKILL.md.
What does wix-design-system do?
It gives your coding agent instant access to Wix Design System props, layout tokens, JSX examples, and testkit driver APIs.
What is required before using this skill?
The @wix/design-system package must be installed in your project via npm i @wix/design-system or yarn add @wix/design-system, as the helper script searches local node_modules.
Source text
SKILL.md · MIT
---
name: wix-design-system
description: Wix Design System component reference. Use when building UI with @wix/design-system, choosing components, checking props and examples, or writing tests with component testkits. Triggers on "what component", "how do I make", "WDS", "show me props", "testkit", "driver", or component names like Button, Card, Modal, Box, Text.
metadata:
verified: true
---
# 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:
```bash
# 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
```bash
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
```bash
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:
```bash
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
```bash
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
```bash
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
```bash
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](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 |
```tsx
<Box gap="SP2" padding="SP3">
```
Only use SP tokens for `gap`, `padding`, `margin` — not for width/height.
## Imports
```tsx
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.
© wix · MIT · wix/skills