agile-proto

Name: agile-proto
Author: djalmajr

github.com/djalmajr设计与 UI4135 次安装5 周前更新

代码仓库

关于 agile-proto

agile-proto 是用于构建零构建、浏览器原生原型的技能，可在正式开发前验证流程与交互。它指导场景组织、HTM UI 实现、交互检查及可选的 Figma 捕获。

主要功能

01零构建 HTML、CSS 和 JavaScript 原型
02基于场景的路由与项目目录指引
03HTM UI 和 z-proto 工作流指导
04交互验证清单
05可选的 Figma 捕获流程

适用场景

01在正式开发前验证产品流程
02将原型场景与敏捷规划文档一起管理
03为所需的 Figma 交接准备运行中的场景

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/djalmajr/skills --skill agile-proto

安装后在 Claude Code 中输入/agile-proto确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

templates/

index.css

index.html

index.js

templates/routes/

home.js

templates/scripts/

bootstrap.sh

详细介绍

静态浏览器原型设计

构建独立原型，在正式实现前验证流程和交互。保持零构建，并采用浏览器原生技术。

“静态”描述的是交付架构：可直接提供服务的 HTML、CSS 和 JavaScript，无需后端或必需的构建流程。原型仍可包含逼真的客户端交互。

如果原型属于某个敏捷计划，请将其放在 planning/<initiative>/proto/ 中，与需求收集、路线图、业务规则和未来的 Epic 工件并列。只有当项目已经遵循该约定时，才使用 {app}/client-proto/。

配套技能：htm-ui

/agile-proto 负责流程：写入位置、场景、z-proto、Figma 截图和串联。组件、令牌、importmap、API 和 UI 示例属于 htm-ui 技能（https://github.com/djalmajr/htm-ui）。此软件包不包含该技能或其示例目录。

实现场景前：

在运行环境的技能根目录（.agents/skills/、.claude/skills/、.opencode/skills/ 及其 ~/ 对应目录）中查找 htm-ui/SKILL.md。
如果存在，请阅读并遵循其中关于组件选择、主题和 API 验证的说明。
如果不存在，请说明缺少此配套技能。不要假装此技能可以替代 htm-ui。请提示安装：

bunx skills add djalmajr/htm-ui --skill htm-ui

如果机器上有多个 Agent，请使用安装此软件包时采用的相同 --agent 标志。

如果未安装该技能，本次会话仍不要因此阻塞原型开发：请使用在线文档 https://djalmajr.github.io/htm-ui/ 和 CDN 模块。官方示例：apps/docs 和 apps/todo。不要将组件目录复制到原型中。

项目根目录

所有路径都应相对于原型所在的仓库解析，而不是技能仓库。如果当前目录位于同级仓库中，请在路径前加上明确的项目根目录。只有在目标确实不明确时才提问。

提示

对于会实质性影响结果的选择，请使用运行环境的结构化提问工具：

决策	建议选项
保真度	草图 · 线框图 · 高保真
Figma 交接	否 · 是
已有原型	扩展现有原型 · 重新开始
缺少 `htm-ui` 技能	立即安装 · 仅使用 CDN／文档继续

如果用户明确要求不中断地执行，请记录尚未解决的选择，并采用最安全、可撤销的假设继续。

技术栈

z-proto：设备预设、缩放、框架和截图控制。
HTM UI：组件——使用经验证的公开源，绝不将组件目录复制到原型中。
Tailwind CSS v4 浏览器模式：采用规范的 HTM UI 语义令牌映射（参见 htm-ui 技能／THEMING.md）。
Preact + htm + preact-iso：用于渲染、状态管理和场景路由。
Iconify：通过 HTM UI 的 Icon 组件使用。

使用方的 importmap：

https://cdn.jsdelivr.net/gh/djalmajr/htm-ui@main/packages/ui/

在确认 npm 版本发布之前，不要指向 esm.sh/htm-ui。不要将 HTM UI 源模块复制到 components/ui/。

从 HTM UI 获取的内容（实时）

不要在此技能中冻结 UI 副本。启动时，从 HTM UI 获取以下内容：

部分	来源
组件	importmap `htm-ui/<module>.js`（CDN）
令牌	`packages/ui/theme.css` 和 `ui.css`（CDN）
Tailwind `@theme` 映射	HTM UI `THEMING.md`，由 `templates/scripts/bootstrap.sh` 注入
产品外壳／场景	使用 `htm-ui` 技能，通过 HTM UI 基元组合

不要从 HTM UI 的 apps/docs 导入 AppShell——该文件是文档界面的外壳（HTM UI 品牌标识、GitHub 星标），不是产品起始模板。

结构

此技能中的模板仅包含原型胶合层（z-proto、routes、Figma）。UI 和主题来自 HTM UI。

planning/<initiative>/proto/
├── index.html
├── index.css
├── index.js
└── routes/
    └── home.js

在 routes/ 中每个场景单独创建一个文件，并在 SCENES 中注册。如果产品需要外壳（侧边栏、顶栏），请使用 htm-ui/sidebar.js 等进行组合——不要复制本地目录。

引导

SKILL_DIR="<folder containing this SKILL.md>"
bash "$SKILL_DIR/templates/scripts/bootstrap.sh" planning/<initiative>/proto
cd planning/<initiative>/proto
bunx serve -s .

应用约定如下：

bash "$SKILL_DIR/templates/scripts/bootstrap.sh" my-app/client-proto
cd my-app/client-proto
bunx serve -s .

