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() 数值会误判。

6.8 KiB Raw Permalink Blame History Unescape Escape

Findings & Decisions

Requirements

Research Findings

Technical Decisions

Issues Encountered

Resources

Visual/Browser Findings

6.8 KiB

Raw Permalink Blame History