---
url: /docs/frontend/ui.md
---
# 组件与主题

## 当前设计系统

公开站和工作台共享 `packages/ui/design/` 的颜色、字体、间距及圆角变量。React 共享组件使用 Astryx 与 StyleX，Astro 页面使用同一组样式变量。原有工作台基础组件保留在 `packages/ui/components/`，逐步按共享设计规范维护。

完整入口、组件用法和调整方法见 [设计系统](../agentbuff-stack/design-system.md)。不要在每个页面各自定义一套主色和按钮。

## 样式文件职责

| 文件                  | 内容                       |
| --------------------- | -------------------------- |
| `design/tokens.css`   | 颜色、字体、间距和主题变量 |
| `design/patterns.css` | 常用布局与页面组合样式     |
| `design/styles.css`   | 设计系统样式入口           |
| `design/index.tsx`    | 可复用的 React 组件        |
| `styles.css`          | 基础组件及全局样式         |

StyleX 的编译设置与共享包的路径需要保持一致。改动后分别构建公开站和工作台，不能只检查其中一个应用。

## 主题配置

默认主题和切换入口由 `websiteConfig.appearance` 控制。工作台主题逻辑在 `apps/app/lib/theme.tsx`；公开站使用同一配置初始化主题。修改默认主题需要重新构建。

## 新增组件

先复用已有组件；确实需要新增时，以命名导出提供小而明确的接口，支持键盘操作、可见焦点、加载和禁用状态。客户界面文案仍遵循产品目标语言，中文仅用于本维护教程。

`bun ui:add` 可用于引入现有基础组件，生成后仍需检查项目命名、导入和样式。不要将生成代码直接当作最终设计。

## 验证

检查浅色、深色、窄屏、键盘焦点以及错误状态。遇到样式缺失，依次确认入口导入、变量定义、StyleX 编译路径和构建产物。