From 62d6d4d5b04580da6b71932e47d96b461e0b6dc2 Mon Sep 17 00:00:00 2001
From: jilinxia <jilinxia@google.com>
Date: Mon, 29 Jun 2026 13:35:11 -0700
Subject: [PATCH 1/5] docs(skills): restructure react-components and
 react-native with phased gates

- Restructure react-components and react-native skills into four phases
- Add explicit quality gates, anti-patterns, and troubleshooting for each phase
- Explicitly cover syncing and updating existing components to align with the latest Stitch designs
- Restore name field in react-components to stitch::react-components for consistency
---
 .../skills/react-components/SKILL.md          | 105 +++++++++---
 .../stitch-build/skills/react-native/SKILL.md | 162 +++++++++++-------
 2 files changed, 183 insertions(+), 84 deletions(-)

diff --git a/plugins/stitch-build/skills/react-components/SKILL.md b/plugins/stitch-build/skills/react-components/SKILL.md
index 1dece3f..44985d6 100644
--- a/plugins/stitch-build/skills/react-components/SKILL.md
+++ b/plugins/stitch-build/skills/react-components/SKILL.md
@@ -1,6 +1,9 @@
 ---
 name: stitch::react-components
-description: Converts Stitch designs into modular Vite and React components using system-level networking and AST-based validation.
+description: >-
+  Converts Stitch designs into modular Vite and React components, or syncs/updates
+  existing React components to align with the latest Stitch designs, using system-level
+  networking and AST-based validation.
 allowed-tools:
   - "stitch*:*"
   - "Bash"
@@ -11,46 +14,100 @@ allowed-tools:
 
 # Stitch to React Components
 
-You are a frontend engineer focused on transforming designs into clean React code. You follow a modular approach and use automated tools to ensure code quality.
+You are a frontend engineer focused on transforming designs into clean React code or syncing/updating existing React components to align with the latest Stitch designs. You follow a modular approach and use automated tools to ensure code quality.
+
+> **CRITICAL: Every step in this skill is MANDATORY. Do NOT skip any step or take shortcuts. Each section contains a GATE that must be satisfied before proceeding.**
+
+## Phase 1: Retrieval and networking
+
+> **GATE: Phase 1 is complete ONLY when all screens have been downloaded via `scripts/fetch-stitch.sh` AND visually audited. Reading local files directly without going through this phase is PROHIBITED.**
 
-## Retrieval and networking
 1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
-2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
+2. **Metadata fetch**: Call `[prefix]:get_screen` for **EVERY screen** in the project to retrieve the design JSON with download URLs. Do NOT skip any screen.
 3. **Check for existing designs**: Before downloading, check if `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png` already exist:
-   - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. Only re-download if the user confirms.
+   - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. **You MUST ask — do not assume.**  Only re-download if the user confirms.
    - **If files do not exist**: Proceed to step 4.
-4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
+4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains. You MUST use the provided script.
    - **HTML**: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"`
-    - **Screenshot**: Append `=w{width}` to the screenshot URL first, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Then run: `bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"`
+   - **Screenshot**: Append `=w{width}` to the screenshot URL first, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Then run: `bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"`
    - This script handles the necessary redirects and security handshakes.
-5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details.
+5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details. **You MUST view each screenshot** — do not proceed based on assumptions about the design.
+6. **Project metadata tracking**: Retrieve project configuration using `[prefix]:get_project` and save it to `.stitch/metadata.json` (inside the app folder, and mirrored in the workspace root). Ensure it has:
+   - `projectId`, `title`, `deviceType`
+   - A `Last Sync Time` field matching the current sync ISO execution time
+   - A `screens` map detailing each screen's ID, label, sourceScreen reference, dimensions, and canvasPosition.
+
+### Anti-patterns for Phase 1
+- ❌ Reading `.stitch/designs/*.html` directly without calling MCP `get_screen` first.
+- ❌ Skipping the `fetch-stitch.sh` download script.
+- ❌ Not asking the user when existing files are found.
+- ❌ Skipping the visual audit of `.png` screenshots.
+- ❌ Failing to generate or update `.stitch/metadata.json` and its `Last Sync Time` field upon syncing.
+
+## Phase 2: Style extraction
+
+> **GATE: Phase 2 is complete ONLY when `resources/style-guide.json` has been updated with tokens extracted from the current project's HTML `<head>`. Tokens from a previous project are NOT acceptable.**
+
+1. **Extract `tailwind.config`**: Open each downloaded HTML file and locate the `tailwind.config` object in the `<head>` `<script>` block. Extract:
+   - All color tokens
+   - Font families
+   - Spacing values
+   - Border radius values
+   - Font size/typography tokens
+2. **Sync `resources/style-guide.json`**: Overwrite the file with the extracted tokens from THIS project. The style guide MUST match the Stitch project being converted.
+3. **Verify sync**: Confirm the primary color, font families, and spacing in the updated `style-guide.json` match what you extracted.
 
