KotodamaJournal
工程札记心情 · 收束Blueprint

我为什么自研一套 React + Lego 组件库

成品 UI 库很好用，直到你同时要搭运营后台和品牌营销站。一套蓝白中后台气质绑死视觉，定制贵；PC / 移动又常被迫拆成两套库；底层还绑着长长的 rc-* 链——修一个定位 bug，人已经跨了三层仓库。

Kotodama 要的不是「antd 子集」，而是：可扩展积木 + 多场景皮肤，并且工程上绝不干扰现网 platform/ / landing/。于是有了独立子项目 design-system/，包名 @kotodama/lego-react，文档挂在 /ui/。

更完整的架构说明在组件文档站：我如何规划与落地组件库。下面用札记体把「为什么 → 怎么规划 → 怎么选 → 怎么写」串一遍。

要解决什么问题

对照开源大库的常见短板，我给自己定了几条硬约束：

痛点 对本库的含义
设计语言刚性 必须同时服务后台与品牌站，视觉不能绑死一套蓝白气质
CSS-in-JS / 重组件性能税 样式自控：CSS Variables + 稳定 kd-* 类名
rc-component 跨仓深 禁止 rc-* / @rc-component/* / antd 作底层
antd vs antd-mobile 割裂 一套组件 + 自适应，不做第二套 mobile-only 库
对 AI / 低代码不友好 组件要可描述；远期产出 LLM 可读契约

一句话：积木优先，而不是复制全家桶。

怎么规划

需求里把场景拆成四块：企业后台、品牌营销站、品牌内容站、同一套组件的移动端自适应。工程上再加一条：独立子项目——目录、依赖、构建、运行时与产品主路径隔离；接点只有 Header 外链和网关静态挂 /ui/。

分期大致是：

  1. S0：骨架、Token、门禁、Button/Input/Layout、Rspress
  2. S1：Form / Table / Nav / Feedback + 后台 Demo
  3. S2：Hero / Section / CTA 等 blocks + 营销 Demo + 响应式
  4. S3：元数据 → LLM 文件、SSR 纪律加固
  5. 之后：跨平台生成、Agent recipes（明确本期不做）

场景分层写进架构原则，依赖单向向下：

primitives（基础）→ patterns（后台模式）→ blocks（营销区块）

扩展靠 wrappers / 组合，不靠无限加 props。这和 Lego Modules 的写法是对齐的。

技术如何选型

定案很短，执行却要守住：

项 定案
框架 React 18+
编写规范 Lego Modules（state / listeners / render / wrappers…）
底层交互 自研或白名单，零 rc-component
样式 CSS Variables + 静态 CSS；主题用 data-theme
文档站 Rspress → /ui/（Storybook 可选，不替代对外站）
工程 design-system/ 独立 pnpm workspace

主题不是「再做一个 dark 开关」那么简单：admin 是中性后台亮色；brand 是营销气质（默认亮色面、深字；暗色宿主走 brand 暗色面，保留暖金，而不是被吞成 admin dark）。文档站 Demo 用 DocsDemoProvider 跟随 Rspress 明暗——亮暗切换要对营销示例同样有意义，这是后来踩对比度坑之后收紧的纪律。

代码如何落地

仓库里看得见的形态：

design-system/
  packages/tokens/     # Design Token
  packages/react/      # @kotodama/lego-react
  apps/docs/           # Rspress → /ui/
  scripts/check-no-rc.mjs

落地时几件「看起来像工程琐事、其实是产品边界」的事：

  • Lego：核心路径（Button、Input、Form、Hero…）用 createComponent；对外仍是普通 React 组件 + ConfigProvider。换皮走 createButtonWithWrappers / createHeroWithWrappers，文档里有可跑示例。
  • 门禁：pnpm check:no-rc + CI；类型检查、构建、测试、元数据覆盖率同一条流水线。
  • 按需：分层入口 primitives / patterns / blocks + 分层 CSS，营销页不必打入 Table。
  • AI 就绪：componentMetaList 构建导出 JSON/YAML，覆盖率门禁锁住回退。
  • 验收 Demo：后台 CRUD 雏形页 + 品牌/营销落地页，同一套 Button/Input，两套主题气质不同、API 一致。

还没做、也不假装做了的

本期明确不做：基于 antd/rc 封装、大而全复制、原生 App 运行时、完整低代码编辑器产品、与 antd API 兼容承诺。P2 的虚拟表格、动效体系、跨平台 PoC、Agent recipes 留在路线图上。

去哪儿看

组件库不是为了「多一个 npm 包」。它是为了让后台效率、品牌表达、移动自适应，以及将来的 AI 装配，共用一份契约、多种皮肤——并且从第一天起就不踩现网的脚。

ON THIS PAGE