datocms-plugin-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DatoCMS Plugin Design System

DatoCMS插件设计系统

This skill turns plugin UI work into native-feeling DatoCMS UI work. Use it when the main problem is visual fit, structure, density, or styling — not when the main problem is wiring hooks or scaffolding a new plugin.

Typical requests this skill should own:

“Make this plugin config screen feel native to DatoCMS”
“Restyle this sidebar panel to match the DatoCMS dashboard”
“Use raw CSS so this plugin page looks like a first-party DatoCMS screen”
“Tighten the spacing and hierarchy in this plugin modal”
“Choose
```
datocms-react-ui
```
components that best match the CMS UI”

本技能可将插件UI改造为具有DatoCMS原生质感的UI。当核心需求是视觉适配、结构调整、密度优化或样式设计时使用本技能——若核心需求是钩子连接或搭建新插件框架，则不适用。

本技能应处理的典型请求：

“让这个插件配置界面具有DatoCMS原生质感”
“重新设计这个侧边栏面板，使其匹配DatoCMS仪表盘风格”
“使用原生CSS让这个插件页面看起来像DatoCMS官方页面”
“调整这个插件模态框的间距和层级结构”
“选择最匹配CMS UI的
```
datocms-react-ui
```
组件”

Step 1: Detect context silently

步骤1：静默检测上下文

Identify whether the target is:
- an existing plugin project
- a greenfield plugin scaffold
- a single screen or surface inside a larger plugin
Identify the touched surface:
- config screen
- page
- sidebar panel
- full sidebar
- modal
- outlet
- inspector
- asset source
Check whether the project already uses
```
datocms-react-ui
```
.
Check whether the requested change is primarily:
- visual restyling
- layout restructuring
- control selection
- theme alignment
- density cleanup
Read the smallest existing UI slice before changing anything:
- the entrypoint for the surface
- the component being restyled
- its local CSS or CSS module
- ```
package.json
```
  only if component availability is unclear

Ask nothing unless the repo cannot tell which surface or plugin repo is being changed.

确定目标类型：
- 现有插件项目
- 全新插件框架
- 大型插件中的单个界面或区域
确定涉及的界面区域：
- 配置界面
- 页面
- 侧边栏面板
- 完整侧边栏
- 模态框
- 嵌入区域
- 检查器
- 资源源
检查项目是否已使用
```
datocms-react-ui
```
。
确定请求的核心变更类型：
- 视觉重设计
- 布局结构调整
- 控件选择
- 主题对齐
- 密度优化
在修改前查看最小范围的现有UI代码：
- 目标区域的入口文件
- 待重设计的组件
- 其本地CSS或CSS模块
- 仅在组件可用性不明确时查看
```
package.json
```

除非无法从仓库判断涉及哪个界面或插件仓库，否则无需询问任何问题。

Step 2: Choose the implementation path

步骤2：选择实现路径

Use the narrowest path that keeps the result native.

选择最精简的路径，确保最终效果与原生UI一致。

A. Public component path first

A. 优先使用公开组件路径

Choose this when

datocms-react-ui

already exposes the control or layout primitive you need.

Prefer it for:

```
Canvas
```
form wrappers and grouped settings
standard fields
buttons and button groups
sections
toolbar and header structure
sidebar panels
dropdowns
spinners and loading states
split layouts with
```
VerticalSplit
```
when available

当

datocms-react-ui

已提供所需的控件或布局基础组件时，选择此路径。

优先用于：

```
Canvas
```
表单包装器和分组设置
标准字段
按钮和按钮组
区块
工具栏和头部结构
侧边栏面板
下拉菜单
加载动画和加载状态
可用
```
VerticalSplit
```
实现的拆分布局

B. Raw React + CSS fallback

B. 原生React + CSS备选方案

Choose this when the public package does not expose the needed layout or when exact CMS composition matters more than a near match.

Use raw code for:

page shells that need CMS-like spacing but not a full custom component library
list and table wrappers plus lightweight summary rows
special empty states or info blocks
split or two-pane layouts when the installed UI package version does not provide a fitting primitive
surface-specific wrappers that only need theme variables and clean CSS

Do not import private CMS styles or private CMS class names into plugins. Recreate the structure with plugin-local CSS using Canvas variables.

当公开组件库未提供所需布局，或需要完全匹配CMS结构而非近似效果时，选择此路径。

使用原生代码实现：

需要CMS风格间距但无需完整自定义组件库的页面框架
列表和表格包装器及轻量级摘要行
特殊空状态或信息块
已安装的UI组件库版本未提供合适基础组件的拆分或双窗格布局
仅需主题变量和简洁CSS的特定区域包装器

不得将CMS私有样式或私有类名导入插件。使用Canvas变量通过插件本地CSS重现结构。

Step 3: Load the minimum references

步骤3：加载最少的参考资料

Always start with:

```
references/foundations.md
```
```
references/datocms-react-ui-bridge.md
```

Load

references/source-map.md

only when the public docs plus the current plugin code are not enough and you need local visual calibration from a CMS checkout.

Then load only the touched reference:

layout or page structure ->
```
references/layouts.md
```
forms, settings screens, controls ->
```
references/forms-and-controls.md
```

tabs, dropdowns, tables, notices, blank slates ->

references/navigation-feedback-and-data-display.md

