add _brand.yml support #39

.github/workflows/type.yaml

@@ -6,7 +6,7 @@ on:
   pull_request:
 
 jobs:
-  check-formatting:
+  check-typing:
     runs-on: ubuntu-latest
 
     steps:
@@ -19,7 +19,12 @@ jobs:
           enable-cache: true
 
       - name: Install the project
-        run: uv sync --all-groups
+        run: |
+          uv sync --all-groups
+          uv pip install brand_yml # for some reason I need to add this manually
 
-      - name: Run tests
+      - name: Run type check (ty)
         run: uv run ty check
+
+      - name: Run type check (pyrefly)
+        run: uv run pyrefly check

.gitignore

@@ -17,3 +17,4 @@ sandbox*
 uv.lock
 
 scripts/release.sh
+_brand.yml

README.md

@@ -32,12 +32,15 @@ function.
 
 ## Themes
 
-**`morethemes`** offers 16 themes at the moment:
+**`morethemes`** offers 16 built-in themes, as well as a special ‘brand’
+theme, based the [\_brand.yml
+specification](https://posit-dev.github.io/brand-yml/):
 
 ### WSJ
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("wsj")
 ```
 
@@ -47,6 +50,7 @@ mt.set_theme("wsj")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("urban")
 ```
 
@@ -56,6 +60,7 @@ mt.set_theme("urban")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("minimal")
 ```
 
@@ -65,6 +70,7 @@ mt.set_theme("minimal")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("ft")
 ```
 
@@ -74,6 +80,7 @@ mt.set_theme("ft")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("nature")
 ```
 
@@ -83,6 +90,7 @@ mt.set_theme("nature")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("economist")
 ```
 
@@ -92,6 +100,7 @@ mt.set_theme("economist")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("greenwave")
 ```
 
@@ -101,6 +110,7 @@ mt.set_theme("greenwave")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("lumen")
 ```
 
@@ -110,6 +120,7 @@ mt.set_theme("lumen")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("ebonis")
 ```
 
@@ -119,6 +130,7 @@ mt.set_theme("ebonis")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("lighter")
 ```
 
@@ -128,6 +140,7 @@ mt.set_theme("lighter")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("vscode-dark")
 ```
 
@@ -137,6 +150,7 @@ mt.set_theme("vscode-dark")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("nord")
 ```
 
@@ -146,6 +160,7 @@ mt.set_theme("nord")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("retro")
 ```
 
@@ -155,6 +170,7 @@ mt.set_theme("retro")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("darker")
 ```
 
@@ -164,6 +180,7 @@ mt.set_theme("darker")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("yellowish")
 ```
 
@@ -173,7 +190,20 @@ mt.set_theme("yellowish")
 
 ``` python
 import morethemes as mt
+
 mt.set_theme("monoblue")
 ```
 
 [![](https://raw.githubusercontent.com/y-sunflower/morethemes/refs/heads/main/docs/img/monoblue.png)](https://y-sunflower.github.io/morethemes/)
+
+### BRAND
+
+The `brand` theme reads a Posit
+[`_brand.yml`](https://posit-dev.github.io/brand-yml/) file and
+generates Matplotlib rcParams from its colors and typography.
+
+``` python
+import morethemes as mt
+
+mt.set_theme("brand")
+```

docs/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

docs/README.qmd

@@ -16,8 +16,6 @@ default-image-extension: ""
 
 [Documentation site](https://y-sunflower.github.io/morethemes/)
 
-
-
 <br>
 
 ## Installation
@@ -28,6 +26,7 @@ pip install morethemes
 
 Don't want to add **`morethemes`** as a dependency? You can either browse the [source code](https://github.com/y-sunflower/morethemes/blob/main/morethemes/themes.py) to find the rcParams, or use the `mt.get_rcparams("theme_name")` function.
 
+
 <br>
 
 ## Themes
@@ -40,9 +39,12 @@ Don't want to add **`morethemes`** as a dependency? You can either browse the [s
 import morethemes as mt
 import matplotlib.pyplot as plt
 
-print(f"**`morethemes`** offers {len(mt.ALL_THEMES)} themes at the moment:\n")
+static_themes = [theme for theme in mt.ALL_THEMES if theme != "brand"]
+print(
+    f"**`morethemes`** offers 16 built-in themes, as well as a special 'brand' theme, based the [_brand.yml specification](https://posit-dev.github.io/brand-yml/):\n"
+)
 
-for theme in mt.ALL_THEMES:
+for theme in static_themes:
     print(f"### {theme.upper()}\n\n")
     print("```python")
     print("import morethemes as mt")
@@ -55,4 +57,13 @@ for theme in mt.ALL_THEMES:
         f"[![](https://raw.githubusercontent.com/y-sunflower/morethemes/refs/heads/main/docs/img/{theme}.png)](https://y-sunflower.github.io/morethemes/)"
     )
     print("\n")
