Awesome Cursor Rules Collection

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind.

Key Principles
- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

UI/UX Design Rules (Apple Human Interface Guidelines Inspired)
- Prioritize clarity, simplicity, and consistency in the UI.
- Follow Apple's "content-first" design approach: avoid unnecessary elements.
- Use system fonts for text (e.g., San Francisco); maintain hierarchy with font sizes and weights.
- Ensure components are accessible (ARIA attributes, keyboard navigation, contrast ratios).
- Design for adaptability: components must work well on various screen sizes and orientations.
- Prefer flat, clean design patterns over skeuomorphic designs.
- Minimize distractions: avoid overusing animations or visual noise.
- Respect system themes (dark/light mode) and user preferences.
- Create intuitive and discoverable navigation using patterns like breadcrumbs or tab bars.

Tailwind + Apple HIG Styling
- Use Tailwind's utility classes to adhere to design principles (e.g., padding, spacing, and alignment).
- Apply consistent margins and spacing based on an 8px grid system.
- Prioritize alignment and symmetry in layouts.
- Use subtle hover and focus states for interactive elements.

TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

Performance Optimization
- Optimize Web Vitals (LCP, CLS, FID).
- Use lazy loading and dynamic imports for non-critical components.
- Minimize 'useEffect' and 'useState' usage; rely on server components where possible.

Use tailwindcss for styling
Use msw for mocking
Use nx for project structure
Angular material for UI
Standalone components

Rules:

- Use async/await syntax instead of promises for cleaner code
- Name components and files with PascalCase
- Use interface for TypeScript types 
- Split code into components instead of one large file
- Add PropTypes for components
- Destructure props for cleaner component code
- Use absolute imports instead of relative imports
- Add comments for complex logic
- Use Tailwind CSS for styling
- Make API calls in useEffect hooks
- Handle errors globally with error boundaries
- Memoize expensive functions for performance
- Use React.memo for referential equality 
- Follow Airbnb style guide conventions

# Rust Learning Assistant
Rustの学習をサポートするためのAI設定

## Language Comparison
*.rs

他言語との比較による説明

### Context
- primary_language: Python
- secondary_languages: TypeScript, Julia
- experience_level: beginner in Rust

### Output Preferences
- 既知の言語（特にPython）との比較による説明を含める
- 新しい概念を導入する際は、既知の言語との違いを強調する
- コード例を示す際は、可能な限り既知の言語での類似実装も示す

## Learning Focus
*.rs

バックエンドエンジニアの視点からの説明

### Output Preferences
- バックエンド開発の文脈での使用例を優先する
- パフォーマンスとメモリ安全性の観点を重視する
- 実践的なユースケースを含める

## Code Explanation
*.rs

コード説明のスタイル設定

### Output Preferences
- 詳細な説明を段階的に提供する
- 新しい概念は基本的な説明から始める
- 実用的な例を含める
- ベストプラクティスを強調する 

本项目是一个使用 daisyui 的 nextjs 项目，

- 使用 pnpm 管理依赖。
- 使用 tailwindcss 进行样式开发。
- icon 使用 lucide-react 库。
- 状态管理使用 zustand。

## 项目逻辑

为用户提供了注册和游客两种登录方式。
进入页面后用户需要阅读相关引导，然后开始写作，发送内容之后会通过AI生成图片。

## Project Information

Main domain: ReviewWeb.site

## Tech stack
- Node.js
- Express.js
- Prisma (PostgreSQL)
- EJS
- TailwindCSS
- Commitlint

## When working with EJS
always use icons from https://remixicon.com/
always use tailwindcss for styling

## When working with Tailwind or CSS
always implement responsive layout with mobile-first approach
always implement dark mode

## For Express.js project
always import prisma client with: `import { prisma } from "@/lib/db";`
always use async/await for better readability and performance
always use `next()` for error handling of all routers
always use try-catch for fallback error handling
always use zod for validation
always generate swagger docs for all APIs
always use `bearerAuth` and `ApiKeyAuth` for swagger security

### Project Description

ReviewWeb.site is a tool that utilizes AI to helps you to scan through the websites and provide feedbacks based on the content.
Use case:
- You have a website and want to know how good it is
- You want to know how to improve your website
- You want to know how to market your website
- You want to know if the website is good for SEO
- You want to know if the website contains inappropriate content
- You want to know if the website is mobile-friendly
- You want to know if the website is secure or contains malware
  
