使用设计系统
用 beUI、motion 组件和产品令牌搭建或改造页面,修改主题,并避开校验器会拒绝的导入。
项目里的每个页面都使用同一套设计系统:管理后台、工作台、登录与系统页,以及公开站。它分三层:挂在 :root 上的令牌、经 src/components/motion 转出的 @workspace/beui 组件,以及少量页面级模式。所有页面默认使用设计系统,不需要包裹层,也不需要设置属性。
准备工作
- 一个能用
pnpm dev运行的项目。 - 确定要搭建或改造的页面,以及它属于后台/工作台(
/admin、/app)还是公开页面。 - 如果是新页面,先读新增后台或工作台页面或替换落地页和定价页。本指南说明两者共用的视觉层。
认识各层
| 层 | 位置 | 用途 |
|---|---|---|
| 令牌 | src/styles/app.css 中的 :root 和 :root[data-theme="dark"] | 颜色、圆角和字体。bg-background、text-muted-foreground、border-border 这类 Tailwind 工具类读取它们 |
| beUI 源码 | packages/beui(workspace 包 @workspace/beui) | 组件本体:按钮、输入框、选择器、标签页、表格、surface、弹窗、浮层、表单布局 |
| motion 组件 | src/components/motion | 页面实际导入的入口。每个文件为本应用转出或适配一个 beUI 组件(button、input、select、switch、checkbox、tabs、surface、table、morphing-modal、drawer、tooltip、toast、empty-state、status-tag、skeleton、loader、theme-toggle) |
| 后台模式 | src/components/admin | 后台页面的整块区域:记录列表、指标行、面板、配置表单、保存状态 |
| 公开页原语 | src/components/marketing/ui/page-shell.tsx | 公开页面的区块、标题和面板 |
| 外壳 | src/components/layout | AppShell(后台、初始化页)和 AppConsoleLayout(工作台):侧边栏、页头,以及页面唯一的 <main> |
搭建一个页面
选定外框
后台页面渲染在 AppShell 里,工作台页面渲染在 AppConsoleLayout 里,公开页面渲染在 PublicMarketingShell 里。<main> 元素由外壳提供。页面内部使用 <section> 和 <div>,不要再写第二个 <main>。
先组合模式,再写标记
后台页面从 src/components/admin 的模式开始:
| 模式 | 导入路径 | 提供什么 |
|---|---|---|
AdminRecords | @/components/admin/admin-records | 由 columns、rows 和 rowKey 生成的可搜索、可分页记录列表;桌面端是表格,手机上是带标签的记录 |
AdminMetrics | @/components/admin/admin-metrics | 由 items(label、value、可选 detail)生成的一行指标 |
AdminPanel、AdminFacts | @/components/admin/admin-detail | 带标题和可选 actions 的面板,以及详情页用的标签/值网格 |
ConfigShell、ConfigPanel、ConfigPanelGrid、ConfigField、ConfigFormFields、ConfigSelect、ConfigSwitch、ConfigTextarea、ConfigMessage、ConfigDetailsTable | @/components/admin/config-layout | 所有 /admin/config/* 表单使用的布局 |
useAdminSave、AdminSaveFeedback | @/components/admin/admin-save | 感知权限的保存状态:allowed、pending、result、save(),以及保存成功或失败的提示 |
AdminSectionWorkspace | @/components/admin/admin-section-workspace | 一个带标题、页头 actions 和子页面链接(tabs)的 AppShell 页面 |
adminRouteFeedback | @/components/admin/admin-route-feedback | 展开到后台路由上的加载中与出错组件 |
useAdminSave("config.write") 从布局快照中读取当前用户的权限。allowed 为 false 时禁用表单并显示只读提示。服务端函数仍然会检查权限。
用 motion 组件填充
控件从 src/components/motion 导入,表单布局从 beUI 包导入:
import { FieldLegend, FieldSet } from "@workspace/beui/form-layout";
import { Button } from "@/components/motion/button";
import { Input } from "@/components/motion/input";
import { Surface, SurfaceContent } from "@/components/motion/surface";Button 和 ButtonLink 的 variant 可取 "primary" | "secondary" | "ghost" | "outline" | "danger"。@workspace/beui 没有入口导出,按需导入子路径(@workspace/beui/form-layout、@workspace/beui/components/motion/*);src/components/motion 里已有封装时优先用封装。
用基于令牌的工具类写样式
使用能解析到令牌的 Tailwind 工具类:bg-background、bg-card、bg-muted、text-foreground、text-muted-foreground、text-primary、border-border、ring-ring、rounded-lg。不要在页面里写十六进制颜色、rgb() 值或内联 style 颜色,因为硬编码的颜色不会跟随深色主题。
只有令牌表达不了差异时才用 dark: 变体。该变体跟随根元素上的 data-theme="dark"。
修改主题
在两个主题里同时修改令牌
打开 src/styles/app.css。产品令牌是 :root 末尾的那一段(注释以 "beUI: one set of tokens for the whole product" 开头),:root[data-theme="dark"] 里有同名的一组:
:root {
--background: #f6f5f1;
--foreground: #20231f;
--card: #ffffff;
--primary: #3859d6;
--primary-foreground: #ffffff;
--muted: #eeede8;
--muted-foreground: #62666e;
--accent: #e8edf9;
--border: #ddded8;
--ring: #3859d6;
--radius: 0.625rem;
}每个值都要在两段里一起改。更换品牌色时,同时设置 --primary、--ring 和 --brand-accent,并选一个在它上面仍然清晰的 --primary-foreground。--radius 控制所有圆角的比例。侧边栏有自己的一组 --sidebar-*。
不要动 Tailwind 映射
@theme inline 这一段把每个令牌映射成工具类颜色(--color-primary: var(--primary))。只有新增令牌并希望有对应工具类时才需要改它。
字体留在样式表里
字体在 app.css 顶部导入(Geist、Geist Mono 和 Noto Sans SC),并写在 :root 的 font-family 以及 @theme inline 的 --font-sans 里。换字体时,替换导入语句和这两处名称。
同步校验器和站点配置
pnpm validate:beui-console 断言六个核心令牌在两个主题下都是十六进制值,并把页面底色固定为 #f6f5f1(浅色)和 #101114(深色)。修改 --background 时,在同一次改动里更新 scripts/validate/beui-console.ts 中的这两个值。然后把 src/config/site.ts 里的 themeColor 和 backgroundColor 改成一致的颜色,见换成自己的品牌。
避开校验器会拒绝的写法
| 规则 | 由谁检查 |
|---|---|
admin、app、auth、system 下的任何路由都不能直接或间接导入 src/components/ui(shadcn)中的模块 | pnpm validate:beui-console |
每个后台和工作台页面都渲染在 AppShell 或 AppConsoleLayout 里 | pnpm validate:beui-console |
后台和工作台页面及其组件不再自带 <main> | pnpm validate:beui-console |
app.css 不在级联层之外声明裸元素规则(a、button、h1、table 等) | pnpm validate:beui-console |
| 令牌不限定在某个界面属性之下 | pnpm validate:beui-console |
落地页和定价页不硬编码颜色、不用内联样式、不用 ds-/mk- 类名前缀 | pnpm validate:example-landing |
新文件不带 !important | pnpm check |
src/styles/app.css 带有历史遗留的 !important 和选择器优先级债务,biome.json 只豁免了这一个文件。不要扩大豁免范围,也不要在整个仓库上运行 biome check --write --unsafe。这条命令会删掉样式表里的 !important,并改写 React hook 的依赖数组。
页面也不使用自己的类名前缀。如果页面来自设计工具,用上面的组件和工具类重新实现,不要粘贴它生成的类名。
新增 beUI 里还没有的组件
- 先看
src/components/motion,大多数控件已经有了。 - 确实没有时,从 beUI registry 把它安装到
packages/beui/src/components/,再在src/components/motion下加一个转出它的薄文件,写法参考src/components/motion/surface.tsx。编码 agent 可以通过 beUI MCP 服务(https://mcp.beui.dev/mcp)获取组件。 - 文字标签由应用的字典提供。需要渲染文字的 beUI 组件从
BeuiLocaleProvider取文案,各布局已经挂载了它。
验证
pnpm validate:beui-console
pnpm validate:example-landing
pnpm validate:mobile
pnpm check在两种主题(切换按钮在公开站页头和后台的账户菜单里)、两种语言、手机宽度和桌面宽度下分别打开页面。深色主题下仍是浅色背景的区域用了硬编码颜色。