Font Customization

Overview

Font customization lets you match your embedded agent's typography to your product's design system. Instead of using default fonts, you can use Google Fonts or host your own custom fonts—creating a seamless experience where agents feel like a native part of your product.

You can customize:

• Font family — Use any Google Font or self-hosted custom font
• Font weights and styles — Define multiple weights (regular, bold, etc.) and styles (normal, italic)
• Typography scale — Override font sizes, weights, letter spacing, and line heights for specific UI elements

Quick Start: Using Google Fonts

The simplest way to customize fonts is to use a Google Font. Just specify the font family name in your SDK initialization.

Basic Example

const myCustomFontTheme = {
    fontFamily: 'Merriweather'
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});

This applies the Merriweather font from Google Fonts to your entire agent UI.

Available Google Fonts

Browse the complete library of Google Fonts at fonts.google.com. Any font listed there can be used with the fontFamily parameter.

Using Custom Self-Hosted Fonts

For complete control over typography, you can use self-hosted fonts. This requires hosting the font files yourself and providing additional metadata.

Requirements

Before implementing custom fonts, you'll need:

• Font files — Font files in .ttf or .otf format
• Public hosting — A publicly accessible URL where your font files are hosted
• SHA-256 checksum — The checksum of each font file for integrity verification
• File size — The exact size of each font file in bytes
• Licensing — Ensure you have proper licensing for web embedding

Implementation

const myCustomFontTheme = {
    fontFamily: 'Firago',
    fontDetails: [
        {
            fontWeight: 600,
            sha256Checksum: '0dda9d907ec201586736814689a387a36fd05ebb87ac6faebdf4f8e4299d3020',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-SemiBoldItalic.ttf',
            fileSize: 813732,
            fontStyle: 'italic',
        },
        {
            fontWeight: 700,
            sha256Checksum: '51ad0da400568385e038ccb962a692f145dfbd9071d7fe5cb0903fd2a8912ccd',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-BoldItalic.ttf',
            fileSize: 813028,
            fontStyle: 'italic',
        },
        {
            fontWeight: 500,
            sha256Checksum: '949698ddae3a568f1ada6eed12d5226d448b0b4a6600a44f096cfd9a1aabb555',
            fontUrl: 'https://raw.githubusercontent.com/bBoxType/FiraGO/master/Fonts/FiraGO_TTF_1001/Italic/FiraGO-MediumItalic.ttf',
            fileSize: 813936,
            fontStyle: 'italic',
        }
    ]
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});

Font Details Parameters

Generating Required Metadata

SHA-256 Checksum (Linux/Mac):

shasum -a 256 "$filename" | cut -d' ' -f1

File Size (Linux/Mac):

wc -c < "$filename" | tr -d ' '

Font Character Coverage

When using custom fonts, ensure they include all required characters:

• Standard alphanumeric characters
• Special symbols and punctuation
• Multilingual character sets (if your agents support multiple languages)

Missing characters will fall back to the system font, which may break your design consistency.

Customizing Typography Scale

Whether you're using Google Fonts or custom fonts, you can override specific typography styles used throughout the agent UI.

Basic Override Example

const customFontTheme = {
    fontFamily: 'Merriweather',
    textStyles: {
        titleSmall: {
            fontSize: 18,
            fontWeight: 600,
        }
    }
};

This changes only the titleSmall style—all other styles remain at their defaults.

Typography Properties

Each text style can include these properties:

Default Typography Scale

The agent UI uses typography tokens based on the Material 3 Design type scale. These tokens define consistent text styles across the interface.

Default Values

const defaultTextStyles = {
    titleLarge: {
        fontSize: 20,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.25,
    },
    titleMedium: {
        fontSize: 18,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.3,
    },
    titleSmall: {
        fontSize: 16,
        fontWeight: 500,
        letterSpacing: 0.15,
        height: 1.35,
    },
    bodyMedium: {
        fontSize: 15,
        fontWeight: 400,
        letterSpacing: 0.15,
        height: 1.6,
    },
    bodySmall: {
        fontSize: 14,
        fontWeight: 400,
        letterSpacing: 0.5,
    },
    labelLarge: {
        fontSize: 16,
        fontWeight: 500,
        letterSpacing: 0.5,
    },
    labelMedium: {
        fontSize: 14,
        fontWeight: 500,
        letterSpacing: 0.3,
        height: 1.4,
    },
    labelSmall: {
        fontSize: 12,
        fontWeight: 400,
        letterSpacing: 0.5,
    },
};