-## Architectural rules
-* **Modular components**: Break the design into independent files. Avoid large, single-file outputs.
-* **Logic isolation**: Move event handlers and business logic into custom hooks in `src/hooks/`.
-* **Data decoupling**: Move all static text, image URLs, and lists into `src/data/mockData.ts`.
-* **Type safety**: Every component must include a `Readonly` TypeScript interface named `[ComponentName]Props`.
+### Anti-patterns for Phase 2
+- ❌ Using `style-guide.json` as-is without verifying it matches the current project.
+- ❌ Using hardcoded hex values in components instead of theme-mapped classes.
+
+## Phase 3: Architectural rules
+
+> **GATE: Every component MUST satisfy ALL of the following rules. Violations will cause `npm run validate` to fail.**
+
+* **Modular components**: Break the design into independent files. **Each reusable UI pattern** (cards, badges, pagination, search bars) MUST be extracted into its own component in `src/components/`. Monolithic page files that contain everything are PROHIBITED.
+* **Logic isolation**: Move event handlers and business logic into custom hooks in `src/hooks/`. Examples: pagination logic → `usePagination`, filtering → `useFilter`.
+* **Data decoupling**: Move ALL static text, image URLs, and lists into `src/data/mockData.ts`. No hardcoded content in components.
+* **Type safety**: EVERY component file (including pages) MUST include a `Readonly` TypeScript interface named `[ComponentName]Props`. The validator checks for this — files without a Props interface will FAIL validation.
 * **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React components.
 * **Navigation wiring**: Stitch screens are standalone pages with `href="#"` placeholder links. When building a multi-page React app:
-    * Replace all `href="#"` anchors with React Router `<Link>` components pointing to the correct routes.
+    * Replace ALL `href="#"` anchors with React Router `<Link>` components pointing to the correct routes.
     * **Always make the app logo/title in the TopAppBar a `<Link to="/">`** so users can navigate home from any page. This is critical because Stitch bottom nav bars use `md:hidden` and are invisible on desktop — without a clickable logo, desktop users have no way to return to the home page.
     * Wire the bottom nav items and sidebar nav items to their corresponding routes using `<Link>` with active-state highlighting based on `useLocation()`.
-* **Style mapping**:
-    * Extract the `tailwind.config` from the HTML `<head>`.
-    * Sync these values with `resources/style-guide.json`.
-    * Use theme-mapped Tailwind classes instead of arbitrary hex codes.
+* **Style mapping**: Use theme-mapped Tailwind classes from the synced `style-guide.json`. No arbitrary hex codes.
+* **Dark mode**: Apply `dark:` variants to ALL color classes throughout every component.
+
+### Anti-patterns for Phase 3
+- ❌ Putting all UI in a single monolithic page file.
+- ❌ Inline event handlers or business logic without hooks.
+- ❌ Hardcoding text, URLs, or data in component files.
+- ❌ Components without a `[Name]Props` interface.
+- ❌ Using hex color values instead of theme tokens.
+- ❌ Leaving `href="#"` links unconverted.
+
+## Phase 4: Execution steps
+
+> **GATE: Phase 4 is complete ONLY when ALL validation checks pass and the dev server renders correctly.**
 
-## Execution steps
 1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
 2. **Data layer**: Create `src/data/mockData.ts` based on the design content.
-3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace all instances of `StitchComponent` with the actual name of the component you are creating.
+3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace ALL instances of `StitchComponent` with the actual name of the component you are creating.
 4. **Application wiring**: Update the project entry point (like `App.tsx`) to render the new components.
