Skip to main content

Typography

Define typography before section components are implemented. The goal is to keep headings, paragraphs, rich text, and CMS editor previews using the same visual language instead of adding one-off text styles during development.

Relevant files in this repository:

  • apps/ui/src/lib/fonts.ts
  • apps/ui/src/app/[locale]/layout.tsx
  • apps/ui/src/components/typography/index.tsx
  • apps/ui/src/components/typography/config.ts
  • apps/strapi/src/admin/ckeditor/headings.ts
  • packages/design-system/src/fonts.css
  • packages/design-system/src/fonts/
  • packages/design-system/src/styles/typography.css
  • packages/design-system/src/styles/theme.css
Start With The Design

List the real text variants from Figma or the existing website before adding CSS. Missing this step usually creates duplicate heading classes, mismatched rich text styles, and CMS options editors should not need.

Variants​

Collect the variants the project actually needs:

  • Headings and display headings.
  • Paragraph sizes.
  • Captions and labels.
  • Button and navigation text.
  • Rich text defaults.
  • Mobile-specific adjustments.
  • Italic, cursive, or decorative variants.

Name variants by visual intent when possible. Semantic HTML tags still control document structure and accessibility, while the visual variant controls appearance.

<Typography tag="h2" variant="heading1">
Large visual heading with correct page hierarchy
</Typography>

Do not assume every h2 must look the same everywhere. If the design uses the same semantic tag with different visual treatment, create a named variant instead of overriding styles locally.

Font Imports​

Font imports are defined in:

apps/ui/src/lib/fonts.ts

Roboto is stored as local WOFF2 files in packages/design-system/src/fonts, including normal and italic variable styles. Next.js loads them without contacting Google Fonts:

import localFont from "next/font/local"

export const fontRoboto = localFont({
src: [
{
path: "../../../../packages/design-system/src/fonts/Roboto-VF.woff2",
weight: "100 900",
style: "normal",
},
{
path: "../../../../packages/design-system/src/fonts/Roboto-Italic-VF.woff2",
weight: "100 900",
style: "italic",
},
],
variable: "--font-roboto",
display: "swap",
})

When replacing Roboto, store the replacement files in the shared font directory and update both src/fonts.css and apps/ui/src/lib/fonts.ts. Keep their family names, weights, and styles aligned with the shared theme's font variable and fallback.

For static font files, import every required weight and style explicitly. For example, after adding the following files to the shared directory:

import localFont from "next/font/local"

export const fontMallory = localFont({
variable: "--font-mallory",
src: [
{
path: "../../../../packages/design-system/src/fonts/Mallory-Regular.woff2",
weight: "400",
style: "normal",
},
{
path: "../../../../packages/design-system/src/fonts/Mallory-Bold.woff2",
weight: "700",
style: "normal",
},
],
})

If the font has a dedicated italic or cursive file, import that file instead of relying only on browser-generated font-style: italic.

Following the AxiCom shared-theme pattern, packages/design-system/src/styles/theme.css connects Tailwind to the family generated by next/font/local, with a fallback for Strapi:

@theme static {
--font-sans: var(--font-roboto, "Roboto"), sans-serif;
}

Next.js defines --font-roboto on <html>. Strapi does not define that variable, so the same token resolves to "Roboto", sans-serif. No application-level font override is needed in globals.css.

packages/design-system/src/fonts.css declares the same font files for Strapi. The build copies them into dist/fonts, and the Strapi admin CSS import lets Vite process their URLs. CKEditor’s serialized CSS omits @font-face rules because URLs inside JSON strings are not processed by Vite.

Font Variables

Set the variable option in next/font and attach it to <html> in the Next.js root layout. The shared theme resolves its variables at :root, so placing the font variable only on <body> would leave the theme using its fallback. Strapi uses the fallback family declared in src/fonts.css.

Root Layout​

Attach font variables to <html> and apply the font utility to <body>:

<html lang={locale} className={fontRoboto.variable} suppressHydrationWarning>
<body className="min-h-screen font-sans antialiased">{children}</body>
</html>

In this repository this happens in:

apps/ui/src/app/[locale]/layout.tsx

Use both:

  • The font variable, for CSS variable access.
  • The Tailwind font utility, for default font application.

Adding the font class only inside nested pages or client components can cause visible font changes and layout shifts.

Shared Styles​

Reusable typography classes are defined in:

packages/design-system/src/styles/typography.css

