@mallardbay/cursor-rules 1.0.10 → 1.0.12

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

@@ -25,10 +25,10 @@ Use theme values consistently across all components:
 -   Use theme typography settings for text styles
 -   Example: `theme.fontSizes.md` instead of `'16px'`
 
-### Borders
+### Borders and border radius
 
 -   Use theme border styles and radius values
--   Example: `theme.borders.sm` instead of `'1px solid'`
+-   Examples: `theme.borders.sm` instead of `'1px solid'`, `theme.radii.md` instead of using px values
 
 ## Component Structure
 
@@ -73,6 +73,12 @@ Ensure responsive and accessible design:
 -   Optimize component rendering
 -   Avoid unnecessary re-renders
 -   Use React.memo and useMemo when appropriate
+-   Avoid defining functions inside components to prevent recreation on each render
+-   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
+-   Use useMemo for object/array creation that would otherwise be recreated on each render
 
 ## File Patterns
 

package/.cursor/frontend-lib/rules/storybook.mdc

@@ -0,0 +1,147 @@
+---
+alwaysApply: true
+---
+
+# Storybook Performance Standards
+
+## Story Optimization
+
+Optimize Storybook stories for better performance and developer experience:
+
+### Story Structure
+
+-   Use `StoryObj` type for better type safety
+-   Implement proper story parameters and controls
+-   Group related stories using `storiesOf` or CSF 3.0
+-   Use meaningful story names and descriptions
+-   Organize stories by component hierarchy (e.g., "Core/Button")
+
+### Story Organization
+
+-   Group stories by component or feature
+-   Use consistent naming conventions for stories
+-   Implement proper story hierarchy with nested folders
+-   Separate interactive and documentation stories
+-   Use helper functions like `renderStorySections` for consistent layouts
+-   Create reusable story section builders for component variants
+
+## Rendering Optimization
+
+Prevent unnecessary re-renders in stories:
+
+-   Avoid inline styles in story args
+-   Prevent inline object creation in story parameters
+-   Use proper key props in story lists
+-   Memoize complex story args and callbacks
+-   Use `fn()` from `@storybook/test` for mock functions
+-   Spread args properly to avoid TypeScript errors
+
+### Story Dependencies
+
+-   Prefer existing dependencies over new ones
+-   Review [package.json](mdc:package.json) before adding new packages
+-   Consider bundle size impact of new story dependencies
+-   Use tree-shaking friendly imports for story utilities
+-   Import storybook helpers from dedicated helper files
+
+## Component Variant Management
+
+-   Use helper functions like `getStoryComponentVariantsAndColorSchemes` for systematic variant testing
+-   Create structured sections for different component states
+-   Implement consistent labeling for component variants
+-   Use TypeScript to ensure proper component prop spreading
+
+## Performance Best Practices
+
+-   Use `play` functions for complex interactions
+-   Implement proper story loading states
+-   Optimize story assets and images
+-   Use Storybook's performance monitoring tools
+-   Implement proper story caching strategies
+-   Avoid inline component creation in render functions
+
+## Story Development
+
+-   Write stories that cover all component states
+-   Use controls for interactive testing
+-   Implement proper accessibility testing in stories
+-   Use Storybook's built-in performance profiling
+-   Create comprehensive variant coverage (primary, secondary, etc.)
+-   Use meaningful labels for each component variant
+-   Implement proper TypeScript typing for story args
+
+## File Patterns
+
+These rules apply to all Storybook story files (`.stories.ts`, `.stories.tsx`, `.stories.js`, `.stories.jsx`) in the project.
+
+# Storybook Performance Standards
+
+## Story Optimization
+
+Optimize Storybook stories for better performance and developer experience:
+
+### Story Structure
+
+-   Use `StoryObj` type for better type safety
+-   Implement proper story parameters and controls
+-   Group related stories using `storiesOf` or CSF 3.0
+-   Use meaningful story names and descriptions
+-   Organize stories by component hierarchy (e.g., "Core/Button")
+
+### Story Organization
+
+-   Group stories by component or feature
+-   Use consistent naming conventions for stories
+-   Implement proper story hierarchy with nested folders
+-   Separate interactive and documentation stories
+-   Use helper functions like `renderStorySections` for consistent layouts
+-   Create reusable story section builders for component variants
+
+## Rendering Optimization
+
+Prevent unnecessary re-renders in stories:
+
+-   Avoid inline styles in story args
+-   Prevent inline object creation in story parameters
+-   Use proper key props in story lists
+-   Memoize complex story args and callbacks
+-   Use `fn()` from `@storybook/test` for mock functions
+-   Spread args properly to avoid TypeScript errors
+
+### Story Dependencies
+
+-   Prefer existing dependencies over new ones
+-   Review [package.json](mdc:package.json) before adding new packages
+-   Consider bundle size impact of new story dependencies
+-   Use tree-shaking friendly imports for story utilities
+-   Import storybook helpers from dedicated helper files
+
+## Component Variant Management
+
+-   Use helper functions like `getStoryComponentVariantsAndColorSchemes` for systematic variant testing
+-   Create structured sections for different component states
+-   Implement consistent labeling for component variants
+-   Use TypeScript to ensure proper component prop spreading
+
+## Performance Best Practices
+
+-   Use `play` functions for complex interactions
+-   Implement proper story loading states
+-   Optimize story assets and images
+-   Use Storybook's performance monitoring tools
+-   Implement proper story caching strategies
+-   Avoid inline component creation in render functions
+
+## Story Development
+
+-   Write stories that cover all component states
+-   Use controls for interactive testing
+-   Implement proper accessibility testing in stories
+-   Use Storybook's built-in performance profiling
+-   Create comprehensive variant coverage (primary, secondary, etc.)
+-   Use meaningful labels for each component variant
+-   Implement proper TypeScript typing for story args
+
+## File Patterns
+
+These rules apply to all Storybook story files (`.stories.ts`, `.stories.tsx`, `.stories.js`, `.stories.jsx`) in the project.

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

