feat(theme): Branded theming via brand_yml

docs/_quarto.yml

@@ -44,3 +44,5 @@ interlinks:
       url: https://matplotlib.org/stable/
     python:
       url: https://docs.python.org/3/
+    brand-yml:
+      url: https://posit-dev.github.io/brand-yml/

pyproject.toml

@@ -52,7 +52,10 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-theme = ["libsass>=0.23.0"]
+theme = [
+    "libsass>=0.23.0",
+    "brand_yml>=0.1.0rc6"
+]
 test = [
     "pytest>=6.2.4",
     "pytest-asyncio>=0.17.2",
@@ -100,6 +103,7 @@ dev = [
     "Flake8-pyproject>=1.2.3",
     "isort>=5.10.1",
     "libsass>=0.23.0",
+    "brand_yml>=0.1.0rc5",
     "pyright>=1.1.383",
     "pre-commit>=2.15.0",
     "wheel",

shiny/_main.py

@@ -41,6 +41,7 @@ def main() -> None:
     "*.htm",
     "*.html",
     "*.png",
+    "_brand*.yml",
 )
 RELOAD_EXCLUDES_DEFAULT = (".*", "*.py[cod]", "__pycache__", "env", "venv")
 

shiny/ui/_html_deps_external.py

@@ -32,7 +32,7 @@ def shiny_page_theme_deps(theme: str | Path | Theme | ThemeProvider | None) -> T
     if theme is None:
         deps_theme = None
     elif isinstance(theme, Theme):
-        deps_theme = theme._html_dependency()
+        deps_theme = theme._html_dependencies()
     elif isinstance(theme, str) and theme.startswith(("http", "//")):
         deps_theme = head_content(link(rel="stylesheet", href=theme, type="text/css"))
     elif isinstance(theme, (str, Path)):

shiny/ui/_theme.py

@@ -7,6 +7,7 @@
 import textwrap
 from typing import Any, Literal, Optional, Sequence, TypeVar
 
+from brand_yml import Brand
 from htmltools import HTMLDependency
 
 from .._docstring import add_example
@@ -460,25 +461,29 @@ def _dep_create(self, css_path: str | pathlib.Path) -> HTMLDependency:
                 "href": css_path.name,
                 "data-shiny-theme": self.name or self._preset,  # type: ignore
             },
+            # Branded themes re-use this tempdir
+            all_files=False,
         )
 
     def _html_dependency_precompiled(self) -> HTMLDependency:
         return self._dep_create(css_path=self._dep_css_precompiled_path())
 
-    def _html_dependency(self) -> HTMLDependency:
+    def _html_dependencies(self) -> list[HTMLDependency]:
         """
         Create an `HTMLDependency` object from the theme.
 
         Returns
         -------
         :
-            An :class:`~htmltools.HTMLDependency` object representing the theme. In
-            most cases, you should not need to call this method directly. Instead, pass
-            the `Theme` object directly to the `theme` argument of any Shiny page
-            function.
+            An list of :class:`~htmltools.HTMLDependency` objects representing the
+            theme. In most cases, you should not need to call this method directly.
+            Instead, pass the `Theme` object directly to the `theme` argument of any
+            Shiny page function.
         """
+        # Note: return a list so that this method can be overridden in subclasses of
+        # Theme that want to attach additional dependencies to the theme dependency.
         if self._can_use_precompiled():
-            return self._html_dependency_precompiled()
+            return [self._html_dependency_precompiled()]
 
         css_name = self._dep_css_name()
         css_path = os.path.join(self._get_css_tempdir(), css_name)
@@ -487,7 +492,7 @@ def _html_dependency(self) -> HTMLDependency:
             with open(css_path, "w") as css_file:
                 css_file.write(self.to_css())
 
-        return self._dep_create(css_path)
+        return [self._dep_create(css_path)]
 
     def tagify(self) -> None:
         raise SyntaxError(
@@ -497,6 +502,36 @@ def tagify(self) -> None:
             "or any `shiny.ui.page_*()` function (Shiny Core)."
         )
 
+    @classmethod
+    def from_brand(cls, brand: str | pathlib.Path | Brand):
+        """
+        Create a custom Shiny theme from a `_brand.yml`
+
+        Creates a custom Shiny theme for your brand using
+        [brand.yml](https://posit-dev.github.io/brand-yml), which may be either an
+        instance of :class:`brand_yml.Brand` or a :class:`Path` used by
+        :meth:`brand_yml.Brand.from_yaml` to locate the `_brand.yml` file.
+
+        Parameters
+        ----------
+        brand
+            A :class:`brand_yml.Brand` instance, or a path to help locate `_brand.yml`.
+            For a path, you can pass `__file__` or a directory containing the
+            `_brand.yml` or a path directly to the `_brand.yml` file.
+
+        Returns
+        -------
+        :
+            A :class:`shiny.ui.Theme` instance with a custom Shiny theme created from
+            the brand guidelines (see :class:`brand_yml.Brand`).
+        """
+        from ._theme_brand import ThemeBrand  # avoid circular import
+
+        if not isinstance(brand, Brand):
+            brand = Brand.from_yaml(brand)
+
+        return ThemeBrand(brand)
+
 
 def path_pkg_preset(preset: ShinyThemePreset, *args: str) -> str:
     """