### Short description
- ReviewWeb.site is a tool that utilizes AI to helps you to scan through the websites and provide feedbacks based on the content.

### Slogans
1. "Your Digital Lens: See Beyond the Surface"
2. "Decode, Improve, Dominate: Your Digital Success Starts Here"
3. "Website Insights, Marketing Hindsights"
4. "Unveil Your Website's True Potential"
5. "Transform Clicks into Insights, Websites into Masterpieces"

### Workflow:
- A user inputs a website url
- A user provides prompt instructions for the review
- After submitting, the system will start the review by crawling the website, analyzing the content, and take screenshots, then generate the report
- The user can review the result and download the report

### APIs
| Method | Endpoint               | Body Params                                                          | Description             |
| ------ | ---------------------- | -------------------------------------------------------------------- | ----------------------- |
| GET    | `/api/v1/healthz`      | -                                                                    | Health check endpoint   |
| GET    | `/api/v1/api_key`      | -                                                                    | Retrieve API key        |
| POST   | `/api/v1/upload`       | -                                                                    | Upload endpoint         |
| GET    | `/api/v1/profile`      | -                                                                    | Get user profile        |
| POST   | `/api/v1/screenshot`   | -                                                                    | Take website screenshot |
| -      | -                      | `url` (required): website url to screenshot                          |                         |
| -      | -                      | `full_page` (optional): full page screenshot (default: `false`)      |                         |
| -      | -                      | `viewport_width` (optional): screenshot width (default: `1400`)      |                         |
| -      | -                      | `viewport_height` (optional): screenshot height (default: `800`)     |                         |
| -      | -                      | `device_scale_factor` (optional): device scale factor (default: `1`) |                         |
| -      | -                      | `is_mobile` (optional): mobile screenshot (default: `false`)         |                         |
| POST   | `/api/v1/review`       | -                                                                    | Review a website        |
| -      | -                      | `url` (required): website url to review                              |                         |
| -      | -                      | `instructions`: review instructions                                  |                         |
| POST   | `/api/v1/review/batch` | -                                                                    | Batch review websites   |
| -      | -                      | `urls`: list of website urls (comma-separated)                       |                         |
| -      | -                      | `instructions`: review instructions                                  |                         |

## Python package management tool: Rye

This project uses rye for python dependency management instead of pip. To check dependencies, check `pyproject.toml` not `requirements.txt`. Rye is effectively cargo for python, with a rust-based backend for blazing fast env & dependency management. 

Don't use `pip install`, always use `rye sync` instead of `pip install -r requirements.txt` and `rye add <package_name> to add a new dependency`. Warn the user, if they try to use `pip` or try run programs with ordinary `python <file_name>.py`, and instead encourage them to run it using `rye run python <file_name>.py` after synchronizing with `rye sync`.

For reference:
- `rye sync`: Ensure it is using the correct python venv
- `rye run python <file_name>.py`: Run the python file using the python env defined by `pyproject.toml`
- `rye run python -m tests.path_to.test_module` to run a specific test in isolation without running all other tests

## Helpful commands

Some helpful commands have been defined in the `Makefile` already.

If the user is confused, point them towards these resources.

- `make all` - runs `main.py`
- `make lint` - runs `black` linter, an opinionated linter
- `make test` - runs all tests defined by `TEST_TARGETS = tests/folder1 tests/folder2`


## Using LLMs: Structured outputs

Whenever the user is using an LLM, always ask them if the output is structured, i.e. outputting a json, yaml, etc., etc. and always encourage them to use the structured chat object. 

```python
from utils.llm import Chatter
from pydantic import BaseModel

class MyOutputSchema(BaseModel):
    ...
chat = Chatter(
    ...
)

chat.set_structured_output(output_schema)
result = chat.invoke("Hello")
```

They allow you to have a 100% guarantee that the LLM will output a JSON/structured format, no more retries/error handling on parsing the LLM output. 


## Using global configuration

Whenever there is a hyperparameter that should be applied across the entire codebase, add those hyperparameters in `global_config/global_config.yaml`. Whenever a user seems to have defined a hyperparameter in the wrong scope, or using a constant value in their code point them towards `global_config/global_config.yaml` and ask them to add it there instead. 

Examples of this are:
- `MAX_RETRIES`
- `MODEL_NAME`
- etc, etc

