10.2 · 样式与主题系统（Styling and Theme System）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节10.2 状态全文译文模块界面与交互、系统架构、配置治理、图谱与关系

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Styling and Theme System 上一章10.1 下一章10.3

源码线索

web/lib/opal/src/components/buttons/button/components.tsx
web/lib/opal/src/components/buttons/line-item-button/README.md
web/lib/opal/src/components/buttons/line-item-button/components.tsx
web/lib/opal/src/components/buttons/open-button/components.tsx
web/lib/opal/src/components/buttons/select-button/components.tsx
web/lib/opal/src/components/buttons/sidebar-tab/README.md
web/lib/opal/src/components/buttons/sidebar-tab/SidebarTab.stories.tsx
web/lib/opal/src/components/index.ts
web/lib/opal/src/components/popover/README.md
web/lib/opal/src/components/popover/components.tsx

模块标签

界面与交互
系统架构
配置治理
图谱与关系
测试、发布与运维

章节正文

样式与主题系统

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/10.2-styling-and-theme-system

样式与主题系统

概览与核心配置

样式系统在 web/src/app/globals.css 中初始化，该文件导入模块化 CSS 文件并定义基础的 Tailwind 层。

Tailwind 配置

系统配置了 darkMode: "class"，允许应用通过向根元素添加 .dark 类来切换主题 web/tailwind-themes/tailwind.config.js:6-6。

Tailwind 配置中的自定义扩展包括：

断点： 自定义屏幕尺寸，如 sm: "724px"、md: "912px"，以及基于高度的特定查询，如 tall 和 short web/tailwind-themes/tailwind.config.js:62-73。
间距与尺寸： 聊天元素的专用宽度，例如 message-default: "740px" 和 searchbar: "850px" web/tailwind-themes/tailwind.config.js:78-88。
动画： 定义了 subtle-pulse、fade-in-scale 以及与 Radix 兼容的 collapsible-down/up 过渡效果 web/tailwind-themes/tailwind.config.js:24-58。

全局 CSS 组织

globals.css 文件作为专用样式表的入口点：

布局： general-layouts.css、z-index.css 和 sizes.css web/src/app/globals.css:8-15。
组件： button.css、card.css、inputs.css 和 knowledge-table.css web/src/app/globals.css:2-10。
排版： 定义了 "KH Teka" 字体的 font-face，并设置了根字体变量 web/src/app/globals.css:19-25 web/src/app/globals.css:179-186。

来源： web/src/app/globals.css:1-30 web/tailwind-themes/tailwind.config.js:1-100

设计令牌与 CSS 变量

Onyx 使用 CSS 变量来维护一致的设计语言，这些变量直接映射到 Figma 设计规范。

颜色系统

颜色在 tailwind.config.js 中映射到语义变量（例如 --text-01、--background-neutral-00）web/tailwind-themes/tailwind.config.js:95-175。这种抽象便于主题切换，并确保组件与特定十六进制颜色代码解耦。

边框与模糊效果

标准化的圆角和效果在全局样式表的 @layer base 中定义：

边框圆角： 范围从 --border-radius-02: 0.125rem 到 --border-radius-full: 64rem web/src/app/globals.css:33-40。
背景模糊： 为覆盖层和模态框提供三个级别的模糊效果 web/src/app/globals.css:43-47。
阴影： 像 .shadow-01 和 .shadow-02 这样的实用工具类使用内部变量来实现一致的深度感 web/src/app/globals.css:135-147。

来源： web/src/app/globals.css:31-48 web/tailwind-themes/tailwind.config.js:95-175

排版系统

排版系统分为几个层级：标题、主要内容、主要 UI 和次要样式。

类别	用途	主要字体	字重
标题 H1	页面标题	Hanken Grotesk	600 `web/src/app/globals.css:190-196`
主要内容	聊天消息 / 正文	Hanken Grotesk	450 `web/src/app/globals.css:224-230`
主要 UI	按钮 / 导航	Hanken Grotesk	500 `web/src/app/globals.css:262-268`
次要	标签 / 元数据	Hanken Grotesk	400 `web/src/app/globals.css:296-302`
等宽	代码 / 技术数据	DM Mono	400 `web/src/app/globals.css:252-258`

