# YCode Cursor AI Rules

## 🎯 Project Context

**YCode** is a self-hosted visual website builder built with Next.js 15, TypeScript, Tailwind CSS, and Supabase. This is a **fast-moving team project** where multiple developers use Cursor simultaneously. Code consistency and abstraction are critical.

---

## 🧠 Core Philosophy: ALWAYS Think About Abstraction

Before writing any code, ask yourself:

1. **Can this logic be extracted into a reusable hook?**

2. **Does a ShadCN component already exist for this UI element?**

3. **Is this component doing too many things? Should it be split?**

4. **Can this be a pure utility function instead of component logic?**

5. **Will another team member be able to reuse this easily?**

**Golden Rule**: If you're writing the same code twice, abstract it.

---

## 🎨 1. ShadCN Components (MANDATORY)

### ALWAYS Use ShadCN for UI Primitives

**Available ShadCN Components** (in `/components/ui/`):

- `Button` - All button interactions

- `Input` - Text inputs

- `Textarea` - Multi-line text

- `Label` - Form labels

- `Select` - Dropdowns

- `Tabs` - Tab navigation

- `Dropdown Menu` - Context menus

- `Popover` - Overlays

- `Tooltip` - Hover hints

- `Slider` - Range inputs

- `Badge` - Status indicators

- `Spinner` - Loading states

- `Icon` - Lucide icons (via icon.tsx)

### ✅ CORRECT Usage

```typescript

import { Button } from '@/components/ui/button';

import { Input } from '@/components/ui/input';

import { Icon } from '@/components/ui/icon';

export function SearchBar({ onSearch }: SearchBarProps) {

const [query, setQuery] = useState('');

return (

<div className="flex gap-2">

<Input

value={query}

onChange={(e) => setQuery(e.target.value)}

placeholder="Search pages..."

/>

<Button size="sm" onClick={() => onSearch(query)}>

<Icon name="search" />

Search

</Button>

</div>

);

}

```

### ❌ FORBIDDEN - Never Do This

```typescript

// ❌ WRONG: Custom button instead of ShadCN

export function SearchBar({ onSearch }: SearchBarProps) {

return (

<button className="px-4 py-2 bg-blue-500 rounded hover:bg-blue-600">

Search

</button>

);

}

// ❌ WRONG: Custom input instead of ShadCN

<input className="border rounded px-2 py-1" />

```

### Extending ShadCN Components

If you need custom behavior, **compose** ShadCN components:

```typescript

// ✅ CORRECT: Composition

import { Button } from '@/components/ui/button';

import { Icon } from '@/components/ui/icon';

interface IconButtonProps {

icon: string;

label: string;

onClick: () => void;

}

export function IconButton({ icon, label, onClick }: IconButtonProps) {

return (

<Button size="sm" variant="secondary" onClick={onClick}>

<Icon name={icon} />

{label}

</Button>

);

}

```

---

## 🏗️ 2. Component Architecture & Abstraction

### Single Responsibility Principle

Each component should do ONE thing well:

```typescript

// ✅ GOOD: Small, focused components

function PageListItem({ page, onSelect, isActive }: PageListItemProps) {

return (

<button

onClick={() => onSelect(page.id)}

className={cn(

'w-full text-left px-3 py-2 rounded',

isActive ? 'bg-zinc-700' : 'hover:bg-zinc-800'

)}

>

<Icon name="file" />

{page.title}

</button>

);

}

function PageList({ pages, selectedId, onSelect }: PageListProps) {

return (

<div className="flex flex-col gap-1">

{pages.map(page => (

<PageListItem

key={page.id}

page={page}

isActive={selectedId === page.id}

onSelect={onSelect}

/>

))}

</div>

);

}

// ❌ BAD: Monolithic component doing everything

function PageManagement() {

// 500 lines of code managing pages, settings, modals, etc.

}

```

### Extract Custom Hooks

Move reusable logic into custom hooks:

```typescript

// ✅ GOOD: Reusable hook

export function useDebounce<T>(value: T, delay: number): T {

const [debouncedValue, setDebouncedValue] = useState(value);

useEffect(() => {

const handler = setTimeout(() => setDebouncedValue(value), delay);

return () => clearTimeout(handler);

}, [value, delay]);

return debouncedValue;

}

// Usage in component

function SearchInput() {

const [query, setQuery] = useState('');

const debouncedQuery = useDebounce(query, 500);

useEffect(() => {

if (debouncedQuery) {

performSearch(debouncedQuery);

}

}, [debouncedQuery]);

}

```

