[RFC] 001 - Lobe UI 2.0

[canisminor1990]

Tip

🤔 RFC 构思阶段，欢迎跟帖讨论 ❤️

背景

Lobe UI 1.0 建立之初只是服务于 LobeChat 和 LobeTheme 相关项目的公共组件，但随着组件增多和应用场景的增加，1.0 碎片化的组件结构和非良好的接口设计在社区中的适配表现开始变得不那么尽如人意。要解决以上种种问题必然会面临一大波 Breaking Change, 为了方便后续 Migrate ，在此会将前期构思阶段记录下来。

CSS in JS + NextJS RSC 之痛

在目前应用过程中其实遇到很多问题：

• 亮暗色: Page Router 中闪白，在 App Router 中解决;
• useStyle: 必须在 use client 下运行, 使得很多原可以在 server 侧渲染的组件也必须放在 client 侧;
• useResponsible: 和 RSC 理念违背，Layout 部分在入口就应该分发，组件部分需要改为纯 css 的媒体查询提升性能.

期间也一度想切换至 shadcn + tailwind 的生态方案，但依然会遇到很多问题：

• tailwind: 纯主观层面无法接受大量堆砌的原子类 class, 后期可读性很差，特别是加上各种伪类语法糖后;
• shadcn: 虽然在原始风格上比 antd 更接近 Lobe 整体的 UI 观感，但缺乏高阶组件和结构化数据的支持，优点在于比 antd 组件定制容易太多 (antd 动不动一个组件几千行代码，想改核心几乎劝退)，但缺点依然在于组件的完备性，比如 antd DatePicker 就处理了大量逻辑和边界情况 (这也是几千行代码的含金量);
• 重构成本: 目前 Lobe UI 基本覆盖了 LobeHub 的所有项目，迁移生态的重构成本过于庞大。

未来的契机：

• react 19: antd-style 的最大限制就是现在用了ConfigProvider 和useContext来拿上下文。而useContext是不支持在服务端跑的,但这个问题在react19里可以解，到时候会提供一个use方法，可以直接use(configprovider)拿到上下文。
• StyleX: Meta 目前依然使用 cssinjs + rsc 的方案，下半年 antd-style 样式引擎会迁到 StyleX 上，这样运行时编译时都得以支持。

遗留问题：

• Vercel V0 : 后续如何对接 vercel v0 生态

结论

Lobe UI 2.0 会继续基于 antd 二次开发，同时增加对于 NextJS 特性的适配力度 (但依然保持独立使用的能力)，主要精力会放在组件性能重构、接口规范与样式定制性上，RSC 支持暂时等待社区发展。

---

Note

设计思路

• 更清晰的入口文件分类
• 提升组件性能 (样式注入+组件层级)
• 更规范主流的接口设计
• 更好的 i18n 支持方式

---

入口文件分离

在 1.0 中除了后期的 mdx 组件外，其余组件都在同一个 index 入口文件中，显得过于冗杂，在 2.0 中将会按组件类型将入口文件进行隔离，目前的入口文件草案为

• @lobehub/ui : 基础通用性组件
• @lobehub/ui/chat : llm chat 部分组件
• @lobehub/ui/mobile : 移动端组件
• @lobehub/ui/mdx : mdx 组件
• @lobehub/ui/brand : LobeHub 品牌类组件
• @lobehub/ui/awesome : 特殊效果形组件，如 Hero \ Landing 中的特效
• @lobehub/ui/server : 用于 NextJs RSC 的布局组件
• @lobehub/ui/hooks : 一些 UI 常用的 hooks ，比如何种滚动事件的处理
• @lobehub/ui/storybook : 一些 UI 组件的调试工具

生态包

• @lobehub/icons : AI/LLM 图标库
• @lobehub/charts : Lobe 图表组件库

组件性能

1. 精简 Theme Custom Token

有非常多自定义 Token 在实际生产中其实并没有运用到，虽然当初设计时考虑得非常完备，但这也导致了主题初始化时将产生非常多无用的实例。

2. 减少组件层级

尽量引入 as 和 asChild 减少组件无意义层级

as

• 目前命名不是很统一，比如在 Flexbox 中叫 as , 在 Antd Flex 中叫 component , 在 Antd Button 中叫 htmlType 且只支持 string
• 类型不够安全和完备，只能使用泛类型处理，且有潜在的接口冲突风险

asChild

