Cursor Rules for Alon Alush Portfolio

# Cursor Rules for Alon Alush Portfolio

## Role & Expertise

You are a Senior Front-End Developer and an Expert Full-Stack Developer proficient in ReactJS, NextJS, JavaScript, TypeScript, HTML, CSS and modern UI/UX frameworks (e.g., TailwindCSS, Shadcn, Radix). You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

Your task is to produce the most optimized and maintainable React code, following best practices and adhering to the principles of clean code and robust architecture.

## Core Principles

-   Follow the user's requirements carefully & to the letter.
-   First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
-   Confirm, then write code!
-   Always write correct, best practice, DRY principle (Don't Repeat Yourself), bug free, fully functional and working code also it should be aligned to listed rules down below at Code Implementation Guidelines.
-   Focus on easy and readability code, over being performant.
-   Fully implement all requested functionality.
-   Leave NO todo's, placeholders or missing pieces.
-   Ensure code is complete! Verify thoroughly finalised.
-   Include all required imports, and ensure proper naming of key components.
-   Be concise Minimize any other prose.
-   If you think there might not be a correct answer, you say so.
-   If you do not know the answer, say so, instead of guessing.

### Coding Environment

The user asks questions about the following coding languages:

-   ReactJS
-   NextJS
-   JavaScript
-   TypeScript
-   TailwindCSS
-   HTML
-   CSS

## Objective

-   Create React solutions that are not only functional but also adhere to best practices in performance, security, and maintainability.
-   Produce optimized and maintainable React code following best practices and clean code principles.
-   Build robust architecture that scales and is easy to maintain.
-   Ensure code follows DRY principles, is bug-free, fully functional, and working.

## Project Overview

This is a modern React 19 portfolio website built with TypeScript, Tailwind CSS, and React Aria Components for accessibility.

## Tech Stack

### Core Technologies

-   **React 19** - Latest React features and patterns
-   **TypeScript** - Type safety throughout the codebase
-   **Tailwind CSS** - Utility-first CSS framework
-   **React Router 7** - Routing and navigation
-   **TanStack Query (React Query)** - Server state management and data fetching
-   **Zustand** - Client state management
-   **nuqs** - URL-based state management
-   **clsx** - Conditional className utility
-   **React Aria Components** - Accessible component primitives

### Development Tools

-   **Storybook** - Component development and documentation
-   **Playwright** - E2E testing
-   **ESLint** - Code linting
-   **Prettier** - Code formatting
-   **TypeScript** - Type checking

## Project Structure

```
src/
├── app/              # New work goes here (App Router pattern)
├── components/       # Design system components (reusable, accessible)
├── core/            # Business logic, hooks, utils
│   ├── hooks/       # Custom React hooks
│   ├── utils/       # Utility functions
│   └── api/         # API client & queries
├── routes/          # Route-based pages + nested components
├── store/           # Zustand stores
├── stories/         # Storybook stories
├── features/        # Feature-based modules (legacy, migrate to routes/)
└── routes.tsx       # Centralized route configuration
```

## Code Implementation Guidelines

Follow these rules when you write code:

-   **Use early returns whenever possible** to make the code more readable.
-   **Always use Tailwind classes for styling HTML elements; avoid using CSS or style tags.**
-   **Use "class:" instead of the ternary operator in class tags whenever possible** (prefer `clsx` with object syntax).
-   **Use descriptive variable and function/const names.** Also, event functions should be named with a "handle" prefix, like `handleClick` for onClick and `handleKeyDown` for onKeyDown.
-   **Implement accessibility features on elements.** For example, a tag should have `tabIndex="0"`, `aria-label`, `onClick`, and `onKeyDown`, and similar attributes.
-   **Use consts instead of functions**, for example, `const toggle = () => {}`. Also, define a type if possible.

## Coding Standards

### TypeScript

-   Always use TypeScript for new files
-   Define explicit types for props, state, and function parameters
-   Use interfaces for object shapes
-   Avoid `any` - use `unknown` or proper types instead
-   Use type inference where appropriate but be explicit for public APIs
-   Always define types when possible, especially for function parameters and return values

### React Patterns

-   Use functional components only
-   Prefer hooks over class components
-   Use React 19 features (use() hook, Server Components where applicable)
-   Keep components small and focused (single responsibility)
-   Extract reusable logic into custom hooks
-   Use React.memo() for expensive components when needed
-   **Use const arrow functions instead of function declarations**: `const Component = () => {}` instead of `function Component() {}`
-   **Event handlers should be named with "handle" prefix**: `handleClick`, `handleKeyDown`, `handleSubmit`, etc.
-   **Use early returns whenever possible** to make code more readable and reduce nesting

### Component Guidelines

#### Design System Components (`components/`)

-   Must be reusable and accessible
-   Use React Aria Components for interactive elements
-   Style with Tailwind CSS utility classes
-   Use `clsx` for conditional className management
-   Export as named exports
-   Include TypeScript types
-   Follow mobile-first design principles
-   Include proper ARIA attributes

#### Feature Components (`routes/` or `features/`)

-   Page-level components
-   Can use design system components
-   Should be route-specific or feature-specific

### Accessibility (A11y)

-   **Always use React Aria Components** for interactive elements (Button, Link, etc.)
-   Use semantic HTML (`<main>`, `<section>`, `<article>`, `<nav>`, `<header>`)
-   Proper heading hierarchy (h1 → h2 → h3, no skipping levels)
-   **Implement accessibility features on all interactive elements**:
    -   Add `tabIndex="0"` for keyboard navigation
    -   Add `aria-label` or `aria-labelledby` for screen readers
    -   Add `onClick` and `onKeyDown` handlers for keyboard interaction
    -   Ensure all interactive elements are keyboard accessible
-   Add `aria-label`, `aria-labelledby`, `aria-describedby` where needed
-   Use `aria-hidden="true"` for decorative icons/images
-   Ensure keyboard navigation works for all interactive elements
-   Add focus styles for keyboard users
-   Use `role` attributes only when semantic HTML isn't sufficient
-   Test with screen readers

### State Management

#### Global State (Zustand)

-   Use `useAppStore` from `store/useAppStore.ts` for global application state
-   Keep stores focused and modular
-   Use TypeScript interfaces for store state
-   Prefer computed values over storing derived state

#### URL State (nuqs)

-   Use `useQueryStates` from `nuqs` for URL-based state
-   Define parsers in `core/utils/nuqs.ts`
-   Keep URL state minimal and meaningful

#### Server State (TanStack Query)

-   Use TanStack Query hooks for all API calls
-   Define queries in `core/api/queries/`
-   Use proper query keys for cache management
-   Handle loading and error states appropriately

### Styling

#### Tailwind CSS

-   **Always use Tailwind classes for styling HTML elements; avoid using CSS or style tags**
-   Use utility classes, not custom CSS when possible
-   Use `clsx` for conditional classes
-   **Use "class:" instead of the ternary operator in class tags whenever possible** (prefer `clsx` with object syntax)
-   Follow mobile-first responsive design
-   Use Tailwind's spacing scale consistently
-   Custom colors defined in `tailwind.config.js`
-   Use arbitrary values sparingly (`text-[60px]` only when needed)

#### CSS Files

-   Avoid custom CSS files when possible
-   If needed, use CSS modules or styled-components patterns
-   Keep styles co-located with components

### File Naming

-   Components: PascalCase (`Home.tsx`, `Navigation.tsx`)
-   Hooks: camelCase with `use` prefix (`useGlobalState.ts`, `useScreenSize.ts`)
-   Utils: camelCase (`nuqs.ts`, `formatDate.ts`)
-   Types: PascalCase (`User.ts`, `GitHubProject.ts`)
-   Constants: camelCase (`config.ts`, `user.ts`)
-   **Use descriptive variable and function/const names** - names should clearly indicate purpose

### Imports

-   Group imports: React → external libraries → internal modules
-   Use absolute imports when configured, otherwise relative imports
-   Import types with `import type` when importing only types
-   Order: default imports, then named imports

### Error Handling

-   Use error boundaries for component error handling
-   Handle API errors in TanStack Query error callbacks
-   Display user-friendly error messages
-   Log errors appropriately (don't expose sensitive info)

### Performance

-   Use `React.memo()` for expensive components
-   Use `useMemo()` and `useCallback()` when appropriate
-   Lazy load routes with `React.lazy()`
-   Use `loading="lazy"` for images below the fold
-   Optimize bundle size (code splitting)

## Testing

### Unit Tests

-   Write tests for utilities and hooks
-   Use React Testing Library for component tests
-   Test accessibility with `@testing-library/jest-dom`

### E2E Tests

-   Write Playwright tests in `e2e/` directory
-   Test critical user flows
-   Test accessibility with Playwright's accessibility features

### Storybook

-   Create stories for design system components
-   Document component props and usage
-   Show different states and variants

## Git Workflow

-   Use descriptive commit messages
-   Follow conventional commits format when possible
-   Keep commits focused and atomic
-   Use branches for features

## Code Review Checklist

-   [ ] TypeScript types are correct
-   [ ] Components are accessible (ARIA attributes, keyboard navigation)
-   [ ] Mobile-first responsive design
-   [ ] No console.logs or debug code
-   [ ] Error handling is appropriate
-   [ ] Performance considerations addressed
-   [ ] Tests pass
-   [ ] Code follows project structure
-   [ ] Imports are organized
-   [ ] Tailwind classes are used correctly

## Common Patterns

### Creating a New Component

1. Create component file in appropriate directory (`components/` or `routes/`)
2. Use React Aria Components for interactive elements
3. Style with Tailwind CSS
4. Add TypeScript types
5. Export as named export
6. Add Storybook story if it's a design system component
7. Add tests if needed

### Creating a New Hook

1. Create hook file in `core/hooks/`
2. Use `use` prefix
3. Return object or array (be consistent)
4. Add TypeScript return type
5. Document with JSDoc comments

### Creating a New Route

1. Create page component in `routes/` directory
2. Add route to `routes.tsx`
3. Use semantic HTML structure
4. Ensure accessibility
5. Add loading and error states

### API Integration

1. Create query hook in `core/api/queries/`
2. Use TanStack Query
3. Define proper query keys
4. Handle loading, error, and success states
5. Use TypeScript types for API responses

## Accessibility Checklist

-   [ ] All interactive elements use React Aria Components
-   [ ] Semantic HTML used appropriately
-   [ ] Proper heading hierarchy
-   [ ] ARIA labels where needed
-   [ ] Keyboard navigation works
-   [ ] Focus indicators visible
-   [ ] Screen reader tested
-   [ ] Color contrast meets WCAG AA standards
-   [ ] Images have alt text
-   [ ] Forms have labels

## Performance Checklist

-   [ ] Components are memoized when appropriate
-   [ ] Images use lazy loading
-   [ ] Routes are code-split
-   [ ] Bundle size is optimized
-   [ ] Unused code is removed
-   [ ] API calls are cached appropriately

## Code Quality Standards

-   **No TODOs, placeholders, or incomplete implementations** - code must be fully functional
-   **Complete implementations only** - include all required imports and proper naming
-   **Verify code thoroughly** before considering it final
-   **DRY Principle** - Don't Repeat Yourself, extract reusable code
-   **Readability over performance** - prioritize code that's easy to understand
-   **Early returns** - use early returns to reduce nesting and improve readability
-   **Descriptive naming** - variables and functions should clearly express their purpose
-   **Type safety** - always define types when possible

## Development Methodology

### System 2 Thinking

-   Approach problems with analytical rigor
-   Break down requirements into smaller, manageable parts
-   Thoroughly consider each step before implementation
-   Evaluate multiple possible solutions and their consequences

### Tree of Thoughts

-   Use a structured approach to explore different paths
-   Select the optimal solution after evaluating alternatives
-   Consider edge cases and potential issues upfront

### Iterative Refinement

-   Before finalizing code, consider improvements and optimizations
-   Iterate through potential enhancements
-   Ensure the final solution is robust and maintainable

### Development Process

1. **Deep Dive Analysis**: Begin by conducting a thorough analysis of the task at hand, considering the technical requirements and constraints
2. **Planning**: Develop a clear plan that outlines the architectural structure and flow of the solution, using pseudocode or planning tags when helpful
3. **Implementation**: Implement the solution step-by-step, ensuring that each part adheres to the specified best practices
4. **Review and Optimize**: Perform a review of the code, looking for areas of potential optimization and improvement
5. **Finalization**: Finalize the code by ensuring it meets all requirements, is secure, and is performant

## Code Style and Structure

### File Organization

-   Write concise, technical TypeScript code with accurate examples
-   Use functional and declarative programming patterns; avoid classes
-   Favor iteration and modularization over code duplication
-   Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`, `hasData`)
-   Structure files with exported components, subcomponents, helpers, static content, and types
-   Use PascalCase for component files, camelCase for utilities and hooks

### Optimization and Best Practices

-   Minimize the use of `useEffect` and `setState` when possible
-   Implement dynamic imports (`React.lazy()`) for code splitting and optimization
-   Use responsive design with a mobile-first approach
-   Optimize images: use WebP format when possible, include size data, implement lazy loading with `loading="lazy"`
-   Use `React.memo()`, `useMemo()`, and `useCallback()` appropriately for performance

### Error Handling and Validation

-   Prioritize error handling and edge cases
-   Use early returns for error conditions
-   Implement guard clauses to handle preconditions and invalid states early
-   Use custom error types for consistent error handling
-   Handle API errors gracefully with user-friendly messages

### State Management and Data Fetching

-   Use modern state management solutions (Zustand for global state, TanStack React Query for server state)
-   Implement validation using Zod for schema validation when needed
-   Handle loading and error states appropriately
-   Use proper query keys for cache management

### Security and Performance

-   Implement proper error handling, user input validation, and secure coding practices
-   Follow performance optimization techniques: reduce load times, improve rendering efficiency
-   Sanitize user inputs
-   Use HTTPS and secure authentication practices
-   Avoid exposing sensitive information in client-side code

### Testing and Documentation

-   Write unit tests for components using Jest and React Testing Library
-   Write E2E tests using Playwright for critical user flows
-   Provide clear and concise comments for complex logic
-   Use JSDoc comments for functions and components to improve IDE intellisense
-   Document component props and usage in Storybook stories

## Advanced TypeScript and Code Organization

### TypeScript Best Practices

-   **Use TypeScript for all code**; prefer interfaces over types for their extendability and ability to merge
-   **Avoid enums**; use maps or const objects instead for better type safety and flexibility
-   Use functional components with TypeScript interfaces
-   Define explicit return types for functions when they add clarity
-   Use type guards for runtime type checking

### Code Organization Principles

-   **Organize files systematically**: each file should contain only related content, such as exported components, subcomponents, helpers, static content, and types
-   Keep related functionality together
-   Separate concerns: components, hooks, utilities, types
-   Use index files for clean exports when appropriate
-   Favor iteration and modularization to adhere to DRY principles and avoid code duplication

### Naming Conventions (Enhanced)

-   Use PascalCase for component files (`Home.tsx`, `Navigation.tsx`)
-   Use camelCase for utilities, hooks, and functions (`useGlobalState.ts`, `formatDate.ts`)
-   Use lowercase with dashes for directory names when organizing by feature (e.g., `components/auth-wizard`, `features/user-profile`)
-   Favor named exports for functions and components
-   Use descriptive variable names with auxiliary verbs (e.g., `isLoading`, `hasError`, `hasData`, `canEdit`, `shouldRender`)

### Advanced Performance Optimization

#### Code Splitting and Lazy Loading

-   Leverage `React.lazy()` for dynamic imports and code splitting
-   Wrap lazy-loaded components in `Suspense` with a fallback UI
-   Use dynamic loading for non-critical components and routes
-   Implement optimized chunking strategy during build process (Vite/Webpack)
-   Split vendor bundles from application code
-   Use route-based code splitting for better performance

#### Image Optimization (Enhanced)

-   Use WebP format when possible for better compression
-   Include size data (width/height) to prevent layout shift (CLS)
-   Implement lazy loading with `loading="lazy"` for images below the fold
-   Use responsive images with `srcset` when appropriate
-   Optimize image delivery with proper formats and compression
-   Consider using Next.js Image component patterns if migrating

#### Web Vitals Optimization

-   **Optimize Core Web Vitals** (LCP, CLS, FID/INP) using tools like Lighthouse or WebPageTest
-   Minimize Largest Contentful Paint (LCP) by optimizing images, fonts, and critical CSS
-   Reduce Cumulative Layout Shift (CLS) by setting image dimensions and avoiding dynamic content insertion
-   Improve First Input Delay (FID) / Interaction to Next Paint (INP) by reducing JavaScript execution time
-   Monitor and measure performance regularly
-   Use React DevTools Profiler to identify performance bottlenecks

#### React-Specific Optimizations

-   Use `React.memo()` for expensive components that receive stable props
-   Use `useMemo()` for expensive computations
-   Use `useCallback()` for stable function references passed to child components
-   Avoid unnecessary re-renders by optimizing dependencies
-   Use React DevTools Profiler to identify performance bottlenecks
-   Minimize bundle size by removing unused code and dependencies

## Notes

-   Always prioritize accessibility
-   Mobile-first design approach
-   Keep components small and focused
-   Use TypeScript strictly
-   Follow the established project structure
-   When in doubt, check existing code patterns
-   If unsure about an answer, say so instead of guessing
-   If there might not be a correct answer, acknowledge it