wix-design-system

WDS 文档导航器

**前提条件：**必须安装 @wix/design-system（npm i @wix/design-system 或 yarn add @wix/design-system）。

辅助脚本

此技能包含 scripts/wds.cjs——一个 Node.js 辅助工具，可自动在 node_modules 中发现 @wix/design-system（支持 monorepo 和工作区），并提供针对性的查询。从用户的项目目录运行此脚本，并使用捆绑脚本的绝对路径：

# 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

工作流

步骤 1：查找合适的组件

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

多个关键词采用 OR 匹配。返回组件名称、描述和使用指南。

步骤 2：获取属性和可用示例

node $WDS component Button

返回完整的属性列表（类型和描述），以及所有可用示例的列表。对于较大的属性文件（>200 行），返回包含属性名称和类型的摘要。

如果你已经知道需要哪些组件（例如步骤 1 返回了候选列表），优先使用批量形式，避免每个组件都单独往返一次：

node $WDS components Button Card Table Input Text Thumbnail

输出中，每个组件的属性块以 --- 分隔。缺失的组件会记录到 stderr 并跳过；只有当所有请求的组件都缺失时，命令才会失败。

步骤 3：获取特定示例

node $WDS example Button "Loading state"

返回示例说明和 JSX 代码。匹配不区分大小写，并支持子字符串（例如，“loading”可匹配“Loading state”）。

步骤 4：使用组件 testkit 编写测试

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

返回 unidriver、vanilla、puppeteer 和 playwright 类型的导入代码片段，以及 driver 方法 API（名称、参数、返回类型、描述）。方法名称匹配不区分大小写，并按子字符串匹配。

步骤 5：查找图标

node $WDS icons Add Edit Delete

图标来自 @wix/wix-ui-icons-common。每个图标都有一个 Small 变体（例如，Add 和 AddSmall）。

后备方案：直接访问文件

如果脚本不可用，文档位于 node_modules/@wix/design-system/dist/docs/：

• components.md — 组件目录（约 978 行，仅使用 grep）
• components/{Name}Props.md — 各组件的属性
• components/{Name}Examples.md — 各组件的示例（使用 grep ^### 查找章节列表）
• components/{Name}Testkit.md — 各组件的 testkit 导入代码和 driver API（使用 grep ^### 查找方法列表）
• testkits.md — testkit 目录（列出有生成的 testkit 文档的组件）
• icons.md — 图标目录（约 818 行，仅使用 grep）

不要完整读取这些文件。先用 grep 搜索关键词，再通过偏移量和限制值读取特定章节。有关文档文件的确切布局和章节结构，请参阅 references/file-structure.md。

---

快速组件映射（设计到 WDS）

设计元素	WDS 组件	备注
矩形/容器	<Box>	布局包装器
文本按钮	<TextButton>	次要操作
带标签的输入框	<FormField> + <Input>	包装输入框
切换开关	<ToggleSwitch>	开/关设置
模态框	<Modal> + <CustomModalLayout>	搭配使用
网格	<Layout> + <Cell>	响应式

间距（px 到 SP 的转换）

当设计师指定像素值时，转换为最接近的 SP 令牌：

令牌	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">

仅对 gap、padding、margin 使用 SP 令牌，不要用于宽度/高度。

导入

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

指南

1. 绝不要覆盖 WDS CSS 令牌。只有在别无他法时，才明确告知提示者这是反模式，应不惜一切代价避免。

故障排除

• 组件渲染时没有样式（呈现为普通 HTML 样式，缺少 WDS 间距和排版）：在根组件/主组件（例如 page.tsx、模态框入口）中添加一次 import "@wix/design-system/styles.global.css";，不要添加到子组件、选项卡或辅助文件中。