Design Token System - Single Source of Truth

Status: ✅ Complete
Date: October 11, 2025
Branch: feat/tailwind-integration

Problem Statement

You asked: “How will this work when we change the design? Can we set it up to change the design theme for a particular app in one place and have that theme apply to the web and to the mobile apps?”

Answer: Yes! Here’s how it works:

Solution Architecture

┌─────────────────────────────────────────────────────────────┐
│         Design Tokens (Single Source of Truth)              │
│         packages/theme/src/tokens.ts                         │
│                                                              │
│  - Colors (primary, secondary, semantic)                    │
│  - Typography (families, sizes, weights)                    │
│  - Spacing (4px base grid)                                  │
│  - Border radius, shadows, z-index, breakpoints             │
└──────────────────┬──────────────────────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │                   │
         ▼                   ▼
┌────────────────┐   ┌────────────────┐
│  Tailwind      │   │ Brand-Specific │
│  Preset        │   │ Theme Override │
│  (Web/Mobile)  │   │                │
└────────┬───────┘   └────────┬───────┘
         │                    │
         │     ┌──────────────┘
         │     │
         ▼     ▼
┌─────────────────────────────────────┐
│      Individual App Configs         │
│                                     │
│  • Pinkguest (pink primary color)  │
│  • Orangeguest (orange primary)    │
│  • RoomLGBT (purple primary)       │
└─────────────────────────────────────┘

How It Works

1. Define Design Tokens Once

File: packages/theme/src/tokens.ts

// This is your SINGLE SOURCE OF TRUTH
export const colors = {
  primary: {
    50: '#f0f9ff',
    500: '#0ea5e9',  // Main primary color
    900: '#0c4a6e',
  },
  // ... all other colors
};

export const typography = {
  families: {
    sans: ['Inter', 'system-ui', 'sans-serif'],
  },
  sizes: {
    base: { size: '1rem', lineHeight: '1.5rem' },
  },
};

2. Create Brand-Specific Overrides (Optional)

File: packages/theme/src/brands.ts

// Pinkguest overrides ONLY the primary color
export const pinkguestTheme = createBrandTheme({
  colors: {
    primary: {
      50: '#fdf2f8',
      500: '#ec4899',  // Pink instead of blue!
      900: '#831843',
    },
  },
});

// Everything else (typography, spacing, etc.) inherits from base

3. Tailwind Preset Consumes Tokens

File: packages/config/tailwind-preset.js

// Import design tokens
const tokens = require('@cloudalt-frontend/theme');

module.exports = {
  theme: {
    extend: {
      colors: tokens.colors,        // ← Design tokens flow here
      fontFamily: tokens.typography.families,
      fontSize: convertFontSizes(tokens.typography.sizes),
      spacing: tokens.spacing,
      // ... all other tokens
    },
  },
};

4. Apps Use Brand-Specific Presets

File: apps/stay_match/pinkguest/mobile/tailwind.config.js

// Option A: Base theme (blue primary)
module.exports = {
  presets: [require('@cloudalt-frontend/config/tailwind-preset')],
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
};

// Option B: Brand-specific theme (pink primary)
const { createBrandPreset } = require('@cloudalt-frontend/config/tailwind-preset');

module.exports = {
  presets: [createBrandPreset('pinkguest')],  // ← Brand name here!
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
};

Usage Examples

Example 1: Change Global Primary Color

Scenario: You want to change the primary color for ALL apps.

Solution: Edit ONE file:

packages/theme/src/tokens.ts

export const colors = {
  primary: {
    50: '#fef2f2',   // Changed from blue to red
    500: '#ef4444',  // New primary red
    900: '#7f1d1d',
  },
};

Result: All apps (web and mobile) using the base theme now have red primary color.

---

Example 2: Change Brand-Specific Color

Scenario: You want Pinkguest to have a different shade of pink.

Solution: Edit ONE file:

packages/theme/src/brands.ts

export const pinkguestTheme = createBrandTheme({
  colors: {
    primary: {
      500: '#db2777',  // Darker pink
    },
  },
});

Result: Only Pinkguest apps change. All other apps unaffected.

---

Example 3: Add New Brand Theme

Scenario: You’re launching “Greenhost” with a green theme.

Solution: Add to packages/theme/src/brands.ts:

export const greenhostTheme = createBrandTheme({
  colors: {
    primary: {
      50: '#f0fdf4',
      500: '#22c55e',  // Green
      900: '#14532d',
    },
  },
});

export const brandThemes = {
  pinkguest: pinkguestTheme,
  orangeguest: orangeguestTheme,
  greenhost: greenhostTheme,  // ← New brand
};

Then in Greenhost’s tailwind config:

module.exports = {
  presets: [createBrandPreset('greenhost')],
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
};

---

Example 4: Change Typography Globally

Scenario: Design wants to switch from Inter to Poppins.

