{"id":"brand-yml","name":"brand-yml","summary":"ShinyアプリやQuarto文書間で一貫したブランディングのためにbrand.ymlファイルを作成・活用しましょう。","body":"# brand.yml Skill\n\nCreate and use `_brand.yml` files for consistent branding across Shiny applications and Quarto documents.\n\n## What is brand.yml?\n\nbrand.yml is a YAML-based format that translates brand guidelines into a machine-readable file usable across Shiny and Quarto. A single `_brand.yml` file defines:\n\n- **Colors** - Palette and semantic colors (primary, success, warning, etc.)\n- **Typography** - Fonts, sizes, weights, line heights\n- **Logos** - Multiple sizes and light/dark variants\n- **Meta** - Company name, links, identity information\n\n## File Naming Convention\n\n- **Standard name**: `_brand.yml` (auto-discovered by Shiny and Quarto)\n- **Custom names**: Any name like `company-brand.yml` (requires explicit paths)\n- **Location**: Typically at project root, or in `_brand/` or `brand/` subdirectories\n\n## Decision Tree\n\nDetermine the user's goal and follow the appropriate workflow:\n\n1. **Creating a new _brand.yml file?** → Follow \"Creating brand.yml Files\"\n2. **Using brand.yml in Shiny for R?** → Read `references/shiny-r.md`\n3. **Using brand.yml in Shiny for Python?** → Read `references/shiny-python.md`\n4. **Using brand.yml in Quarto?** → Read `references/quarto.md`\n5. **Using brand.yml in R (general)?** → Read `references/brand-yml-in-r.md` (R Markdown, theming functions, programmatic access)\n6. **Modifying existing _brand.yml?** → Follow \"Modifying Existing Files\"\n7. **Troubleshooting integration?** → Follow \"Troubleshooting\"\n\n## Creating brand.yml Files\n\nWhen creating `_brand.yml` files from brand guidelines:\n\n### Step 1: Gather Information\n\nCollect brand information:\n- **Colors**: Primary, secondary, accent colors with hex values\n- **Fonts**: Font families and where they're sourced (Google Fonts, local files, etc.)\n- **Logos**: Logo file paths or URLs for different sizes\n- **Company info**: Name, website, social links (optional)\n\n### Step 2: Read the Specification\n\nLoad `references/brand-yml-spec.md` to understand the complete brand.yml structure, field options, and syntax.\n\n### Step 3: Build the File Incrementally\n\nStart with the essential sections and add optional elements:\n\n**Minimum viable _brand.yml:**\n\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```\n\n**Add colors as needed:**\n\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```\n\n**Add typography details:**\n\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```\n\n**Add logos:**\n\n```yaml\nlogo:\n  small: logos/icon.png\n  medium: logos/header.png\n  large: logos/full.svg\n```\n\n**Add meta information:**\n\n```yaml\nmeta:\n  name: Company Name\n  link: https://example.com\n```\n\n### Step 4: Apply Best Practices\n\nFollow these rules from `references/brand-yml-spec.md`:\n\n- All fields are optional - only include what's needed\n- Use hex color format: `\"#0066cc\"`\n- Prefer simple syntax (strings over objects) when possible\n- Use lowercase names with hyphens: `brand-blue`, `success-green`\n- Include `https://` in all URLs\n- Define colors/fonts before referencing them\n- For color ranges (shades/tints), choose the midpoint color\n\n### Step 5: Validate Structure\n\nCheck that:\n- YAML syntax is valid (proper indentation, quotes on hex colors)\n- Color references match palette names\n- Font families are defined before use\n- File paths are relative to `_brand.yml` location\n- All URLs include protocol (`https://`)\n\n## Modifying Existing Files\n\nWhen modifying existing `_brand.yml` files:\n\n1. **Read the current file** to understand existing structure\n2. **Consult brand-yml-spec.md** for valid field options\n3. **Maintain consistency** with existing naming patterns\n4. **Preserve references** - if other colors/elements reference a name, update consistently\n5. **Test integration** - verify changes apply correctly in Shiny/Quarto\n\nCommon modifications:\n- **Adding colors**: Add to `color.palette`, then reference in semantic colors\n- **Changing fonts**: Update in `typography.fonts`, ensure weights/styles are available\n- **Adding logo variants**: Use `light`/`dark` structure for multiple variants\n- **Light/dark mode**: Add `light` and `dark` variants to colors\n\n## Using with Shiny for R\n\nWhen the user wants to apply brand.yml to a Shiny for R app:\n\n1. **Read `references/shiny-r.md`** for complete integration guide\n2. **Key function**: `bs_theme(brand = TRUE)` or `bs_theme(brand = \"path\")`\n3. **Automatic discovery**: Place `_brand.yml` at app root\n4. **Page functions**: Works with `page_fluid()`, `page_sidebar()`, etc.\n\nQuick example:\n\n```r\nlibrary(shiny)\nlibrary(bslib)\n\nui <- page_fluid(\n  theme = bs_theme(brand = TRUE),\n  # ... UI elements\n)\n```\n\n## Using with Shiny for Python\n\nWhen the user wants to apply brand.yml to a Shiny for Python app:\n\n1. **Read `references/shiny-python.md`** for complete integration guide\n2. **Key function**: `ui.Theme.from_brand(__file__)`\n3. **Automatic discovery**: Place `_brand.yml` at app root\n4. **Installation**: Requires `pip install \"shiny[theme]\"`\n\nQuick example (Shiny Express):\n\n```python\nfrom shiny.express import ui\n\nui.page_opts(theme=ui.Theme.from_brand(__file__))\n```\n\nQuick example (Shiny Core):\n\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```\n\n## Using with Quarto\n\nWhen the user wants to apply brand.yml to Quarto documents:\n\n1. **Read `references/quarto.md`** for complete integration guide\n2. **Automatic discovery**: Place `_brand.yml` at project root with `_quarto.yml`\n3. **Supported formats**: HTML, dashboards, RevealJS, Typst PDFs\n4. **Theme layering**: Use `brand` keyword to control precedence\n\nQuick example (document):\n\n```yaml\n---\ntitle: \"My Document\"\nformat:\n  html:\n    brand: _brand.yml\n---\n```\n\nQuick example (project in `_quarto.yml`):\n\n```yaml\nproject:\n  brand: _brand.yml\n\nformat:\n  html:\n    theme: default\n```\n\n## Troubleshooting\n\n### Brand Not Applying\n\n**Shiny:**\n- Verify file is named `_brand.yml` (with underscore)\n- Check file location (app directory or parent directories)\n- Try explicit path: `bs_theme(brand = \"path/to/_brand.yml\")` or `ui.Theme.from_brand(\"path\")`\n- For Python: Ensure `libsass` is installed\n\n**Quarto:**\n- Verify `_brand.yml` is at project root\n- Ensure `_quarto.yml` exists for project-level branding\n- Try explicit path in document frontmatter\n- Check theme layering order if using custom themes\n\n### Colors Not Matching\n\n- Ensure hex colors have quotes: `\"#0066cc\"` not `#0066cc`\n- Verify color names match palette definitions exactly\n- Check semantic colors (primary, success, etc.) reference valid palette names\n- Ensure palette is defined before semantic colors\n\n### Fonts Not Loading\n\n- Verify Google Fonts spelling and availability\n- Check internet connection (required for Google Fonts)\n- Ensure `source: google` or `source: bunny` is specified\n- Verify font family names match exactly in typography elements\n- For Typst: Check font cache with `quarto typst fonts`\n\n### YAML Syntax Errors\n\n- Check indentation (use spaces, not tabs)\n- Ensure hex colors have quotes: `\"#447099\"`\n- Verify colons have space after them: `primary: blue`\n- Check list items have hyphens: `- family: Inter`\n- Use YAML validator if syntax issues persist\n\n## Reference Documentation\n\nLoad these as needed for detailed information:\n\n- **`references/brand-yml-spec.md`**: Complete brand.yml specification with all sections, fields, examples, and validation rules\n- **`references/shiny-r.md`**: Using brand.yml with Shiny for R via bslib (bs_theme, automatic discovery, Shiny-specific integration)\n- **`references/shiny-python.md`**: Using brand.yml with Shiny for Python via ui.Theme (from_brand(), installation, performance)\n- **`references/quarto.md`**: Using brand.yml with Quarto (formats, light/dark mode, layering, extensions, Typst)\n- **`references/brand-yml-in-r.md`**: General R usage including R Markdown integration, theming functions (ggplot2, gt, flextable, plotly, thematic), and programmatic brand access\n\n## Key Principles\n\n- **Start simple**: Begin with colors and one font family\n- **Keep it concise**: Only include fields directly relevant to the brand\n- **Prefer standard names**: Use Bootstrap color names when possible (blue, green, red, etc.)\n- **Use automatic discovery**: Name file `_brand.yml` for auto-detection\n- **Test across targets**: Verify brand applies correctly in all intended formats\n- **Version control**: Include `_brand.yml` in git repository\n\n## Common Patterns\n\n### Light/Dark Mode Colors\n\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\nLight/dark color modes were added in Quarto version 1.8 and currently are not supported in the R or Python brand.yml packages.\n\n### Logo Variants\n\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```\n\n### Multiple Font Weights\n\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```\n\n### Color Aliases\n\n```yaml\ncolor:\n  palette:\n    navy: \"#003366\"\n    ocean-blue: \"#0066cc\"\n    sky-blue: \"#3399ff\"\n    primary-color: ocean-blue  # Alias\n    brand-blue: ocean-blue     # Alias\n    blue: sky-blue             # Alias for primary colors\n  primary: brand-blue\n```\n\nInclude Bootstrap color names when possible, either defined directly or as aliases: `blue`, `indigo`, `purple`, `pink`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `white`, `black`. This is useful for consistency and these colors are picked up automatically by tools that use brand.yml.\n\n## Tips\n\n- **Read specification first**: Always consult `brand-yml-spec.md` when creating or modifying files\n- **Framework-specific guides**: Load the appropriate reference (shiny-r.md, shiny-python.md, quarto.md) for integration details\n- **Validate incrementally**: Start with minimal structure, test, then add complexity\n- **Use references**: Define colors in palette, then reference by name in semantic colors\n- **Standard file name**: Use `_brand.yml` for automatic discovery\n- **Explicit paths**: Use custom file names only when necessary (shared branding, multiple variants)","author":"@posit-dev","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/posit-dev/skills/tree/main/brand-yml","license":"MIT","category":"coding","lang":"en","tokens":2770,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/brand-yml-in-r.md","size":9754,"sha256":"780fb3bbe9a2750ca5b8ad6e26ee33252442111a6f2304cb94b9dfacf3ca1f40"},{"path":"references/brand-yml-spec.md","size":9652,"sha256":"4c1c8800cb9a80563a78ba3b7ac7590f775535fc91c338f04e0b9ed61e5ec606"},{"path":"references/quarto.md","size":8844,"sha256":"81427cd4b7154faa638d5e5e56a569239cca83d13f3a208bbf2d20f43e29d30e"},{"path":"references/shiny-python.md","size":7929,"sha256":"6d034f3bba828070478c62e2b8272ea6572971f2fd607b1128504d50125cf2db"},{"path":"references/shiny-r.md","size":7928,"sha256":"0109581d56119a7a6c1dbb1b06254deee018ef922da2ceec2a7039b1244cb59d"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["acmecorp.com","bsky.app","docs.acmecorp.com","mastodon.social","mycompany.com","twitter.com","www.acmecorp.com","www.facebook.com","www.linkedin.com"]}}