treg/design.cn.md

name, description

name	description
treg-design-guidelines	为 treg 设计和实现产品界面。以新版 Getting started 设计为视觉基准，覆盖品牌、布局、字体、颜色、组件、响应式、交互与可访问性。

Design interfaces like treg

让用户知道 agent 能做什么，并能立即完成下一步：接入 agent、找到工具、连接自己的账号、检查调用与花费。界面应清楚、轻盈、有技术气质；通过像素标题、柔和表面和真实任务场景形成辨识度。

本文件是新版界面的设计规范，供设计师、开发者和 coding agent 使用。它不代表新版已经合入产品，也不改变 API、权限、计费或产品能力。现有实现与行为以 AGENTS.md 和对应的 context fragments 为准。

1. 来源与优先级

本版于 2026-09-07 核对以下资料：

来源	用途
Vercel design.md	借鉴其任务优先、规则优先级、视觉系统、交互与验收的组织方法，不继承 Vercel 品牌、CSS 或专属报告布局
新版线上原型	核对部署中的 HTML、CSS 与交互源码
设计仓库	固定参考版本；该版本 styles.css 与本次获取的线上 CSS 字节一致
Figma 新版完整页面，12:596	已读取设计上下文和截图；作为 Getting started 的主要视觉依据
Figma 工作区，1:3	包含多个版本；12:33 的侧栏布局不作为新版默认外壳

本次视觉核对使用 Figma 截图，线上样式与行为核对使用源码；未完成线上浏览器渲染与交互验收。

发生冲突时，按以下顺序决策：

1. 用户明确要求、真实产品行为、权限与数据准确性。
2. 可访问性、任务可完成性、现有框架和路由约定。
3. 本文件明确提炼的新版规则。
4. 指定 Figma 节点的视觉意图，以及部署源码中的有效样式。
5. 其他旧稿、原型默认值和实现细节。

下文的「参考值」来自上述设计或源码；「实施要求」是本规范对完整产品体验的要求，不表示原型已经实现。Catalog 的细节来自仓库；Activity、Team、Billing 等页面使用本规范延展，不宣称已有完整新版设计稿。

2. 产品表达

• 品牌写作 treg，保持小写。说明 agent 能完成的任务，避免空泛的能力宣言。
• a tool / 工具：agent 调用的对象。
• the catalog / 工具目录：公开可发现的工具。
• your own tools / 你自己的工具：团队自己的 keys 和 skills 所支持的工具。
• registry：只指服务端本身。不要把任何一半产品称为 vault、marketplace 或 registry。
• 团队自己的 key 优先，不经 treg 计量收费，也不参与路由或溢出。计费文案必须保留这个区别。
• 不笼统承诺「自动选最优 provider」。只有明确披露的 routed endpoints 和 overflow 场景可表达对应行为。
• provider 数量、价格、余额、连接状态和奖励来自真实数据。原型的团队名、头像、余额和 demo token 都不是生产默认值。

页面标题与按钮采用 sentence case；正文短而直接。按钮说明动作，例如 Copy、Connect account、View activity。错误同时说明问题和可执行的下一步。不要以全大写标签、过密字距或微小灰字替代信息层级；OWNER 等短角色标记可保留。

3. 设计判断

任务在前，品牌在细节里。 首屏给出当前上下文和可执行动作。Getting started 的主体是接入说明，不是大幅营销 hero；Catalog 的主体是搜索与发现，不是介绍目录的长文。

无彩色骨架，局部有生命力。 以浅灰画布、白色面板、炭黑文字与反色控件建立结构。色彩主要来自 agent 品牌、任务图片和状态。不要给每个模块分配一种装饰色。

柔和容器，明确层级。 大圆角用于任务模块，较小圆角用于内部代码表面，胶囊用于选择和身份。不要让每一行内容都成为卡片，也不要抹平稿件中有任务意义的面板分组。

像素是点睛。 像素字体用于页面标题和少量引导语；正文、表格、表单保持易读。避免将整个产品做成终端或像素游戏。

视觉承诺必须真实。 看起来可点击的元素必须完成动作，或说明不可用原因。复制示例只是复制，不表示 agent 已执行任务；完成接入必须由真实状态确认。

4. 外壳与布局

新版默认采用顶部导航，主内容居中。不要因现有 dashboard 使用侧栏，就将两套外壳同时保留。

