Represents the typographic choices of a brand.
This class defines the structure and behavior of typography settings, including fonts, base text, headings, monospace text, and links.
This minimal example chooses only the font family for the base text, headings and monospace. These fonts will be sourced, by default, from Google Fonts.
By default, fonts are sourced from Google Fonts, but you can also provide font sources in fonts. Here we’re using a system font for “Open Sans” and Google Fonts for the others.
In addition to setting the font family for key elements, you can choose other typographic properties. This example sets the line height and font size for base text, uses the primary accent color for headings and reduces the font size for monospace code, in addition to choosing the font family for each.
Font files may be sourced in a number of different ways.
Each font family should be declared in a list item provided to typography.fonts. Local font files can be stored adjacent to the _brand.yml file, and each file for a given family needs to be declared in the files key. Typically these font files cover a specific font weight and style.
_brand.yml
color:
primary: '#f24242'
typography:
fonts:
# Local files
- family: Open Sans
source: file
files:
- path: fonts/open-sans/OpenSans-Variable.ttf
- path: fonts/open-sans/OpenSans-Variable-Italic.ttf
style: italic
# Online files
- family: Closed Sans
source: file
files:
- path: https://example.com/Closed-Sans-Bold.woff2
weight: bold
- path: https://example.com/Closed-Sans-Italic.woff2
style: italic
# Online Font Foundries
- family: Roboto Slab
source: google
weight: 600..900
style: normal
display: block
- family: Fira Code
source: bunny
# weight: [100, 200, 300, 400, 500, 600, 700, 800, 900]
# style: [normal, italic]
base:
family: Open Sans
line-height: 1.25
size: 1rem
headings:
family: Roboto Slab
color: primary
weight: 600
monospace:
family: Fira Code
size: 0.9emColors in the typographic elements—color or background-color—can use the names of colors in color.palette or the theme color names in color.
_brand.yml
color:
palette:
red: '#FF6F61'
primary: '#87CEEB'
secondary: '#50C878'
danger: red
foreground: '#1b1818'
background: '#f7f4f4'
typography:
headings:
color: primary
monospace-inline:
color: background
background-color: red
monospace-block:
color: foreground
background-color: background
link:
color: dangerlist[BrandTypographyFontFamily]
A list of font family definitions. Each definition in the list describes a font family that is available to the brand. Fonts may be stored in files (either adjacent to _brand.yml or hosted online) or may be provided by Google Fonts or Font Bunny (a GDPR-compliant Google Fonts alternative).
BrandTypographyBase | None
The type used as the default text, primarily in the document body.
BrandTypographyHeadings | None
The type used for headings. Note that these settings cover all heading levels (h1, h2, etc.).
BrandTypographyMonospace | None
The type used for code blocks and other monospaced text.
BrandTypographyMonospaceInline | None
The type used for inline code; inherits properties from monospace.
BrandTypographyMonospaceBlock | None
The type use for code blocks; inherits properties from monospace.
BrandTypographyLink | None
Type settings used for hyperlinks.
| Name | Description |
|---|---|
| fonts_css_include | Generates CSS include statements for the defined fonts. |
| fonts_html_dependency | Generate an HTMLDependency for the font CSS and font files. |
| fonts_write_css | Writes fonts.css into a directory, with copies of local fonts. |
Generates CSS include statements for the defined fonts.
This method creates CSS @import or @font-face rules for all fonts defined in the typography configuration.
| Name | Type | Description |
|---|---|---|
| str | A string containing CSS include statements for all defined fonts. |
Generate an HTMLDependency for the font CSS and font files.
This method creates an HTMLDependency object for the font CSS file and supporting font files written by the .fonts_html_dependency() method. It’s useful for integrating the font styles into web or Shiny applications that use htmltools.
| Name | Type | Description |
|---|---|---|
HTMLDependency | None |
An htmltools.HTMLDependency object if typography includes font file definitions or None if no font CSS is needed. |
Writes fonts.css into a directory, with copies of local fonts.
Writes a fonts.css file (or file_css) into path_dir and copies any local fonts into the directory as well.
| Name | Type | Description |
|---|---|---|
| Path | None | Returns the path to the directory where the files were written, i.e. path_dir. |
typography
Typography module for brand configuration and management.
This module provides classes and utilities for defining and managing typographic choices in brand guidelines.
| Name | Description |
|---|---|
| BrandTypographyFontFamily | Runtime representation of an annotated type. |
| Name | Description |
|---|---|
| BrandTypographyFontSource | A base class representing a font source. |
| BrandTypographyFontFiles | A font family defined by a collection of font files. |
| BrandTypographyFontGoogle | A font family provided by Google Fonts. |
| BrandTypographyFontBunny | A font family provided by Bunny Fonts. |
| BrandTypographyGoogleFontsApi | A font source that utilizes the Google Fonts (or a compatible) API. |
| BrandTypographyGoogleFontsWeightRange | Represents a range of font weights for Google Fonts. |
| BrandTypographyBase | Typographic settings for base (or body) text. |
| BrandTypographyHeadings | Typographic settings for headings and titles. |
| BrandTypographyMonospace | Typographic settings for monospace text. |
| BrandTypographyMonospaceInline | Typographic settings for inline monospace text. |
| BrandTypographyMonospaceBlock | Typographic settings for block monospace text. |
| BrandTypographyLink | Typographic settings for hyperlinks. |
A base class representing a font source.
This class serves as a template for various font sources, encapsulating common properties and behaviors.
| Name | Description |
|---|---|
| family | The font family name. |
| source | The source of the font family, one of "system", "file", "google", or "bunny". |
| Name | Description |
|---|---|
| to_css | Create the CSS declarations needed to use the font family. |
Create the CSS declarations needed to use the font family.
A font family defined by a collection of font files.
This class represents a font family that is specified using individual font files, either from local files or files hosted online. A font family is generally composed of multiple font files for different weights and styles within the same family. Currently, TrueType (.ttf), OpenType (.otf), and WOFF (.woff or .woff2) formats are supported.
typography:
fonts:
# Local font files
- family: Open Sans
files:
- path: fonts/open-sans/OpenSans-Bold.ttf
style: bold
- path: fonts/open-sans/OpenSans-Italic.ttf
style: italic
# Online files
- family: Closed Sans
files:
- path: https://example.com/Closed-Sans-Bold.woff2
weight: bold
- path: https://example.com/Closed-Sans-Italic.woff2
style: italicA font family provided by Google Fonts.
This class represents a font family that is sourced from Google Fonts. It allows you to specify the font family name, weight range, and style.
Subclass of brand_yml.typography.BrandTypographyGoogleFontsApi, the generic Google Fonts API font source.
In this example, the Inter font is imported with all font weights and both normal and italic styles (these are the defaults). Additionally, the Roboto Slab font is sourced from Google Fonts with three specific font weights – 400, 600, 800 – and only the normal style.
yaml typography: fonts: - family: Inter source: google - family: Roboto Slab source: google weight: [400, 600, 800] style: normal
A font family provided by Bunny Fonts.
This class represents a font family that is sourced from Bunny Fonts. It allows you to specify the font family name, weight range, and style.
Subclass of brand_yml.typography.BrandTypographyGoogleFontsApi, the generic Google Fonts API font source.
In this example, the Fira Code font is sourced from Bunny Fonts. By default all available weights and styles will be used.
A font source that utilizes the Google Fonts (or a compatible) API.
This class provides a way to fetch and manage typography assets from Google Fonts, allowing for easy integration with brand-specific typographic styles.
| Name | Description |
|---|---|
| display | Specifies how a font face is displayed based on whether and when it is downloaded and ready to use. |
| style | The font style(s) (italic or normal) to be imported for the font family. |
| url | URL of the Google Fonts-compatible API. (Primarily for internal use.) |
| version | Google Fonts API version. (Primarily for internal use.) |
| weight | The desired front weights to be imported for the font family. |
| Name | Description |
|---|---|
| to_import_url | Returns the URL for the font family to be used in a CSS @import statement. |
Returns the URL for the font family to be used in a CSS @import statement.
Represents a range of font weights for Google Fonts.
This class is used to specify a continuous range of font weights to be imported from Google Fonts for variable fonts that support a range of font weights. The weight range is represented as a list of two integers, where the first integer is the start of the range and the second is the end.
300..700: Represents a range from light (300) to bold (700)100..900: Represents the full range of weights from thin to blackWhen serialized, this class will convert the range to a string format (e.g., “300..700”) for compatibility with the Google Fonts API.
list[BrandTypographyFontWeightInt]
A list containing two integers representing the start and end of the weight range.
| Name | Description |
|---|---|
| model_dump | Usage docs: https://docs.pydantic.dev/2.10/concepts/serialization/#modelmodel_dump |
typography.BrandTypographyGoogleFontsWeightRange.model_dump(
mode='python',
include=None,
exclude=None,
context=None,
by_alias=False,
exclude_unset=False,
exclude_defaults=False,
exclude_none=False,
round_trip=False,
warnings=True,
serialize_as_any=False,
)Usage docs: https://docs.pydantic.dev/2.10/concepts/serialization/#modelmodel_dump
Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
Args: mode: The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects. include: A set of fields to include in the output. exclude: A set of fields to exclude from the output. context: Additional context to pass to the serializer. by_alias: Whether to use the field’s alias in the dictionary key if defined. exclude_unset: Whether to exclude fields that have not been explicitly set. exclude_defaults: Whether to exclude fields that are set to their default value. exclude_none: Whether to exclude fields that have a value of None. round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T]. warnings: How to handle serialization errors. False/“none” ignores them, True/“warn” logs errors, “error” raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError]. serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
Returns: A dictionary representation of the model.
Typographic settings for base (or body) text.
In some cases, you may wish to convert the base font size to an appropriate unit, such as rem (i.e. a font size relative to the root element’s font size). Use typography_base_size_unit in pydantic’s serialization context to request the units for the base font size. (Note that currently only "rem" is supported.)
The font family to be used. Note that the font family name should match a resource in typography.fonts.
The font weight (boldness) of the text.
The font size of the text. Should be a CSS length unit (e.g., 14px).
The line height of the text. Line height refers to the vertical space between lines of text.
Typographic settings for headings and titles.
The font family used for headings. Note that this should match a resource in typography.fonts.
The font weight (or boldness) of the text.
The font style for the heading, i.e., whether it should be styled in a "normal" or "italic" style.
The line height of the heading. Line height refers to the vertical space between lines of text.
The color of the text.
This example sets up typography settings for headings using the Inter font at a weight of 600 and with a line height that is 1.2 times the font size.
Typographic settings for monospace text.
This class defines general typography options for monospace text, typically used for code blocks and other programming-related content. These choices can be further refined for inline and block monospace text using brand_yml.typography.BrandTypographyMonospaceInline and brand_yml.typography.BrandTypographyMonospaceBlock respectively.
The font family to be used for monospace text. Note that the font family name should match a resource in typography.fonts.
The font weight (boldness) of the monospace text. Can be a numeric value between 100 and 900, or a string like “normal” or “bold”.
The font size of the monospace text. Should be a CSS length unit (e.g., “0.9em”, “14px”).
This example sets up typography settings for monospace text using the Fira Code font at a slightly smaller size than the base text:
You can also specify additional properties like weight:
For more complex setups, you can define different styles for inline and block monospace text:
Typographic settings for inline monospace text.
This class defines typography options for inline monospace text, typically used for code snippets or technical terms within regular text. It inherits properties from brand_yml.typography.BrandTypographyMonospace with additional options for foreground and background colors.
The font family to be used for inline monospace text. Note that the font family name should match a resource in typography.fonts.
The font weight (boldness) of the inline monospace text. Can be a numeric value between 100 and 900, or a string like “normal” or “bold”.
The font size of the inline monospace text. Should be a CSS length unit (e.g., “0.9em”, “14px”).
The color of the inline monospace text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
The background color of the inline monospace text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
This example sets up typography settings for inline monospace text using the Fira Code font at a slightly smaller size than the base text, with custom colors:
typography:
fonts:
- family: Fira Code
source: bunny
monospace:
family: Fira Code
size: 0.9em
monospace-inline:
color: "#7d12ba" # purple
background-color: "#f8f9fa" # light grayYou can also use color names defined in your brand’s color palette:
Typographic settings for block monospace text.
This class defines typography options for block monospace text, typically used for code blocks or other larger sections of monospaced content. It inherits properties from brand_yml.typography.BrandTypographyMonospace and adds options for line height, foreground color, and background color.
The font family to be used for block monospace text. Note that the font family name should match a resource in typography.fonts.
The font weight (boldness) of the block monospace text. Can be a numeric value between 100 and 900, or a string like “normal” or “bold”.
The font size of the block monospace text. Should be a CSS length unit (e.g., “0.9em”, “14px”).
The line height of the block monospace text. Line height refers to the vertical space between lines of text.
The color of the block monospace text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
The background color of the block monospace text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
This example sets up typography settings for block monospace text using the Fira Code font at a slightly smaller size than the base text, with custom colors:
Typographic settings for hyperlinks.
This class defines typography options for hyperlinks, allowing customization of font weight, colors, and text decoration.
The font weight (boldness) of the hyperlink text. Can be a numeric value between 100 and 900, or a string like “normal” or “bold”.
The color of the hyperlink text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
The background color of the hyperlink text. Can be any CSS-compatible color definition or a reference to a color defined in the brand’s color palette.
str | None
The text decoration for the hyperlink. Common values include “underline”, “none”, or “underline”.
This example sets up typography settings for hyperlinks with a custom color and text decoration:
You can also use color names defined in your brand’s color palette: