agent-notes-kit 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +190 -2
  3. package/install.mjs +254 -0
  4. package/package.json +23 -4
  5. package/scripts/agent-note-tree.mjs +77 -0
  6. package/scripts/archived-agent-notes.mjs +143 -0
  7. package/scripts/verify-agent-note-classification.mjs +17 -0
  8. package/scripts/verify-agent-note-format.mjs +79 -0
  9. package/scripts/verify-archived-agent-notes.mjs +126 -0
  10. package/template/.agents/agents/README.md +40 -0
  11. package/template/.agents/agents/_main.md +46 -0
  12. package/template/.agents/agents/_template.md +18 -0
  13. package/template/.agents/agents/architect.md +18 -0
  14. package/template/.agents/agents/archivist.md +18 -0
  15. package/template/.agents/agents/doc-writer.md +18 -0
  16. package/template/.agents/agents/implementer.md +18 -0
  17. package/template/.agents/agents/reviewer.md +18 -0
  18. package/template/.agents/agents/test-engineer.md +18 -0
  19. package/template/.agents/agents/ui-reviewer.md +18 -0
  20. package/template/.agents/notes/AGENTS.md +7 -0
  21. package/template/.agents/notes/README.md +123 -0
  22. package/template/.agents/notes/archived/AGENTS.md +7 -0
  23. package/template/.agents/notes/archived/architecture/.gitkeep +0 -0
  24. package/template/.agents/notes/archived/bug-fix/.gitkeep +0 -0
  25. package/template/.agents/notes/archived/feature/.gitkeep +0 -0
  26. package/template/.agents/notes/archived/manifest.json +4 -0
  27. package/template/.agents/notes/archived/process/.gitkeep +0 -0
  28. package/template/.agents/notes/archived/simplification/.gitkeep +0 -0
  29. package/template/.agents/notes/archived/testing/.gitkeep +0 -0
  30. package/template/.agents/notes/implemented/AGENTS.md +13 -0
  31. package/template/.agents/notes/implemented/architecture/.gitkeep +0 -0
  32. package/template/.agents/notes/implemented/bug-fix/.gitkeep +0 -0
  33. package/template/.agents/notes/implemented/feature/.gitkeep +0 -0
  34. package/template/.agents/notes/implemented/process/.gitkeep +0 -0
  35. package/template/.agents/notes/implemented/simplification/.gitkeep +0 -0
  36. package/template/.agents/notes/implemented/testing/.gitkeep +0 -0
  37. package/template/.agents/notes/proposed/architecture/.gitkeep +0 -0
  38. package/template/.agents/notes/proposed/bug-fix/.gitkeep +0 -0
  39. package/template/.agents/notes/proposed/feature/.gitkeep +0 -0
  40. package/template/.agents/notes/proposed/process/.gitkeep +0 -0
  41. package/template/.agents/notes/proposed/simplification/.gitkeep +0 -0
  42. package/template/.agents/notes/proposed/testing/.gitkeep +0 -0
  43. package/template/.agents/notes/rejected/architecture/.gitkeep +0 -0
  44. package/template/.agents/notes/rejected/bug-fix/.gitkeep +0 -0
  45. package/template/.agents/notes/rejected/feature/.gitkeep +0 -0
  46. package/template/.agents/notes/rejected/process/.gitkeep +0 -0
  47. package/template/.agents/notes/rejected/simplification/.gitkeep +0 -0
  48. package/template/.agents/notes/rejected/testing/.gitkeep +0 -0
  49. package/template/.agents/skills/agent-experience/SKILL.md +25 -0
  50. package/template/.agents/skills/archive-agent-notes/SKILL.md +68 -0
  51. package/template/.agents/skills/code-review/SKILL.md +40 -0
  52. package/template/.agents/skills/doc-writing/SKILL.md +48 -0
  53. package/template/.agents/skills/error-handling/SKILL.md +35 -0
  54. package/template/.agents/skills/find-simplifications/SKILL.md +43 -0
  55. package/template/.agents/skills/init-architecture/SKILL.md +41 -0
  56. package/template/.agents/skills/pr-description/SKILL.md +51 -0
  57. package/template/.agents/skills/pre-push-checks/SKILL.md +42 -0
  58. package/template/.agents/skills/prose-standard/SKILL.md +49 -0
  59. package/template/.agents/skills/ui-ux/SKILL.md +107 -0
  60. package/template/.agents/skills/ui-ux/references/alignment.md +24 -0
  61. package/template/.agents/skills/ui-ux/references/icons.md +54 -0
  62. package/template/.agents/skills/ui-ux/references/responsive.md +52 -0
  63. package/template/.agents/skills/ui-ux/references/spacing.md +17 -0
  64. package/template/docs/AGENTS.md +36 -0
  65. package/template/docs/architecture.md +33 -0
  66. package/template/docs/contracts.md +22 -0
  67. package/template/docs/design/README.md +7 -0
  68. package/template/docs/design.md +30 -0
  69. package/template/docs/glossary.md +11 -0
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: prose-standard
3
+ description: 写、审、删、审文案时使用;决定文档/注释在哪里必须有,写够保留契约,删推理转录、重复与装饰。
4
+ ---
5
+
6
+ # 文案标准
7
+
8
+ 写够以保留契约,再删推理转录、重复与装饰。「契约」是调用方/被调方/实现者/生产者/消费者依赖的义务、不变量、前后条件或兼容承诺。
9
+
10
+ > 归属:本技能管句子级契约与删冗余;文档结构/放置/事实核对见 [doc-writing](../doc-writing/SKILL.md),常驻文档规则见 [docs/AGENTS.md](../../../docs/AGENTS.md)。
11
+
12
+ - 注释描述代码表达不了的非显然契约或理由,不复述代码。
13
+ - 用更精确的词(规则/API/字段集/类型/校验/时序点/组件拆分/失败态)取代泛词(contract/boundary/shape/surface 只在确指时才用)。
14
+
15
+ ## 保留完整命题
16
+
17
+ 编辑前先列出段落里的每个命题,保留相关的:施动者与动作、条件/时序/顺序、情态(must/may/never)、否定保证与例外、所有权/副作用/失败模式/后果。只有每个事实子句都存活且更清晰时,删形容词/重复/叙述才算改进——字数少本身不是改进。
18
+
19
+ 一处一个家:行为/失败/所有权/后果在使用点就地写全;架构/理由/算法/历史链接到归属文档。
20
+
21
+ ## 按位置要求的覆盖
22
+
23
+ - **公开 JSDoc**:可观察的返回区分、抛错、副作用、所有权、时序、取消、持久性。
24
+ - **内部注释**:非显然结构与明显复杂的局部结构——不变量、竞态顺序、所有权、安全边界、意外失败。
25
+ - **模块注释**:模块角色、依赖、职责、非显然架构选择。
26
+ - **测试**:只解释非显然设计——为何这个 fixture/断言/平台兼容/真实入口/间接观察必要。
27
+ - **README**:消费方契约——配置、语义、失败、限制、扩展点、模型可见效果。
28
+ - **决策记录**:保留独有理由、机制、备选、后果、验证证据、覆盖缺口。
29
+ - **提示与可见字符串**:文案即行为;措辞变化要有行为证据,无归属场景就保持不变并报 defer。
30
+ - **诊断**:点出失败主体/路径、违反的规则、非显然的修正。
31
+
32
+ ## 推理泄漏(cot-leakage)
33
+
34
+ 推理泄漏 = 视角停在「写作会话」而非仓库:引用只有那次会话能见的工件、叙述改动而非状态、或与已离开的评审者争论。
35
+
36
+ **一条测试**:HEAD 读者在没有会话转录/PR 线程/未提交草稿时,能否解析每个引用并验证每个断言?不能 → 重述存活事实、删其余。
37
+
38
+ 分类:死设计引用(`(decision 7)`/`§4.7`)→ 改为具名路径或删;堆栈/PR 视角("本 PR 加")→ 陈述机制;变更叙述("used to"/"不再")→ 陈述现状;评审编排("评审驳回")→ 保留结论删过程;控制流叙述 → 删;hedge("暂时够用")→ 升为 TODO 或陈述真实边界。
39
+
40
+ **非泄漏(保留)**:issue 引用、决策记录/复盘里的合并 PR 引用、抑制注释(如 `oxlint-disable … -- reason`)、反事实现状("没有 X 就会 Y")、实测数值、运行时新旧态。
41
+
42
+ ## 流程
43
+
44
+ 1. 确认 scope 与 mode(缺 scope 就停)。
45
+ 2. 读文档规范与归属代码再判断。
46
+ 3. 检查整个 scope,别只看大文件。
47
+ 4. 每个候选分类:保留/补充/删/还原/重构/推迟;只在授权编辑时改。
48
+ 5. 先改 owner 再改派生工件。
49
+ 6. 跑相关检查与 `git diff --check`。
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: ui-ux
3
+ description: 设计或评审项目用户可见 UI 时使用;覆盖对齐、间距、图标、视觉基础、几何与交互,改动前按影响分级做必做检查,交付前核验渲染结果。
4
+ ---
5
+
6
+ # UI 设计与评审
7
+
8
+ 本技能是 UI 设计与评审的入口,统领工作流、视觉基础、几何与交互;对齐、间距、图标、响应式细节在 references 里按需加载。结构性 UI 决策(设计系统、组件体系)在 [`.agents/notes/implemented/architecture/`](../../notes/implemented/architecture/) 留记录,见[决策记录规则](../../notes/README.md)。
9
+
10
+ <a id="required-review-loop"></a>
11
+ ## UI 改动工作流
12
+
13
+ 对所有 UI 改动(含可见的 loading、错误、禁用、展开、聚焦态)套用适用规则。按影响与回归风险选投入程度;普通开发不需要完整设计审计。
14
+
15
+ | 改动 | 必做检查 | 附加产出 |
16
+ |---|---|---|
17
+ | 本地文案、图标复用、配色或间距 | 看真实页面、受影响的相邻元素与相关状态,跑适用测试 | 简要汇报结果与缺口,无需单独方案/截图报告 |
18
+ | 页面布局、共享组件或全局样式 | 识别受影响关系与消费者,在组装后的页面里检查不同布局/内容/状态变体 | 简述范围,必要时保留起始版本与对比截图 |
19
+ | 显式的全面评审 | 覆盖约定区域与相关状态,区分已核验结果/缺陷/未核验范围 | 用评审清单记录覆盖、发现与证据 |
20
+
21
+ ### 受影响 UI 的最低检查
22
+
23
+ 即使小改动也适用;可省略文档,不可省略检查。开真实页面看改动元素及其直接相邻元素,而不是只看 CSS 或孤立组件。
24
+
25
+ - **颜色或透明度:** 看明暗两主题,含受影响的前景/背景与状态组合。
26
+ - **布局、间距、排版或尺寸:** 看受限容器与长内容/换行,检查断点两侧、对齐、裁切与操作可达性。
27
+ - **交互:** 走一遍改动路径与受影响的聚焦/禁用/加载/错误/展开/重叠态。只看改动能影响到的状态,不是穷举组合。
28
+ - **共享组件或全局样式:** 追踪受影响的消费者,检查不同组装布局与状态;单个孤立示例不构成覆盖。
29
+
30
+ 若必需场景不可得,说明没查什么、为什么、如何补验;标签化的生产组件 fixture 只算部分证据,不是真实页面。没做完必需检查,不得声称核验完成。跑原有适用测试;源码检查与测试通过不等于渲染结果正确。
31
+
32
+ 相关改动一起批处理,复用现有应用实例与有效证据。纯文档改动、或渲染结果可证明不变的 refactor,无需新截图,说明依据即可。
33
+
34
+ 需要前后对比时,保留真实的起始实现(含未提交改动),用可比条件截图。绝不重建缺失的「before」冒充原件。无论是否需额外证据,都保护现有工作。
35
+
36
+ 交接/评审/推送前,只核对新增的累计交互、缺失的必需检查与失效的证据;不要每个阶段都重做已完成核验。如实汇报结果与缺口;缺必需场景/检查时,不得声称完整覆盖或视觉验收。
37
+
38
+ ## 选规则归属(按需加载 reference)
39
+
40
+ | 需要决定 | 看哪份 |
41
+ |---|---|
42
+ | 共享轴、文本起点、居中、树缩进、完整图标盒 | [对齐](references/alignment.md) |
43
+ | 语义分组、内外间距、重复节奏、分节 | [间距与分组](references/spacing.md) |
44
+ | 图标选择/绘制、图标按钮、图标义不清的操作、可访问标签与焦点 | [图标](references/icons.md) |
45
+ | 响应式布局、移动端 hover/触屏、截断、icon-only、移动键盘 | [响应式与移动端](references/responsive.md) |
46
+ | 颜色、排版与既有处理 | 下方「视觉基础」 |
47
+ | 组件几何、嵌套轮廓、状态填充 | 下方「组件几何」 |
48
+ | 反馈生命周期、加载、覆盖层、平台留白 | 下方「交互与反馈」 |
49
+
50
+ 只加载与任务相关的 reference,不默认全部加载。
51
+
52
+ ## 复用优先
53
+
54
+ 能力合适时优先扩展现有组件、容器与交互;图标先搜库复用,不复制 SVG、不造近似重复。重构前先读项目的组件/状态归属与分层约定。
55
+
56
+ ## 视觉基础
57
+
58
+ - 复用页面或最近相似处的 token、数值与整套处理,不随手加字面量。
59
+ - 颜色明暗两主题都验;保证前景/背景可读,尤其弱化文字。
60
+ - 字号克制:新增/改动的 CSS 默认不用加粗(≤500),靠尺寸或墨色强调。
61
+ - 用主题排版角色 → 页面自身尺度 → 同类页面比例,不要为单个元素发明尺寸;同辈共享尺寸、尺度保持精简。
62
+
63
+ ## 组件几何
64
+
65
+ 先定组件角色与尺寸变体,再定容器关系。高度、圆角、曲线、内缩与材质一起比;圆角相同不等于协调,换行/展开不等于该用更大圆角。
66
+
67
+ - **内缩:** 协调内/外曲线与内缩;同心圆弧的圆角相减是精确的,超椭圆只是名义尺寸,还要看对角线留白。
68
+ - **平接/相邻:** 外框拥有外露角,内部接缝保持直角;hover 填充与伪元素沿此轮廓,不裁菜单/焦点。
69
+ - **独立子卡片/分组:** 用自己的角色/尺寸档,不沿用对话框圆角或父级 padding 相减。
70
+ - **圆/胶囊:** 保持形状(含头像容器与图片),用主题的圆曲线例外;普通控件用共享曲线。
71
+
72
+ 保持填充、描边与覆盖层在 hover/按下/选中/加载/禁用态几何稳定。阴影自带中性发丝线时,保留语义色描边、不叠中性边。相关控件在受影响主题/状态下、实际尺寸、相关长标签/窄布局里一起比;静态检查能拦不支持的声明,渲染对比才判合身。
73
+
74
+ ## 交互与反馈
75
+
76
+ ### 反馈面
77
+
78
+ 按消息生命周期选反馈:
79
+
80
+ - 瞬时成功/失败用应用级 Toast,宿主要活得比上报面板/标签长(例如删除会关闭来源面板,Toast 不能随它消失)。不要对 pending 态 toast。
81
+ - 失败操作保留可见数据;删除失败保留行。
82
+ - 面板内失败用就地提示:查询失败给 Retry、字段校验就地显示;有内容时放紧凑提示,仅空面板用居中完整错误态。
83
+ - 错误文案短而平实,一句话,无内部黑话(必要诊断码除外)。中文提示最多两句、结尾省句号。给提示留位或用 overlay,避免挤动相邻元素。
84
+
85
+ ### 加载态
86
+
87
+ 列表用骨架,其余页面级加载用居中裸 spinner;每页/组件一种加载处理(含并发区域)。仅当上下文需要才加加载文字。
88
+
89
+ ### 覆盖层与菜单
90
+
91
+ 合并前验证每个菜单/popover/tooltip:点外关闭(可聚焦时 Esc 关闭)、留边距适配视口、逃逸祖先裁剪/包含块/邻居遮挡(需要时 portal 到 body);只翻到能容纳的一侧,两侧都不行时不来回翻。共享滚动条样式与小幅内缩;滚动条不得被圆角/边缘裁剪。
92
+
93
+ ### 平台窗口适配
94
+
95
+ 新头部/页面兼顾各平台窗口 chrome;菜单/模态/overlay 原语消费平台的 frame 留白变量;本地平台 inset 用作用域覆盖 + 样式断言修复,不改全局变量;一并核验总留白 + 页面内缩。
96
+
97
+ ## 一起检查
98
+
99
+ 先看整体构图,再看内部/跨组关系、远处同辈与展开内容。轴两端都要对上;完整图标盒对齐后再做光学微调。保留弹层/焦点可见性、字段反馈、窄布局操作与草稿。检查受影响主题材质/平台背景。整界面声明覆盖所有区域;fixture/裁剪只能证明其所渲染的范围。
100
+
101
+ ## 一条规则一个归属
102
+
103
+ 更新本技能内对应章节或 reference;不要把设计专长拆成独立技能。示例放案例参考,AGENTS 与 PR 流程链接到这里而非复制规则。规则改动写明适用范围、决策、例外与可观察验证,更新区分案例并删除被取代的陈述;只自动化可机械判定的检查。
104
+
105
+ ## 设计评审升级
106
+
107
+ 涉及面广的 UI 改动、或任何用户可感知的 UI/交互变化,须经设计或产品评审。无人担任该角色时,向设计/产品评审人申请。(评审人名单随团队变化,在此维护。)
@@ -0,0 +1,24 @@
1
+ # UI 对齐
2
+
3
+ 在 [UI 开发循环](../SKILL.md#required-review-loop) 内套用。对齐可比的同辈,包括可选图标与操作的槽位。
4
+
5
+ ## 先布局结构,再视觉校准
6
+
7
+ 区分点击目标、绘制的按钮、完整图标盒与绘制轮廓。有意的图标留白属于布局盒,不要因为像素没贴参考线就删它;放大目标不得移动该盒。先查容器、槽位、列、间距与意外覆盖,再做光学校正。CSS 盒相同、或每个绘制轮廓都对齐,都不单独构成平衡。
8
+
9
+ 跨用法不一致的字形归其图标 owner;针对特定构图的视觉校正需局部理由并与同辈对比。保留既有层级:子图标可与父文本对齐,但 DOM 嵌套不等于缩进。裸图标与带边框控件比较时,额外 hit padding 不是共享可见边。
10
+
11
+ ## 同时选对象和轴
12
+
13
+ 给对齐对象与参照容器命名。padding 相同不等于文本起点对齐;SVG 尺寸相同不等于可见中心对齐。贴近页脚操作的控件,明确选控件边还是完整图标盒边,测量时不要来回换。
14
+
15
+ | 对齐 | 用在哪 | 判断真实关系 | 常见错误 |
16
+ |---|---|---|---|
17
+ | 左缘 | 导航标签、列表标题、字段标签、阅读内容 | 同角色文本起点落在同一根刻意轴线上(含跨组) | 每个组件各有看似合理但不一致的内缩 |
18
+ | 水平居中 | 独立主按钮或短空态堆 | 图标+标签或整组在命名容器里居中 | 只居中标签、把图标贴在框外 |
19
+ | 垂直居中 | 单行图标/标签行或同级工具栏控件 | 可见中心平衡;整个可点单元高度稳定 | CSS 等高掩盖了不同 SVG 留白或行盒 |
20
+ | 基线/首行 | 混合字号、多行标签带前导图标 | 文本基线一致;图标属于目标首行 | 把图标相对整段多行居中 |
21
+ | 两缘 | 标题/操作行、左右两组 | 左组贴内容缘、右组贴尾部缘 | 把每个图标平均分布到整行宽度 |
22
+ | 重复列 | 操作簇、时间戳、文件行 | 对应槽位跨行共享中心或边缘 | 只有最后一个图标对齐、前面的漂移 |
23
+
24
+ 先正常化同辈控件的尺寸与槽位,再做必要的小光学偏移,并验证可比用法。保留可用、不重叠的 hit target,不用 transform 掩盖父布局不一致。透明 hit padding 可超出绘制的图标槽;收紧簇后检查相邻目标边。检查[间距](spacing.md)时不动已选轴;不确定的判断查案例。
@@ -0,0 +1,54 @@
1
+ # UI 图标
2
+
3
+ 在 [UI 开发循环](../SKILL.md#required-review-loop) 内、目标页面或模态上下文中套用。
4
+
5
+ ## 先复用现有图标
6
+
7
+ 按含义与支持变体搜图标库与可比 UI。复用共享组件;不要复制 SVG 进功能、也不要造近似重复。尺寸/颜色/位置不匹配属于变体或消费方布局,不是新画一张的理由。
8
+
9
+ 仅当现有图形无法表达含义、或用户要求不同设计时才画。画之前说明最接近的替代与未满足的含义/设计差异。新字形上线前需设计审批;被要求的草稿可本地准备。不要为修一个消费方而重画共享字形。
10
+
11
+ ## 系统风格
12
+
13
+ - 用极简、几何、功能性、含义熟悉的字形。轮廓、端点、接合、粗细、留白与复杂度与同辈一致;避免装饰性、插画感细节。
14
+ - 用简单几何与克制的圆角。16px 设计尺寸下约 1px 圆角是软化的起点,不是每个转角都要;保留有用的尖角。
15
+ - 默认单色轮廓、继承 `currentColor`,不加渐变/阴影/纹理/3D。保留有意的填充、状态点、选中标记与镂空。
16
+ - 平衡结构与留白,不强求对称;避免意外倾斜或头重脚轻。保留含义方向。用间隙、重叠、嵌套与被遮挡的断线厘清复杂含义;避免意外相切、暗结与在实际尺寸下消失的间隙。仅当能提升识别度才加轮廓细节;不必把每个对象都塞进闭合轮廓。
17
+
18
+ ## 光学尺寸与清晰度先行
19
+
20
+ 用所属控件支持的尺寸与粗细。改共享 view-box 会按各自 CSS 尺寸影响所有消费方;紧凑菜单与更大的图标按钮都要看,小号 chevron 调清晰后可能在浮动按钮里过大。必要时调消费方的图标尺寸,但保留按钮基座与 hit target。
21
+
22
+ 柔和度排查:CSS 尺寸与祖先 transform → view box 与绘制边界 → 描边 vs 填充轮廓 → 设备像素位置 → 颜色/透明度。非 16 的 view box 合法;比较相同图形后再把清晰度归因于 inline SVG vs sprite。
23
+
24
+ 描边缩放:源描边宽度随 SVG viewport 缩放、填充轮廓按几何缩放;普通放置/复用修复不要加非缩放描边或把填充轮廓转描边——那属于独立的库改动,需消费方验证。
25
+
26
+ 缩放后在实际 DPR 下检查直边:中心与宽度共同决定覆盖,整数源坐标不保证边缘清晰。仅当布局把原本清晰的图形夹在像素之间时,才按设备像素取整定位覆盖层,保留锚定与 viewport 包含。曲线/对角线保持抗锯齿;不要全局 round path 或用 `crispEdges` 掩盖放置错误。1.3px 描边的部分覆盖是合理的。
27
+
28
+ ## 画新图标
29
+
30
+ 先确定含义、位置、实际尺寸、同辈与状态;仅在信息缺失会改变设计时才问。产出可编辑 SVG;共享线图标需要 Regular 与 Medium 两变体共享构造,纯填充变体可共享几何。用组件/主题约定在目标尺寸下调轮廓、间隙、中心与粗细,不用消费方专属的 stroke/scale 覆盖。
31
+
32
+ 交付可编辑图形 + 渲染后的同辈对比(含标签或控件)。说明语义选择与未解决的替代。草稿留本地;落地时注册可复用组件并更新文档。区分「评审中提案」与「已审批字形」。
33
+
34
+ ## 规范化用户素材
35
+
36
+ 改动用户素材前,先确定其含义、可识别特征与预期用途。保留原形与可识别形式;有等价样例时作为参照展示,但不拿它顶替用户要求规范化的那幅画。把技术修复(画布、比例、描边、颜色继承、位置)与轮廓/隐喻改动分开;指出必要的简化。
37
+
38
+ 用与新建图形相同的系统风格与验证标准。检查 SVG path、transform、fill、stroke 与引用。重建位图参照时不要描摹光栅化/压缩伪影;标注演绎出的细节,不可恢复的定义性特征要问。交付可编辑 SVG 与「原图/规范化/同辈」在相同条件下的目标尺寸对比。图形改动与消费方布局修复分开。
39
+
40
+ ## 放置与使用
41
+
42
+ 区分点击目标、可见按钮基座、图标槽与绘制字形。目标/SVG 尺寸相等不等于光学尺寸相等;在标签旁比较轮廓、描边、留白与中心。先修容器与意外 CSS 覆盖;仅当失衡跨用法都随该字形时才修共享图形。
43
+
44
+ 图标与其关联文本(同一动作/值/输入提示)必须共享前景色、有效透明度与状态变化,含子菜单值 chevron 与搜索占位符;继承共享角色,不要另设独立图标 token。文本与独立清除操作可不同;状态/警告/品牌角色保留语义色。两主题都查计算后的颜色与祖先透明度。规则只约束改到的消费方;更新它不认证未动的 UI。
45
+
46
+ ## 图标控件与交互
47
+
48
+ 图标义不清的 icon-only 操作配 Tooltip,需 hover/选择的说明性内容配 HoverCard;优先用这些原语而非零散 `title` 属性。保留可访问标签与焦点。
49
+
50
+ ## 验证与交接
51
+
52
+ 普通图标复用/放置改动:在实际尺寸与相关状态检查受影响控件,无需固定尺寸/DPR 矩阵或单独栅格报告。新建/改动图形、描边或渲染:与同辈比较受影响尺寸与粗细;描边缩放或像素位置可能变化时查 DPR 1 与 2,颜色或光学粗细受影响时查两主题。需要时保留前后截图。
53
+
54
+ 集合级改动后,追踪受影响家族、消费方与粗细,包括渲染可能改变的未动图形;用未动的同辈作参照。显式要求的全集评审在匹配条件下盘点并比较每个字形。仅为当前修复必要时才合并重复图形;无关的重复单独记录,不扩大任务。不确定的判断查案例。
@@ -0,0 +1,52 @@
1
+ # UI 响应式与移动端
2
+
3
+ 在 [UI 开发循环](../SKILL.md#required-review-loop) 内套用。对比整页/模态里的换行与布局关系,保留草稿、焦点与操作可达。只「塞进视口」不等于达标。
4
+
5
+ ## 1. 最小视口
6
+
7
+ 以 390 CSS px 宽为主要验收下限:无意外重叠、裁切、页面级横向滚动,主操作不可达。低于 390px 可放宽。
8
+
9
+ ## 2. 决策顺序
10
+
11
+ 1. 先调整空间分配或换行;再考虑截断、icon-only、把图标挪进「更多」菜单。
12
+ 2. 主操作与主状态不可省略。
13
+ 3. 不要用全局裁切、缩小所有字号、或缩小点击目标来掩盖冲突。
14
+ 4. 仅在产品设计明确要求时才缩小字号。
15
+
16
+ ## 3. 文本截断
17
+
18
+ 1. 截断内容必须在二级页面或菜单里完整可取。
19
+ 2. 截断不得丢错误或关键信息。
20
+ 3. 标签导航、可见选择器、按钮、tag 等优先单行截断。
21
+ 4. 别处取不到的重要信息必须完整显示、不截断。
22
+
23
+ ## 4. 标题
24
+
25
+ 1. 页面标题优先完整显示,必要时把操作区换到另一行。
26
+ 2. 卡片标题优先自然换行;若限制行数,完整标题仍要可查看。
27
+
28
+ ## 5. icon-only 控件
29
+
30
+ 1. 降为纯图标需同时满足:图标含义清晰(或操作用户熟悉)+ hover 出 tooltip。
31
+ 2. 导航到独立页面的入口不要降成图标。
32
+
33
+ ## 6. 移动端 hover 行为
34
+
35
+ 1. hover 效果放在 `@media (hover: hover)` 下(与视口宽度无关);JS hover 处理器在混合输入设备上忽略 touch 事件。
36
+ 2. 手机上点按不得留下仅供 hover 的背景/高亮/操作可见性;无 hover 时操作仍可见或经显式控件可达;键盘用户可达同一操作。
37
+ 3. 保留正常的选中/展开/启用/按下态与焦点指示,与 hover 能力无关;不要为了消除 hover 效果而清焦点(`:focus-visible` 也适用于 touch 聚焦的输入框)。
38
+ 4. 宽度变化期间控件仍可见可交互时保留焦点;避免仅为改布局而重挂载控件;若焦点控件被隐藏/移除,把焦点移到合适的剩余控件,且不要无故弹起移动键盘。
39
+
40
+ ## 7. 移动端 tooltip
41
+
42
+ 1. 只提供辅助信息(操作名、快捷键)的 tooltip 在移动端不显示;点按仍直接执行原操作。
43
+ 2. 提供补充说明的 tooltip 在移动端支持点按显示。
44
+
45
+ ## 8. 移动端键盘
46
+
47
+ 非明确意图时,不要自动弹起输入键盘。
48
+
49
+ ## 9. 输入能力与移动输入框
50
+
51
+ 1. 呈现层优先用 CSS 媒体特性:`(pointer: coarse)` 表主指针精度、`(hover: none)` 表不可 hover、宽度查询选布局断点;这些查询检测不到物理键盘;绝不靠解析 UA 分支布局。
52
+ 2. 输入框在 `(pointer: coarse)` 下取 16px 下限以避免 iOS Safari 聚焦缩放;细指针保持现有紧凑尺寸。
@@ -0,0 +1,17 @@
1
+ # UI 间距与分组
2
+
3
+ 在 [UI 开发循环](../SKILL.md#required-review-loop) 内套用。间距应说明哪些文本、输入与操作属于一组。
4
+
5
+ ### 先定分组,再定间距
6
+
7
+ 按「一个对象/动作/重复单元」分组,而不是 DOM 兄弟、背景或组件树。定位前先陈述这种关系。每个嵌套层级独立检查;更大的外层间距不等于更大的内层间距。
8
+
9
+ 例如:标题+描述是一节;三个会话操作是一个操作组;成员卡片是一节、与任务分开。表单里复选框+标签是选项,选项构成字段,字段构成表单,表单构成列表——逐层检查关系,而非到处套同一间距。
10
+
11
+ 无显式分隔时,可比的相邻组之间要明显大于组内。相等只是防「倒置」的下界。重复构图共享间距/padding/对齐;标签长度不成为加无关间距的理由。
12
+
13
+ 换行、元数据、子组或独立操作增多时,加大包围间距以保住分组。紧凑图标/标签对与多行卡片节需要不同档位。不要从卡片面积推导间距、也不要处处乘 margin。分隔与不同表面可强化分隔,但标题必须比前一组更贴近自己的内容。
14
+
15
+ 在正常字号下判断真实留白,含 padding、行高、字形留白与边框。CSS margin 比例本身不证明分组。匹配两个可见间距时,给两对端点都命名,并计入各自容器的 padding、边框与文本行盒;可见间距相等可能需要不相等的 margin。控件绘制边与文本字形边是不同端点,整个评审保持一致。
16
+
17
+ 复用页面间距与样式 token,保持[对齐](alignment.md)轴,不确定的判断查案例。本技能不定义数值刻度。
@@ -0,0 +1,36 @@
1
+ # AGENTS.md — 文档规范
2
+
3
+ 本文档定义文档的结构、层级归属与写作规则,适用于面向人的文档。决策记录([`.agents/notes/`](../.agents/notes/README.md))遵循其自身规则,不在本规范范围内。
4
+
5
+ ## 文档结构
6
+
7
+ 把每篇文档归为 **教程(tutorial)** 或 **参考(reference)**:
8
+
9
+ - **教程**:按顺序带读者走向一个结果,只引入每一步所需的内容。
10
+ - **参考**:定义查证范围与当前行为,不承载教学顺序。
11
+
12
+ 写作顺序:先定文档在树里的位置 → 确定允许的详略 → 选教程或参考 →(教程)按前置依赖与难度排序概念 → 把属于下级的细节挪走 → 用链接取代低层解释。
13
+
14
+ ## 一个事实一个家
15
+
16
+ 每个事实只有一个归属——其职责所属的层级;别处只链接,不重复。
17
+
18
+ | 层级 | 职责 | 不该放 |
19
+ |---|---|---|
20
+ | 根 `AGENTS.md` / `CLAUDE.md` | 常驻规则:每会话都要有,每条 1–3 行,链接到归属 | 故事、示例、情境流程、从别处复述的内容 |
21
+ | 子树 `AGENTS.md` | 该子树专属规则 | 根文件已承载的仓库级规则 |
22
+ | [`architecture.md`](architecture.md) | 架构现状:组成、分层、运行时词汇、扩展点(是什么) | 类型定义(→ 模块/包文档)、决策理由(→ 决策记录)、实现状态注记 |
23
+ | [`design.md`](design.md) | UI 设计现状与规格 | 设计决策理由(→ 决策记录)、原始设计稿(→ `docs/design/`) |
24
+ | [`glossary.md`](glossary.md) | 核心术语的唯一定义 | 术语背后的决策理由(→ 决策记录) |
25
+ | [`contracts.md`](contracts.md) | 前后端数据契约:DTO/枚举与 TS 接口的一一对应 | 契约背后的决策理由(→ 决策记录) |
26
+ | [`.agents/notes/`](../.agents/notes/README.md) | 决策记录:为什么、放弃了什么(`implemented/` 用现在时写现状) | 迁移计划、验收清单、已落地后的 spec 式语气;归档记录是冻结历史 |
27
+ | 包/模块 README | 该包契约:配置、语义、限制、扩展点 | JSDoc 复述、别包的事 |
28
+
29
+ 归属规则:缺陷复盘 → 复盘文档;决策理由 → 决策记录;操作步骤 → 教程/如何做;类型定义 → 模块文档;包契约 → README;常驻规则 → 根 `AGENTS.md`;评审强制规则 → 各自的规则文件。
30
+
31
+ ## 写作规则
32
+
33
+ - **只写现状。** 历史留在 commit、PR、决策记录或复盘里;其余文档写当前机制,不写变更经过或临时状态。
34
+ - **中文书写。** 术语首次出现可附英文原名;机器校验的 token 按各自契约保留。
35
+ - **一句话说清职责**,避免空话与重复。
36
+ - **事实与理由分离**:文档写「是什么」,决策记录写「为什么」。
@@ -0,0 +1,33 @@
1
+ # 架构
2
+
3
+ > 本文档描述本项目的**当前架构(现状)**,回答「是什么」。
4
+ > 配套的决策记录在 [`.agents/notes/implemented/architecture/`](../.agents/notes/implemented/architecture/) 里,回答「为什么这样定、放弃了什么」。
5
+ > 改结构前先读这里;改出一个结构性决定时,在 `architecture/` 写一篇决策记录,并同步更新本文档的现状。
6
+
7
+ ## 仓库布局
8
+
9
+ (在此描述顶层目录 / 包 / 模块的职责,一句话一个。)
10
+
11
+ ## 分层
12
+
13
+ (代码如何分层,各层职责与依赖方向:例如上层可依赖下层、反之禁止。)
14
+
15
+ ## 运行时词汇
16
+
17
+ (核心术语的唯一定义放 [glossary.md](glossary.md),此处只列与本架构强相关的关键概念,或直接链接过去。)
18
+
19
+ ## 模块与依赖
20
+
21
+ (主要模块及其依赖关系,说明边界与禁止的依赖方向。)
22
+
23
+ ## 扩展点
24
+
25
+ (哪里允许扩展、如何扩展、谁负责注册。)
26
+
27
+ ## 边界与不变量
28
+
29
+ (硬边界、不可破坏的不变量、失败如何体现。)
30
+
31
+ ## 关键决策索引
32
+
33
+ (链接到 `.agents/notes/` 里对应分类的决策记录,按需罗列。)
@@ -0,0 +1,22 @@
1
+ # 前后端数据契约
2
+
3
+ > 前后端字段对齐的唯一事实来源。后端 DTO / 枚举 与前端 TS interface / 枚举 必须在此一一对应;
4
+ > 改动任何一侧都要同步更新本文档,reviewer 也对照这里检查。
5
+
6
+ ## 通用约定
7
+
8
+ (命名、空值、时间格式、枚举值、错误码等全局约定。)
9
+
10
+ ## <领域 / 模块 A>
11
+
12
+ ### 后端
13
+
14
+ (DTO / VO / 枚举定义,或链接到实现处。)
15
+
16
+ ### 前端
17
+
18
+ (TS interface / type / 枚举。)
19
+
20
+ ### 差异与注意
21
+
22
+ (字段映射、命名不一致处、可空性差异。)
@@ -0,0 +1,7 @@
1
+ # 设计稿
2
+
3
+ 存放 UI 设计稿:线框、视觉稿、截图、交互稿。规格与索引在 [`../design.md`](../design.md),这里放原始文件。
4
+
5
+ - 命名建议:`{功能}-{版本}-{状态}.{png,svg,fig}`,状态用 `draft` / `review` / `approved`。
6
+ - 注明更新日期与对应的代码版本/commit。
7
+ - 二进制文件遵循仓库的大小与托管约定;大文件可改存外部链接,在此留链接与摘要。
@@ -0,0 +1,30 @@
1
+ # UI 设计
2
+
3
+ > 本文档描述项目的 UI 设计现状与规格(是什么)。配套:
4
+ > - [ui-ux 技能](../.agents/skills/ui-ux/SKILL.md) 是设计与评审的流程与规则(怎么做);
5
+ > - 决策记录([`feature/`](../.agents/notes/implemented/feature/) 与 [`architecture/`](../.agents/notes/implemented/architecture/))承载 UI/交互决策的理由(为什么)。
6
+ > 原始设计稿(线框、视觉稿、截图)放 [`docs/design/`](design/),本文档只做规格陈述与索引。
7
+
8
+ ## 设计原则
9
+
10
+ (视觉与交互的核心原则,几条即可。)
11
+
12
+ ## 视觉令牌
13
+
14
+ (颜色、字号、间距、圆角、阴影等 token 的定义,或链接到实现处。)
15
+
16
+ ## 组件规格
17
+
18
+ (关键组件的角色、状态、尺寸变体。)
19
+
20
+ ## 交互规格
21
+
22
+ (关键交互流程、反馈、加载态、错误态。)
23
+
24
+ ## 设计稿索引
25
+
26
+ (链接到 `docs/design/` 下的设计稿,注明版本与状态。)
27
+
28
+ ## 评审记录
29
+
30
+ (或链接到评审清单/记录;涉及面广的改动按 ui-ux 技能走设计评审。)
@@ -0,0 +1,11 @@
1
+ # 术语表
2
+
3
+ > 集中定义项目里反复出现的核心概念,消除同名异义。架构文档([architecture.md](architecture.md))的「运行时词汇」小节链接到这里;每个术语只在此定义一次。
4
+
5
+ ## <术语 A>
6
+
7
+ (一句话精确定义;必要时给出边界与反例。)
8
+
9
+ ## <术语 B>
10
+
11
+ (……)