Any private or secret keys should be stored in the sample.env dotenv file, which is automatically loaded into the .env file in the root of the project.

Examples of this are:
- `OPENAI_API_KEY`
- `HELICONE_API_KEY`
- `GITHUB_PERSONAL_ACCESS_TOKEN`
- etc, etc


And to autoload these from the environment, add the names to the global_config.py class member `_ENV`.

Then, these global config values can be accessed in python files using:

```yaml file=global_config/global_config.yaml
example_key: example_value
example_parent:
  example_child: example_value
```

```python
from global_config import global_config

print(global_config.example_parent.example_child)
```


## Writing tests

Whenever implementing a new feature, always encourage the user to write a test.

Tests are written using pytest. To add a new test, create a new file/directory in the `tests/` directory. Ensure, that whenever you create a new directory in the `tests/` directory, you also add a `tests/.../__init__.py` to the directory so python can recognize the test directory.

### Test structure

Look at below example for how you should write tests.

```python
from tests.test_template import TestTemplate, slow_test, nondeterministic_test
from global_config import global_config

class TestSkeleton(TestTemplate):
    # Initialize shared variables here for all tests
    @pytest.fixture(autouse=True)
    def setup_shared_variables(self, setup):
        # Initialize shared attributes here
        pass

    # Actual test code here
    # Possibly @slow_test or @nondeterministic_test
    def test_function(self):
        # Any actual test code here
        assert True
```



Few things to note:
- Inherit from `TestTemplate` (see `tests/test_template.py`) for proper test setup
- Use `self.config` for test configuration (loaded from `tests/config.yaml`)
- Prefix tests with `test_` and use `@slow_test` or `@nondeterministic_test` decorator for slow and/or nondeterministic tests
- Never use `unittest`, always use pytest


## Stylistic preferences
- Use snake case for all function, file, and directory names
- Use camel case for class names
- Use all lowercase for variable names
- Use all uppercase for constants
- Use 4 spaces for indentation
- Use double quotes for strings

Phase 1: Core Component Management
Basic Component Structure
Define component categories (CPU, GPU, Motherboard, etc.)
Create base component schema with essential fields
Set up database structure for components
Component CRUD Operations
Build component creation form with validation
Implement edit functionality
Add delete with dependency checking
Create bulk import/export system using CSV/JSON
Category Management
Create category hierarchy system
Implement category-specific attributes
Add category-based filtering and organization


Phase 2: Price & Compatibility Systems
Price Tracking
Set up price history database structure
Create price update automation system
Implement price change notifications
Add price trend visualization
Compatibility Engine
Define compatibility rules for each component type
Create compatibility checking system
Implement warning/error messaging
Add compatibility suggestion system

Phase 3: Build Analytics
Build Tracking
Create build history database
Implement build success/failure logging
Add build completion tracking
Set up build statistics collection
Component Pairing Analysis
Track successful component combinations
Analyze common compatibility issues
Create popularity metrics for combinations
Implement recommendation engine
Popular Builds
Track most-used configurations
Analyze build performance metrics
Create build templates system
Implement build sharing features

Phase 4: User Management
User System
Set up user authentication
Create user profiles
Implement role-based access
Add user activity tracking
Build History
Create personal build library
Add build saving/loading
Implement build sharing
Create build comparison tools
Phase 5: Inventory Management
Stock Management
Create stock level tracking
Implement low stock alerts
Add stock history tracking
Create stock prediction system
Price Management
Set up automated price updates
Create price comparison system
Implement price alert system
Add price optimization tools

You are an expert full-stack TypeScript developer specializing in modern React applications.

CORE EXPERTISE:
- Next.js 14+ with App Router
- TypeScript
- React Server Components
- Tailwind CSS
- Shadcn UI (Radix UI-based)
- Contentlayer & MDX
- Framer Motion

CODE ARCHITECTURE:
1. Directory Structure:
   /src/
   ├── app/           # Next.js App Router pages
   ├── components/    # React components
   │   ├── ui/       # Shadcn UI components
   │   ├── forms/    # Form components
   │   └── layout/   # Layout components
   ├── lib/          # Utility functions
   ├── hooks/        # Custom React hooks
   ├── styles/       # CSS and Tailwind styles
   └── types/        # TypeScript types

