Brand Types

Static Brand Types

Types for pre-defined static brand themes.

BrandTheme

Base interface for static brand definitions.

interface BrandTheme {
  id: string;
  name: string;
  description: string;
}

string

required

Unique identifier for the brand. Used in CSS classes as brand-{id}.

name

string

required

Display name of the brand.

description

string

required

Human-readable description of the brand theme.

Example

export const strideBrand: BrandTheme = {
  id: 'stride',
  name: 'Stride',
  description: 'Default Stride Design System brand with blue primary colors'
};

export const coralBrand: BrandTheme = {
  id: 'coral',
  name: 'Coral',
  description: 'Coral theme with warm orange-red primary colors'
};

Dynamic Brand Types

Types for creating custom white-label brands with dynamic token configuration.

DynamicBrandConfig

Complete configuration for a dynamic brand including all token categories.

interface DynamicBrandConfig {
  id: string;
  name: string;
  description?: string;
  tokens: {
    core?: CoreBrandTokens;
    semantic?: SemanticBrandTokens;
    typography?: TypographyBrandTokens;
    layout?: LayoutBrandTokens;
    custom?: Record<string, string>;
  };
  fallback?: {
    brand?: string;
    useSemanticFallback?: boolean;
  };
}

string

required

Unique identifier for the brand. Must contain only alphanumeric characters, hyphens, and underscores.

name

string

required

Display name of the brand.

description

string

Optional description of the brand.

tokens

object

required

Token definitions organized by category.

tokens.core

CoreBrandTokens

Core color tokens (primary, neutral, success, warning, danger).

tokens.semantic

SemanticBrandTokens

Semantic tokens for text, backgrounds, borders, etc.

tokens.typography

TypographyBrandTokens

Typography tokens for fonts and weights.

tokens.layout

LayoutBrandTokens

Layout tokens for spacing, radius, shadows, transitions.

tokens.custom

Record<string, string>

Custom CSS variables.

fallback

object

Fallback configuration for undefined tokens.

fallback.brand

string

Brand ID to use for fallback values. Defaults to system default.

fallback.useSemanticFallback

boolean

Whether to use semantic tokens from fallback brand. Defaults to true.

Example

const myBrand: DynamicBrandConfig = {
  id: 'acme-corp',
  name: 'Acme Corporation',
  description: 'Custom brand for Acme Corp',
  tokens: {
    core: {
      primary: {
        500: '#6366F1',
        600: '#4F46E5',
        700: '#4338CA'
      }
    },
    semantic: {
      textPrimary: '#1F2937',
      bgPrimary: '#FFFFFF',
      interactivePrimary: 'var(--brand-primary-500)'
    },
    typography: {
      fontFamilyPrimary: 'Inter, sans-serif'
    },
    layout: {
      radiusButton: '8px'
    }
  },
  fallback: {
    brand: 'stride',
    useSemanticFallback: true
  }
};

Token Types

CoreBrandTokens

Core color palette tokens. All properties are optional to allow partial definitions.

interface CoreBrandTokens {
  primary?: {
    50?: string;
    100?: string;
    200?: string;
    300?: string;
    400?: string;
    500?: string;  // Main brand color
    600?: string;
    700?: string;
    800?: string;
    900?: string;
    950?: string;
  };
  
  neutral?: {
    0?: string;    // Usually white
    50?: string;
    100?: string;
    200?: string;
    300?: string;
    400?: string;
    500?: string;
    600?: string;
    700?: string;
    800?: string;
    900?: string;
    950?: string;  // Usually black
  };

  success?: {
    50?: string;
    100?: string;
    500?: string;  // Main success color
    600?: string;
    700?: string;
  };

  warning?: {
    50?: string;
    100?: string;
    500?: string;  // Main warning color
    600?: string;
    700?: string;
  };

  danger?: {
    50?: string;
    100?: string;
    500?: string;  // Main danger color
    600?: string;
    700?: string;
  };
}

Example

const coreTokens: CoreBrandTokens = {
  primary: {
    50: '#F0F9FF',
    500: '#3B82F6',  // Main brand color
    900: '#1E3A8A'
  },
  neutral: {
    0: '#FFFFFF',
    500: '#6B7280',
    950: '#030712'
  },
  success: {
    500: '#10B981'
  },
  danger: {
    500: '#EF4444'
  }
};

SemanticBrandTokens

Semantic tokens for component styling. Can reference core tokens or use hard-coded values.

interface SemanticBrandTokens {
  // Text colors
  textPrimary?: string;
  textSecondary?: string;
  textTertiary?: string;
  textInverse?: string;
  textDisabled?: string;
  textLink?: string;
  textLinkHover?: string;
  textBrand?: string;