部位	桌面参考值	规则
顶栏	高 57px；水平 padding 20px；垂直 padding 11px	左侧品牌与团队，中间主导航，右侧社区、余额、账户；导航与两翼独立对齐
团队选择器	209 × 38px；圆角 10px	长名称截断，角色与展开动作保持可辨认
主导航	最小高 32px；水平 padding 16px；项间距 2px	当前页使用实心反色背景；其他项安静但清晰
页面外边距	22px 26px 64px	页面标题、卡片、搜索和底部内容共享对齐线
Getting started 内容宽	最大 1080px	自适应居中，替代旧稿 760px 的单窄列
Catalog 内容宽	最大 1380px	为搜索、分类与工具比较提供更大宽度
欢迎行	桌面上方留白 64px；搜索约 200 × 39.5px	标题在左，搜索在右；该留白仅用于此引导场景
接入模块	左侧 360px，其余宽度为说明；内边距 24px	选择 agent 与预览在左，可复制操作和 token 在右
任务示例	两列，gap 12px；卡片参考高 200px	同级示例使用相同的信息顺序；内容增长时允许增高
Catalog 平台网格	自动填充，最小列宽 300px，gap 12px	容器更窄时单列，不压缩卡片正文

间距以 4、8、12、16、24、32、64px 为常用尺度。14px 的首卡间距、16px 的模块间距等稿件参考值可以保留；不要为了机械统一而改变构图。每个间距由一个容器负责，避免父级 gap 与子级 margin 叠加。

使用流式布局而非照搬 Figma 绝对坐标。Grid 和 Flex 子项设 min-width: 0，可伸缩列使用 minmax(0, 1fr)。不要通过页面级 overflow-x: hidden/clip 掩盖溢出。

5. 字体

角色	字体	参考字号 / 行高	字重
页面标题	Geist Pixel	22 / 27.5px	400
短引导语，如 Try it out 的介绍	Geist Pixel	16 / 22px	400
模块标题	Google Sans Flex	16 / 24px	500
正文、表单说明	Google Sans Flex	14 / 21px	400；关键字段标签 600
导航、选择器	Google Sans Flex	13 / 19.5px	400-600，按状态区分
次级说明	Google Sans Flex	12.5 / 19.375px	400
示例卡片标签	Inter	12.5 / 19.375px	400
示例任务正文	Inter	13 / 20.15px	600
命令、token、代码	DM Mono	12 / 18.6px	400
余额数值、步骤编号	DM Mono	12 / 18px	500

正文 fallback 为 Inter、系统 sans-serif；代码 fallback 为系统 monospace。Geist Pixel 缺失时允许回退到 mono，不能阻塞页面。中文内容须提供具有完整字形的系统字体回退，不能强制使用缺失字形的像素字体。

保留 DM Mono 用于余额这一 treg 细节，不照搬 Vercel 将财务数字全部设置为 Sans 的规则。比较数值使用 tabular numerals，单位与精度保持一致。

Logo 字标以 Figma 的 Google Sans Flex 15px / 500 为目标；当前原型 .brand 仍继承早期 mono 声明，是已知差异，不作为第二种品牌字体规则。

6. 颜色与主题

下表使用原型现有变量名，数值取 CSS 最终覆盖结果。不能只读取文件开头的旧色板。组件应使用语义变量，不重复散落 hex 值；表中颜色是视觉基准，不是所有文字组合都已通过对比度检查的声明。

Token / 角色	Light	Dark
--bg，画布	#f8f8f8	#000000
--surface，主面板	#ffffff	#181917
--panel	#f8f8f8	#181917
--panel-2，内层区域	#f8f8f8	#222320
--ink，主文字	#1a1a1a	#f3f3ef
--muted，次级文字参考	#7c7c7c	#a5a5a0
--muted-2，弱提示参考	#989898	#7f807b
--line，细分界	rgba(0,0,0,.10)	rgba(255,255,255,.10)
--line-2，控件边界	rgba(37,37,34,.20)	rgba(255,255,255,.17)
--hover	rgba(42,42,37,.04)	rgba(255,255,255,.06)
--inverse / --inverse-ink	#1a1a1a / #f8f8f7	#f3f3ef / #151613
--green，成功	#118453	#45e39e
--teal，信息	#1a7da6	#6fcdf0
--amber，提醒、角色参考	#ba6603	#f0c249
--red，错误	#c0362f	#f08a84

补充表面参考：浅色代码内层为白色，深色为 #171816；浅色任务卡文字覆盖层为 rgba(255,255,255,.80)，深色为 rgba(24,25,23,.84)。

