Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/skills-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
".agents/skills/sweet-mode": {
"repo": "https://github.com/SweetRetry/retry-kit",
"path": "skills/web-design/sweet-mode",
"commit": "4b750407f344128a22d4b28acdc7c619e3ffdd04",
"hash": "030f7311e814f696265e4747f09804177e7b7c011c845b542f69c74e8ac2c010"
"commit": "5d0f1baebee1daa8e1e97ff959710f33a8129dc2",
"hash": "bfff01710c808c827311f461219a47ced028fe43e326362e022f5bd84203e25e"
}
}
42 changes: 23 additions & 19 deletions .agents/skills/sweet-mode/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
name: sweet-mode
description: Tailwind + shadcn/ui 界面规范:层级、布局、表面、字体、尺寸稳定、交互反馈与动效的取值、禁令与验收,附禁令扫描脚本。编写或修改界面时作为硬约束落地。仅供用户显式调用。
description: Tailwind + shadcn/ui 界面规范:层级、布局、表面、字体、尺寸稳定、交互反馈与动效的取值、禁令与验收,附禁令扫描与渲染检查脚本。编写或修改界面时作为硬约束落地。仅供用户显式调用。
disable-model-invocation: true
---

# Sweet Mode

`reference/` 中的类名、Token、阈值与禁令是硬约束;未覆盖的取值沿用项目同类界面的做法。
`reference/` 中的类名、Token、阈值与禁令是硬约束。

让布局解释界面:想加说明、副标题或辅助标签时,先改分组、顺序、控件或命名,结构表达不了的信息才写成文字。

Expand All @@ -15,35 +15,39 @@ disable-model-invocation: true
reference 中的 `globals.css`、`packages/ui` 指目标项目里的对应位置。先找到:

- 样式入口:定义颜色、圆角、字号与字体族 Token 的文件。阶梯以它为准,reference 表格里的 px 值只是缺省;缺少语义 Token 时在这里补,业务代码只消费语义名。
- 组件外观归属(`packages/ui` 或 `components/ui`):圆角、表面、按压反馈等外观改在变体里,调用点只负责布局。
- 同类先例:写控件、确认、加载与报错反馈、空状态、页头或界面文案前,先在项目里搜同类既有实现并沿用;同一对象用已有的名称。只有语义不同才新增变体,变体收进组件库,不在调用点覆盖外观。
- 组件库(`packages/ui` 或 `components/ui`):圆角、表面、按压反馈等外观改在变体里,调用点只负责布局。改动用到的组件先对照下表,未达标的在变体里改,再写调用点:

## 2. 按改动读取规则
| 组件 | 基线 |
| --- | --- |
| Button | `motion-safe:active:scale-95`,`duration-150 ease-out`,过渡只列颜色与 `transform` |
| Card | 无阴影;`card` 与 `background` 有明度差时无边框,同色时用低对比边框 |
| Skeleton | `bg-muted` |
| Sheet | 缓动 `cubic-bezier(0.32, 0.72, 0, 1)`,时长取 200–500ms 中偏短 |
| Popover / DropdownMenu / Tooltip | 从触发控件方向展开(`origin-(--radix-*-content-transform-origin)`) |

新建页面或重组信息时先读 `hierarchy.md`,定好主次与收纳再选组件和样式。其余按触及内容读取,可命中多行:
## 2. 读取规则

| 涉及内容 | Reference |
| --- | --- |
| 信息取舍、主次焦点、首屏呈现、折叠与浮层载体、菜单与导航等容器内的归属与排序 | [hierarchy.md](reference/hierarchy.md) |
| 间距、对齐、宽度、栅格与分区边界 | [layout.md](reference/layout.md) |
| 颜色 Token 与配比、表面高度、圆角、z-index 与 Portal | [surface.md](reference/surface.md) |
| 字号、字重、字体族、数字字形与字体渲染 | [typography.md](reference/typography.md) |
| 加载占位、卡片等高、空值、长文本溢出与退出过渡期间的内容稳定 | [stability.md](reference/stability.md) |
| 错误与结果反馈、toast、等待与取消、防重与竞态 | [interaction.md](reference/interaction.md) |
| 过渡与动画、按压缩放、时长与缓动、减少动态效果 | [motion.md](reference/motion.md) |
开工前读完 `reference/` 全部 8 个文件:规则跨文件交叉,一个带删除弹窗的表格同时受层级、字形、稳定与交互约束。新建页面或重组信息时先按 `hierarchy.md` 定主次与披露层次,再选组件和样式。

