Kigo Typography System

Overview

The Kigo Typography System lets SDK-hosted sites override default typography, load custom fonts, and keep branding consistent across all text rendered by the Kigo SDKs. Typography is configured under theme.typography in the SDK context.

Font priority (Kigo TOP SDK):

Program- or partner-specific typography (configured by Kigo) — when present, it replaces any theme.typography passed in context
Hosted site override via theme.typography in context
Kigo default typography (fallback configuration, then the built-in SDK defaults)

📘
Other SDKs
The Loyalty Wallet, Local+, and Verify SDKs use only the theme.typography passed in context, falling back to the built-in SDK defaults.

Any property you omit falls back to the SDK default for that property, so you only need to set what you want to change.

Typography Context Structure

The typography system is built around the KigoTypographyTheme type, which provides granular control over font families, sizes, weights, and spacing for different text variants.

Core Types

export type TypographyVariantConfig = {
  fontFamily?: string;
  fontSize?: string;
  fontWeight?: number;
  letterSpacing?: string;
  lineHeight?: string;
};

export type FontSourceMapping = {
  family: string;
  url: string;
};

export type KigoTypographyTheme = {
  // Parent font family for all text
  fontFamily?: string;
  // Parent font family for the large title variants (titleXl, titleLg, titleMd)
  titleFontFamily?: string;
  // Font family for buttons (falls back to fontFamily)
  buttonFontFamily?: string;
  // Where we load the fonts from
  fontSources?: FontSourceMapping[];
  // Text variants
  titleXl?: TypographyVariantConfig;
  titleLg?: TypographyVariantConfig;
  titleMd?: TypographyVariantConfig;
  titleSmBd?: TypographyVariantConfig;
  titleSm?: TypographyVariantConfig;
  titleXs?: TypographyVariantConfig;
  bodyMdBold?: TypographyVariantConfig;
  bodyMd?: TypographyVariantConfig;
  bodySmBold?: TypographyVariantConfig;
  bodySm?: TypographyVariantConfig;
  bodyXsBold?: TypographyVariantConfig;
  bodyXs?: TypographyVariantConfig;
};

Font Family Resolution

Each variant resolves its font family in this order:

titleXl, titleLg, titleMd: variant fontFamily → titleFontFamily → fontFamily → SDK default
All other variants: variant fontFamily → fontFamily → SDK default
Buttons: buttonFontFamily → fontFamily

Implementation Guide

1. Setting Up Custom Fonts

Loading Custom Fonts

To use custom fonts in your SDK-hosted site, provide font sources that the SDK can load:

const customTypography: KigoTypographyTheme = {
  fontSources: [
    {
      family: 'CustomFont',
      url: 'https://fonts.googleapis.com/css2?family=CustomFont:wght@400;600;700&display=swap'
    },
    {
      family: 'BrandFont',
      url: 'https://your-cdn.com/fonts/brand-font.woff2'
    }
  ],
  fontFamily: 'CustomFont, sans-serif',
  titleFontFamily: 'BrandFont, serif'
};

How Font Sources Are Loaded

Direct font files: URLs ending in .woff2, .woff, .ttf, .otf, or .eot are registered as an @font-face rule for the given family, with font-display: swap.
Stylesheet URLs: any other URL (for example, Google Fonts) is fetched as CSS and injected into the page. The SDK fetches it from the browser, so the URL must allow cross-origin requests.
Valid URLs: url must be absolute (http...) or relative (/... or ./...). Sources missing a family or url are skipped with a console warning.
Default font: the SDK default font (Inter) is always loaded in addition to your sources.

Font Loading Best Practices

Web Fonts: Use Google Fonts or other web font services for reliable loading
Self-Hosted Fonts: Ensure your CDN provides proper CORS headers
Matching names: The family in fontSources must match the name used in your fontFamily values
Fallbacks: Always include fallback fonts (e.g. sans-serif) for better user experience

2. Typography Variants

The system provides 12 predefined typography variants. SDK defaults are shown below (all use Inter with 0px letter spacing):

Title Variants

titleXl: Extra large titles (50px, 800 weight, 50px line height)
titleLg: Large titles (32px, 800 weight, 40px line height)
titleMd: Medium titles (22px, 800 weight, 28px line height)
titleSmBd: Small bold titles (16px, 800 weight, 24px line height)
titleSm: Small titles (16px, 700 weight, 20px line height)
titleXs: Extra small titles (14px, 700 weight, 20px line height)

Body Variants

bodyMdBold: Medium bold body text (14px, 600 weight, 20px line height)
bodyMd: Medium body text (14px, 400 weight, 20px line height)
bodySmBold: Small bold body text (12px, 600 weight, 16px line height)
bodySm: Small body text (12px, 400 weight, 16px line height)
bodyXsBold: Extra small bold body text (10px, 600 weight, 16px line height)
bodyXs: Extra small body text (10px, 400 weight, 16px line height)

3. Complete Implementation Example

// Define your custom typography configuration
const partnerTypography: KigoTypographyTheme = {
  // Load custom fonts
  fontSources: [
    {
      family: 'Inter',
      url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap'
    },
    {
      family: 'Playfair Display',
      url: 'https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700;900&display=swap'
    }
  ],
  
  // Set base font families
  fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
  titleFontFamily: 'Playfair Display, serif',
  buttonFontFamily: 'Inter, sans-serif',
  
  // Override specific variants
  titleXl: {
    fontFamily: 'Playfair Display, serif',
    fontSize: '48px',
    fontWeight: 900,
    letterSpacing: '-0.02em',
    lineHeight: '1.1'
  },
  
  titleLg: {
    fontFamily: 'Playfair Display, serif',
    fontSize: '36px',
    fontWeight: 700,
    letterSpacing: '-0.01em',
    lineHeight: '1.2'
  },
  
  bodyMd: {
    fontFamily: 'Inter, sans-serif',
    fontSize: '16px',
    fontWeight: 400,
    letterSpacing: '0em',
    lineHeight: '1.5'
  },
  
  bodySm: {
    fontFamily: 'Inter, sans-serif',
    fontSize: '14px',
    fontWeight: 400,
    letterSpacing: '0.01em',
    lineHeight: '1.4'
  }
};

