cc-web/.codex/skills/create-cc-web-theme/references/lessons-learned.md

主题创作经验教训

目录

1. 完成标准
2. 构图与装饰
3. 边框与动态尺寸
4. 图标与重复来源
5. 透明度与选择器
6. 居中、菜单与动态 DOM
7. 范围控制与缓存

1. 完成标准

教训：自动化通过不代表像设计图

症状：资产存在、选择器命中、回归全绿，但用户第一眼认为“完全不是一个东西”。

根因：回归只能证明结构契约，不能证明构图比例、边框轻重、视觉层级和图标质感。

做法：

• 把真实浏览器视觉对照列为独立完成阶段。
• 按参考图原始视口先验收，再做响应式。
• 为关键区域记录截图、几何值和 computed style。
• 用户未确认或对照差异明显时，回滚“完成”状态。

2. 构图与装饰

教训：参考图不是配色板

症状：颜色接近，但人物被遮罩压黑、侧栏比例不对、卡片堆叠、整体质感跑偏。

根因：只抽取黑、金、棕等颜色，没有量化参考图的空间、留白和主视觉安全区。

做法：先量化侧栏/顶栏/输入区比例、主视觉 bbox、阅读安全区和面板覆盖范围。

教训：主题感不是“给所有组件加边框”

症状：搜索框、消息、列表、弹层、工具块全都厚金边和切角，界面像重型游戏皮肤。

根因：把局部装饰语言泛化到所有组件。

做法：建立装饰预算。只让主按钮、输入框和少数工具框承担强边框；普通消息、列表和小标签使用轻线或无边框。

教训：先删重，再加细节

症状：越修越多伪元素、渐变、阴影和粒子，参考主体反而更弱。

做法：按“背景 → 大布局 → 面板 → 边框 → 图标 → 微交互”排序。发现层级错误时先删除多余装饰，不继续叠覆盖规则。

3. 边框与动态尺寸

教训：固定比例伪元素不适合动态输入框

症状：单行看似正确，多行内容后边框、底线或徽记偏移；窄屏出现非等比压缩。

根因：把固定 width/height 比例的整框放在 ::before/::after，它不跟随真实内容盒的边界语义。

做法：

• 动态宽高使用 border-image/九宫格。
• 把不能拉伸的徽记和可拉伸边线分开。
• 测试最短、常规和最大高度。
• focus/drag/note 状态不要用 border: 0 破坏 frame。

教训：莫名边框通常来自叠层，不是主框

症状：按钮旁多出框、输入区出现虚线、聚焦后冒出第二层边。

根因：旧 focus ring、按钮 ::after、背景素材烘焙线、主框图片内外双线同时存在。

做法：在 DevTools 逐个关闭伪元素、border、outline、box-shadow 和背景图，确定真实来源后只删那一层。

4. 图标与重复来源

教训：统一画布不等于统一视觉尺寸

症状：CSS 都是 24px，但图标仍显得过小、过大或偏心。

根因：透明画布内的 alpha 主体 bbox 不同；不同形状的光学重心也不同。

做法：记录源规格、输出画布、alpha bbox 和实际 CSS 尺寸；非对称图标按 alpha 重心校正。

教训：最大档切图缩小不一定更清晰

症状：64px 原色 PNG 缩到 18–24px 后灰边、糊、材质脏。

根因：有损素材板中的半透明暗边和高光被浏览器重采样到很小区域。

做法：主交互控件重切对应规格并制作干净 mask；多色状态和头像保留原色但独立裁切。

教训：新图标可能叠在旧图标上

症状：头像两个图、新会话加号消失/重复、发送按钮出现“一坨”。

根因：真实 DOM 已有文字、SVG 或 <img>，主题又添加了背景图或伪元素。

做法：先检查 DOM。每个语义只保留一个视觉来源；只在目标主题下隐藏原生子节点。

5. 透明度与选择器

教训：RGBA 很低仍可能看起来不透明

症状：外层气泡改为 2%–10% alpha，页面仍像实心黑卡片。

根因可能包括：

• 内层 tool-call/content/title 仍是 90% 黑底。
• blur 太高，把背景细节抹成均匀色块。
• 旧规则用更高 specificity 锁住 background。
• 伪元素仍覆盖整层。

做法：从最外层到最内层检查 computed background、background-image、opacity、backdrop-filter 和伪元素。用背景纹理是否可辨判断“透”，不用数值自我证明。

教训：backdrop-filter 变了不代表背景色也变了

症状：DevTools 显示 blur 已更新，但气泡底色完全不变。

根因：共享 :is() 规则的最高参数 specificity 超过后置主题规则。

做法：查看每个 computed 属性的获胜规则；使用同级 selector 或只对冲突属性精确增加 !important。不要把 !important 扩散到整个主题。

教训：模糊强度不是越高越有磨砂感

症状：提高 blur 后背景更像不透明色块。

根因：暗场细节被平均，透景消失。

做法：先降低染色层，再用较小 blur 配合适度 saturate/brightness；最终数值按当前背景实测，不把某个主题的 blur(3px) 当通用常量。

6. 居中、菜单与动态 DOM

教训：CSS “居中”需要测量证据

症状：代码有 flex/absolute 50%，视觉仍偏。

根因：容器本身不在画布中心、baseline 不一致、图片 alpha 主体偏心或滚动条改变内容区中心。

做法：分别测容器中心、画布中心、图标 alpha 中心和文字 line box；记录像素差后修正。

教训：菜单没显示可能是被父级裁切

症状：点击后状态正确，菜单 DOM 也存在，但看不到。

根因：列表项 overflow: hidden、错误 stacking context 或按钮被 flex 挤出。

做法：检查展开态 overflow、定位基准、z-index 和操作区尺寸。只在菜单打开时解除必要裁切。

教训：静态与动态 welcome 会漂移

症状：首次打开显示旧文案，刷新/切会话后才正确；结构修了一处另一处仍旧。

根因：index.html 与 buildWelcomeMarkup() 是两条渲染路径。

做法：结构同步，动态文案使用同一 formatter/hydration 节点；回归同时读取静态与动态源码。

7. 范围控制与缓存

教训：用户圈的是哪层，就只改哪层

症状：用户要求气泡透明，却修改了所有卡片、工具层或整页背景，导致更多视觉偏差。

做法：先用 DOM/DevTools 确认用户所指层级，明确 selector 列表；超出范围的发现只记录，不顺手实施。

教训：选择器写错会让正确元素消失

症状：加号消失或旧规则继续生效。

根因：假定 class 名，没有检查真实 DOM；新 selector 命中不存在节点，旧隐藏规则仍命中真实节点。

做法：实现前用 rg 和浏览器检查实际 class，回归断言真实节点保持所需显示状态。

教训：缓存会制造“完全没变化”的假象

做法：

• 修改 CSS/JS 后推进 cache-busting query。
• 用浏览器读取实际 <link>/<script> URL。
• 用 HTTP 请求确认最新资源内容与 200。
• 确认缓存后再判断 CSS 是否无效。

教训：并行会话会反复覆盖共享主题文件

做法：开始前审计活跃会话和脏文件；为子任务划分不重叠写入面。发现相同区块连续回写时停止互相覆盖，协调后再合并。