migrated legacy_doc_id: D1-B-SPEC-007 level: l3

Xisound 研发中心 · 前端 UI 标准规范 v1.0

本文档定位

层级：D1 研发中心级（B-rd）· 横跨所有前端产品的最低共同标准

关系：本文是研发中心对前端 UI 的"宪法"；具体组件 API 见 D3-FE-ARCH-003 共享 UI kit 架构；模块 UI 实施细则见 D3-FE-ARCH-007 模块 UI 实现规范

目标读者：所有前端工程师 / 设计师 / 提交前端 PR 的智能体

强制性：本规范为研发中心强制基线，违反的 PR 由 reviewer 直接打回

文档使命

定义 Xisound 所有前端产品在视觉、交互、可访问性、国际化、性能等维度的最低共同标准，使智能体与人类工程师在不同产品（XiStudio / XiForge / XiTune / XiTest / XiProbe / XiVST / XiMind）之间切换时能立即按统一规范产出。

1. 色彩规范

1.1 色彩来源

所有色值必须通过 Tailwind preset 引用，禁止在 Vue 组件 / CSS 中硬编码 hex / rgb。

色彩详细定义见 D0 3+1 品牌色彩系统
前端实现见 @xi/ui-kit/tailwind-preset.ts（详见 D3-FE-ARCH-003 §2.4）

1.2 语义色映射

语义	Tailwind class	用途
主色（曦紫）	`xi-primary-500`	主按钮 / 焦点态 / 链接默认色
强调色（极光青）	`xi-accent-500`	强调元素 / 高亮徽标
文字主色	`xi-ink-900`	正文 / 标题
背景纸色	`xi-paper-50`	卡片背景 / 浅模式底色
成功	`xi-success`	完成 / 在线 / running 状态
警告	`xi-warning`	注意但可继续 / loading 后可恢复
错误	`xi-danger`	失败 / 离线 / error 状态
信息	`xi-info`	中性提示 / 默认进度条

1.3 禁止行为

禁止使用 <span style="color"> / <font color> 等内联色
禁止在 Mermaid 图节点上手写 fill:#xxx，必须用 xyL0~xyL5 / xySuccess / xyWarn / xyError / xyEnd class
禁止在文档 Markdown 表格内嵌 HTML 颜色标签（违反 md-writing-spec §7.1）

2. 字体与排版

2.1 字体栈

// tailwind-preset.ts 已定义
fontFamily: {
  sans: ['"Inter"', '"PingFang SC"', 'sans-serif'],
  mono: ['"JetBrains Mono"', 'monospace'],
}

西文：Inter
中文：PingFang SC（macOS）/ Microsoft YaHei（Windows · 兜底）
代码 / 数值：JetBrains Mono

2.2 字号阶梯

用途	Tailwind class	行高
标题 H1	`text-3xl` (30px)	`leading-tight`
标题 H2	`text-2xl` (24px)	`leading-tight`
标题 H3	`text-xl` (20px)	`leading-snug`
正文	`text-base` (16px)	`leading-normal`
辅助文字 / 标签	`text-sm` (14px)	`leading-normal`
极小字（徽标 / hint）	`text-xs` (12px)	`leading-tight`

2.3 强制约束

模块卡片 / 表格 / 弹窗的同类元素必须使用同一字号 class
禁止用 style="font-size: ..." 内联设置字号
文案不得硬编码中英文，必须走 useI18nStore（详见 §6 i18n）

3. 间距与布局

3.1 间距阶梯（4px 基准）

Token	值	Tailwind class
`space-1`	4px	`p-1 / m-1 / gap-1`
`space-2`	8px	`p-2 / m-2 / gap-2`
`space-3`	12px	`p-3 / m-3 / gap-3`
`space-4`	16px	`p-4 / m-4 / gap-4`
`space-6`	24px	`p-6 / m-6 / gap-6`
`space-8`	32px	`p-8 / m-8 / gap-8`

3.2 常用布局规则

卡片内边距：p-4（16px）
表单元素垂直间距：gap-3（12px）
段落之间：mb-4（16px）
按钮组：gap-2（8px）
模块面板与画布间隙：gap-4（16px）

3.3 容器最大宽度

内容主体：max-w-7xl（1280px）
设置 / 表单页：max-w-3xl（768px）
极宽画布（LinkCanvas / SignalCanvas）：无限宽 + 内部滚动

4. 图标规范

4.1 图标系统

来源：统一使用 @xi/ui-kit 的 <Icon> 组件 + xi-icons SVG 图标库
尺寸：默认 16px / 20px / 24px / 32px 四档（对应 size="sm" | "md" | "lg" | "xl"）
着色：通过 currentColor 继承父级文字色，禁止在 SVG 内硬编码 fill

4.2 模块图标 fallback 三级

参考 D3-FE-ARCH-007 §2.3：

模块自身 icon（module.iconUrl）
模块 category 默认 icon（按 20 类分组各有一个 fallback）
通用 default icon（最终兜底）

4.3 第三方图标库

允许使用：

Material Icons（通过 mkdocs-material 已集成）
Lucide Icons（lucide-vue-next）