// Apply typography to SDK context
window.Kigo.setContext({
  theme: {
    palette: {
      primary: '#4B55FD',
      secondary: '#CCFFFE'
    },
    typography: partnerTypography
  },
  // ... other context properties
});

4. Integration with SDK Wrapper

For seamless integration, you can extend the existing SDK wrapper to include typography configuration:

// In your SDK wrapper or initialization code
const initializeKigoSDK = (partnerConfig: PartnerConfig) => {
  const typographyConfig: KigoTypographyTheme = {
    fontSources: partnerConfig.fontSources || [],
    fontFamily: partnerConfig.fontFamily || 'Inter, sans-serif',
    titleFontFamily: partnerConfig.titleFontFamily || partnerConfig.fontFamily || 'Inter, sans-serif',
    // Add specific variant overrides as needed
    ...partnerConfig.typographyVariants
  };

  window.Kigo.setContext({
    theme: {
      palette: {
        primary: partnerConfig.primaryColor,
        secondary: partnerConfig.secondaryColor
      },
      typography: typographyConfig
    },
    // ... other context properties
  });
};

Advanced Customization

1. Responsive Typography

You can implement responsive typography by using CSS custom properties and media queries:

const responsiveTypography: KigoTypographyTheme = {
  fontFamily: 'Inter, sans-serif',
  titleXl: {
    fontSize: 'clamp(32px, 5vw, 48px)', // Responsive font size
    lineHeight: '1.1'
  },
  bodyMd: {
    fontSize: 'clamp(14px, 2vw, 16px)',
    lineHeight: '1.5'
  }
};

2. Brand-Specific Typography

For brands with specific typography requirements:

const brandTypography: KigoTypographyTheme = {
  fontSources: [
    {
      family: 'Brand Sans',
      url: 'https://cdn.brand.com/fonts/brand-sans.woff2'
    }
  ],
  fontFamily: 'Brand Sans, Arial, sans-serif',
  titleFontFamily: 'Brand Sans, Arial, sans-serif',
  
  // Maintain brand consistency
  titleXl: {
    fontFamily: 'Brand Sans, Arial, sans-serif',
    fontSize: '42px',
    fontWeight: 700,
    letterSpacing: '-0.025em'
  }
};

3. Accessibility Considerations

Ensure your typography choices meet accessibility standards:

const accessibleTypography: KigoTypographyTheme = {
  fontFamily: 'Inter, sans-serif',
  
  // Ensure sufficient contrast and readability
  bodyMd: {
    fontSize: '16px', // Minimum readable size
    lineHeight: '1.5', // Good line spacing
    letterSpacing: '0.01em' // Slight letter spacing for readability
  },
  
  // High contrast for important text
  bodyMdBold: {
    fontSize: '16px',
    fontWeight: 600, // Not too heavy for good readability
    lineHeight: '1.4'
  }
};

Best Practices

1. Font Loading Strategy

Preload critical fonts: Use <link rel="preload"> for essential fonts
Font display: Direct font files are registered with font-display: swap; for stylesheet URLs, include display=swap (e.g. Google Fonts) for better perceived performance
Subset fonts: Only load the character sets you need

2. Performance Optimization

Limit font variants: Only load the weights and styles you actually use
Use system fonts as fallbacks: Provide good fallbacks for faster initial rendering
Monitor font loading: Use the Font Loading API to track font loading performance

3. Brand Consistency

Maintain hierarchy: Ensure your typography scale maintains visual hierarchy
Consistent spacing: Use consistent letter-spacing and line-height values
Test across devices: Verify typography looks good on all target devices

4. Testing and Validation

Cross-browser testing: Test typography rendering across different browsers
Device testing: Verify on various screen sizes and resolutions
Accessibility testing: Ensure sufficient contrast ratios and readability

Troubleshooting

Common Issues

Fonts not loading: Check CORS headers and font URL accessibility
Font falls back to default: Make sure the font name used in fontFamily matches a family declared in fontSources
Context typography ignored (Kigo TOP SDK): A program- or partner-level typography configuration takes priority over theme.typography; contact the Kigo team to change it
Inconsistent rendering: Ensure font fallbacks are properly specified
Performance issues: Optimize font loading and consider using font subsets

Debugging Tips

Check the browser console for FontLoader: warnings. The SDK warns when a font source is skipped (missing or invalid URL), when a stylesheet fails to fetch, when a font fails to load, and when a variant references a font family that no font source declares
Use browser dev tools to inspect font loading
Check network tab for font request failures
Verify font-family declarations in computed styles
Test with different font loading strategies

Migration Guide

From Default Typography

If you're migrating from the default typography system:

Audit current usage: Identify which typography variants are currently used
Plan your hierarchy: Design your new typography scale
Implement gradually: Start with base fonts, then add specific variants
Test thoroughly: Ensure all text elements render correctly

From Custom CSS

If you're migrating from custom CSS typography:

Map CSS classes: Identify which CSS classes correspond to typography variants
Convert properties: Translate CSS properties to TypographyVariantConfig
Update references: Replace CSS class usage with typography variants
Verify consistency: Ensure the new system maintains your design intent

This typography system provides the flexibility needed to maintain brand consistency while ensuring optimal performance and accessibility across all SDK-hosted implementations.