# Arco Design 设计系统

## Arco Design 设计系统界面预览

搜索、选择、纳入或移除报告分区,然后生成一份独立的本地大纲。

## Arco Design 设计系统设计参考

React 的 Arco 上游来源。Less 常量以 @ 开头显示;运行时的 CSS 变量使用 --。预览间距与面板布局是基于这些刻度所做的原创应用选择。

### 尺寸与间距

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| @size-mini | 24px | 紧凑型组件高度别名。 |
| @size-small | 28px | 小号组件高度。 |
| @size-default | 32px | 默认组件高度。 |
| @size-large | 36px | 大号组件高度。 |
| @spacing-1 … @spacing-6 | 2, 4, 6, 8, 10, 12px | 小间距步长。 |
| @spacing-7 … @spacing-10 | 16, 20, 24, 32px | 分组步长。 |
| @border-radius-small | 2px | 小圆角。 |
| @border-radius-medium | 4px | 中圆角。 |
| @border-radius-large | 8px | 大圆角。 |
### 字体与动效

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| @font-size-body | 14px | 全局正文尺寸。 |
| @line-height-base | 1.5715 | 在 14px 字号下约为 22px 的行高盒。 |
| @font-family | Inter, system and CJK fallbacks | 命名为 Inter 并不代表会下载该字体。 |
| @code-family | Consolas, Menlo | 面向代码的字体堆栈。 |
| @transition-duration-1 / 2 / 3 | 0.1s / 0.2s / 0.3s | 前三个时长常量。 |
| @transition-timing-function-standard | cubic-bezier(.34,.69,.1,1) | 已发布的标准曲线。 |
### 色板锚点

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| @arcoblue-6 | #165dff | Arco 蓝锚点。 |
| @gray-1 | #f7f8fa | 浅色中性色。 |
| @gray-2 | #f2f3f5 | 次级填充中性色。 |
| @gray-3 | #e5e6eb | 边框中性色。 |
| @gray-8 | #4e5969 | 次级文字中性色。 |
| @gray-10 | #1d2129 | 主文字中性色。 |
| @red-6 | #f53f3f | 红色锚点;不要假定其在小字号下也有足够对比度。 |
| @green-6 | #00b42a | 绿色锚点。 |
### 运行时变量命名约定

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --color-text-1 | Primary text role | 默认变量前缀并非 arco。 |
| --color-fill-2 | Secondary fill role | 在具备主题感知能力的区域中,应使用它而非硬编码的灰色。 |
| --border-radius-medium | Medium corner role | 在运行时导出。 |
| body[arco-theme="dark"] | Dark theme selector | 设置或移除该 body 属性。 |
| --color-bg-2 | Container surface | 在深色模式下会解析为不同的值。 |
### Transfer 的状态与事件

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| dataSource | {key:string,value:string,disabled?:boolean}[] | 稳定的 key 用于标识各个分区。 |
| targetKeys | string[] | 目标列中的成员关系。 |
| selectedKeys | string[] | 复选框的选中状态,而非目标列的成员关系。 |
| onChange | (newTargetKeys,direction,moveKeys) | 提交新的成员关系数组。 |
| onSelectChange | (leftSelectedKeys,rightSelectedKeys) | 将两者合并以作为受控的 selectedKeys。 |
| filterOption | (inputValue,item) => boolean | 原始默认行为是大小写敏感的子串匹配。 |
| showSearch | Boolean or per-list configuration | 该示例在两个列表中都启用了搜索。 |
| oneWay | Boolean | 仅在不希望从目标列中移除时使用。 |
| simple | Boolean or retainSelectedItems options | 选中后可自动移动;但这与显式的转移操作并不等价。 |
## Arco Design 设计系统完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## Arco Design 设计系统 Transfer 代表的是成员关系,而不仅仅是复选框列表

### 审慎地选择报告分区

> 当操作者需要比较两个集合——可用分区与已纳入报告的分区时,Arco Transfer 非常实用。勾选某一行只是将其标记以供后续操作;除非启用了简单模式,否则并不会立即移动该分区。

该样例保留了明确的两步式操作。用户先选择 Acquisition channels,再激活 Include,然后生成大纲。该大纲是一份独立的快照,因此之后在编辑器中所做的更改不会悄然重写已生成的版本。

阅读配套规范

## Arco Design 设计系统 将尺寸刻度与间距刻度分开使用

### 相同的数字可以代表不同的维度