实现细节

排版通过 globals.css 中定义的实用工具类应用 web/src/app/globals.css:190-320。系统还包含一个特定的 .prose 配置，用于处理聊天界面中的 Markdown 渲染，调整标题、列表和段落的边距，以确保与聊天图标对齐 web/src/app/globals.css:74-127。

来源： web/src/app/globals.css:174-325 web/tailwind-themes/tailwind.config.js:74-77

Opal 组件库

Opal 库（web/lib/opal）是 Onyx 的内部设计系统。它提供了封装应用视觉标识的高级 React 组件。

组件架构

实体关联：UI 元素到 Opal 组件

此图将应用中使用的视觉系统名称桥接到 Opal 库中的具体组件实现。

Onyx · 实体关联：UI 元素到 Opal 组件 · 图 1

来源： web/lib/opal/src/components/index.ts:1-134 web/lib/opal/src/components/buttons/button/components.tsx:53-123 web/lib/opal/src/components/buttons/open-button/components.tsx:83-177

关键组件

1. 按钮系统

标准 Button 组件使用 Interactive.Stateless 和 Interactive.Container 来处理突出程度（主要、次要、第三级）和尺寸 web/lib/opal/src/components/buttons/button/components.tsx:53-115。它通过 Radix UI 原语支持工具提示 web/lib/opal/src/components/buttons/button/components.tsx:118-123。

2. OpenButton（可折叠）

用于下拉触发器和可折叠 UI。它支持 foldable 属性，在该属性下标签和 V 形图标会动画消失，仅保留图标可见 web/lib/opal/src/components/buttons/open-button/components.tsx:149-163。它从 Radix 数据属性派生其交互状态（例如 "open"）web/lib/opal/src/components/buttons/open-button/components.tsx:98-103。

3. LineItemButton

一种用于列表的专用按钮，它包装了 Interactive.Stateful 和 ContentAction web/lib/opal/src/components/buttons/line-item-button/components.tsx:52-106。它专为高密度 UI 布局（如侧边栏或设置列表）而设计。

4. 内容布局

该库包含 ContentMd、ContentLg 和 ContentXl，用于实现一致的标题和描述模式 web/lib/opal/src/layouts/content/ContentMd.tsx:128-230。这些组件支持内联编辑（editable 属性）和状态图标（auxIcon）web/lib/opal/src/layouts/content/ContentMd.tsx:42-75。

来源： web/lib/opal/src/components/index.ts:9-50 web/lib/opal/src/components/buttons/button/components.tsx:1-125 web/lib/opal/src/components/buttons/open-button/components.tsx:1-179 web/lib/opal/src/components/buttons/line-item-button/components.tsx:1-108 web/lib/opal/src/layouts/content/ContentMd.tsx:1-230

应用集成

样式和 Opal 组件被集成到主要的应用页面中，如 AppPage 和 NRFPage。

组件实现：输入与聊天布局

此图将高级应用部分映射到底层布局和输入组件。

Onyx · 组件实现：输入与聊天布局 · 图 2

实现细节

AppInputBar： 使用 useContentEditable 钩子来处理富文本输入，包括将文件粘贴为磁贴 web/src/sections/input/AppInputBar.tsx:148-170。它集成了 Opal 的 Button 和 SelectButton，用于文件选择和深度研究切换等操作 web/src/sections/input/AppInputBar.tsx:55-56。
动效与过渡： 系统使用 motion/react（Framer Motion）来实现页面级别的过渡，并使用 "Fade" 组件来平滑 UI 更新 web/src/refresh-pages/AppPage.tsx:81-105。
布局原语： 来自 web/src/layouts/general-layouts 的 Section 组件提供了一个标准化的容器，用于在整个应用中实现水平和垂直对齐 web/src/refresh-pages/AppPage.tsx:8-8。

来源：

web/src/refresh-pages/AppPage.tsx:81-105
web/src/sections/input/AppInputBar.tsx:148-200
web/src/app/nrf/NRFPage.tsx:170-180
web/src/app/craft/components/InputBar.tsx:169-191