### Extract Utility Functions

Keep components clean by moving pure functions to `/lib`:

```typescript

// ✅ GOOD: Utility in /lib/layer-utils.ts

export function findLayerById(layers: Layer[], id: string): Layer | null {

for (const layer of layers) {

if (layer.id === id) return layer;

if (layer.children) {

const found = findLayerById(layer.children, id);

if (found) return found;

}

}

return null;

}

// Usage in component

import { findLayerById } from '@/lib/layer-utils';

function LayerEditor({ layers, selectedId }: LayerEditorProps) {

const selectedLayer = findLayerById(layers, selectedId);

// ...

}

```

---

## 📁 3. File & Naming Conventions

### File Names

- **All files**: `kebab-case.tsx` (e.g., `page-settings.tsx`, `user-profile.tsx`)

- **Components**: PascalCase export matching filename

- File: `layer-renderer.tsx` → Export: `LayerRenderer`

- **Utilities**: camelCase functions

- File: `layer-utils.ts` → Export: `findLayerById`

- **Hooks**: camelCase with `use` prefix

- File: `use-debounce.ts` → Export: `useDebounce`

### Variable & Function Names

```typescript

// Components & Types: PascalCase

const UserProfile: React.FC<UserProfileProps> = () => {};

interface LayerProps {}

type PageStatus = 'draft' | 'published';

// Functions & Variables: camelCase

const handleClick = () => {};

const userData = fetchUser();

function formatDate(date: Date) {}

// Event Handlers: handleX pattern

const handleSubmit = () => {};

const handlePageSelect = (id: string) => {};

const handleInputChange = (e: ChangeEvent) => {};

// Boolean: isX, hasX, shouldX

const isLoading = false;

const hasChildren = layers.length > 0;

const shouldRender = isVisible && hasData;

// Constants: SCREAMING_SNAKE_CASE

const MAX_PAGE_SIZE = 100;

const API_BASE_URL = 'https://api.example.com';

const DEFAULT_LAYER_CLASSES = 'flex gap-4';

```

---

## 📦 4. Import Organization

**ALWAYS order imports consistently** to prevent merge conflicts:

```typescript

// 1. React/Next.js core

import React, { useState, useEffect, useMemo, useCallback } from 'react';

import { useRouter, usePathname } from 'next/navigation';

import Image from 'next/image';

// 2. External libraries (alphabetical)

import { create } from 'zustand';

import debounce from 'lodash.debounce';

import { DndContext } from '@dnd-kit/core';

// 3. ShadCN UI components (alphabetical)

import { Button } from '@/components/ui/button';

import { Input } from '@/components/ui/input';

import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';

// 4. Internal components (alphabetical)

import { LayerRenderer } from '@/components/layers/LayerRenderer';

import { PageSettings } from './PageSettings';

import ElementLibrary from './ElementLibrary';

// 5. Stores (alphabetical)

import { useEditorStore } from '@/stores/useEditorStore';

import { usePagesStore } from '@/stores/usePagesStore';

// 6. Utils, APIs, lib (alphabetical)

import { pagesApi } from '@/lib/api';

import { cn } from '@/lib/utils';

import { findLayerById } from '@/lib/layer-utils';

// 7. Types (always last, alphabetical)

import type { Layer, Page, PageLayers, Asset } from '@/types';

```

---

## 🛣️ 5. Path Aliases - When to Use What

### Rules:

- Use `@/` for **everything outside current directory**

- Use `./` **ONLY** for files in the **same directory**

- Use `../` **sparingly** (max 1 level up, prefer `@/`)

- **NEVER** use deep relative paths like `../../../../`

```typescript

// ✅ CORRECT

import { Button } from '@/components/ui/button';

import { useEditorStore } from '@/stores/useEditorStore';

import { PageSettings } from './PageSettings'; // Same directory

import { findLayerById } from '@/lib/layer-utils';

// ❌ WRONG

import { Button } from '../../../components/ui/button';

import { useEditorStore } from '../../stores/useEditorStore';

```

---