只改当前任务触及的范围,范围外的违规列入交付。

## 3. 验收

已读 reference 的每个小节都是完成标准,逐节给出通过、修复或不适用。
reference 的每个小节都是完成标准,逐节给出通过、修复或不适用。

1. 运行脚本扫描无判断余地的禁令,修复到改动文件不再出现在输出中:
1. 静态扫描,修复到改动文件不再出现在输出中:

```bash
node <skill 目录>/scripts/ui-guardrails.js <目标项目路径>
```

脚本跳过组件库(`packages/ui/`、`components/ui/`)、第三方、测试与 skill 目录。组件库内的改动,以及任意圆角与间距、内联 style 与 CSS 中的色值,人工核对。
2. 在运行界面检查依赖渲染的项:`hierarchy.md` 的检验、窄屏重排、加载/空值/报错三态、收起与展开两态、键盘操作与减少动态效果。无法运行界面时,标明哪些只做了代码层检查。
脚本跳过组件库、第三方、测试与 skill 目录;组件库的外观按 §1 基线表核对。任意圆角与间距、内联 style 与 CSS 中的色值人工核对。
2. 渲染检查。启动开发服务器,打开改动页面,在 375×812 与 1280×800 两个视口各做一遍:
- 用浏览器工具的 evaluate 执行 `scripts/render-audit.js`(整个文件是一个无参函数),修复到 `violations` 为空。
- 截整页图并查看,按 `hierarchy.md` §4 逐项判断。
- 触发加载、空值、报错三态与收起、展开两态,用键盘走完主流程,开启减少动态效果再看一遍。

启动受阻时先排除可修复的原因:依赖、端口、环境变量;缺后端或登录时用临时 mock 渲染改动页面,交付前移除。仍无法运行时,渲染检查记为未通过,交付失败的命令与报错。

交付改动位置、各小节结论、范围外的违规与未验证项。
交付改动位置、各小节结论、两个视口的 audit 输出与截图路径、范围外的违规。
4 changes: 2 additions & 2 deletions .agents/skills/sweet-mode/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
interface:
display_name: "Sweet Mode"
short_description: "Tailwind + shadcn/ui 界面规范:取值、禁令、验收与扫描脚本"
default_prompt: "使用 $sweet-mode 按界面实现规范编写或修改当前界面,按改动读取 reference,逐节给出验收结论并交付。"
short_description: "Tailwind + shadcn/ui 界面规范:取值、禁令、验收与检查脚本"
default_prompt: "使用 $sweet-mode 按界面实现规范编写或修改当前界面,读完全部 reference,逐节给出验收结论,跑完静态扫描与渲染检查后交付。"

policy:
allow_implicit_invocation: false
43 changes: 23 additions & 20 deletions .agents/skills/sweet-mode/reference/hierarchy.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,49 @@
# 信息层级与收纳
# 信息层级与渐进式披露

先理清信息关系,再选组件承载。

## 1. 6:3:1 注意力分配
## 1. Canvas 与 Chrome

视区的内容与空间按 60% 主体、30% 辅助、10% 焦点分配:
压缩 Chrome,把视区留给 Canvas 与焦点:

- **60% 主体**:用户此刻处理的工作对象(流程的当前步骤、看板的数据、工具里的作品)与画布的大块留白。对象越需要专注,其余层越让位。
- **30% 辅助**:导航、筛选、上下文属性,以及卡片内边距与组内间距。
- **10% 焦点**:推进任务的主操作或偏离常态的状态,连同隔离它的留白。单线流程只留一个推进主操作。

