@mallardbay/cursor-rules 1.0.0

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

@@ -0,0 +1,63 @@
+---
+description: Defines best practices for building consistent, maintainable, and responsive UI in Mallard Bay projects
+globs:
+alwaysApply: false
+---
+# UI Development Standards
+
+## Theme Usage
+Use theme values consistently across all components:
+
+### Colors
+- Use theme colors instead of hardcoded values
+- Example: `theme.colors.primary` instead of `'#000000'`
+
+### Spacing
+- Use theme spacing values for margins and padding
+- Example: `theme.space[4]` instead of `'16px'`
+
+### Typography
+- Use theme typography settings for text styles
+- Example: `theme.fontSizes.md` instead of `'16px'`
+
+### Borders
+- Use theme border styles and radius values
+- Example: `theme.borders.sm` instead of `'1px solid'`
+
+## 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
+
+### Component Library
+- Use existing components in @mallardbay/lib-react-components, @mallardbay/lib-react-components is based off Crakra UI v2
+- If no component available in @mallardbay/lib-react-components, create one using Crakra UI and place it under src/components/shared/todo-lib-react-components/ to me moved later
+
+## Responsive Design
+Ensure responsive and accessible design:
+
+### Breakpoints
+- Use theme breakpoints for responsive design
+- Implement mobile-first approach
+
+### Spacing
+- Use responsive spacing values
+- Adapt layouts for different screen sizes
+
+### Animations
+- Use theme transition values for animations
+- Keep animations smooth and performant
+
+### Rendering
+- Optimize component rendering
+- Avoid unnecessary re-renders
+- Use React.memo and useMemo when appropriate
+
+## File Patterns
+These rules apply to all TypeScript and TSX files in the project.

package/.cursor/lib/rules/ui.mdc

@@ -0,0 +1,63 @@
+---
+description: Defines best practices for building consistent, maintainable, and responsive UI in Mallard Bay projects
+globs:
+alwaysApply: false
+---
+# UI Development Standards
+
+## Theme Usage
+Use theme values consistently across all components:
+
+### Colors
+- Use theme colors instead of hardcoded values
+- Example: `theme.colors.primary` instead of `'#000000'`
+
+### Spacing
+- Use theme spacing values for margins and padding
+- Example: `theme.space[4]` instead of `'16px'`
+
+### Typography
+- Use theme typography settings for text styles
+- Example: `theme.fontSizes.md` instead of `'16px'`
+
+### Borders
+- Use theme border styles and radius values
+- Example: `theme.borders.sm` instead of `'1px solid'`
+
+## 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
+
+### Component Library
+- Use existing components in @mallardbay/lib-react-components, @mallardbay/lib-react-components is based off Crakra UI v2
+- If no component available in @mallardbay/lib-react-components, create one using Crakra UI and place it under src/components/shared/todo-lib-react-components/ to me moved later
+
+## Responsive Design
+Ensure responsive and accessible design:
+
+### Breakpoints
+- Use theme breakpoints for responsive design
+- Implement mobile-first approach
+
+### Spacing
+- Use responsive spacing values
+- Adapt layouts for different screen sizes
+
+### Animations
+- Use theme transition values for animations
+- Keep animations smooth and performant
+
+### Rendering
+- Optimize component rendering
+- Avoid unnecessary re-renders
+- Use React.memo and useMemo when appropriate
+
+## File Patterns
+These rules apply to all TypeScript and TSX files in the project.

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

