diff --git a/.agents/skills/skills-lock.json b/.agents/skills/skills-lock.json index b74ce44..b24c84c 100644 --- a/.agents/skills/skills-lock.json +++ b/.agents/skills/skills-lock.json @@ -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" } } diff --git a/.agents/skills/sweet-mode/SKILL.md b/.agents/skills/sweet-mode/SKILL.md index f5ab887..a3123f1 100644 --- a/.agents/skills/sweet-mode/SKILL.md +++ b/.agents/skills/sweet-mode/SKILL.md @@ -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、阈值与禁令是硬约束。 让布局解释界面:想加说明、副标题或辅助标签时,先改分组、顺序、控件或命名,结构表达不了的信息才写成文字。 @@ -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 /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 输出与截图路径、范围外的违规。 diff --git a/.agents/skills/sweet-mode/agents/openai.yaml b/.agents/skills/sweet-mode/agents/openai.yaml index 660f690..0b321df 100644 --- a/.agents/skills/sweet-mode/agents/openai.yaml +++ b/.agents/skills/sweet-mode/agents/openai.yaml @@ -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 diff --git a/.agents/skills/sweet-mode/reference/hierarchy.md b/.agents/skills/sweet-mode/reference/hierarchy.md index 9c15b8c..064394d 100644 --- a/.agents/skills/sweet-mode/reference/hierarchy.md +++ b/.agents/skills/sweet-mode/reference/hierarchy.md @@ -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(脱离、须专注);独立路由(需深链或分享)。推不出时沿用应用内同类场景的处理,同类内容全应用一种披露方式。 -收纳边界: +披露边界: -- 只有一两个次要操作,或收纳后入口比原内容更难懂时,直接呈现。 +- 只有一两个次要操作,或折叠后入口比原内容更难懂时,直接呈现。 - 表格行只留识别与判断所需的列和主操作,其余操作进尾部溢出菜单,详情进抽屉或详情页。 - 专业工具与设置的高频项一次点击可达,危险设置直接可见。 - 悬停只做增强:后果、禁用原因、报错与操作都有不依赖悬停的可见入口,触屏与键盘可达。 -- 收纳入口是带可访问名称的图标或带状态的标签,不依赖隐藏手势。 +- 披露入口是带可访问名称的图标或带状态的标签,不依赖隐藏手势。 - 浮层不嵌套浮层;二级内容改为模态内分步或锚定浮层。 - 展开后的内容不推翻用户基于收起态已做出的判断。 @@ -58,8 +59,10 @@ ## 4. 检验 -- **眯眼**:模糊细节后,首要焦点、分组与阅读路径仍清楚,无等权区块混战。 -- **移除**:逐项移除卡片、边框、背景、图标、颜色与动效,不损失含义或可供性的不恢复。 +- **缩略图**:整页截图缩到约 400px 宽查看,首要焦点、分组与阅读路径仍清楚,无等权区块混战。 +- **Data-ink ratio**:逐项移除卡片、边框、背景、图标、颜色与动效,不损失信息或意符(signifier)的不恢复。 +- **最小惊讶**:每个操作前只凭文案、图标与位置预测结果,再实际操作;结果与预测一致,没有未声明的跳转、清空或提交。 +- **一致**:同一对象在全应用只用一个名称;同类操作、确认方式、反馈形态、空状态与同级控件尺寸与项目已有界面相同。差异只用来表达语义差异,没有语义的差异改成既有做法。 - **同级**:重复结构的对象语义、结构与操作相同;不等价对象已用排序、分组、占比或密度区分;同级图表共享基准轴,面积与数值线性对应。 - **移植**:只换文案后,组织方式能直接套给无关业务,说明构图由模板主导,按内容重做。 -- **窄屏**:靠重排保持层级与操作,不截断关键内容、不缩小正文。 +- **窄屏**:375px 截图中靠重排保持层级与操作,关键内容完整,正文字号不变。 diff --git a/.agents/skills/sweet-mode/reference/icon.md b/.agents/skills/sweet-mode/reference/icon.md new file mode 100644 index 0000000..cb46473 --- /dev/null +++ b/.agents/skills/sweet-mode/reference/icon.md @@ -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`,含义由相邻标题承担。 +- 卡片、侧栏、弹窗内的子列表空态不加插图。 diff --git a/.agents/skills/sweet-mode/reference/interaction.md b/.agents/skills/sweet-mode/reference/interaction.md index b790112..a2178be 100644 --- a/.agents/skills/sweet-mode/reference/interaction.md +++ b/.agents/skills/sweet-mode/reference/interaction.md @@ -14,7 +14,7 @@ ## 2. 等待与恢复 -结果可撤销且极少失败 → 先呈现结果,失败时回滚到真实状态并就近说明,不以刷新代替恢复。不可逆或常失败 → 等服务端确认,反馈放在触发控件上。 +结果可撤销且极少失败 → 乐观更新(optimistic update):先按成功渲染,提交前保存快照,失败时回滚并就近说明,不以刷新代替恢复。不可逆或常失败 → 悲观更新(pessimistic update):等服务端确认再变更界面,反馈放在触发控件上。 | 等待时长 | 反馈 | | :--- | :--- | @@ -27,3 +27,4 @@ - **竞态**:切换、分页、筛选时丢弃不属于最新意图的响应。 - **保留输入**:提交、校验或网络失败后保留已填内容与选项。 - **不可逆**:在不可逆时点前确认影响范围,或提供有效撤销。 +- **破坏性操作隔离**:不与正向主按钮紧挨并列。弹窗与表单底部正向主按钮在端侧,破坏性按钮取弱样式并拉开间距;菜单中破坏性条目置于最底部,用 `DropdownMenuSeparator` 隔开并取 `variant="destructive"`。 diff --git a/.agents/skills/sweet-mode/reference/layout.md b/.agents/skills/sweet-mode/reference/layout.md index ca30b8c..67d4aa1 100644 --- a/.agents/skills/sweet-mode/reference/layout.md +++ b/.agents/skills/sweet-mode/reference/layout.md @@ -5,7 +5,7 @@ ## 间距 - 8px 网格(`gap-2/4/6/8`);4px 只用于图标、角标等紧密关联元素。 -- 组间距至少是组内间距的 2 倍。标题上方留白大于下方;标签先与输入框成组,再排表单项间距。 +- 按接近性(Law of Proximity)分组:组间距至少是组内间距的 2 倍。标题上方留白大于下方;标签先与输入框成组,再排表单项间距。 - 新布局从较宽档位起步,在完整页面中逐档收紧,到分组清楚、阅读顺畅、主操作可达为止;高频工具与密集数据按任务密度取值。 - 兄弟间距由父容器 `gap-*` / `space-y-*` 控制,可复用组件根节点无外部 margin。`margin` 只用于 `ml-auto` 推挤、负边距通栏与长文本排版流。 @@ -29,10 +29,16 @@ 跨多列的子项在移动端默认 `col-span-12`。 +## 控件 + +- 高度由组件 `size` 变体管理:调用点不给 Button、Input、SelectTrigger 写 `h-*` 或 `py-*`;同一行并排的输入、只读值容器与操作按钮保持单行且同高(传相同 `size`,带并排按钮的只读值优先用 ``)。 +- 输入框宽度跟随预期字符数:表单容器 `max-w-*` 内,验证码、端口、金额、天数等短字段收窄到 `w-24`–`w-48`,长文本字段才占满整行。 +- 选择控件跟随选项数:2–4 个互斥短选项平铺为 RadioGroup 或 ToggleGroup;5–12 项用 Select;超过 12 项用 Combobox。 +- 单独的 Switch 切换即生效,不配保存按钮。 + ## 对齐 -- 每个区块一条主轴:标题、正文、标签、控件的起始边落在同一条线上,不混用左对齐与居中。 -- 轴线看文字与图形的实际边缘:带内边距的 ghost 按钮、列表项 hover 底色用 `-mx-*` 配 `px-*` 补偿。 +- 每个区块一条主轴:标题、正文、标签、控件的起始边落在同一条线上,不混用左对齐与居中。轴线按光学对齐取边,见下文。 - 偏离轴线须承载层级或状态(缩进、悬挂图标、居中的空态与主图),否则是缺陷。 - 图标与文字 `inline-flex items-center gap-2`;大标题伴随辅助操作用 `items-baseline`。 - 数值列的对齐见 [typography.md](typography.md#数字字形)。 @@ -40,8 +46,14 @@ ## 边界 - 分区先靠留白与共享对齐轴,再用微弱明度差,不用高对比度 1px 边框。 -- 成组列表可用 `divide-y divide-border/40`;菜单等紧凑容器留白拉不开组间距时,用分隔线标组边界。`` 不作默认分区手段。 +- 同色相邻要留缝:填充色相同且有别于底色的相邻元素(并排按钮、卡片、标签、色块、选中行)零间距相接时,按统一连接性(uniform connectedness)读成一个整体。留出 `gap-*` 就打断了连接,不必再换颜色或加边框;只有有意读成一件控件(ButtonGroup、分段控件)时才相接。 +- 一处边界只用一种手段:相邻区域已靠明度差区分(`bg-sidebar` 与 `bg-background`、`bg-card` 与 `bg-background`)时不再加分隔线或外框。Table、代码块等自带边界的组件直接放进布局流,不外套带内边距和边框的 Card。 +- 成组列表可用 `divide-y divide-border/40`;菜单用组件库的 `DropdownMenuSeparator` 等子组件分组,工具栏控件组之间用 ``;其余分区用留白,不放横向 ``。 + +## 光学对齐(Optical Alignment) -## 光学微调 +对齐文字字面与图形的视觉边缘和重心,不对齐 DOM 边框盒;调整只在局部封装: -以视觉重心为准,只在局部封装:不对称图形(Play / Star)`translate-x-px` 微移 1–2px;图标加文字的按钮削减图标侧 1–2px 内边距;引用块首行引号用 `hanging-punctuation: first` 或负缩进。 +- 带内边距的 ghost 按钮、列表项 hover 底色用 `-mx-*` 配 `px-*` 补偿,让文字落回轴线。 +- 不对称图形(Play / Star)`translate-x-px` 微移 1–2px;图标加文字的按钮削减图标侧 1–2px 内边距。 +- 引用块首行引号用 `hanging-punctuation: first` 或负缩进。 diff --git a/.agents/skills/sweet-mode/reference/resilience.md b/.agents/skills/sweet-mode/reference/resilience.md new file mode 100644 index 0000000..930e9b2 --- /dev/null +++ b/.agents/skills/sweet-mode/reference/resilience.md @@ -0,0 +1,31 @@ +# 界面韧性 + +任何数据极值、异步切换与状态退场,都不撑破布局、不发生位移、不闪空内容。 + +## 1. 加载 + +- **首次加载(冷加载)**:结构固定的内容(卡片、表格、媒体)用 `aspect-*` 或 1:1 骨架屏占位;动态长流(文章、评论)只留 `min-h-[1lh]`,避免空数据时二次坍塌。 +- **翻页、筛选、刷新**:keep previous data(TanStack Query 的 `placeholderData: keepPreviousData`),旧数据留在原处 `opacity-60`,新数据返回后原地替换,不退回骨架屏;加载反馈放在触发控件(按钮内 Spinner、Tab、边缘细进度条)。骨架屏只用于没有旧数据的冷加载;清空搜索或重置视图时直接清空。 +- **控件**:按钮进入加载或禁用态时锁定宽高。 + +## 2. 卡片网格等高 + +同排卡片根节点 `h-full flex flex-col`;标题 `line-clamp-2` 或设最小高度,正文 `flex-1`,底部操作 `mt-auto`;媒体显式声明比例(`aspect-video w-full object-cover`)。 + +## 3. 空值 + +- **空态体量随容器**:主工作区为空时渲染完整空状态(标题、一句说明、主按钮,可加一幅按 `icon.md` §3 自绘的业务插图);卡片、侧栏或弹窗内的子列表为空时只留一行 `text-sm text-muted-foreground`,或隐藏该区块。空状态不套 `border-dashed` 虚线框。 +- **缺失**:缺失文本留 `min-h-[1lh]` 或 `"—"`。占位区分未加载、空、缺失与失败,不用默认值掩盖。 +- **报错**:有校验的字段底部只留一个 `min-h-5` 辅助槽,报错出现时不推挤下方控件;字段带静态说明(`FieldDescription`)时,报错在该槽位内原地替换说明,不把说明与空报错槽上下叠放;无校验的字段不预留空槽。 + +## 4. 溢出(Defensive CSS) + +- 含动态文本的 Flex/Grid 子项加 `min-w-0`,长文本 `truncate` 或 `line-clamp-*`;被截断的业务名称用 Tooltip 或详情承接全文。 +- 无空格长串(UUID、密钥、URL、哈希、文件路径)按所处结构分流:与按钮水平并排或需整段选中的单值容器保持单行(`` 或 `whitespace-nowrap overflow-x-auto`),不用 `break-all` 折行撑高;只需识别的列表项用 `truncate` 或保留首尾的中段省略;独立占块的多行流(日志、堆栈)才用 `break-all`。 +- 裁切容器(`overflow-hidden`、`overflow-x-auto`)内贴边的 Input 与 Button 至少留 `p-0.5`,focus ring 不被边缘切掉。 + +## 5. 退出过渡 + +退出过渡期间内容停在退出前的状态:触发退出的回调只负责退出,不改写即将消失的视图层级、选择、草稿、文案或计数;需要重置的状态在下次进入时重置。浮层关闭、toast 消失、折叠收起与列表项移除同理。 + +从菜单项打开 Dialog / AlertDialog 时,弹窗用受控 `open` 状态挂在菜单外、与菜单平级;嵌在菜单项里会随菜单关闭卸载,弹窗闪退或残留指针锁定。 diff --git a/.agents/skills/sweet-mode/reference/stability.md b/.agents/skills/sweet-mode/reference/stability.md deleted file mode 100644 index 7e7d1cc..0000000 --- a/.agents/skills/sweet-mode/reference/stability.md +++ /dev/null @@ -1,23 +0,0 @@ -# 尺寸稳定 - -状态变化不移动已有内容的位置。 - -## 1. 加载 - -- **首次加载**:结构固定的内容(卡片、表格、媒体)用 `aspect-*` 或 1:1 骨架屏占位;动态长流(文章、评论)只留 `min-h-[1lh]`,避免空数据时二次坍塌。 -- **翻页、筛选、刷新**:旧数据保持渲染(`opacity-60`),加载反馈放在触发控件(按钮内 Spinner、Tab、边缘细进度条)。清空搜索或重置视图时直接清空。 -- **控件**:按钮进入加载或禁用态时锁定宽高。 - -## 2. 卡片网格等高 - -同排卡片根节点 `h-full flex flex-col`;标题 `line-clamp-2` 或设最小高度,正文 `flex-1`,底部操作 `mt-auto`;媒体显式声明比例(`aspect-video w-full object-cover`)。 - -## 3. 空值与溢出 - -- 空列表渲染固定体量的空状态;缺失文本留 `min-h-[1lh]` 或 `"—"`。占位区分未加载、空、缺失与失败,不用默认值掩盖。 -- 字段提示区预留 `min-h-5`,报错出现时不推挤提交按钮。 -- 含动态文本的 Flex/Grid 子项加 `min-w-0`,长文本 `truncate` 或 `line-clamp-*`。 - -## 4. 退出过渡 - -退出过渡期间内容停在退出前的状态:触发退出的回调只负责退出,不改写即将消失的视图层级、选择、草稿、文案或计数;需要重置的状态在下次进入时重置。浮层关闭、toast 消失、折叠收起与列表项移除同理。 diff --git a/.agents/skills/sweet-mode/reference/surface.md b/.agents/skills/sweet-mode/reference/surface.md index b5835c9..929399c 100644 --- a/.agents/skills/sweet-mode/reference/surface.md +++ b/.agents/skills/sweet-mode/reference/surface.md @@ -1,8 +1,8 @@ # 色彩、表面与层叠 -只消费语义 Token。色值集中在样式入口,业务代码不写 Hex/OKLCH 与任意值。 +只消费语义 Token。色值集中在样式入口,业务代码不写 Hex/OKLCH、任意值、Tailwind 原生色板(`slate-500`、`emerald-500/10`、`white`);只有遮罩、媒体播放底色与媒体上的渐变遮罩用 `black` / `white` 及其透明度。媒体上的文字等不随主题变化的颜色,在样式入口定义专用 Token。 -## 1. 表面高度(E0–E3) +## 1. 表面层级 Elevation(E0–E3) 每个表面归入一层: @@ -14,6 +14,7 @@ | E3 浮层 | 菜单、Popover | `popover` / `popover-foreground` | - 嵌套不等于抬升;同级表面不层层叠放。 +- 表面分离靠明度差。阴影只在组件库的浮层变体里定义,调用点只用 `shadow-none`。 - Dialog、AlertDialog、Sheet 用 `background` 加配套遮罩;Tooltip 用 `foreground` 作底、`background` 作字。调用点不改写成 `popover`。 - `accent` 只表达交互高亮,`input` 只用于输入控件边界,都不是通用的“再高一层”。 - 亮暗双主题(`:root` / `.dark`)。暗色下 `card`、`popover` 略亮于 `background`,同一局部链上明度与层叠不翻转;`sidebar` 与 `background` 并列,不参与此检查。浮层去掉阴影后仍能靠明度差、边框或遮罩与下层区分。 @@ -23,6 +24,10 @@ 只做强调的焦点色(`primary`、`destructive` 等品牌与状态色)不超过视区的 10%,不作大面积背景;E0 保持低彩度,`accent` 不计入。颜色本身编码信息(数据分类、状态)或本身就是内容(品牌表达、从内容提取的主题色)时按需放开,经 Token 定义并限定范围,框架保持中性,文字对比度不让步。编辑器、画布、代码区等工作区把强调色收到光标、选择与必要反馈。 +- **次要文字**:用 `text-muted-foreground`,不用 `text-foreground/60` 这类透明度或 `opacity-*` 降低静态文字对比度;刷新时整体变暗的旧数据不在此列。 +- **状态**:表格与列表中的状态用 6px 语义色圆点配文字,或低透明度软底(`bg-destructive/10 text-destructive`),不用实心高饱和 Badge;实心 `primary` 只留给视区唯一的主按钮。 +- **涨跌**:行情与监控核心面之外,统计数字不加红绿涨跌色;需要表达增减时写出 `+` 或 `−` 符号。 + ## 3. 圆角 只用样式入口的圆角阶梯: @@ -40,7 +45,7 @@ 缺省对象与下面两条冲突时,以下面为准: -- **同心**:$R_{inner} = \max(0, R_{outer} - (\text{Padding} + \text{Border}))$。结果不在阶梯上时取不超过它的最大一档,为 0 时 `rounded-none`。 +- **同心圆角(concentric corners)**:$R_{inner} = \max(0, R_{outer} - (\text{Padding} + \text{Border}))$。结果不在阶梯上时取不超过它的最大一档,为 0 时 `rounded-none`。 - **形态**:固定高度控件取 $R \le H/4$(圆角矩形)或 $R \ge H/2$(胶囊),不落在两者之间。 `corner-shape: squircle` 包在 `@supports` 内,以 `border-radius` 回退。 diff --git a/.agents/skills/sweet-mode/reference/typography.md b/.agents/skills/sweet-mode/reference/typography.md index 5d2935f..f4bf2b4 100644 --- a/.agents/skills/sweet-mode/reference/typography.md +++ b/.agents/skills/sweet-mode/reference/typography.md @@ -4,15 +4,20 @@ ## 字阶 -文字篇幅与视觉重量按 6:3:1 分配: - -| 配比 | 字号 | 字重 | 角色 | -| :--- | :--- | :--- | :--- | -| 60% 阅读 | `text-xs`–`text-base`(长文正文可 `text-lg`) | `font-normal` | 正文、表格行、表单说明、辅助标注 | -| 30% 结构 | `text-lg` / `text-xl` | `font-medium` / `font-semibold` | 模块与卡片标题、表单分组 Label | -| 10% 焦点 | `text-2xl` 及以上 | `font-semibold` | 页面主标题、Hero、核心 KPI | - -- 下限 `text-xs`;正文不大面积加粗;列表项不套标题字号。 +应用界面以 `text-sm` 为基准,层级先靠字重与颜色拉开,字号只在页面级标题处放大: + +| 角色 | 字号 | 字重 | +| :--- | :--- | :--- | +| 元数据、时间戳、辅助标注 | `text-xs` | `font-normal` | +| 正文、表格行、表单说明 | `text-sm`;长文阅读 `text-base` / `text-lg` | `font-normal` | +| 控件文字(Button、Tab、菜单项)、字段 Label、表头 | `text-sm`,紧凑控件 `text-xs` | `font-medium` | +| 卡片、模块与表单分组标题 | `text-sm` / `text-base` | `text-sm` 配 `font-medium`,`text-base` 配 `font-semibold` | +| 页面内分区标题 | `text-base` / `text-lg` | `font-semibold` | +| 页面主标题 | `text-xl` / `text-2xl` | `font-semibold` | +| Hero、核心 KPI | `text-2xl` 及以上 | `font-semibold` | + +- 字重只用 `font-normal` / `font-medium` / `font-semibold`。营销与长文页面按阅读距离整体上调标题字号,字重不变。 +- 下限 `text-xs`;正文段落用 `font-normal`;列表项不套标题字号。 - 同一视区只有一个最高级标题。 - 内容装不下时重组布局,不缩字号。 @@ -24,5 +29,4 @@ ## 字体渲染(仅 macOS 生效) -- 根节点 `antialiased`,只设一处;个别区域需要系统渲染时局部 `subpixel-antialiased`。 -- 关闭系统加粗后细字重在深色底上偏细,深色表面的正文与标签取 `font-normal` 及以上。 +根节点 `antialiased`,只设一处;个别区域需要系统渲染时局部 `subpixel-antialiased`。 diff --git a/.agents/skills/sweet-mode/scripts/render-audit.js b/.agents/skills/sweet-mode/scripts/render-audit.js new file mode 100644 index 0000000..2be436e --- /dev/null +++ b/.agents/skills/sweet-mode/scripts/render-audit.js @@ -0,0 +1,230 @@ +/** + * 渲染检查:在已打开的页面里执行,返回只有渲染后才能发现的违规。 + * - overflow:内容宽于视口;元素越出视口且没有横向滚动或裁切的祖先(body / html 上的 + * overflow-x-hidden 不算);子项越出 flex / grid 容器 + * - text-overflow:文字溢出自身盒子,或被裁切却没有省略号与 line-clamp + * - row-height:同一行的卡片或水平并排的控件(按钮与输入 / 只读值容器)高度不一致 + * - adjacent-fill:相邻兄弟元素填充色相同且有别于底色,彼此相接且交界处没有边框 + * - font-size:计算字号小于 12px + * + * 整个文件是一个无参函数,用浏览器工具的 evaluate 执行; + * Playwright:await page.evaluate(`(${source})()`)。 + */ +() => { + const viewport = document.documentElement.clientWidth + const violations = [] + const styleOf = (element) => getComputedStyle(element) + + const describe = (element) => { + const id = element.id ? `#${element.id}` : "" + const classes = (element.getAttribute("class") ?? "").trim().split(/\s+/).filter(Boolean).slice(0, 4) + const text = (element.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 40) + return `${element.tagName.toLowerCase()}${id}${classes.map((name) => `.${name}`).join("")}${text ? ` "${text}"` : ""}` + } + + const isRendered = (element) => { + const rect = element.getBoundingClientRect() + return rect.width > 1 && rect.height > 1 && styleOf(element).visibility !== "hidden" + } + + const clipsX = (element) => styleOf(element).overflowX !== "visible" + + const hasClippingAncestor = (element) => { + for (let parent = element.parentElement; parent && parent !== document.body; parent = parent.parentElement) { + if (clipsX(parent)) return true + } + return false + } + + const insideScroller = (element) => { + for (let parent = element.parentElement; parent && parent !== document.body; parent = parent.parentElement) { + if (["auto", "scroll"].includes(styleOf(parent).overflowX)) return true + } + return false + } + + const hasSurface = (element) => { + const style = styleOf(element) + return ( + !/rgba\(0, 0, 0, 0\)|transparent/.test(style.backgroundColor) || + parseFloat(style.borderTopWidth) > 0 || + style.boxShadow !== "none" + ) + } + + // grid 子项会被拉伸,可见的卡片常是它唯一的子元素 + const surfaceOf = (element) => { + for (let node = element; node; node = node.children.length === 1 ? node.children[0] : null) { + if (hasSurface(node)) return node + } + return null + } + + const elements = [...document.body.querySelectorAll("*")].filter( + (element) => !["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"].includes(element.tagName) && isRendered(element) + ) + + const scrollWidth = document.documentElement.scrollWidth + if (scrollWidth > viewport + 1) { + violations.push({ rule: "overflow", element: "html", detail: `内容宽 ${scrollWidth}px,超出视口 ${viewport}px` }) + } + const overflowing = [] + for (const element of elements) { + if (overflowing.some((reported) => reported.contains(element))) continue + const rect = element.getBoundingClientRect() + const crossesEdge = (rect.left < viewport && rect.right > viewport + 1) || (rect.right > 0 && rect.left < -1) + if (crossesEdge && styleOf(element).position !== "fixed" && !hasClippingAncestor(element)) { + overflowing.push(element) + violations.push({ + rule: "overflow", + element: describe(element), + detail: `占据 ${Math.round(rect.left)}–${Math.round(rect.right)}px,视口宽 ${viewport}px`, + }) + } + } + + // 长文本把 flex / grid 子项撑出容器(缺 min-w-0);负边距是有意的对齐补偿,横向滚动区内的越界是预期行为 + for (const container of elements) { + const style = styleOf(container) + if (!/(?:flex|grid)$/.test(style.display) || style.overflowX !== "visible" || insideScroller(container)) continue + const box = container.getBoundingClientRect() + for (const child of container.children) { + const childStyle = styleOf(child) + if (!isRendered(child) || ["absolute", "fixed"].includes(childStyle.position)) continue + const rect = child.getBoundingClientRect() + const excess = Math.max( + rect.right - box.right - Math.max(0, -parseFloat(childStyle.marginRight)), + box.left - rect.left - Math.max(0, -parseFloat(childStyle.marginLeft)) + ) + if (excess > 1) { + violations.push({ rule: "overflow", element: describe(child), detail: `越出 ${style.display} 容器 ${Math.round(excess)}px` }) + break + } + } + } + + // 文字按所在块级盒子判断:Range 只量文字本身,不受角标等绝对定位子元素干扰 + const blockOf = (element) => { + let node = element + while (node.parentElement && /^(?:inline|contents)$/.test(styleOf(node).display)) node = node.parentElement + return node + } + const smallText = new Set() + const brokenText = new Set() + const range = document.createRange() + const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT) + for (let node = walker.nextNode(); node; node = walker.nextNode()) { + const parent = node.parentElement + if (!node.textContent.trim() || !parent || !isRendered(parent)) continue + if (["SCRIPT", "STYLE", "NOSCRIPT", "TEXTAREA", "OPTION"].includes(parent.tagName) || parent.closest("svg")) continue + + const fontSize = parseFloat(styleOf(parent).fontSize) + if (fontSize < 12 && !smallText.has(parent)) { + smallText.add(parent) + violations.push({ rule: "font-size", element: describe(parent), detail: `字号 ${fontSize}px` }) + } + + const container = blockOf(parent) + if (brokenText.has(container)) continue + range.selectNodeContents(node) + const text = range.getBoundingClientRect() + const box = container.getBoundingClientRect() + // 字形盒可能高于行盒(leading-none、阿拉伯文等高字形字体);真正的纵向溢出至少多出一行 + const slack = fontSize * 0.6 + const outX = text.right > box.right + 1 || text.left < box.left - 1 + const outY = text.bottom > box.bottom + slack || text.top < box.top - slack + if (!outX && !outY) continue + + const style = styleOf(container) + const clamped = style.webkitLineClamp !== "none" && style.webkitLineClamp !== "" + const cut = (overflow) => ["hidden", "clip"].includes(overflow) + let detail = null + if ((outX && style.overflowX === "visible") || (outY && style.overflowY === "visible")) { + detail = "文字越出所在盒子,压到相邻内容" + } else if ((outX && cut(style.overflowX) && style.textOverflow !== "ellipsis" && !clamped) || (outY && cut(style.overflowY) && !clamped)) { + detail = "文字被裁切且没有省略号或 line-clamp" + } + if (detail) { + brokenText.add(container) + violations.push({ rule: "text-overflow", element: describe(container), detail }) + } + } + + for (const grid of elements.filter((element) => styleOf(element).display.endsWith("grid"))) { + const rows = new Map() + for (const child of grid.children) { + const surface = isRendered(child) ? surfaceOf(child) : null + if (!surface) continue + const rect = surface.getBoundingClientRect() + if (rect.height < 48) continue + const top = Math.round(child.getBoundingClientRect().top) + rows.set(top, [...(rows.get(top) ?? []), rect.height]) + } + for (const heights of rows.values()) { + if (heights.length > 1 && Math.max(...heights) - Math.min(...heights) > 1) { + violations.push({ + rule: "row-height", + element: describe(grid), + detail: `同排卡片高度 ${heights.map(Math.round).join(" / ")}px`, + }) + } + } + } + + const CONTROL = 'button, input, select, code, [role="combobox"], [data-slot="input"], [data-slot="select-trigger"], [data-slot="button"]' + for (const row of elements.filter((element) => { + const style = styleOf(element) + return style.display.endsWith("flex") && style.flexDirection === "row" + })) { + const controls = [...row.children] + .filter((child) => isRendered(child) && child.matches(CONTROL)) + .map((child) => child.getBoundingClientRect()) + if (controls.length < 2) continue + // 排除 flex-wrap 折到下一行的子项,只比较纵向投影重叠的同行控件 + const first = controls[0] + const sameLine = controls.filter((rect) => rect.top < first.bottom && first.top < rect.bottom) + if (sameLine.length < 2) continue + const heights = sameLine.map((rect) => rect.height) + if (Math.max(...heights) - Math.min(...heights) > 2) { + violations.push({ + rule: "row-height", + element: describe(row), + detail: `同行控件高度 ${heights.map(Math.round).join(" / ")}px`, + }) + } + } + + // 同色填充块零间距相接会读成一个整体;与底色相同的填充不可见,不算; + // 有意合成的控件组与交界处带边框的成组列表(divide-y)本就要读成一组,豁免 + const isTransparent = (color) => /rgba\(0, 0, 0, 0\)|transparent/.test(color) + const backdropOf = (element) => { + for (let parent = element.parentElement; parent; parent = parent.parentElement) { + const color = styleOf(parent).backgroundColor + if (!isTransparent(color)) return color + } + return "rgb(255, 255, 255)" + } + const GROUP = '[role="group"], [role="radiogroup"], [role="tablist"], [role="toolbar"], [data-slot$="group"]' + const edgeBorder = (element, side) => { + const style = styleOf(element) + return parseFloat(style[`border${side}Width`]) > 0 || style.boxShadow !== "none" + } + for (const element of elements) { + const fill = styleOf(element).backgroundColor + const next = element.nextElementSibling + if (isTransparent(fill) || !next || !isRendered(next) || styleOf(next).backgroundColor !== fill) continue + if (fill === backdropOf(element) || element.parentElement?.closest(GROUP)) continue + const a = element.getBoundingClientRect() + const b = next.getBoundingClientRect() + const overlapX = Math.min(a.right, b.right) - Math.max(a.left, b.left) + const overlapY = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) + let touching = false + if (overlapY > 1 && Math.abs(b.left - a.right) <= 1) touching = !edgeBorder(element, "Right") && !edgeBorder(next, "Left") + else if (overlapX > 1 && Math.abs(b.top - a.bottom) <= 1) touching = !edgeBorder(element, "Bottom") && !edgeBorder(next, "Top") + if (touching) { + violations.push({ rule: "adjacent-fill", element: describe(element), detail: `与下一个兄弟元素同为 ${fill} 且零间距相接` }) + } + } + + return { viewport:`${window.innerWidth}×${window.innerHeight}`, scrollWidth, violations } +} diff --git a/.agents/skills/sweet-mode/scripts/ui-guardrails.js b/.agents/skills/sweet-mode/scripts/ui-guardrails.js index 449fd2c..b48b02c 100644 --- a/.agents/skills/sweet-mode/scripts/ui-guardrails.js +++ b/.agents/skills/sweet-mode/scripts/ui-guardrails.js @@ -1,8 +1,14 @@ /** * 只扫描“无判断余地”的 UI 禁令,规则名前缀对应 reference 文件: + * - hierarchy:用 · / • 把多个字段拼成一行、Card 嵌套 Card + * - layout:横向 分区 * - motion:transition-all、布局属性过渡、ease-in、motion 从 scale: 0 入场 - * - surface:z-index 任意值、越出阶梯的 z-index、arbitrary class 中的硬编码色值 - * - typography:任意字号、任意字体族 + * - surface:z-index 任意值与越出阶梯、硬编码色值、Tailwind 原生色板、调用点阴影、 + * 彩色渐变与渐变文字、大半径模糊光晕、静态文字的透明度 + * - typography:任意字号、任意字体族、阶梯外字重 + * + * 组件库(packages/ui、shadcn 的 components/ui)不扫描:其中的过渡与尺寸多是组件机制, + * 外观按 SKILL.md 的基线表人工核对。 * * 圆角与间距的任意值**不在此列**:规则本身有判断余地(公式推导的转角、 * 行高托底与光学微调值域),扫描会产生误报,交由审查判断。 @@ -17,7 +23,7 @@ import { readFileSync } from "node:fs" import { join, resolve } from "node:path" const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|css|scss|vue|svelte|astro|html|mdx)$/ -// 组件库(packages/ui、shadcn 的 components/ui)、第三方、测试夹具与 agent skill(含本脚本的副本)不属于业务代码 +// 组件库、第三方、构建产物、测试夹具与 agent skill(含本脚本的副本)不属于调用点代码 const EXCLUDED = /(?:^|\/)(?:node_modules|vendor|dist|build|\.next|coverage|components\/ui|\.[\w-]+\/skills)\/|^packages\/ui\/|\.(?:test|spec)\.[^/]+$/ @@ -26,6 +32,13 @@ const L = "(? @@ -34,6 +47,13 @@ const isLadderZ = (value) => const Z_SUGGESTION = "改用 -z-10 / z-0 / z-10 / z-20 / z-30 / z-40 / z-50;被遮挡时用 Portal 提升" const CHECKS = [ + { + rule: "hierarchy/separator-dot", + pattern: "[·•]|&(?:middot|bull|#183|#8226|#xb7|#x2022);|\\\\u(?:00b7|2022)", + flags: "i", + message: "用圆点把多个字段拼成一行", + suggestion: "每个字段先判断去留,留下的放进分组、对齐的列或行尾、图标或 Badge", + }, { rule: "motion/transition-all", pattern: `${L}transition-all${R}|\\btransition(?:-property|Property)?\\s*:\\s*["'\`]?all\\b`, @@ -79,6 +99,40 @@ const CHECKS = [ message: "z-index 超出业务代码上限 50", suggestion: Z_SUGGESTION, }, + { + rule: "surface/palette-color", + pattern: `${L}${COLOR_UTILITY}-${PALETTE}(?:\\/[\\w.]+)?${R}`, + // 遮罩、媒体播放底色与压在媒体上的渐变色标不随主题变化 + accept: (match) => /^(?:bg|from|via|to)-black(?:\/\d+)?$|^(?:from|via|to)-white(?:\/\d+)?$/.test(match[0]), + message: "Tailwind 原生色板绕过语义 Token,亮暗主题下不跟随", + suggestion: "改用 bg-muted / text-muted-foreground / border-border 等语义 Token;缺 Token 时在样式入口补充", + }, + { + rule: "surface/shadow", + // 跳过 CSS 选择器(.shadow-lg { box-shadow: none }) + pattern: `(? + /(?:^|:)(?:hover|focus[\w-]*|active|disabled|placeholder|aria-[^:]*|data-[^:]*|group-[^:]*|peer-[^:]*):/.test(match[1]) || + /^(?:xs|sm|base|lg|[2-9]?xl)$/.test(match[2]) || + new RegExp(`^${PALETTE}$`).test(match[2]) || + /^(?:white|black)$/.test(match[2]), + message: "用透明度降低静态文字对比度", + suggestion: "次要文字改用 text-muted-foreground", + }, { rule: "surface/color-literal", pattern: `${L}[a-z][\\w-]*-\\[[^\\]\\s]*?${COLOR_LITERAL}[^\\]\\s]*\\]`, @@ -97,13 +151,43 @@ const CHECKS = [ message: "任意字体族绕过字体 Token", suggestion: "改用 font-sans / font-mono / font-serif", }, -].map((check) => ({ - ...check, - regex: new RegExp(check.pattern, `g${check.flags ?? ""}`), -})) + { + rule: "typography/font-weight", + pattern: `${L}font-(?:thin|extralight|light|bold|extrabold|black|\\[\\d+\\])${R}`, + message: "字重越出阶梯", + suggestion: "只用 font-normal / font-medium / font-semibold", + }, + { + rule: "layout/separator", + pattern: `]*\\borientation\\s*=\\s*\\{?\\s*["'\`]vertical)[^>]*>`, + message: "用横向 Separator 分区", + suggestion: "分区改用留白与对齐轴;菜单用组件库的 *MenuSeparator,工具栏控件组之间用 orientation=\"vertical\"", + }, + { + rule: "hierarchy/nested-card", + find: findNestedCards, + message: "卡片套卡片", + suggestion: "内层改用留白、分组或 bg-muted 填充区块,只保留外层 Card", + }, +].map((check) => { + if (check.find) return check + const regex = new RegExp(check.pattern, `g${check.flags ?? ""}`) + return { ...check, find: (content) => content.matchAll(regex) } +}) -// 一次廉价扫描筛掉绝大多数文件;漏掉的字面量会让对应规则失效,新增规则时同步补充 -const PREFILTER = /transition|ease|scale|z-|z-?index|text-\[|font-\[|-\[/i +// 只匹配 ,不含 CardHeader 等子组件;自闭合的 不开启嵌套 +function findNestedCards(content) { + const nested = [] + let depth = 0 + for (const match of content.matchAll(/(?/])([^>]*)>/g)) { + if (match[1]) depth = Math.max(0, depth - 1) + else if (!match[2].endsWith("/")) { + if (depth > 0) nested.push(match) + depth += 1 + } + } + return nested +} function findRepositoryRoot(target) { try { @@ -160,13 +244,11 @@ function locate(starts, offset) { } function scanContent(content, file) { - if (!PREFILTER.test(content)) return [] - const findings = [] let starts = null for (const check of CHECKS) { - for (const match of content.matchAll(check.regex)) { + for (const match of check.find(content)) { if (check.accept?.(match)) continue starts ??= lineStarts(content) findings.push({ diff --git a/apps/web/src/components/agents/agent-indicator.tsx b/apps/web/src/components/agents/agent-indicator.tsx index 420182b..8a10d4f 100644 --- a/apps/web/src/components/agents/agent-indicator.tsx +++ b/apps/web/src/components/agents/agent-indicator.tsx @@ -30,9 +30,9 @@ const ALL = Array.from({ length: CELLS }, () => true) /* * Tool-call alternates between a cross and four corners: * cross: corners: - * · ■ · ■ · ■ - * ■ ■ ■ · · · - * · ■ · ■ · ■ + * . # . # . # + * # # # . . . + * . # . # . # */ const TC_CROSS = [false, true, false, true, true, true, false, true, false] diff --git a/apps/web/src/components/agents/prompt-input/model-picker.tsx b/apps/web/src/components/agents/prompt-input/model-picker.tsx index a3d34ed..9950496 100644 --- a/apps/web/src/components/agents/prompt-input/model-picker.tsx +++ b/apps/web/src/components/agents/prompt-input/model-picker.tsx @@ -73,7 +73,7 @@ export const ModelPicker = ({ {/* The name is the part that changes, so it is the part that truncates. */} {active.name} - + } /> diff --git a/apps/web/src/components/blog/blog-page.tsx b/apps/web/src/components/blog/blog-page.tsx index 540421a..e59d21c 100644 --- a/apps/web/src/components/blog/blog-page.tsx +++ b/apps/web/src/components/blog/blog-page.tsx @@ -5,7 +5,16 @@ import { Streamdown } from "streamdown" import { Toc } from "@/components/blog/toc" import { SiteHeader } from "@/components/site-header" import { slugify } from "@/lib/toc" -import { COPY, POST_IDS, postLink, postOf, type Lang, type PostId } from "./posts" +import { + AUTHOR, + COPY, + POST_IDS, + PUBLISHED, + postLink, + postOf, + type Lang, + type PostId, +} from "./posts" /** The plain text of rendered Markdown children, so a heading's id matches its nav entry. */ function textOf(children: ReactNode): string { @@ -74,8 +83,10 @@ export function BlogPage({ lang, post: id }: { lang: Lang; post: PostId }) {
-

- {copy.byline(post.minutes)} +

+ {AUTHOR} + + {copy.readTime(post.minutes)}

{/* Below lg the side column is gone, so the nav folds above the post. */}
diff --git a/apps/web/src/components/blog/posts.ts b/apps/web/src/components/blog/posts.ts index b877160..240a0cd 100644 --- a/apps/web/src/components/blog/posts.ts +++ b/apps/web/src/components/blog/posts.ts @@ -9,18 +9,24 @@ import harnessZh from "../../../content/harness.zh.md?raw" export const LANGS = ["en", "zh"] as const export type Lang = (typeof LANGS)[number] +/** Who wrote every post, and when. */ +export const AUTHOR = "Retry" +export const PUBLISHED = "2026-10-16" + /** The words around a post, per language. */ export const COPY = { en: { toc: "On this page", next: "Read next", - byline: (minutes: number) => `Retry · October 16, 2026 · ${minutes} min read`, + date: "October 16, 2026", + readTime: (minutes: number) => `${minutes} min read`, switchTo: { label: "中文", aria: "Switch to Chinese" }, }, zh: { toc: "目录", next: "下一篇", - byline: (minutes: number) => `Retry · 2026 年 10 月 16 日 · ${minutes} 分钟阅读`, + date: "2026 年 10 月 16 日", + readTime: (minutes: number) => `${minutes} 分钟阅读`, switchTo: { label: "EN", aria: "Switch to English" }, }, } as const satisfies Record diff --git a/docs/guardrails.md b/docs/guardrails.md index 764246b..ddf0bbb 100644 --- a/docs/guardrails.md +++ b/docs/guardrails.md @@ -31,12 +31,12 @@ Hooks come from `lefthook.yml` and install with `pnpm install`. Pre-commit forma - `apps/web/src/components/{agents,scroll-rail,ui}` is the app's own component library and is exempt from the color, value and inline-style rules. `no-restyle` still applies there. - **Rule scans.** `pnpm rules:check` runs three scans with no room for judgment: - `zod:check` fails on Zod v3 patterns and deprecated APIs ([rules/zod-v4/README.md](rules/zod-v4/README.md)). - - `ui:check` runs the [sweet-mode](../.agents/skills/sweet-mode/SKILL.md) scanner. It fails on `transition-all`, transitions on layout properties, `ease-in`, entering from `scale: 0`, z-index off the `-z-10` to `z-50` ladder, hard-coded colors in classes, and arbitrary font sizes and families. It skips `packages/ui`, `components/ui`, tests and skill directories. + - `ui:check` runs the [sweet-mode](../.agents/skills/sweet-mode/SKILL.md) scanner. It fails on fields joined by `·`, `transition-all`, transitions on layout properties, `ease-in`, entering from `scale: 0`, z-index off the `-z-10` to `z-50` ladder, hard-coded colors and Tailwind palette colors in classes, call-site shadows, decorative gradients and blur glows, static text faded with opacity, arbitrary font sizes and families, weights off the ladder, horizontal `` and a Card inside a Card. It skips `packages/ui`, `components/ui`, tests and skill directories. - `skills:check` fails when a copied skill drifted from its source. `.agents/skills/void` must match the installed `void` package byte for byte. `.agents/skills/sweet-mode` must match the hash recorded in `.agents/skills/skills-lock.json`. - **Types.** `tsc --noEmit` per workspace through Turborepo, with `strict` and `noUncheckedIndexedAccess`. In `apps/web` it runs `void prepare` first, which generates the binding types. - **Unit tests.** Vitest via `vp test`, one project per app and package. Tests call pure modules and never start a container. - **Build.** The production build of every workspace, the same one `pnpm deploy` ships. -- **Unused code.** knip, configured in `knip.json`. It fails on unused files, exports and dependencies in every workspace, `packages/ui` included, where the entry points are the same files its `exports` map publishes. Delete what it reports, or add a real entry point to `knip.json` when the file is loaded by a tool. +- **Unused code.** knip, configured in `knip.json`. It fails on unused files, exports and dependencies in every workspace, `packages/ui` included, where the entry points are the same files its `exports` map publishes. Delete what it reports, or add a real entry point to `knip.json` when the file is loaded by a tool. Copied skills under `.agents/skills/` are ignored. Their files run outside the build, and `pnpm skills:check` owns them. - **Browser smoke tests.** `pnpm e2e` drives a disposable local app with Playwright and writes evidence to `.verification/`. Details are in the [verification skill](../.agents/skills/verify-web/SKILL.md). ## Dependencies diff --git a/knip.json b/knip.json index 9834c67..a3c918d 100644 --- a/knip.json +++ b/knip.json @@ -1,6 +1,6 @@ { "$schema": "https://unpkg.com/knip@6/schema.json", - "ignore": ["docs/rules/**"], + "ignore": ["docs/rules/**", ".agents/skills/**"], "workspaces": { ".": { "entry": ["scripts/e2e-browser.js"],