Rules for Clise Design Canvas

Project Architecture Overview

This is a React-based design canvas application built with TypeScript, using CanvasKit for high-performance rendering. The architecture follows strict single-responsibility principles with atomic state management using Jotai.

Core Technologies & Libraries

React 18 with TypeScript (strict mode)
Jotai for atomic state management
CanvasKit (Google's Skia-based 2D graphics library)
Lucide React for icons
CSS Modules for styling

File Structure & Naming Conventions

Universal File Naming Convention

ALL files must use kebab-case naming (e.g.,

element-atoms.ts

canvaskit-canvas.tsx

cursor-manager.ts

)

Maximum 200 lines of code per file - split files when they exceed this limit
Component files:
```
component-name.tsx
```
Utility files:
```
util-name.ts
```
Type definition files:
```
type-definitions.ts
```
Hook files:
```
use-hook-name.ts
```
or
```
hook-name-hooks.ts
```

Store Architecture (Single Responsibility Modules)

All store files use kebab-case naming and are split by responsibility:

Atoms (state definitions):

```
document-atoms.ts
```
- Document name, tool selection
```
element-atoms.ts
```
- Element storage, CRUD operations, element families
```
selection-atoms.ts
```
- Selection state, box selection coordinates
```
interaction-atoms.ts
```
- Dragging, resizing, drawing, context menu states
```
viewport-atoms.ts
```
- Zoom, pan, canvas/viewport dimensions
```
renderer-atoms.ts
```
- CanvasKit instance, renderer configuration
```
clipboard-atoms.ts
```
- Copy/paste operations
```
derived-atoms.ts
```
- Cross-module derived atoms (to avoid circular imports)

Hooks (state access patterns):

document-hooks.ts

element-hooks.ts

selection-hooks.ts

, etc.

Each hooks file corresponds to its atoms counterpart
```
index.ts
```
re-exports everything for backward compatibility

Canvas Architecture

```
canvaskit-canvas.tsx
```
- Main canvas component using atomic state hooks
```
drawing/CanvasKitRenderer.ts
```
- Pure renderer class, no React state
```
managers/
```
- Utility classes for calculations (no React state)
```
hooks/
```
- Custom canvas-specific hooks
```
utils.ts
```
- Pure utility functions for coordinate transforms, element detection

State Management Patterns

Atomic State Architecture - CRITICAL RULES

NEVER use React state (useState, useReducer, etc.) - ALWAYS use Jotai atoms instead

NEVER use
const [state, setState] = useState()
- use

const [value, setValue] = useAtom(someAtom)

instead

NEVER use
useRef()
for state - use atoms for all application state
Each piece of state has a single-responsibility atom
Use
```
atomFamily
```
for dynamic collections (elements by ID)
Derived atoms for computed values that depend on multiple atoms
If you see React state in existing code, refactor it to use atoms

Element Management

Elements stored in
```
elementAtomFamily(id)
```
for granular updates
```
elementIdsAtom
```
maintains order and existence
```
elementsAtom
```
is a derived atom that combines IDs with element data

Position and style updates use optimized

elementPositionAtomFamily

and

elementStyleAtomFamily

Interaction State Management

Each interaction type has dedicated atoms:

isDraggingAtom

isResizingAtom

isDrawingAtom

isBoxSelectingAtom

Coordinates stored in canvas coordinate system (after
```
screenToCanvas
```
transformation)
Box selection stores start/end in canvas coordinates for consistent rendering

Canvas Rendering Architecture

Coordinate System

Screen Coordinates: Raw mouse/touch coordinates from browser events
Canvas Coordinates: World coordinates after zoom/pan transformation
Transformation Order: DPR scaling → center-origin zoom → pan translation

Key Coordinate Functions

screenToCanvas(clientX, clientY, viewportInfo, transform); // Converts screen → canvas
canvasToScreen(canvasX, canvasY, viewportInfo, transform); // Converts canvas → screen

Center-Origin Zoom Implementation

// In renderer - zoom around canvas center, not top-left
const centerX = dimensions.width / dpr / 2;
const centerY = dimensions.height / dpr / 2;
canvasContext.translate(centerX, centerY);
canvasContext.scale(zoom, zoom);
canvasContext.translate(-centerX, -centerY);

Element System

Element Types

type ElementType = "rect" | "ellipse" | "frame" | "text";
type Tool = "select" | "rect" | "ellipse" | "frame" | "text" | "path";

Element Structure

All elements extend
```
BaseElement
```
with
```
id
```
, position (
```
x
```
,
```
y
```
,
```
w
```
,
```
h
```
), styling, hierarchy
```
TextElement
```
adds
```
text
```
,
```
color
```
,
```
fontSize
```
,
```
fontFamily
```
Frame elements can contain other elements via
```
parentId
```
relationships

Element Operations

CRUD operations via write-only atoms:

addElementAtom

updateElementAtom

deleteElementsAtom

Optimized position-only updates:
```
updateElementPositionAtom
```
Optimized style-only updates:
```
updateElementStyleAtom
```

Reordering via

reorderElementsAtom

with specific operations:

"bring-to-front" | "send-to-back"

etc.

Interaction Patterns

Selection System

Multi-selection with Ctrl/Cmd (toggle) and Shift (extend)
Box selection with real-time visual feedback and element intersection testing
Selection coordinates stored as canvas coordinates, transformed for rendering

Resize System

8-handle resize system:
```
nw
```
,
```
n
```
,
```
ne
```
,
```
w
```
,
```
e
```
,
```
sw
```
,
```
s
```
,
```
se
```
Handle detection with zoom-scaled hit areas
Real-time resize with
```
ResizeManager.calculateResize()
```
Resize cursors:
```
nw-resize
```
,
```
ns-resize
```
,
```
ne-resize
```
,
```
ew-resize
```

Drawing System

Tool-based drawing with atomic state management
Drawing coordinates stored in canvas coordinate system
Real-time preview during drawing operations
Tool automatically switches to "select" after drawing completion

Position calculated to stay within canvas bounds
Coordinates stored relative to canvas container
Operations: copy, paste, duplicate, reorder (bring to front/back, etc.)

Reorder operations use specific parameter structure:

{ elementIds: string[], operation: "bring-to-front" | ... }

Canvas Rendering Rules

CanvasKit Renderer Patterns

Renderer is a pure class with no React dependencies
All transformations applied in specific order: DPR → zoom → pan
Elements rendered with proper z-ordering (frames behind, selection on top)
Box selection rendered in world coordinates (same as elements)

Performance Optimizations

Surface recreation on every render for proper state management
Device pixel ratio handling for high-DPI displays
Atomic updates for fine-grained re-renders
Debounced parent-child relationship updates

TypeScript Conventions

Strict TypeScript Rules

No
```
any
```
types (use proper typing or
```
unknown
```
)
All function parameters and return types explicitly typed
Interface segregation for complex types
Generic constraints for reusable components

Import/Export Patterns

Absolute imports using
```
@store/index
```
path mapping
Re-export patterns through
```
index.ts
```
files for clean APIs
Circular import prevention through
```
derived-atoms.ts
```

Event Handling Patterns

Mouse Event Processing

Get
```
getBoundingClientRect()
```
for coordinate normalization
Create
```
viewportInfo
```
and
```
transform
```
objects
Convert to canvas coordinates using
```
screenToCanvas
```
Process interaction based on current tool and state
Update atomic state through appropriate atoms

Keyboard Shortcuts

Delete/Backspace: Delete selected elements
Ctrl/Cmd+A: Select all elements
Ctrl/Cmd+C: Copy selected elements
Ctrl/Cmd+V: Paste elements
Ctrl/Cmd+D: Duplicate elements
D key: Duplicate elements (without modifier)
Escape: Close context menus
Zoom: Ctrl/Cmd + =/-/0

Testing & Development Patterns

Component Testing Approach

Test atomic state changes independently
Mock CanvasKit for unit tests
Test coordinate transformations with known values
Verify interaction state machines

Debugging Guidelines

Use atomic state inspection via Jotai DevTools
Log coordinate transformations during development
Verify render dependencies in useEffect arrays
Check for state synchronization between atoms

Error Handling

Canvas Errors

Graceful CanvasKit initialization failure handling
Surface creation error recovery
Coordinate transformation boundary checking
Element operation validation

State Consistency

Validate element IDs exist before operations
Check selection state consistency after updates
Ensure parent-child relationship integrity
Handle race conditions in async operations

Performance Guidelines

State Update Optimization

Use atomic updates for fine-grained changes
Batch related state changes when possible
Debounce expensive operations (parent-child updates)
Minimize React re-renders through proper dependency arrays

Rendering Optimization

Cache CanvasKit objects when possible
Use appropriate paint disposal patterns
Minimize canvas state save/restore calls
Optimize hit testing for large element counts

Code Style Guidelines

File Size & Organization

MAXIMUM 200 lines per file - when a file approaches this limit:
- Split into smaller single-responsibility files
- Extract utility functions to separate files
- Create composite hooks to group related functionality
- Move large type definitions to separate type files

Formatting & Structure

Use arrow functions for components and utilities
Prefer
```
const
```
assertions for literal types
Use destructuring for clean parameter extraction
Group related imports with clear separation

Naming Conventions

Files: ALL files must use kebab-case (e.g.,

element-atoms.ts

resize-manager.ts

canvas-component.tsx

)

Atoms:
```
*Atom
```
suffix (e.g.,
```
selectionAtom
```
)
Hooks:
```
use*
```
prefix (e.g.,
```
useSelection
```
)
Managers:
```
*Manager
```
suffix (e.g.,
```
ResizeManager
```
)
Types: PascalCase interfaces and types

Integration Patterns

Hook Usage Patterns

// CORRECT: Always use Jotai atomic hooks - NEVER React state
const [selection, setSelection] = useSelection();
const [isDragging, setIsDragging] = useIsDragging();
const [elements] = useElements();

// WRONG: Never use React state
// const [selection, setSelection] = useState([]); // ❌ FORBIDDEN
// const [isDragging, setIsDragging] = useState(false); // ❌ FORBIDDEN

// Use composite hooks for related operations
const { addElement, updateElement } = useElementOperations();

// Create context for coordinate transformations
const viewportInfo = { x: 0, y: 0, width, height, zoom, rect };
const transform = { zoom, panX: pan.x, panY: pan.y };

Canvas Integration

// Coordinate transformation pattern
const canvasCoords = screenToCanvas(clientX, clientY, viewportInfo, transform);

// Element detection pattern
const clickedElement = getElementAtPoint(canvasCoords, elements);
const resizeHandle = getResizeHandle(canvasCoords, element, zoom);

// Atomic state updates
setIsDragging(true);
setDragStart(canvasCoords);
setSelection([elementId]);

CRITICAL ENFORCEMENT RULES

State Management (STRICTLY ENFORCED)

ZERO TOLERANCE for React state - any
```
useState
```
,
```
useReducer
```
, or
```
useRef
```
for state must be replaced with atoms
Every piece of application state MUST use Jotai atoms
If you see React state in any file, it must be refactored immediately

File Organization (STRICTLY ENFORCED)

ALL files MUST use kebab-case naming - no exceptions
200 lines maximum per file - split files that exceed this limit
Single responsibility per file - one clear purpose per file

Code Review Checklist

Before any code is considered complete, verify:

✅ No React state (useState, useReducer, useRef for state)
✅ All files use kebab-case naming
✅ All files under 200 lines
✅ Single responsibility per file
✅ Proper atomic state patterns
✅ Coordinate transformations use center-origin zoom

Follow these patterns consistently throughout the codebase. When adding new features, maintain the atomic state architecture and single-responsibility principle. Always prefer atomic hooks over local React state, and ensure coordinate transformations are handled correctly for the center-origin zoom system.

Rules for Clise Design Canvas

Project Architecture Overview

Core Technologies & Libraries

React 18 with TypeScript (strict mode)
Jotai for atomic state management
CanvasKit (Google's Skia-based 2D graphics library)
Lucide React for icons
CSS Modules for styling

File Structure & Naming Conventions

Universal File Naming Convention

ALL files must use kebab-case naming (e.g.,

element-atoms.ts

canvaskit-canvas.tsx

cursor-manager.ts

)

Maximum 200 lines of code per file - split files when they exceed this limit
Component files:
```
component-name.tsx
```
Utility files:
```
util-name.ts
```
Type definition files:
```
type-definitions.ts
```
Hook files:
```
use-hook-name.ts
```
or
```
hook-name-hooks.ts
```

Store Architecture (Single Responsibility Modules)

All store files use kebab-case naming and are split by responsibility:

Atoms (state definitions):

```
document-atoms.ts
```
- Document name, tool selection
```
element-atoms.ts
```
- Element storage, CRUD operations, element families
```
selection-atoms.ts
```
- Selection state, box selection coordinates
```
interaction-atoms.ts
```
- Dragging, resizing, drawing, context menu states
```
viewport-atoms.ts
```
- Zoom, pan, canvas/viewport dimensions
```
renderer-atoms.ts
```
- CanvasKit instance, renderer configuration
```
clipboard-atoms.ts
```
- Copy/paste operations
```
derived-atoms.ts
```
- Cross-module derived atoms (to avoid circular imports)

Hooks (state access patterns):

document-hooks.ts

element-hooks.ts

selection-hooks.ts

, etc.

Each hooks file corresponds to its atoms counterpart
```
index.ts
```
re-exports everything for backward compatibility

Canvas Architecture

```
canvaskit-canvas.tsx
```
- Main canvas component using atomic state hooks
```
drawing/CanvasKitRenderer.ts
```
- Pure renderer class, no React state
```
managers/
```
- Utility classes for calculations (no React state)
```
hooks/
```
- Custom canvas-specific hooks
```
utils.ts
```
- Pure utility functions for coordinate transforms, element detection

State Management Patterns

Atomic State Architecture - CRITICAL RULES

NEVER use React state (useState, useReducer, etc.) - ALWAYS use Jotai atoms instead

NEVER use
const [state, setState] = useState()
- use

const [value, setValue] = useAtom(someAtom)

instead

NEVER use
useRef()
for state - use atoms for all application state
Each piece of state has a single-responsibility atom
Use
```
atomFamily
```
for dynamic collections (elements by ID)
Derived atoms for computed values that depend on multiple atoms
If you see React state in existing code, refactor it to use atoms

Element Management

Elements stored in
```
elementAtomFamily(id)
```
for granular updates
```
elementIdsAtom
```
maintains order and existence
```
elementsAtom
```
is a derived atom that combines IDs with element data

Position and style updates use optimized

elementPositionAtomFamily

and

elementStyleAtomFamily

Interaction State Management

Each interaction type has dedicated atoms:

isDraggingAtom

isResizingAtom

isDrawingAtom

isBoxSelectingAtom

Coordinates stored in canvas coordinate system (after
```
screenToCanvas
```
transformation)
Box selection stores start/end in canvas coordinates for consistent rendering

Canvas Rendering Architecture

Coordinate System

Screen Coordinates: Raw mouse/touch coordinates from browser events
Canvas Coordinates: World coordinates after zoom/pan transformation
Transformation Order: DPR scaling → center-origin zoom → pan translation

Key Coordinate Functions

screenToCanvas(clientX, clientY, viewportInfo, transform); // Converts screen → canvas
canvasToScreen(canvasX, canvasY, viewportInfo, transform); // Converts canvas → screen

Center-Origin Zoom Implementation

// In renderer - zoom around canvas center, not top-left
const centerX = dimensions.width / dpr / 2;
const centerY = dimensions.height / dpr / 2;
canvasContext.translate(centerX, centerY);
canvasContext.scale(zoom, zoom);
canvasContext.translate(-centerX, -centerY);

Element System

Element Types

type ElementType = "rect" | "ellipse" | "frame" | "text";
type Tool = "select" | "rect" | "ellipse" | "frame" | "text" | "path";

Element Structure

All elements extend
```
BaseElement
```
with
```
id
```
, position (
```
x
```
,
```
y
```
,
```
w
```
,
```
h
```
), styling, hierarchy
```
TextElement
```
adds
```
text
```
,
```
color
```
,
```
fontSize
```
,
```
fontFamily
```
Frame elements can contain other elements via
```
parentId
```
relationships

Element Operations

CRUD operations via write-only atoms:

addElementAtom

updateElementAtom

deleteElementsAtom

Optimized position-only updates:
```
updateElementPositionAtom
```
Optimized style-only updates:
```
updateElementStyleAtom
```

Reordering via

reorderElementsAtom

with specific operations:

"bring-to-front" | "send-to-back"

etc.

Interaction Patterns

Selection System

Multi-selection with Ctrl/Cmd (toggle) and Shift (extend)
Box selection with real-time visual feedback and element intersection testing
Selection coordinates stored as canvas coordinates, transformed for rendering

Resize System

8-handle resize system:
```
nw
```
,
```
n
```
,
```
ne
```
,
```
w
```
,
```
e
```
,
```
sw
```
,
```
s
```
,
```
se
```
Handle detection with zoom-scaled hit areas
Real-time resize with
```
ResizeManager.calculateResize()
```
Resize cursors:
```
nw-resize
```
,
```
ns-resize
```
,
```
ne-resize
```
,
```
ew-resize
```

Drawing System

Tool-based drawing with atomic state management
Drawing coordinates stored in canvas coordinate system
Real-time preview during drawing operations
Tool automatically switches to "select" after drawing completion

Position calculated to stay within canvas bounds
Coordinates stored relative to canvas container
Operations: copy, paste, duplicate, reorder (bring to front/back, etc.)

Reorder operations use specific parameter structure:

{ elementIds: string[], operation: "bring-to-front" | ... }

Canvas Rendering Rules

CanvasKit Renderer Patterns

Renderer is a pure class with no React dependencies
All transformations applied in specific order: DPR → zoom → pan
Elements rendered with proper z-ordering (frames behind, selection on top)
Box selection rendered in world coordinates (same as elements)

Performance Optimizations

Surface recreation on every render for proper state management
Device pixel ratio handling for high-DPI displays
Atomic updates for fine-grained re-renders
Debounced parent-child relationship updates

TypeScript Conventions

Strict TypeScript Rules

No
```
any
```
types (use proper typing or
```
unknown
```
)
All function parameters and return types explicitly typed
Interface segregation for complex types
Generic constraints for reusable components

Import/Export Patterns

Absolute imports using
```
@store/index
```
path mapping
Re-export patterns through
```
index.ts
```
files for clean APIs
Circular import prevention through
```
derived-atoms.ts
```

Event Handling Patterns

Mouse Event Processing

Get
```
getBoundingClientRect()
```
for coordinate normalization
Create
```
viewportInfo
```
and
```
transform
```
objects
Convert to canvas coordinates using
```
screenToCanvas
```
Process interaction based on current tool and state
Update atomic state through appropriate atoms

Keyboard Shortcuts

Delete/Backspace: Delete selected elements
Ctrl/Cmd+A: Select all elements
Ctrl/Cmd+C: Copy selected elements
Ctrl/Cmd+V: Paste elements
Ctrl/Cmd+D: Duplicate elements
D key: Duplicate elements (without modifier)
Escape: Close context menus
Zoom: Ctrl/Cmd + =/-/0

Testing & Development Patterns

Component Testing Approach

Test atomic state changes independently
Mock CanvasKit for unit tests
Test coordinate transformations with known values
Verify interaction state machines

Debugging Guidelines

Use atomic state inspection via Jotai DevTools
Log coordinate transformations during development
Verify render dependencies in useEffect arrays
Check for state synchronization between atoms

Error Handling

Canvas Errors

Graceful CanvasKit initialization failure handling
Surface creation error recovery
Coordinate transformation boundary checking
Element operation validation

State Consistency

Validate element IDs exist before operations
Check selection state consistency after updates
Ensure parent-child relationship integrity
Handle race conditions in async operations

Performance Guidelines

State Update Optimization

Use atomic updates for fine-grained changes
Batch related state changes when possible
Debounce expensive operations (parent-child updates)
Minimize React re-renders through proper dependency arrays

Rendering Optimization

Cache CanvasKit objects when possible
Use appropriate paint disposal patterns
Minimize canvas state save/restore calls
Optimize hit testing for large element counts

Code Style Guidelines

File Size & Organization

MAXIMUM 200 lines per file - when a file approaches this limit:
- Split into smaller single-responsibility files
- Extract utility functions to separate files
- Create composite hooks to group related functionality
- Move large type definitions to separate type files

Formatting & Structure

Use arrow functions for components and utilities
Prefer
```
const
```
assertions for literal types
Use destructuring for clean parameter extraction
Group related imports with clear separation

Naming Conventions

Files: ALL files must use kebab-case (e.g.,

element-atoms.ts

resize-manager.ts

canvas-component.tsx

)

Atoms:
```
*Atom
```
suffix (e.g.,
```
selectionAtom
```
)
Hooks:
```
use*
```
prefix (e.g.,
```
useSelection
```
)
Managers:
```
*Manager
```
suffix (e.g.,
```
ResizeManager
```
)
Types: PascalCase interfaces and types

Integration Patterns

Hook Usage Patterns

// CORRECT: Always use Jotai atomic hooks - NEVER React state
const [selection, setSelection] = useSelection();
const [isDragging, setIsDragging] = useIsDragging();
const [elements] = useElements();

// WRONG: Never use React state
// const [selection, setSelection] = useState([]); // ❌ FORBIDDEN
// const [isDragging, setIsDragging] = useState(false); // ❌ FORBIDDEN

// Use composite hooks for related operations
const { addElement, updateElement } = useElementOperations();

// Create context for coordinate transformations
const viewportInfo = { x: 0, y: 0, width, height, zoom, rect };
const transform = { zoom, panX: pan.x, panY: pan.y };

Canvas Integration

// Coordinate transformation pattern
const canvasCoords = screenToCanvas(clientX, clientY, viewportInfo, transform);

// Element detection pattern
const clickedElement = getElementAtPoint(canvasCoords, elements);
const resizeHandle = getResizeHandle(canvasCoords, element, zoom);

// Atomic state updates
setIsDragging(true);
setDragStart(canvasCoords);
setSelection([elementId]);

CRITICAL ENFORCEMENT RULES

State Management (STRICTLY ENFORCED)

ZERO TOLERANCE for React state - any
```
useState
```
,
```
useReducer
```
, or
```
useRef
```
for state must be replaced with atoms
Every piece of application state MUST use Jotai atoms
If you see React state in any file, it must be refactored immediately

File Organization (STRICTLY ENFORCED)

ALL files MUST use kebab-case naming - no exceptions
200 lines maximum per file - split files that exceed this limit
Single responsibility per file - one clear purpose per file

Code Review Checklist

Before any code is considered complete, verify:

✅ No React state (useState, useReducer, useRef for state)
✅ All files use kebab-case naming
✅ All files under 200 lines
✅ Single responsibility per file
✅ Proper atomic state patterns
✅ Coordinate transformations use center-origin zoom

Rules for Clise Design Canvas

Related Skills

Markdown Converter

Nano Banana Pro

1password