@@ -0,0 +1,48 @@
+---
+description: Defines structure, naming, reuse, and dependency guidelines to ensure clean, maintainable, and consistent TypeScript code across the project—favoring pragmatism, proven libraries, and shared conventions.
+globs:
+alwaysApply: false
+---
+# Code Quality Standards
+
+## Code Structure
+- Maximum file length: 200 lines
+- Maximum function length: 50 lines
+- Naming conventions:
+  - Components: PascalCase
+  - Functions: camelCase
+  - Constants: UPPER_SNAKE_CASE
+  - Types: PascalCase
+- Types should be defined at the bottom of files
+- 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
+
+## Code Reuse
+- Use shared libraries to avoid duplication
+- Primary libraries to use:
+  - [@mallardbay/lib-react-components](mdc:package.json)
+  - [@mallardbay/lib-shared-helpers](mdc:package.json)
+
+## Third party libraries
+- Favor battle-tested libraries over custom solutions. If a well-maintained, widely-used library solves the problem cleanly, use it. Reinventing functionality that’s already solid, reliable, and well-documented usually leads to more bugs, more maintenance, and wasted time.
+- Prioritize stability and ecosystem fit. Pick libraries that are actively maintained, have strong adoption, and fit well within our existing tech stack. Avoid fringe or unmaintained packages unless there’s a strong reason.
+- Suggest existing libraries during code review. If you spot hand-rolled code that could be replaced with a proven library, flag it. Examples:
+- Use zod or yup instead of custom input validation
+- Use date-fns instead of writing date math from scratch
+- Use radash for utility-heavy logic if readability or testability improves
+- Use react-hook-form for complex form state handling
+- Be pragmatic. Sometimes a simple custom solution is faster and easier than pulling in a heavy dependency—but always weigh short-term gains against long-term cost.
+- Make reuse easy. If we do build something custom, design it to be clean, reusable, and well-documented. That way, we’re not creating another wheel, but investing in something worth maintaining.
+
+## String Constants
+- Use constants instead of string literals for:
+  - Copy text (UI content)
+  - Test IDs
+  - Error messages
+  - URLs
+- Source constants from:
+  - @mallardbay/lib-shared-helpers
+  - Local constants files
+
+## Cursor Rules
+- Suggest cursor rules as needed

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

@@ -0,0 +1,40 @@
+---
+description: Outlines expectations for pull request size, test coverage, documentation, and review process—promoting focused, well-tested, and maintainable contributions that align with team standards and improve review efficiency.
+globs:
+alwaysApply: false
+---
+# Code Review Standards
+
+## Pull Request Guidelines
+
+### Size Requirements
+- Maximum PR size: 400 lines
+- Split large changes into smaller, focused PRs
+- Keep changes atomic and focused
+- Consider impact on review process
+
+## Testing Requirements
+Ensure comprehensive test coverage:
+
+### Test Coverage
+- All new code must include tests
+- Follow testing standards in [testing.mdc](mdc:.cursor/rules/testing.mdc)
+- Include unit tests for new functionality
+- Avoid making a ton of changes to existing tests while refactoring
+
+### Code Documentation
+- Document complex logic with comments
+- Explain non-obvious implementation details
+- Document features added and important caveats in README
+
+### Review Process
+- Review for code quality
+- Check for test coverage
+- Verify documentation
+- Ensure adherence to project standards
+
+## Best Practices
+- Keep PRs focused and manageable
+- Include clear PR descriptions
+- Reference related issues/tickets
+- Respond to review comments promptly

package/.cursor/shared/rules/error-handling.mdc

@@ -0,0 +1,41 @@
+---
+description: Defines consistent patterns for API and form error handling—focusing on clear user feedback, robust validation, and reliable logging to improve user experience, developer debugging, and overall app resilience.
+globs:
+alwaysApply: false
+---
+# Error Handling Standards
+
+## API Error Handling
+Implement comprehensive API error handling
+
+### Error Types
+- Handle network errors
+- Handle server errors
+- Handle validation errors
+- Handle Apollo-specific errors
+
+### Error Presentation
+- Show error toasts for user feedback
+- Use original error messages when appropriate
+- Provide clear, actionable error messages
+- Log errors for debugging
+
+## Form Validation
+Implement robust form validation
+- Validate all user inputs
+- Show validation errors clearly
+- Handle form submission errors
+- Use [@hookform/resolvers](mdc:package.json) for validation
+
+### Error Display
+- Show validation errors inline
+- Provide clear error messages
+- Highlight invalid fields
+- Prevent form submission with invalid data
+
+## Best Practices
+- Use try-catch blocks appropriately
+- Implement proper error boundaries
+- Log errors for debugging
+- Provide user-friendly error messages
+- Handle edge cases gracefully

package/.cursor/shared/rules/mallardbay.mdc

