devskill 2.0.2

package/skills/react-native-skills/README.md

@@ -0,0 +1,165 @@
+# React Native Guidelines
+
+A structured repository for creating and maintaining React Native Best Practices
+optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component.md` - Wrap strings in Text components
+- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
+
+### List Performance (HIGH)
+
+- `list-performance-virtualize.md` - Use virtualized lists (LegendList,
+  FlashList)
+- `list-performance-function-references.md` - Keep stable object references
+- `list-performance-callbacks.md` - Hoist callbacks to list root
+- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
+- `list-performance-item-memo.md` - Pass primitives for memoization
+- `list-performance-item-expensive.md` - Keep list items lightweight
+- `list-performance-images.md` - Use compressed images in lists
+- `list-performance-item-types.md` - Use item types for heterogeneous lists
+
+### Animation (HIGH)
+
+- `animation-gpu-properties.md` - Animate transform/opacity instead of layout
+- `animation-gesture-detector-press.md` - Use GestureDetector for press
+  animations
+- `animation-derived-value.md` - Prefer useDerivedValue over useAnimatedReaction
+
+### Scroll Performance (HIGH)
+
+- `scroll-position-no-state.md` - Never track scroll in useState
+
+### Navigation (HIGH)
+
+- `navigation-native-navigators.md` - Use native stack and native tabs
+
+### React State (MEDIUM)
+
+- `react-state-dispatcher.md` - Use functional setState updates
+- `react-state-fallback.md` - State should represent user intent only
+- `react-state-minimize.md` - Minimize state variables, derive values
+
+### State Architecture (MEDIUM)
+
+- `state-ground-truth.md` - State must represent ground truth
+
+### React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions.md` - Destructure functions early
+- `react-compiler-reanimated-shared-values.md` - Use .get()/.set() for shared
+  values
+
+### User Interface (MEDIUM)
+
+- `ui-expo-image.md` - Use expo-image for optimized images
+- `ui-image-gallery.md` - Use Galeria for lightbox/galleries
+- `ui-menus.md` - Native dropdown and context menus with Zeego
+- `ui-native-modals.md` - Use native Modal with formSheet
+- `ui-pressable.md` - Use Pressable instead of TouchableOpacity
+- `ui-measure-views.md` - Measuring view dimensions
+- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset.md` - Use contentInset for dynamic spacing
+- `ui-styling.md` - Modern styling patterns (gap, boxShadow, gradients)
+
+### Design System (MEDIUM)
+
+- `design-system-compound-components.md` - Use compound components
+
+### Monorepo (LOW)
+
+- `monorepo-native-deps-in-app.md` - Install native deps in app directory
+- `monorepo-single-dependency-versions.md` - Single dependency versions
+
+### Third-Party Dependencies (LOW)
+
+- `imports-design-system-folder.md` - Import from design system folder
+
+### JavaScript (LOW)
+
+- `js-hoist-intl.md` - Hoist Intl formatter creation
+
+### Fonts (LOW)
+
+- `fonts-config-plugin.md` - Load fonts natively at build time
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `rendering-` for Core Rendering
+   - `list-performance-` for List Performance
+   - `animation-` for Animation
+   - `scroll-` for Scroll Performance
+   - `navigation-` for Navigation
+   - `react-state-` for React State
+   - `state-` for State Architecture
+   - `react-compiler-` for React Compiler
+   - `ui-` for User Interface
+   - `design-system-` for Design System
+   - `monorepo-` for Monorepo
+   - `imports-` for Third-Party Dependencies
+   - `js-` for JavaScript
+   - `fonts-` for Fonts
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+````markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```tsx
+// Bad code example
+```
+````
+
+**Correct (description of what's right):**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
+
+```
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, causes crashes or broken UI
+- `HIGH` - Significant performance improvements
+- `MEDIUM` - Moderate performance improvements
+- `LOW` - Incremental improvements
+```

package/skills/react-native-skills/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: vercel-react-native-skills
+description:
+  React Native and Expo best practices for building performant mobile apps. Use
+  when building React Native components, optimizing list performance,
+  implementing animations, or working with native modules. Triggers on tasks
+  involving React Native, Expo, mobile performance, or native platform APIs.
+license: MIT
+metadata:
+  author: vercel
+  version: '1.0.0'
+---
+
+# React Native Skills
+
+Comprehensive best practices for React Native and Expo applications. Contains
+rules across multiple categories covering performance, animations, UI patterns,
+and platform-specific optimizations.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building React Native or Expo apps
+- Optimizing list and scroll performance
+- Implementing animations with Reanimated
+- Working with images and media
+- Configuring native modules or fonts
+- Structuring monorepo projects with native dependencies
+
+## Rule Categories by Priority
+
+| Priority | Category         | Impact   | Prefix               |
+| -------- | ---------------- | -------- | -------------------- |
+| 1        | List Performance | CRITICAL | `list-performance-`  |
+| 2        | Animation        | HIGH     | `animation-`         |
+| 3        | Navigation       | HIGH     | `navigation-`        |
+| 4        | UI Patterns      | HIGH     | `ui-`                |
+| 5        | State Management | MEDIUM   | `react-state-`       |
+| 6        | Rendering        | MEDIUM   | `rendering-`         |
+| 7        | Monorepo         | MEDIUM   | `monorepo-`          |
+| 8        | Configuration    | LOW      | `fonts-`, `imports-` |
+
+## Quick Reference
+
+### 1. List Performance (CRITICAL)
+
+- `list-performance-virtualize` - Use FlashList for large lists
+- `list-performance-item-memo` - Memoize list item components
+- `list-performance-callbacks` - Stabilize callback references
+- `list-performance-inline-objects` - Avoid inline style objects
+- `list-performance-function-references` - Extract functions outside render
+- `list-performance-images` - Optimize images in lists
+- `list-performance-item-expensive` - Move expensive work outside items
+- `list-performance-item-types` - Use item types for heterogeneous lists
+
+### 2. Animation (HIGH)
+
+- `animation-gpu-properties` - Animate only transform and opacity
+- `animation-derived-value` - Use useDerivedValue for computed animations
+- `animation-gesture-detector-press` - Use Gesture.Tap instead of Pressable
+
+### 3. Navigation (HIGH)
+
+- `navigation-native-navigators` - Use native stack and native tabs over JS navigators
+
+### 4. UI Patterns (HIGH)
+
+- `ui-expo-image` - Use expo-image for all images
+- `ui-image-gallery` - Use Galeria for image lightboxes
+- `ui-pressable` - Use Pressable over TouchableOpacity
+- `ui-safe-area-scroll` - Handle safe areas in ScrollViews
+- `ui-scrollview-content-inset` - Use contentInset for headers
+- `ui-menus` - Use native context menus
+- `ui-native-modals` - Use native modals when possible
+- `ui-measure-views` - Use onLayout, not measure()
+- `ui-styling` - Use StyleSheet.create or Nativewind
+
+### 5. State Management (MEDIUM)
+
+- `react-state-minimize` - Minimize state subscriptions
+- `react-state-dispatcher` - Use dispatcher pattern for callbacks
+- `react-state-fallback` - Show fallback on first render
+- `react-compiler-destructure-functions` - Destructure for React Compiler
+- `react-compiler-reanimated-shared-values` - Handle shared values with compiler
+
+### 6. Rendering (MEDIUM)
+
+- `rendering-text-in-text-component` - Wrap text in Text components
+- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering
+
+### 7. Monorepo (MEDIUM)
+
+- `monorepo-native-deps-in-app` - Keep native dependencies in app package
+- `monorepo-single-dependency-versions` - Use single versions across packages
+
+### 8. Configuration (LOW)
+
+- `fonts-config-plugin` - Use config plugins for custom fonts
+- `imports-design-system-folder` - Organize design system imports
+- `js-hoist-intl` - Hoist Intl object creation
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/list-performance-virtualize.md
+rules/animation-gpu-properties.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

package/skills/react-native-skills/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/web-design-guidelines/skills/react-native-skills`
+- **Git SHA:** `9aec8ee6aaf702e49312a071e672f1c1b7b7e948`
+- **Synced:** 2026-03-24