禁止使用：

emoji（在标题 / 按钮 / 表格中）—— 仅允许在 admonition 主题图标中（由 Material 主题统一处理）
自绘 PNG 图标（破坏矢量缩放与暗色模式）

5. 交互与动效

所有可交互元素（button / link / input / 拖拽节点）必须有可见的焦点环：

/* @xi/ui-kit · 全局焦点态规则 */
.xi-focusable:focus-visible {
  outline: 2px solid theme('colors.xi.primary.500');
  outline-offset: 2px;
}

禁止用 outline: none 移除焦点环（除非提供等效替代视觉）
键盘 Tab 导航必须能覆盖所有可交互元素

5.2 动效时长

场景	时长	easing
微交互（hover / focus 颜色变化）	150 ms	`ease-out`
状态切换（toggle / accordion）	200 ms	`ease-in-out`
模态弹出 / 抽屉滑入	250 ms	`ease-out`
加载动画（spin / pulse）	1000-1500 ms	`linear` 循环
错误徽标闪烁	200 ms × 3 次	`ease-in-out`

5.3 减少动效（prefers-reduced-motion）

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

所有 apps 必须在全局 CSS 中包含此规则（已封装在 @xi/ui-kit/global.css）。

6. 国际化（i18n）

6.1 强制约束

所有面向用户的文案必须走 i18n key，不得硬编码中文 / 英文
Key 命名空间：
通用 UI：ui.{component}.{purpose}（如 ui.modal.confirm-cancel）
业务模块：modules.{moduleType}.{field}（如 modules.source.tone-frequency-label）
app 专属：{app}.{view}.{key}（如 xistudio.link-editor.save-button）

6.2 翻译文件位置

packages/ui-kit/src/i18n/
├── zh-CN.json
└── en-US.json

apps/xi-studio/src/i18n/
├── zh-CN.json
└── en-US.json

每个 app 自己的翻译文件只覆盖本 app 专属 key，通用 UI key 由 @xi/ui-kit 提供。

6.3 默认语言

默认 zh-CN
用户可在 TopBar 切换 en-US（持久化到 useI18nStore + localStorage）
Y2+ 计划支持 ja-JP / de-DE

7.1 核心规则

所有 button / link / icon-only-button 必须有 aria-label
所有 form input 必须有关联的 <label> 或 aria-labelledby
错误提示必须有 role="alert" + aria-live="polite"
状态指示灯必须有 aria-label 描述当前状态（如"信号源运行中"/"加载失败"）
颜色对比度：
正文文字与背景 ≥ 4.5:1
大字号（≥ 18px）≥ 3:1
非文字 UI（图标 / 边框）≥ 3:1

7.2 键盘导航

Tab / Shift+Tab 顺序与视觉顺序一致
Enter / Space 触发 button
Esc 关闭 modal / drawer / dropdown
拖拽区（<XiFileDropzone>）支持键盘 focus + Enter 触发文件选择

7.3 屏幕阅读器测试

所有重大功能上线前用 NVDA（Windows）或 VoiceOver（macOS）做一次完整流程
错误信息 / 加载状态 / 成功反馈必须能被读出

8. 性能基线

8.1 关键指标

指标	目标	测量工具
首屏 LCP（Largest Contentful Paint）	≤ 2.5 s	Lighthouse / Web Vitals
首屏 FID（First Input Delay）	≤ 100 ms	Web Vitals
首屏 CLS（Cumulative Layout Shift）	≤ 0.1	Web Vitals
画布拖拽 FPS（200 模块）	≥ 60 FPS	Chrome DevTools Performance
频谱图实时渲染（2048 点）	≥ 60 FPS	Chrome DevTools Performance
信号画布实时值更新（100 信号 × 100Hz）	≥ 60 FPS	Chrome DevTools Performance

8.2 优化要点

路由级懒加载（defineAsyncComponent）
大列表用虚拟滚动（vue-virtual-scroller）
WebSocket 高频消息批量化（参考 D3-FE-ARCH-003 §3.3 signal-value-event 批量推送）
实时值更新使用 requestAnimationFrame 节流，避免每个值都触发响应式更新

9. 错误处理与用户反馈

9.1 反馈层级

层级	用途	实现
Toast（短时）	操作成功 / 轻量错误	`useNotificationStore.show({ type, message })`
Alert（持续）	上下文相关警告 / 错误	`<XiAlert>` 组件
Modal（阻塞）	关键确认 / 严重错误	`<XiModal>` 组件
状态指示灯（持续）	模块 / 设备 / 链接的运行状态	`<SourceStatusDot>` / `<XiBadge>`

9.2 错误信息要求

错误提示必须包含三要素：

是什么错了（如 "wav 加载失败"）
为什么错（如 "文件大小超过 500 MB"）
如何恢复（如 retry 按钮 / 修改采样率 action）

反例与正例：

<!-- ❌ 错误 · 用户不知道发生了什么也不知如何恢复 -->
<XiAlert type="error" message="错误" />

