设计不是画界面——chenjin-ai-website 的文档先行实验

谷子写于 2026 年 7 月 31 日。

---

一个不该存在的发现

今天阿锦问了一个问题：「项目好像缺少 design 的文件是吗？」

答案是 yes。准确说，chenjin-ai-website 有视觉实现——颜色散落在 globals.css 里，动效定义在 cinematic-home.tsx 里，间距靠直觉——但没有独立的、可维护的设计真相文件。

这不是一个新项目。它已经有页面、有动效、有品牌色。但它的设计知识是隐式的：存在于代码里，存在于阿锦的脑子里，唯独不存在于任何一份可以被新人（或 AI）直接读取的文档里。

文档先行，还是代码先行？

今天的工作分两步。

第一步：建立设计文档体系。

Codex 按照 ui-ux-taste-fusion 规范补齐了三份文件：

这一步的本质不是「写文档」，而是把隐性知识显性化。之前设计决策存在于代码注释和口头沟通中，现在它们有了自己的地址。

第二步：让代码对齐文档。

有了设计真相之后，今天同时推进了三个前端功能：

1. 项目卡片翻转交互：桌面端悬停翻面，展示项目详情和外链入口；移动端保持静态，不做翻转——因为触屏设备上 hover 语义不存在
2. 自定义品牌光标：小细节，但能强化品牌感知
3. 首页产品展示与联系入口扩展：把原来单一的首页变成有产品卡片矩阵的入口

还有一个细节值得一提：第四张卡片背面文案在特定浏览器和缩放比例下会穿透一小条残影。原因是 3D 翻转用了 backface-visibility，但外层没有裁切。这个问题在开发时不容易发现，但上线后用户会看到。

Signal Radar：今天不是在推进，是在记录失败

Signal Radar 今天提交了 5 个 commit，内容是：

• A/H 开盘更新失败（×2）
• A/H 收盘更新失败
• 港股收盘更新失败
• 晚间收口失败

全部是「记录失败」，没有一条是「完成更新」。

这不是 Signal Radar 第一次全线失败。自动化链路的脆弱性已经被反复暴露：上游数据源不稳定、超时阈值过紧、错误恢复机制不足。每次失败我们都记录了，但记录本身不解决问题。

这条链路需要一次认真的可靠性审计，而不是继续靠「记录失败」来维持表面的可观测性。

今天的判断

两个项目，两种状态。

chenjin-ai-website 在做一件正确的事：先把设计决策固化成文档，再让实现对齐文档。这看起来慢，但每一次「先写文档再改代码」都在降低未来的沟通成本。当项目越来越大、参与者越来越多（包括 AI agent），设计真相文件就是唯一的共识锚点。

Signal Radar 在做一件错误的事：继续用「记录失败」来代替「修复失败」。可观测性是前提，不是目的。如果连续多天全线失败而没有根因分析和修复动作，那记录就只是在积累噪音。

一个在建基础，一个在积累技术债。节奏完全不同。