vtex-io-admin-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Admin React Interfaces

管理端React界面

When this skill applies

本规范适用场景

Use this skill when building administrative React interfaces for VTEX Admin experiences.

Settings pages
Moderation tools
Internal dashboards
Operational forms and tables

Do not use this skill for:

storefront components
render-runtime blocks
route authorization design
backend service structure

当你为VTEX Admin构建管理类React界面时遵循本规范。

设置页面
审核工具
内部仪表盘
运营类表单和表格

本规范不适用于：

店铺前端组件
render-runtime区块
路由权限设计
后端服务结构

Decision rules

决策规则

Use VTEX official design systems for admin interfaces.
Prefer
```
vtex.styleguide
```
as the default choice for VTEX IO admin apps published to customers.
Accept
```
@vtex/shoreline
```
as an official VTEX design system, especially in internal back-office contexts.
Prefer core Styleguide layout patterns such as
```
Layout
```
,
```
PageHeader
```
, and
```
PageBlock
```
for page composition.
Prefer Styleguide building blocks for common admin needs:
```
Table
```
,
```
Input
```
,
```
Dropdown
```
,
```
Toggle
```
,
```
Tabs
```
,
```
Modal
```
,
```
Spinner
```
, and
```
Alert
```
.
Keep admin screens focused on operational clarity rather than storefront styling concerns.
Prefer explicit loading, empty, and error states for data-heavy admin pages.
Use button loading states and toast-based feedback for async actions so users can tell when a mutation starts, succeeds, or fails.
Prefer internationalized messages over hardcoded admin copy so labels and feedback can stay consistent across stores and locales.
Use tables, forms, filters, and feedback patterns that align with VTEX Admin conventions.
Prefer official design system components over custom clickable
```
div
```
or
```
span
```
patterns so focus behavior, keyboard navigation, and accessibility attributes remain correct by default.
For large lists and tables, prefer pagination and server-side filtering over loading everything into the browser and filtering in memory.
For search and filtering, prefer the search and filter patterns offered by the official design systems instead of inventing custom control behavior.
Keep labels, messages, and action copy in a single language per app and avoid mixing tones or languages on the same screen.
In forms, keep actions consistent: use a primary save action, an optional secondary cancel action when appropriate, and explicit feedback after submit.

管理端界面使用VTEX官方设计系统。
面向客户发布的VTEX IO管理端应用默认优先选择
```
vtex.styleguide
```
。
可使用官方VTEX设计系统
```
@vtex/shoreline
```
，内部后台场景下优先推荐。
页面搭建优先使用Styleguide核心布局模式，例如
```
Layout
```
、
```
PageHeader
```
、
```
PageBlock
```
。
通用管理端需求优先使用Styleguide基础组件：
```
Table
```
、
```
Input
```
、
```
Dropdown
```
、
```
Toggle
```
、
```
Tabs
```
、
```
Modal
```
、
```
Spinner
```
、
```
Alert
```
。
管理端页面以操作清晰度为核心，无需考虑店铺前端的样式需求。
重数据型管理端页面优先明确展示加载、空数据、错误状态。
异步操作使用按钮加载状态和toast类反馈，让用户明确感知变更操作的启动、成功、失败状态。
优先使用国际化文案而非硬编码的管理端文本，确保标签和反馈在不同店铺、不同 locale 下保持一致。
表格、表单、筛选、反馈模式需符合VTEX Admin规范。
优先使用官方设计系统组件，而非自定义可点击
```
div
```
或
```
span
```
模式，确保聚焦行为、键盘导航、无障碍属性默认符合要求。
针对大量列表和表格，优先使用分页和服务端筛选，而非将所有数据加载到浏览器后进行内存筛选。
搜索和筛选优先使用官方设计系统提供的搜索筛选模式，不要自定义控件行为。
单个应用内的标签、消息、操作文案保持单一语言，避免同一页面混合语言或语气风格。
表单内操作保持一致：使用主保存操作，合适场景下可添加次要取消操作，提交后给出明确反馈。

Hard constraints

硬性约束

Constraint: Admin UIs must use VTEX design systems

约束：管理端UI必须使用VTEX设计系统

Admin panel components MUST use VTEX official design systems.

Why this matters

VTEX Admin has a consistent design language. VTEX official design systems preserve that consistency, while generic third-party UI libraries create inconsistent visuals, styling conflicts, and review problems.

Detection

If you see Material UI, Chakra, Ant Design, or another generic third-party UI system in an admin app, STOP and replace it with VTEX design system patterns. Do not flag