hook-specific screen shape and sizing ->
```
references/plugin-surfaces.md
```
raw CSS implementation ->
```
references/raw-css-fallbacks.md
```

Do not load the whole bundle for a small restyle.

始终从以下资料开始：

```
references/foundations.md
```
```
references/datocms-react-ui-bridge.md
```

仅当公开文档和当前插件代码不足以满足需求，且需要从CMS本地检出版本进行视觉校准，才加载

references/source-map.md

。

然后仅加载与修改相关的参考资料：

布局或页面结构 ->
```
references/layouts.md
```
表单、设置界面、控件 ->
```
references/forms-and-controls.md
```
标签页、下拉菜单、表格、提示、空白状态 ->
```
references/navigation-feedback-and-data-display.md
```
钩子相关的界面形状和尺寸 ->
```
references/plugin-surfaces.md
```
原生CSS实现 ->
```
references/raw-css-fallbacks.md
```

小范围重设计无需加载全部参考资料。

Step 4: Build native-looking UI

步骤4：构建原生风格UI

Keep these guardrails:

Match DatoCMS density before inventing layout.
Use project theme variables from
```
<Canvas>
```
instead of hardcoded brand colors.
Prefer 1px borders, 3-5px radii, and subtle shadow only where the CMS uses it.
Keep page widths, toolbar heights, section spacing, and form rhythm close to the CMS source of truth.
Use one primary action per section or screen.
Keep destructive actions isolated.
Use labels above controls, hints below, and concise error text.
Favor sections, toolbars, sidebars, and tables over decorative cards.
Avoid hero blocks, KPI grids, ornamental copy, oversized rounded corners, heavy gradients, and dashboard filler.
Keep custom CSS local to the plugin and variable-driven.
If a public component is close but incomplete, compose around it instead of replacing all controls.

When a user asks for a plugin UI that “looks native”, optimize in this order:

structure
spacing
typography
color and theming
control choice
micro-interactions

遵循以下准则：

在自定义布局前先匹配DatoCMS的密度。
使用
```
<Canvas>
```
提供的项目主题变量，而非硬编码品牌颜色。
仅在CMS使用的位置使用1px边框、3-5px圆角和柔和阴影。
保持页面宽度、工具栏高度、区块间距和表单节奏与CMS基准一致。
每个区块或界面仅保留一个主要操作按钮。
隔离破坏性操作。
控件上方使用标签，下方使用提示，错误文本简洁明了。
优先使用区块、工具栏、侧边栏和表格，而非装饰性卡片。
避免英雄区块、KPI网格、装饰性文案、超大圆角、厚重渐变和仪表盘填充内容。
保持自定义CSS本地化且由变量驱动。
若公开组件接近需求但不完整，可基于其进行组合，而非替换所有控件。

当用户要求插件UI“看起来像原生”时，按以下优先级优化：

结构
间距
排版
颜色与主题
控件选择
微交互

Step 5: Verify

步骤5：验证

Run the smallest useful verification in the target plugin repo:

the repo's existing build script (
```
npm run build
```
,
```
pnpm build
```
, etc.) by default
or the nearest existing typecheck or build command

Then name the one manual UI check that matters most for the surface:

config screen -> spacing, section grouping, primary action placement
page -> toolbar or header rhythm and scroll behavior
sidebar panel -> density and collapsed or open behavior
modal -> focus, width, and action hierarchy
outlet -> inline fit with surrounding CMS UI
asset source -> search or result rhythm and sizing
inspector or full sidebar ->
```
noAutoResizer
```
and two-pane behavior if present

在目标插件仓库中执行最有效的验证：

默认执行仓库现有的构建脚本（
```
npm run build
```
、
```
pnpm build
```
等）
或执行最接近的类型检查或构建命令

然后指定针对该界面最重要的手动UI检查项：

配置界面 -> 间距、区块分组、主要操作按钮位置
页面 -> 工具栏或头部节奏及滚动行为
侧边栏面板 -> 密度及折叠/展开行为
模态框 -> 焦点、宽度和操作层级
嵌入区域 -> 与周边CMS UI的内联适配度
资源源 -> 搜索或结果的节奏与尺寸
检查器或完整侧边栏 -> 若存在
```
noAutoResizer
```
则检查其行为及双窗格表现

Cross-skill routing

跨技能路由

New plugin project or new plugin folder ->
```
datocms-plugin-scaffold
```
Existing plugin feature work, hook wiring, parameter logic, or surface behavior ->
```
datocms-plugin-builder
```
Mixed tasks are normal:
- use this skill for native DatoCMS UI choices
- pair with scaffold or builder for hook wiring or project setup
Standalone CMA work outside plugin UI ->
```
datocms-cma
```
Front-end site integration work ->
```
datocms-frontend-integrations
```

新插件项目或新插件文件夹 ->
```
datocms-plugin-scaffold
```
现有插件功能开发、钩子连接、参数逻辑或界面行为 ->
```
datocms-plugin-builder
```
混合任务属正常情况：
- 使用本技能处理DatoCMS原生UI相关选择
- 搭配框架搭建或插件构建技能处理钩子连接或项目设置
插件UI之外的独立CMA工作 ->
```
datocms-cma
```
前端站点集成工作 ->
```
datocms-frontend-integrations
```