wecom-ui-shadcn 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frizenchow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# wecom-ui-shadcn
+
+> 企业微信 UI 组件库 — shadcn 范式、Tailwind + Radix Primitives、token 全部来自 `@wecom-design/tokens`。
+> 覆盖 design system / desktop / mobile（后续）三层。
+
+## 背景
+
+我们想做的事：**让 AI agent（Claude Code / Cursor 等）直接生成可投放的企业微信 UI 原型**。
+那就需要一套 AI 友好的组件库——shadcn 命名让 LLM 不必查文档，prop 语义贴合企业微信设计语言，每个组件都有"对照 Figma 还原过"的可信度。
+
+设计稿源：Figma `Desktop Library` `0zsTetwqRuSKJRsyJJXcjg`，通过 Figma Dev Mode MCP 拉规格。
+官方组件库 `@wecom-design/desktop` 是参考来源，但本仓库**完全独立重写**，只复用其 Token 包。
+
+## 现状
+
+- ✅ 设计 token 接入（`@wecom-design/tokens@1.0.4`，本地 patch 把 `_` 统一为 `-`，详见 `docs/TOKEN_PATCH.md`）
+- ✅ Phase 3a 进行中（shadcn 范畴的 ~25 个原子/分子组件）
+  - 已完成：Button / Checkbox / Radio / Switch / Badge / Hyperlink / Separator / Toggle / SplitButton / Input / Textarea / Menu(Dropdown + Context) / Sidebar (Item + Group + Label)
+  - 进行中：剩余原子组件
+- ⏭️ Phase 3b：壳层与复合组件（TitleBar / TopNav / ListView 族 / Table 族 …）
+- ⏭️ Phase 3c：WeCom 专有组件（Basement / BusinessDialog / TreeView …）
+- ⏭️ Mobile 组件库（待启动）
+- ⏭️ 主页（Home / Docs / Components）— 暂缓
+
+## 快速开始
+
+### 当作 npm 包消费（推荐）
+
+```bash
+pnpm add wecom-ui-shadcn
+# react / react-dom 是 peerDep，要保证 >=18
+```
+
+```tsx
+// 1. 在你应用入口（main.tsx）一次性引入样式
+import 'wecom-ui-shadcn/styles.css'
+
+// 2. 任何组件里直接用
+import { Button, Checkbox, DropdownMenu } from 'wecom-ui-shadcn'
+
+export function App() {
+  return <Button color="blue">Hello</Button>
+}
+```
+
+如果使用 Tailwind CSS（推荐），把组件库的 preset 加进 config 以清空默认 palette/spacing 强制只用 token：
+
+```ts
+// tailwind.config.ts
+import wecomPreset from 'wecom-ui-shadcn/tailwind.preset'
+
+export default {
+  presets: [wecomPreset],
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/wecom-ui-shadcn/dist/**/*.{js,mjs}',
+  ],
+}
+```
+
+### 在仓库里本地开发（审查页）
+
+```bash
+git clone <repo-url> wecom-ui-shadcn
+cd wecom-ui-shadcn
+pnpm install
+pnpm dev
+# 浏览器 http://localhost:5173，可看到 14 个组件的审查页
+```
+
+`pnpm typecheck` 跑 TS 编译检查；`pnpm build` 用 tsup 打包。
+
+## 项目结构
+
+```
+wecom-ui-shadcn/
+├── src/
+│   ├── components/          # 每个组件一个目录（Button/、Checkbox/ ...）
+│   ├── lib/cn.ts            # clsx + tailwind-merge 的统一封装
+│   ├── styles.css           # 入口样式：导入上游 token + 老命名 alias
+│   └── index.ts             # 唯一对外出口
+├── dev/                     # 组件审查页（Vite SPA）
+│   ├── index.html
+│   ├── main.tsx
+│   └── pages/
+│       ├── App.tsx          # 顶部导航 + hash 路由
+│       ├── Home.tsx
+│       └── *Review.tsx      # 每个组件一个审查页
+├── docs/
+│   └── TOKEN_PATCH.md       # 历史：1.0.4 时本地 patch 的说明（1.0.5 起已不需要）
+├── tailwind.preset.ts       # 把 --wc-* 变量暴露到 Tailwind theme
+├── tailwind.config.ts
+├── tsup.config.ts
+├── vite.config.ts
+├── LICENSE
+└── package.json
+```
+
+## 添加 / 扩充组件的标准流程
+
+> 这一节既给 **AI agent** 也给 **人类协作者** 看。Claude Code / Cursor 在新增组件时按这个流程做。
+
+每加一个组件经过以下 5 步——**不要跳步、不要凭印象写**。
+
+### 1. 在 Figma 找到设计源
+
+进入 Desktop Library，找到目标组件（例如 `Tag`）。**记下 node-id**（如 `9098:36022`），后面要用它拉规格。
+如果用 Figma Dev Mode MCP，`get_metadata` 返回组件 frame 下所有 variant 的 node-id 列表，每个 variant 都需要拉。
+
+### 2. 拉真规格——不要靠肉眼/印象/猜
+
+对每个 variant 用 `mcp__figma-dev-mode__get_design_context` 拿真规格。
+**SVG 切片组件**（Switch、Checkbox、Radio、Sidebar 等）必须 `curl http://localhost:3845/assets/<HASH>.svg` 看真路径——颜色、几何都从 SVG 反推，**不要从 `get_variable_defs` 猜值**。
+
+跨 variant 的规格（width / height / padding / radius / 字号）要列对照表，确认所有 variant 的几何**完全一致**。如果不一致，用"透明 1px border 基线"对齐：基础 class 加 `border border-solid border-transparent`，有边框的 variant 只覆写 `border-color`，避免 1px 偏移。
+
+### 3. 实现组件
+
+每个组件目录的标准结构：
+
+```
+src/components/Foo/
+├── Foo.tsx              # 主体：cva variants + 视觉 + Radix Primitive（如有）
+├── colors.ts            # 跨 variant 的色值表（cva 的 color 变体）
+└── index.ts             # 出口
+```
+
+实现要点：
+
+- **样式只能用 `--wc-*` token**：`bg-[var(--wc-base-gray-005,rgba(6,15,26,0.05))]`，**不要硬编码** `#xxx`/`bg-gray-100`/`p-4`（非 token 数值）。
+- **shadcn 有的组件用 shadcn 名**（Button / Badge / Toggle / DropdownMenu …）。shadcn 没有的用 WeCom 设计名（Hyperlink / SplitButton / SidebarMenuItem …）。详见"命名约定"。
+- **prop 语义跟 WeCom 设计稿对齐**：`color="gold" | "blue" | ...`，不强行映射成 shadcn 的 `variant="default | destructive"`。LLM 读 TS 类型就能正确生成。
+- **状态由 CSS 接管**：Hover / Pressed / Disabled / Focus 用 `:hover`、`:active`、`:disabled`、`aria-invalid`、Radix `data-state`，**不要把这些做成 prop**。
+- **行为由 Radix 接管**：DropdownMenu 用 `@radix-ui/react-dropdown-menu`，Switch 用 `@radix-ui/react-switch`，Toggle 用 `@radix-ui/react-toggle`，等等。可访问性、键盘导航、focus management 全部白嫖。
+- **cva 写 variants**：用 `class-variance-authority` 让 size / color / theme 等组合明确。共用基线（无变体的样式）放数组首项。
+- **`cn()` 合并类名**：`import { cn } from '@/lib/cn'`，从不直接 `className={a + ' ' + b}`。
+
+### 4. 写审查页
+
+`dev/pages/<Foo>Review.tsx`，每个组件**全量遍历变体矩阵**——每个 size × color × layout × state（Normal / Hover / Pressed / Disabled / Selected …）都画出来。
+hover / pressed 由真实鼠标实测。selected / disabled 由 prop 模拟。
+然后在 `dev/pages/App.tsx` 的 `ROUTES` 里挂上一条 `'foo': { title: 'Foo', el: <FooReview /> }`。
+
+审查页要做到：**和 Figma 截图并排放，几何（width/height/padding/radius/字号/字重）完全对得上**。这是验收红线。
+
+### 5. typecheck
+
+```bash
+pnpm typecheck
+```
+
+过了再喊 review。
+
+### 完成后还要做的：
+
+- 在 `src/index.ts` 把组件导出
+- 如果该组件强依赖某个 Radix primitive，记得 `pnpm add @radix-ui/react-xxx`
+
+## 命名约定
+
+详细见 `../wecom-docs-design/docs/AI_PROMPTING.md`，核心规则：
+
+1. **shadcn 标准优先**：shadcn 有同义组件 → 用 shadcn 名（Button / Badge / Toggle / Switch / Checkbox / DropdownMenu / Separator …）
+2. **shadcn 没有的组件用 WeCom 命名**：Hyperlink / SplitButton / MiniProgramBar / Basement 系列等
+
+## Token 约束
+
+所有样式**只能来自** `@wecom-design/tokens`（CSS 变量 `--wc-*`），**禁止硬编码**颜色 / 间距 / 圆角 / 字号 / 阴影。
+
+```tsx
+// ✅ 用 CSS 变量
+<div className="bg-[var(--wc-base-gray-005,rgba(6,15,26,0.05))]">...</div>
+
+// ❌ 硬编码
+<div className="bg-[#f5f5f5]">...</div>
+<div className="bg-gray-100">...</div>  // tailwind 默认调色板已被 preset 清空
+```
+
+如必须硬编码（Figma 临时数值还没补 token）→ 加注释 `// @non-token: <理由>` 标记，等 audit 脚本扫到再补。
+
+## 协作约束（Karpathy Guidelines）
+
+四条规则——AI 也要遵守：
+
+1. **Think Before Coding** — 明确假设、不静默选择、不确定就问
+2. **Simplicity First** — 只写解决问题的最少代码，不预先抽象、不做没要求的"灵活性"
+3. **Surgical Changes** — 只改必要的部分，不顺手"优化"相邻代码
+4. **Goal-Driven Execution** — 定义可验证的成功标准（审查页对得上 Figma、typecheck 过）
+
+## 相关链接
+
+- Figma 设计稿：`https://www.figma.com/design/0zsTetwqRuSKJRsyJJXcjg/`
+- 上游 token 包：`@wecom-design/tokens`（公共 npm，58KB 纯 CSS 变量）
+- 同级原型仓库：`../wecom-docs-design`（最终消费方，本组件库的演练场）
+- shadcn/ui：`https://ui.shadcn.com/`（命名 / API 设计参考）
+
+## 给 AI Agent 的快速指令
+
+如果你是 Claude Code / Cursor 等 agent，被要求"加一个 X 组件"或"扩充 Y 组件"，照下面顺序操作：
+
+1. 读完本 README 的 **「添加 / 扩充组件的标准流程」** 5 步
+2. 用 Figma MCP 拉 X / Y 的所有 variant 规格（**不要靠记忆/印象**）
+3. 实现 → 审查页 → typecheck → 喊 review
+4. 任何一步遇到 ambiguity（命名、prop 设计、token 缺失），**停下来问用户**——不要自己拍板
+
+## License
+
+Internal — 暂未对外发布。