ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Open CoDesign 空状态设计规范:用 empty-states 技能让 AI 生成告别 “No data“ 占位符

Open CoDesign 空状态设计规范:用 empty-states 技能让 AI 生成告别 “No data“ 占位符 人工智能AI 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载本指南以 Open CoDesign 内置方法技能method skillempty-states.md 为绝对核心讲解「首次使用 / 无结果 / 错误」三种空状态的分类规则、文案与代码模式并结合仓库源码技能加载器、SkillFrontmatter 校验、内置脚手架揭示其在实际 AI 生成流程中的落地机制。读完本文你将掌握一套可直接复用的空状态设计规范以及 Open CoDesign 中技能文件的编写、加载与调用原理能自己编写或改造同类的设计技能。Open CoDesign 是一款本地优先local-first、支持多模型Claude、GPT、Gemini、Kimi、GLM、Ollama的开源设计生成工具核心工作流是Prompt → 原型 / 幻灯片 / PDF。为了让 AI 生成的设计稿在细节上达到专业水准项目内置了一批方法技能method skill——以 Markdown 编写的规则说明书由 agent 在写代码前加载。empty-states就是其中专门约束空状态empty state设计的技能。一、empty-states 技能是什么定位与触发条件empty-states是 Open CoDesign 内置技能之一其任务定位记录在技能文件的 YAML frontmatter 中见 empty-states.mdname: empty-states技能 ID同时是skill(name)工具调用的入参description明确说明它为三类关键空状态设计界面——首次使用还没有任何记录、无结果筛选/搜索无匹配、错误网络/服务失败并用于替换一切笼统的 No data 占位符trigger.providers: [*]对所有模型提供方Claude、GPT、Gemini 等通用不区分具体厂商trigger.scope: system触发作用域为系统级即任何生成任务都可能在合适时机调用user_invocable: true用户也可以主动要求加载该技能。什么时候应该触发它技能正文第一段定义了触发时机——任何可能渲染出零条数据的 UI 表面列表、表格、看板kanban、收件箱视图搜索与筛选结果面板依赖数据的仪表盘与统计组件通知、动态流、评论线程任何可能发生网络或查询失败的界面。也就是说空状态不是最后补一个占位图的收尾工作而是一类必须被提前设计的状态任何数据驱动的界面都要覆盖。技能文件在仓库中的组织方式empty-states技能文件位于应用模板树中apps/desktop/resources/templates/skills/empty-states.md根据 templates/README.md 的说明skills/*.md是可编辑的 Markdown 方法技能通过skill(name)加载它们描述如何工作布局、可访问性、图表、表单、响应式行为、工艺检查等。整个resources/templates目录会在首次启动时被复制到用户的应用数据目录中形成一棵用户可编辑的模板树用户可以在userData/templates/skills/下看到并修改这些技能文件。仓库中的技能全家桶见 skills 目录还包括form-layout、loading-skeleton、surface-elevation、cjk-typography、accessibility-states、responsive-layout、craft-polish等同级技能empty-states是其中的 P0 级设计技能之一见 apps/desktop/CHANGELOG.md 中 5 new P0 design skills 的发布记录。二、三条铁律恰好三种空状态绝不合并、绝不裸奔技能的 Rules 部分确立了整个规范的核心——世界上恰好有三种空状态每种有各自的文案模式不能折叠成一个通用组件首次使用First-use——用户还没有创建第一条记录。一句话解释这个功能是做什么的一个主 CTA——创建第一条记录的那个动作一张与产物相关的示意插图发票、图表、聊天气泡不要用通用的剪贴板或放大镜图标。无结果No-results——用户筛选或搜索后没有任何匹配。复述用户的查询No tickets matched urgnet必须原样引用实际查询词从以下四种补救动作中提供两个清除筛选clear-filter、扩大搜索范围broaden-search、拼写建议suggest-spelling、最近结果recent-results绝不能复用首次使用的插图——否则用户会以为自己的数据丢失了。错误Error——请求失败。用通俗语言说明原因Network unreachable、Server returned 500主 CTA重试Retry次级链接反馈问题或打开调试详情面板绝不能让整屏只显示一条堆栈跟踪。另外还有两条补充规则统计占位统计卡片没有数据时渲染一个长破折号—而不是0。0是一个真实值今天的销售额是零—才表示没有数据。代码模式是{value ?? —}。绝不允许上线一个只写着 No data 或 Nothing here yet 的界面——每一个空状态都必须回答我接下来该做什么。Do / Dont 速查Do应当在无结果消息中原样引用用户的查询词每个分类使用不同的插图让用户能直观区分第一次来和没有匹配错误状态提供 Retry 按钮并在重试时使用乐观 UIoptimistic UI空状态文案与其他字符串一起进入本地化i18n目录。Dont禁止不要把首次使用插图复用到无结果状态不要在从未收到过数据的统计卡片上显示0不要单独展示技术错误码如Error 500必须搭配人类可读的原因不要让空状态被一个永远不结束的 spinner 遮住。三、Code patterns四段可直接落地的 TSX 模板技能文件提供了四段可复制的 React/TSX 代码模式全部基于 Tailwind 类名实现。3.1 首次使用First-usediv classNamegrid place-items-center gap-4 py-16 text-center InvoiceIllustration classNamew-32 h-32 opacity-80 / p classNamemax-w-sm text-sm text-muted-foreground Invoices you create will appear here. Send your first one to get paid. /p button classNameh-11 px-4 rounded-md bg-blue-600 text-white Create invoice /button /div关键点一句功能说明 一个主 CTA 与产物强相关的插图发票示例。插图用opacity-80弱化视觉重量避免喧宾夺主。3.2 无结果No-resultsdiv classNamegrid place-items-center gap-3 py-12 text-center SearchIllustration classNamew-24 h-24 opacity-70 / p classNametext-smNo tickets matched strong{query}/strong./p div classNameflex gap-2 button onClick{clearFilters} classNameh-9 px-3 text-sm rounded borderClear filters/button button onClick{broaden} classNameh-9 px-3 text-sm rounded borderSearch all projects/button /div /div关键点查询词用strong原样强调提供两个补救动作清除筛选 扩大搜索范围插图换成了放大镜类注意它和首次使用的产物插图不同——首次使用禁止用放大镜这里是搜索语义的合法场景且不能复用首次使用插图。3.3 错误Errordiv classNamegrid place-items-center gap-3 py-12 text-center AlertIllustration classNamew-24 h-24 text-red-500 / p classNametext-smNetwork unreachable. Check your connection and try again./p button onClick{retry} classNameh-10 px-4 rounded bg-blue-600 text-whiteRetry/button a href/support classNametext-xs underline text-muted-foregroundReport this problem/a /div关键点人类可读的原因说明Network unreachable Retry 主按钮 Report this problem 次级链接。错误插图用text-red-500传达警示语义。3.4 统计占位Stats placeholderdd classNametext-2xl font-semibold{value ?? —}/dd关键点用空值合并运算符??——只有value为null/undefined时才显示—真实的0值照常渲染。四、从规范到实现技能在 Open CoDesign 中如何被加载与调用empty-states不只是一份给人看的规范它是会被 agent 实际加载执行的可运行规则。理解其背后的加载机制能让你真正掌握这类技能文件的编写方法。4.1 Frontmatter 的 Schema 定义技能 frontmatter 由 Zod schema SkillFrontmatterV1 严格校验字段包括字段类型/默认值说明schemaVersion字面量1版本标识name字符串必填技能名对应文件名 slugdescription字符串必填≤1536 字符给 agent 的能力描述aliases字符串数组默认[]别名可用别名调用dependencies字符串数组默认[]依赖的其他技能validationHints字符串数组默认[]校验提示trigger{providers: [*], scope: system \| prefix}触发条件适用模型、作用域disable_model_invocation布尔默认false是否禁止模型主动调用user_invocable布尔默认true是否允许用户主动调用allowed_tools字符串数组可选技能可用的工具白名单empty-states.md的 frontmatter 完全符合该 schemaproviders: [*]表示所有模型提供方通用scope: system为系统级disable_model_invocation: falseuser_invocable: true意味着模型可以自动触发、用户也可以手动点名。4.2 加载器与优先级技能加载器位于 packages/core/src/skills/loader.ts包含一套手写的轻量 YAML frontmatter 解析器支持折叠标量、字面量标量|、行内序列[a, b]、块序列- item等然后通过SkillFrontmatterV1.safeParse校验失败会抛出ERROR_CODES.SKILL_LOAD_FAILED。加载分为三个层级优先级为project user builtin见loadAllSkillsbuiltinDir应用内置技能目录即resources/templates/skillsuserDir~/.config/open-codesign/skills之类的用户目录projectDirproject/.codesign/skills项目目录。当多个层级存在同名技能时高优先级覆盖低优先级——用户或项目可以改写内置技能的行为这是技能体系可定制性的关键。4.3 skill 工具agent 如何读规则packages/core/src/tools/skill.ts 中的makeSkillTool把技能暴露为 agent 的skill工具入参name即技能 ID如empty-states描述中明确列举了empty-states等内置技能名invokeSkill先列出技能清单listSkillManifest按名字或别名匹配再从模板树中读取 Markdown 正文返回给模型每个会话对每个技能只加载一次重复调用会返回简短的 already loaded 提示避免重复注入整篇文本浪费上下文dedup机制读取路径经过resolveSafeManifestPath安全检查拒绝符号链接穿越模板根目录registered path escapes template root / registered path traverses symbolic link防止路径逃逸。也就是说当生成任务涉及列表、仪表盘、搜索等界面时agent 会调用skill(empty-states)把这份规范注入上下文再据此写代码。测试用例 packages/core/src/tools/skill.test.ts 和 packages/core/src/skills/loader.test.ts 均覆盖了empty-states的加载与依赖解析。4.4 配套脚手架empty-states.jsx除方法技能外仓库还提供了配套的可复制源码片段 empty-states.jsx在 scaffolds/manifest.json 中登记为ui-primitive类别。它内置了五种空状态变体搜索无结果、收件箱清零✉️、图表无数据、看板为空、出错重试⚠️每种都包含图标、标题、说明与 CTA 按钮可作为scaffold(kind, destPath)复制的起点素材。注意区分skills/*.md是方法规则如何做scaffolds/ui-primitives/*.jsx是起点素材直接复制的代码二者通过 manifest 分开管理。五、把规范落进你自己的界面一份 5 步检查清单把empty-states技能提炼成可执行的设计流程盘点所有零数据场景列表、搜索、仪表盘、通知、评论线程逐个标注属于首次使用 / 无结果 / 错误中的哪一类——绝不合并也绝不遗漏错误态。按分类写文案首次使用写功能是什么 下一步动作无结果原样引用查询词并给两个补救动作错误用通俗语言说明原因并给 Retry 与反馈入口。分配插图语义首次使用用产物相关图发票、图表、气泡无结果用搜索语义图两者必须不同错误用警示语义图。统计卡片无数据一律—不用0。给每个空状态一个下一步主 CTA 指向能改变现状的动作创建、清筛、重试、换关键词。本地化与重试体验文案进 i18n 字符串目录错误重试配合乐观 UI避免用户卡在永不停歇的 spinner 前。对照 Do / Dont 清单 逐项自检是否复用了插图是否显示了裸错误码是否出现了裸 No data六、结语空状态是一等公民而不是事后补丁empty-states技能的价值在于把空状态设计从可有可无的收尾工作提升为有明确分类、有固定文案模式、有代码模板、有落地机制的一等设计规则。在 Open CoDesign 中它通过 frontmatterSkillFrontmatterV1 Markdown 正文 加载器loader.tsskill工具skill.ts这条完整链路进入每个生成会话让任何模型在产出列表、仪表盘、搜索界面时都能遵守同一套高标准。如果你正在 Open CoDesign 中编写自己的技能或希望在自己的产品中推行空状态规范可以直接把 empty-states.md 作为模板写好 frontmatter名称、描述、触发条件、写清 Rules 与 Do/Dont、附上可复制的代码模式然后放入skills目录即可被加载。记住它的核心判断三种空状态缺一不可每个空状态都必须回答下一步做什么。赞分享人工智能AI 应用桌面应用【免费下载链接】open-codesignOpen-source Claude Design alternative. One-click import your Claude Code / Codex API key. Prompt → prototype / slides / PDF. Multi-model (Claude, GPT, Gemini, Kimi, GLM, Ollama). BYOK, local-first, MIT.项目地址https://gitcode.com/gh_mirrors/op/open-codesign点击查看免费下载相关推荐Phoenix 前端空状态Empty States设计规范从 No tags 到 No results 的语义化实现指南Phoenix 前端空状态Empty States设计规范从 No tags 到 No results 的语义化实现指南 Phoenix 前端位可观测性AI 评测LLMOpsAI 应用人工智能Open CoDesign DESIGN.md设计系统实战把品牌规范变成可复用的AI设计记忆Open CoDesign DESIGN.md设计系统实战把品牌规范变成可复用的AI设计记忆 Open CoDesign 是一款开源的桌面端 AI 设计工具人工智能AI 应用桌面应用typescript-sdk 服务端 Tools 开发指南registerTool 注册、参数校验与结构化输出typescript sdk 服务端 Tools 开发指南registerTool 注册、参数校验与结构化输出 本篇指南基于 modelcontextpro人工智能AI 应用桌面应用上一篇深度解析AList 115 Open存储驱动Token格式错误的终极修复方案下一篇tmux-resurrect 程序恢复配置吃透 ~、-、* 三大符号10 分钟搞定自定义恢复列表创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表