Copilot instructions

1---
2applyTo: '**'
3---
4# React + Vite + shadcn/ui Template - Premium Design System
5 
6## CRITICAL RULES - READ FIRST
7 
8### NEVER CREATE:
9- **Monolithic components** over 300 lines
10- **Copy-pasted code** - extract to reusable functions/hooks
11- **Inline API calls** in components - use service layer
12- **Poor accessibility** - maintain WCAG 2.1 AA contrast (4.5:1 minimum)
13- **Generic designs** - always adapt to target industry/audience
14 
15### ALWAYS CREATE:
16- **Focused components** (20-100 lines, single responsibility)
17- **Custom hooks** for reusable logic
18- **Composition patterns** - build complex UI from smaller parts
19- **Shared types** in `lib/types.ts` 
20- **Premium designs** with sophisticated animations and visual hierarchy
21 
22## Essential Commands
23```bash
24npm run dev          # Start development server (port 8080)
25npm run build        # Production build  
26npm run lint         # Run ESLint - MUST pass before shipping
27```
28 
29## DETAILED GUIDELINES
30 
31This project uses a modular instruction system. For comprehensive guidance, see:
32 
33- **[Architecture Guidelines](./architecture.instructions.md)** - Component organization, reusability patterns, custom hooks, and code structure
34- **[Design Guidelines](./design.instructions.md)** - Visual design system, industry-specific styling, accessibility, and premium UI patterns
35- **[Development Workflow](./development.instructions.md)** - Commands, configuration, testing, and quality standards
36- **[Component Guidelines](./components.instructions.md)** - UI, common, and feature component patterns
37- **[Hooks Guidelines](./hooks.instructions.md)** - Custom hook patterns for data, forms, and UI state
38- **[Page Guidelines](./pages.instructions.md)** - Page composition and organization rules
39- **[Library Guidelines](./lib.instructions.md)** - Utilities, types, constants, and service layer patterns
40- **[Quality Checklist](./quality.instructions.md)** - Code quality, design standards, and never-ship rules
41 
42## Tech Stack Overview
43 
44### Project Overview
45- **Framework**: React 18.3.1 with TypeScript
46- **Build Tool**: Vite 5.4.1
47- **UI Components**: shadcn/ui (Radix UI primitives)
48- **Styling**: Tailwind CSS with custom theme
49- **Routing**: React Router DOM v6
50- **State Management**: TanStack Query (React Query)
51- **Backend**: Supabase (Authentication, Database, Real-time)
52- **Form Handling**: React Hook Form with Zod validation
53- **Package Manager**: npm
54 
55### Essential Commands
56```bash
57npm run dev          # Start development server (port 8080)
58npm run build        # Production build
59npm run lint         # Run ESLint
60```
61 
62### Key Architecture Rules
631. **No monolithic components** - Keep components under 300 lines
642. **Extract reusable logic** to custom hooks
653. **Use composition patterns** - build complex UI from smaller components
664. **Separate concerns** - UI, business logic, and API calls in different layers
675. **Shared types** - define interfaces once in `lib/types.ts`
68 
69### Design Principles
701. **Industry-appropriate design** - adapt colors and style to target audience
712. **Accessibility first** - maintain WCAG 2.1 AA contrast standards
723. **Premium feel** - sophisticated animations and visual hierarchy
734. **Mobile-first** responsive design approach
74 
75### Project Structure
76```
77src/
78├── components/
79│   ├── ui/              # shadcn/ui components
80│   ├── common/          # Reusable components  
81│   ├── forms/           # Form components
82│   └── features/        # Feature-specific components
83├── hooks/               # Custom React hooks
84├── integrations/
85│   └── supabase/        # Supabase client and types
86│       ├── client.ts    # Supabase client instance
87│       └── types.ts     # Database type definitions
88├── lib/
89│   ├── utils.ts         # Utilities (includes cn function)
90│   ├── types.ts         # Shared TypeScript types
91│   ├── constants.ts     # App constants
92│   └── validations/     # Zod schemas
93├── pages/               # Route components (composition only)
94├── services/            # API calls
95└── context/             # React context providers
96 
97supabase/                # Supabase local development
98├── config.toml          # Supabase CLI configuration
99└── migrations/          # Database migrations (auto-generated)
100```
101 
102## Supabase Integration
103 
104### Quick Start
1051. Create a Supabase project at [supabase.com](https://supabase.com)
1062. Copy `.env.example` to `.env` and add your credentials:
107```bash
108   VITE_SUPABASE_URL=https://your-project.supabase.co
109   VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
110```
1113. Import and use the Supabase client:
112```typescript
113   import { supabase } from "@/integrations/supabase/client";
114```
115 
116### Usage Examples
117 
118**Data Fetching with TanStack Query:**
119```typescript
120import { useQuery } from "@tanstack/react-query";
121import { supabase } from "@/integrations/supabase/client";
122 
123export const usePosts = () => {
124  return useQuery({
125    queryKey: ['posts'],
126    queryFn: async () => {
127      const { data, error } = await supabase
128        .from('posts')
129        .select('*')
130        .eq('published', true);
131      
132      if (error) throw error;
133      return data;
134    }
135  });
136};
137```
138 
139**Mutations:**
140```typescript
141import { useMutation, useQueryClient } from "@tanstack/react-query";
142import { supabase } from "@/integrations/supabase/client";
143 
144export const useCreatePost = () => {
145  const queryClient = useQueryClient();
146  
147  return useMutation({
148    mutationFn: async (newPost) => {
149      const { data, error } = await supabase
150        .from('posts')
151        .insert(newPost)
152        .select()
153        .single();
154      
155      if (error) throw error;
156      return data;
157    },
158    onSuccess: () => {
159      queryClient.invalidateQueries({ queryKey: ['posts'] });
160    }
161  });
162};
163```
164 
165**Authentication:**
166```typescript
167// Sign up
168const { data, error } = await supabase.auth.signUp({
169  email: 'user@example.com',
170  password: 'securepassword'
171});
172 
173// Sign in
174const { data, error } = await supabase.auth.signInWithPassword({
175  email: 'user@example.com',
176  password: 'securepassword'
177});
178 
179// Get current user
180const { data: { user } } = await supabase.auth.getUser();
181```
182 
183**Type Safety:**
184```typescript
185import type { Tables, TablesInsert } from "@/integrations/supabase/types";
186 
187// Use generated types
188type Post = Tables<'posts'>;
189type NewPost = TablesInsert<'posts'>;
190```
191 
192### Best Practices
193- Always use TanStack Query for data fetching and mutations
194- Handle errors gracefully with try-catch or error boundaries
195- Use TypeScript types from `@/integrations/supabase/types`
196- Enable Row Level Security (RLS) on your Supabase tables
197- Never expose sensitive credentials in environment variables
198 
199### Supabase CLI Commands
200```bash
201# Local development (requires Docker)
202npx supabase start              # Start local Supabase
203npx supabase stop               # Stop local Supabase
204 
205# Type generation
206npx supabase gen types typescript --local &gt; src/integrations/supabase/types.ts
207 
208# Migrations
209npx supabase migration new migration_name    # Create new migration
210npx supabase db push                          # Push migrations to remote
211```
212 
213## Security Note
214This is a **client-side application**. Only use `VITE_` environment variables for public configuration. Never expose sensitive data like API secrets.
215 
216## Important Reminders
217- Do what has been asked; nothing more, nothing less
218- NEVER create files unless absolutely necessary
219- ALWAYS prefer editing existing files over creating new ones
220- NEVER proactively create documentation files unless explicitly requested