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。

验收与升级

更换变量后检查 /、/pricing、/tools/json-formatter、/design、/dashboard、/history、/settings、/login。
查看浅色、深色和手机宽度；确认导航可关闭，键盘焦点可见，表单标签与错误提示可读。
工具走一遍输入、处理、复制、下载和保存；不要只看截图。
执行 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 继续保留。

AgentBuff Stack 界面复用指南 ​

修改一个新站的外观 ​

浅色首页与公开页面 ​

公共导航与滚动 ​

React 组合示例 ​

样式编译与主题 ​

验收与升级 ​