Fonts

Custom themes need font files and matching font-family tokens. This guide uses the acme theme from Create a Theme and an example font named “Acme Sans”. Replace the names and paths with your own.

Add your font files

Place your font files in public/fonts/ and create src/themes/acme/fonts.css alongside the generated theme files.

src/themes/acme/fonts.css

@font-face {
  font-family: "Acme Sans";
  src: url("/fonts/AcmeSans-Regular.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: "Acme Sans";
  src: url("/fonts/AcmeSans-Medium.woff2") format("woff2");
  font-weight: 500;
  font-style: normal;
  font-display: swap;
}

Default typography uses weights 400 and 500; add a declaration for each weight and style you use. The CLI never creates or overwrites fonts.css.

Set the theme font families

Add fontFamily inside themes.acme.globalTokens:

vortex.config.ts

fontFamily: {
  heading: { family: '"Acme Sans", sans-serif' },
  body: { family: '"Acme Sans", sans-serif' },
},

bun run build:theme

Import the styles

Import the font stylesheet and generated theme once in your app's root entry:

src/main.tsx

import "./themes/acme/fonts.css";
import "./themes/acme/globals.css";

For Next.js with a root-level app/ directory, import them in the root layout:

app/layout.tsx

import "../src/themes/acme/fonts.css";
import "../src/themes/acme/globals.css";

For src/app/layout.tsx, use ../themes/acme/fonts.css and ../themes/acme/globals.css.

Adjust typography

Semantic typography tokens combine font family, size, weight, line height, and letter spacing. Add this alongside globalTokens inside themes.acme to use the 125 font-size token for the mobile bodyMdRegular style:

vortex.config.ts

semanticTokens: {
  typography: {
    bodyMdRegularMobile: {
      fontFamily: "body",
      size: "125",
      weight: "regular",
      lineHeight: "600",
      letterSpacing: "normal",
    },
  },
},

Each field references a global token. Include all five fields; see Create a Theme. Mobile and desktop styles are separate; change bodyMdRegularDesktop too when needed. See the typography reference for names and values.

Run bun run build:theme again. Your existing globals.css import loads the updated typography.

Default Vortex theme

The default vortex theme uses Hellix for headings and Inter for body text but doesn't load either font. Add @font-face declarations for them as in step 1, or the system font stack is used.