使用设计系统

用 beUI、motion 组件和产品令牌搭建或改造页面,修改主题,并避开校验器会拒绝的导入。

项目里的每个页面都使用同一套设计系统:管理后台、工作台、登录与系统页,以及公开站。它分三层:挂在 :root 上的令牌、经 src/components/motion 转出的 @workspace/beui 组件,以及少量页面级模式。所有页面默认使用设计系统,不需要包裹层,也不需要设置属性。

准备工作

认识各层

层位置用途
令牌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/layoutAppShell(后台、初始化页)和 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"] 里有同名的一组:

src/styles/app.css
: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
新文件不带 !importantpnpm check

src/styles/app.css 带有历史遗留的 !important 和选择器优先级债务,biome.json 只豁免了这一个文件。不要扩大豁免范围,也不要在整个仓库上运行 biome check --write --unsafe。这条命令会删掉样式表里的 !important,并改写 React hook 的依赖数组。

页面也不使用自己的类名前缀。如果页面来自设计工具,用上面的组件和工具类重新实现,不要粘贴它生成的类名。

新增 beUI 里还没有的组件

  1. 先看 src/components/motion,大多数控件已经有了。
  2. 确实没有时,从 beUI registry 把它安装到 packages/beui/src/components/,再在 src/components/motion 下加一个转出它的薄文件,写法参考 src/components/motion/surface.tsx。编码 agent 可以通过 beUI MCP 服务(https://mcp.beui.dev/mcp)获取组件。
  3. 文字标签由应用的字典提供。需要渲染文字的 beUI 组件从 BeuiLocaleProvider 取文案,各布局已经挂载了它。

验证

pnpm validate:beui-console
pnpm validate:example-landing
pnpm validate:mobile
pnpm check

在两种主题(切换按钮在公开站页头和后台的账户菜单里)、两种语言、手机宽度和桌面宽度下分别打开页面。深色主题下仍是浅色背景的区域用了硬编码颜色。

下一步