package/skills/react-native-skills/metadata.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "organization": "Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://reactnative.dev",
+    "https://docs.swmansion.com/react-native-reanimated",
+    "https://docs.swmansion.com/react-native-gesture-handler",
+    "https://docs.expo.dev",
+    "https://legendapp.com/open-source/legend-list",
+    "https://github.com/nandorojo/galeria",
+    "https://zeego.dev"
+  ]
+}

package/skills/react-native-skills/rules/_sections.md

@@ -0,0 +1,86 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL  
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH  
+**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH  
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH  
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH  
+**Description:** Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM  
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM  
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM  
+**Description:** Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+## 10. Design System (design-system)
+
+**Impact:** MEDIUM  
+**Description:** Architecture patterns for building maintainable component
+libraries.
+
+## 11. Monorepo (monorepo)
+
+**Impact:** LOW  
+**Description:** Dependency management and native module configuration in
+monorepos.
+
+## 12. Third-Party Dependencies (imports)
+
+**Impact:** LOW  
+**Description:** Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+## 13. JavaScript (js)
+
+**Impact:** LOW  
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 14. Fonts (fonts)
+
+**Impact:** LOW  
+**Description:** Native font loading for improved performance.

package/skills/react-native-skills/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/skills/react-native-skills/rules/animation-derived-value.md