## ⚛️ 6. Server vs Client Components (Next.js 15)

### Default: Server Components

**Don't add any directive** - components are Server Components by default.

### Add `'use client'` ONLY When:

- Using React hooks (`useState`, `useEffect`, `useCallback`, etc.)

- Using event handlers (`onClick`, `onChange`, `onSubmit`)

- Using browser APIs (`window`, `localStorage`, `document`)

- Using Zustand stores

- Using client-only libraries

```typescript

// ✅ Server Component (no directive)

// app/[slug]/page.tsx

export default async function Page({ params }: { params: { slug: string } }) {

const page = await fetchPageBySlug(params.slug);

return <LayerRenderer layers={page.layers} />;

}

// ✅ Client Component (with directive)

// app/ycode/components/LayersTree.tsx

'use client';

import { useState } from 'react';

export default function LayersTree({ layers }: LayersTreeProps) {

const [expanded, setExpanded] = useState<Set<string>>(new Set());

// Component using hooks and state

}

```

### Keep `'use client'` Close to Leaves

Push client boundaries down the tree:

```typescript

// ✅ GOOD: Server component wraps client component

// app/page.tsx (Server Component)

export default function Page() {

return (

<div>

<Header /> {/* Server */}

<InteractiveWidget /> {/* Client */}

<Footer /> {/* Server */}

</div>

);

}

// ❌ BAD: Everything is client-side unnecessarily

'use client';

export default function Page() {

return (

<div>

<Header /> {/* Unnecessarily client-side */}

<InteractiveWidget />

<Footer /> {/* Unnecessarily client-side */}

</div>

);

}

```

---

## 🗄️ 7. Repository Pattern (Backend/API)

### NEVER Use Supabase Directly in API Routes

**Architecture**: `API Route → Repository → Supabase Client`

```typescript

// ✅ CORRECT: Use repository pattern

// app/api/pages/[id]/route.ts

import { NextRequest, NextResponse } from 'next/server';

import { getPageById, updatePage } from '@/lib/repositories/pageRepository';

export async function GET(

request: NextRequest,

{ params }: { params: { id: string } }

) {

try {

const page = await getPageById(params.id);

if (!page) {

return NextResponse.json({ error: 'Page not found' }, { status: 404 });

}

return NextResponse.json({ data: page });

} catch (error) {

console.error('Error fetching page:', error);

return NextResponse.json(

{ error: 'Failed to fetch page' },

{ status: 500 }

);

}

}

// ❌ WRONG: Direct Supabase in API route

import { getSupabaseAdmin } from '@/lib/supabase-server';

export async function GET(request: NextRequest, { params }) {

const supabase = await getSupabaseAdmin();

const { data } = await supabase.from('pages').select('*').eq('id', params.id);

// WRONG! Use repository instead

}

```

### Create Repositories for All Data Entities

**IMPORTANT**: Always use alias imports (`@/lib/...`) for all lib modules including `supabase-server` and repositories. Never use relative imports like `../supabase-server` or `../repositories/settingsRepository`. This ensures consistent behavior and allows overlays to work correctly in multi-tenant deployments.

Example structure in `/lib/repositories/pageRepository.ts`:

```typescript

import { getSupabaseAdmin } from '@/lib/supabase-server';

import type { Page } from '@/types';

export async function getAllPages(): Promise<Page[]> {

const client = await getSupabaseAdmin();

const { data, error } = await client

.from('pages')

.select('*')

.order('created_at', { ascending: false });

if (error) throw new Error(`Failed to fetch pages: ${error.message}`);

return data || [];

}

export async function getPageById(id: string): Promise<Page | null> {

const client = await getSupabaseAdmin();

const { data, error } = await client

.from('pages')

.select('*')

.eq('id', id)

.single();

if (error && error.code !== 'PGRST116') {

throw new Error(`Failed to fetch page: ${error.message}`);

}

return data;

}

export async function createPage(pageData: Omit<Page, 'id' | 'created_at' | 'updated_at'>): Promise<Page> {

const client = await getSupabaseAdmin();

const { data, error } = await client

.from('pages')

.insert(pageData)

.select()

.single();

if (error) throw new Error(`Failed to create page: ${error.message}`);

return data;

}

```

### ALWAYS Use Upsert for Database Operations

