LobeHub 设计原型技能用真实设计系统构建单文件交互式 HTML 原型的完整实践【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub本文基于 LobeHub 仓库中的design-prototype技能文档讲解如何在零构建步骤的前提下生成一个双击即可在浏览器打开、完全可交互的单文件 HTML 设计原型。该原型并非静态切图而是由 LobeHub 生产环境同款设计系统lobehub/ui5.x antd 6 antd-styletoken版本直接取自本仓库node_modules渲染源码保持生产级 React 写法。读完本文你将掌握一次性构建原型运行时的完整流程、requireshim babel 在线编译的底层机制、交付前的 Playwright 无头校验方法以及仓库总结出的若干高价值陷阱清单。一、核心思想原型代码可以粗糙交互必须完整design-prototype技能定义在 SKILL.md 中其定位在文档开头就写得很明确交付物是一个 HTML 文件双击打开、完全可交互由真实的设计系统渲染——lobehub/ui5.x antd 6 antd-styletokens版本号与本仓库node_modules中完全一致当前仓库package.json锁定为lobehub/ui^5.38.0、antd6.3.5、antd-style4.1.0、react19.2.7源码保持生产风格 Reactimport { Block } from lobehub/ui、createStyles(({ css, token }) …)、hooks、memo全部照常写。因此把原型转正进生产代码主要是**拆分成多个文件而不是重写**对原型代码质量有明确的豁免边界单文件、无 i18n、内联数据都可以接受quick-and-dirty但交互必须完整——状态states、过渡transitions、可供性affordances才是原型的意义所在而不是代码风格。二、工作原理一次性打包运行时 每个原型零构建技能文档给出的工作流如下one-time (~2s, cached): scripts/build-runtime.sh → lobe-prototype-runtime.js (IIFE global) vendored babel.min.js per prototype (no build): single HTML script runtime babel-standalone script typetext/babel with production-style React分两层理解2.1 一次性构建从本仓库 node_modules 打包出 IIFE 全局命名空间构建脚本 build-runtime.sh 做了三件事定位 esbuild不额外安装依赖而是从 pnpm store 里挑一份 esbuild 二进制esbuild 是 vite 的传递依赖ESBUILD$(ls -d $REPO_ROOT/node_modules/.pnpm/esbuild*/node_modules/esbuild/bin/esbuild | sort -V | tail -1)用 esbuild 把运行时入口打包为 IIFE全局名为__PROTO_DEPS_NS__并针对浏览器场景做了若干关键配置$ESBUILD $SKILL_DIR/assets/entry.mjs \ --bundle --formatiife --global-name__PROTO_DEPS_NS__ \ --platformbrowser --define:process.env.NODE_ENVproduction --minify \ --loader:.cssempty --loader:.woffdataurl --loader:.woff2dataurl \ --loader:.svgdataurl --loader:.pngdataurl \ --outfile$OUT_DIR/lobe-prototype-runtime.js其中--formatiife--global-name决定了运行时挂载到window.__PROTO_DEPS_NS__上--loader:.cssempty把样式文件置空原型阶段不关心 CSS 产物字体与图片则内联为 dataurl保证产物自包含。vendor 一份 babel-standalonepin 在7.26.4从 unpkg 下载用于浏览器端编译 JSX/CommonJS 语法。文件已存在且非空时跳过下载实现~2s、可缓存的一次性成本。打包入口 entry.mjs 是运行时的唯一事实来源single source of truth。它把原型可用的所有模块 import 后以模块名 → 命名空间的对象形式导出export default { lobehub/ui: { ActionIcon, Alert, Avatar, Block, Button, Center, Collapse, ConfigProvider, DraggablePanel, Drawer, DropdownMenu, Empty, Flexbox, Highlighter, Hotkey, Icon, Image, Input, InputNumber, Markdown, Modal, MotionProvider, NeuralNetworkLoading, Popover, ScrollShadow, SearchBar, Segmented, Select, Skeleton, SortableList, Tabs, Tag, Text, TextArea, ThemeProvider, Tooltip }, lobehub/icons: { Amp, ClaudeCode, Codex, HermesAgent, OpenClaw, OpenCode }, lobehub/ui/base-ui: baseUI, // 全量命名空间 antd: { App, Badge, Checkbox, Divider, Dropdown, Progress, Radio, Slider, Space, Steps, Table }, antd-style: antdStyle, // 全量命名空间 lucide-react: lucide, // 全量命名空间 motion/react: motionReact, motion/react-m: motionReactM, react: react, react-dom: reactDom, react-dom/client: reactDomClient, react/jsx-runtime: jsxRuntime, };与 SKILL.md 正文所列清单相比entry.mjs实际还包含lobehub/icons、ConfigProvider、MotionProvider、motion/react与react/jsx-runtime等条目——以entry.mjs为准。缺组件时的处理方式是文档明确给出的加到entry.mjs重跑构建脚本~2s。文档同时给出体积参考当前精选集curated subset约 16MB从磁盘加载完全无压力如果不想维护精选名单export * from lobehub/ui全量导出也可行约 27MB。产物lobe-prototype-runtime.js与babel.min.js均被 assets/.gitignore 忽略不进入版本库。这套方案的关键收益在文档中点明因为 react、emotion、theme-context 都来自同一次 bundle它们在构造上就是单例——不会出现两份 React 实例或主题上下文不共享这类 CDN 拼凑方案的经典问题。2.2 每个原型require shim babel-standalone 的无构建执行模板文件 template.html 展示了生产风格 import 如何在不经过构建工具的情况下跑起来。其核心是一段 3 行的window.requireshimscript src./lobe-prototype-runtime.js/script script // Map bare module specifiers onto the bundled namespaces, so the code below // keeps production-style import { X } from lobehub/ui. window.require (name) { const m __PROTO_DEPS_NS__.default[name]; if (!m) throw new Error( prototype runtime is missing module: name — add it to entry.mjs and rebuild, ); return m; }; window.exports {}; window.module { exports: window.exports }; /script script src./babel.min.js/script页面随后通过script typetext/babel>bash .agents/skills/design-prototype/scripts/build-runtime.sh /tmp/my-proto若目标目录中已存在lobe-prototype-runtime.js与babel.min.js且设计系统版本未升级可跳过此步。第 2 步复制模板并替换示例 App把 references/template.html 复制到与运行时相同的目录重命名然后把示例App换成真实的界面surface。文档特别强调runtime shim 代码块保持原样不动。模板中的示例App本身就示范了文档要求的设计底线——用一条状态切换条state-toggle strip演示四种状态const [state, setState] useState(data); // … Flexbox horizontal gap{8} {[data, empty, loading, error].map((s) ( Button key{s} sizesmall type{state s ? primary : default} onClick{() setState(s)} {s} /Button ))} /Flexbox Center flex{1} {state data TextReplace me with the real surface./Text} {state empty Empty descriptionNothing here yet /} {state loading ( Text typesecondaryskeleton / NeuralNetworkLoading here…/Text )} {state error ( Flexbox aligncenter gap{8} Text typedangerFailed to load./Text Button sizesmallRetry/Button /Flexbox )} /Center页面骨架上还有两个细节值得注意#boot节点是加载占位符原型代码执行成功后自行document.querySelector(#boot).remove()样式统一走createStyles并直接引用 token如token.colorBgLayout与生产代码一致。第 3 步直接打开open /tmp/my-proto/xxx.html无服务器、无构建。这也是单文件原型的终极验收标准文件协议file://下即可运行这也是为什么字体/图片在 bundle 时必须内联为 dataurl、babel 必须保留原始 UMD 版本见下文陷阱清单。四、交付前校验无头浏览器检查 亲眼看截图文档把交付前校验提升为一个独立强制环节理由很直接原型是视觉交付物不能盲发dont ship it sight-unseen。校验方法使用本仓库 e2e 工程自带的 Playwrighte2e/package.json 中即依赖 playwright一个极简检查脚本如下// node /tmp/check.mjs — adjust paths import { chromium } from repo/e2e/node_modules/playwright/index.mjs; const b await chromium.launch(); const p await b.newPage(); const errs []; p.on(pageerror, (e) errs.push(String(e))); await p.goto(file:///tmp/my-proto/xxx.html); await p.waitForSelector(#root *, { timeout: 30000 }); await p.screenshot({ path: /tmp/proto.png }); // Read the screenshot yourself console.log(errors:, errs); await b.close();验收清单包含三条零 console 错误pageerror事件捕获到的数组必须为空亲自查看截图脚本注释里的 Read the screenshot yourself 是原话——截图必须被审阅者看过双主题 窄视口检查 light 与 dark 两种外观通过 emulateprefers-color-scheme若该界面存在移动端形态再补一次窄视口检查。五、陷阱清单文档总结的五条硬约束SKILL.md 的 Pitfalls 一节浓缩了真实踩坑经验每一条都有对应的机制解释陷阱说明与机制Switch在lobehub/ui/base-ui不在根包base-ui 的其他基础原语同样如此从根包 import 会导致运行时构建失败。entry.mjs中import * as baseUI from lobehub/ui/base-ui即为此单独成行用createStyles不要用createStaticStyles静态样式抽取依赖构建步骤原型场景没有构建步骤。这是文档声明的唯一被批准的偏离生产写法的做法交给实现者时必须注明babel 必须是原始 UMD 文件unpkg/jsdelivr 来源esm.sh 会把它改写为 ESM而经典script src遇到export语法会直接报错require shim 抛错带模块名当某个 import 不在运行时里时shim 抛出prototype runtime is missing module: xxx — add it to entry.mjs and rebuild。这是加到 entry.mjs 并重新构建的信号不是模板 bugtoken 简写有严格取值范围Text type只接受secondary \| success \| warning \| danger \| infoTag color没有primary。这一点在 DESIGN.md 的 Applying tokens in components 一节有完整展开非法 prop 值是静默失败渲染成字面色或被忽略而非报错因此需要用color{cssVar.colorTextTertiary}之类方式直接设 token其中第五条与 DESIGN.md 的 token 规范形成了闭环原型既然使用生产同款组件与 token就天然继承生产的取值约束这也是原型与生产同源方案的另一层价值。六、设计标准原型与生产界面执行同一把尺子文档最后一节 Design bar 明确原型就是一个 surface界面因此 ux 技能 的检查清单同样适用于原型所演示的内容。具体约束如下必须展示至少一个非 happy-path 状态empty / loading / error / in-progress理想情况下放在一条状态切换条后面模板即此做法。只做 happy path 的原型是对设计的欠规格化等于默认放过了缺失的状态复用应用的 surface contracts侧边栏面板用DraggablePanel折叠 拖拽调宽是现成的加载态用 skeleton 或NeuralNetworkLoading永不使用 antd 的Spin模态流程走createModal风格不要画你没有接线的可供性cursor: zoom-in但点了没有缩放、keycap 快捷键样式但根本没有绑定按键——在交互式原型中死掉的可供性就是规格 bug交付前对照 ux Quick review 走一遍原型对刻意不做的部分用 HTML 注释注明这是裁剪cut而非决策decision让接手实现的人清楚边界。七、边界与适用前提适用前提需要在仓库根目录运行构建脚本依赖本仓库已安装好的node_modulespnpm store 中的 esbuild、lobehub/ui、antd等以及构建一次时对外网下载 babel.min.js 的一次性访问原型运行本身离线可用版本耦合运行时与node_modules同版本是刻意设计。设计系统升级如lobehub/ui大版本变化后应重新执行构建脚本产物本身不入库已被.gitignore忽略定位边界该技能服务的是实现前探索设计explore a redesign before committing to implementation阶段——产出的单文件原型用于评审与交互验证正式落地时按拆文件、接 i18n、按生产样式规范必要时把createStyles换回createStaticStyles的路径推进而不是直接把原型文件塞进应用。小结LobeHub 的design-prototype技能给出了一条可复用的高保真原型路线用一次 ~2 秒的 esbuild 打包把生产版本的设计系统固化成 IIFE 运行时用requireshim babel-standalone 让原型代码保持生产级 React 写法用 Playwright 无头检查 人工看截图作为交付闸门并用一份陷阱清单和 ux 检查标准把原型质量约束在和生产界面同一水平。整个技能的全部实现仅由四个文件支撑——SKILL.md流程与规则、build-runtime.sh构建、entry.mjs运行时清单、template.html模板是以最小工具链换取最大保真度的典型案例。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
