Available from 3.5.0
Fonts (UIKit)
Fonts is the typography configuration API for customizing font families and weights across the design system in UIKit applications.
Platform availability: iOS 17.0+
When to use:
- Use the Fonts API when you need to customize typography across your app to match brand guidelines or use custom font families.
- Consider keeping the default LibreFranklin fonts when brand consistency with the Backbase design system is preferred.
Import
import BackbaseDesignSystem
API reference
DesignSystem.Fonts
The fonts configuration class for the design system.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
defaultFont |
(UIFont.TextStyle, UIFont.Weight) -> UIFont |
The fixed-size font without scaling |
|
preferredFont |
(UIFont.TextStyle, UIFont.Weight) -> UIFont |
The scaled font with dynamic type support |
Initializers
- init(fontFileNameMappings:)
- Creates a new fonts configuration with custom font file mappings.
|
Parameter |
Type |
Description |
|---|---|---|
|
fontFileNameMappings |
[UIFont.Weight: String] |
The dictionary mapping font weights to font file names |
Configuration
fontFileNameMappings
The fontFileNameMappings parameter maps UIFont.Weight values to font file names without the .ttf extension.
|
Weight |
Default Font File |
|---|---|
|
.black |
LibreFranklin-Black |
|
.bold |
LibreFranklin-Bold |
|
.heavy |
LibreFranklin-ExtraBold |
|
.light |
LibreFranklin-Light |
|
.medium |
LibreFranklin-Medium |
|
.regular |
LibreFranklin-Regular |
|
.semibold |
LibreFranklin-SemiBold |
|
.thin |
LibreFranklin-Thin |
|
.ultraLight |
LibreFranklin-ExtraLight |
Usage
Basic usage
To change the fonts used by the design system, override the font file name mappings:
DesignSystem.shared.fonts = DesignSystem.Fonts(fontFileNameMappings: [
.black: "LibreFranklin-Black",
.bold: "LibreFranklin-Bold",
.heavy: "LibreFranklin-ExtraBold",
.ultraLight: "LibreFranklin-ExtraLight",
.light: "LibreFranklin-Light",
.medium: "LibreFranklin-Medium",
.regular: "LibreFranklin-Regular",
.semibold: "LibreFranklin-SemiBold",
.thin: "LibreFranklin-Thin"
])
Custom font handling
If you need complete control over font handling, override the following variables:
DesignSystem.shared.fonts.preferredFont = { style, weight in
return UIFont(...)
}
DesignSystem.shared.fonts.defaultFont = { style, weight in
return UIFont(...)
}
Warning: Do not return a scaled font using the UIFontMetrics.scaledFont API in the defaultFont property as it may cause crashes.
Legacy
You can customise your app's fonts by changing the font name mapping in the token JSON file exported via the Backbase Figma Theme exporter. Replace the names of the font mapping with your own filenames without the .ttf extension.
{
"typography": {
"fontNames": {
"black": "LibreFranklin-Black",
"bold": "LibreFranklin-Bold",
"heavy": "LibreFranklin-ExtraBold",
"ultraLight": "LibreFranklin-ExtraLight",
"light": "LibreFranklin-Light",
"medium": "LibreFranklin-Medium",
"regular": "LibreFranklin-Regular",
"semibold": "LibreFranklin-SemiBold",
"thin": "LibreFranklin-Thin"
}
}
}
Note: If you do not map all values, the default LibreFranklin font will still be used for the unmapped values. Adding extra mappings has no effect.
Once the tokens file is updated and added to your project, add your font files to your project's resource directory and ensure they are added to the main bundle. The design system will use those font files. Then initialise the design system with the token file:
final class AppDelegate: RetailUSAppDelegate {
override init() {
DesignSystem.initialize(jsonName: "customDesignTokens")
super.init { (sdk, design) in
// ...
}
}
}
If you would like to use the system font family instead of the out-of-the-box or a custom font, remove the "fontNames" mapping entirely from the token JSON file and the system font family will be used.
Accessibility
This component is built with accessibility in mind. See the information below for supported behaviors and configuration options.
Configuration
|
Feature |
Description |
|---|---|
|
Dynamic Type |
The preferredFont method returns fonts that support Dynamic Type |
|
Scaling |
Fonts automatically scale based on user accessibility settings |
Best practices
- Use preferredFont for all user-facing text to ensure proper accessibility support.
- Avoid using UIFontMetrics.scaledFont API with defaultFont as it may cause crashes.
- Test with different Dynamic Type sizes to ensure text remains readable.
Dependencies
- External dependencies: None
- Internal dependencies: None
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Black |
typography.fontNames.black |
LibreFranklin-Black |
|
Bold |
typography.fontNames.bold |
LibreFranklin-Bold |
|
Heavy |
typography.fontNames.heavy |
LibreFranklin-ExtraBold |
|
Light |
typography.fontNames.light |
LibreFranklin-Light |
|
Medium |
typography.fontNames.medium |
LibreFranklin-Medium |
|
Regular |
typography.fontNames.regular |
LibreFranklin-Regular |
|
Semibold |
typography.fontNames.semibold |
LibreFranklin-SemiBold |
|
Thin |
typography.fontNames.thin |
LibreFranklin-Thin |
|
Ultra Light |
typography.fontNames.ultraLight |
LibreFranklin-ExtraLight |
Semantic tokens
|
Token |
API Reference |
Description |
|---|---|---|
|
Preferred Font |
DesignSystem.shared.fonts.preferredFont(style, weight) |
Dynamic type font with scaling support |
|
Default Font |
DesignSystem.shared.fonts.defaultFont(style, weight) |
Fixed-size font without scaling |
|
Font Mappings |
DesignSystem.Fonts(fontFileNameMappings:) |
Custom font file name configuration |
See also
- SwiftUI Fonts - SwiftUI font integration
- TextInput - Text input component that uses design system fonts
- Button - Button component that uses design system fonts