• radix 工具组件，目前在 shadcn 中运用较多：https://www.radix-ui.com/primitives/docs/utilities/slot
• 优点是类型完备和安全，不要考虑接口继承的问题
• 缺点是逻辑有点逆向

// your-button.jsx
import React from 'react';
import { Slot } from '@radix-ui/react-slot';

function Button({ asChild, ...props }) {
  const Comp = asChild ? Slot : 'button';
  return <Comp {...props} />;
}

// your-button.jsx
import React from 'react';
import { Slot, Slottable } from '@radix-ui/react-slot';

function Button({ asChild, leftElement, rightElement, ...props }) {
  const Comp = asChild ? Slot : 'button';
  return (
    <Comp {...props}>
      {leftElement}
      <Slottable>{children}</Slottable>
      {rightElement}
    </Comp>
  );
}

3. 降低样式复写侵入性

• 尽量使用 ConfigProvider 进行 token 层面复写取代大规模 css 层面复写
• 在一些高自定义组件上，改为使用 rc 自定义，而不使用样式复写
• 使用 where https://ant-design.github.io/antd-style/zh-CN/guide/components-usage#%E5%BC%80%E5%90%AF-where-%E9%80%89%E6%8B%A9%E5%99%A8

// components/button.ts
import { cva } from "class-variance-authority";
 
const button = cva(["font-semibold", "border", "rounded"], {
  variants: {
    intent: {
      primary: [
        "bg-blue-500",
        "text-white",
        "border-transparent",
        "hover:bg-blue-600",
      ],
      // **or**
      // primary: "bg-blue-500 text-white border-transparent hover:bg-blue-600",
      secondary: [
        "bg-white",
        "text-gray-800",
        "border-gray-400",
        "hover:bg-gray-100",
      ],
    },
    size: {
      small: ["text-sm", "py-1", "px-2"],
      medium: ["text-base", "py-2", "px-4"],
    },
  },
  compoundVariants: [
    {
      intent: "primary",
      size: "medium",
      class: "uppercase",
      // **or** if you're a React.js user, `className` may feel more consistent:
      // className: "uppercase"
    },
  ],
  defaultVariants: {
    intent: "primary",
    size: "medium",
  },
});
 
button();
// => "font-semibold border rounded bg-blue-500 text-white border-transparent hover:bg-blue-600 text-base py-2 px-4 uppercase"
 
button({ intent: "secondary", size: "small" });
// => "font-semibold border rounded bg-white text-gray-800 border-gray-400 hover:bg-gray-100 text-sm py-1 px-2"

4. 更结构化的变体

考虑引入 cva 使变体样式更结构化

https://cva.style/docs/getting-started/variants

5. 去除 useResponsible

useResponsible: 和 RSC 理念违背，Layout 部分在入口就应该分发，组件部分需要改为纯 css 的媒体查询提升性能.

6. 抽象更多常用的 stylish

在实际使用中还是会遇到挺多重复使用的变体样式，在减少自定义 token 的基础上考虑对于自定义 stylish 进一步扩充

---

接口规范

Warning

• 目前某些自定义接口命名不是非常主流，如大部分组件的样式变体用的是 type，主流应该是 variant
• 一些二开的 Antd 组件类型继承不完备

解法：

接口规范 Follow antd 的接口设计规范：Wiki: API Naming rules (ant-design/ant-design), 尽量减少非主流命名

...

---

滚动条

Warning

滚动条值得单独拿出来说一说，之前的处理方式一直不是很好，目前主要的问题如下：

• 如果使用纯 css 定制方案，定制的滚动条会占用固定宽度，就算在不需要滚动的场景下依然会有宽度
• 在某些全屏禁用滚动的场景下，如弹窗、图片预览，由于滚动条小时，渲染宽度会发生变化，导致抖动
• 使用原生滚动条在 windows 中过于丑陋和占用空间

解法：

考虑使用 https://github.com/KingSora/OverlayScrollbars

---

更好的 i18n 支持

Warning

目前组件中的文案部分使用 texts props 进行传出，其实是一种相对临时和不可维护的方案，一个组件在多个地方使用，就需要多次传入 i18n 内容

解法：

考虑将文案表整合成一个 i18n 文件，通过 ConfigProvider 进行配置

---

单元测试/视觉回归测试

Warning

发生过几次因为接口改动导致的连锁问题，需补充更健全的单元测试