Arco 的尺寸常量以 4 像素为步长递增,而间距刻度则以 2、4、6、8、10、12 起步,之后再出现更大的跳跃。默认组件尺寸别名为 32px。如果假定所有尺寸或间距后缀代表相同的数值,就会导致控件不一致。

在这一原创构图中,两个转移面板使用中等圆角,并设有 24px 的页面边距。小号复选框与行分隔线承载了密集的选择任务;较大的页面区域提供了视觉分隔,而不会用过大的卡片取代有用的内容。

阅读配套规范

## Arco Design 设计系统 在应用样式中保留语义角色

### CSS 变量有其自身的命名约定

默认主题导出的变量(如 --color-text-1 和 --color-fill-2)并不带有 arco 前缀。自定义构建可以更改该前缀,因此在集成到具有命名空间的应用时,应检查编译后的主题。主色板变量是 RGB 通道值;使用者需要写成 rgb(var(--primary-6)),而不能将该变量当作完整的十六进制颜色值来使用。

预览中为主要操作和选中行使用了经过验证的 Arco 蓝锚点。受限的分区使用禁用状态的复选框和说明性文字,而不是可能暗示“存在可修复错误”的红色。

阅读配套规范

## Arco Design 设计系统 支持密集标签和较长的分区名称

### 实用的正文字号刻度

默认正文字号为 14px,行高倍数为 1.5715。已发布的字体族以 Inter 开头,并包含系统字体与中日韩备用字体。这是一个 CSS 字体堆栈,并不能证明 Inter 字体文件已被实际加载。

报告分区标签可能比示例中的更长。离线版本会对行内文字进行换行,并在小视口下将面板堆叠显示,从而保持 Include 和 Remove 标签的可读性。它不会把整个转移组件缩小到文字难以辨认的程度。

阅读配套规范

## Arco Design 设计系统 两个受控数组可避免行为歧义

### 成员关系与选中状态含义不同

targetKeys 表示哪些条目属于报告。selectedKeys 表示左右两个列表中当前被勾选的复选框。onSelectChange 会提供左、右两个数组;在控制 selectedKeys 时需要将它们拼接起来。onChange 则会提供新的成员关系、方向以及被移动的 key。

1. 即使某个来源条目的显示标签发生变化,也要让其 key 保持稳定。

2. 在 onSelectChange 中合并左右两侧的选中数组。

3. 用 onChange 返回的新数组替换 targetKeys。

4. 移动完成后清除临时选中状态,并告知其对本地产生的影响。

阅读配套规范

## Arco Design 设计系统 搜索应收窄视图,而不删除成员关系

### 明确匹配规则

默认的源过滤器使用区分大小写的子字符串测试将查询与项目值进行比较。提供的示例将其替换为小写匹配。搜索隐藏的已选行不应意味着该行已从报告成员中消失。

对于这个小列表，分页和虚拟化几乎没有什么价值。Arco 为更大的数据集提供了这些选项，但应用程序仍然拥有稳定的键、完整的目标集以及跨过滤视图选择项目的规则。

- 可用列表和已包含列表有单独命名的搜索字段。

- 无匹配消息描述的是过滤后的视图，而不是空数据集。

- 准备大纲使用 targetKeys，而不仅仅是当前可见的行。

阅读配套规范

## Arco Design 设计系统深色模式会改变界面表面和文本

### 设置发布的选择器

Arco 在 theme 标签下以 arco-theme="dark" 发布其深色覆盖。在默认构建中，该标签是 body。删除该属性会恢复正常规则；添加一个名为 dark 的无关类并不相同API。

如果添加深色预览，请同时解决容器和文本角色。离线样本故意保持浅色，而原生示例可以使用已导入的主题CSS。不要用全局滤镜反转报告缩略图或插图。

```
document.body.setAttribute('arco-theme', 'dark');
// Restore default:
document.body.removeAttribute('arco-theme');
```

代码参考

阅读配套规范

## Arco Design 设计系统包、样式表和实际边界

### 报告大纲不会导出报告数据

React 包是 @arco-design/web-react，其完整的 CSS 入口是 dist/css/arco.css。示例从包根目录导入 Transfer 和 Button 并使用受控状态，而不是创造一个 report-builder API。

独立预览使用原生复选框和按钮解释选择行为，因此它可以离线工作。它验证交互逻辑和响应式组合；它不证明原生包在使用项目中编译。生产导出器需要后端和权限检查，超出禁用示例行的范围。