实施要求：小字不能因为叫 muted 就免于对比度要求。正文和必要辅助文字至少 4.5:1，大字至少 3:1；控件和焦点的必要视觉边界至少 3:1。原型的 #7c7c7c、#989898 和低透明度文案必须结合实际背景复核，必要时加深，不能忠实复制可读性缺陷。

默认浅色；账户菜单提供 Light / Dark，并记住明确选择。深色保持相同的信息层级，独立设置表面、图片遮罩和控件颜色，不对整页直接反相。原型深色下的 provider 胶囊保留浅底，以承载品牌图标。

7. 表面、圆角与图形

用途	参考圆角
接入主卡	32px；窄屏 24px
Try it out、Build on treg 外层	24px
设置分组、场景图片卡	20px
代码表面、图片预览、场景文字覆盖层	16px
Catalog 平台卡	15px
导航、团队选择器	10px
小型复制按钮	7px
搜索、agent / provider 选择、分段切换	胶囊，使用足够大的半径

面板边框轻而连续。稿件中 0.5px 的边框用于高密度屏幕的细线效果；在目标设备上消失时使用稳定的 1px 低对比边框。阴影用于浮层与可交互卡片的层级，不给每个静态模块制造悬浮感。

允许且限定以下品牌效果：

• ASCII / 像素背景：只在页面上部作为低对比背景，不参与布局、不截获指针、不承载信息。使用设计提供的资产，不另造网格纹理。
• 任务场景图片：用于 Getting started 示例，帮助区分任务。图片只是场景示意，不能伪装成真实调用结果。
• 局部磨砂：顶栏参考 blur 14px；场景卡文字覆盖层参考 blur 32px。无滤镜支持时仍须有足够不透明的可读底色。
• 局部渐变：保留场景图片的可读性遮罩、余额胶囊的极淡渐变，以及已设计的推荐入口效果。不扩展为全站渐变按钮、发光边框或渐变文字。

不要把 Vercel 对纹理、图片或磨砂的全面限制直接套用到 treg；也不要将这里的局部例外扩展成每页都需要的装饰。

8. 核心组件与任务流程

Getting started

按「Set up your agent → Try it out → 可选的 Build on treg」组织。步骤编号表示操作顺序，不是装饰性章节号。

• 接入卡同时展示所选 agent、相应说明、可复制的命令或提示词。切换 agent 后，这些内容和适用的图像应一致。
• treg token 默认遮蔽；显隐和复制分别操作。复制完整且被授权展示的值，不能复制遮蔽字符串；复制成功也不自动展开 token。
• 示例卡整卡可复制提示词，用局部 Copied 状态确认；不要把复制包装成已经执行了调用。
• OAuth 连接按用户任务分组。入口说明连接的服务；实际授权范围、审核状态和错误来自产品逻辑。
• Build on treg 是可选路径。两种受众通过分段切换看到各自说明；手动设置使用渐进展开。

Catalog

• 搜索、分类筛选、结果数量、平台卡与详情构成连续发现路径。搜索无结果时保留输入，给出清除筛选或换词的动作。
• 分类使用下划线激活态；它与顶部主导航的实心激活态承担不同层级，不应强行合并。
• 平台卡优先展示图标、名称、能做什么及必要的数量或状态。不要将简介压成无人能读的灰色小字。
• 详情比较围绕任务、provider、价格单位、认证与可调用状态组织。用表格支持精确对照，不用图片卡包装技术记录。
• 不把原型固定数据、模拟连接按钮或推荐顺序解释为真实能力与可用性。

通用行为

• 主动作使用实心反色控件；次动作使用浅表面或描边；低优先级操作使用文字按钮。危险动作通过明确动词和局部危险状态表达。
• 搜索入口应实际进入 Catalog 并聚焦搜索；展示快捷键时必须实现，不能截获用户在文本框中的正常输入。
• 菜单提供键盘操作、Escape 关闭、焦点返回和准确的展开状态。禁止在一个按钮里嵌套另一个交互控件。
• 状态至少覆盖 default、hover、focus、pressed、disabled、loading、success、error。当前页和选中项不能只靠颜色区分。
• 复制必须在剪贴板写入成功后才显示成功；失败给出可手动选择的内容和简短提示。
• 异步请求保持布局稳定，失败保留输入并允许重试。空状态、加载状态、零结果与权限不足分别表达。