+
+print("### BRAND\n\n")
+print(
+    "The `brand` theme reads a Posit [`_brand.yml`](https://posit-dev.github.io/brand-yml/) file and generates Matplotlib rcParams from its colors and typography.\n"
+)
+print("```python")
+print("import morethemes as mt")
+print('mt.set_theme("brand")')
+print("```\n")
 ```

docs/contributing.md

@@ -40,9 +40,9 @@ uv run pytest
 
 ```python
 sunglasses_theme = {
-    "name": "sunglasses", # the name of your theme
+    "name": "sunglasses",  # the name of your theme
     "description": "A description of the theme",
-    "theme": { # all arguments passed to plt.rcParams
+    "theme": {  # all arguments passed to plt.rcParams
         "axes.facecolor": "#232323",
         "figure.facecolor": "#282828",
     },
@@ -59,7 +59,7 @@ sunglasses_theme = {
 ALL_THEMES = {
     "darker": darker_theme,
     "lighter": lighter_theme,
-    "sunglasses": sunglasses_theme, # add your theme here
+    "sunglasses": sunglasses_theme,  # add your theme here
 }
 ```
 

docs/guide/create-your-theme.md

@@ -69,6 +69,7 @@ For example, when I set the theme to `darker`, it will call all parameters of th
 
 ```python
 import morethemes as mt
+
 mt.set_theme("darker")
 ```
 
@@ -131,13 +132,13 @@ plt.rcParams.keys()
 Colors is the main thing that changes in a theme. Here you'll find every param name that you might need:
 
 ```python
-plt.rcParams["axes.facecolor"] = "black"     # Axes color
-plt.rcParams["figure.facecolor"] = "black"   # Figure color
-plt.rcParams["axes.labelcolor"] = "grey"     # Label color
-plt.rcParams["axes.edgecolor"] = "grey"      # Spines color
-plt.rcParams["xtick.color"] = "grey"         # x tick color
-plt.rcParams["ytick.color"] = "grey"         # y tick color
-plt.rcParams["text.color"] = "white"         # Text color
+plt.rcParams["axes.facecolor"] = "black"  # Axes color
+plt.rcParams["figure.facecolor"] = "black"  # Figure color
+plt.rcParams["axes.labelcolor"] = "grey"  # Label color
+plt.rcParams["axes.edgecolor"] = "grey"  # Spines color
+plt.rcParams["xtick.color"] = "grey"  # x tick color
+plt.rcParams["ytick.color"] = "grey"  # y tick color
+plt.rcParams["text.color"] = "white"  # Text color
 ```
 
 By default, matplotlib charts will be <span style="color: #1f77b4;">**blue**</span>. But if your chart has 2 colors, by default, the colors will be <span style="color: #1f77b4;">**blue**</span> and <span style="color: #ff7f0e;">**orange**</span>. If there are 3, the colors will be <span style="color: #1f77b4;">**blue**</span>, <span style="color: #ff7f0e;">**orange**</span> and <span style="color: #2ca02c;">**green**</span>. This will continue with 7 other colors.
@@ -146,8 +147,9 @@ This is called a `prop_cycle`. Changing this parameter will also to change defau
 
 ```python
 from cycler import cycler
+
 plt.rcParams["axes.prop_cycle"] = cycler(
-   "color", ["#FED789", "#A4BED5", "#72874E", "#023743", "#476F84", "#453947"]
+    "color", ["#FED789", "#A4BED5", "#72874E", "#023743", "#476F84", "#453947"]
 )
 ```
 
@@ -156,20 +158,20 @@ plt.rcParams["axes.prop_cycle"] = cycler(
 You can control the appearance of spines around matplotlib Axes with the following parameters:
 
 ```python
-plt.rcParams["axes.spines.top"] = False       # Remove top spine
-plt.rcParams["axes.spines.bottom"] = False    # Remove bottom spine
-plt.rcParams["axes.spines.right"] = False     # Remove right spine
-plt.rcParams["axes.spines.left"] = False      # Remove left spine
-plt.rcParams["axes.edgecolor"] = "#eeeeee"    # Spine color
-plt.rcParams["axes.linewidth"] = 1.5          # Spine width
+plt.rcParams["axes.spines.top"] = False  # Remove top spine
+plt.rcParams["axes.spines.bottom"] = False  # Remove bottom spine
+plt.rcParams["axes.spines.right"] = False  # Remove right spine
+plt.rcParams["axes.spines.left"] = False  # Remove left spine
+plt.rcParams["axes.edgecolor"] = "#eeeeee"  # Spine color
+plt.rcParams["axes.linewidth"] = 1.5  # Spine width
 ```
 
 ### Fonts
 
 It is highly recommended to use a specific font for a theme, as it plays a major role in the brand image.
 
 ```python
-plt.rcParams['font.family'] = _set_family("Font Name")
+plt.rcParams["font.family"] = _set_family("Font Name")
 ```
 
 ### Others

docs/guide/reference.md

@@ -6,17 +6,35 @@ This document explains everything you need to get started using **`morethemes`**
 
 `mt.set_theme()` is the **main function** you'll need. It basically has 2 arguments:
 
-- `theme_name`: the name of the theme you want to apply. It must be one of the available themes: _"wsj"_, _"urban"_, _"minimal"_, _"ft"_, _"nature"_, _"economist"_, _"retro"_, _"yellowish"_, _"darker"_, _"monoblue"_.
+- `theme_name`: the name of the theme you want to apply. It can be a built-in theme or `"brand"`.
 - `reset_to_default`: whether to reset to default matplotlib theme before applying the theme. If not, themes can stack on top of each other. Default is `True` (and recommended).
 
 Once the function is called, it will apply the theme to the **global matplotlib configuration**. You can reset to default theme by calling `mt.set_theme("default")`
 
 ```python
 import morethemes as mt
 
-mt.set_theme("wsj") # Wall Street Journal
+mt.set_theme("wsj")  # Wall Street Journal
 ```
 
+### The `brand` theme
+
+The `brand` theme reads a Posit [`_brand.yml`](https://posit-dev.github.io/brand-yml/) file and generates Matplotlib rcParams from its colors and typography. Install the optional dependency first:
+
+```bash
+pip install "morethemes[brand]"
+```
+
+Then call it from a project containing `_brand.yml` (or configure the path using the `brand_yml` package's supported discovery settings):
+
+```python
+import morethemes as mt
+
+mt.set_theme("brand")
+```
+
+The generated theme uses the brand foreground/background colors, primary and secondary colors, palette colors for the plot color cycle, and base/heading typography settings supported by Matplotlib. System and Google fonts are supported; local-file and Bunny font sources are not.
+
 <br>
 
 ## `mt.get_rcparams()`
@@ -29,6 +47,8 @@ import morethemes as mt
 wsj_rcparams = mt.get_rcparams("wsj")
 ```
 
+`mt.get_rcparams("brand")` dynamically parses the discovered `_brand.yml` file and returns the generated rcParams.
+
 Then you can apply them to your matplotlib configuration with:
 
 ```python