@vtex/shoreline

as third-party.

Correct

tsx

import { Layout, PageHeader, PageBlock, Table } from 'vtex.styleguide'

tsx

import { Button, Table, EmptyState } from '@vtex/shoreline'

Wrong

tsx

import { DataGrid } from '@material-ui/data-grid'

管理后台组件必须使用VTEX官方设计系统。

重要性说明

VTEX Admin有统一的设计语言，VTEX官方设计系统可以保持这种一致性，而通用第三方UI库会导致视觉不一致、样式冲突、审核问题。

检测规则

如果在管理端应用中看到Material UI、Chakra、Ant Design或其他通用第三方UI系统，请停止开发，替换为VTEX设计系统模式。不要将

@vtex/shoreline

判定为第三方库。

正确示例

tsx

import { Layout, PageHeader, PageBlock, Table } from 'vtex.styleguide'

tsx

import { Button, Table, EmptyState } from '@vtex/shoreline'

错误示例

tsx

import { DataGrid } from '@material-ui/data-grid'

Constraint: Admin screens must expose loading, empty, and error states

约束：管理端页面必须展示加载、空数据和错误状态

Operational interfaces MUST make data state visible to the user.

Why this matters

Admin users need reliable operational feedback. Silent blank screens are harder to support and diagnose than explicit states.

Detection

If a page loads remote data but renders nothing meaningful on loading, empty, or error cases, STOP and add explicit UI states.

Correct

tsx

if (loading) {
  return (
    <PageBlock>
      <Spinner />
    </PageBlock>
  )
}

if (error) {
  return (
    <PageBlock>
      <Alert type="error">Failed to load data. Please try again.</Alert>
    </PageBlock>
  )
}

Wrong

tsx

return <Table items={data?.items ?? []} />

运营类界面必须向用户清晰展示数据状态。

重要性说明

管理端用户需要可靠的操作反馈，相比明确的状态提示，无提示的空白页面更难支持和排查问题。

检测规则

如果页面加载远程数据，但在加载、空数据、错误场景下没有展示有意义的内容，请停止开发，添加明确的UI状态。

正确示例

tsx

if (loading) {
  return (
    <PageBlock>
      <Spinner />
    </PageBlock>
  )
}

if (error) {
  return (
    <PageBlock>
      <Alert type="error">Failed to load data. Please try again.</Alert>
    </PageBlock>
  )
}

错误示例

tsx

return <Table items={data?.items ?? []} />

Constraint: Admin actions must provide explicit user feedback

约束：管理端操作必须向用户提供明确反馈

Mutations in admin screens MUST report success, failure, or pending state clearly.

Why this matters

Operational actions affect real store configuration and data. Users need immediate feedback to avoid repeated or ambiguous actions.

Detection

If a button triggers a write action with no feedback on result, STOP and add explicit feedback.

Correct

tsx

<Button isLoading={saving}>Save</Button>
showToast({ message: 'Settings saved successfully' })

Wrong

tsx

<Button onClick={save}>Save</Button>

管理端页面的变更操作必须清晰提示成功、失败或待处理状态。

重要性说明

操作会影响真实的店铺配置和数据，用户需要即时反馈避免重复操作或歧义操作。

检测规则

如果按钮触发写入操作但没有结果反馈，请停止开发，添加明确反馈。

正确示例

tsx

<Button isLoading={saving}>Save</Button>
showToast({ message: 'Settings saved successfully' })

错误示例

tsx

<Button onClick={save}>Save</Button>

Constraint: Data-heavy admin screens must stay bounded and navigable

约束：重数据型管理端页面必须保持可限制、可导航

Lists, tables, and search-heavy admin screens MUST use bounded rendering patterns such as pagination and should prefer server-side filtering when the API supports it.

Why this matters

Admin pages often deal with operational datasets that grow over time. Rendering too many rows at once or filtering only in memory creates poor performance and brittle UX.

Detection

If a page renders very large collections without pagination, or loads the full dataset into the browser just to filter locally, STOP and add bounded navigation or server-side filtering.

Correct

tsx

<Table items={items} />
<Pagination currentItemFrom={1} currentItemTo={10} totalItems={120} />

Wrong

tsx

const filtered = allItems.filter(matchesSearch)
return <Table items={filtered} />

列表、表格、重搜索的管理端页面必须使用限制渲染模式（例如分页），API支持时优先使用服务端筛选。

重要性说明