  // Background colors
  bgPrimary?: string;
  bgSecondary?: string;
  bgTertiary?: string;
  bgInverse?: string;
  bgDisabled?: string;
  bgOverlay?: string;
  bgTooltip?: string;

  // Interactive states
  interactivePrimary?: string;
  interactivePrimaryHover?: string;
  interactivePrimaryActive?: string;
  interactivePrimaryDisabled?: string;
  interactiveSecondary?: string;
  interactiveSecondaryHover?: string;
  interactiveSecondaryActive?: string;
  interactiveDisabled?: string;

  // Border colors
  borderPrimary?: string;
  borderSecondary?: string;
  borderFocus?: string;
  borderError?: string;
  borderSuccess?: string;
  borderWarning?: string;

  // Status indicators
  statusSuccess?: string;
  statusSuccessBg?: string;
  statusSuccessText?: string;
  statusWarning?: string;
  statusWarningBg?: string;
  statusWarningText?: string;
  statusDanger?: string;
  statusDangerBg?: string;
  statusDangerText?: string;

  // Surface colors
  surfaceCard?: string;
  surfaceModal?: string;
  surfacePopover?: string;
  surfaceTooltip?: string;
}

Example

const semanticTokens: SemanticBrandTokens = {
  // Reference core tokens
  textPrimary: 'var(--brand-neutral-900)',
  textSecondary: 'var(--brand-neutral-600)',
  interactivePrimary: 'var(--brand-primary-500)',
  
  // Or use hard-coded values
  bgPrimary: '#FFFFFF',
  borderPrimary: '#E5E7EB',
  
  // Mix both approaches
  statusSuccess: 'var(--brand-success-500)',
  statusSuccessBg: '#ECFDF5'
};

TypographyBrandTokens

Typography-related tokens for fonts and weights.

interface TypographyBrandTokens {
  fontFamilyPrimary?: string;
  fontFamilySecondary?: string;
  fontWeightNormal?: string;
  fontWeightMedium?: string;
  fontWeightSemibold?: string;
  fontWeightBold?: string;
}

Example

const typographyTokens: TypographyBrandTokens = {
  fontFamilyPrimary: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
  fontFamilySecondary: 'JetBrains Mono, monospace',
  fontWeightNormal: '400',
  fontWeightMedium: '500',
  fontWeightSemibold: '600',
  fontWeightBold: '700'
};

LayoutBrandTokens

Layout and spacing tokens.

interface LayoutBrandTokens {
  spacingScale?: number;
  radiusScale?: number;
  radiusCard?: string;
  radiusButton?: string;
  radiusInput?: string;
  shadowSm?: string;
  shadowMd?: string;
  shadowLg?: string;
  transitionFast?: string;
  transitionNormal?: string;
  transitionSlow?: string;
}

Example

const layoutTokens: LayoutBrandTokens = {
  spacingScale: 4,
  radiusScale: 8,
  radiusCard: '12px',
  radiusButton: '8px',
  radiusInput: '6px',
  shadowSm: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
  shadowMd: '0 4px 6px -1px rgb(0 0 0 / 0.1)',
  shadowLg: '0 10px 15px -3px rgb(0 0 0 / 0.1)',
  transitionFast: '150ms',
  transitionNormal: '200ms',
  transitionSlow: '300ms'
};

System Configuration Types

DynamicBrandSystemConfig

Global configuration for the dynamic brand system.

interface DynamicBrandSystemConfig {
  defaultFallbackBrand: string;
  enableLocalStorage: boolean;
  enableTransitions: boolean;
  transitionDuration: number;
}

defaultFallbackBrand

string

required

Default brand ID to use for fallback values. Default: ‘stride’

enableLocalStorage

boolean

required

Enable localStorage persistence for brands and settings. Default: true

enableTransitions

boolean

required

Enable CSS transitions when switching brands. Default: true

transitionDuration

number

required

Duration of brand switch transitions in milliseconds. Default: 50

Example

const systemConfig: DynamicBrandSystemConfig = {
  defaultFallbackBrand: 'stride',
  enableLocalStorage: true,
  enableTransitions: true,
  transitionDuration: 200
};

Complete Brand Example

Here’s a complete example of a dynamic brand with all token types:

import type { DynamicBrandConfig } from 'stride-ds';

