Building cross-platform design systems: from web to mobile and back

Introduction

Picture this: your startup just launched a successful web application, and now stakeholders want iOS and Android versions—yesterday. The design team scrambles to recreate components across platforms, developers debate whether buttons should look identical everywhere, and three months later, users complain that the mobile app “doesn’t feel like the same product.” Sound familiar?

This scenario plays out countless times across the tech industry, highlighting a critical challenge in modern product development: how do you maintain a cohesive brand experience across web, mobile, and emerging platforms without sacrificing development velocity or platform-specific user expectations? The answer lies in building robust cross-platform design systems that bridge the gap between design and development while respecting the unique characteristics of each platform.

In this article, we’ll explore proven strategies for creating design systems that work seamlessly across web, iOS, Android, and other platforms. You’ll learn how to structure design tokens for maximum reusability, implement component libraries that translate effectively across technologies, and establish workflows that keep designers and developers aligned. We’ll examine real-world case studies, dive into practical implementation details, and provide actionable frameworks you can apply to your own cross-platform projects.

The stakes are higher than ever: in 2024, users interact with brands across an average of 4.2 different touchpoints, and 73% report that inconsistent experiences negatively impact their perception of a brand. A well-architected cross-platform design system isn’t just a technical convenience—it’s a competitive advantage that directly impacts user satisfaction, development efficiency, and business outcomes.

Understanding cross-platform design challenges

Before diving into solutions, it’s essential to understand the unique challenges that cross-platform design systems must address. Unlike single-platform design work, cross-platform systems must balance universal consistency with platform-specific conventions and technical constraints.

Platform convention conflicts

Each platform has established design patterns that users expect. iOS users anticipate swipe gestures and tab bars at the bottom, while Android users expect floating action buttons and navigation drawers. Web users are accustomed to hover states and keyboard navigation that don’t exist on mobile devices. These platform-specific expectations create tension with the goal of maintaining consistent branding and user experience across all touchpoints.

Consider a simple button component. On the web, it might include hover and focus states with specific cursor behaviors:

.button {
  background: var(--color-primary);
  border-radius: 8px;
  padding: 12px 24px;
  transition: all 0.2s ease;
}

.button:hover {
  background: var(--color-primary-hover);
  transform: translateY(-1px);
}

.button:focus {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

On mobile platforms, the same button needs to account for touch targets, haptic feedback, and different interaction patterns:

// iOS SwiftUI example
Button("Primary Button") {
    // Action
}
.buttonStyle(PrimaryButtonStyle())
.sensoryFeedback(.impact, trigger: buttonPressed)

struct PrimaryButtonStyle: ButtonStyle {
    func makeBody(configuration: Configuration) -> some View {
        configuration.label
            .padding(.horizontal, 24)
            .padding(.vertical, 12)
            .background(Color.primary)
            .cornerRadius(8)
            .scaleEffect(configuration.isPressed ? 0.95 : 1.0)
            .animation(.easeInOut(duration: 0.1), value: configuration.isPressed)
    }
}

Technical implementation differences

Different platforms use different technologies, frameworks, and styling approaches. CSS properties don’t directly translate to SwiftUI modifiers or Android XML attributes. React components can’t be directly imported into React Native without modification. These technical differences require careful abstraction and planning to maintain consistency.

A navigation component that works perfectly in React might look like this:

const Navigation = ({ items, activeItem }) => {
  return (
    <nav className="navigation">
      {items.map(item => (
        <NavItem 
          key={item.id}
          item={item}
          isActive={item.id === activeItem}
        />
      ))}
    </nav>
  );
};

But the equivalent React Native component requires different styling approaches and navigation libraries:

import { NavigationContainer } from '@react-navigation/native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const Tab = createBottomTabNavigator();

const Navigation = ({ screens }) => {
  return (
    <NavigationContainer>
      <Tab.Navigator
        screenOptions={{
          tabBarStyle: styles.tabBar,
          tabBarActiveTintColor: colors.primary,
        }}
      >
        {screens.map(screen => (
          <Tab.Screen
            key={screen.name}
            name={screen.name}
            component={screen.component}
          />
        ))}
      </Tab.Navigator>
    </NavigationContainer>
  );
};

Design tool integration complexity

Design tools like Figma, Sketch, and Adobe XD excel at creating static designs, but they struggle with the dynamic nature of cross-platform systems. Designers often create multiple versions of the same component for different platforms, leading to inconsistencies and maintenance overhead. The handoff between design and development becomes more complex when the same conceptual component has different visual representations across platforms.

Design tokens: the foundation of cross-platform consistency

Design tokens are the atomic elements of a design system—the named entities that store design decisions like colors, typography, spacing, and animation values. They serve as the single source of truth that translates design decisions into platform-specific code.

Implementing a token-based architecture

A well-structured token system organizes values hierarchically, from global brand values to component-specific applications:

{
  "color": {
    "brand": {
      "primary": {
        "value": "#1a73e8",
        "type": "color",
        "description": "Primary brand color used for CTAs and key interactive elements"
      },
      "secondary": {
        "value": "#34a853",
        "type": "color"
      }
    },
    "semantic": {
      "success": {
        "value": "{color.brand.secondary}",
        "type": "color"
      },
      "error": {
        "value": "#ea4335",
        "type": "color"
      },
      "warning": {
        "value": "#fbbc04",
        "type": "color"
      }
    },
    "component": {
      "button": {
        "primary": {
          "background": {
            "value": "{color.brand.primary}",
            "type": "color"
          },
          "text": {
            "value": "#ffffff",
            "type": "color"
          }
        }
      }
    }
  },
  "spacing": {
    "xs": {
      "value": "4px",
      "type": "dimension"
    },
    "sm": {
      "value": "8px",
      "type": "dimension"
    },
    "md": {
      "value": "16px",
      "type": "dimension"
    },
    "lg": {
      "value": "24px",
      "type": "dimension"
    },
    "xl": {
      "value": "32px",
      "type": "dimension"
    }
  },
  "typography": {
    "heading": {
      "h1": {
        "fontSize": {
          "value": "32px",
          "type": "dimension"
        },
        "fontWeight": {
          "value": "700",
          "type": "fontWeight"
        },
        "lineHeight": {
          "value": "1.25",
          "type": "number"
        }
      }
    },
    "body": {
      "regular": {
        "fontSize": {
          "value": "16px",
          "type": "dimension"
        },
        "fontWeight": {
          "value": "400",
          "type": "fontWeight"
        },
        "lineHeight": {
          "value": "1.5",
          "type": "number"
        }
      }
    }
  }
}

Token transformation for different platforms

Using tools like Style Dictionary or Theo, these tokens can be automatically transformed into platform-specific formats:

// style-dictionary.config.js
const StyleDictionary = require('style-dictionary');

StyleDictionary.extend({
  source: ['tokens/**/*.json'],
  platforms: {
    web: {
      transformGroup: 'web',
      buildPath: 'build/web/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables'
      }]
    },
    ios: {
      transformGroup: 'ios',
      buildPath: 'build/ios/',
      files: [{
        destination: 'tokens.swift',
        format: 'ios-swift/class.swift'
      }]
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/',
      files: [{
        destination: 'tokens.xml',
        format: 'android/resources'
      }]
    },
    reactNative: {
      transformGroup: 'react-native',
      buildPath: 'build/react-native/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
}).buildAllPlatforms();

This configuration generates platform-specific token files:

Web (CSS custom properties):

:root {
  --color-brand-primary: #1a73e8;
  --color-brand-secondary: #34a853;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --typography-heading-h1-font-size: 32px;
}

iOS (Swift):

public class DesignTokens {
    public static let colorBrandPrimary = UIColor(hex: "#1a73e8")
    public static let colorBrandSecondary = UIColor(hex: "#34a853")
    public static let spacingXs: CGFloat = 4
    public static let spacingSm: CGFloat = 8
    public static let typographyHeadingH1FontSize: CGFloat = 32
}

Android (XML resources):

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <color name="color_brand_primary">#1a73e8</color>
  <color name="color_brand_secondary">#34a853</color>
  <dimen name="spacing_xs">4dp</dimen>
  <dimen name="spacing_sm">8dp</dimen>
  <dimen name="typography_heading_h1_font_size">32sp</dimen>
</resources>

Advanced token strategies

For complex design systems, consider implementing contextual tokens that adapt based on platform capabilities:

{
  "animation": {
    "duration": {
      "fast": {
        "value": "150ms",
        "type": "duration",
        "platforms": {
          "web": "150ms",
          "ios": "0.15",
          "android": "150"
        }
      }
    },
    "easing": {
      "ease-out": {
        "value": "cubic-bezier(0.25, 0.46, 0.45, 0.94)",
        "type": "cubicBezier",
        "platforms": {
          "web": "cubic-bezier(0.25, 0.46, 0.45, 0.94)",
          "ios": "UIView.AnimationOptions.curveEaseOut",
          "android": "DecelerateInterpolator()"
        }
      }
    }
  }
}

Component architecture for cross-platform systems

Building reusable components across platforms requires careful architectural planning. The goal is to create components that maintain consistent behavior and appearance while leveraging platform-specific optimizations and conventions.

Shared logic, platform-specific implementation

The most effective approach separates component logic from presentation, allowing shared business logic while adapting the user interface to each platform’s conventions:

// Shared component logic
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'outline';
  size: 'small' | 'medium' | 'large';
  disabled?: boolean;
  loading?: boolean;
  onPress: () => void;
  children: React.ReactNode;
}

interface ButtonState {
  isPressed: boolean;
  isHovered: boolean;
  isFocused: boolean;
}

export const useButtonLogic = (props: ButtonProps) => {
  const [state, setState] = useState<ButtonState>({
    isPressed: false,
    isHovered: false,
    isFocused: false
  });

  const handlePress = useCallback(() => {
    if (!props.disabled && !props.loading) {
      props.onPress();
    }
  }, [props.disabled, props.loading, props.onPress]);

  const getStyleVariant = useCallback((platform: 'web' | 'mobile') => {
    // Returns platform-appropriate styles based on variant, size, and state
    return getButtonStyles(props.variant, props.size, state, platform);
  }, [props.variant, props.size, state]);

  return {
    state,
    setState,
    handlePress,
    getStyleVariant
  };
};

Web implementation:

// Button.web.tsx
export const Button: React.FC<ButtonProps> = (props) => {
  const { state, setState, handlePress, getStyleVariant } = useButtonLogic(props);
  const styles = getStyleVariant('web');

  return (
    <button
      className={`button ${styles.className}`}
      onMouseEnter={() => setState(s => ({ ...s, isHovered: true }))}
      onMouseLeave={() => setState(s => ({ ...s, isHovered: false }))}
      onMouseDown={() => setState(s => ({ ...s, isPressed: true }))}
      onMouseUp={() => setState(s => ({ ...s, isPressed: false }))}
      onFocus={() => setState(s => ({ ...s, isFocused: true }))}
      onBlur={() => setState(s => ({ ...s, isFocused: false }))}
      onClick={handlePress}
      disabled={props.disabled}
    >
      {props.loading && <Spinner size="small" />}
      {props.children}
    </button>
  );
};

React Native implementation:

// Button.native.tsx
import { Pressable, Text, View } from 'react-native';
import * as Haptics from 'expo-haptics';

export const Button: React.FC<ButtonProps> = (props) => {
  const { handlePress, getStyleVariant } = useButtonLogic(props);
  const styles = getStyleVariant('mobile');

  const handlePressWithHaptics = () => {
    Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
    handlePress();
  };

  return (
    <Pressable
      style={({ pressed }) => [
        styles.button,
        pressed && styles.pressed,
        props.disabled && styles.disabled
      ]}
      onPress={handlePressWithHaptics}
      disabled={props.disabled || props.loading}
    >
      <View style={styles.content}>
        {props.loading && <ActivityIndicator size="small" color={styles.textColor} />}
        <Text style={styles.text}>{props.children}</Text>
      </View>
    </Pressable>
  );
};

Component library structure

Organizing cross-platform components requires a clear directory structure that separates shared logic from platform-specific implementations:

src/
├── components/
│   ├── Button/
│   │   ├── index.ts                    # Platform-specific exports
│   │   ├── Button.types.ts             # Shared TypeScript interfaces
│   │   ├── Button.logic.ts             # Shared business logic
│   │   ├── Button.styles.ts            # Style generation functions
│   │   ├── Button.web.tsx              # Web implementation
│   │   ├── Button.native.tsx           # React Native implementation
│   │   ├── Button.stories.tsx          # Storybook stories
│   │   └── Button.test.tsx             # Shared tests
│   ├── Input/
│   ├── Modal/
│   └── Navigation/
├── tokens/
│   ├── colors.json
│   ├── typography.json
│   └── spacing.json
└── utils/
    ├── platform.ts                     # Platform detection utilities
    └── styles.ts                       # Style helper functions

Advanced component patterns

For complex components that need to adapt significantly across platforms, consider using the adapter pattern:

// Component adapter interface
interface ComponentAdapter<Props, NativeProps> {
  adaptProps: (props: Props) => NativeProps;
  getDefaultProps: () => Partial<Props>;
  validateProps: (props: Props) => boolean;
}

// Web adapter for Navigation component
const WebNavigationAdapter: ComponentAdapter<NavigationProps, WebNavProps> = {
  adaptProps: (props) => ({
    ...props,
    role: 'navigation',
    'aria-label': props.accessibilityLabel,
    className: `navigation navigation--${props.variant}`
  }),
  getDefaultProps: () => ({
    variant: 'horizontal',
    showLabels: true
  }),
  validateProps: (props) => {
    return props.items.length > 0 && props.items.length <= 7;
  }
};

// Mobile adapter for Navigation component
const MobileNavigationAdapter: ComponentAdapter<NavigationProps, MobileNavProps> = {
  adaptProps: (props) => ({
    ...props,
    screenOptions: {
      tabBarStyle: getTabBarStyle(props.variant),
      tabBarShowLabel: props.showLabels,
      tabBarAccessibilityLabel: props.accessibilityLabel
    }
  }),
  getDefaultProps: () => ({
    variant: 'bottom-tabs',
    showLabels: false // Mobile typically shows icons only
  }),
  validateProps: (props) => {
    return props.items.length > 0 && props.items.length <= 5; // iOS HIG guideline
  }
};

Workflow integration and developer experience

A successful cross-platform design system requires seamless integration between design and development workflows. This involves establishing clear handoff processes, automated documentation, and developer-friendly tooling.

Design-to-development handoff

Modern design tools can integrate directly with development workflows through plugins and APIs. Here’s how to set up automated design token sync with Figma:

// figma-token-sync.js
const { Figma } = require('figma-api');
const fs = require('fs');

const figma = new Figma({
  personalAccessToken: process.env.FIGMA_TOKEN,
});

async function syncTokensFromFigma() {
  try {
    const file = await figma.getFile(process.env.FIGMA_FILE_KEY);
    
    // Extract design tokens from Figma styles
    const colors = extractColorsFromStyles(file.styles);
    const typography = extractTypographyFromStyles(file.styles);
    const spacing = extractSpacingFromComponents(file.document);
    
    const tokens = {
      color: colors,
      typography: typography,
      spacing: spacing
    };
    
    // Write tokens to JSON file
    fs.writeFileSync('./tokens/design-tokens.json', JSON.stringify(tokens, null, 2));
    
    console.log('Design tokens synced successfully from Figma');
  } catch (error) {
    console.error('Error syncing tokens:', error);
  }
}

function extractColorsFromStyles(styles) {
  const colors = {};
  
  Object.values(styles).forEach(style => {
    if (style.styleType === 'FILL') {
      const colorName = style.name.toLowerCase().replace(/\s+/g, '-');
      colors[colorName] = {
        value: rgbToHex(style.fills[0].color),
        type: 'color',
        description: style.description
      };
    }
  });
  
  return colors;
}

// Run sync on design token updates
if (require.main === module) {
  syncTokensFromFigma();
}

Automated documentation and testing

Storybook serves as the central hub for cross-platform component documentation and testing:

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-design-tokens',
    '@storybook/addon-viewport',
    '@storybook/addon-a11y'
  ],
  features: {
    buildStoriesJson: true
  }
};

Component stories that work across platforms:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'Primary button component that works across web and mobile platforms.'
      }
    },
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/...'
    }
  },
  argTypes: {
    variant: {
      control: { type: 'select' },
      options: ['primary', 'secondary', 'outline'],
      description: 'Visual style variant'
    },
    size: {
      control: { type: 'select' },
      options: ['small', 'medium', 'large'],
      description: 'Button size'
    }
  }
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Primary Button'
  }
};

export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
    </div>
  ),
  parameters: {
    docs: {
      description: {
        story: 'All button variants displayed together for comparison.'
      }
    }
  }
};

export const Responsive: Story = {
  args: {
    variant: 'primary',
    children: 'Responsive Button'
  },
  parameters: {
    viewport: {
      viewports: {
        mobile: { name: 'Mobile', styles: { width: '375px', height: '667px' } },
        tablet: { name: 'Tablet', styles: { width: '768px', height: '1024px' } },
        desktop: { name: 'Desktop', styles: { width: '1200px', height: '800px' } }
      }
    }
  }
};

Continuous integration for design systems

Set up automated testing and deployment for your design system:

# .github/workflows/design-system.yml
name: Design System CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run linting
      run: npm run lint
    
    - name: Run tests
      run: npm run test:coverage
    
    - name: Build design tokens
      run: npm run tokens:build
    
    - name: Build Storybook
      run: npm run storybook:build
    
    - name: Visual regression testing
      run: npm run test:visual
    
    - name: Component library build
      run: npm run build
    
    - name: Publish to npm (if main branch)
      if: github.ref == 'refs/heads/main'
      run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
    
    - name: Deploy Storybook (if main branch)
      if: github.ref == 'refs/heads/main'
      run: npm run storybook:deploy
      env:
        STORYBOOK_DEPLOY_TOKEN: ${{ secrets.STORYBOOK_TOKEN }}

Visual regression testing

Visual regression testing catches unintended changes in component appearance across platforms:

// visual-regression.config.js
const { configure } = require('@storybook/testing-library');
const { chromium, webkit, firefox } = require('playwright');

configure({
  testIdAttribute: 'data-testid',
});

const devices = [
  // Web browsers
  { name: 'Chrome Desktop', browser: 'chromium', viewport: { width: 1200, height: 800 } },
  { name: 'Safari Desktop', browser: 'webkit', viewport: { width: 1200, height: 800 } },
  { name: 'Firefox Desktop', browser: 'firefox', viewport: { width: 1200, height: 800 } },
  
  // Mobile viewports
  { name: 'iPhone 12', browser: 'webkit', viewport: { width: 390, height: 844 } },
  { name: 'Pixel 5', browser: 'chromium', viewport: { width: 393, height: 851 } },
];

async function runVisualTests() {
  for (const device of devices) {
    const browser = await require('playwright')[device.browser].launch();
    const context = await browser.newContext({
      viewport: device.viewport,
    });
    
    const page = await context.newPage();
    
    // Test each component story
    const stories = await getStorybookStories();
    
    for (const story of stories) {
      await page.goto(`http://localhost:6006/iframe.html?id=${story.id}`);
      await page.waitForLoadState('networkidle');
      
      // Take screenshot and compare with baseline
      await expect(page).toHaveScreenshot(`${device.name}-${story.title}.png`);
    }
    
    await browser.close();
  }
}

Cross-platform accessibility testing

Ensuring accessibility across platforms requires platform-specific testing approaches:

// accessibility.test.ts
import { render, screen } from '@testing-library/react';
import { render as renderNative } from '@testing-library/react-native';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Button } from './Button';

expect.extend(toHaveNoViolations);

describe('Button Accessibility', () => {
  // Web accessibility tests
  describe('Web', () => {
    it('should have no accessibility violations', async () => {
      const { container } = render(
        <Button variant="primary" onPress={() => {}}>
          Click me
        </Button>
      );
      
      const results = await axe(container);
      expect(results).toHaveNoViolations();
    });
    
    it('should be keyboard navigable', () => {
      render(
        <Button variant="primary" onPress={() => {}}>
          Click me
        </Button>
      );
      
      const button = screen.getByRole('button');
      expect(button).toHaveAttribute('tabIndex', '0');
      
      button.focus();
      expect(button).toHaveFocus();
    });
    
    it('should have proper ARIA attributes', () => {
      render(
        <Button variant="primary" onPress={() => {}} disabled>
          Disabled button
        </Button>
      );
      
      const button = screen.getByRole('button');
      expect(button).toHaveAttribute('aria-disabled', 'true');
    });
  });
  
  // React Native accessibility tests
  describe('React Native', () => {
    it('should have proper accessibility props', () => {
      renderNative(
        <Button variant="primary" onPress={() => {}}>
          Click me
        </Button>
      );
      
      const button = screen.getByRole('button');
      expect(button).toHaveProp('accessible', true);
      expect(button).toHaveProp('accessibilityRole', 'button');
    });
    
    it('should support screen reader announcements', () => {
      renderNative(
        <Button 
          variant="primary" 
          onPress={() => {}} 
          accessibilityLabel="Add item to cart"
        >
          Add to Cart
        </Button>
      );
      
      const button = screen.getByLabelText('Add item to cart');
      expect(button).toBeTruthy();
    });
  });
});

Performance testing across platforms

Monitor performance impact of your design system components:

// performance.test.ts
import { performance } from 'perf_hooks';
import { render } from '@testing-library/react';
import { ComponentList } from './test-utils/ComponentList';

describe('Component Performance', () => {
  it('should render large lists efficiently', () => {
    const startTime = performance.now();
    
    render(
      <ComponentList>
        {Array.from({ length: 1000 }, (_, i) => (
          <Button key={i} variant="primary" onPress={() => {}}>
            Button {i}
          </Button>
        ))}
      </ComponentList>
    );
    
    const endTime = performance.now();
    const renderTime = endTime - startTime;
    
    // Should render 1000 buttons in under 100ms
    expect(renderTime).toBeLessThan(100);
  });
  
  it('should have minimal bundle impact', () => {
    const bundleAnalysis = require('./build/bundle-analysis.json');
    const designSystemSize = bundleAnalysis.assets
      .filter(asset => asset.name.includes('design-system'))
      .reduce((total, asset) => total + asset.size, 0);
    
    // Design system should be under 50KB gzipped
    expect(designSystemSize).toBeLessThan(50 * 1024);
  });
});

Advanced cross-platform strategies

For mature design systems serving large organizations, several advanced strategies can further improve consistency and developer experience.

Dynamic theme switching

Modern applications often require theme switching (light/dark mode, brand variants). Here’s how to implement this across platforms:

// theme-provider.ts
interface Theme {
  colors: ColorTokens;
  typography: TypographyTokens;
  spacing: SpacingTokens;
}

interface ThemeContextValue {
  theme: Theme;
  isDark: boolean;
  toggleTheme: () => void;
  setTheme: (theme: Theme) => void;
}

const ThemeContext = createContext<ThemeContextValue | null>(null);

export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [isDark, setIsDark] = useState(false);
  const [customTheme, setCustomTheme] = useState<Theme | null>(null);
  
  // Listen to system theme changes
  useEffect(() => {
    if (Platform.OS === 'web') {
      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
      setIsDark(mediaQuery.matches);
      
      const handleChange = (e: MediaQueryListEvent) => setIsDark(e.matches);
      mediaQuery.addEventListener('change', handleChange);
      
      return () => mediaQuery.removeEventListener('change', handleChange);
    } else {
      // React Native
      import('react-native').then(({ Appearance }) => {
        setIsDark(Appearance.getColorScheme() === 'dark');
        
        const subscription = Appearance.addChangeListener(({ colorScheme }) => {
          setIsDark(colorScheme === 'dark');
        });
        
        return () => subscription?.remove();
      });
    }
  }, []);
  
  const theme = useMemo(() => {
    const baseTheme = isDark ? darkTheme : lightTheme;
    return customTheme ? mergeThemes(baseTheme, customTheme) : baseTheme;
  }, [isDark, customTheme]);
  
  const value = {
    theme,
    isDark,
    toggleTheme: () => setIsDark(!isDark),
    setTheme: setCustomTheme
  };
  
  return (
    <ThemeContext.Provider value={value}>
      {children}
    </ThemeContext.Provider>
  );
};

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
};

