supervision-ui-sdk — 监管平台设计系统前端 SDK

监管平台（莫衡企信）设计系统的可分发前端 SDK：55 个 shadcn/ui + Tailwind v4 组件，带平台完整主题（品牌蓝 #0071e3、oklch 令牌、明暗双套），与 claude.ai/design 的「监管平台设计系统」项目（5f5c78a3-…）同源。

• 组件实现打包为浏览器全局 window.SupervisionUI（运行时共 300+ 导出：55 个主组件 + 全部子组件 + toast 等工具）。
• React 18 外部化：bundle 依赖 window.React / window.ReactDOM，由 dist/vendor/ 提供（也可换成你自己的 React 18/19 UMD）。
• 完整 TypeScript 声明见 types/（入口 types/index.d.ts）。
• 每个组件的中文文档见 docs/README.md。

目录结构

sdk/
├─ dist/
│  ├─ supervision-ui.js    # 组件 bundle（IIFE，挂 window.SupervisionUI，~2.4MB）
│  ├─ supervision-ui.css   # 主题令牌 + Tailwind 工具类（必须加载，无 JS ThemeProvider）
│  └─ vendor/
│     ├─ react.js          # React + ReactDOM 合并包（挂 window.React / window.ReactDOM）
│     └─ react-dom.js      # 占位（已合并进 react.js）
├─ types/                  # 完整 .d.ts 声明树（入口 index.d.ts，55 个具名导出）
├─ docs/                   # 组件文档（README.md 索引 + components/*.md ×55）
└─ package.json

安装

# 一键落地静态资源（无需先 npm install）：拷贝 dist 到 ./supervision-ui 并打印接入片段
npx supervision-ui-sdk init [目标目录]

# 或作为依赖安装（获得 types/ 类型提示与 docs/ 文档）
npm install supervision-ui-sdk

npm install 后资源位于 node_modules/supervision-ui-sdk/dist/，类型入口 node_modules/supervision-ui-sdk/types/index.d.ts；npx supervision-ui-sdk docs 可打印本地文档路径。

快速开始（script 标签）

加载顺序固定：先 React，再 bundle；CSS 必须引入。

<link rel="stylesheet" href="sdk/dist/supervision-ui.css" />
<script src="sdk/dist/vendor/react.js"></script>
<script src="sdk/dist/supervision-ui.js"></script>
<div id="root"></div>
<script>
  const { Button, Card, CardHeader, CardTitle, CardContent } = window.SupervisionUI;
  const e = React.createElement;
  ReactDOM.createRoot(document.getElementById('root')).render(
    e(Card, { className: 'w-80 m-8' },
      e(CardHeader, null, e(CardTitle, null, '你好')),
      e(CardContent, null, e(Button, null, '确定'))),
  );
</script>

已有 React 工程（Vite/webpack）：把 React 暴露到 window 后引入 bundle，即可从 window.SupervisionUI 解构使用；类型提示指向 types/index.d.ts。

主题与样式约定

样式完全由 CSS 变量驱动（supervision-ui.css），没有 React 主题 Provider。

• 暗色模式：给任意祖先加 dark 类（<div class="dark">…），全部令牌自动切换。
• 自定义布局用 Tailwind 工具类写在 className 上，只用语义令牌，不写裸 hex：

| 用途 | Tailwind 工具类 | CSS 变量 | |---|---|---| | 品牌主色（按钮/强调） | bg-primary text-primary-foreground ring-ring | --primary（= --brand #0071e3） | | 页面/卡片背景 | bg-background bg-card | --background --card | | 次级/弱化文字 | text-muted-foreground | --muted-foreground | | 次要底纹 | bg-secondary bg-muted bg-accent | --secondary --accent | | 边框/分隔 | border-border border-input | --border --input | | 危险/删除 | bg-destructive text-destructive | --destructive | | 弹层背景 | bg-popover | --popover | | 圆角 | rounded-md rounded-lg rounded-xl | --radius |

字体：正文使用系统中日文字体栈（PingFang / Microsoft YaHei 等，--font-sans），品牌标题字「阿里巴巴普惠体 3.0」未打包（按名引用、自动回退系统栈）。

需要包装器的组件

多数组件可独立渲染，以下例外（详见各自文档）：

• Tooltip → 子树需 TooltipProvider 包裹
• Sidebar 全家 → 需 SidebarProvider
• Toaster → 应用根部挂载一次，用 window.SupervisionUI.toast() 触发
• ChartContainer → 包裹 Recharts 图表，传 config，系列色引用 var(--color-<key>)
• 浮层类（Dialog/Sheet/Popover/Select…）自管 portal，组合 *Trigger + *Content 即可，无需 Provider

重新生成

SDK 由 ds-bundle 产物组装。组件源码（apps/web/src/components/ui/）变更后：

1. 按 .design-sync/NOTES.md 的构建配方重跑（pnpm build → CSS 剥字 → tsc 声明 → package-build.mjs）；
2. 重跑组装脚本重新生成 sdk/（dist 拷贝 + types 树 + 55 篇文档均为脚本产物，勿手改）。