用途
brand-yml 用于为 Quarto 项目创建 _brand.yml 品牌标识文件，将品牌颜色、排版和标识信息以结构化 YAML 格式保存。当用户需要生成、修复、扩展或现代化品牌文件时可以使用该技能。
主要能力
- 从多种来源提取品牌信息：网站 URL、上传的品牌指南（PDF、图片或文档）、手动文字描述，或已有的 _brand.yml 文件。
- 从网页中提取 CSS 自定义属性、meta 主题色、显著十六进制色值、font-family 声明和 Open Graph 元数据；若页面链接了 CSS 文件也会一并获取，并查找 Google Fonts 或 Bunny Fonts 的 link 标签。
- 从品牌指南中提取具名颜色（含十六进制值）、字体族、使用规则（标题与正文分别使用哪种字体）以及 logo 文件引用。
- 通过网页搜索补全信息：将专有或未知字体匹配到最接近的 Google Fonts 替代字体（并在 YAML 注释中标注替换和原字体名）；验证知名品牌的精确十六进制色值；检查 Google Fonts 可用的字重和样式。
- 按规范组装 _brand.yml，并执行校验。
使用方式
技能首先要求阅读完整规范文档 references/brand-yml-spec.md，其中包含所有允许字段、语法变体和完整注释示例。
工作流分为五步：
- 收集品牌信息：确定输入来源。若来源不明确，询问用户偏好。
- 研究与补全：使用网页搜索填补空缺。
- 组装 _brand.yml：遵循严格的结构、排版和 logo 规则。
- 校验：检查调色板引用是否存在、别名是否有循环引用、字体族是否有匹配条目、typography.base 中是否误含 color 键、source: file 字体是否至少有一个 files 条目、YAML 语法是否有效、十六进制色值是否加引号等。
- 交付输出：简单品牌（少于约 40 行 YAML）直接在聊天中以 YAML 代码块呈现；复杂品牌或用户要求文件时，创建文件并交付。输出后附简要总结，包括提取的颜色及角色、所选字体（注明替换）、可进一步自定义的字段，以及下载 logo 或字体文件的说明。
结构规则要点
- 只包含适用的字段，空字段或默认值字段应完全省略。
- 不需要复杂映射时使用简单字符串形式。
- color.palette 保持扁平，不嵌套；名称遵循 Sass 变量约定（小写、连字符）。
- 优先使用六位十六进制色值（#RRGGBB）。
- 主题颜色字段尽量引用 color.palette 中的名称。
- 绝不在 typography.base 中设置 color，基础文字颜色自动来自 color.foreground。
排版规则要点
- source: google 或 source: bunny 时，只列出品牌实际使用的字重和样式；若默认值即可则省略 weight 和 style。
- Web 字体优先使用 source: google。
- source: file 时包含占位路径，并添加注释说明字体文件下载位置；每个 source: file 字体必须至少有一个 files 条目。
- 专有字体建议使用 Google Fonts 替代，并添加注释注明原专有字体名。
Logo 规则要点
- 使用 logos/ 目录下的占位文件路径。
- 添加注释提示用户下载 logo 文件并放在 _brand.yml 旁边。
调色板指导
- 品牌提供一系列深浅色调时，选取中间值作为调色板条目。
- 当品牌颜色自然对应 Bootstrap 主色名（blue、red、green、orange 等）时，为其创建别名。
- 尽可能将语义主题色（primary、success、warning、danger、info）映射到调色板名称。
defaults 部分
仅在用户明确要求 Bootstrap、Quarto 格式或 Shiny 主题自定义时才包含，默认不添加。
适用场景
- 为 Quarto 项目建立统一品牌视觉。
- 从现有网站或品牌指南中提取配色与字体并结构化。
- 修复、扩展或现代化已有的 _brand.yml 文件。
- 已知品牌名称但缺少精确色值时进行查证。
限制与禁止事项
- 不编造用户未提供或无法验证的颜色或字体。
- 除非明确要求，不包含 defaults 部分。
- 不在 typography.base 中使用 color。
- 不包含空节或无信息量的默认值字段。
- 不使用 RGB、HSL 或具名 CSS 颜色，始终转换为十六进制。
- 十六进制色值必须加引号（YAML 会将未加引号的 # 视为注释）。
常见模式
- 已知颜色的大学或组织：搜索官方十六进制值，使用精确值而非从截图猜测。
- 网站提取：先查找 CSS 自定义属性，再回退到关键元素的计算样式，并检查 Google Fonts 导入。
- 最小品牌：若用户只提供主色和字体名，生成仅含 color.primary、color.foreground、color.background 和 typography.base 的最小文件，不填充多余字段。