Kigo Typography System

Overview

The Kigo Typography System provides comprehensive typography customization capabilities for SDK-hosted sites. This system allows partners to override default typography settings, implement custom fonts, and maintain consistent branding across all text elements within the Kigo SDK.

Typography Context Structure

The typography system is built around the KigoTypographyContext interface, 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 KigoTypographyContext = {
  // Parent font family for all text (excluding title text if titleFontFamily is set)
  fontFamily?: string;
  // Parent font family for title text (titleXl, titleLg, titleMd, titleSmBd, titleSm, titleXs)
  titleFontFamily?: 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;
};

Implementation Guide

1. Setting Up Custom Fonts

Loading Custom Fonts

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

const customTypography: KigoTypographyContext = {
  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'
};

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
Fallbacks: Always include fallback fonts for better user experience
Performance: Use font-display: swap for better loading performance

2. Typography Variants

The system provides 12 predefined typography variants that cover common use cases:

Title Variants

titleXl: Extra large titles (50px, 800 weight)
titleLg: Large titles (32px, 800 weight)
titleMd: Medium titles (22px, 800 weight)
titleSmBd: Small bold titles (16px, 800 weight)
titleSm: Small titles (16px, 700 weight)
titleXs: Extra small titles (default size)

Body Variants

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

3. Complete Implementation Example

// Define your custom typography configuration
const partnerTypography: KigoTypographyContext = {
  // 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',
  
  // 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: KigoTypographyContext = {
    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: KigoTypographyContext = {
  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: KigoTypographyContext = {
  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: KigoTypographyContext = {
  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: Use font-display: swap 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
Inconsistent rendering: Ensure font fallbacks are properly specified
Performance issues: Optimize font loading and consider using font subsets

Debugging Tips

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.