design-prototype

设计原型

一个 HTML 文件，双击即可打开，完全可交互，由实际设计系统（@lobehub/ui 6.x 组件、编译后的 style.css、--lobe-* 主题令牌——版本与本仓库 node_modules 中的版本完全一致）渲染；同时，源码保持面向生产环境的 React 风格（import { Block } from '@lobehub/ui'、createStaticStyles(({ css, cssVar }) => …)、hooks、memo）。推广到生产环境时，主要是“拆分成多个文件”，而不是“重写”。

原型代码可以快速拼凑（一个文件、没有国际化、数据内联），但交互必须完整：状态、转换和操作提示才是原型的重点，而不是代码风格。

工作原理

one-time (~2s, cached):   scripts/build-runtime.sh  →  lobe-prototype-runtime.js (IIFE global)
                                                       + lobe-prototype-runtime.css
                                                       + vendored babel.min.js
per prototype (no build): single HTML  =  <link css> + <script runtime> + babel-standalone
                          + <script type="text/babel"> with production-style React

• 运行时从本仓库自己的 node_modules 打包 react、react-dom/client、完整的 @lobehub/ui 命名空间、lucide-react 和 motion，因此令牌、组件和版本都与生产环境一致，并通过构建方式确保 react/emotion/theme-scope 是单例。
• entry.mjs 还会导入 @lobehub/ui/theme.css、global.css 和 style.css（与应用在 src/layout/GlobalProvider/AppTheme.tsx 中加载的三个文件相同）；esbuild 会将它们输出为 lobe-prototype-runtime.css，并由模板的 <head> 引入。
• 通过 3 行的 window.require 垫片和 babel 的 transform-modules-commonjs，原型可以保留真实的 import 语句。
• 主题通过 CSS 属性设置，而不是使用 provider：模板的 head 脚本会根据 prefers-color-scheme（及其变化）调用 setLobeTheme({ appearance })，因此首次绘制前，浅色/深色主题就会跟随操作系统。使用 setLobeTheme({ appearance: 'dark' }) 强制指定主题，或使用 <ThemeScope appearance="dark"> 创建独立区域。React 树会像应用的 AppTheme 一样包裹在 <ConfigProvider motion={motion}> 中（为 Button、Drawer、Modal 等提供动效，以及字体、焦点环和弹出层 portal 容器），并使用 <ToastHost /> 提供 toast。

⚠️ 不要再尝试纯 CDN 方案（esm.sh 导入映射）。该方案已试用并被否决：esm.sh 对依赖链中的 CJS 命名导出分析接连失败，而 ?bundle 引入的未指定版本 react-is 返回 404。从本仓库自己的 node_modules 打包，是唯一能与生产环境版本完全一致的方式。

快速开始

1. 将运行时构建到原型所在目录（任何目录均可；/tmp 也可以）：

   bash .agents/skills/design-prototype/scripts/build-runtime.sh /tmp/my-proto
   

   如果目录中已有 lobe-prototype-runtime.{js,css} 和 babel.min.js，且设计系统版本未升级，则可跳过。首次运行会从 unpkg 下载固定版本的 babel.min.js；后续运行会复用该文件。

2. 将 references/template.html 复制到同一目录，重命名，并将示例 App 替换为实际界面。不要改动运行时垫片代码块。

3. 打开文件（open /tmp/my-proto/xxx.html）——无需服务器或构建。

交付前验证

使用无头模式检查页面能否渲染且没有控制台错误（本仓库的 e2e 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();

然后查看截图——原型是视觉交付物；不要未经检查就交付。检查浅色和深色主题（模拟 prefers-color-scheme），如果界面需要适配移动端，也要检查窄视口。

运行时包含的内容（可自由扩展）

请参阅 assets/entry.mjs——它是唯一可信来源。目前包含：