const techStartupBrand: DynamicBrandConfig = {
  id: 'tech-startup',
  name: 'Tech Startup',
  description: 'Modern tech company brand with purple accents',
  
  tokens: {
    // Core color palette
    core: {
      primary: {
        50: '#FAF5FF',
        100: '#F3E8FF',
        200: '#E9D5FF',
        300: '#D8B4FE',
        400: '#C084FC',
        500: '#A855F7',  // Main brand color
        600: '#9333EA',
        700: '#7E22CE',
        800: '#6B21A8',
        900: '#581C87',
        950: '#3B0764'
      },
      neutral: {
        0: '#FFFFFF',
        50: '#F9FAFB',
        100: '#F3F4F6',
        500: '#6B7280',
        900: '#111827',
        950: '#030712'
      },
      success: {
        50: '#ECFDF5',
        500: '#10B981',
        700: '#047857'
      },
      danger: {
        50: '#FEF2F2',
        500: '#EF4444',
        700: '#B91C1C'
      }
    },
    
    // Semantic tokens
    semantic: {
      textPrimary: 'var(--brand-neutral-900)',
      textSecondary: 'var(--brand-neutral-500)',
      textBrand: 'var(--brand-primary-600)',
      
      bgPrimary: '#FFFFFF',
      bgSecondary: 'var(--brand-neutral-50)',
      
      interactivePrimary: 'var(--brand-primary-500)',
      interactivePrimaryHover: 'var(--brand-primary-600)',
      interactivePrimaryActive: 'var(--brand-primary-700)',
      
      borderPrimary: 'var(--brand-neutral-200)',
      borderFocus: 'var(--brand-primary-500)',
      
      statusSuccess: 'var(--brand-success-500)',
      statusDanger: 'var(--brand-danger-500)'
    },
    
    // Typography
    typography: {
      fontFamilyPrimary: 'Inter, system-ui, sans-serif',
      fontFamilySecondary: 'JetBrains Mono, monospace',
      fontWeightNormal: '400',
      fontWeightMedium: '500',
      fontWeightSemibold: '600',
      fontWeightBold: '700'
    },
    
    // Layout
    layout: {
      radiusCard: '16px',
      radiusButton: '12px',
      radiusInput: '8px',
      shadowMd: '0 4px 6px -1px rgb(168 85 247 / 0.1)',
      transitionNormal: '200ms'
    },
    
    // Custom variables
    custom: {
      'hero-gradient': 'linear-gradient(135deg, var(--brand-primary-500), var(--brand-primary-700))',
      'card-hover-shadow': '0 20px 25px -5px rgb(168 85 247 / 0.15)'
    }
  },
  
  // Fallback configuration
  fallback: {
    brand: 'stride',
    useSemanticFallback: true
  }
};

export default techStartupBrand;

Using Brand Types

Type Guards

import type { BrandTheme, DynamicBrandConfig } from 'stride-ds';

function isStaticBrand(brand: BrandTheme | DynamicBrandConfig): brand is BrandTheme {
  return !('tokens' in brand);
}

function isDynamicBrand(brand: BrandTheme | DynamicBrandConfig): brand is DynamicBrandConfig {
  return 'tokens' in brand;
}

Type-Safe Token Access

function getPrimaryColor(brand: DynamicBrandConfig): string | undefined {
  return brand.tokens.core?.primary?.[500];
}

function getTextColor(brand: DynamicBrandConfig): string | undefined {
  return brand.tokens.semantic?.textPrimary;
}

Utilities

Types

Static Brand Types

BrandTheme

Example

Dynamic Brand Types

DynamicBrandConfig

Example

Token Types

CoreBrandTokens

Example

SemanticBrandTokens

Example

TypographyBrandTokens

Example

LayoutBrandTokens

Example

System Configuration Types

DynamicBrandSystemConfig

Example

Complete Brand Example

Using Brand Types

Type Guards

Type-Safe Token Access

Build docs developers (and LLMs) love

Utilities

Types

​Static Brand Types

​BrandTheme

​Example

​Dynamic Brand Types

​DynamicBrandConfig

​Example

​Token Types

​CoreBrandTokens

​Example

​SemanticBrandTokens

​Example

​TypographyBrandTokens

​Example

​LayoutBrandTokens

​Example

​System Configuration Types

​DynamicBrandSystemConfig

​Example

​Complete Brand Example

​Using Brand Types

​Type Guards

​Type-Safe Token Access

Build docs developers (and LLMs) love

Static Brand Types

BrandTheme

Example

Dynamic Brand Types

DynamicBrandConfig

Example

Token Types

CoreBrandTokens

Example

SemanticBrandTokens

Example

TypographyBrandTokens

Example

LayoutBrandTokens

Example

System Configuration Types

DynamicBrandSystemConfig

Example

Complete Brand Example

Using Brand Types

Type Guards

Type-Safe Token Access