管理端页面通常处理随时间不断增长的运营数据集，一次性渲染过多行或仅在内存中筛选会导致性能低下、用户体验脆弱。

检测规则

如果页面渲染超大型集合没有分页，或加载全量数据到浏览器仅为了本地筛选，请停止开发，添加限制导航或服务端筛选。

正确示例

tsx

<Table items={items} />
<Pagination currentItemFrom={1} currentItemTo={10} totalItems={120} />

错误示例

tsx

const filtered = allItems.filter(matchesSearch)
return <Table items={filtered} />

Constraint: Interactive controls must use accessible semantics

约束：交互控件必须使用可访问语义

Admin interactions MUST use accessible controls and should prefer official design system components instead of custom clickable non-semantic elements.

Why this matters

Keyboard navigation, focus handling, and screen-reader behavior are part of baseline admin usability. Non-semantic clickable elements make accessibility regressions much more likely.

Detection

If you see clickable

div

span

elements being used as primary controls where a button, link, or design system component should be used, STOP and replace them.

Correct

tsx

<Button variation="primary">Save</Button>

Wrong

tsx

<div onClick={save}>Save</div>

管理端交互必须使用可访问控件，优先使用官方设计系统组件，而非自定义可点击的无语义元素。

重要性说明

键盘导航、聚焦处理、屏幕阅读器行为是管理端基础可用性的一部分，无语义可点击元素极容易导致可访问性退化。

检测规则

如果看到可点击

div

或

span

元素被用作主控件，而本该使用按钮、链接或设计系统组件，请停止开发，替换对应元素。

正确示例

tsx

<Button variation="primary">Save</Button>

错误示例

tsx

<div onClick={save}>Save</div>

Admin builder structure

Admin构建器结构

Admin pages in VTEX IO are exposed through the Admin builder:

Use the
```
admin/
```
folder to declare navigation and routes.
Use
```
admin/navigation.json
```
to define sections, subsections, and Admin navigation paths.
Use
```
admin/routes.json
```
to map each Admin path to a React component implemented under
```
react/
```
.
Use the
```
react/
```
folder to implement the page components used by Admin routes.

Practical rules:

Each entry in
```
admin/routes.json
```
should point to a real component in
```
react/
```
.
The route
```
path
```
should stay aligned with the navigation structure declared in
```
admin/navigation.json
```
.
Page components should use VTEX Admin layout patterns such as
```
Layout
```
,
```
PageHeader
```
, and
```
PageBlock
```
, or official Shoreline equivalents in internal contexts.

VTEX IO的管理端页面通过Admin构建器对外暴露：

使用
```
admin/
```
文件夹声明导航和路由。
使用
```
admin/navigation.json
```
定义分区、子分区和Admin导航路径。
使用
```
admin/routes.json
```
将每个Admin路径映射到
```
react/
```
目录下实现的React组件。
使用
```
react/
```
文件夹实现Admin路由使用的页面组件。

实操规则：

```
admin/routes.json
```
中的每个条目都应该指向
```
react/
```
下的真实组件。
路由
```
path
```
应该与
```
admin/navigation.json
```
中声明的导航结构保持一致。
页面组件应该使用VTEX Admin布局模式，例如
```
Layout
```
、
```
PageHeader
```
、
```
PageBlock
```
，内部场景下使用官方Shoreline对应的等效组件。

Example: navigation.json structure

示例：navigation.json结构

admin/navigation.json

json

[
  {
    "section": "storeSettings",
    "subSection": "storeFront",
    "subSectionItems": [
      {
        "labelId": "admin/my-settings.navigation.title",
        "path": "/admin/app/my-settings"
      }
    ]
  }
]

Main fields:

```
section
```
/
```
subSection
```
: define where the link appears in the Admin navigation tree.

subSectionItems[].path

: should match the

path

declared in

admin/routes.json

```
titleId
```
/
```
labelId
```
: message IDs used to internationalize navigation labels.
```
adminVersion
```
: optional and only needed for compatibility between legacy and newer Admin experiences. Do not use it in the default example for new apps.

admin/navigation.json

json

[
  {
    "section": "storeSettings",
    "subSection": "storeFront",
    "subSectionItems": [
      {
        "labelId": "admin/my-settings.navigation.title",
        "path": "/admin/app/my-settings"
      }
    ]
  }
]

主要字段：

```
section
```
/
```
subSection
```
: 定义链接在Admin导航树中的展示位置。

subSectionItems[].path

: 应该与

admin/routes.json

中声明的

path

匹配。

