Onyx 前端开发规范指南：基于 Opal 设计系统的 web/ 与 desktop/ 编码标准
【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer
导读
本文基于 web/CLAUDE.md 整理而成，它定义了 Onyx 前端（web/目录的 Next.js 应用与desktop/目录的 Tauri 外壳）的统一开发标准。核心思想是：所有 UI 一律来自 Opal 设计系统（@opal/*）与refresh-components，禁止直接使用原生 HTML 控件、裸文本节点与旧组件库。读完本文，你将掌握组件来源的优先级选择、设计 Token 与暗色模式的正确用法、i18n 国际化与类型安全的强制约定，以及组件测试与 E2E 测试的执行方式，可直接套用到 Onyx 前端的日常开发中。
适用范围与文件约定
这些标准同时适用于web/与desktop/。仓库约定：每个 Opal 组件与布局旁边都带有一个README.md，说明其架构、props 与用法示例（例如 Opal components 目录 中的组件级 README）。规范原文明确要求："Read that README instead of guessing props"—— 在使用某个组件前，必须先读它旁边的 README，而不是靠猜 props。
从仓库根目录的 AGENTS.md 可以确认，前端技术栈为Next.js 16、React 19、TypeScript、Tailwind CSS，web/lib/opal与web/lib/shared以 workspace 形式作为本地包（@onyx-ai/opal、@onyx-ai/shared，见 web/package.json）。web/AGENTS.md 是前端规范的完整入口，本文所依据的web/CLAUDE.md是其核心内容摘要。
组件来源：优先级顺序与禁用清单
规范的组件引入顺序（优先级从高到低）如下：
web/lib/opal/src/（@opal/*）：设计系统本体，是 UI 的第一来源。web/src/refresh-components/：尚未沉淀进 Opal 的生产组件。web/src/sections/（功能组合件，实体卡片位于sections/cards/）与web/src/layouts/。
严禁从web/src/components/引入任何内容 —— 它是遗留代码且正在被删除。唯一的例外是src/components/icons/icons.tsx中的createLogoIcon（已在仓库中确认该文件存在）。
@opal/*内部又分两层，对应 core README 中"像 Rust 的corecrate 一样"的比喻：
@opal/core：最底层的原语（Interactive、Animations等），用于构建组件，应用代码不应直接使用。@opal/components与@opal/layouts：基于 core 构建的高层组件，是应用代码的消费入口（如Button、OpenButton、SelectButton、Tag，见 components README）。
常见场景的标准组件选择
| 场景 | 应使用的组件 |
|---|---|
| 管理页与设置页 | SettingsLayouts.{Root,Header,Body}（来自@opal/layouts） |
| 图标 + 标题 + 描述 | Content或ContentAction（@opal/layouts） |
| 空状态与错误页 | IllustrationContent |
| 按钮 | Button（@opal/components），禁用裸<button> |
| 输入类 | Opal 或 refresh-components，禁用裸<input>、<textarea>、<select> |
| 文本 | Text（@opal/components），用font与colorprops；禁止裸文本节点 |
| 图标 | 仅限@opal/icons，禁止lucide-react或react-icons |
| 悬停显现 | Hoverable（@opal/core）；若必须手写，需加no-hover:opacity-100以兼容触屏设备 |
关于图标缺失的处理流程：若@opal/icons中缺少所需图标，应通过 Figma MCP 工具从 Figma 引入，并添加到lib/opal/src/icons/目录中（该目录已在仓库中确认存在）。
refresh-components 的覆盖范围很广，仓库中实际包含AreaChart、Calendar、Chip、Collapsible、DateRangePicker、FrostedDiv、Keycap、PreviewImage、SimplePopover、SimpleTabs等组件，以及avatars/、buttons/、cards/、form/、inputs/、messages/、modals/、texts/、tiles/等子目录，每个组件旁通常伴随.stories.tsx或.test.tsx文件（如DateRangePicker.test.tsx）。
有原因的规则：设计 Token、暗色模式与数据获取
禁止dark:Tailwind 修饰符
设计 Token 已同时定义明暗两套主题（仓库web/lib/shared/tokens/下即有semantic-light.json与semantic-dark.json），手动覆盖会破坏暗色模式。因此整个代码库禁止使用dark:修饰符，唯一允许使用的是createLogoIcon。
禁止内置 Tailwind 颜色
不得使用bg-gray-100、text-blue-600这类内置颜色类，必须使用 Token 类，包括：
text-0Xbackground-neutral-0Xbackground-tint-0Xborder-0Xaction-selection-0Xaction-danger-0Xstatus-{info,success,warning,error}-0Xtheme-*
Token 定义位于 web/lib/shared/tokens/，包含primitives.json、semantic-light.json、semantic-dark.json、shadow.json、size.json、typography-presets.json、typography.json等文件，由 style-dictionary（style-dictionary.config.mjs）统一管理，确保明暗两套语义在同一套 Token 体系内联动。
文本 props 接受 Markdown
任何渲染为可见文本的 prop（title、description、label）应声明为string | RichStr（来自@opal/types），并用Text渲染。调用方通过markdown()（@opal/utils）显式启用解析，纯字符串永远不会被当作 Markdown 解析。
尺寸 props 默认"md"
当 prop 类型是@opal/types的SizeVariants（或其子集）时，默认值统一为"md"。从 types.ts 源码可见完整尺寸阶梯："fit" | "full" | "xl" | "lg" | "md" | "sm" | "xs" | "2xs"，并衍生出ContainerSizeVariants（排除full、xl）等便捷类型。
优先 padding，避免包 div
使用组件的paddingprop 而非在外面套一层<div>；若库组件没有该 prop，应优先给组件本身增加 prop，而不是添加 wrapper。
数据获取：useSWR
数据获取统一在客户端、需要数据的组件内部使用useSWR，加载期间展示 loader；禁止在页面顶层拉取数据再向下传递。这与 AGENTS.md 中"调用后端一律经由前端（如http://localhost:3000/api/persona而非http://localhost:8080/api/persona）"的约定配合使用。
代码风格约定
- 绝对导入：
@/指向src/，@opal/指向 Opal；禁止../相对路径。 - 函数声明：组件用
function声明，不用箭头函数。 - 类型组织：props 接口（
FooProps）与组件放在同一文件；共享类型放入同目录的types.ts。interfaces.ts是旧命名，碰到时应改名。 - 类名拼接：使用
cn（@opal/utils），禁止模板字符串拼接。 - Hooks 归属：业务 feature hooks 放
web/src/lib/<feature>/hooks.ts；不依赖应用知识的 UI hooks 放 Opal；web/src/hooks/是最后的选择。
i18n（next-intl）约定
- 禁止硬编码面向用户的字符串：
src/下的裸文本会触发 oxlint 规则i18n/no-raw-jsx-text而失败。客户端用useTranslations("<namespace>")，服务端用await getTranslations(...)。 - 单一事实来源：web/src/i18n/messages/en.json 是英文源文件；新增或修改 key 时，必须为该目录下所有其他语言文件提供最佳翻译。缺失或多余的 key 会导致
types:check失败；各语言之间的 ICU 结构必须一致（由 web/src/i18n/tests/catalog.test.ts 校验）。 - Key 命名规范：
<namespace>.<section>.<element>.<role>，camelCase，例如settings.appearance.colorMode.title。英文文案的措辞修改不会改变 key。 - ICU：参数与复数一律用 ICU 语法，禁止拼接翻译片段。
- 日期与数字：使用
useFormatter与useLocale，禁止硬编码"en-US"。 - 逻辑属性：新样式使用
ms-、pe-、start-等逻辑属性，而非ml-、pr-、left-。
仓库中web/src/i18n/目录实际包含messages/、config.ts、config.test.ts、request.ts、types.d.ts与__tests__/，i18n 管道与类型生成均已就位。
测试约定
- 组件测试（Jest + React Testing Library）：规范见 web/tests/README.md。
- E2E 测试（Playwright）：硬性规则（Page Object Model、locator 优先级）见 web/tests/e2e/README.md。
- 运行 E2E 测试：必须使用
cd web && bun run playwright <TEST_NAME>；不要使用bunx或npx，因为它们可能拉取未锁定版本的 Playwright。根目录 AGENTS.md 还提示，Playwright 全局 setup 会创建管理员账号admin_user@example.com/TestPassword123!（见 web/tests/e2e/constants.ts），应用运行于http://localhost:3000。
相关 npm scripts 见 web/package.json：lint（oxlint）、types:check（next typegen+tsc --noEmit）、format（oxfmt）、test（jest）、playwright（playwright test）、storybook（Storybook dev server）等。
总结
Onyx 前端规范的核心可以浓缩为三句话：
- 组件来源有纪律：优先 Opal → refresh-components → sections/layouts，绝不触碰正在删除的旧
components/。 - 样式必须走 Token：不用
dark:、不用内置 Tailwind 颜色，明暗主题由 Token 统一驱动。 - 国际化与类型检查是硬门槛：所有用户可见字符串走 next-intl 与
en.json单一事实源，缺 key 或 ICU 结构不一致都会让 CI 失败。
对于任何 Opal 组件，先读它旁边的 README 再使用 —— 这是避免踩坑、保持前端代码库长期一致性的最佳实践。
【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
