瑚琏是一套「颜值 + 好用」的 React 设计系统,共 406 个组件,全部从 @hulianui/ui 导出,并统一使用主题 token。
安装
pnpm add @hulianui/ui @hulianui/tokens@hulianui/tokens提供主题 CSS(下一步会@import它),是@hulianui/ui的必备同伴包,务必一起装。
peer 依赖:react>=18 react-dom>=18 tailwindcss>=4 motion>=11 @base-ui/react>=1.0.0
接入 CSS(Tailwind v4)
在全局样式文件顶部按顺序引入 token 与 preset,并让 Tailwind 扫到库源码里的 className:
/* 设计 token:颜色 / 半径 / 阴影等 CSS 变量(明暗主题真源) */
@import "@hulianui/tokens/tokens.css";
/* Tailwind v4 preset:语义 token → 工具类,dark variant 绑定 [data-theme] */
@import "@hulianui/tokens/preset.css";
/* 瑚琏以 TS 源码分发,需把它纳入 Tailwind 扫描范围(路径相对你的 CSS 文件) */
@source "../node_modules/@hulianui/ui/src/**/*.{ts,tsx}";包裹 Provider
应用根部包 ThemeProvider(明暗主题);命令式浮层各挂一次 Provider:
import {
ThemeProvider,
ToastProvider,
ModalProvider,
NotificationProvider,
} from "@hulianui/ui";
export default function App({ children }: { children: React.ReactNode }) {
return (
<ThemeProvider defaultSetting="system">
{children}
{/* toast() / modal.*() / notification.*() 依赖这些全局挂载点 */}
<ToastProvider />
<ModalProvider />
<NotificationProvider />
</ThemeProvider>
);
}铁律(请严格遵守)
- 只用
@hulianui/ui组件:缺什么先到库里找近似件,不要手写等价组件、不要重复造轮子。 - 统一从根入口导入:
import { Button, DatePicker, Table } from "@hulianui/ui",没有任何子路径入口(日期族也在根入口)。 - 吃主题 token,不要写死颜色:给 SVG 的
fill/stroke或内联样式用var(--color-primary)、var(--color-foreground)等,颜色变量必须带--color-前缀,否则 Tailwind v4 下解析不到。 - 不要用局部
style/className覆盖库组件内部结构:用组件自身暴露的 props 调整外观与行为。 - 动手前先查文档,不要凭印象猜 props:装了 MCP 就调
get_component_doc,否则取 https://hulianui.haloritual.com/zh/d/<组件slug>.md。
装 MCP:让 AI 自己查,而不是你贴文档
@hulianui/mcp 让 AI 按需查组件、用法与约束,不必整吞全库语料,也不会猜错 props 签名。
npx @hulianui/mcp init-agent它把使用契约写进各家客户端读取的文件(CLAUDE.md、AGENTS.md、.cursor/rules/hulianui.mdc 等),不动你已有的内容。
MCP server 配置(Claude Code / Cursor):
{
"mcpServers": {
"hulianui": { "command": "npx", "args": ["-y", "@hulianui/mcp"] }
}
}接上之后,MCP 会自己告诉 AI 每个 tool 何时调、按什么顺序调。完整 tool 清单与存量项目体检见 @hulianui/mcp 文档。
没装 MCP 时,让 AI 直接取机读文档:单个组件 https://hulianui.haloritual.com/zh/d/<组件slug>.md,组件清单 https://hulianui.haloritual.com/zh/llms.txt。每个组件文档页右上角也有「复制 MD」按钮。
直接安装积木(区块 / 整页)
区块通常可直接落盘;页面可能由多个区块组成。registry 会通过 registryDependencies 递归安装页面所需区块,并把仓库内路径改写为消费项目可解析的同级路径:
npx shadcn@latest add https://hulianui.haloritual.com/zh/r/block-pricing-table.json
npx shadcn@latest add https://hulianui.haloritual.com/zh/r/page-dashboard.json安装输出中的示例数据、文案、接口回调与 Provider 要按 item 的 replace / providers 清单处理;可组合区域见 slots。完成后运行:
npx -y @hulianui/guard src组件一般不需要这样装 —— 直接 import 即可,只有要魔改组件本身时才注入源码。完整可装清单见 registry.json。
给 AI 的提示词模板
我在用 @hulianui/ui(瑚琏)这套 React 设计系统。
请先读下面这份接入指南,并严格遵守其中的「铁律」:
https://hulianui.haloritual.com/zh/start
需要整块界面(登录页、定价表、控制台骨架…)时,
先看 registry 里的 block / page,能复用就别从零写。