Solution: Edit ONE file:

packages/theme/src/tokens.ts

export const typography = {
  families: {
    sans: ['Poppins', 'system-ui', 'sans-serif'],  // Changed!
  },
};

Result: All apps (web and mobile) now use Poppins.

---

Example 5: Adjust Spacing Scale

Scenario: Design wants tighter spacing across all apps.

Solution: Edit ONE file:

packages/theme/src/tokens.ts

export const spacing = {
  1: '0.2rem',    // Changed from 0.25rem
  2: '0.4rem',    // Changed from 0.5rem
  3: '0.6rem',    // Changed from 0.75rem
  // ...
};

Result: All apps get new spacing scale automatically.

Component Usage

Web Component (React)

// Automatically uses design tokens via Tailwind
function Button() {
  return (
    <button className="bg-primary-500 text-white px-4 py-2 rounded-lg">
      Click Me
    </button>
  );
}

Mobile Component (React Native)

// Same Tailwind classes work via NativeWind!
import { View, Text, Pressable } from 'react-native';

function Button() {
  return (
    <Pressable className="bg-primary-500 px-4 py-2 rounded-lg">
      <Text className="text-white font-semibold">
        Click Me
      </Text>
    </Pressable>
  );
}

Direct Token Usage (if needed)

// You can also import tokens directly
import { colors } from '@cloudalt-frontend/theme';

const styles = {
  backgroundColor: colors.primary[500],
};

Testing Changes

Step 1: Edit Design Tokens

# Edit the tokens file
code packages/theme/src/tokens.ts

Step 2: Changes Propagate Automatically

No rebuild needed! The tokens are imported at build time.

Step 3: Test in Storybook (Phase 1.3)

# Launch Storybook to see all components with new tokens
yarn nx run storybook:storybook

Step 4: Test in Mobile App

# Clear Metro cache to pick up changes
yarn nx run pinkguest-mobile:start --clear

Migration Path

Phase 1: Infrastructure (Current)

• ✅ Design tokens defined in packages/theme
• ✅ Tailwind preset consumes tokens
• ✅ Brand-specific overrides system
• ✅ Documentation complete

Phase 2: Apply to Pinkguest

• 📅 Add tailwind.config.js to Pinkguest mobile
• 📅 Convert components to use Tailwind classes
• 📅 Test thoroughly

Phase 3: Extract to Shared Components

• 📅 Move common components to packages/ui
• 📅 Components already use design tokens via Tailwind
• 📅 Reusable across all brands

Phase 4: Rollout to Other Apps

• 📅 Copy tailwind config to each app
• 📅 Use brand-specific preset per app
• 📅 Gradual migration of components

Benefits

1. Single Point of Control

Change design tokens once, all apps update automatically.

2. Brand Consistency

Each brand can override specific tokens while keeping shared values.

3. Type Safety

TypeScript types ensure tokens are used correctly.

4. Works Everywhere

Same tokens work in:

• Web apps (Tailwind CSS)
• Mobile apps (NativeWind)
• Storybook (design documentation)
• Direct imports (when needed)

5. Design-Dev Sync

Export tokens from Figma → Update tokens.ts → All apps updated.

Advanced: Figma Integration

Future Enhancement

# Export tokens from Figma (using Tokens Studio plugin)
# → packages/theme/figma-tokens.json

# Transform to TypeScript
node scripts/generate-design-tokens.mjs

# Result: packages/theme/src/tokens.ts updated automatically

This enables true design-to-code synchronization.

Common Questions

Q: What if I need app-specific colors that aren’t in the theme?

A: Override in the app’s tailwind config:

module.exports = {
  presets: [createBrandPreset('pinkguest')],
  theme: {
    extend: {
      colors: {
        'custom-accent': '#ff69b4',  // App-specific
      },
    },
  },
};

Q: Do web and mobile share the EXACT same components?

A: No, but they share design tokens (colors, spacing, etc.). Components are platform-specific but visually consistent.

Q: Can I have different tokens for web vs mobile?

A: Yes, but discouraged. Better to have responsive design with shared tokens.

Q: How do I preview changes before committing?

A: Use Storybook! It shows all components with current tokens.

Related Documentation

• Tailwind Integration Guide
• Figma Tokens Studio Setup
• Phase 1 Roadmap

Summary

Yes, you CAN change design in one place and have it apply to web and mobile!

• One file to rule them all: packages/theme/src/tokens.ts
• Brand overrides: packages/theme/src/brands.ts
• Automatic propagation: Tailwind preset + NativeWind
• Works everywhere: Web, mobile, Storybook

Example workflow:

1. Designer updates brand colors in Figma
2. Developer updates packages/theme/src/tokens.ts (or automates it)
3. All apps get new colors automatically
4. No component changes needed (they use className="bg-primary-500")

This is the power of design tokens!