网页控件翻译词典面向 Vibe Coding
把模糊需求 翻译成一次做对的规格。
Better Web Controls 是一本给 AI 读的控件词典。
控件名称、形式与操作规则写明白了，AI 才不会靠猜。
npx skills add shanchuann/better-web-controls
同一个需求
原话
帮我做个下拉，能选负责人
AI 自己猜形式、猜操作规则。猜错一次，返工一次。
规格
负责人用 Select 单选下拉：选项为团队成员、单选、选中打勾、可清空重选、点外部或 Esc 关闭
形式与操作规则一次到位，交付可以复核。
效果预览
从上往下读的经营报告 先结论，再趋势，最后原因
能选负责人的单选下拉 选中打勾，可清空重选
滚动后收窄的导航栏 桌面悬浮吸顶，移动端沉底
按住拖动的轮播 松手回正，键盘也能操作
输入文字才能删除 输入一致之前，按钮不可用
首次使用的空页面 给创建和导入两条路
工作流
-
01
识别需求类型
控件、布局、交互规则、修复、图表，先归位，再读对应的参考文件。
-
02
列候选，写理由
下拉 7 种、进度 8 种、导航 9 种，用途各不相同。给出 2 至 3 个候选和适用场景，信息不足就先问。
-
03
留下选型笔记
候选对比、判断依据、升级条件写进 notes.md。过程可复核，交付可验收。
-
04
输出规格
按名称、形式、操作规则的固定顺序给出 Prompt，或直接按规格生成页面。
评测
带技能
100%
36 / 36 条断言通过
产出里有候选对比、选型理由和升级条件，可以拿去验收。
不带技能
86.1%
31 / 36 条断言通过
直接给实现，过程不可复核。这一组运行时禁止读取技能目录。
+13.9pp同一批场景，只差一本词典
| # | 场景 | 带技能 | 不带技能 | 不带技能的失败项 |
|---|---|---|---|---|
| 0 | 导航栏没有候选对比与选型理由 | 4 / 4 | 3 / 4 | 没有候选对比与选型理由 |
| 1 | 页面修复 | 4 / 4 | 4 / 4 | 无 |
| 2 | 轮播 | 4 / 4 | 4 / 4 | 无 |
| 3 | 下拉选人没有候选对比与选型理由 | 4 / 4 | 3 / 4 | 没有候选对比与选型理由 |
| 4 | 删除确认 | 4 / 4 | 4 / 4 | 无 |
| 5 | 保存提示 | 4 / 4 | 4 / 4 | 无 |
| 6 | 经营报告图表没有图表选型理由 | 4 / 4 | 3 / 4 | 没有图表选型理由 |
| 7 | 空状态双场景无结果态放了错误的大按钮 | 4 / 4 | 3 / 4 | 无结果态放了错误的大按钮 |
| 8 | 登录页没有候选对比与选型理由 | 4 / 4 | 3 / 4 | 没有候选对比与选型理由 |
差距落在选型过程
5 个失败项里，4 个是没写候选对比与选型理由。裸跑直接给实现，过程不可复核；带技能的产出把判断依据留在了 notes.md 里。
隐性规则决定对错
空状态一题，裸跑把搜索无果做成了提示加大按钮，还加了新建客户这个会把用户带向错误动作的入口。带技能按搜索改关键词、筛选改条件的规则处理。
参考文件
- controls.md 控件图鉴 按钮 6 形态、下拉 7 种、轮播 7 种、Tab 6 种、侧边栏 5 种、弹窗、进度 8 种、上传 5 种、表格 5 种、长列表加载 3 种、步骤条、Tooltip、命令面板、特殊控件 10 种、表单输入控件。
- layouts.md 布局与结构 网站布局 7 种、AI 产品布局 6 种、登录页 5 种、导航 9 种、首页 10 模块、首屏设计、大屏 5 种布局、工作台实战、风格参考图。
- rules.md 交互规则 提示 7 级、二次确认 7 种、等待体验 6 种、校验时机、表单 7 检查点、空状态 5 种、对齐 5 种、长页面定位 7 种、分组方式、设计术语 7 词、暗色模式、移动端降级 7 项。
- fixes.md 细节修复 细节修复 7 句，按症状、病因、指令三段写；常见问题 6 句 Prompt。
- charts.md 图表选型 10 种图表与场景的对应关系，以及用来定夺的决策问句。
安装
# 交互式安装，自动识别已装好的 agent
$npx skills add shanchuann/better-web-controls
# 只写到 OpenCode
$npx skills add shanchuann/better-web-controls -a opencode
# 全局安装，跨项目可用
$npx skills add shanchuann/better-web-controls -g
- 01环境。Node.js 22.20 以上。skills CLI 支持 75 个以上的 agent。
- 02落位。安装时写入对应 agent 的技能目录：OpenCode 为
.opencode/skills/，全局为~/.config/opencode/skills/，不用手动放。 - 03更新。技能发版后执行
npx skills update即可。