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 CSSweb/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或ContentActionopal/layouts空状态与错误页IllustrationContent按钮Buttonopal/components禁用裸button输入类Opal 或 refresh-components禁用裸input、textarea、select文本Textopal/components用font与colorprops禁止裸文本节点图标仅限opal/icons禁止lucide-react或react-icons悬停显现Hoverableopal/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-dictionarystyle-dictionary.config.mjs统一管理确保明暗两套语义在同一套 Token 体系内联动。文本 props 接受 Markdown任何渲染为可见文本的 proptitle、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是旧命名碰到时应改名。类名拼接使用cnopal/utils禁止模板字符串拼接。Hooks 归属业务 feature hooks 放web/src/lib/feature/hooks.ts不依赖应用知识的 UI hooks 放 Opalweb/src/hooks/是最后的选择。i18nnext-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.rolecamelCase例如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_userexample.com/TestPassword123!见 web/tests/e2e/constants.ts应用运行于http://localhost:3000。相关 npm scripts 见 web/package.jsonlintoxlint、types:checknext typegentsc --noEmit、formatoxfmt、testjest、playwrightplaywright test、storybookStorybook 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），仅供参考