<!-- ✅ 正确 · 三要素齐全 -->
<XiAlert
  type="error"
  message="wav 加载失败"
  description="文件大小 612 MB 超过 500 MB 上限"
  :actions="[{ label: '选择更小的文件', onClick: reselect }]"
/>

10. 命名约定

10.1 文件命名

类型	规则	示例
Vue 组件	PascalCase	`ModuleNode.vue` / `SignalCanvas.vue`
Composable	camelCase + `use` 前缀	`useSourceStateStore.ts` / `useDraggable.ts`
Store 文件	camelCase + `Store` 后缀	`audioEngineStore.ts`
工具函数	camelCase	`computeBiquadCoeffs.ts`
类型定义	PascalCase + `.types.ts` 或 `types.ts`	`LinkModel.types.ts`
常量	UPPER_SNAKE_CASE	`MAX_WAV_SIZE_MB = 500`

10.2 CSS class 命名

推荐使用 Tailwind utility class，不写自定义 class
必须自定义时使用 BEM：xi-module-node__toggle--running
禁止使用 emoji 作为 class 名

10.3 Vue Props / Events

Props camelCase 在 <script>，kebab-case 在 <template>：:max-size-mb="500"
Events 使用 kebab-case：@select / @update:visible
双向绑定一律用 v-model:xxx，禁止手写 :value + @input

11. PR 自查清单（提交前强制核对）

11.1 视觉与交互

色值通过 Tailwind class 引用，无硬编码 hex / rgb
字号通过 text-{size} class，无 style="font-size"
间距通过 p-/m-/gap- class，无内联 style
图标使用 <Icon> 组件，无 PNG / 内联 SVG fill
焦点态可见（Tab 导航有清晰焦点环）
动效遵守 §5.2 时长基线 + 支持 prefers-reduced-motion

11.2 内容与文案

所有用户可见文案走 i18n key，无硬编码中英文
错误信息三要素齐全（什么错 / 为什么错 / 如何恢复）
产品名拼写规范（XiStudio / XiDSP / 等，参考 md-writing-spec §11）

11.3 无障碍

button / link / icon-only-button 有 aria-label
form input 有关联 <label>
错误 alert 有 role="alert" + aria-live
状态指示灯有 aria-label
关键流程通过 NVDA / VoiceOver 测试

11.4 性能

路由懒加载（非首屏组件用 defineAsyncComponent）
大列表使用虚拟滚动
高频实时值用 RAF 节流
Lighthouse 评分 ≥ 90（Performance / Accessibility / Best Practices）

11.5 命名

Vue 组件 PascalCase，文件名与组件名一致
Composable 以 use 开头
CSS class 优先 Tailwind，自定义遵守 BEM
Props camelCase，模板用 kebab-case

11.6 文档与契约

新组件已在 D3-FE-ARCH-003 登记 API 契约
新 WebSocket 消息已在 @xi/protocol 加 zod schema
模块 UI 改动符合 D3-FE-ARCH-007 强制规范
Markdown 文档遵守 md-writing-spec v1.1（Admonition 8 白名单 / 表格无嵌 HTML / 标题无 emoji）

12. 与其他规范的关系

12.1 上游规范

D0 MD 写作规范 v1.1：Markdown 文件格式契约
D0 3+1 品牌色彩系统：色彩定义来源
D0 文档编号规范：本文档遵循其命名

12.2 同级规范

B-rd 软件开发规范：通用软件工程规范
B-rd 算法开发规范：DSP 算法侧规范
B-rd 测试规范：测试与质量标准

12.3 下游规范

D3-FE-ARCH-001 顶层架构：前端总体架构
D3-FE-ARCH-003 共享 UI kit：组件 API 实现层
D3-FE-ARCH-007 模块 UI 实现规范：模块卡片 / Library / Tuning Dialog
D3-FE-ARCH-010 Source/Sink 前端实施规范：source/sink 模块专属

13. DQ 清单

编号	问题	状态	建议
DQ-FE-UI-01	是否引入 Storybook + Chromatic 做视觉回归	⏳ 待定	Y1Q4 引入；早期手工 review
DQ-FE-UI-02	暗色模式是否同步上线	⏳ 待定	Y1Q3 灰度上线；MVP 阶段先聚焦浅色
DQ-FE-UI-03	是否提供英文之外的语言（ja / de）	⏳ Y2+	视客户需求决定优先级
DQ-FE-UI-04	第三方图标库是否限制为 Lucide 一家	⏳ 待定	建议统一 Lucide，减少 bundle

14. 版本与变更记录

版本	日期	作者	说明
v1.0	2026-05-09	work-cline	首版；研发中心级前端 UI 标准基线（色彩 / 字体 / 间距 / 图标 / 交互 / a11y / i18n / 性能 / 命名 / PR 自查）

附录 A · 引用

D0 MD 写作规范 v1.1
D0 3+1 品牌色彩系统
D0 文档编号规范
D3-FE-ARCH-001 顶层架构
D3-FE-ARCH-003 共享 UI kit 架构
D3-FE-ARCH-007 模块 UI 实现规范
D3-FE-ARCH-010 Source/Sink 前端实施规范