@@ -0,0 +1,22 @@
+---
+description: Describes Mallard Bay’s mission to simplify and scale outfitter operations through purpose-built software—emphasizing real-world impact, outfitter collaboration, and a long-term vision to digitize and unify the outdoor experience industry.
+globs:
+alwaysApply: false
+---
+# Mallard Bay: Outfitter Management System Overview
+
+Mallard Bay is a specialized platform designed to streamline operations for outfitters—businesses that offer guided outdoor experiences such as hunting, fishing, and eco-tourism. At its core, Mallard Bay operates as an outfitter management system, purpose-built to reduce administrative burden, improve customer experience, and unlock new revenue channels for guides and lodge operators.
+
+# Built for Outfitters, with Outfitters in Mind
+
+At Mallard Bay, we’re not just building software — we’re solving real problems for real people in the outfitting industry. Every feature we ship is grounded in one simple principle: if it doesn’t make an outfitter’s life easier or their business better, it doesn’t belong in our product.
+
+We work closely with outfitters of all sizes to understand their workflows, pain points, and growth challenges. From there, we prioritize meaningful features that drive efficiency, boost bookings, and enhance the guest experience.
+
+Whether it’s reducing no-shows with smart reminders, saving time through automated group booking tools, or enabling instant rebooking with dynamic availability, we’re laser-focused on delivering value — not fluff.
+
+We’re building tools that fit into the way outfitters actually work — not the way a generic booking platform thinks they should.
+
+# Vision
+
+Mallard Bay aims to be the digital backbone for the outfitting industry—a single source of truth for trip logistics, customer interaction, and business growth. The long-term goal is to transform an analog, fragmented market into a digital-first, scalable ecosystem.

package/.cursor/shared/rules/performance.mdc

@@ -0,0 +1,38 @@
+---
+description: Defines best practices for optimizing React components, rendering efficiency, and dependency management—focusing on minimizing re-renders, reducing bundle size, and enabling smooth user experiences through memoization, lazy loading, and performance-aware development.
+globs:
+alwaysApply: false
+---
+# Performance Standards
+
+## React Optimization
+Optimize React components for better performance:
+
+### Component Optimization
+- Use `React.memo` for pure components
+- Implement `useCallback` for function props
+- Use `useMemo` for expensive computations
+- Avoid inline function definitions in render
+
+## Rendering Optimization
+Prevent unnecessary re-renders:
+- Avoid inline styles in components
+- Prevent inline object creation in render
+- Use proper key props in lists
+- Memoize complex objects and callbacks
+
+### Dependencies
+- Prefer existing dependencies over new ones
+- Review [package.json](mdc:package.json) before adding new packages
+- Consider bundle size impact of new dependencies
+- Use tree-shaking friendly imports
+
+## Best Practices
+- Implement proper code splitting
+- Use lazy loading for routes and large components
+- Optimize images and assets
+- Monitor performance metrics
+- Use React DevTools for performance profiling
+
+## File Patterns
+These rules apply to all TypeScript and TSX files in the project.

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

@@ -0,0 +1,61 @@
+---
+description: Outlines practical, value-driven testing guidelines focused on reliability, developer confidence, and speed. Emphasizes high-impact coverage (not overkill), structured test organization, clear scenarios, and reusable mock/test utilities—enabling fast iteration without sacrificing quality.
+globs:
+alwaysApply: false
+---
+# Testing Standards
+
+## Test Coverage and Structure
+We aim for high-impact test coverage, focused on adding value and improving developer confidence and experience. The priority is to cover critical logic, edge cases, and integration points where bugs would hurt the most. Tests should act as a safety net and enable fast, fearless iteration—not as a box-ticking exercise.
+
+We do not chase 100% coverage for its own sake. If a test doesn’t meaningfully reduce risk or help developers move faster, it’s not worth writing. The goal is smart coverage, not maximum coverage—optimize for reliability, clarity, and development speed without overengineering.
+
+Avoid e2e tests for UI. Favor unit tests.
+
+### Coverage Requirements
+- Minimum test coverage: 80%
+- Place tests in `_tests_` directory closest to the file being tested
+- Use `.spec.ts` or `.spec.tsx` file extensions
+- Do NOT Use `.test.ts` or `.test.tsx` file extensions
+
+
+### Test Organization
+- Maximum nesting level: 2
+- Use `test` or `it` for test cases
+- Keep tests focused and atomic
+- Follow AAA pattern (Arrange, Act, Assert)
+
+### Required Scenarios
+- Happy path testing
+- Error case handling
+- Edge case coverage
+- All tests must pass before completion
+
+### Test Quality
+- Write clear, descriptive test names
+- Test one concept per test case
+- Avoid test interdependence
+- Use meaningful assertions
+- Avoid tests that will make the overall run slower
+
+### Component Testing
+- Use `renderWithProviders` for component tests
+- Use `renderHookWithProviders` for hook tests
+- Avoid mocking dependent components
+- Test component behavior, not implementation
+
+### Mocking Guidelines
+- Use mock helpers instead of inline mocks
+- Follow existing patterns for:
+  - Entity mocks
+  - Apollo mocks
+  - Provider mocks
+- Keep mocks simple and maintainable
+
+### Test Utilities
+- Leverage testing utilities from [@testing-library/react](mdc:package.json)
+- Use [@testing-library/jest-dom](mdc:package.json) for DOM assertions
+- Follow established patterns in existing tests
+
+## File Patterns
+These rules apply to all test files with `.spec.ts` or `.spec.tsx` extensions.

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

