---
url: /docs/agentbuff-stack/design-system.md
---
# AgentBuff Stack 界面复用指南

本地组件预览：<http://localhost:4410/design>。该页有 `noindex`，不进入 sitemap。公开页、登录页和工作台共享纯白浅色底、炭黑深色主题、轻磨砂表面与 Figtree 无衬线排版；字体在本站提供，不向 Google Fonts 请求。

## 修改一个新站的外观

* 品牌名称、文案和业务配置：`packages/core/website.ts`。
* 颜色、字体、圆角和浅深主题：`packages/ui/design/tokens.css`。
* 共享 HTML 视觉模式：`packages/ui/design/patterns.css`。
* React 组件和 StyleX 布局：`packages/ui/design/index.tsx`。
* 营销站布局：`apps/web/layouts/BaseLayout.astro` 和 `apps/web/styles/globals.css`。
* 工作台导航：`apps/app/components/layout/`；后台排版：`apps/app/styles/globals.css`。

`--ui-*` 是品牌语义变量。Astryx 的 `--color-*`、现有 Radix/shadcn 的颜色变量都映射到它们；不要在页面另写一套颜色。新品牌至少同时修改 `--ui-brand`、`--ui-brand-hover` 和 `--ui-on-brand` 的浅深两组值，并检查文字对比度。

磨砂表面使用 `--ui-frost` 和轻量背景模糊；`--ui-surface-tint` 提供柔和表面层次。定价重点卡片和底部引导区使用 `--ui-contrast`、`--ui-on-contrast`、`--ui-contrast-muted` 与 `--ui-contrast-border`，在浅深主题下自动反转黑白关系。背景的细颗粒纹理为静态样式，不覆盖交互控件。

改变 `--theme-color` 时，还需同步 `apps/app/index.html`、`apps/app/public/site.manifest`、`apps/web/layouts/BaseLayout.astro` 的预绘制值。这些在 CSS 加载前执行，无法从样式表读取颜色。`site:create` 会更新副本的名称、manifest 名称和域名，配色默认继承这份模板。

## 浅色首页与公开页面

浅色主题参考 EasyStarter 的留白和黑白关系：纯白背景、淡灰边框、黑色主按钮、圆角胶囊操作与居中标题。保留本站 Figtree 字体和品牌标记，深色继续使用哑光黑。浅色颗粒更轻，强度由 `--ui-grain-opacity` 控制；浅深颜色仍统一维护在共享变量中。

首页淡网格仅是 CSS 装饰，不参与交互。输入与输出示例由共享 `runTool` 在构建时产生，链接进入实际 JSON 工具，不是模拟工具功能。首屏没有新增 React 岛，也没有引入远程字体、背景图片或动画库。

公开导航共用 `packages/core/navigation.ts`，首页根路径只在 `/` 上高亮，博客文章路径会高亮 `Blog`。新增同级公开页面时更新导航及 sitemap；`blog.enabled=false` 自动隐藏所有消费端的博客导航。博客卡片、搜索栏和文章目录使用同一套语义配色，手机尺寸下筛选、示例和目录改为纵向排列。

功能内容在 `apps/web/lib/features.ts`，由首页和 `/features` 复用。只列当前工具、保存历史、工作台与教程等已实现能力；支付、存储、生成任务等模块需要各自真实验收后再加入公开描述。

## 公共导航与滚动

公共导航组件为 `apps/web/components/SiteHeader.astro`，所有公开页面通过 `BaseLayout` 复用。页首不使用分隔横线，滚动超过 48px 后导航收窄为带磨砂底、细边框和柔和阴影的悬浮栏；回到顶部恢复开放形态。宽度与内边距过渡使用 CSS，滚动监听为被动监听，并通过 `requestAnimationFrame` 合并更新，没有添加动画库或 React 岛。

960px 及以下改用原生 `details` 菜单，支持键盘展开、Escape 关闭并还原焦点、点击外部关闭和跨页访问。禁用脚本仍可通过原生展开菜单访问所有公共页面。系统减少动效时关闭收拢过渡与菜单入场动画，悬浮导航仍可用。