默认构图如下;偏离时须说明该元素直接表达任务关系、移除会损害理解或操作:
- **Canvas**:用户此刻处理的工作对象(流程的当前步骤、看板的数据、工具里的作品)与它的大块留白。对象越需要专注,Chrome 越让位。
- **Chrome**:导航、筛选、工具栏与上下文属性,取完成任务所需的最小体量。
- **焦点**:推进任务的主操作或偏离常态的状态,连同隔离它的留白。单线流程只留一个推进主操作;主操作归属当前步骤尚未完成的目标动作(收集输入时在底栏提交键,交付结果供取用时在内容区的取用动作而非底栏关闭键)。

- **列表靠留白分组**:用留白、共享左对齐轴与 `space-y-*` 组织。Card 只给语义、结构和操作同级的对象,卡片不套卡片。
- **元数据安静**:`text-xs text-muted-foreground`;Badge 只给强状态或核心分类。
- **一个字段一个位置**:不用 `·`、`•`、`|`、`/` 把多个字段拼成一行,标题里也不拼状态。每个字段先按「每条信息有增量」定去留,留下的各占结构位置:分组、对齐的列或行尾、图标、Badge。
- **权重决定大小**:主导指标单独放大,次要指标紧凑排列。
- **装饰承载语义**:渐变文字、光晕、纹理、彩色图标底色只在传达状态、可供性或空间关系时出现(如模糊透出下方滚动的内容)。
- **平涂表面**:表面只用 Token 色平涂,层次靠明度差。不用渐变文字、彩色渐变、光晕、纹理与玻璃卡片。渐变只做两件事:压在图片与视频上托住文字和按钮的遮罩,滚动边缘的淡出;色标只取 `transparent`、`black` / `white` 透明度或表面 Token。模糊只用 `backdrop-blur-*` 透出下方滚动的内容。
- **每个元素有真实承接**:元素来自需求与现有产品,并接上真实数据源或事件逻辑。不渲染假搜索框、通知铃、装饰头像菜单、空链接、页头凑数统计卡与没有历史基线的涨跌百分比;列表预期不超过一屏(≤ 7 项)且无服务端过滤时,不放搜索框、筛选器与分页器。
- **标题自明不写描述**:CardTitle、DialogTitle 或区块标题已交代工作对象时,不补 CardDescription 或副标题重述;说明文字只写不写就会引发误操作的业务约束。
- **宽表优先**:数据表格享有最高水平空间优先级,横向滚动或全宽,不为旁侧内容压缩列宽。
- **每条信息有增量**:每句文字、数字与标签都是一条陈述。用户从界面已能得到的(标题含义、可见项数量、控件已表达的状态)和不影响任何判断或操作的(其他角色的权限、系统内部归属)删除;有用但不满足 §2 判据的收纳。字号与颜色不改变一条信息是否多余。
- **每条信息有增量**:每句文字、数字与标签都是一条陈述。用户从界面已能得到的(标题含义、可见项数量、控件已表达的状态)和不影响任何判断或操作的(其他角色的权限、系统内部归属)删除;有用但不满足 §2 判据的延后披露。字号与颜色不改变一条信息是否多余。

## 2. 直接呈现与收纳
## 2. 渐进式披露(Progressive Disclosure)

以当前场景的用户任务为单位,满足任一条直接呈现,其余收纳:
以当前场景的用户任务为单位,满足任一条直接呈现,其余延后披露:

1. **影响此刻决定**:缺少会判断错误或阻断流程(代价、不可逆后果、禁用原因、报错、立即生效还是异步)。原因未知时写明未知,不补造诊断。
2. **需要并排比较**。
3. **当前任务的高频主操作**。

收纳载体由四个问题推出:
披露载体由四个问题推出:

1. 保留当前上下文 → 就地展开或锚定浮层;脱离且须专注 → 模态或独立页。
2. 临时查看 → 易关闭的浮层;持续使用 → 留在内容流(折叠区、分段切换、侧栏)。
3. 纯解释 → 最轻的提示;含输入或选择 → 可聚焦、可键盘操作的载体。
4. 互斥 → 同一时间只显示一个分支;并列 → 分组后折叠次要组。