-5. **Quality check**:
-    * Run `npm run validate <file_path>` for each component.
-    * Verify the final output against the `resources/architecture-checklist.md`.
+5. **Quality check** — ALL of the following are MANDATORY:
+    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in `src/components/` and `src/pages/`. ALL must report `✨ COMPONENT VALID.`
+    * Run `tsc --noEmit` to verify zero TypeScript errors.
+    * Verify the final output against `resources/architecture-checklist.md` — every checkbox must be satisfied.
     * Start the dev server with `npm run dev` to verify the live result.
+    * Report the validation results to the user with a clear pass/fail summary.
+
+### Anti-patterns for Phase 4
+- ❌ Skipping `npm run validate` for any component.
+- ❌ Not running `tsc --noEmit`.
+- ❌ Not checking `resources/architecture-checklist.md`.
+- ❌ Declaring "done" without starting the dev server.
 
 ## Troubleshooting
 * **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
-* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles.
+* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles. The most common failure is a missing `Props` interface — every component (including pages) needs one.
 * **Dead navigation links**: Stitch HTML uses `href="#"` placeholders everywhere. Every `<a href="#">` must be converted to a `<Link to="/route">` with a real route. Verify all nav items are clickable and lead to the correct page.
+* **Stale style-guide.json**: If colors or fonts look wrong, the `style-guide.json` likely has tokens from a different project. Re-extract from the current HTML `<head>`.
\ No newline at end of file
diff --git a/plugins/stitch-build/skills/react-native/SKILL.md b/plugins/stitch-build/skills/react-native/SKILL.md
index 3a0004b..14bb42a 100644
--- a/plugins/stitch-build/skills/react-native/SKILL.md
+++ b/plugins/stitch-build/skills/react-native/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: stitch::react-native
-description: Convert Stitch HTML designs to React Native components with StyleSheet
+description: >-
+  Convert Stitch HTML designs to React Native components, or syncs/updates existing
+  native components to align with the latest Stitch designs, using StyleSheet.
 allowed-tools:
   - "stitch*:*"
   - "Bash"
@@ -11,21 +13,57 @@ allowed-tools:
 
 # Stitch to React Native Components
 
-You are a mobile engineer focused on transforming Stitch web designs into clean, production-ready React Native code. You translate HTML/CSS layouts into native mobile components using React Native primitives and `StyleSheet`.
+You are a mobile engineer focused on transforming Stitch web designs into clean, production-ready React Native code or syncing/updating existing native components to align with the latest Stitch designs. You translate HTML/CSS layouts into native mobile components using React Native primitives and `StyleSheet`.
+
+> **CRITICAL: Every step in this skill is MANDATORY. Do NOT skip any step or take shortcuts. Each section contains a GATE that must be satisfied before proceeding.**
+
+## Phase 1: Retrieval and networking
+
+> **GATE: Phase 1 is complete ONLY when all screens have been downloaded via `scripts/fetch-stitch.sh` AND visually audited. Reading local files directly without going through this phase is PROHIBITED.**
 
-## Retrieval and networking
 1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
-2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
+2. **Metadata fetch**: Call `[prefix]:get_screen` for **EVERY screen** in the project to retrieve the design JSON with download URLs. Do NOT skip any screen.
 3. **Check for existing designs**: Before downloading, check if `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png` already exist:
-   - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. Only re-download if the user confirms.
+   - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. **You MUST ask — do not assume.** Only re-download if the user confirms.
    - **If files do not exist**: Proceed to step 4.
-4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
+4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains. You MUST use the provided script.
    - **HTML**: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"`
    - **Screenshot**: Append `=w{width}` to the screenshot URL first, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Then run: `bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"`
    - This script handles the necessary redirects and security handshakes.