**NEVER execute queries in loops or use Promise.all for individual database operations.**

Use batch operations with `upsert` instead of separate insert/update operations.

```typescript

// ✅ CORRECT: Batch upsert operation

const itemsToUpsert = items.map(item => ({

id: item.id,

name: item.name,

is_published: true,

updated_at: new Date().toISOString(),

}));

await client

.from('table_name')

.upsert(itemsToUpsert, {

onConflict: 'id,is_published', // Composite key

});

// ❌ WRONG: Queries in loops

for (const item of items) {

const existing = await getItemById(item.id);

if (existing) {

await client.from('table_name').update(item).eq('id', item.id);

} else {

await client.from('table_name').insert(item);

}

}

// ❌ WRONG: Promise.all with individual queries

const updates = items.map(item =>

client.from('table_name').update(item).eq('id', item.id)

);

await Promise.all(updates);

```

### Rules

1. **ALWAYS** use `upsert` for insert/update operations

2. **NEVER** execute queries inside loops

3. **NEVER** use `Promise.all` with individual update queries

4. **ALWAYS** batch operations when possible

5. Use `onConflict` parameter to specify composite keys for upsert operations

---

## 🔄 8. API Response Format (Consistency)

### All API Routes MUST Return Consistent Format

Use the `ApiResponse<T>` type from `/types/index.ts`:

```typescript

// ✅ Success response

return NextResponse.json({

data: result

}, { status: 200 });

// ✅ Error response

return NextResponse.json({

error: 'Descriptive error message'

}, { status: 400 });

// ✅ With optional message

return NextResponse.json({

data: result,

message: 'Page published successfully'

}, { status: 200 });

```

### Status Codes

- `200` - Success (GET, PUT)

- `201` - Created (POST)

- `204` - No Content (DELETE)

- `400` - Bad Request (validation errors)

- `404` - Not Found

- `500` - Internal Server Error

---

## ⚠️ 9. Error Handling & Async Operations

### ALWAYS Follow This Pattern

```typescript

// ✅ REQUIRED pattern for ALL async operations

const handleAction = async () => {

try {

setLoading(true);

setError(null); // Clear previous errors

const result = await apiCall();

// Success handling

setData(result);

} catch (error) {

console.error('Context-specific message:', error);

setError(error instanceof Error ? error.message : 'Unknown error occurred');

} finally {

setLoading(false); // Always runs

}

};

```

### In Components with UI State

```typescript

function PageEditor({ pageId }: PageEditorProps) {

const [page, setPage] = useState<Page | null>(null);

const [loading, setLoading] = useState(true);

const [error, setError] = useState<string | null>(null);

useEffect(() => {

const loadPage = async () => {

try {

setLoading(true);

const result = await pagesApi.getById(pageId);

setPage(result.data);

} catch (err) {

setError(err instanceof Error ? err.message : 'Failed to load page');

} finally {

setLoading(false);

}

};

loadPage();

}, [pageId]);

if (loading) return <Spinner />;

if (error) return <ErrorMessage error={error} />;

if (!page) return null;

return <div>{/* Render page */}</div>;

}

```

---

## ⏳ 10. Loading States (MANDATORY)

### Always Show Loading for Async Operations

```typescript

// ✅ CORRECT: Loading state shown

function PageList() {

const [pages, setPages] = useState<Page[]>([]);

const [loading, setLoading] = useState(true);

useEffect(() => {

fetchPages().then(setPages).finally(() => setLoading(false));

}, []);

if (loading) {

return <Spinner />;

}

return <div>{/* Render pages */}</div>;

}

// ❌ WRONG: No loading state

function PageList() {

const [pages, setPages] = useState<Page[]>([]);

useEffect(() => {

fetchPages().then(setPages);

}, []);

return <div>{/* Flashes empty state, then content */}</div>;

}

```

### Use ShadCN Spinner

```typescript

import { Spinner } from '@/components/ui/spinner';

if (loading) return <Spinner />;

if (loading) return (

<div className="flex items-center justify-center p-8">

<Spinner />

</div>

);

```

---

## 🔀 11. Conditional Rendering - Early Returns

### Prefer Early Returns Over Nested Ternaries