• @lobehub/ui：完整命名空间——所有组件（Button、Input、Modal、 createModal、confirmModal、Table、Switch、Checkbox、Radio、Badge、 Progress、Slider、Steps、Divider、DropdownMenu、Accordion、Collapsible、 Spin、Skeleton、DraggablePanel、FloatingSheet、……），以及 toast / ToastHost、 MotionProvider、setLobeTheme、ThemeScope、useThemeMode、useTheme，还有样式 API createStaticStyles、cssVar、cx、css、keyframes、responsive、 useResponsive
• @lobehub/icons：Amp、ClaudeCode、Codex、HermesAgent、OpenClaw、OpenCode
• lucide-react、motion/react、motion/react-m、react、react/jsx-runtime、 react-dom、react-dom/client：完整命名空间

不包含：@lobehub/ui/form、@lobehub/ui/pro-table、@lobehub/ui/chat 和其他子路径——添加 import * as x from '@lobehub/ui/<sub>' + 一个 '@lobehub/ui/<sub>': x 条目，然后重新构建（约 2 秒）。体积约为 17MB JS + 0.3MB CSS（从磁盘加载没问题）。

选择 v6 对应项

• 反馈：toast.success(…) + <ToastHost />；对话框：Modal、createModal、 confirmModal。
• 菜单：DropdownMenu items={…}（点击时打开）；上下文菜单：ContextMenuTrigger。
• 布局：Flexbox horizontal gap={…} / Center / Grid——没有 Space。
• 折叠内容：多个区块使用 Accordion，单个区域使用 Collapsible。
• Badge、Checkbox、Divider、Progress、Radio、Slider、Steps、Switch、 Table（columns / dataSource / rowSelection）均为根导出项。
• 不确定名称时 → 查看 node_modules/@lobehub/ui/es/index.d.mts，不要猜测；未知导入在运行时会是 undefined，而不是构建错误。

注意事项

• 样式请严格按照生产环境的做法，使用 createStaticStyles + cssVar.*——它基于 emotion，并在调用时插入样式，因此不需要构建步骤。令牌会解析为 var(--lobe-*) 并随主题切换；切勿硬编码浅色/深色颜色。
• 组件样式位于级联层（lobe-base、lobe-popup、lobe-ui），因此原型 <style> 中任何未分层的 CSS 都会覆盖它们。通过 className / style / classNames / styles 插槽属性进行覆盖，不要使用 button { … } 之类的全局选择器。
• 保留指向 lobe-prototype-runtime.css 的 <link>——没有它，组件将不会应用样式，且 --lobe-* 令牌未定义。
• babel 必须保持为原始 UMD 文件（unpkg/jsdelivr）。esm.sh 会将其重写为 ESM，经典的 <script src> 遇到 export 时会报错。
• require 垫片会在导入内容不在运行时中时抛出异常，并显示模块名称——这表示需要“添加到 entry.mjs 并重新构建”，不是模板错误。
• Text type 仅接受 secondary|success|warning|danger|info；Tag color 不支持 primary（参见 DESIGN.md“在组件中应用令牌”）。

设计标准（与生产界面相同）

原型就是一个界面——ux 清单适用于它所_展示_的内容：

• 展示至少一种非理想路径状态（空 / 加载中 / 错误 / 进行中），最好像模板那样通过状态切换条展示。只展示理想路径的原型无法充分说明设计，并会在无形中默认缺失状态是合理的。
• 复用应用的界面契约：侧边面板使用 DraggablePanel（自带折叠和拖动调整大小功能）；加载状态遵循 ux 技能反馈 §4.1 的场景表（Skeleton / Spin，只有 AI 工作才使用 variant="network"）；模态框使用 createModal 风格的流程。
• 不要展示没有接入功能的交互提示（例如没有缩放功能却设置 cursor: zoom-in，或没有对应按键却显示键帽标签）——在_交互式_原型中，失效的交互提示属于规格错误。
• 交付前，按照 ux 快速审查清单检查原型；任何有意不在范围内的内容，都应在 HTML 注释中注明，让实现者知道这是删减项，而非设计决定。