-5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details.
+5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details. **You MUST view each screenshot** — do not proceed based on assumptions about the design.
+6. **Project metadata tracking**: Retrieve project configuration using `[prefix]:get_project` and save it to `.stitch/metadata.json` (inside the app folder, and mirrored in the workspace root). Ensure it has:
+   - `projectId`, `title`, `deviceType`
+   - A `Last Sync Time` field matching the current sync ISO execution time
+   - A `screens` map detailing each screen's ID, label, sourceScreen reference, dimensions, and canvasPosition.
+
+### Anti-patterns for Phase 1
+- ❌ Reading `.stitch/designs/*.html` directly without calling MCP `get_screen` first.
+- ❌ Skipping the `fetch-stitch.sh` download script.
+- ❌ Not asking the user when existing files are found.
+- ❌ Skipping the visual audit of `.png` screenshots.
+- ❌ Failing to generate or update `.stitch/metadata.json` and its `Last Sync Time` field upon syncing.
+
+## Phase 2: Theme extraction
+
+> **GATE: Phase 2 is complete ONLY when `src/theme.ts` has been created or updated with tokens extracted from the current project's HTML `<head>`. Hardcoding color hex codes or using themes from a different project is NOT acceptable.**
+
+1. **Extract `tailwind.config`**: Open each downloaded HTML file and locate the `tailwind.config` object in the `<head>` `<script>` block. Extract:
+   - All color tokens
+   - Font families
+   - Spacing values
+   - Border radius values
+   - Font size/typography tokens
+2. **Create/Sync `src/theme.ts`**: Write the extracted tokens to `src/theme.ts` as TypeScript constants. Ensure every color, spacing, and typography value has a corresponding token.
+3. **Verify theme**: Confirm the theme colors and fonts in `src/theme.ts` match what you extracted from the HTML design.
+
+### Anti-patterns for Phase 2
+- ❌ Hardcoding color hex codes or rgba strings directly inside component StyleSheet declarations.
+- ❌ Using theme tokens from a previous project without extracting them from the new design.
+- ❌ Skipping the creation/update of `src/theme.ts`.
 
-## HTML to React Native mapping
+## Phase 3: Architectural rules and HTML mapping
+
+> **GATE: Every component MUST satisfy ALL of the following rules. Violations will cause `npm run validate` to fail.**
 
 ### Element mapping
 Map HTML elements to React Native components using these rules:
@@ -47,42 +85,40 @@ Map HTML elements to React Native components using these rules:
 ### Style mapping
 CSS and Tailwind classes do not work in React Native. Convert all styles to `StyleSheet.create()`:
 