```typescript

// ✅ GOOD: Early returns (clean, readable)

function PageEditor({ pageId }: PageEditorProps) {

const { page, loading, error } = usePageData(pageId);

if (loading) {

return <Spinner />;

}

if (error) {

return <ErrorMessage error={error} />;

}

if (!page) {

return <EmptyState message="Page not found" />;

}

return (

<div>

<h1>{page.title}</h1>

{/* Main content */}

</div>

);

}

// ❌ BAD: Nested ternaries (hard to read, hard to maintain)

function PageEditor({ pageId }: PageEditorProps) {

const { page, loading, error } = usePageData(pageId);

return loading ? (

<Spinner />

) : error ? (

<ErrorMessage error={error} />

) : !page ? (

<EmptyState message="Page not found" />

) : (

<div>

<h1>{page.title}</h1>

{/* Main content */}

</div>

);

}

```

### For Simple Conditions

Use inline ternaries for simple show/hide:

```typescript

// ✅ GOOD: Simple inline conditional

<div>

{isVisible && <Notice message="Page is published" />}

{count > 0 ? <Badge>{count}</Badge> : null}

</div>

```

---

## 🎭 12. State Management with Zustand

### Keep Stores Focused and Domain-Specific

```typescript

// ✅ GOOD: Focused store

// stores/useEditorStore.ts

import { create } from 'zustand';

interface EditorState {

selectedLayerId: string | null;

currentPageId: string | null;

isLoading: boolean;

isSaving: boolean;

}

interface EditorActions {

setSelectedLayerId: (id: string | null) => void;

setCurrentPageId: (id: string | null) => void;

setLoading: (value: boolean) => void;

setSaving: (value: boolean) => void;

}

type EditorStore = EditorState & EditorActions;

export const useEditorStore = create<EditorStore>((set) => ({

selectedLayerId: null,

currentPageId: null,

isLoading: false,

isSaving: false,

setSelectedLayerId: (id) => set({ selectedLayerId: id }),

setCurrentPageId: (id) => set({ currentPageId: id }),

setLoading: (value) => set({ isLoading: value }),

setSaving: (value) => set({ isSaving: value }),

}));

```

### Use TypeScript Interfaces for Store Types

Always define separate interfaces for state and actions, then combine them.

---

## ⚡ 13. Performance Optimization

### When to Optimize

1. **Profile First** - Don't optimize prematurely

2. **Use React DevTools Profiler** to identify slow components

3. **Optimize when you see actual performance issues**

### React.memo for Expensive Pure Components

```typescript

// ✅ Use React.memo for pure components that render often

import React, { memo } from 'react';

interface LayerItemProps {

layer: Layer;

onSelect: (id: string) => void;

}

const LayerItem: React.FC<LayerItemProps> = memo(({ layer, onSelect }) => {

return (

<div onClick={() => onSelect(layer.id)}>

{layer.name}

</div>

);

});

```

### useCallback for Functions Passed as Props

```typescript

// ✅ useCallback prevents unnecessary re-renders

function LayersList({ layers }: LayersListProps) {

const handleSelect = useCallback((id: string) => {

console.log('Selected:', id);

}, []); // Empty deps - function never changes

return (

<>

{layers.map(layer => (

<LayerItem key={layer.id} layer={layer} onSelect={handleSelect} />

))}

</>

);

}

```

### useMemo for Expensive Calculations

```typescript

// ✅ useMemo caches expensive computations

function PageEditor({ pageId }: PageEditorProps) {

const { draftsByPageId } = usePagesStore();

// Expensive: traverse tree structure

const layersForCurrentPage = useMemo(() => {

if (!pageId) return [];

const draft = draftsByPageId[pageId];

return draft ? draft.layers : [];

}, [pageId, draftsByPageId]);

return <LayerRenderer layers={layersForCurrentPage} />;

}

```

---

## ♿ 14. Accessibility (A11y)

### Required for All Interactive Elements

```typescript

// ✅ GOOD: Accessible button

<Button

onClick={handleDelete}

aria-label="Delete page"

aria-describedby="delete-hint"

>

<Icon name="trash" />

</Button>

<span id="delete-hint" className="sr-only">

This action cannot be undone

</span>

// ❌ BAD: Not accessible

<div onClick={handleDelete}>

<Icon name="trash" />

</div>

```

### Checklist

- ✅ Use semantic HTML (`<button>` not `<div onClick>`)