@@ -0,0 +1,53 @@
+---
+title: Prefer useDerivedValue Over useAnimatedReaction
+impact: MEDIUM
+impactDescription: cleaner code, automatic dependency tracking
+tags: animation, reanimated, derived-value
+---
+
+## Prefer useDerivedValue Over useAnimatedReaction
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+`useAnimatedReaction`. Derived values are declarative, automatically track
+dependencies, and return a value you can use directly. Animated reactions are
+for side effects, not derivations.
+
+**Incorrect (useAnimatedReaction for derivation):**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct (useDerivedValue):**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+Reference:
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)

package/skills/react-native-skills/rules/animation-gesture-detector-press.md

@@ -0,0 +1,95 @@
+---
+title: Use GestureDetector for Animated Press States
+impact: MEDIUM
+impactDescription: UI thread animations, smoother press feedback
+tags: animation, gestures, press, reanimated
+---
+
+## Use GestureDetector for Animated Press States
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+`Gesture.Tap()` and shared values instead of Pressable's
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+JS thread round-trip for press animations.
+
+**Incorrect (Pressable with JS thread callbacks):**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct (GestureDetector with UI thread worklets):**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+Reference:
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)

package/skills/react-native-skills/rules/animation-gpu-properties.md

@@ -0,0 +1,65 @@
+---
+title: Animate Transform and Opacity Instead of Layout Properties
+impact: HIGH
+impactDescription: GPU-accelerated animations, no layout recalculation
+tags: animation, performance, reanimated, transform, opacity
+---
+
+## Animate Transform and Opacity Instead of Layout Properties
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect (animates height, triggers layout every frame):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+    overflow: 'hidden',
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+**Correct (animates scaleY, GPU-accelerated):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scaleY: withTiming(expanded ? 1 : 0) },
+    ],
+    opacity: withTiming(expanded ? 1 : 0),
+  }))
+
+  return (
+    <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>
+      {children}
+    </Animated.View>
+  )
+}
+```
+
+**Correct (animates translateY for slide animations):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: withTiming(visible ? 0 : 100) },
+    ],
+    opacity: withTiming(visible ? 1 : 0),
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.