用途:把现有 UI 组件库移植到 Marko 6,并打包成 shadcn 兼容的 marko-ui 注册表格式(含 Marko 源码的 JSON)。交互逻辑来自 Zag.js 状态机,样式保持 Tailwind。
流程要点:
- 先判断去向:拉取官方 wanted-libraries 列表,按名称(不区分大小写)匹配。若在 wanted 中,则 fork 官方 marko-ui 仓库、建分支,并优先遵循该仓库自身的编写文档(CLAUDE.md、notes/component-authoring.md、/docs/creating-components);组件放在 packages/shadcn/ui/<name>/ 并附 registry.meta.json,PR 需通过仓库的机械化一致性门槛。若不在 wanted 中,则克隆 marko-ui-registry-template,自建社区注册表,自行托管(含 GitHub Pages 工作流),并提交一行 PR 加入目录;不要向官方仓库提交未被需要组件的 PR。
- 清点源库:克隆并阅读真实代码,枚举组件,分为静态(纯标记+类名)、交互(在 zagjs.com 找对应机器,约 50 个可用)、无 Zag 对应(用 onMount 普通 DOM 实现或跳过并记录,不做半成品)。同时映射样式系统、整理共享工具(如 cn)。先写出组件→分类→Zag 机器→依赖的清点清单作为移植计划。
- 逐个移植:从最简单的开始,先读 marko6 技能掌握语言层规则,再写 .marko 文件。一致性要求:DOM 结构、类名字符串、data 属性、键盘/指针行为与源库相同。静态组件为单根元素、data-slot 标记、cn() 合并类名、展开 ...rest;交互组件用 marko-zag 的 <zag> 标签,细节见 references/marko-gotchas.md。一个组件一个目录,每个部件一个文件,有变体时加 variants.ts,并在 registry.json 或 registry.meta.json 注册,逐组件提交且每次可构建。
- 机械验证:用 marko-type-check 做类型检查(不要用 tsc),在生产构建上跑 SSR+水合渲染,在真实浏览器用真实指针事件驱动每个交互,并与源库在线文档截图比对;无法消除的偏差要记录。
- 发布:社区路径用 marko-ui registry build 构建、校验、部署后提交目录 PR;官方路径跑完整检查套件并附验证证据开 PR。
限制与原则:先读文件再移植,只移植实际挂载的代码;无法忠实移植的组件跳过并记录,不做近似或伪造;最终报告需如实列出偏差、跳过项和失败项。
原文提到需阅读 references/marko-gotchas.md、references/verification.md、references/registry-publishing.md、references/parity-process.md 等参考文件,但未提供其中内容;组件清单、支持平台、收费情况等事实暂未提供。