- ✅ Include ARIA labels for icon-only buttons

- ✅ Maintain proper heading hierarchy (h1 → h2 → h3)

- ✅ Add alt text for images

- ✅ Ensure keyboard navigation works (Tab, Enter, Esc)

- ✅ Test with screen reader when possible

- ✅ Maintain sufficient color contrast

---

## 📝 15. Comments & Documentation

### When to Comment

```typescript

// ✅ GOOD: Explain WHY, not WHAT

// Use debounce to prevent excessive API calls during typing

const debouncedSearch = useDebounce(searchQuery, 500);

// Edge case: Supabase returns error code PGRST116 for "not found"

if (error && error.code !== 'PGRST116') {

throw error;

}

// TODO: Add pagination after 100 pages - performance degrades with large lists

const pages = await getAllPages();

// ❌ BAD: Obvious comments that repeat the code

// Set loading to true

setLoading(true);

// Loop through pages

pages.forEach(page => {

// ...

});

```

### JSDoc for Public APIs

```typescript

/**

* Recursively finds a layer by ID in a tree structure

* @param layers - Array of layers to search

* @param id - Unique layer ID to find

* @returns The found layer or null if not found

*/

export function findLayerById(layers: Layer[], id: string): Layer | null {

for (const layer of layers) {

if (layer.id === id) return layer;

if (layer.children) {

const found = findLayerById(layer.children, id);

if (found) return found;

}

}

return null;

}

```

---

## 🧹 16. Input Sanitization (MANDATORY for Design Properties)

### ALWAYS Sanitize User Input for Tailwind Classes

Design property inputs (fontSize, width, padding, etc.) MUST be sanitized to prevent invalid Tailwind classes. Spaces break Tailwind syntax.

### Use Centralized Utilities

**Location**: `/lib/utils.ts`

```typescript

import { removeSpaces, sanitizeInput } from '@/lib/utils';

// ✅ CORRECT: Use removeSpaces for Tailwind values

const handleFontSizeChange = (value: string) => {

const sanitized = removeSpaces(value); // "10 rem" → "10rem"

updateDesignProperty('typography', 'fontSize', sanitized || null);

};

// ✅ CORRECT: Use controlled input hook (auto-sanitizes)

const [fontSizeInput, setFontSizeInput] = useControlledInput(fontSize);

// Spaces automatically stripped at input level - never appear in the field

// ❌ WRONG: No sanitization

const handleChange = (value: string) => {

updateDesignProperty('typography', 'fontSize', value); // "10 rem" creates invalid class!

};

```

### useControlledInput Hook

The `useControlledInput` hook automatically sanitizes input values by default:

```typescript

import { useControlledInput } from '@/hooks/use-controlled-input';

// Auto-sanitizes by default (removes spaces)

const [fontSizeInput, setFontSizeInput] = useControlledInput(fontSize);

// Opt-out of sanitization if needed (rare)

const [customInput, setCustomInput] = useControlledInput(value, undefined, false);

```

### Available Sanitization Functions

```typescript

// Quick helper: Remove all spaces

removeSpaces('10 rem') // '10rem'

// Advanced: Custom sanitization

sanitizeInput(' 100px ', {

removeSpaces: false,

trim: true // '100px'

})

sanitizeInput('#FF 00 00', {

removeSpaces: true // '#FF0000'

})

```

### Rules

1. **ALWAYS** use `removeSpaces()` from `@/lib/utils` for design property handlers

2. **NEVER** create duplicate `const sanitize =` helpers in components

3. **USE** `useControlledInput` hook for design property inputs (auto-sanitizes)

4. **IMPORT** from `@/lib/utils`, not inline implementations

### Defense in Depth

We use **two layers** of protection:

1. **Hook Level**: `useControlledInput` strips spaces before they appear in the input field

2. **Handler Level**: `removeSpaces()` ensures spaces don't get saved

### Example: Complete Implementation

```typescript

import { useControlledInput } from '@/hooks/use-controlled-input';

import { removeSpaces } from '@/lib/utils';

import { extractMeasurementValue } from '@/lib/measurement-utils';

export default function TypographyControls({ layer, onLayerUpdate }) {

const { updateDesignProperty, getDesignProperty } = useDesignSync({

layer,

onLayerUpdate,