阅读配套规范

## Arco Design 设计系统组件示例

### 完整的独立交互示例

将完整文档保存为 index.html 并在浏览器中打开。独立的 HTML 对 Arco Transfer 行为的解释和经过验证的主题锚点；原生 React 示例单独提供。

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Arco report section transfer</title><style>
*{box-sizing:border-box}body{margin:0;color:#1d2129;background:#f7f8fa;font:14px/22px Arial,sans-serif}header{padding:20px 28px;background:white;border-bottom:1px solid #e5e6eb;display:flex;justify-content:space-between}.logo{font-size:18px;font-weight:bold;letter-spacing:-.02em}.logo i{font-style:normal;color:#165dff;margin-right:8px}header small{color:#4e5969}main{max-width:1050px;padding:28px;margin:auto}h1{font-size:24px;line-height:32px;margin:0 0 8px}.lead{color:#4e5969;margin:0 0 24px}.transfer{display:grid;grid-template-columns:minmax(0,1fr) 106px minmax(0,1fr);align-items:stretch}.list{border:1px solid #e5e6eb;background:white;border-radius:4px;min-width:0}.head{padding:16px;background:#f2f3f5;display:flex;gap:8px;justify-content:space-between}.head h2{font-size:14px;margin:0}.count{font-size:12px;color:#4e5969}.search{padding:12px;border-bottom:1px solid #e5e6eb}.search label{font-size:12px;display:block;margin-bottom:4px;color:#4e5969}.search input{height:32px;width:100%;border:1px solid transparent;background:#f2f3f5;padding:4px 12px;font:inherit;border-radius:2px}input:focus,button:focus-visible{outline:2px solid #165dff;outline-offset:2px}.items{min-height:290px;padding:8px}.item{display:flex;gap:10px;padding:12px 8px;border-radius:2px;align-items:start;cursor:pointer}.item:has(input:checked){background:#e8f3ff}.item input{width:16px;height:16px;accent-color:#165dff;margin-top:3px;flex-shrink:0}.item small{display:block;color:#4e5969;font-size:12px}.item:has(input:disabled){color:#86909c;cursor:not-allowed}.ops{padding:16px 12px;display:flex;flex-direction:column;gap:12px;justify-content:center}button{font:14px/22px Arial;border:1px solid #e5e6eb;background:white;color:#1d2129;border-radius:2px;padding:5px 12px;cursor:pointer}.ops button{padding:5px 4px}.primary{background:#165dff;border-color:#165dff;color:#fff}button:disabled{background:#f2f3f5;color:#86909c;border-color:#e5e6eb;cursor:not-allowed}.footer{display:flex;justify-content:space-between;align-items:center;gap:16px;padding:20px 0}.footer p{font-size:12px;color:#4e5969;margin:0}.outline{background:white;border:1px solid #e5e6eb;border-radius:4px;padding:24px}.outline h2{font-size:16px;margin:0 0 12px}.outline ol{margin:0;padding-left:20px}.note{color:#4e5969;font-size:12px;margin-top:20px}.empty{padding:20px 8px;color:#4e5969}.selection{font-size:12px;color:#4e5969;padding:10px 16px;border-top:1px solid #e5e6eb}@media(max-width:650px){main{padding:24px 16px}.transfer{grid-template-columns:1fr}.ops{flex-direction:row;padding:12px}.ops button{padding:6px 16px}.items{min-height:160px}.footer{align-items:start;flex-direction:column}header{padding:16px}}
</style><header><span class="logo"><i>A /</i> Analytics workspace</span><small>Report studio</small></header><main><h1>Choose report sections</h1><p class="lead">Build an outline from the sections available to this workspace.</p><div class="transfer"><section class="list"><div class="head"><h2>Available sections</h2><span id="left-count" class="count"></span></div><div class="search"><label for="left-search">Find available section</label><input id="left-search" type="search" placeholder="Search by section name"></div><div class="items" id="left"></div><div class="selection" id="left-selected"></div></section><div class="ops"><button class="primary" id="include" disabled>Include →</button><button id="remove" disabled>← Remove</button></div><section class="list"><div class="head"><h2>Included in report</h2><span id="right-count" class="count"></span></div><div class="search"><label for="right-search">Find included section</label><input id="right-search" type="search" placeholder="Search included sections"></div><div class="items" id="right"></div><div class="selection" id="right-selected"></div></section></div><div class="footer"><p id="status" role="status">Select a section, then choose Include or Remove.</p><button id="prepare" class="primary">Prepare outline</button></div><section class="outline"><h2>Prepared outline</h2><div id="snapshot">No outline prepared yet.</div></section><p class="note">HTML interpretation of Arco Transfer · Original sample sections · Local outline only, no analytics data exported</p></main><script>
const data=[{key:'overview',value:'Executive overview',detail:'A concise summary of the reporting period'},{key:'traffic',value:'Acquisition channels',detail:'How people arrive at your product'},{key:'retention',value:'Retention cohorts',detail:'Returning usage by cohort'},{key:'revenue',value:'Revenue breakdown',detail:'Revenue categories and trends'},{key:'raw',value:'Raw event export',detail:'Restricted · unavailable in this specimen',disabled:true}];const $=id=>document.getElementById(id);let target=new Set(['overview']),selected=new Set();
function render(){for(const side of ['left','right']){const items=data.filter(x=>target.has(x.key)===(side==='right')),query=$(side+'-search').value.toLowerCase(),host=$(side);host.replaceChildren();$(side+'-count').textContent=items.length+' sections';const visible=items.filter(x=>x.value.toLowerCase().includes(query));if(!visible.length){const p=document.createElement('p');p.className='empty';p.textContent=query?'No matching sections.':'No sections in this column.';host.append(p)}for(const item of visible){const label=document.createElement('label');label.className='item';const input=document.createElement('input');input.type='checkbox';input.id='check-'+item.key;input.checked=selected.has(item.key);input.disabled=!!item.disabled;input.setAttribute('aria-label',item.value);input.onchange=()=>{input.checked?selected.add(item.key):selected.delete(item.key);render();$('check-'+item.key)?.focus()};const text=document.createElement('span'),small=document.createElement('small');text.textContent=item.value;small.textContent=item.detail;text.append(small);label.append(input,text);host.append(label)}$(side+'-selected').textContent=items.filter(x=>selected.has(x.key)).length+' selected'}$('include').disabled=!data.some(x=>selected.has(x.key)&&!target.has(x.key)&&!x.disabled);$('remove').disabled=!data.some(x=>selected.has(x.key)&&target.has(x.key)&&!x.disabled);$('prepare').disabled=!target.size}
function move(toTarget){const moved=data.filter(x=>selected.has(x.key)&&target.has(x.key)!==toTarget&&!x.disabled);for(const item of moved)toTarget?target.add(item.key):target.delete(item.key);selected.clear();render();$('status').textContent=moved.length+' section(s) '+(toTarget?'included in':'removed from')+' the local draft.';$(toTarget?'right-search':'left-search').focus()}
$('include').onclick=()=>move(true);$('remove').onclick=()=>move(false);for(const side of ['left','right'])$(side+'-search').oninput=render;$('prepare').onclick=()=>{const ol=document.createElement('ol');for(const item of data.filter(x=>target.has(x.key))){const li=document.createElement('li');li.textContent=item.value;ol.append(li)}$('snapshot').replaceChildren(ol);$('status').textContent='Local report outline prepared. No data exported.'};render();
</script></html>
```

代码参考

- 受限的报告部分无法移动。已选行和已包含部分是不同的状态，与原生 Transfer 解释的区别相匹配。

### 受控报告部分传输

Transfer 管理源和目标成员身份，而应用程序状态存储单独准备的大纲。受限行演示了禁用选项，而不是假装强制执行服务器授权。

```
// npm install @arco-design/web-react react react-dom
import React,{useState} from 'react';
import {createRoot} from 'react-dom/client';
import {Transfer,Button} from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';
const data = [
 {key:'overview',value:'Executive overview'},
 {key:'traffic',value:'Acquisition channels'},
 {key:'retention',value:'Retention cohorts'},
 {key:'revenue',value:'Revenue breakdown'},
 {key:'raw',value:'Raw event export (restricted)',disabled:true}
];
function ReportBuilder(){
 const [target,setTarget]=useState(['overview']);
 const [selected,setSelected]=useState([]);
 const [snapshot,setSnapshot]=useState([]);
 const [status,setStatus]=useState('Choose sections for a local report.');
 return <main style={{padding:24,maxWidth:960,margin:'auto'}}>
  <h1>Report sections</h1>
  <Transfer dataSource={data} targetKeys={target} selectedKeys={selected}
   titleTexts={['Available sections','Included in report']}
   operationTexts={['Include','Remove']}
   showSearch searchPlaceholder={['Find available section','Find included section']}
   filterOption={(query,item)=>item.value.toLowerCase().includes(query.toLowerCase())}
   onSelectChange={(left,right)=>setSelected([...left,...right])}
   onChange={(keys,direction,moved)=>{
    setTarget(keys);setSelected([]);
    setStatus(`${moved.length} section(s) moved to ${direction}. Draft only.`);
   }} />
  <p role="status">{status}</p>
  <Button type="primary" disabled={!target.length} onClick={()=>{
   setSnapshot([...target]);setStatus('Local report outline prepared. No data exported.');
  }}>Prepare outline</Button>
  <h2>Prepared outline</h2>
  {snapshot.length ? <ol>{snapshot.map(key=><li key={key}>{data.find(item=>item.key===key).value}</li>)}</ol> : <p>No outline prepared yet.</p>}
 </main>;
}
createRoot(document.getElementById('root')).render(<ReportBuilder />);
```

代码参考

- 复选框选择和已包含报告成员是不同的数组。

- 自定义过滤器使匹配不区分大小写。

- 示例数据是原创的；不会加载或导出任何分析数据。原生编译仍然是一个单独的集成检查。

## Arco Design 设计系统 AI Agent 设置

### 实现起点

导入一次完整的 arco.css 样式表，并将 React 示例挂载到根元素中。不要将此 React 包与 Arco Vue 导入混合使用。

```
npm install @arco-design/web-react react react-dom
```

### 适用于你项目的提示词

```
使用 Arco React Transfer，具有稳定的 dataSource 键以及单独受控的 targetKeys 和 selectedKeys。提供不区分大小写的过滤器、明确的包含/删除操作以及准备好的大纲快照。保留 Arco CSS 变量语法，并诚实地标记离线解释。
```

## Arco Design 设计系统来源和范围

独立的 OpenDesign 参考。原始报告数据和仅本地预览；禁用行不是授权边界。

- React 包 安装和样式表入口。

- 全局令牌 尺寸、间距和语义映射。

- 默认主题 排版和动效。

- 调色板 经过验证的颜色锚点。

- CSS 变量 运行时名称和深色选择器。

- Transfer API 受控状态和回调签名。

## Arco Design 设计系统相关资源

### Atlassian 设计系统

使用语义化的 Atlassian 设计令牌、8 像素间距标尺、真实的 Button、Lozenge 与 Toggle API，以及必需的 Compiled 样式配置，构建一块议题规划看板。检视一条议题、筛选看板，并移动本地工作项，同时不把选中与状态混为一谈。

### AWS Cloudscape

一份 Cloudscape 配置指南，包含真实的可视化刷新令牌、感知密度的间距、受控表单 API，以及可运行的两步资源向导。

### Backbase 设计系统

使用 Backbase 的 Angular 模块、语义主题导出和明确的审核状态构建品牌银行审核流程。比较 Web API 与单独记录的原生尺寸。


- [实现参考](https://raw.githubusercontent.com/arco-design/arco-design/main/components/Transfer/interface.tsx)
- [来源](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/global.less)
- [来源](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/default.less)
- [来源](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/color/colors.less)
- [来源](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/css-variables.less)
- [来源](https://raw.githubusercontent.com/arco-design/arco-design/main/components/Transfer/interface.tsx)
- [阅读配套规范](https://raw.githubusercontent.com/arco-design/arco-design/main/components/Transfer/interface.tsx)
- [阅读配套规范](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/global.less)
- [阅读配套规范](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/css-variables.less)
- [阅读配套规范](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/default.less)
- [代码参考](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/css-variables.less)
- [阅读配套规范](https://raw.githubusercontent.com/arco-design/arco-design/main/README.md)
- [代码参考](https://raw.githubusercontent.com/arco-design/arco-design/main/components/Transfer/interface.tsx)
- [React 包 安装和样式表入口。](https://raw.githubusercontent.com/arco-design/arco-design/main/README.md)
- [全局令牌 尺寸、间距和语义映射。](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/global.less)
- [默认主题 排版和动效。](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/default.less)
- [调色板 经过验证的颜色锚点。](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/color/colors.less)
- [CSS 变量 运行时名称和深色选择器。](https://raw.githubusercontent.com/arco-design/arco-design/main/components/style/theme/css-variables.less)
- [Transfer API 受控状态和回调签名。](https://raw.githubusercontent.com/arco-design/arco-design/main/components/Transfer/interface.tsx)