Register each typography variant with Tailwind’s @utility directive so Tailwind tooling can recognize it for class suggestions and @apply. Put font family, font weight, spacing, and related properties directly on the variant when they are part of that variant's visual contract.

Every current typo-* utility includes font-sans, following the AxiCom pattern of defining the font family on each variant. Rich text paragraphs inherit their text color unless content formatting or another style sets it explicitly.

Simplified examples:

@utility typo-h1 {
@apply mb-2 font-sans text-4xl md:text-5xl lg:text-6xl;
}

@utility typo-p-medium {
@apply mb-0.5 font-sans text-sm;
}

Apply default styles for raw h1 through h6 tags and p inside @layer base. The default paragraph uses typo-p-medium. This lets typography utilities override the tag's default appearance, including when a component uses a different visual variant from its semantic tag.

Reuse these utilities with @apply in the selector groups for CKEditor content, CKEditor style previews, and TipTap content. Keep these scoped rules outside CSS layers to preserve editor overrides and ensure stored CMS content receives styles even when Tailwind does not detect its classes in source files.

When changing selector groups, preserve class names so CKEditor content, TipTap content, frontend rich text, and the Typography component keep matching.

Example structure:

@layer base {
h1 {
@apply typo-h1;
}

p {
@apply typo-p-medium;
}
}

.ck-editor-ui h1,
.ck-editor-ui .typo-h1,
.ck-editor__main .ck-content h1,
.ck-editor__main .ck-content .typo-h1,
.ck .ck-style-grid__button__preview .typo-h1,
.tip-tap-editor-wrapper h1,
.tip-tap-editor-wrapper .typo-h1 {
@apply typo-h1;
}

For broader editor setup, see Rich Text Editors.

Typography Component​

Frontend semantic text should use the shared Typography component:

apps/ui/src/components/typography/index.tsx

It lets the caller choose:

  • The rendered HTML tag.
  • The visual typography variant.
  • Optional text color and font weight variants.

Available variants are mapped in:

apps/ui/src/components/typography/config.ts

Example:

export const variantStyles = {
heading1: "typo-h1",
heading2: "typo-h2",
heading3: "typo-h3",
heading4: "typo-h4",
heading5: "typo-h5",
heading6: "typo-h6",
small: "typo-p-small",
medium: "typo-p-medium",
large: "typo-p-large",
}

Default variants are defined per tag in defaultStyles, so components usually do not need to specify a variant explicitly.

Keep Tags And Variants Separate

Use the tag for semantic structure and the variant for visual style. This keeps accessibility decisions separate from design decisions.

CMS Sync​

When typography classes are changed or redefined, update Strapi options only when editors should be able to select the variant.

CKEditor typography options live in:

apps/strapi/src/admin/ckeditor/headings.ts

The styleVariants constant should mirror the frontend variants exposed to content editors:

Simplified structure:

const styleVariants = [
{ label: "Default", class: "typo-none" },
{ label: "Heading 1", class: "typo-h1" },
{ label: "Heading 2", class: "typo-h2" },
{ label: "Paragraph Small", class: "typo-p-small" },
{ label: "Paragraph Medium", class: "typo-p-medium" },
{ label: "Paragraph Large", class: "typo-p-large" },
] as const

Variant Decisions​

Decide which values belong directly in a typography variant and which should stay configurable.

For headings, fixed font family, weight, and color often make sense because heading styles should remain visually consistent.

For rich text, hardcoding these values can reduce flexibility. Rich text content often receives styling from a Strapi component, page-builder wrapper, or theme setting.

Before adding a variant, decide:

  • Is the visual style globally reusable?
  • Is it tied to a specific section?
  • Should editors control color or font weight from the CMS?
  • Should the style apply inside rich text?
  • Is the HTML tag separate from the visual variant?

Avoid overriding typography with !important. Prefer creating a named variant when a new visual style is needed.

Avoid Local Overrides

If several components need the same text style, add a typography variant. Local Tailwind overrides make frontend components and CMS-rendered content drift apart.

Change Checklist​

When adding or changing a typography variant, update the relevant files together:

  • packages/design-system/src/styles/typography.css for .typo-* styles and rich text selectors.
  • apps/ui/src/components/typography/config.ts for variantStyles, defaultStyles, and optional color or weight variants.
  • apps/strapi/src/admin/ckeditor/headings.ts when CKEditor should expose the variant to editors.
  • packages/design-system/src/styles/theme.css if the change needs new font or spacing tokens, and packages/design-system/src/styles/colors.css for color tokens.