# Findings & Decisions

## Requirements

- 把本次主题创作的经验、教训和方法写成一个本地 Skill。
- Skill 放在项目的 `.codex/skills/` 下。
- 后续创建其他主题时能够直接触发和复用。
- 保留现有主题概念图、素材板、切片和研究产物，不做资产清理。

## Research Findings

- `skill-creator` 要求从零创建 Skill 时必须使用 `init_skill.py`，完成后运行 `quick_validate.py`。
- Skill frontmatter 只允许 `name` 与 `description`；触发条件必须完整写进 description。
- `agents/openai.yaml` 应包含 `display_name`、25–64 字符的 `short_description`，以及显式提到 `$create-cc-web-theme` 的 `default_prompt`。
- Skill 应采用渐进披露：SKILL.md 保留核心流程，案例教训与细节放进一层 `references/`，避免重复。
- 当前仓库存在大量主题相关未提交改动；本任务只能新增 Skill 和任务记录，不能覆盖其他改动。
- 现有主题资料已经形成完整证据链：归档源图、切片研究、提取脚本、输出 manifest、CSS 实现、专项回归和浏览器实测记录。未来主题应复用这条链，而不是只保留最终 PNG/CSS。
- 最初“源码和回归通过即完成”的判断导致视觉验收失败。主题任务的完成门槛必须包含与参考图逐项对照的真实浏览器截图/计算样式/几何测量。
- 参考图是构图契约，不只是配色灵感。背景主角安全区、侧栏宽度、内容中心、边框轻重、图标视觉主体和层级关系都需要先量化。
- 可伸缩输入框不能把固定比例完整边框图放在 `::before` 上随容器拉伸；内容增高会导致框体偏移。最终有效方案是九宫格思路的 `border-image`，让角、边和底部装饰分别承担职责。
- “CSS 数值已更透明”不代表视觉上真的透明。嵌套工具层、旧高优先级选择器与高 blur 都可能让气泡仍像实心块；必须检查 computed style、逐层背景和实际透景。
- `:is()` 使用最高参数 specificity，后追加的低特异性规则可能只覆盖 `backdrop-filter`、覆盖不了背景色。遇到“改了没变化”时先查规则来源与 computed style，不要继续盲调数值。
- 图标需要区分容器尺寸、源图规格、alpha 主体边界和光学中心。把所有 64px 原色 PNG 一刀切缩成 22px 会产生灰边、糊边和比例失衡；主交互控件更适合清理后的 mask，多色状态/头像保留原色切图。
- 欢迎页同时存在静态首屏与动态 `buildWelcomeMarkup`，任何结构或文案修改必须双路径同步，并用回归断言防止静态写死动态数据。
- 浏览器几何验收能快速识别“看着不正”：欢迎卡曾偏左约 147px，加入 `margin: 0 auto` 后中心误差降至约 2px；图标也应以 alpha 重心而不是画布边界衡量。
- 主题资产必须保留源概念图、素材板、切片坐标和提取脚本；最终资产只是派生物，后续新增功能往往需要回到源板重新切片。
- 当前 cc-web 主题架构以 `THEME_OPTIONS`、`html[data-theme]`、首屏 bootstrap、语义变量、共享暗色 completion selector 和后置主题专属层组成；未来主题应沿用这条单源链路，不再造第二套设置列表或 body class。
- Wasteland 专项回归最终覆盖了主题注册、可见性、迁移策略、动态/静态 welcome、共享 selector、本地资产格式/尺寸/hash、manifest、响应式、reduced-motion、对比度、cache bust 和防远程 URL。Skill 的验收清单应保留这些类别，但不能硬编码 Wasteland 数值。
- 隔离前向测试使用完全不同的“海底生物机械”主题请求，子代理只依赖新 Skill 即识别出主题隔离、源资产归档、动态输入框、透明嵌套层、welcome 双路径和真实浏览器门禁，证明流程能够泛化。
- 当前提取脚本证明可复现资产流程应记录：源文件、裁剪框、源规格、检测框、输出画布和派生关系。阈值与坐标属于主题案例，不应固化为跨主题常量。
- 对非对称图标，按 alpha 加权重心校正比按画布中心更可靠；对可伸缩装饰框，应优先采用九宫格/border-image 或拆分稳定区域，禁止直接横纵拉伸整张构图。

## Technical Decisions

| Decision | Rationale |
|----------|-----------|
| 项目级 Skill 路径使用 `.codex/skills/create-cc-web-theme/` | 用户明确指定，且便于随仓库复用 |
| 核心流程与案例参考分离 | 降低常驻上下文体积，同时保留本次主题的完整教训 |
| 将视觉验收作为强制门禁 | 本次多轮返工证明仅靠源码断言和回归通过无法保证与设计图一致 |
| 将“主题隔离、素材保留、动态内容、真实浏览器验证”写成硬约束 | 这些是本次最反复、代价最高的问题 |
| Skill references 至少拆分为“经验教训”和“验收清单” | 前者解释判断依据，后者为后续任务提供可执行门禁 |
| 复用现有提取脚本的方法，不把 Wasteland 坐标硬编码成通用脚本 | 不同主题素材板结构不同，错误自动化比手工确认成本更高 |
| Skill 不新增通用切片脚本 | 现有源板差异大；改为要求每个主题保存可重放的专用提取脚本和 manifest |
| Skill 使用 4 个单层 reference | 分别承载经验教训、资产方法、cc-web 架构和验收清单，避免 SKILL.md 膨胀 |
| Skill 结构验证已通过 | quick_validate、引用存在性、frontmatter 键和 openai.yaml mention 均符合规范 |

## Issues Encountered

| Issue | Resolution |
|-------|------------|
| 初始把项目级 Skill 路径说成 `.agents/skills` | 用户纠正后立即切换到 `.codex/skills`，且未创建错误目录 |
| planning-with-files 检测到根级旧计划和其他活跃计划 | 使用 `.planning/cc-web-theme-creation-skill/` 独立作用域，避免覆盖 |

## Resources

- `.trellis/tasks/07-17-gilded-wasteland-theme/`
- `.trellis/tasks/07-17-gilded-wasteland-theme/research/extract_reference_chrome.py`
- `public/assets/themes/wasteland/`
- `public/style.css`
- `public/app.js`
- `public/index.html`
- `scripts/regression.js`
- `.codex/skills/planning-with-files/`
- `/home/hdzx/.codex/skills/.system/skill-creator/`

## Visual/Browser Findings

- 视觉层的高频失败模式集中在：整体过暗、厚金边、全组件切角、图标缩放糊、边框重复、伪元素随内容错位、按钮光学不居中、气泡被嵌套层锁成实心、欢迎卡按参考构图左对齐而非画布居中。
- 有效验收至少覆盖桌面参考尺寸、常规桌面、窄屏三个视口，并记录横向溢出、主容器中心差、图标 alpha 重心、动态高度和 computed style。
- 参考图中的“磨砂”应通过真实背景细节是否可见判断；仅看 `rgba()`、`blur()` 数值会误判。