Design Tokens

Design tokens are the visual atoms of our design system. They are named entities that store visual design attributes, such as colors, typography, and spacing. This system ensures consistency across the application while allowing for high levels of customization and theming.

Core Concepts

The system is built on a layered architecture:

1. Primitives: Raw values (e.g., hex codes in colors.ts).
2. Semantic Tokens: Tokens with specific meaning (e.g., primary, background, success).
3. Themes: Bundled semantic tokens defining a specific look (e.g., Modern, Retro, Cozy, Paper).

Usage in Expo

To access design tokens in your components, use the useThemeTokens hook.

import { View, Text } from 'react-native';
import { useThemeTokens } from '@/constants/theme-context';

export function MyComponent() {
  const tokens = useThemeTokens();

  return (
    <View style={{ 
      backgroundColor: tokens.background, 
      padding: tokens.spacing.md 
    }}>
      <Text style={[tokens.typography.body.medium, { color: tokens.primary }]}>
        Hello World
      </Text>
    </View>
  );
}

Theme Variants

Our system supports multiple themes, each with its own personality:

Dynamic Customization

The design tokens system is highly dynamic and responds to user preferences:

Accent Colors

Users can choose a custom accent color (Green, Blue, Indigo, Purple, Pink, Amber) which influences the accentSurface and specific border colors.

Appearance Modes

• Light: High-key color schemes.
• Dark: Low-key color schemes.
• System: Automatically follows the device's brightness setting.

Typography Scale

The ModernTypography scale provides a full range of styles from display to label, ensuring consistent hierarchy.

tokens.primary       // Main brand color
tokens.onPrimary     // Text on primary
tokens.background    // Page background
tokens.surface       // Card background
tokens.accentSurface // Tinted background

Implementation Details

The core logic resides in:

• constants/design-tokens.ts: The data structures and theme definitions.
• constants/theme-context.tsx: The React Context that manages theme state and computes final tokens.
• constants/use-design-tokens.ts: Utility hooks for quick access.

Adding New Tokens

1. Open constants/design-tokens.ts.
2. Add the new property to the DesignTokens interface.
3. Provide values for all theme definitions (e.g., modernLightTokens, modernDarkTokens, etc.).
4. If the token is computed (like accentSurface), update the useMemo block in theme-context.tsx.