SilentPolish: Next.js 全应用优化
修复间距和设计缺陷,使用 next/image,删除所有虚假数据,并将所有内容集中到 site.ts 中。
触发提示: "对整个应用遵循此技能。按顺序执行每一步。不要跳过任何文件。"
0. 上下文
- Next.js 应用(假定使用 App Router;根据 Pages Router 调整)。
- UI 可能由 AI 工具生成(例如通过 MCP 的 Google Stitch)。预计会存在不一致的内边距、固定像素尺寸、普通
<img>标签以及编造的数字、统计数据、价格、日期和表格行。 - 所有者将经常(每天)手动更新真实数据。所有可更改的数据必须位于一个文件中:
site.ts。
1. 硬性规则(绝不违反)
- 组件中没有虚假数据。 没有编造的数字、统计数据、百分比、价格、评分、数量、日期、姓名、电子邮件、电话、评价或表格行。
- 所有数据均来自
site.ts。 组件仅从中读取。组件绝不能包含字面数据。 - 绝不编造替代数字。 使用
null(渲染为—)或空数组。占位符必须明显是空的,而不是看起来逼真。 - 所有内容图像均使用
next/image。 没有<img>标签。 - 单一间距系统。 没有随机的一次性内边距。
- 不改变设计方向(颜色、字体、品牌感觉)。仅修复间距和缺陷。
- 不破坏正在工作的功能。 最后运行构建。
- 遍历整个应用: 每个页面、布局、组件以及 loading/error/not-found 文件。
2. 工作流
按顺序执行步骤。在更改任何内容之前报告审计结果。
步骤 1:审计
运行 scripts/audit.sh <project-root>(或 references/audit-patterns.md 中的手动 grep 命令)。输出一个简短的分组列表:
- A. 虚假/硬编码数据:JSX 文本中的数字、组件内部类似数据的数组、虚假的联系信息、虚假的日期。
- B. 图像:
<img>标签、用作内容的 CSS 背景图像。 - C. 布局/内边距问题:固定像素尺寸、
h-screen/100vh、混合节内边距、双重内边距、移动端边缘触碰、水平滚动、用于布局的绝对定位、负 margin 技巧、缺少max-width、文本溢出、不统一的卡片尺寸/圆角。
步骤 2:创建 site.ts
将 assets/templates/site.ts 复制到 src/config/site.ts(或 config/ / lib/ 以匹配项目;使用项目现有的导入别名,例如 @/config/site)。
- 完全类型化。每个可更改的值都放在这里。
- 未知值为
null或[],绝不是虚假数据。 - 每个部分上方的注释告诉所有者要编辑什么。
- 保持扁平简单。仅保留与实际应用匹配的部分;为审计发现的内容(定价、日程、费率、团队...)添加部分。
- 将所有者的快速更新指南(下面的第 5 节)作为注释放在顶部。
步骤 3:替换每个组件中的虚假数据
针对审计 A 中的每个发现:
- 从组件中移除硬编码的值或数组。
- 向
site.ts添加一个匹配的条目,使用空占位符(null、""、[])。 - 在组件中导入它并从中渲染。
- 优雅地处理空状态(不崩溃,不破坏布局)。
参考模式:assets/templates/StatsExample.tsx、assets/templates/TableExample.tsx。
规则:
- 数字、日期、价格、表格数据和联系信息必须在
site.ts中。静态品牌词汇(标题、按钮标签、导航标签)可以保留在组件中,或者如果可能更改则移至site.ts。 - 使用稳定的
id作为 React 键,而不是数组索引。 - 仅用于布局的数字(
grid-cols-3)是可以的。 - 不能有
Math.random()和虚假的动画计数器。计数器只能动画到从site.ts读取的值,并在null时显示—。 - 联系/社交项目在为空时隐藏:
{contact.email && <a ...>}。
步骤 4:使用 next/image 处理图像
替换每个 <img> 和内容 background-image。完整规则在 references/image-rules.md 中。摘要:
- 始终有意义的
alt(仅对于纯装饰性图像为空)。 width+height,或者fill配合relative父容器。不能同时使用。- 使用
fill时:添加sizes和object-cover/object-contain。 priority仅用于首屏 / LCP 图像。- 本地文件放在
/public/images/中;远程主机添加到next.config的remotePatterns。 - 路径、替代文本和尺寸位于
site.ts(images)中。 - 如果没有真实文件,不要使用外部库存 URL。渲染一个中性的空块(
bg-muted aspect-[16/9]),并为所有者保留site.ts条目。 - 将
rounded和overflow-hidden放在包装器上。
步骤 5:内边距和间距系统
- 将
assets/templates/Container.tsx和Section.tsx复制到components/ui/。 - 仅使用
references/spacing-system.md中的比例。 - 将每个页面部分包裹在
<Section>中;移除多余的临时px-*/py-*。 - 移除双重内边距、基于像素的尺寸以及节上的
h-screen/100vh。 - 统一页眉、页脚、卡片(一个圆角半径)、按钮(44px 最小触摸目标)、表单、长文本(
max-w-prose),并将表格包裹在overflow-x-auto中。 - 仅在所有其他修复无效后,才将
overflow-x-hidden添加到body作为最后手段。
如果项目不使用 Tailwind,则创建具有相同比例的 CSS 变量。
步骤 6:设计缺陷清单
按照 references/design-checklist.md 工作并修复所有问题。
步骤 7:验证
运行 scripts/verify.sh <project-root>(类型检查、lint、构建,然后重新运行审计)。修复所有失败项。在构建通过之前不要说“完成”。
步骤 8:最终报告(必需输出)
- 更改的文件
- 移入
site.ts的内容(部分及其控制的内容) - 移除的虚假数据(内容和位置)
- 转换的图像(数量,以及任何需要所有者提供真实文件的项)
- 间距修复(全局更改、新的
Container/Section使用情况) - 所有者必须填写的所有内容(
null/[]条目列表) - 构建结果(通过/失败)
5. 所有者的快速更新指南(也放在 site.ts 顶部)
- 更新数字:
site.ts→stats→ 更改value。 - 更新表格(每天):
tables.main.rows→ 编辑/添加行 → 将updatedAt设置为今天的日期("YYYY-MM-DD")。 - 更改联系信息:
contact。 - 替换图像: 将文件放入
/public/images/→ 更新images中的src、alt、width、height。 - 隐藏内容: 将值设置为
null或将列表设置为[]。 - 保存。站点在下次重新加载/部署时更新。无需编辑组件。
6. 不要做
- 不要编造数字、名称、价格、评论或日期来“填补空间”。
- 不要将数据数组留在组件内部。
- 不要将
<img>或 CSS 背景图像用于内容。 - 不要添加新的随机内边距值。
- 不要重新设计颜色、字体或品牌。
- 除非真正需要,不要添加依赖项。
- 不要跳过文件或在“主页”处停止。
- 在构建通过之前不要说“完成”。