2. Component Organization:
   - Place page-specific components in app/_components/
   - Keep reusable components in src/components/
   - Use kebab-case for component files (e.g., auth-form.tsx)
   - Implement atomic design principles

CODING STANDARDS:
1. TypeScript:
   - Use strict type checking
   - Prefer interfaces over types
   - Use const assertions for literals
   - Implement proper error handling
   - Use discriminated unions for complex states

2. React Patterns:
   - Default to Server Components
   - Use 'use client' only when necessary
   - Implement proper error boundaries
   - Use React.Suspense for loading states
   - Follow the Container/Presenter pattern

3. State Management:
   - Use React Server Components for server state
   - Prefer URL state with nuqs
   - Implement local state with useState/useReducer
   - Use context sparingly and strategically

4. Styling:
   - Use Tailwind CSS with custom variables
   - Follow mobile-first responsive design
   - Implement dark mode with CSS variables
   - Use CSS modules for component-specific styles
   - Maintain consistent color schemes via CSS variables

PERFORMANCE OPTIMIZATION:
- Implement proper image optimization
- Use dynamic imports for large components
- Optimize Web Vitals (LCP, FID, CLS)
- Implement proper caching strategies
- Use proper lazy loading techniques

TOOLING:
- ESLint with strict rules
- Prettier for code formatting
- Husky for git hooks
- Commitlint for commit messages
- TypeScript strict mode enabled

WHEN WRITING CODE:
1. Prioritize:
   - Type safety
   - Performance
   - Accessibility
   - Reusability
   - Clean code principles

2. Avoid:
   - Any type assertions
   - Class components
   - Prop drilling
   - Unnecessary client-side JavaScript
   - Direct DOM manipulation

3. Prefer:
   - Function declarations over arrows
   - Server Components where possible
   - CSS variables for theming
   - Composition over inheritance
   - Early returns for conditionals

DOCUMENTATION:
- Include JSDoc comments for complex functions
- Document component props with TypeScript
- Add README.md for major features
- Include usage examples in comments
- Document any workarounds or gotchas

ERROR HANDLING:
- Implement proper error boundaries
- Use typed error handling
- Provide meaningful error messages
- Log errors appropriately
- Implement fallback UI states

We are implementing the full html5 spec. When answering questions, refer to the specification and pick solutions that will take us towards 100% compliance.

I will post failing testcases, and your job is to improve the code (tokenizer, parser, constants, node) so that we increase test coverage. When making changes, make sure you don't break previously passing testcases. Refer to both the Expected (correct according to spec) parse trees, the Actual (where our parser is failing) parse trees, and the debug printouts when understanding what the core problem is, and then suggest improvements to the code.

# Android Development Assistant Configuration

## ASSISTANT DEFINITION
```
ROLE: Android Development Expert
EXPERIENCE_LEVEL: Advanced (10+ years)
SPECIALTIES:
- Kotlin & Jetpack Compose
- Clean Architecture
- Performance Optimization

PHILOSOPHY:
1. Code Quality:
   - Clean, maintainable code
   - SOLID principles
   - Best practices

2. Architecture:
   - Clean Architecture
   - MVVM pattern
   - Domain-driven design

3. Communication:
   - Technical accuracy
   - Educational approach
   - Systematic problem-solving
```

## PROJECT STANDARDS

### 1. Critical Rules
```
DEPENDENCIES:
- Version modifications: PROHIBITED
- New libraries: TEAM APPROVAL REQUIRED
- Version compatibility: MANDATORY CHECK

ARCHITECTURE:
- Domain layer must be pure Kotlin
- Presentation layer uses Compose
- Clean separation between layers
```

You are a Senior Front-End Engineer and an expert in TypeScript, React and Vite.

Key Principles

- Write concise, technical responses with accurate TypeScript examples.
- Use functional, declarative programming. Avoid classes.
- Prefer iteration and modularization over duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading).
- Favor named exports for components.

JavaScript/TypeScript

- Use "function" keyword for pure functions and top level functions.
- Use TypeScript for all code. Prefer types over interfaces. Avoid enums, use maps.
- File structure: Exported component, subcomponents, helpers, static content.
- Always use curly braces for all code blocks.
- Use single quotes for strings.

React

- Use functional components and TypeScript types.
- Use declarative JSX.
- Use function, not const, for components.
- Use CSS modules for styling, do not use Tailwind.
- Place static content and interfaces at file end.
- Refer to the latest React documentation for best practices.