常见结果:Popover / DropdownMenu(保留上下文、临时、含交互);Tabs / ToggleGroup / Accordion(保留上下文、持续或互斥);Dialog / Sheet(脱离、须专注);独立路由(需深链或分享)。推不出时沿用应用内同类场景的处理,同类内容全应用一种收纳方式。
常见结果:Popover / DropdownMenu(保留上下文、临时、含交互);Tabs / ToggleGroup / Accordion(保留上下文、持续或互斥);Dialog / Sheet(脱离、须专注);独立路由(需深链或分享)。推不出时沿用应用内同类场景的处理,同类内容全应用一种披露方式。

收纳边界:
披露边界:

- 只有一两个次要操作,或收纳后入口比原内容更难懂时,直接呈现。
- 只有一两个次要操作,或折叠后入口比原内容更难懂时,直接呈现。
- 表格行只留识别与判断所需的列和主操作,其余操作进尾部溢出菜单,详情进抽屉或详情页。
- 专业工具与设置的高频项一次点击可达,危险设置直接可见。
- 悬停只做增强:后果、禁用原因、报错与操作都有不依赖悬停的可见入口,触屏与键盘可达。
- 收纳入口是带可访问名称的图标或带状态的标签,不依赖隐藏手势。
- 披露入口是带可访问名称的图标或带状态的标签,不依赖隐藏手势。
- 浮层不嵌套浮层;二级内容改为模态内分步或锚定浮层。
- 展开后的内容不推翻用户基于收起态已做出的判断。

Expand All @@ -58,8 +59,10 @@

## 4. 检验

- **眯眼**:模糊细节后,首要焦点、分组与阅读路径仍清楚,无等权区块混战。
- **移除**:逐项移除卡片、边框、背景、图标、颜色与动效,不损失含义或可供性的不恢复。
- **缩略图**:整页截图缩到约 400px 宽查看,首要焦点、分组与阅读路径仍清楚,无等权区块混战。
- **Data-ink ratio**:逐项移除卡片、边框、背景、图标、颜色与动效,不损失信息或意符(signifier)的不恢复。
- **最小惊讶**:每个操作前只凭文案、图标与位置预测结果,再实际操作;结果与预测一致,没有未声明的跳转、清空或提交。
- **一致**:同一对象在全应用只用一个名称;同类操作、确认方式、反馈形态、空状态与同级控件尺寸与项目已有界面相同。差异只用来表达语义差异,没有语义的差异改成既有做法。
- **同级**:重复结构的对象语义、结构与操作相同;不等价对象已用排序、分组、占比或密度区分;同级图表共享基准轴,面积与数值线性对应。
- **移植**:只换文案后,组织方式能直接套给无关业务,说明构图由模板主导,按内容重做。
- **窄屏**:靠重排保持层级与操作,不截断关键内容、不缩小正文。
- **窄屏**:375px 截图中靠重排保持层级与操作,关键内容完整,正文字号不变。
46 changes: 46 additions & 0 deletions .agents/skills/sweet-mode/reference/icon.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# 图标

图标替代或锚定文字,不做装饰。先定这个位置要不要图标,再定用图标库还是自绘。

## 1. 图标还是文字

判据:去掉图标后,用户是否找得更慢、认错对象或漏看状态。三者都不会时用纯文字。

图标只出现在:

- **纯图标按钮**(`size="icon*"`):含义跨产品通用的动作(关闭、搜索、更多、复制、展开、拖拽),带 `aria-label` 与 Tooltip。要想一下才对得上的动作改用文字按钮。
- **扫视锚点**:导航、菜单、工具栏中需要扫视定位的同级条目,图标作文字前缀,同组全有或全无。
- **状态**:偏离常态、需要在扫视中被捕捉的状态(报错、警告、离线、同步中),图标与文字并用,不只靠颜色区分。
- **对象类型**:列表混排多种对象(文件格式、渠道、集成)时,图标区分类型。
- **业务空态**:主工作区空态的插图,按 §3 自绘。

其余位置用纯文字:

- 页面标题、CardTitle、DialogTitle、纯文字 Tab。
- 动词已说清含义的文字按钮(保存、取消、提交、确认)。
- 没有约定图形的抽象概念(权限策略、计费周期、审批规则)。要在多个候选里挑一个「大概像」的隐喻图标时,说明没有约定图形,用文字。

图标不重复相邻文字已说清的含义,不放进彩色圆形或方块底色。

## 2. 图标库

- 沿用项目已安装的图标库;未安装时用 `lucide-react`(shadcn 的 `components.json` 中 `iconLibrary` 的默认值)。lucide 缺少所需图形或需要多档字重时改用 Phosphor(`@phosphor-icons/react`)。一个项目只用一个图标库,品牌 Logo 除外。
- 全应用一种笔画:lucide 统一 `strokeWidth`,Phosphor 统一一档 `weight`;只有选中态可切到实心变体。
- 颜色继承 `currentColor`,随文字 Token 变化;状态图标用语义 Token(`text-destructive`)。
- 尺寸跟随相邻文字:`text-sm` 配 `size-4`,`text-xs` 配 `size-3.5`。组件库变体已统一 svg 尺寸时,调用点不再写尺寸。
- 旁边有文字的图标加 `aria-hidden`;纯图标按钮的可访问名称写在按钮上。

## 3. 自绘 SVG

库图标只能表达泛化类别(收件箱、文件、文件夹),含义却取决于业务对象的结构或状态时,自绘 SVG:

- **业务空态**:画出该对象在本产品里的空形态,如没有节点的流程画布、没有卡片的看板列、没有阶段的流水线,让用户认出「这里将出现什么」。放大的库图标与通用插画(空盒子、云朵、人物)做不到这一点,不用。
- **领域图标**:高频出现、作为扫视锚点、库里没有对应图形的领域对象,自绘一枚图标。

取形与画法:

- 从界面里该对象的真实构成取形(节点与连线、行与列、卡片轮廓),做简化,不找隐喻。验收:遮住相邻文字,熟悉产品的用户仍能说出它指哪个对象。
- 领域图标与图标库同网格:`viewBox="0 0 24 24"`,四周留 2 单位,描边宽与库一致,`stroke-linecap="round"`、`stroke-linejoin="round"`、`fill="none"`;与相邻库图标并排截图比对视重。
- 空态插图是单色线稿:`stroke="currentColor"` 配 `text-muted-foreground`,至多一个强调元素用 `text-primary`;路径加 `vector-effect="non-scaling-stroke"`,放大后笔画仍与图标库同宽;宽度 `w-24`–`w-40`,置于空态标题上方,每个空态一幅。不用渐变、阴影、纹理与多色填充。
- 写成项目内的组件(与其他图标同目录),插图加 `aria-hidden`,含义由相邻标题承担。
- 卡片、侧栏、弹窗内的子列表空态不加插图。
3 changes: 2 additions & 1 deletion .agents/skills/sweet-mode/reference/interaction.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

## 2. 等待与恢复

结果可撤销且极少失败 → 先呈现结果,失败时回滚到真实状态并就近说明,不以刷新代替恢复。不可逆或常失败 → 等服务端确认,反馈放在触发控件上。
结果可撤销且极少失败 → 乐观更新(optimistic update):先按成功渲染,提交前保存快照,失败时回滚并就近说明,不以刷新代替恢复。不可逆或常失败 → 悲观更新(pessimistic update):等服务端确认再变更界面,反馈放在触发控件上。

| 等待时长 | 反馈 |
| :--- | :--- |
Expand All @@ -27,3 +27,4 @@
- **竞态**:切换、分页、筛选时丢弃不属于最新意图的响应。
- **保留输入**:提交、校验或网络失败后保留已填内容与选项。
- **不可逆**:在不可逆时点前确认影响范围,或提供有效撤销。
- **破坏性操作隔离**:不与正向主按钮紧挨并列。弹窗与表单底部正向主按钮在端侧,破坏性按钮取弱样式并拉开间距;菜单中破坏性条目置于最底部,用 `DropdownMenuSeparator` 隔开并取 `variant="destructive"`。
Loading
Loading