-**Layout**: Flexbox is the default layout system. `flexDirection` defaults to `'column'` (not `'row'` like web CSS).
-- `display: flex` is implicit on every `View`.
-- `justify-content` maps to `justifyContent`.
-- `align-items` maps to `alignItems`.
-- `gap` maps to `gap` (React Native 0.71+). For older versions, use `marginBottom` on children.
-
-**Dimensions**: Use numbers (not strings). `width: 100` means 100 density-independent pixels.
-- Percentage strings are supported: `width: '100%'`.
-- For responsive sizing, use `useWindowDimensions()` from `react-native`.
-- There is no `vw`/`vh`. Calculate from `Dimensions.get('window')`.
-
-**Typography**: All text styles must be on `Text` components, never on `View`.
-- `font-size` maps to `fontSize` (number, not string).
-- `font-weight` maps to `fontWeight` (string: `'400'`, `'700'`, `'bold'`).
-- `line-height` maps to `lineHeight` (number).
-- `letter-spacing` maps to `letterSpacing`.
-- `text-transform` maps to `textTransform`.
-- `color` applies to `Text` only.
-
-**Borders and shadows**:
-- `border-radius` maps to `borderRadius`.
-- `box-shadow` does not exist. Use `elevation` (Android) and `shadowColor`/`shadowOffset`/`shadowOpacity`/`shadowRadius` (iOS).
-- Use `Platform.select()` to apply platform-specific shadow styles.
-
-**Unsupported CSS properties** (handle manually or skip):
-- `hover`, `transition`, `animation` (use `react-native-reanimated` for animations).
-- `position: fixed` (use `position: 'absolute'` with manual offset).
-- `overflow: auto` (use `ScrollView`).
-- `z-index` works but only between sibling views.
-- `opacity` works. `visibility: hidden` does not exist; use conditional rendering or `opacity: 0`.
-
-**Color extraction**: Extract the Tailwind config from the HTML `<head>`. Map color tokens to a `theme.ts` constants file instead of hardcoding hex values in StyleSheet.
+* **Layout**: Flexbox is the default layout system. `flexDirection` defaults to `'column'` (not `'row'` like web CSS).
+  - `display: flex` is implicit on every `View`.
+  - `justify-content` maps to `justifyContent`.
+  - `align-items` maps to `alignItems`.
+  - `gap` maps to `gap` (React Native 0.71+). For older versions, use `marginBottom` on children.
+* **Dimensions**: Use numbers (not strings). `width: 100` means 100 density-independent pixels.
+  - Percentage strings are supported: `width: '100%'`.
+  - For responsive sizing, use `useWindowDimensions()` from `react-native`.
+  - There is no `vw`/`vh`. Calculate from `Dimensions.get('window')`.
+* **Typography**: All text styles must be on `Text` components, never on `View`.
+  - `font-size` maps to `fontSize` (number, not string).
+  - `font-weight` maps to `fontWeight` (string: `'400'`, `'700'`, `'bold'`).
+  - `line-height` maps to `lineHeight` (number).
+  - `letter-spacing` maps to `letterSpacing`.
+  - `text-transform` maps to `textTransform`.
+  - `color` applies to `Text` only.
+* **Borders and shadows**:
+  - `border-radius` maps to `borderRadius`.
+  - `box-shadow` does not exist. Use `elevation` (Android) and `shadowColor`/`shadowOffset`/`shadowOpacity`/`shadowRadius` (iOS). Use `Platform.select()` to apply platform-specific shadow styles.
+* **Unsupported CSS properties**: Do not use `hover`, `transition`, `animation` (use `react-native-reanimated` for animations), or `position: fixed` (use absolute positioning instead).
+
+### Architectural Rules
+* **Modular components (Atomic Design)**: Break the design into independent files. Organize components as atoms (buttons, labels, icons), molecules (input groups, cards), and organisms (headers, lists, forms). Place them in `src/components/atoms/`, `src/components/molecules/`, and `src/components/organisms/`. Monolithic page/screen files are PROHIBITED.
+* **Logic isolation**: Move event handlers, API calls, and business logic into custom hooks in `src/hooks/`. Components should only handle rendering.
+* **Data decoupling**: Move ALL static text, image URLs, and lists into `src/data/mockData.ts`. No hardcoded content in components.
+* **Type safety**: EVERY component file (including screens) MUST export a TypeScript interface named `[ComponentName]Props` with `readonly` property modifiers. The validator requires the interface to be **exported** — files without an exported Props interface will FAIL validation.
+* **No hardcoded styles**: Extract colors, spacing, and font sizes into `src/theme.ts`. Reference them in `StyleSheet.create()`. Absolutely no raw color hex codes or rgba strings are allowed in component files.
+* **Navigation**: Use React Navigation for screen transitions. Define screen types with `NativeStackScreenProps` or `BottomTabScreenProps`.
+* **Accessibility**: Every interactive element must have `accessibilityLabel` and `accessibilityRole`. Images need `accessibilityLabel`. Use `accessibilityState` for toggles and checkboxes.
+* **Safe areas**: Wrap top-level screen components with `SafeAreaView` from `react-native-safe-area-context` (not the default one from `react-native`).
+* **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated components.
 
 ### Platform-specific code
 When the design requires different behavior on iOS and Android:
-
 ```typescript
 import { Platform } from 'react-native';
 
@@ -101,33 +137,39 @@ const styles = StyleSheet.create({
 });
 ```
 
-## Architectural rules
+### Anti-patterns for Phase 3
+- ❌ Putting all UI in a single monolithic screen file.
+- ❌ Using HTML tags (like `div`, `span`, `p`) instead of React Native components.
+- ❌ Inline event handlers or business logic without custom hooks.
+- ❌ Hardcoding text, URLs, or colors in component files.
+- ❌ Components without an **exported** `[Name]Props` interface.
+- ❌ Using raw hex color values or rgba strings in `StyleSheet.create()`.
 