Component composition patterns

For complex components that need significant platform-specific behavior, use composition patterns:

// Composition-based Navigation component
interface NavigationComposition {
  Container: React.ComponentType<NavigationContainerProps>;
  Item: React.ComponentType<NavigationItemProps>;
  Badge: React.ComponentType<NavigationBadgeProps>;
}

// Web implementation
const WebNavigation: NavigationComposition = {
  Container: ({ children, ...props }) => (
    <nav className="navigation" {...props}>
      <ul className="navigation__list">
        {children}
      </ul>
    </nav>
  ),
  
  Item: ({ icon, label, isActive, href, ...props }) => (
    <li className="navigation__item">
      <a 
        href={href}
        className={`navigation__link ${isActive ? 'active' : ''}`}
        {...props}
      >
        {icon && <span className="navigation__icon">{icon}</span>}
        <span className="navigation__label">{label}</span>
      </a>
    </li>
  ),
  
  Badge: ({ count, color = 'primary' }) => (
    <span className={`navigation__badge navigation__badge--${color}`}>
      {count}
    </span>
  )
};

// React Native implementation
const NativeNavigation: NavigationComposition = {
  Container: ({ children, ...props }) => (
    <Tab.Navigator {...props}>
      {children}
    </Tab.Navigator>
  ),
  
  Item: ({ icon, label, component, ...props }) => (
    <Tab.Screen
      name={label}
      component={component}
      options={{
        tabBarIcon: ({ focused, color, size }) => 
          React.cloneElement(icon, { color, size }),
        tabBarLabel: label,
        ...props
      }}
    />
  ),
  
  Badge: ({ count, color = 'primary' }) => (
    <View style={[styles.badge, { backgroundColor: colors[color] }]}>
      <Text style={styles.badgeText}>{count}</Text>
    </View>
  )
};

// Platform-specific export
export const Navigation = Platform.select({
  web: WebNavigation,
  default: NativeNavigation
});

// Usage remains consistent across platforms
const App = () => (
  <Navigation.Container>
    <Navigation.Item 
      icon={<HomeIcon />} 
      label="Home" 
      href="/" 
      component={HomeScreen}
    />
    <Navigation.Item 
      icon={<SearchIcon />} 
      label="Search" 
      href="/search"
      component={SearchScreen}
    />
    <Navigation.Item 
      icon={
        <>
          <CartIcon />
          <Navigation.Badge count={3} color="error" />
        </>
      } 
      label="Cart" 
      href="/cart"
      component={CartScreen}
    />
  </Navigation.Container>
);

Conclusion

Building effective cross-platform design systems requires a holistic approach that balances consistency with platform-specific best practices. The key to success lies in establishing a strong foundation with design tokens, creating flexible component architectures that separate logic from presentation, and implementing workflows that seamlessly connect design and development teams.

The strategies outlined in this article—from token-first architecture to composition patterns to comprehensive testing—provide a roadmap for creating design systems that scale across web, mobile, and emerging platforms. The real-world case study demonstrates that the investment in cross-platform design systems pays dividends in development velocity, user experience consistency, and long-term maintainability.

As the digital landscape continues to evolve with new platforms and interaction paradigms, the principles of good cross-platform design remain constant: start with a solid foundation, respect platform conventions while maintaining brand consistency, invest in developer experience, and continuously measure and iterate based on real-world usage.

Remember that building a cross-platform design system is not a one-time project but an ongoing evolution. Start with your most critical components, establish clear governance processes, and gradually expand your system’s scope and sophistication. With careful planning and execution, your cross-platform design system will become a competitive advantage that accelerates development, improves user experiences, and enables your organization to deliver consistent value across all digital touchpoints.

Further reading

• Design Tokens W3C Community Group Specification
• Cross-Platform Component Libraries: A Deep Dive
• Building Accessible Design Systems
• Style Dictionary Documentation
• React Native Web: Shared Component Architecture
• Flutter for Web: Cross-Platform Design Considerations