[arvinxx]

Brand 我在想是不是可以单独提出来。放在 UI 里好像没有太大必要？

[canisminor1990]

也不是不可以，我想组成像 vercel barnds 一样比较完备的 barnd 包： https://vercel.com/geist/brands

[canisminor1990]

或者可以和 @lobehub/icons 放一起

[arvinxx]

vercel 这个是一个叫 geist 的名字，然后 geist/brand 感觉挺正常的。但是 @lobehub/ui/brand 这个从属关系上看稍微有点怪。

[arvinxx]

可以新增一个 @lobehub/ui/next 来做 nextjs 组件的特殊适配。以及给一个 @lobehub/ui/rsc 可以后续放一些服务端组件

[canisminor1990]

next 适配目前感觉用 ConfigProvier as 更加灵活，只要吧 a / img / script 之类的组件的单独封装一下，就可以直接通过配置的方式进行适配

[arvinxx]

没有其他特殊组件吗？

[canisminor1990]

其他感觉暂时还没遇到过

[arvinxx]

哦想起来有的，https://github.com/lobehub/lobe-chat/blob/main/src/layout/GlobalProvider/StyleRegistry.tsx 这个是 next 专用的

[arvinxx]

组件 interface 规范感觉可以参考 antd 的接口设计规范：https://github.com/ant-design/ant-design/wiki/API-Naming-rules

[MapleEve]

i18n 这块按照目前我们线上项目踩的坑来看还是需要接入一个 saas 服务来保证 proof reading 和 votes，来解决 GPT 不准确的问题

下面有几个要考虑的点

1. 支持自动缩放字号来让控件适配，如果针对性市场覆盖面较广则需要重新设定栅格和控件大小
2. 做为开源项目，可以考虑申请 Crowdin 这类saas来做深度化的 i18n，并利用他的接口来直接进行版本管理
3. 如果对于实际产品的 UI 层面展示和交互需求，特别是针对性目标市场（比如优先简中、繁中、英语、法语、日语），应该优先考虑引导让对翻译不满意的用户（也就是所有潜在语种用户）参与到 i18n 的贡献中，并在合理的位置提供一个 i18n contribution list

[arvinxx]

其实 i18n 这块，从组件的角度不应该考虑 i18next ，直接采用纯文件导入的方案可能更合适，类似 antd 的实现: https://github.com/ant-design/ant-design/tree/master/components/locale

[canisminor1990]

可能写得不是很准确，我是想说复合 i18next 习惯的方式，不是直接引入 i18next

[arvinxx]

到时候自动提示这个可能会有点难，得看看怎么做类型自动推断。其他应该都是比较现成的方案

[arvinxx]

感觉有必要针对稳定性这块再加一条考虑因素： 单元测试/视觉回归测试

[yi-boide]

我目前有个项目中就使用了当前的UI的组件，遇到的问题就是设计师设计了一套样式，和这个有些出入的地方，需要进行修改，发现只能通过全局样式逐层查找的方式进行变更样式
类似如下：

.chat-item {
  padding-left: 0 !important;
  padding-right: 0 !important;
  & > div:first-child {
    top: -18px;
  }
  & > .layoutkit-flexbox .layoutkit-flexbox {
    &:first-child {
      font-size: 14px;
    }
    & + .layoutkit-flexbox > .layoutkit-flexbox {
      background: var(--ld-chat-item-bg-color);
    }
  }
}

.custom-chat > section > div > textarea,
.custom-chat > section > div + div {
  padding: 0;
}
.custom-chat-send > div:last-child button {
  padding: 0 44px;
}

这样处理起来确实很不方便，希望后续可以加入css样式变量进行控制，类似如下的效果,可以在外面更改--ld-chat-item-bg-color进行变更相关的样式，自身带有默认样式：

:root {
--ld-chat-item-bg-color: #ccc;
}
a {
 background: var(--ld-chat-item-bg-color, #fff)
}

[Lnncoco]

同样遇到这类问题, 由于没有给关键层定义有语义的名称, 导致覆盖css时得依赖上下层级, 或者用一个看起来不太稳定的随机名来重写 css

[arvinxx]

@canisminor1990 这个感觉需要在组件层面加上，添加语义化的槽位来提升的覆写便利性。chat 里偶尔也会遇到。

antd 会在 v6 里做完备的语义化 DOM 的能力，感觉 v2 也可以对应支持上