-* **Atomic Design**: Organize components as atoms (buttons, labels, icons), molecules (input groups, cards), and organisms (headers, lists, forms). Place them in `src/components/atoms/`, `src/components/molecules/`, `src/components/organisms/`.
-* **Logic isolation**: Move event handlers, API calls, and business logic into custom hooks in `src/hooks/`. Components should only handle rendering.
-* **Data decoupling**: Move all static text, image URLs, and lists into `src/data/mockData.ts`. Components receive data through props.
-* **Type safety**: Every component must export a TypeScript interface named `[ComponentName]Props` with `readonly` property modifiers.
-* **No hardcoded styles**: Extract colors, spacing, and font sizes into `src/theme.ts`. Reference them in `StyleSheet.create()`.
-* **Navigation**: Use React Navigation for screen transitions. Define screen types with `NativeStackScreenProps` or `BottomTabScreenProps`.
-* **Accessibility**: Every interactive element must have `accessibilityLabel` and `accessibilityRole`. Images need `accessibilityLabel`. Use `accessibilityState` for toggles and checkboxes.
-* **Safe areas**: Wrap top-level screen components with `SafeAreaView` from `react-native-safe-area-context` (not the one from `react-native`).
-* **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React Native components.
+## Phase 4: Execution steps
 
-## Execution steps
+> **GATE: Phase 4 is complete ONLY when ALL validation checks pass and components compile correctly.**
 
 1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
-2. **Theme layer**: Create `src/theme.ts` from the extracted Tailwind config. Define colors, spacing, typography, and shadow presets.
-3. **Data layer**: Create `src/data/mockData.ts` based on the design content. Extract all text, image URIs, and list data.
-4. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace all instances of `StitchComponent` with the actual component name. Map HTML elements to React Native primitives following the mapping table above.
+2. **Theme layer**: Create `src/theme.ts` from the extracted Tailwind config.
+3. **Data layer**: Create `src/data/mockData.ts` based on the design content.
+4. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace ALL instances of `StitchComponent` with the actual component name. Map HTML elements to React Native primitives.
 5. **Navigation wiring**: If the design has multiple screens, set up a `NavigationContainer` with a stack or tab navigator in `App.tsx`.
-6. **Quality check**:
-   * Run `npm run validate <file_path>` for each component.
-   * Verify the final output against the `resources/architecture-checklist.md`.
-   * Start Metro with `npx react-native start` or `npx expo start` to verify the live result on a simulator/device.
+6. **Quality check** — ALL of the following are MANDATORY:
+    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in components and screens. ALL must report `COMPONENT VALID.`
+    * Run `tsc --noEmit` to verify zero TypeScript errors.
+    * Verify the final output against `resources/architecture-checklist.md` — every checkbox must be satisfied.
+    * Start the packager (`npx react-native start` or `npx expo start`) to verify the app renders correctly on a simulator/device.
+    * Report the validation results to the user with a clear pass/fail summary.
+
+### Anti-patterns for Phase 4
+- ❌ Skipping `npm run validate` for any component.
+- ❌ Not running `tsc --noEmit`.
+- ❌ Not checking `resources/architecture-checklist.md`.
+- ❌ Declaring "done" without checking the components on a simulator or device.
 
 ## Troubleshooting
 * **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
-* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles.
+* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles. The most common failures are missing an **exported** `Props` interface or leaving raw hex colors in `StyleSheet.create()`.
 * **Text outside Text component**: React Native crashes if raw strings appear outside `<Text>`. Verify all text nodes are wrapped.
 * **Image sizing**: Unlike web `<img>`, React Native `Image` has no intrinsic size. Always specify `width` and `height` in styles or use `aspectRatio`.
 * **FlatList vs ScrollView**: If you see a "VirtualizedList inside ScrollView" warning, replace the outer `ScrollView` with a plain `View` or use `FlatList` `ListHeaderComponent`/`ListFooterComponent`.

From ec43edba6b33d579430188687f4e5ac8c43cffae Mon Sep 17 00:00:00 2001
From: jilinxia <jilinxia@google.com>
Date: Mon, 29 Jun 2026 13:57:24 -0700
Subject: [PATCH 2/5] docs(skills): make phase 4 dev server and simulator
 testing optional

- Update react-components and react-native skills to make Phase 4 audits optional
- Require explicit user permission before starting dev servers, packagers, or simulators
- Keep TypeScript compilation verification mandatory but adjust gate rules
---
 .../skills/react-components/SKILL.md          | 19 ++++++++-----------
 .../stitch-build/skills/react-native/SKILL.md | 19 ++++++++-----------
 2 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/plugins/stitch-build/skills/react-components/SKILL.md b/plugins/stitch-build/skills/react-components/SKILL.md