@@ -1,48 +1,53 @@
 ---
 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
+
+-   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)
+
+-   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.
+
+-   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
+
+-   Use constants instead of string literals for:
+    -   Copy text (UI content). Most projects have a `copy-constants` file
+    -   Test IDs. Most projects have `TEST_IDS` defined
+    -   Error messages
+    -   URLs
+-   Source constants from:
+    -   @mallardbay/lib-shared-helpers
+    -   Local constants files
 
 ## Cursor Rules
-- Suggest cursor rules as needed
+
+-   Suggest cursor rules as needed

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

@@ -1,40 +1,46 @@
 ---
 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
+
+-   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
+
+-   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
+
+-   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
+
+-   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
+
+-   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

@@ -1,41 +1,48 @@
 ---
 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
+
+-   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
+
+-   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
+
+-   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
+
+-   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
+
+-   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/general-best-practices.mdc

@@ -0,0 +1,163 @@
+---
+description: Core development principles and best practices that always apply—optimized for AI agents to produce clean, maintainable, reviewable code with low cognitive complexity, clear semantics, and incremental changes.
+alwaysApply: true
+---
+
+# General Best Practices
+
+These principles apply to all code changes and should guide every implementation decision.
+
+## Core Principles
+
+### DRY (Don't Repeat Yourself)
+- Extract common logic into reusable functions, utilities, or shared modules
+- Leverage existing patterns and utilities before creating new ones
+- When duplicating code, ask: "Can this be abstracted?"
+- Prefer composition and shared utilities over copy-paste solutions
+
+### Leverage Existing Patterns
+- **Always** search the codebase for similar implementations before creating new code
+- Follow established patterns, conventions, and architectural decisions
+- Use existing utilities, helpers, and shared libraries
+- Match the style and structure of related files
+- When patterns exist, use them consistently—don't invent new approaches without justification
+
+### Incremental Changes
+- **Minimize large changes in a single PR or commit**
+- Break large features into smaller, testable increments
+- Make changes that are easy to review and understand
+- Prefer multiple small PRs over one massive change
+- Each change should be independently testable and reviewable
+- If a change touches many files, consider splitting it into logical phases
+
+### Semantic Clarity
+- Use **semantic, self-documenting names** for functions, variables, and types
+- Function names should clearly describe what they do (e.g., `calculateTotalPrice` not `calc`)
+- Variable names should express intent (e.g., `userAccountBalance` not `bal`)
+- Terminology should be consistent across the codebase
+- Avoid abbreviations unless they're widely understood in the domain
+- Names should make code readable without comments
+
+### Cognitive Complexity
+- **Keep cognitive complexity low**—code should be easy to understand at a glance
+- Prefer early returns and guard clauses over deep nesting
+- Break complex logic into smaller, well-named functions
+- Maximum nesting depth: 3 levels
+- Use intermediate variables to clarify intent
+- Extract complex conditionals into named boolean functions
+- Avoid deeply nested ternaries—use if/else or extract to function
+
+### Separation of Concerns
+- **Files**: Each file should have a single, clear responsibility
+- **Functions**: Each function should do one thing well
+- Separate business logic from presentation, data access, and side effects
+- Keep UI components focused on rendering and user interaction
+- Extract business logic into pure functions or services
+- Avoid god objects or functions that do too much
+
+## Code Quality Standards
+
+### Avoid "AI Slop"
+- **Write code that's easy for humans to review**
+- Avoid generating large amounts of code without understanding context
+- Don't create unnecessary abstractions or over-engineered solutions
+- Remove unused code, imports, and dead branches
+- Clean up commented-out code and debugging statements
+- If an approach doesn't work, **clean up failed attempts** before trying another
+- Keep only relevant, working code—remove experimental code that didn't pan out
+
+### Testing and Linting
+- **Lint and test files related to your changes** before completing work
+- Run linters on modified files and fix issues
+- Run tests for affected modules, not the entire test suite unnecessarily
+- For large changes: **use test sharding**—split tests across multiple runs
+- **Do not run all tests in parallel** when dealing with many changes
+- Tests should be **clear, fast, and minimize setup duplication**
+- Use shared test utilities and fixtures to reduce boilerplate
+- Each test should be independent and runnable in isolation
+
+### Code Organization
+- Group related functionality together
+- Keep related code close (cohesion)
+- Minimize dependencies between modules (loose coupling)
+- Use appropriate data structures for the problem
+- Prefer composition over inheritance
+- Make functions pure when possible (no side effects)
+- Handle edge cases explicitly—don't rely on implicit behavior
+
+### Type Safety and Clarity
+- Use TypeScript types effectively—avoid `any` unless necessary
+- Make types explicit and meaningful
+- Use const assertions and readonly where appropriate
+- Prefer `const` over `let`, avoid `var`
+- Use type guards and discriminated unions for type narrowing
+
+### Performance Considerations
+- Consider performance implications, but **avoid premature optimization**
+- Profile before optimizing—optimize bottlenecks, not everything
+- Use appropriate algorithms and data structures
+- Avoid unnecessary re-renders, re-computations, or API calls
+- Cache expensive computations when appropriate
+
+## AI Agent Workflow
+
+### Before Making Changes
+1. **Create a plan** before making changes directly—outline the approach, identify affected files, and break down the work into steps
+2. **Read existing code** to understand patterns and context
+3. **Search the codebase** for similar implementations
+4. **Check git history** to understand why code exists as it does
+5. **Identify related files** that might be affected
+6. **Ask clarifying questions** if requirements are unclear
+
+### During Implementation
+1. Make **small, incremental changes**
+2. **Test as you go**—verify each change works before moving on
+3. **Lint frequently**—don't accumulate lint errors
+4. **Follow existing patterns**—don't reinvent the wheel
+5. **Use semantic names**—code should be self-documenting
+6. **Keep functions focused**—one responsibility per function
+7. **Extract common logic**—don't duplicate code
+
+### After Making Changes
+1. **Clean up failed attempts**—remove experimental code
+2. **Remove unused code**—imports, variables, functions
+3. **Run linters** on modified files
+4. **Run relevant tests**—not the entire suite unless necessary
+5. **Verify the change works** end-to-end
+6. **Check for side effects**—ensure changes don't break unrelated code
+
+### When Changes Are Large
+1. **Consider splitting** into multiple smaller PRs
+2. **Use test sharding**—run tests in batches, not all at once
+3. **Review incrementally**—make sure each part works before moving on
+4. **Document the approach**—explain why changes are structured this way
+5. **Check impact** on related systems and files
+
+## Anti-Patterns to Avoid
+
+- ❌ Copy-pasting code instead of extracting to a function
+- ❌ Creating new patterns when existing ones work
+- ❌ Making massive changes in one go
+- ❌ Using vague names like `data`, `temp`, `value`, `thing`
+- ❌ Deeply nested conditionals and loops
+- ❌ Functions that do multiple unrelated things
+- ❌ Leaving commented-out code or debugging statements
+- ❌ Skipping tests or linting "to save time"
+- ❌ Running entire test suite for small changes
+- ❌ Leaving experimental code after failed attempts
+- ❌ Premature optimization without profiling
+- ❌ Using `any` types to avoid type errors
+- ❌ Magic numbers or strings without constants
+
+## Remember
+
+**Code is read far more often than it's written.** Write code that:
+- Is easy to understand
+- Is easy to review
+- Is easy to test
+- Is easy to modify
+- Follows established patterns
+- Has clear semantics
+- Minimizes cognitive load
+
+When in doubt, prefer clarity and simplicity over cleverness.

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

@@ -1,38 +1,45 @@
 ---
 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
+
+-   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
+
+-   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
+
+-   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
+
+-   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

@@ -32,7 +32,8 @@ Avoid e2e tests for UI. Favor unit tests.
 
 -   Happy path testing
 -   Error case handling
--   Edge case coverage
+-   Edge case coverage within reason. Optimize for branching logic, and avoid creating nearly identical tests
+-   Aim for simplicity
 -   All tests must pass before completion
 
 ### Test Quality