9. 动效与媒体

原型交互过渡常用 120-180ms，主题变化约 240ms，页面进入约 280ms。参考曲线为 cubic-bezier(.2,.72,.25,1)，位移退出曲线为 cubic-bezier(.22,1,.36,1)。优先过渡颜色、透明度和轻微 transform，不使用 transition: all。

场景卡可有 1-2px 的轻微上移；不让位移妨碍点击或阅读。不要增加弹跳、滚动揭幕、自动打字和闪烁状态灯。

背景视频和 agent 预览属于可选品牌媒体。静态 poster 必须构成完整体验；视频不能阻塞页面、承担状态提示或自动发声。尊重 reduced motion：停用两类自动视频与非必要位移，保留静态图；长时间自动播放还须有可访问的暂停方式。只暂停 ASCII 背景而继续播放 agent 预览不算完整支持。

资产从设计仓库的 assets/figma/ 和 assets/icons/treg/ 获取。复用真实 treg mark、provider 标志和图标，不用 emoji 或手画近似图替代。固定图像尺寸避免布局跳动；正式交付使用项目托管资产，不依赖临时 Figma 导出 URL。

10. 响应式与可访问性

宽度参考	布局行为	实施要求
大于 1180px	三段顶栏、双列接入卡、两列任务卡	避免左右内容增长挤压中央导航
不超过 1180px	顶栏开始收缩，导航可局部滚动	团队选择移入可访问菜单，不直接丢失切换能力
不超过 820px	顶栏分为两行，接入卡上下堆叠，左右留白 18px	取消固定位高约束，导航及浮层不能重叠正文
不超过 620px	搜索独占一行，任务卡单列，左右留白 12px，卡片 padding 16px	Team、余额等移入更多菜单，不能只用 display:none 移除功能

断点服务内容，不是设备分类。上述值来自原型，新页面遇到拥挤时应提前重排。检查窄至 320px、常见手机、平板、1440px 桌面和 200% 缩放；不要缩小字体来维持桌面构图。

页面使用 landmarks、一个描述性 h1、连续标题层级、原生按钮和表单标签。图标操作有可访问名称；装饰图片使用空 alt，视频不进入焦点顺序。表格有标题、列头、正确的数值对齐；长代码或宽表格仅在所属容器内滚动。

所有交互都必须有可见焦点。小图标的视觉尺寸可保持 12-20px，但点击区域要扩大；触屏目标建议达到 44 × 44px。Toast 与复制反馈使用简短的 live status，不能仅通过变绿反馈结果。

11. 接入现有工程

保留项目的 Vue、路由、服务端与资源管理约定。Figma 返回的 React + Tailwind 是参考表示，不构成迁移框架的理由。视觉修改放入实际拥有该界面的文件；本文件没有提供或要求另一个运行时设计系统。

实施前读取对应 context fragment；复用已有交互行为和组件职责。将本规范的语义角色映射到现有 token，逐步收敛重复声明，不把原型 CSS 中「旧规则 + 多轮覆盖」的历史整体搬入产品。

关键脚本必须遵循项目同源资源约定；字体、图片和视频失败时页面仍可用。新视觉不应改变认证、团队范围、计费、路由或浏览器前进后退行为。若任务确实要求改变行为，同步更新对应产品说明。

12. 交付前检查

1. 首屏能看出当前任务、下一步动作与 treg 身份；页面没有为品牌装饰推迟主要操作。
2. 字体、图片裁切、圆角、对齐线与指定 Figma 版本一致；没有混入旧侧栏稿。
3. 浅深主题均可读；没有丢失焦点、低对比关键文案、溢出或窄屏消失的必要入口。
4. 接入选择、复制、显隐、搜索、筛选、菜单和主题切换真实可用；成功、失败、空态与加载态清楚。
5. 文案遵守 treg 词汇，余额和状态来自真实数据；没有 demo token、模拟成功或虚构功能。
6. reduced motion、字体失败和媒体失败均有完整退路。
7. 在真实浏览器中对照首屏与整页，检查桌面、手机、键盘路径及深色模式；未验证的部分明确记录，不把源码阅读当成视觉验收。

已知原型差异需在实施时处理：账户菜单的 Your vault 应为 Your own tools；模拟操作不能代替生产功能；窄屏隐藏入口必须有替代访问路径；.try-card:focus-visible 清除焦点的规则不能沿用。它们是原型限制，不是新版设计语言的一部分。