index 44985d6..95b6634 100644
--- a/plugins/stitch-build/skills/react-components/SKILL.md
+++ b/plugins/stitch-build/skills/react-components/SKILL.md
@@ -87,24 +87,21 @@ You are a frontend engineer focused on transforming designs into clean React cod
 
 ## Phase 4: Execution steps
 
-> **GATE: Phase 4 is complete ONLY when ALL validation checks pass and the dev server renders correctly.**
+> **GATE: Phase 4 verification, audits, and validation checks are optional. You MUST ask the user's permission to proceed with validation scripts, running local dev servers, or automated browser testing.**
 
 1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
 2. **Data layer**: Create `src/data/mockData.ts` based on the design content.
 3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace ALL instances of `StitchComponent` with the actual name of the component you are creating.
 4. **Application wiring**: Update the project entry point (like `App.tsx`) to render the new components.
-5. **Quality check** — ALL of the following are MANDATORY:
-    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in `src/components/` and `src/pages/`. ALL must report `✨ COMPONENT VALID.`
-    * Run `tsc --noEmit` to verify zero TypeScript errors.
-    * Verify the final output against `resources/architecture-checklist.md` — every checkbox must be satisfied.
-    * Start the dev server with `npm run dev` to verify the live result.
-    * Report the validation results to the user with a clear pass/fail summary.
+5. **Quality check (Optional - Ask User first)**:
+    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in `src/components/` and `src/pages/` to report component validity.
+    * Run `tsc --noEmit` to verify TypeScript compile status.
+    * Check output against `resources/architecture-checklist.md`.
+    * Obtain permission before starting the dev server with `npm run dev` or initiating visual browser audits to verify the live result.
 
 ### Anti-patterns for Phase 4
-- ❌ Skipping `npm run validate` for any component.
-- ❌ Not running `tsc --noEmit`.
-- ❌ Not checking `resources/architecture-checklist.md`.
-- ❌ Declaring "done" without starting the dev server.
+- ❌ Commencing dev server start or browser audits without user consent.
+- ❌ Declaring task "done" without verifying code compiles.
 
 ## Troubleshooting
 * **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
