The Brand kit in Acquia Source CMS provides a central repository to manage the typography of your site. Instead of manually writing @font-face Cascading Style Sheets (CSS) or importing font packages into individual components, you can upload font files to the Brand kit a single time. Drupal Canvas generates the required CSS, loads the fonts in the editor and the published site, and provides ready-to-use code snippets for your components.

This document provides instructions about how to add, configure, and use Brand kit fonts in Drupal Canvas, including the companion Command Line Interface (CLI) workflow for teams that manage fonts in code.

Prerequisites

To use Brand kit fonts in Drupal Canvas, ensure the following: 

• Permission to administer the Brand kit. For more information, visit Managing permissions.
• Permission to publish auto-saves because the Brand kit uses the draft and auto-save system of Drupal Canvas.
• Accepted formats: WOFF2 (recommended), WOFF, TTF, and OTF. 
• Supported CLI providers: google, bunny, fontshare, fontsource, npm, and adobe.

Understanding Brand kit fonts

The Brand kit stores fonts in a single global font library shared across your entire site. Fonts are organized by font family, and each family contains multiple variants, such as different combinations of weight and style. Examples include Regular, Bold, and Italic.

After you upload a font file, Drupal Canvas reads the metadata of the file to detect the family name, weight, style, and adjustable axes for variable fonts. Drupal Canvas generates the @font-face CSS and loads the font into the editor and the front end without additional configuration.

Drupal Canvas supports static fonts, which use one file per weight and style combination, and variable fonts, which use a single file to cover a range of weights, widths, and other axes.

Accessing the Brand kit

To open the Brand kit:

1. Access your site.
2. On the top right, click Edit to open Drupal Canvas.
3. Open a page in the Drupal Canvas editor.
4. In the Canvas sidebar, click the Brand kit icon.
5. Click the Fonts tab.

Adding a font family

To add a font family:

1. Access the Brand kit.
2. In the Fonts tab, select + Upload.
3. Select one or more font files, such as .woff2, .woff, .ttf, or .otf. Multi-select to upload several variants simultaneously.

Drupal Canvas uploads each file, reads the metadata, including family name, weight, style, and variable font axes, and saves the file to the Brand kit.

The @font-face CSS is generated and loaded into the editor and the published site. If a file has no readable family name, Drupal Canvas derives a name from the filename. 

Adding a variant to an existing family

To add another weight or style, such as Bold or Italic, to a family:

1. Access the Brand kit.
2. Select the font family row to open the detail panel.
3. In the header, select Add variant.
4. Select the font files for the variant to add them to the same family.

The header displays the variant count, for example, 3 variants uploaded.

Renaming a font family

The family name is the CSS font-family value that your components reference. Select a recognizable name, such as Inter or Mona Sans.

To rename a font family:

1. Access the Brand kit.
2. Select the font family row to open the panel.
3. Edit the Family name field.
4. Click away from the field to save the changes. 

The new name applies to every variant in the family.

Configuring a static font variant

For static fonts, each variant has dedicated weight and style settings.

To configure a static font variant:

1. Access the Brand kit.
2. Open a family panel and select a variant from the list.
3. Under Variant settings, configure the settings:
   • Weight: Enter the CSS font-weight value, such as 400 for Regular or 700 for Bold. The default value is 400 if the field remains empty.
   • Style: Select Normal or Italic.

Changes save as you edit.

Configuring a variable font variant

Variable fonts expose adjustable axes detected from the font file. Instead of fixed weight and style values, you can configure each axis with a slider.

Drupal Canvas derives the CSS font-weight range and font-style from the axes. The variant label reflects the font type, such as Variable · WOFF2 or 700 Italic · TTF.

To configure a variable font variant:

1. Access the Brand kit.
2. Open a family panel and select the variable font variant.
3. Under CSS settings, adjust the slider for each detected axis:
   • wght: Weight range, such as 100 to 900
   • wdth: Width range, such as 75 to 125
   • opsz: Optical size range, such as 8 to 144
   • ital or : Italic or slant settings
4. Set the default value for each axis. 

After you save, Drupal Canvas clamps values to the minimum and maximum limits of the axis.

Previewing a font and copying code snippets

Every selected variant displays a live preview and ready-to-use code snippets.

Reviewing the live preview

A font preview card renders sample text with the uploaded font and applies your current weight, style, and axis settings. Use the preview to confirm that the font displays as intended before you apply the font to components.

To review the preview:

1. Access the Brand kit.
2. Open the font family panel and select the variant that you want to preview.

Copying code snippets

Drupal Canvas provides two code snippets with dedicated copy buttons:

• Tailwind theme (CSS): Registers the font as a Tailwind theme token. Paste this snippet into your Global CSS file or the CSS file of a component:

@theme {
  --font-inter: "Inter", sans-serif;
}

This snippet creates a font-inter utility class family.

• HTML: Demonstrates how to apply the font token in markup. For a static font:

<p class="font-inter font-[700] not-italic">
The quick brown fox jumps over the lazy dog.
</p>