```
titleId
```
/
```
labelId
```
: 用于导航标签国际化的消息ID。
```
adminVersion
```
: 可选字段，仅用于新旧Admin体验的兼容，新应用的默认示例中不要使用。

Example: tying Admin builder to a React page

示例：将Admin构建器与React页面关联

admin/routes.json

json

{
  "admin.app.my-settings": {
    "component": "MySettingsPage",
    "path": "/admin/app/my-settings"
  }
}

react/MySettingsPage.tsx

tsx

import React from 'react'
import { Layout, PageHeader, PageBlock } from 'vtex.styleguide'

const MySettingsPage: React.FC = () => (
  <Layout pageHeader={<PageHeader title="My settings" />}>
    <PageBlock>
      {/* Page content goes here */}
    </PageBlock>
  </Layout>
)

export default MySettingsPage

admin/routes.json

json

{
  "admin.app.my-settings": {
    "component": "MySettingsPage",
    "path": "/admin/app/my-settings"
  }
}

react/MySettingsPage.tsx

tsx

import React from 'react'
import { Layout, PageHeader, PageBlock } from 'vtex.styleguide'

const MySettingsPage: React.FC = () => (
  <Layout pageHeader={<PageHeader title="My settings" />}>
    <PageBlock>
      {/* Page content goes here */}
    </PageBlock>
  </Layout>
)

export default MySettingsPage

Preferred pattern

首选模式

Use VTEX design systems to keep operational state explicit and optimize for clarity over ornamental UI. Use

PageHeader

and

PageBlock

with Styleguide where appropriate, or equivalent official Shoreline patterns in internal contexts. Use

Spinner

Alert

EmptyState

for data states and

showToast

plus button loading states for async feedback. Use paginated tables for large datasets, prefer server-side filtering when possible, and keep form actions consistent with primary save and optional cancel behavior.

使用VTEX设计系统明确展示运营状态，优先保证清晰度而非装饰性UI。合适场景下搭配Styleguide的

PageHeader

和

PageBlock

使用，内部场景下使用等效的官方Shoreline模式。数据状态使用

Spinner

Alert

EmptyState

，异步反馈使用

showToast

加按钮加载状态。大型数据集使用分页表格，可能时优先使用服务端筛选，表单操作保持一致的主保存、可选取消行为。

Common failure modes

常见错误模式

Using third-party UI libraries in admin apps.
Omitting loading, empty, or error states.
Triggering mutations without visible feedback.
Rendering large tables without pagination or filtering everything only in memory.
Building clickable controls with non-semantic elements instead of accessible buttons or links.
Mixing languages or inconsistent copy style on the same admin screen.

在管理端应用中使用第三方UI库。
遗漏加载、空数据或错误状态。
触发变更操作没有可见反馈。
渲染大型表格不加分页，或所有筛选仅在内存中执行。
使用无语义元素构建可点击控件，而非可访问的按钮或链接。
同一管理端页面混合语言或文案风格不一致。

Review checklist

审核检查清单

Does the screen use VTEX official design systems (Styleguide or Shoreline), not generic UI libs?
Does the page use
```
PageHeader
```
and
```
PageBlock
```
layout patterns where appropriate (or Shoreline equivalents)?
Are loading, empty, and error states explicit?
Are large tables or lists paginated and filtered in a scalable way?
Are write actions safe and visible?
Are interactive controls using accessible semantics instead of clickable non-semantic elements?
Are labels and feedback messages internationalized instead of hardcoded?
Is the app using one consistent language and tone for labels and actions?
Does the UI look and behave like a VTEX Admin tool?

页面使用VTEX官方设计系统（Styleguide或Shoreline），没有使用通用UI库？
合适场景下页面使用了
```
PageHeader
```
和
```
PageBlock
```
布局模式（或Shoreline等效组件）？
加载、空数据、错误状态展示明确？
大型表格或列表使用了可扩展的分页和筛选方式？
写入操作安全且状态可见？
交互控件使用了可访问语义，而非可点击的无语义元素？
标签和反馈消息做了国际化处理，没有硬编码？
应用的标签和操作使用了统一的语言和语气？
UI的外观和行为符合VTEX Admin工具的规范？

Reference

参考资料

Admin apps - Admin builder context
Shoreline repository - Official VTEX Shoreline design system repository
Shoreline docs - Shoreline component and design system documentation

Admin apps - Admin构建器相关说明
Shoreline repository - VTEX官方Shoreline设计系统仓库
Shoreline docs - Shoreline组件与设计系统文档