diff --git a/plugins/stitch-build/skills/react-native/SKILL.md b/plugins/stitch-build/skills/react-native/SKILL.md
index 14bb42a..2ffab43 100644
--- a/plugins/stitch-build/skills/react-native/SKILL.md
+++ b/plugins/stitch-build/skills/react-native/SKILL.md
@@ -147,25 +147,22 @@ const styles = StyleSheet.create({
 
 ## Phase 4: Execution steps
 
-> **GATE: Phase 4 is complete ONLY when ALL validation checks pass and components compile correctly.**
+> **GATE: Phase 4 verification, audits, and simulator/packager testing are optional. You MUST ask the user's permission to proceed with validation scripts, starting packagers, or simulator audits.**
 
 1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
 2. **Theme layer**: Create `src/theme.ts` from the extracted Tailwind config.
 3. **Data layer**: Create `src/data/mockData.ts` based on the design content.
 4. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace ALL instances of `StitchComponent` with the actual component name. Map HTML elements to React Native primitives.
 5. **Navigation wiring**: If the design has multiple screens, set up a `NavigationContainer` with a stack or tab navigator in `App.tsx`.
-6. **Quality check** — ALL of the following are MANDATORY:
-    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in components and screens. ALL must report `COMPONENT VALID.`
-    * Run `tsc --noEmit` to verify zero TypeScript errors.
-    * Verify the final output against `resources/architecture-checklist.md` — every checkbox must be satisfied.
-    * Start the packager (`npx react-native start` or `npx expo start`) to verify the app renders correctly on a simulator/device.
-    * Report the validation results to the user with a clear pass/fail summary.
+6. **Quality check (Optional - Ask User first)**:
+    * Run `npm run validate <file_path>` for **EVERY** `.tsx` file in components and screens to report component validity.
+    * Run `tsc --noEmit` to verify TypeScript compile status.
+    * Check output against `resources/architecture-checklist.md`.
+    * Obtain permission before starting the packager (`npx react-native start` or `npx expo start`) or starting visual simulator audits to verify the app renders correctly on a simulator/device.
 
 ### Anti-patterns for Phase 4
-- ❌ Skipping `npm run validate` for any component.
-- ❌ Not running `tsc --noEmit`.
-- ❌ Not checking `resources/architecture-checklist.md`.
-- ❌ Declaring "done" without checking the components on a simulator or device.
+- ❌ Launching packagers or simulators without user consent.
+- ❌ Declaring task "done" without verifying code compiles.
 
 ## Troubleshooting
 * **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.

From 6bd44392992cd65554c462f5e04dec9009291566 Mon Sep 17 00:00:00 2001
From: jilinxia <jilinxia@google.com>
Date: Mon, 29 Jun 2026 14:06:48 -0700
Subject: [PATCH 3/5] docs(readme): move stitch::react-native above remotion in
 skills table

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 86a404e..df04375 100644
--- a/README.md
+++ b/README.md
@@ -105,8 +105,8 @@ Code generation, framework integration, and asset compilation from Stitch design
 | Skill | Description | Prompt Example |
 |---|---|---|
 | [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | *"Convert all screens in Stitch project `projects/123` to React components."* |
+| [stitch::react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | *"Convert the Stitch design to React Native components with proper theme and navigation."* |
 | [remotion](plugins/stitch-build/skills/remotion/) | Generate walkthrough videos from Stitch projects using Remotion with smooth transitions and zooming | *"Generate a walkthrough video of the Stitch project `projects/456`."* |
-| [react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | *"Convert the Stitch design to React Native components with proper theme and navigation."* |
 | [shadcn-ui](plugins/stitch-build/skills/shadcn-ui/) | Expert guidance for integrating and building applications with shadcn/ui components | *"Set up shadcn/ui and build a data table with sorting and filtering."* |
 
 ---

From e5cdbf6859a547cfc503b36e3d09d0d8d7d881a2 Mon Sep 17 00:00:00 2001
From: jilinxia <jilinxia@google.com>
Date: Mon, 29 Jun 2026 14:08:11 -0700
Subject: [PATCH 4/5] docs(readme): add sync example to
 stitch::react-components

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index df04375..f88467a 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,7 @@ Code generation, framework integration, and asset compilation from Stitch design
 
 | Skill | Description | Prompt Example |
 |---|---|---|
-| [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | *"Convert all screens in Stitch project `projects/123` to React components."* |
+| [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | · *"Convert all screens in Stitch project `projects/123` to React components."*<br>· *"Sync the app to the last updates of the Stitch project `13039335308618232534`."* |
 | [stitch::react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | *"Convert the Stitch design to React Native components with proper theme and navigation."* |
 | [remotion](plugins/stitch-build/skills/remotion/) | Generate walkthrough videos from Stitch projects using Remotion with smooth transitions and zooming | *"Generate a walkthrough video of the Stitch project `projects/456`."* |
 | [shadcn-ui](plugins/stitch-build/skills/shadcn-ui/) | Expert guidance for integrating and building applications with shadcn/ui components | *"Set up shadcn/ui and build a data table with sorting and filtering."* |

From ba6907b99ab3a5116cd0b0112cef2691ef612bf0 Mon Sep 17 00:00:00 2001
From: jilinxia <jilinxia@google.com>
Date: Mon, 29 Jun 2026 14:08:29 -0700
Subject: [PATCH 5/5] docs(readme): add sync example to stitch::react-native

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f88467a..94e15a3 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ Code generation, framework integration, and asset compilation from Stitch design
 | Skill | Description | Prompt Example |
 |---|---|---|
 | [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | · *"Convert all screens in Stitch project `projects/123` to React components."*<br>· *"Sync the app to the last updates of the Stitch project `13039335308618232534`."* |
-| [stitch::react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | *"Convert the Stitch design to React Native components with proper theme and navigation."* |
+| [stitch::react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | · *"Convert the Stitch design to React Native components with proper theme and navigation."*<br>· *"Sync the app to the last updates of the Stitch project `13039335308618232534`."* |
 | [remotion](plugins/stitch-build/skills/remotion/) | Generate walkthrough videos from Stitch projects using Remotion with smooth transitions and zooming | *"Generate a walkthrough video of the Stitch project `projects/456`."* |
 | [shadcn-ui](plugins/stitch-build/skills/shadcn-ui/) | Expert guidance for integrating and building applications with shadcn/ui components | *"Set up shadcn/ui and build a data table with sorting and filtering."* |