For a variable font, the snippet includes the axis settings:

<p class="font-inter font-[500] not-italic [font-variation-settings:'wght'_500,'opsz'_18]">
The quick brown fox jumps over the lazy dog.
</p>

Drupal Canvas generates the @font-face rule. You require only the theme token and class from the snippets above.

Using a Brand kit font in your components

After a font is added to the Brand kit, Drupal Canvas loads the font on the page.

To apply a font to your components:

1. Register the token: Paste the Tailwind theme (CSS) snippet into the Global CSS file of your project so that the font-* utility is available to all components. Execute this step a single time per font.
2. Apply the class: In a Code Component, add the class from the HTML example snippet to the elements that you want to style, for example, class="font-inter". Place component-specific font styles in the CSS file of that component.
3. Save and preview the page: Text renders in your brand font in the editor and the published site.

Do not import font packages directly from JavaScript or TypeScript files of a component:

// Do not perform this in a Code Component
import '@fontsource/inter';

Allow the Brand kit to load the font and reference the font by its family name or Tailwind token. This practice maintains consistent font loading across the editor and the front end and prevents duplicate font loads.

Removing a font variant

To remove a font variant:

1. Access the Brand kit.
2. Open the font family panel and select the variant that you want to remove.
3. Select the trash icon next to the variant label.

If you remove the last variant in a family, Drupal Canvas removes the family. Font files are tracked through the File Usage API of Drupal and are removed when no font references remain.

Managing fonts through the CLI

Teams that manage fonts in source control or AI agents that configure sites programmatically can manage Brand kit fonts through code with Drupal Canvas CLI. Fonts managed through the CLI and fonts uploaded through the UI are stored in the same global Brand kit.

Enabling Brand kit synchronization

Brand kit synchronization is opt-in. Enable synchronization per command or with an environment variable:

npx canvas pull --include-brand-kit
npx canvas push --include-brand-kit

Or set the environment variable:

export CANVAS_INCLUDE_BRAND_KIT=true

Declaring fonts in canvas.brand-kit.json

Create a canvas.brand-kit.json file in the root directory of your project. Each font family is defined as provider-based or local:

{
  "fonts": {
    "defaults": {
      "weights": ["400"],
      "styles": ["normal"],
      "subsets": ["latin"]
    },
    "families": [
      {
        "name": "Inter",
        "provider": "google",
        "weights": ["400", "700"],
        "styles": ["normal", "italic"]
      },
      {
        "name": "My Font",
        "src": "fonts/MyFont-Regular.woff2",
        "weights": ["400"],
        "styles": ["normal"]
      }
    ]
  }
}

Provider-based fonts use name and provider. Supported providers include google, bunny, fontshare, fontsource, npm, and adobe. The npm provider resolves @fontsource/* and @fontsource-variable/* packages from node_modules. The adobe provider requires a kit ID under providers.adobe.id. Optionally specify weights, styles, subsets, and axisDefaults, which are per-axis default overrides for variable fonts, such as "axisDefaults": { "wght": 500 }.

Local file fonts use name and src, where src is a path relative to the root directory of your project.

Pushing and pulling fonts

Use the following CLI commands to manage fonts:

• canvas push --include-brand-kit: Resolves each family from the provider or local file, uploads the font files, and replaces the global Brand kit font set of the site with the contents of canvas.brand-kit.json. An empty families list clears all fonts from the Brand kit.
• canvas pull --include-brand-kit: Downloads the global Brand kit configuration into canvas.brand-kit.json and saves font files to a local fonts/ directory.

A push and subsequent pull produce no drift, duplicates, or data loss. Provider-based variable fonts have their axes extracted and human-readable axis names added, so the Brand kit UI displays the same axis sliders as fonts uploaded through the interface.

Because a push command replaces the remote font set, maintain canvas.brand-kit.json as the single source of truth when managing fonts through code. This practice prevents a push action from removing fonts added through the UI.

Brand kit fonts

@theme {
  --font-inter: "Inter", sans-serif;
}

<p class="font-inter font-[700] not-italic">
The quick brown fox jumps over the lazy dog.
</p>

<p class="font-inter font-[500] not-italic [font-variation-settings:'wght'_500,'opsz'_18]">
The quick brown fox jumps over the lazy dog.
</p>

// Do not perform this in a Code Component
import '@fontsource/inter';

npx canvas pull --include-brand-kit
npx canvas push --include-brand-kit

export CANVAS_INCLUDE_BRAND_KIT=true

{
  "fonts": {
    "defaults": {
      "weights": ["400"],
      "styles": ["normal"],
      "subsets": ["latin"]
    },
    "families": [
      {
        "name": "Inter",
        "provider": "google",
        "weights": ["400", "700"],
        "styles": ["normal", "italic"]
      },
      {
        "name": "My Font",
        "src": "fonts/MyFont-Regular.woff2",
        "weights": ["400"],
        "styles": ["normal"]
      }
    ]
  }
}