his ensures that a change in the source of truth propagates automatically.

TypeScript Token Definition:

// tokens/src/types.ts
export interface DesignTokens {
  primitive: {
    color: {
      blue: { 500: string };
      gray: { 900: string };
    };
    spacing: {
      sm: number;
      md: number;
      lg: number;
    };
  };
  semantic: {
    color: {
      primary: string; // Maps to primitive.color.blue.500
      text: string;    // Maps to primitive.color.gray.900
    };
    spacing: {
      containerPadding: number; // Maps to primitive.spacing.md
    };
  };
}

// tokens/src/tokens.json
{
  "primitive": {
    "color": {
      "blue": { "500": "#0055FF" },
      "gray": { "900": "#1A1A1A" }
    },
    "spacing": {
      "sm": 8,
      "md": 16,
      "lg": 24
    }
  },
  "semantic": {
    "color": {
      "primary": "{primitive.color.blue.500}",
      "text": "{primitive.color.gray.900}"
    },
    "spacing": {
      "containerPadding": "{primitive.spacing.md}"
    }
  }
}

2. Component Library Architecture

Components must consume semantic tokens exclusively. Hardcoding primitive values within components is prohibited. This enforces themeability and ensures that global updates (e.g., dark mode, brand refresh) require zero component code changes.

React Native Component Example:

// components/src/Button.tsx
import React from 'react';
import { TouchableOpacity, Text, StyleSheet } from 'react-native';
import { useDesignTokens } from '@codcompass/tokens';

interface ButtonProps {
  variant?: 'primary' | 'secondary';
  label: string;
  onPress: () => void;
}

export const Button: React.FC<ButtonProps> = ({ variant = 'primary', label, onPress }) => {
  const tokens = useDesignTokens();

  const styles = StyleSheet.create({
    container: {
      backgroundColor: variant === 'primary' 
        ? tokens.semantic.color.primary 
        : tokens.semantic.color.backgroundSecondary,
      paddingVertical: tokens.semantic.spacing.vertical,
      paddingHorizontal: tokens.semantic.spacing.horizontal,
      borderRadius: tokens.semantic.radius.button,
    },
    label: {
      color: variant === 'primary' 
        ? tokens.semantic.color.textOnPrimary 
        : tokens.semantic.color.text,
      fontWeight: tokens.semantic.font.weight.medium,
    },
  });

  return (
    <TouchableOpacity style={styles.container} onPress={onPress} accessibilityRole="button">
      <Text style={styles.label}>{label}</Text>
    </TouchableOpacity>
  );
};

3. Automation and Synchronization

Manual synchronization is a failure point. Implement a pipeline where:

1. Designers update tokens in Figma using a plugin that exports to the JSON schema.
2. A commit triggers a CI job that runs token transformers.
3. Transformers generate Swift structs, Kotlin objects, and TypeScript interfaces.
4. Generated code is published to private registries or committed to the monorepo.
5. Visual regression tests validate the output against baseline screenshots.

Architecture Rationale:

• Monorepo vs. Polyrepo: For mobile teams, a monorepo (e.g., using Nx or Turborepo) is recommended to share token definitions and component logic across iOS, Android, and shared web packages. This reduces versioning friction.
• Semantic Versioning: Tokens and components must follow SemVer. Breaking changes in token structure require major version bumps to prevent runtime crashes in consuming apps.

Pitfall Guide

1. Over-Engineering Component APIs

Mistake: Creating components with excessive props to handle every edge case. Impact: Components become brittle and difficult to maintain. Best Practice: Compose components. Build primitives (Box, Text, Icon) and combine them for complex UIs. Only abstract patterns that appear in three or more distinct contexts.

2. Ignoring Accessibility by Default

Mistake: Treating accessibility as an afterthought or a separate checklist. Impact: Non-compliant apps, legal risk, and poor UX for assistive technology users. Best Practice: Bake accessibility into the design system. Tokens should include focus ring widths and contrast ratios. Components should expose accessibilityLabel, accessibilityHint, and role by default. Implement automated accessibility scanning in CI.

3. Token Drift Between Figma and Code

Mistake: Designers and engineers maintaining separate lists of values. Impact: UI inconsistencies and "design debt." Best Practice: Enforce a single source of truth. Use tools like Style Dictionary or custom transformers to generate code from the canonical token file. Figma should be configured to read from the same source, or a sync plugin must run on every design change.

4. Hardcoding Platform-Specific Values

Mistake: Embedding iOS/Android specific metrics directly in shared logic. Impact: Inconsistent behavior and inability to share components across platforms. Best Practice: Abstract platform differences into token layers. For example, define safeAreaInset as a token that resolves to different values on iOS and Android, rather than hardcoding 20 or 24 in component styles.

