@mallardbay/cursor-rules 1.0.10 → 1.0.11

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/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

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

@@ -1,24 +1,27 @@
 ---
-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
+alwaysApply: true
 ---
+
 # 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
+
+-   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
+
+-   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/README.md

@@ -1,10 +1,15 @@
 # Cursor Rules
 
-A tool for managing Cursor IDE rules across different environment types with shared base configurations.
+A tool for managing Cursor IDE rules and Claude Code configuration across different environment types with shared base configurations.
 
 ## Overview
 
-This project provides a structured way to manage Cursor IDE rules for different development environments while maintaining a shared base configuration. It supports three main environment types:
+This project provides a structured way to manage AI agent rules for different development environments while maintaining a shared base configuration. It generates:
+
+- **Cursor IDE**: `.cursor/rules/*.mdc` files
+- **Claude Code**: A combined `CLAUDE.md` file at project root
+
+It supports three main environment types:
 
 -   `frontend`: Basic frontend development rules
 -   `frontend-lib`: Extended rules for frontend library development, inheriting from frontend rules
@@ -66,6 +71,22 @@ The rules follow an inheritance pattern:
 -   All environments include the shared base rules
 -   `frontend-lib` inherits rules from both `frontend` and `frontend-lib` directories
 
+## Output
+
+Running the setup script generates:
+
+```
+your-project/
+├── .cursor/
+│   └── rules/          # Cursor IDE rules (*.mdc files)
+│       ├── code-quality.mdc
+│       ├── testing.mdc
+│       └── ...
+└── CLAUDE.md           # Claude Code configuration (combined rules)
+```
+
+The `CLAUDE.md` file combines all applicable rules into a single file, with YAML frontmatter stripped for compatibility with Claude Code.
+
 ## Development
 
 ### Adding New Rules

package/bin/setup-cursor.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # setup-cursor.sh — frontend & frontend-lib layering with shared base
+# Also generates CLAUDE.md for Claude Code
 
 set -e
 
@@ -11,8 +12,13 @@ if [ -z "$ENV_TYPE" ]; then
   exit 1
 fi
 
-SCRIPT_PATH="$(realpath "$0")"
-SRC_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+# Get the real path of the script (portable across Mac/Linux)
+get_real_path() {
+  local path="$1"
+  cd "$(dirname "$path")" && echo "$(pwd -P)/$(basename "$path")"
+}
+SCRIPT_PATH="$(get_real_path "$0")"
+SRC_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd -P)"
 
 SHARED_DIR="$SRC_DIR/.cursor/shared/rules"
 FRONTEND_DIR="$SRC_DIR/.cursor/frontend/rules"
@@ -21,6 +27,10 @@ BACKEND_DIR="$SRC_DIR/.cursor/backend/rules"
 
 mkdir -p .cursor/rules
 
+# Temporary file to collect CLAUDE.md content
+CLAUDE_MD_TEMP=$(mktemp)
+trap 'rm -f "$CLAUDE_MD_TEMP"' EXIT
+
 copy_rules() {
   local DIR="$1"
   if [ -d "$DIR" ]; then
@@ -29,20 +39,48 @@ copy_rules() {
   fi
 }
 
+# Append rules to CLAUDE.md (strips YAML frontmatter)
+append_to_claude_md() {
+  local DIR="$1"
+  if [ -d "$DIR" ]; then
+    for file in "$DIR"/*.mdc; do
+      [ -f "$file" ] || continue
+      # Add separator
+      echo "" >> "$CLAUDE_MD_TEMP"
+      echo "---" >> "$CLAUDE_MD_TEMP"
+      echo "" >> "$CLAUDE_MD_TEMP"
+      # Strip YAML frontmatter (content between --- markers) and append
+      awk '
+        BEGIN { in_frontmatter=0; found_end=0 }
+        /^---$/ && !found_end {
+          if (in_frontmatter) { found_end=1; next }
+          else { in_frontmatter=1; next }
+        }
+        !in_frontmatter || found_end { print }
+      ' "$file" >> "$CLAUDE_MD_TEMP"
+    done
+  fi
+}
+
 # Always include shared rules
 copy_rules "$SHARED_DIR"
+append_to_claude_md "$SHARED_DIR"
 
 # Inheritance handling
 case "$ENV_TYPE" in
   frontend)
     copy_rules "$FRONTEND_DIR"
+    append_to_claude_md "$FRONTEND_DIR"
     ;;
   backend)
     copy_rules "$BACKEND_DIR"
+    append_to_claude_md "$BACKEND_DIR"
     ;;
   frontend-lib)
     copy_rules "$FRONTEND_DIR"
     copy_rules "$FRONTEND_LIB_DIR"
+    append_to_claude_md "$FRONTEND_DIR"
+    append_to_claude_md "$FRONTEND_LIB_DIR"
     ;;
   *)
     echo "Unknown environment type: $ENV_TYPE"
@@ -50,4 +88,9 @@ case "$ENV_TYPE" in
     ;;
 esac
 
-echo ".cursor/rules setup complete for '$ENV_TYPE'"
+# Generate CLAUDE.md
+mv "$CLAUDE_MD_TEMP" CLAUDE.md
+trap - EXIT
+echo "CLAUDE.md generated for Claude Code"
+
+echo "Setup complete for '$ENV_TYPE' (Cursor + Claude)"

package/package.json

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