在 Shiny/Quarto 中统一品牌时：创建并应用…

为 Shiny for R/Python 和 Quarto 项目创建、修改、集成并排查 _brand.yml 品牌配置文件。

适用场景

解决思路

1. 文件命名与放置：标准名用 `_brand.yml`（Shiny 和 Quarto 自动发现）；自定义名如 `company-brand.yml` 需显式指定路径；通常放在项目根目录，或 `_brand/`、`brand/` 子目录。
2. 创建前收集品牌信息：颜色（主色、辅助色、强调色及 hex 值）；字体（字体系列及来源，如 Google Fonts、本地文件等）；Logo（不同尺寸的文件路径或 URL）；公司信息（名称、网站、社交链接，可选）。
3. 创建或修改前先加载 `references/brand-yml-spec.md` 掌握完整 brand.yml 结构、字段选项和语法。
4. 增量构建 `_brand.yml`：先写最小可用版本：\n```yaml\ncolor:\n palette:\n brand-blue: '#0066cc'\n primary: brand-blue\n background: '#ffffff'\n\ntypography:\n fonts:\n - family: Inter\n source: google\n weight: [400, 600]\n base: Inter\n```
5. 添加颜色：在 `color.palette` 中定义调色板，再在语义颜色中引用：\n```yaml\ncolor:\n palette:\n brand-blue: '#0066cc'\n brand-orange: '#ff6600'\n brand-gray: '#666666'\n primary: brand-blue\n secondary: brand-gray\n warning: brand-orange\n foreground: '#333333'\n background: '#ffffff'\n```
6. 添加排版细节：\n```yaml\ntypography:\n fonts:\n - family: Inter\n source: google\n weight: [400, 600, 700]\n style: [normal, italic]\n - family: Fira Code\n source: google\n weight: [400, 500]\n base:\n family: Inter\n size: 16px\n line-height: 1.5\n headings:\n family: Inter\n weight: 600\n monospace: Fira Code\n```
7. 添加 Logo：\n```yaml\nlogo:\n small: logos/icon.png\n medium: logos/header.png\n large: logos/full.svg\n```
8. 添加元信息：\n```yaml\nmeta:\n name: Company Name\n link: https://example.com\n```
9. 应用最佳实践：所有字段可选，只包含需要的内容；使用 hex 颜色格式 `\"#0066cc\"`；可能时优先用简单语法（字符串而非对象）；用小写连字符命名如 `brand-blue`、`success-green`；所有 URL 包含 `https://`；先定义颜色/字体再引用；颜色范围（明暗/色调）选择中间色。
10. 验证结构：YAML 语法有效（缩进正确、hex 颜色加引号）；颜色引用与 palette 名称一致；字体族在使用前定义；文件路径相对于 `_brand.yml` 所在位置；所有 URL 包含协议 `https://`。
11. 修改现有 `_brand.yml`：先读当前文件了解结构；查阅 `brand-yml-spec.md` 合法字段；保持现有命名模式一致；保留引用——若其他颜色/元素引用某名称，同步更新；测试集成，确认变更在 Shiny/Quarto 中正确应用。
12. 常见修改：添加颜色时先加入 `color.palette`，再在语义颜色中引用；更改字体时更新 `typography.fonts`，确保权重/样式可用；添加 Logo 变体时用 `light`/`dark` 结构；添加 light/dark 模式时为颜色增加 `light` 和 `dark` 变体。
13. Shiny for R 集成：阅读 `references/shiny-r.md`；关键函数是 `bs_theme(brand = TRUE)` 或 `bs_theme(brand = \"path\")`；将 `_brand.yml` 放在 app 根目录自动发现；可用于 `page_fluid()`、`page_sidebar()` 等页面函数。示例：\n```r\nlibrary(shiny)\nlibrary(bslib)\n\nui <- page_fluid(\n theme = bs_theme(brand = TRUE),\n # ... UI elements\n)\n```
14. Shiny for Python 集成：阅读 `references/shiny-python.md`；关键函数是 `ui.Theme.from_brand(__file__)`；将 `_brand.yml` 放在 app 根目录自动发现；需安装 `pip install \"shiny[theme]\"`。Shiny Express 示例：\n```python\nfrom shiny.express import ui\n\nui.page_opts(theme=ui.Theme.from_brand(__file__))\n```\nShiny Core 示例：\n```python\nfrom shiny import App, ui\n\napp_ui = ui.page_fluid(\n theme=ui.Theme.from_brand(__file__),\n # ... UI elements\n)\n```
15. Quarto 集成：阅读 `references/quarto.md`；将 `_brand.yml` 与 `_quarto.yml` 放在项目根目录自动发现；支持 HTML、dashboards、RevealJS、Typst PDFs；使用 `brand` 关键字控制主题层叠优先级。文档 frontmatter 示例：\n```yaml\n---\ntitle: My Document\nformat:\n html:\n brand: _brand.yml\n---\n```\n项目 `_quarto.yml` 示例：\n```yaml\nproject:\n brand: _brand.yml\n\nformat:\n html:\n theme: default\n```
16. 排查“品牌未应用”（Shiny）：确认文件名为 `_brand.yml`（带下划线）；检查文件位置（app 目录或父目录）；尝试显式路径 `bs_theme(brand = \"path/to/_brand.yml\")` 或 `ui.Theme.from_brand(\"path\")`；Python 确认已安装 `libsass`。
17. 排查“品牌未应用”（Quarto）：确认 `_brand.yml` 在项目根目录；项目级品牌需有 `_quarto.yml`；在文档 frontmatter 中尝试显式路径；若使用自定义主题，检查主题层叠顺序。
18. 排查“颜色不匹配”：确保 hex 颜色加引号：`\"#0066cc\"` 而非 `#0066cc`；确认颜色名称与 palette 定义完全一致；检查语义颜色（primary、success 等）引用有效 palette 名称；确保 palette 在语义颜色之前定义。
19. 排查“字体未加载”：验证 Google Fonts 拼写和可用性；检查网络连接（Google Fonts 需要）；确保指定 `source: google` 或 `source: bunny`；确认字体族名称在排版元素中完全匹配；Typst 用 `quarto typst fonts` 检查字体缓存。
20. 排查“YAML 语法错误”：检查缩进（用空格，不用 tab）；确保 hex 颜色加引号：`\"#447099\"`；确认冒号后有空格：`primary: blue`；检查列表项有连字符：`- family: Inter`；语法问题持续时使用 YAML validator。
21. 按需加载参考文档：`references/brand-yml-spec.md`（完整 brand.yml 规范，含所有章节、字段、示例和校验规则）；`references/shiny-r.md`（Shiny for R 通过 bslib 使用 brand.yml，含 `bs_theme`、自动发现、Shiny 集成）；`references/shiny-python.md`（Shiny for Python 通过 `ui.Theme` 使用 brand.yml，含 `from_brand()`、安装、性能）；`references/quarto.md`（Quarto 使用 brand.yml，含格式、light/dark 模式、层叠、扩展、Typst）；`references/brand-yml-in-r.md`（R 通用用法，含 R Markdown、主题函数 ggplot2/gt/flextable/plotly/thematic、程序化访问品牌）。
22. 关键原则：从简单开始，先颜色和一个字体族；保持简洁，只包含与品牌直接相关的字段；尽量用标准名称（Bootstrap 颜色名如 blue、green、red 等）；用自动发现，文件命名 `_brand.yml`；跨目标测试品牌是否在全部目标格式中正确应用；把 `_brand.yml` 纳入 git 版本控制。
23. 常见模式：light/dark 模式颜色示例：\n```yaml\ncolor:\n primary:\n light: '#0066cc'\n dark: '#3399ff'\n background:\n light: '#ffffff'\n dark: '#1a1a1a'\n foreground:\n light: '#333333'\n dark: '#e0e0e0'\n```\n注意：light/dark 颜色模式在 Quarto 1.8 加入，R/Python brand.yml 包当前不支持。
24. 常见模式：Logo 变体示例：\n```yaml\nlogo:\n images:\n logo-dark: logos/logo-dark.svg\n logo-white: logos/logo-white.svg\n icon: logos/icon.png\n small: icon\n medium:\n light: logo-dark\n dark: logo-white\n```
25. 常见模式：多字重示例：\n```yaml\ntypography:\n fonts:\n - family: Inter\n source: google\n weight: [300, 400, 500, 600, 700]\n style: [normal, italic]\n base:\n family: Inter\n weight: 400\n headings:\n family: Inter\n weight: 600\n```
26. 常见模式：颜色别名示例：\n```yaml\ncolor:\n palette:\n navy: '#003366'\n ocean-blue: '#0066cc'\n sky-blue: '#3399ff'\n primary-color: ocean-blue\n brand-blue: ocean-blue\n blue: sky-blue\n primary: brand-blue\n```\n尽量包含 Bootstrap 颜色名（可直接定义或作别名）：`blue`、`indigo`、`purple`、`pink`、`red`、`orange`、`yellow`、`green`、`teal`、`cyan`、`white`、`black`；这有助于一致性，使用 brand.yml 的工具会自动识别这些颜色。
27. 技巧：始终先读 `brand-yml-spec.md` 再创建或修改；集成细节加载对应参考（shiny-r.md、shiny-python.md、quarto.md）；增量校验，先最小结构、测试、再增加复杂度；先在 palette 定义颜色，再按名称在语义颜色中引用；用标准文件名 `_brand.yml` 自动发现；仅在必要时用自定义文件名显式路径（共享品牌、多个变体）。

适用边界 · 注意事项

• 不使用 Shiny、Quarto、bslib 或 shiny[theme] 的项目不适用。
• 需要在 R/Python 中使用 light/dark 颜色模式时不要依赖 brand.yml：R/Python brand.yml 包当前不支持，Quarto 1.8+ 才支持。
• 无网络且未配置本地字体时，不要指定 `source: google` 或 `source: bunny` 加载字体。