5. Lack of Governance and Ownership

Mistake: Allowing any team member to add tokens or components without review. Impact: Token bloat, naming chaos, and duplicate components. Best Practice: Establish a Design System Guild. Require PR reviews for token additions. Define strict naming conventions and deprecation policies. Maintain a changelog that communicates changes to all product teams.

6. Performance Overhead in Abstraction

Mistake: Creating heavy wrapper components that trigger excessive re-renders or layout calculations. Impact: Jank and poor scroll performance on low-end devices. Best Practice: Profile components regularly. Use React.memo or equivalent optimizations. Ensure token access is efficient (e.g., cached context providers rather than repeated lookups). Avoid deep nesting of style abstractions.

7. Neglecting Dark Mode and Theming

Mistake: Building the system only for light mode or hardcoding colors. Impact: Inability to support system themes, requiring a complete rewrite later. Best Practice: Design tokens must support dynamic values. Structure tokens to support multiple themes (e.g., light and dark branches). Components should resolve colors based on the active theme context, not static values.

Production Bundle

Action Checklist

• Audit Existing UI: Inventory current components and identify duplicates, inconsistencies, and hardcoded values.
• Define Token Schema: Create the JSON structure for primitive, semantic, and component tokens. Establish naming conventions.
• Select Tooling: Choose a token transformer (e.g., Style Dictionary) and a monorepo manager. Configure Figma plugins for export.
• Build Core Primitives: Implement foundational components (Box, Text, Icon, Button) using semantic tokens only.
• Implement Automation: Set up CI/CD pipeline to transform tokens and generate platform-specific code on commit.
• Establish Governance: Create contribution guidelines, review processes, and a deprecation policy.
• Add Visual Regression Tests: Integrate tools like Percy or Chromatic to detect UI changes automatically.
• Document Usage: Provide code snippets, design guidelines, and accessibility requirements for every component.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup / MVP	Lightweight Token Set + Shared React Native Components	Speed to market; avoid over-engineering. Focus on core tokens and high-frequency components.	Low initial setup; moderate maintenance as scale increases.
Enterprise / Multi-Brand	Full Token Hierarchy + Platform-Specific Wrappers + Governance Guild	Supports theming, brand variations, and strict compliance. Requires rigorous versioning.	High initial investment; low long-term maintenance cost.
iOS/Android Native Only	Token Transformers to Swift/Kotlin + Shared Design Library	No cross-platform framework overhead. Direct integration with native UI kits.	Medium setup; requires discipline to keep native implementations aligned.
Design-Heavy Culture	Figma-First Workflow + Automated Code Generation	Empowers designers; reduces engineering friction. Ensures pixel-perfect implementation.	Medium setup; requires robust plugin ecosystem and sync reliability.

Configuration Template

tokens.config.js (Style Dictionary Example)

module.exports = {
  source: ['src/tokens/**/*.json'],
  platforms: {
    ts: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.d.ts',
        format: 'typescript/declarations',
      }],
    },
    swift: {
      transformGroup: 'ios',
      buildPath: 'dist/ios/',
      files: [{
        destination: 'DesignTokens.swift',
        format: 'ios-swift/enum',
      }],
    },
    kotlin: {
      transformGroup: 'android',
      buildPath: 'dist/android/',
      files: [{
        destination: 'DesignTokens.kt',
        format: 'android/resources',
      }],
    },
  },
};

package.json (Design System Package)

{
  "name": "@codcompass/mobile-design-system",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build:tokens": "style-dictionary build",
    "build:components": "tsc --project tsconfig.build.json",
    "lint": "eslint src/",
    "test": "jest --coverage",
    "prepublishOnly": "npm run build:tokens && npm run build:components && npm run lint && npm run test"
  },
  "dependencies": {
    "react-native": ">=0.68.0"
  },
  "devDependencies": {
    "style-dictionary": "^3.7.0",
    "typescript": "^5.0.0",
    "jest": "^29.0.0"
  }
}

Quick Start Guide

1. Initialize Monorepo: Run npx create-codcompass-app --type mobile-design-system. This scaffolds a monorepo with packages/tokens, packages/components, and CI configuration.
2. Generate Tokens: Add your initial tokens.json to packages/tokens/src. Run npm run build:tokens to generate TypeScript interfaces and platform code. Verify output in dist/.
3. Create First Component: In packages/components/src, create Button.tsx. Import tokens using useDesignTokens(). Implement styles referencing semantic tokens. Export the component.
4. Link to App: In your mobile app monorepo, add @codcompass/mobile-design-system as a workspace dependency. Import Button and verify it renders correctly with tokenized styles.
5. Enable Sync: Install the Figma plugin configured in the repo. Connect your Figma file to the token source. Push a design change and verify the CI pipeline generates updated code within minutes.