@@ -0,0 +1,24 @@
+---
+description: Outlines a pragmatic approach to TypeScript—favoring strict type safety where it adds real value in catching bugs and improving developer experience, without unnecessary overhead. Includes file organization, best practices, and consistent use of TypeScript to enforce clarity, maintainability, and confidence in the codebase.
+globs:
+alwaysApply: false
+---
+# TypeScript Development Standards
+
+## Type Safety
+Enforce comprehensive type safety across the codebase:
+
+### Strict Type Checking
+Be as strictly as possible where it delivers clear value—specifically in preventing bugs and improving the developer experience. The goal is to enforce strong types and catch issues early, without introducing excessive friction or overhead. If a strict setting improves safety, maintainability, or clarity, we’ll use it. If it creates noise or slows down iteration without real benefit, we’ll dial it back. This is about pragmatic strictness, not dogmatism.
+
+### File Organization
+- Place types at the bottom of files
+- Define PropTypes before component definitions
+
+## Best Practices
+- Use TypeScript for all new code
+- Leverage TypeScript's type system for better code quality
+- Follow React best practices with TypeScript
+- Use proper type definitions for props and state
+- Utilize TypeScript's utility types when appropriate
+- Suggest existing libaries as needed

package/bin/setup-cursor.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# setup-cursor.sh
+# Pulls shared Cursor rules unless running in CI, supports env-specific configs
+
+set -e
+
+# Detect CI environment
+if [ "$CI" = "true" ] || [ "$GITHUB_ACTIONS" = "true" ] || [ "$GITLAB_CI" = "true" ] || [ "$CIRCLECI" = "true" ]; then
+  echo "Detected CI environment – skipping .cursor setup"
+  exit 0
+fi
+
+# Check if an argument was passed
+ENV_TYPE="$1"
+
+if [ -z "$ENV_TYPE" ]; then
+  echo "Usage: bash setup-cursor.sh <env-type>"
+  echo "Example: bash setup-cursor.sh frontend"
+  exit 1
+fi
+
+REPO_URL="git@github.com:your-org/cursor-rules.git"
+TMP_DIR=".cursor-tmp"
+
+echo "Cloning rules from $REPO_URL..."
+
+# Remove existing .cursor and temp dir
+rm -rf .cursor "$TMP_DIR"
+
+# Clone into a temporary folder
+git clone --depth=1 "$REPO_URL" "$TMP_DIR"
+
+# Check for required rule files
+SHARED_RULES="$TMP_DIR/.cursor/shared/rules"
+ENV_RULES="$TMP_DIR/.cursor/$ENV_TYPE/rules"
+
+if [ ! -f "$SHARED_RULES" ]; then
+  echo "Shared rules not found in repo."
+  rm -rf "$TMP_DIR"
+  exit 1
+fi
+
+if [ ! -f "$ENV_RULES" ]; then
+  echo "Rules for environment '$ENV_TYPE' not found in repo."
+  echo "Expected: .cursor/$ENV_TYPE/rules"
+  rm -rf "$TMP_DIR"
+  exit 1
+fi
+
+# Setup final .cursor structure
+mkdir -p .cursor
+cat "$SHARED_RULES" "$ENV_RULES" > .cursor/rules
+
+# Clean up
+rm -rf "$TMP_DIR"
+
+echo ".cursor/rules setup complete for '$ENV_TYPE' with shared rules."

package/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "@mallardbay/cursor-rules",
+    "version": "1.0.0",
+    "description": "Mallard Bay shared cursor rules",
+    "main": "bin/setup-cursor.sh",
+    "repository": "git@github.com:mallardbay/cursor-rules.git",
+    "author": "mfrr1118 <mfrr@me.com>",
+    "license": "MIT",
+    "keywords": [
+        "cursor",
+        "ide",
+        "configuration"
+    ],
+    "files": [
+        "bin",
+        ".cursor"
+    ],
+    "publishConfig": {
+        "access": "public"
+    }
+}