? 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)**

```javascript
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.