@mallardbay/cursor-rules 1.0.28 → 1.0.30

package/.cursor/frontend-mobile/rules/ui.mdc

@@ -0,0 +1,124 @@
+---
+description: Defines best practices for building consistent, maintainable, and library-agnostic UI in Mallard Bay React Native projects
+globs:
+alwaysApply: true
+---
+
+# UI Development Standards (React Native)
+
+## Component Abstraction Layer
+
+The mobile app uses NativeBase under the hood, but **all UI primitives must be accessed through custom wrapper components**. This abstraction enables switching to a different component library (e.g., Gluestack, Tamagui) with minimal churn.
+
+### Import Rules
+
+- **Never import directly from `native-base`** in feature code — always use the project's custom wrapper components
+- **Never import from `~components/shared/ui`** — use the abstraction layer instead
+- Wrapper components live in a dedicated directory (e.g., `src/components/primitives/` or the project's established equivalent)
+- Only the wrapper component files themselves may import from `native-base`
+
+### Wrapper Component Guidelines
+
+- Each wrapper should expose a **stable, minimal API** — only pass through props the project actually uses
+- Use TypeScript interfaces for wrapper props rather than re-exporting the library's prop types
+- Keep wrappers thin — they should delegate to the underlying library, not add business logic
+- Name wrappers after their semantic purpose (e.g., `AppText`, `AppButton`, `AppBox`) or match the library's naming if there's no ambiguity
+- Document any NativeBase-specific behavior the wrapper intentionally hides or transforms
+
+### Example Pattern
+
+```tsx
+// src/components/primitives/AppButton.tsx — ✅ Correct
+import { Button as NativeBaseButton } from "native-base"
+
+export default function AppButton(props: AppButtonProps) {
+    return <NativeBaseButton {...props} />
+}
+
+// src/features/booking/BookingCard.tsx — ✅ Correct
+import AppButton from "~components/primitives/AppButton"
+
+// src/features/booking/BookingCard.tsx — ❌ Wrong
+import { Button } from "native-base"
+import { Button } from "~components/shared/ui"
+```
+
+## Theme Usage
+
+Use theme values consistently across all components:
+
+### Colors
+
+- Use theme colors instead of hardcoded values
+- Example: `theme.colors.primary[500]` instead of `'#3B82F6'`
+
+### Spacing
+
+- Use theme spacing values for margins and padding
+- Example: `theme.space[4]` instead of numeric literals
+
+### Typography
+
+- Use theme typography settings for text styles
+- Example: `theme.fontSizes.md` instead of hardcoded numbers
+
+## Component Structure
+
+Maintain clean and consistent component structure:
+
+### Nesting
+
+- Limit component nesting to maximum depth of 3
+- Keep component hierarchy readable and maintainable
+
+### Inline Styles
+
+- Limit inline styles to maximum of 2 per component
+- Prefer theme-based styling and style props
+
+### Component Library
+
+- Use the project's custom wrapper components (abstraction layer) for all UI primitives
+- If a wrapper doesn't exist yet for a NativeBase component you need, create one in the primitives directory following the established pattern
+- Keep wrapper components minimal and focused on API stability
+
+## Platform Considerations
+
+### React Native Specifics
+
+- Use `StyleSheet.create` or NativeBase style props — avoid inline object styles
+- Prefer `FlatList` / `SectionList` over mapping arrays for long lists
+- Use platform-specific extensions (`.ios.tsx`, `.android.tsx`) only when behavior genuinely diverges
+- Test on both iOS and Android
+
+### Navigation
+
+- Follow the project's established navigation patterns (React Navigation or equivalent)
+- Keep screen components thin — delegate to feature components
+
+### Performance
+
+- Use `React.memo` for pure list item components
+- Use `useCallback` for handlers passed to list items
+- Use `useMemo` for expensive computations and filtered/sorted data
+- Avoid anonymous functions in `renderItem` and event handlers
+- Minimize bridge crossings by batching state updates
+
+## Rendering Optimization
+
+- Optimize component rendering
+- Avoid unnecessary re-renders
+- Move function definitions outside components or use `useCallback` for event handlers
+- Use `useCallback` for functions passed as props to child components
+- Use `useMemo` for expensive computations and complex data transformations
+- Memoize filtered, sorted, or mapped arrays to avoid recalculation on every render
+
+## File Patterns
+
+These rules apply to all TypeScript and TSX files in the project.
+
+## Components
+
+- Keep components small and focused on a single responsibility
+- Use functional components with hooks instead of class components
+- Prefer `export default function BookingCard() {` over `function BookingCard(): React.ReactElement | null {` when defining components

package/.cursor/shared/rules/code-quality.mdc

@@ -14,7 +14,13 @@ alwaysApply: false
     -   Functions: camelCase
     -   Constants: UPPER_SNAKE_CASE
     -   Types: PascalCase
--   Types should be defined at the bottom of files
+-   Follow this ordering within files:
+    1.  Imports
+    2.  Constants
+    3.  Exported functions / components
+    4.  Helpers and other non-exported definitions
+    5.  Types (when not imported)
+-   Exported members always come before non-exported members
 -   PropTypes should be defined before component definitions
 -   Prefer using alias for importing components. Only use relative for tests or when there's a direct sibling
 

package/.cursor/shared/rules/testing.mdc

@@ -56,13 +56,14 @@ We do not chase 100% coverage for its own sake. If a test doesn’t meaningfully
 
 ### Mocking Guidelines
 
--   Use mock helpers instead of inline mocks
--   Follow existing patterns for:
+-   **Always use mock helpers**—never define mocks inline. All mocks should come from dedicated mock helper files following existing patterns for:
     -   Entity mocks
     -   Apollo mocks
     -   Provider mocks
+-   **Mock data through Apollo mocks, not module mocks**—use Apollo mock providers to control query/mutation responses instead of mocking modules or components directly
 -   Keep mocks simple and maintainable
 -   **Do not use variable matchers for Apollo mocks**—match exact variables (e.g. avoid `expect.anything()` or `variables: {}`) so tests fail when the component passes incorrect variables to queries or mutations
+-   **Never mock `@mallardbay/lib-react-components`**—if truly unavoidable, stop and ask for approval first
 
 ### Test Utilities
 

package/.cursor/shared/rules/typescript.mdc

@@ -14,7 +14,13 @@ Be as strictly as possible where it delivers clear value—specifically in preve
 
 ### File Organization
 
--   Place types at the bottom of files
+-   Follow this ordering within files:
+    1.  Imports
+    2.  Constants
+    3.  Exported functions / components
+    4.  Helpers and other non-exported definitions
+    5.  Types (when not imported)
+-   Exported members always come before non-exported members
 -   Define PropTypes before component definitions
 
 ## Best Practices

package/bin/setup-cursor.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# setup-cursor.sh — frontend & frontend-lib layering with shared base
+# setup-cursor.sh — frontend, frontend-lib, frontend-mobile & backend layering with shared base
 # Also generates CLAUDE.md for Claude Code and AGENTS.md for Codex
 
 set -e
@@ -65,6 +65,7 @@ fi
 SHARED_DIR="$SRC_DIR/.cursor/shared/rules"
 FRONTEND_DIR="$SRC_DIR/.cursor/frontend/rules"
 FRONTEND_LIB_DIR="$SRC_DIR/.cursor/frontend-lib/rules"
+FRONTEND_MOBILE_DIR="$SRC_DIR/.cursor/frontend-mobile/rules"
 BACKEND_DIR="$SRC_DIR/.cursor/backend/rules"
 SHARED_SKILLS_DIR="$SRC_DIR/.cursor/shared/skills"
 
@@ -215,6 +216,10 @@ case "$ENV_TYPE" in
     append_to_md_files "$FRONTEND_DIR"
     append_to_md_files "$FRONTEND_LIB_DIR"
     ;;
+  frontend-mobile)
+    copy_rules "$FRONTEND_MOBILE_DIR"
+    append_to_md_files "$FRONTEND_MOBILE_DIR"
+    ;;
   *)
     echo "Unknown environment type: $ENV_TYPE"
     exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.28",
+    "version": "1.0.30",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
     "repository": "git@github.com:mallardbay/cursor-rules.git",