Where Typography Tokens Are Used

The agent UI applies these typography tokens to specific interface elements:

Complete Customization Example

Here's a comprehensive example showing Google Fonts with typography overrides:

const myCustomFontTheme = {
    fontFamily: 'Poppins',
    textStyles: {
        titleLarge: {
            fontSize: 22,
            fontWeight: 600,
            letterSpacing: 0.15,
            height: 1.3,
        },
        titleMedium: {
            fontSize: 18,
            fontWeight: 600,
            letterSpacing: 0.15,
            height: 1.3,
        },
        bodyMedium: {
            fontSize: 16,
            fontWeight: 400,
            letterSpacing: 0.15,
            height: 1.6,
        },
        labelLarge: {
            fontSize: 14,
            fontWeight: 500,
            letterSpacing: 0.5,
        },
    }
};

mindset.init({
    customFontTheme: myCustomFontTheme,
    // ... other initialization parameters
});

Hosting Custom Fonts

If you're using self-hosted custom fonts, you'll need to host them somewhere publicly accessible. Here are recommended hosting options:

Recommended: Cloud Storage (Production)

Best for: Production applications with high traffic

https://your-bucket.s3.amazonaws.com/fonts/YourFont.ttf

https://youraccount.blob.core.windows.net/fonts/YourFont.ttf

https://storage.googleapis.com/your-bucket/fonts/YourFont.ttf

Alternative: Static Hosting Services

Best for: Small to medium projects, prototyping

• Netlify / Vercel — Deploy fonts as static assets in your project
• Cloudflare Pages — Host fonts with automatic global CDN
• DigitalOcean Spaces — S3-compatible storage with CDN

Development Only: GitHub

Best for: Testing and development (not production)

Host font files in a public GitHub repository:

https://raw.githubusercontent.com/username/repo/branch/path-to/font.ttf

Firebase Storage

Upload fonts to Firebase Storage and set them to publicly readable:

1. Upload font files to Firebase Storage
2. Set read permissions to public
3. Generate direct download link from Firebase Console

Not Recommended: Google Drive

Best Practices

Font Selection

Match your product's design system. Use the same font family your product uses to create visual consistency.

Provide multiple weights. Include at least regular (400) and bold (700) weights for proper text hierarchy.

Test multilingual support. If your agents support multiple languages, verify your font includes all necessary character sets.

Check licensing. Ensure you have proper licensing for web embedding before using custom fonts.

Performance

Use Google Fonts when possible. They're automatically optimized, cached, and require no hosting setup.

Host custom fonts on a CDN. Use cloud storage with CDN for fast global delivery.

Limit font weights. Only include the weights you actually use to reduce load times.

Verify file sizes. Large font files (>1MB) can slow down initial load. Consider using subsets or optimized formats.

Typography Scale

Start with defaults. Test the default typography scale before customizing.

Override selectively. Only customize the tokens that need to match your design system.

Maintain readability. Ensure font sizes, weights, and line heights provide comfortable reading experiences.

Test across devices. Verify your typography works well on mobile, tablet, and desktop screens.

Backward Compatibility

The SDK maintains backward compatibility for font configuration:

No customization provided:

• Uses default Poppins font family
• Applies default text styles

Font family only (no text styles):

• Uses provided font family
• Applies default text styles

Text styles only (no font family):

• Uses default Poppins font family
• Applies provided text styles

Font family without font details:

• Attempts to load as Google Font
• Falls back to Poppins if not found

Troubleshooting

Custom font not loading

Possible causes:

• Font URL is not publicly accessible
• CORS headers not configured properly
• Incorrect SHA-256 checksum
• Incorrect file size

Solution: Verify the font URL is publicly accessible, check hosting service CORS settings, regenerate checksums and file sizes.

Font looks incorrect or fallback is used

Possible causes:

• Missing font weights
• Font doesn't include required characters
• Font style mismatch (normal vs italic)

Solution: Provide multiple font weights in fontDetails. Verify font includes all characters used in your agents. Check that fontStyle parameter matches actual font style.

Typography doesn't match design system

Possible causes:

• Using wrong typography tokens
• Not overriding enough properties
• Line height or letter spacing too different

Solution: Review the typography token usage table. Override font size, weight, and line height together. Test changes incrementally.

Performance issues with custom fonts

Possible causes:

• Font files are too large
• Hosting service is slow
• Too many font weights loaded

Solution: Optimize font files or use subsets. Use CDN for font hosting. Limit font weights to those actually needed.