Platform-Specific Considerations for Converting Stitch Designs to React Native

TLDR: Converting Stitch designs to React Native requires mapping web components to native equivalents, translating CSS to StyleSheet objects, handling platform-specific code with Platform.select, bundling assets via require(), and validating the output using the provided scripts in the google-labs-code/stitch-skills repository.

Stitch generates design specifications optimized for web environments using HTML and CSS. When targeting React Native—where the rendering layer uses native iOS and Android components instead of the DOM—developers must transform web-centric patterns into mobile-native equivalents. The google-labs-code/stitch-skills repository provides the necessary templates, validation scripts, and architecture checklists to facilitate this conversion while respecting platform constraints.

Component Mapping from Web to Native

Stitch outputs generic component definitions that assume a web context. In React Native, you must map these to native component equivalents.

Replace web elements like <div> and <span> with React Native primitives:

• <View> replaces block-level containers
• <Text> replaces text spans and headings
• <Image> replaces <img> tags
• <TouchableOpacity> or <Pressable> replace click handlers

The repository provides a reference implementation in plugins/stitch-build/skills/react-native/resources/component-template.tsx that demonstrates the expected JSX structure for generated components. This template serves as the foundation for transforming Stitch design nodes into native mobile components.

Styling Strategy and Layout Adaptations

Web-centric CSS and Tailwind classes do not translate directly to React Native. The platform uses JavaScript-based StyleSheet objects that support only a subset of CSS properties.

Converting CSS to StyleSheet

React Native requires explicit StyleSheet definitions rather than inline CSS classes. According to the architecture-checklist.md in the repository, you must convert pixel values to density-independent pixels (dp) and remove unsupported properties like box-shadow or float.

// src/components/GeneratedCard.tsx
import { View, Text, Image, StyleSheet } from 'react-native';

export const GeneratedCard = () => (
  <View style={styles.container}>
    <Image 
      source={require('../assets/card-image.png')} 
      style={styles.image} 
    />
    <Text style={styles.title}>Stitch-Generated Card</Text>
  </View>
);

const styles = StyleSheet.create({
  container: {
    padding: 16,
    backgroundColor: '#fff',
    borderRadius: 8,
    marginBottom: 12, // Converted to dp units
  },
  image: {
    width: 120,
    height: 80,
    resizeMode: 'cover',
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
    color: '#212121',
  },
});

Handling Responsive Layout

Mobile screens vary in size and pixel density. The architecture-checklist.md recommends using the Dimensions API or Flexbox heuristics to adapt Stitch design tokens (spacing, typography) to mobile viewport constraints. Avoid absolute positioning when possible; instead apply Flexbox layouts that reflow across screen sizes.

Platform-Specific Implementation

React Native applications run on both iOS and Android, but UI patterns and styling defaults differ between platforms. The conversion process must account for these variations.

Using Platform.select

For components that require different styling or behavior per platform, use Platform.select to branch logic. The validate.js script specifically checks for missing platform guards when analyzing the converted output.

// src/components/PlatformButton.tsx
import { TouchableOpacity, Text, Platform, StyleSheet } from 'react-native';

export const PlatformButton = ({ label, onPress }) => (
  <TouchableOpacity
    style={Platform.select({
      ios: styles.iosButton,
      android: styles.androidButton,
    })}
    onPress={onPress}
  >
    <Text style={styles.label}>{label}</Text>
  </TouchableOpacity>
);

const styles = StyleSheet.create({
  iosButton: {
    backgroundColor: '#007AFF',
    borderRadius: 8,
    paddingVertical: 10,
    paddingHorizontal: 20,
  },
  androidButton: {
    backgroundColor: '#2196F3',
    elevation: 2, // Android-specific shadow
    borderRadius: 2,
    paddingVertical: 12,
    paddingHorizontal: 24,
  },
  label: {
    color: '#fff',
    textAlign: 'center',
  },
});

File-Level Platform Splitting

For complex variations, the repository supports platform-specific file extensions. Create separate implementations using Component.ios.tsx and Component.android.tsx when the differences exceed simple styling branches. The validate.js script validates that these files exist when platform-specific logic is detected.

Asset Management and Navigation

Stitch designs reference images and fonts using web URLs. React Native requires these assets to be bundled with the application binary.

Bundling Assets

Convert web asset URLs to local require() statements. The package.json in plugins/stitch-build/skills/react-native/package.json defines the necessary dependencies for asset handling, while the architecture checklist specifies that all images must reside in the native project bundle.

// src/assets/index.ts
export const images = {
  logo: require('./logo.png'),    // Bundled with the app
  hero: require('./hero.jpg'),
};

Implementing Navigation

Web-style routing (e.g., React Router) is not available in React Native. The component-template.tsx includes placeholders for integrating React Navigation, which uses native navigation controllers.

// src/navigation/AppNavigator.tsx
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { GeneratedCard } from '../components/GeneratedCard';

const Stack = createStackNavigator();

export const AppNavigator = () => (
  <NavigationContainer>
    <Stack.Navigator initialRouteName="Home">
      <Stack.Screen name="Home" component={GeneratedCard} />
    </Stack.Navigator>
  </NavigationContainer>
);

Validation and Build Pipeline

The repository provides automation scripts to ensure converted designs meet React Native constraints.

Fetching Design Data

Use fetch-stitch.sh to pull the latest Stitch design JSON. This script retrieves the design specification from the Stitch output pipeline, preparing it for transformation.

Validating Platform Constraints

Run validate.js to catch unsupported web constructs before building. This script checks for:

• Missing platform selectors on platform-specific UI patterns
• Unsupported CSS properties in StyleSheet definitions
• Missing asset references

The validation step prevents runtime errors by enforcing the constraints documented in architecture-checklist.md.

Summary

• Map components from web elements to React Native primitives (View, Text, Image) using the template in component-template.tsx.
• Convert styles to StyleSheet objects, removing unsupported CSS and adapting to dp units.
• Handle platform differences via Platform.select or separate .ios.tsx and .android.tsx files.
• Bundle assets using require() rather than web URLs.
• Replace web routing with React Navigation structures.
• Validate conversions using fetch-stitch.sh and validate.js before compilation.

Frequently Asked Questions

How do I handle web-specific CSS properties like box-shadow in React Native?

React Native's StyleSheet does not support box-shadow. For iOS, use the shadowColor, shadowOffset, shadowOpacity, and shadowRadius properties. For Android, use the elevation style property. The validate.js script flags unsupported properties during conversion.

Can I use the same component files for both iOS and Android?

Yes, for shared logic. Use Platform.select within a single file for minor styling differences. For significantly different implementations, create separate files with .ios.tsx and .android.tsx extensions. The validate.js script checks for proper platform guards in either approach.

How are Stitch design tokens converted to React Native units?

Stitch outputs design tokens in pixels. React Native uses density-independent pixels (dp) which map 1:1 with CSS pixels on standard density screens. The architecture-checklist.md recommends passing these values directly to StyleSheet while using Flexbox for responsive layouts rather than absolute pixel positioning.

Where can I find a complete reference implementation?

The repository includes examples/gold-standard-card.tsx, a fully-realized component generated from a Stitch design. This file demonstrates proper component mapping, StyleSheet usage, and platform-specific handling, serving as the authoritative reference for conversion quality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}