导航固定于视口，初始占位保持正文位置；文章目录和锚点保留顶部空间，避免标题被导航遮挡。主题图标使用 SVG，与 HTML 主题属性同步，导航的颜色仍来自共享语义变量。

## React 组合示例

```tsx
import { Action, Page, PageHeading, Surface } from "@repo/ui/design";

export function Example() {
  return (
    <Page>
      <PageHeading
        eyebrow="Your workspace"
        title="A new task."
        description="Bring your input and review the result."
      />
      <Surface padding={6}>
        <Action
          label="Start processing"
          variant="primary"
          onClick={() => {
            /* 调用实际处理器 */
          }}
        />
      </Surface>
    </Page>
  );
}
```

`Action`、`Surface`、`TextInput` 和 `TextArea` 直接导出 Astryx 原组件，不复制库源码，也不创建只转发 props 的组件包装。`Page`、`PageHeading`、`Metric`、`Brand`、`AuthLayout` 提供已在多个真实页面复用的版式。业务请求、会话和路由继续放在消费应用。

Astryx 使用 `label`、`isDisabled`、`isLoading`，不是旧组件的 `children`、`disabled`。`TextArea.onChange` 的第一个参数是字符串。输入标签由库关联生成的 ID，不要额外添加重复标签。密码表单仍使用支持原生 `minLength`/`maxLength` 的现有输入控件，错误、验证、无障碍和授权逻辑保持原流程。

保留的 Radix 对话框、下拉菜单、单选主题控件、原生验证表单通过共享变量获得同样的外观。没有为了换样式重写这些行为。以后新增界面优先 Astryx，已有复杂控件按真实业务需要迁移。

工作台在 `apps/app/tailwind.config.css` 预先声明样式层顺序，把 Astryx 的 `reset` 放在组件与工具类之前。否则晚导入的重置层会覆盖现有按钮背景、文字颜色和输入框边框，导致操作按钮看起来只剩普通文字；不要通过每个页面重复覆盖来修复这个顺序问题。

## 样式编译与主题

Astryx 0.6.6 使用随包提供的预编译 CSS。我们自己的 React 版式由 StyleX 0.19.1 编译；App 的 Vite 和 Web 的 Astro/Vite 都配置 `@stylexjs/unplugin`，顺序在 React 编译前。Vitest 使用同一插件的 Rollup 转换器，避免启动只供开发 CSS 热更新的轮询服务器。生产构建输出静态 CSS，不在浏览器调用 `stylex.create` 生成样式。

两端都导入 `@repo/ui/design/styles.css`。CSS 包含 Astryx reset、组件、neutral 主题，再用未分层的品牌变量覆盖库的主题层。没有导入 Astryx 的 Tailwind 颜色桥，因为该桥的 `text-primary` 语义与现有表单的 `primary` 主色不同。

HTML 的 `data-astryx-theme="neutral"` 激活库主题。我们不增加 Astryx `Theme` 根提供器：它会再次写 `<html>` 的主题属性。App 继续由原有 Jotai `useTheme()`、预绘制脚本和 `ThemeSync` 控制；公开页的轻量脚本使用相同 `theme` JSON 存储协议，支持系统主题、跨标签页切换和存储不可用的当前页切换。没有第二套持久化主题状态。

Astro 公开页和博客仍构建完整静态 HTML。只有工具和组件预览加载 React 交互岛；公开页的标题、正文、canonical、结构化数据不依赖浏览器执行 JavaScript。

## 验收与升级

1. 更换变量后检查 `/`、`/pricing`、`/tools/json-formatter`、`/design`、`/dashboard`、`/history`、`/settings`、`/login`。
2. 查看浅色、深色和手机宽度；确认导航可关闭，键盘焦点可见，表单标签与错误提示可读。
3. 工具走一遍输入、处理、复制、下载和保存；不要只看截图。
4. 执行 `bun app:build`、`bun web:build`、`bun typecheck`、`bun web:check`、`bun lint`、`bun format:check`；主题和认证改动再运行已有测试。

Astryx 为 Beta，版本已固定。升级时核对组件 API、构建和上述真实流程。Astryx 与 StyleX 的 MIT 及字体的 OFL 许可见根目录 `THIRD-PARTY-NOTICES.md`，原模板 `LICENSE` 继续保留。