此脚本会复制胶合层，并注入来自 HTM UI THEMING.md 的 @theme 块。使用 SPA 模式，以便直接重新加载 preact-iso 路由时能解析到 index.html。

场景实现

遵循 htm-ui 技能（如果未安装，请参考文档/CDN）：

检查现有原型和项目规则。
查阅实时文档和实际模块导出内容。
编写自定义标记前，先选择现有组件和变体。
每个文件单独导入：

import { Button } from "htm-ui/button.js";
import { Card, CardContent, CardHeader, CardTitle } from "htm-ui/card.js";

在多行模板中，每个组件的开始/结束表达式都必须单独占一行。
让每个承诺的交互都可观察，并在适当情况下支持撤销。

文档：https://djalmajr.github.io/htm-ui/components/<slug>。运行时：https://cdn.jsdelivr.net/gh/djalmajr/htm-ui@main/packages/ui/<module>.js。切勿根据 React shadcn 推断 API。

实现交接

浏览器原型本身就是自描述的实现依据：稳定的场景 ID 和路由用于标识流程；htm-ui/<module>.js 导入用于标识基础组件。不要仅为重复记录这些导入而添加第二份必需目录。

缺失映射应作为警告处理，绝不能自动阻止流程。

场景模式

每个场景都放在单独的文件中，并使用稳定的 id 和 path 注册到 SCENES。骨架会直接渲染场景；如果产品需要外壳，请使用 HTM UI 基础组件进行组合。

import { html } from "htm/preact";
import { useState } from "preact/hooks";
import { Button } from "htm-ui/button.js";

export function InvitePage() {
  const [sent, setSent] = useState(false);
  return html`
    <main class="flex h-full w-full flex-1 flex-col gap-4 overflow-y-auto p-6">
      <${Button} onClick=${() => setSent(true)}>
        Send invitation
      <//>
      <p aria-live="polite" class="text-sm text-muted-foreground">
        ${sent ? "Invitation sent." : "No invitation sent yet."}
      </p>
    </main>
  `;
}

保留对 ?route=<scene-id> 的支持。Figma 截图使用 URL 哈希，因此模板的路由桥接必须在根据查询字符串选择场景时保留 #figmacapture。

产品保真度

预先填充表单，并使用真实的内联模拟数据。
除非已发布的产品会展示，否则不要在可见 UI 中暴露内部架构、测试说明、提供方或业务规则解释。
将发现的领域规则以稳定 ID 记录在 planning/<initiative>/business/*.md 中。
基础示例和变体示例在数据、配置和行为上都应有实质差异。
使用语义化令牌和内置组件变体；避免在产品界面中使用原始调色板类。
保持标准输入框、选择框和按钮的高度。
对有界滚动区域使用 ScrollArea，并避免文档滚动相互冲突。
测试覆盖层碰撞处理，并确保下拉菜单/弹出框内容不会被原型框架裁切。

交互验证

逐页验证原型页面。不要等评审人员发现示例无法交互。

对于每个交互式场景：

点击每个主要和次要操作；
编辑输入框和选择框，并确认状态变化可观察；
测试键盘焦点、Enter/Space、Escape 和 Tab 顺序；
测试菜单和覆盖层能否通过点击外部关闭；
测试窄屏和宽屏视口预设；
测试内容溢出和内部滚动；
确认没有控制台错误或模块加载失败；
对照实际实现的行为检查 UI 文案。

对于按钮、表单、开关、菜单、可排序列表、分段输入框或覆盖层，仅有静态截图是不够的。

Figma 导出

先构建并验证 HTML 原型，然后捕获正在运行的界面。不要将手动重绘的近似版本作为主要交付成果。

确保 index.html 加载 https://mcp.figma.com/mcp/html-to-design/capture.js。
在 localhost 或 HTTPS 上提供原型。
使用 ?route=<scene-id>#figmacapture=<captureId>&figmaselector=%23app 打开每个场景。
轮询时重复使用同一个 capture ID；待处理期间不要生成替代 ID。
将捕获内容放在专用的 source-captures 页面上，按路由命名，并安排好布局以供审阅。
将任何较早手工构建的近似版本标记为过时。

如需手动粘贴到 Figma 桌面版，请在 <z-proto> 上设置 figma-key，并使用其捕获操作。

规则

原型无需使用构建工具、安装包、JSX 或 TypeScript。
仅从 htm-ui/<module>.js 导入组件；绝不要创建本地复制的 UI 组件库。
使用 <${Icon} icon="lucide:..." />；绝不要添加 lucide-react。
每个文件只放一个场景，并在 SCENES 中注册。
使用 htm-ui/ 基元组合外壳（htm-ui 技能）；不要复制 apps/docs 或本地组件库。
模拟数据保留在场景内部；不要添加后端。
为每个场景指定一个明确的滚动所有者。
使用语义化主题令牌，而非原始颜色值。
将交互验证视为完成工作的一部分。
请求 Figma 交接时，捕获正在运行的原型。
不要在此包中重复官方 HTM UI 示例；请阅读 htm-ui 技能或文档。

检查清单

后续衔接

原型通过验证后：

UI 密集型项目 → /agile-epic（或针对局部屏幕使用 /agile-story）。将场景 ID 放在 Prototype refs 下。
可选：使用原型路由作为第一个目录，运行 /ux-flows new（或 discover），然后针对已提供服务的原型或后续生产应用运行 /ux-persona。
除非用户豁免此关卡，否则不要从未经验证的原型直接跳到生产环境实现。

支持 Markdown

登录后评论