@clipboard-health/ai-rules 0.2.0 → 0.2.4

package/frontend/AGENTS.md

@@ -0,0 +1,4190 @@
+<!-- Generated by Ruler -->
+
+<!-- Source: .ruler/common/codeStyleAndStructure.md -->
+
+# Code style and structure
+
+- Write concise, technical TypeScript code with accurate examples.
+- Use functional and declarative programming patterns.
+- Prefer iteration and modularization over code duplication.
+- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
+- Structure files: constants, types, exported functions, non-exported functions.
+- Avoid magic strings and numbers; define constants.
+- Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
+- When declaring functions, use the `function` keyword, not `const`.
+- Prefer data immutability.
+
+<!-- Source: .ruler/common/errorHandlingAndValidation.md -->
+
+# Error handling and validation
+
+- Sanitize user input.
+- Handle errors and edge cases at the beginning of functions.
+- Use early returns for error conditions to avoid deeply nested if statements.
+- Place the happy path last in the function for improved readability.
+- Avoid unnecessary else statements; use the if-return pattern instead.
+- Use guard clauses to handle preconditions and invalid states early.
+- Implement proper error logging and user-friendly error messages.
+- Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
+
+<!-- Source: .ruler/common/keyConventions.md -->
+
+# Key conventions
+
+- You are familiar with the latest features and best practices.
+- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
+- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
+- If there might not be a correct answer or do not know the answer, say so instead of guessing.
+
+<!-- Source: .ruler/common/testing.md -->
+
+# Testing
+
+- Follow the Arrange-Act-Assert convention for tests with newlines between each section.
+- Name test variables using the `mockX`, `input`, `expected`, `actual` convention.
+- Aim for high test coverage, writing both positive and negative test cases.
+- Prefer `it.each` for multiple test cases.
+- Avoid conditional logic in tests.
+
+<!-- Source: .ruler/common/typeScript.md -->
+
+# TypeScript usage
+
+- Use strict-mode TypeScript for all code; prefer interfaces over types.
+- Avoid enums; use const maps instead.
+- Strive for precise types. Look for type definitions in the codebase and create your own if none exist.
+- Avoid using type assertions like `as` or `!` unless absolutely necessary.
+- Use the `unknown` type instead of `any` when the type is truly unknown.
+- Use an object to pass multiple function params and to return results.
+- Leverage union types, intersection types, and conditional types for complex type definitions.
+- Use mapped types and utility types (e.g., `Partial<T>`, `Pick<T>`, `Omit<T>`) to transform existing types.
+- Implement generic types to create reusable, flexible type definitions.
+- Utilize the `keyof` operator and index access types for dynamic property access.
+- Implement discriminated unions for type-safe handling of different object shapes where appropriate.
+- Use the `infer` keyword in conditional types for type inference.
+- Leverage `readonly` properties for function parameter immutability.
+- Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
+- Implement exhaustiveness checking using `never`.
+
+<!-- Source: .ruler/frontend/custom-hooks.md -->
+
+# Custom Hook Standards
+
+## Hook Structure
+
+```typescript
+interface UseFeatureOptions {
+  enabled?: boolean;
+  refetchInterval?: number;
+}
+
+export function useFeature(params: Params, options: UseFeatureOptions = {}) {
+  const { enabled = true } = options;
+
+  // Multiple queries/hooks
+  const query1 = useQuery(...);
+  const query2 = useQuery(...);
+
+  // Derived state
+  const computed = useMemo(() => {
+    // Combine data
+    return transformData(query1.data, query2.data);
+  }, [query1.data, query2.data]);
+
+  // Callbacks
+  const handleAction = useCallback(async () => {
+    // Perform action
+  }, [dependencies]);
+
+  // Return structured object
+  return {
+    // Data
+    data: computed,
+
+    // Loading states
+    isLoading: query1.isLoading || query2.isLoading,
+    isError: query1.isError || query2.isError,
+
+    // Actions
+    refetch: async () => {
+      await Promise.all([query1.refetch(), query2.refetch()]);
+    },
+    handleAction,
+  };
+}
+```
+
+## Naming Rules
+
+- **Always** prefix with `use`
+- Boolean hooks: `useIsFeatureEnabled`, `useShouldShowModal`, `useHasPermission`
+- Data hooks: `useGetData`, `useFeatureData`
+- Action hooks: `useBookShift`, `useSubmitForm`
+
+## Return Values
+
+- Return objects (not arrays) for complex hooks
+- Name properties clearly: `isLoading` not `loading`, `refetch` not `refresh`
+- Group related properties together
+
+```typescript
+// Good - clear property names
+return {
+  data,
+  isLoading,
+  isError,
+  refetch,
+};
+
+// Avoid - array destructuring for complex returns
+return [data, isLoading, refetch]; // Only for very simple hooks
+```
+
+## State Management with Constate
+
+For local/shared state management, use **`constate`** to create context with minimal boilerplate:
+
+```typescript
+import constate from "constate";
+import { useState, useCallback } from "react";
+
+// Define your hook with state logic
+function useShiftFilters() {
+  const [filters, setFilters] = useState<Filters>({});
+  const [isLoading, setIsLoading] = useState(false);
+
+  const applyFilters = useCallback((newFilters: Filters) => {
+    setFilters(newFilters);
+  }, []);
+
+  const clearFilters = useCallback(() => {
+    setFilters({});
+  }, []);
+
+  return {
+    filters,
+    isLoading,
+    applyFilters,
+    clearFilters,
+  };
+}
+
+// Create provider and hook with constate
+export const [ShiftFiltersProvider, useShiftFiltersContext] = constate(useShiftFilters);
+```
+
+**Usage:**
+
+```typescript
+// Wrap components that need access
+function ShiftsPage() {
+  return (
+    <ShiftFiltersProvider>
+      <ShiftList />
+      <FilterPanel />
+    </ShiftFiltersProvider>
+  );
+}
+
+// Use in child components
+function ShiftList() {
+  const { filters, applyFilters } = useShiftFiltersContext();
+
+  // Use shared state
+  return <div>{/* ... */}</div>;
+}
+```
+
+**Benefits:**
+
+- Minimal boilerplate compared to raw Context API
+- TypeScript support out of the box
+- Avoids prop drilling
+- Clean separation of state logic
+
+**When to use Constate:**
+
+- Sharing state between multiple sibling components
+- Complex feature-level state (filters, UI state, form state)
+- Alternative to prop drilling
+
+**When NOT to use Constate:**
+
+- Server state (use React Query instead)
+- Global app state (consider if it's truly needed)
+- Simple parent-child communication (use props)
+
+## Boolean Hooks
+
+```typescript
+// Pattern: useIs*, useHas*, useShould*
+export function useIsFeatureEnabled(): boolean {
+  const flags = useFeatureFlags();
+  return flags.includes("new-feature");
+}
+
+export function useHasPermission(permission: string): boolean {
+  const user = useUser();
+  return user.permissions.includes(permission);
+}
+
+export function useShouldShowModal(): boolean {
+  const hasSeenModal = usePreference("hasSeenModal");
+  return !hasSeenModal;
+}
+```
+
+## Data Transformation Hooks
+
+```typescript
+export function useTransformedData() {
+  const { data: rawData, isLoading, isError } = useGetRawData();
+
+  const transformedData = useMemo(() => {
+    if (!rawData) return undefined;
+
+    return rawData.map((item) => ({
+      ...item,
+      displayName: formatName(item),
+    }));
+  }, [rawData]);
+
+  return {
+    data: transformedData,
+    isLoading,
+    isError,
+  };
+}
+```
+
+## Side Effect Hooks
+
+```typescript
+// Hooks that perform side effects (logging, tracking, etc.)
+export function useTrackPageView(pageName: string) {
+  useEffect(() => {
+    logEvent("PAGE_VIEWED", { pageName });
+  }, [pageName]);
+}
+
+// Usage
+export function MyPage() {
+  useTrackPageView("MyPage");
+  // ... rest of component
+}
+```
+
+## Composite Hooks
+
+```typescript
+// Combines multiple hooks and data sources
+export function useWorkerBookingsData() {
+  const worker = useDefinedWorker();
+  const isFeatureEnabled = useIsFeatureEnabled("new-bookings");
+
+  const {
+    data: shifts,
+    isLoading: isLoadingShifts,
+    refetch: refetchShifts,
+  } = useGetShifts(worker.id);
+
+  const {
+    data: invites,
+    isLoading: isLoadingInvites,
+    refetch: refetchInvites,
+  } = useGetInvites(worker.id, { enabled: isFeatureEnabled });
+
+  // Combine data
+  const bookings = useMemo(() => {
+    return [...(shifts ?? []), ...(invites ?? [])].sort(sortByDate);
+  }, [shifts, invites]);
+
+  // Combined loading state
+  const isLoading = isLoadingShifts || isLoadingInvites;
+
+  // Combined refetch
+  async function refreshAllData() {
+    await Promise.all([refetchShifts(), refetchInvites()]);
+  }
+
+  return {
+    // Data
+    bookings,
+
+    // States
+    isLoading,
+    isFeatureEnabled,
+
+    // Actions
+    refreshAllData,
+  };
+}
+```
+
+## Co-location
+
+- Place hooks in `hooks/` folder within feature directory
+- Place API hooks in `api/` folder
+- Keep generic/shared hooks in `lib/` or `utils/`
+
+```text
+FeatureName/
+├── api/
+│   ├── useGetFeature.ts      # API data fetching
+│   └── useUpdateFeature.ts
+├── hooks/
+│   ├── useFeatureLogic.ts    # Business logic hooks
+│   ├── useFeatureState.ts    # Constate state hooks
+│   └── useFeatureFilters.ts
+└── components/
+    └── FeatureComponent.tsx
+```
+
+## Options Pattern
+
+```typescript
+// Always use options object for flexibility
+interface UseFeatureOptions {
+  enabled?: boolean;
+  refetchInterval?: number;
+  onSuccess?: (data: Data) => void;
+}
+
+export function useFeature(params: Params, options: UseFeatureOptions = {}) {
+  const { enabled = true, refetchInterval, onSuccess } = options;
+
+  // Use options in queries
+  return useQuery({
+    enabled,
+    refetchInterval,
+    onSuccess,
+    // ...
+  });
+}
+```
+
+## Hook Dependencies
+
+```typescript
+// Be explicit about dependencies
+export function useFormattedData(rawData: Data[]) {
+  return useMemo(() => {
+    return rawData.map(format);
+  }, [rawData]); // Clear dependency
+}
+
+// Avoid creating functions in dependency arrays
+export function useHandler() {
+  const [value, setValue] = useState();
+
+  // Good - stable reference
+  const handleChange = useCallback((newValue: string) => {
+    setValue(newValue);
+  }, []); // No dependencies on value
+
+  return handleChange;
+}
+```
+
+## Best Practices
+
+- **Prefix with `use`** - Always
+- **Return objects, not arrays** - For hooks with multiple values
+- **Use constate for shared state** - Avoid prop drilling
+- **API hooks in `api/`** - Logic hooks in `hooks/`
+- **Clear property names** - `isLoading`, not `loading`
+- **Options pattern** - For flexible configuration
+- **Explicit dependencies** - In useMemo/useCallback
+
+<!-- Source: .ruler/frontend/data-fetching.md -->
+
+# Data Fetching Standards
+
+## Technology Stack
+
+- **React Query** (@tanstack/react-query) for all API calls
+- **Axios** for HTTP requests
+- **Zod** for response validation
+
+## Core Principles
+
+1. **Use URL and query parameters in query keys** - Makes cache invalidation predictable
+2. **Always use `useGetQuery` hook** - Provides consistent structure, logging, and validation
+3. **Define Zod schemas** for all API requests and responses
+4. **Log errors with centralized constants** - From `APP_V2_APP_EVENTS`, never inline strings
+5. **Rely on React Query state** - Use `isLoading`, `isError`, `isSuccess` - don't reinvent state management
+6. **Use `enabled` for conditional fetching** - With `isDefined()` helper
+7. **Use `invalidateQueries` for disabled queries** - Not `refetch()` which ignores enabled state
+
+## Hook Patterns
+
+### Simple Query
+
+```typescript
+export function useGetUser(userId: string) {
+  return useGetQuery({
+    url: `/api/users/${userId}`,
+    responseSchema: userSchema,
+    enabled: isDefined(userId),
+    staleTime: minutesToMilliseconds(5),
+    meta: {
+      logErrorMessage: APP_V2_APP_EVENTS.GET_USER_FAILURE,
+    },
+  });
+}
+```
+
+### Infinite/Paginated Query
+
+```typescript
+export function usePaginatedShifts(params: Params) {
+  return useInfiniteQuery({
+    queryKey: ["shifts", params],
+    queryFn: async ({ pageParam }) => {
+      const response = await get({
+        url: "/api/shifts",
+        queryParams: { cursor: pageParam, ...params },
+        responseSchema: shiftsResponseSchema,
+      });
+      return response.data;
+    },
+    getNextPageParam: (lastPage) => lastPage.links.nextCursor,
+  });
+}
+```
+
+### Composite Data Fetching
+
+```typescript
+// Hook that combines multiple queries
+export function useWorkerBookingsData() {
+  const { data: shifts, isLoading: isLoadingShifts, refetch: refetchShifts } = useGetShifts();
+  const { data: invites, isLoading: isLoadingInvites, refetch: refetchInvites } = useGetInvites();
+
+  // Combine data
+  const bookings = useMemo(() => {
+    return [...(shifts ?? []), ...(invites ?? [])];
+  }, [shifts, invites]);
+
+  // Combine loading states
+  const isLoading = isLoadingShifts || isLoadingInvites;
+
+  // Combine refetch functions
+  async function refreshAllData() {
+    await Promise.all([refetchShifts(), refetchInvites()]);
+  }
+
+  return {
+    bookings,
+    isLoading,
+    refreshAllData,
+  };
+}
+```
+
+## Error Handling
+
+Always use centralized error constants and handle expected errors gracefully:
+
+```typescript
+useGetQuery({
+  url: "/api/resource",
+  responseSchema: schema,
+  meta: {
+    logErrorMessage: APP_V2_APP_EVENTS.GET_RESOURCE_FAILURE, // ✅ Centralized
+    userErrorMessage: "Failed to load data", // Shows alert to user
+  },
+  useErrorBoundary: (error) => {
+    // Don't show error boundary for 404s (expected errors)
+    return !(axios.isAxiosError(error) && error.response?.status === 404);
+  },
+  retry: (failureCount, error) => {
+    // Don't retry 404s or 401s
+    if (axios.isAxiosError(error)) {
+      const status = error.response?.status;
+      return ![404, 401].includes(status ?? 0);
+    }
+    return failureCount < 3;
+  },
+});
+```
+
+## State Management - Don't Reinvent the Wheel
+
+❌ **Don't** create your own loading/error state:
+
+```typescript
+const [data, setData] = useState();
+const [isLoading, setIsLoading] = useState(false);
+const [error, setError] = useState();
+
+useEffect(() => {
+  async function fetchData() {
+    try {
+      setIsLoading(true);
+      const result = await api.get("/data");
+      setData(result);
+    } catch (err) {
+      setError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  }
+  fetchData();
+}, []);
+```
+
+✅ **Do** use React Query states:
+
+```typescript
+const { data, isLoading, isError, isSuccess } = useGetQuery({...});
+
+if (isLoading) return <Loading />;
+if (isError) return <Error />;
+if (isSuccess) return <div>{data.property}</div>;
+```
+
+## Mutations
+
+```typescript
+export function useCreateDocument() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (data: CreateDocumentRequest) => {
+      return await post({
+        url: "/api/documents",
+        data,
+        responseSchema: documentSchema,
+      });
+    },
+    onSuccess: () => {
+      // Invalidate queries to refetch
+      queryClient.invalidateQueries(["documents"]);
+    },
+    onError: (error) => {
+      logEvent(APP_V2_APP_EVENTS.CREATE_DOCUMENT_FAILURE, { error });
+    },
+  });
+}
+```
+
+## Query Keys
+
+Always include URL and parameters in query keys:
+
+```typescript
+// ❌ Don't use static strings
+useQuery({ queryKey: "users", ... });
+
+// ✅ Do include URL and params
+useQuery({ queryKey: [`/api/users?${status}`, { status }], ... });
+
+// Consistent query key structure
+export const queryKeys = {
+  users: ["users"] as const,
+  user: (id: string) => ["users", id] as const,
+  userShifts: (id: string) => ["users", id, "shifts"] as const,
+};
+
+// Usage
+useQuery({
+  queryKey: queryKeys.user(userId),
+  // ...
+});
+```
+
+## Refetch Intervals
+
+```typescript
+useGetQuery({
+  url: "/api/resource",
+  responseSchema: schema,
+  refetchInterval: (data) => {
+    // Dynamic refetch based on data state
+    if (!data?.isComplete) {
+      return 1000; // Poll every second until complete
+    }
+    return 0; // Stop refetching
+  },
+});
+```
+
+## Conditional Fetching
+
+Use `enabled` option with `isDefined()` helper:
+
+```typescript
+import { isDefined } from "@/lib/utils";
+
+const { data } = useGetQuery({
+  url: "/api/resource",
+  responseSchema: schema,
+  // Only fetch when conditions are met
+  enabled: isDefined(userId) && isFeatureEnabled,
+});
+```
+
+## Refetch vs InvalidateQueries
+
+**Important:** For disabled queries, use `invalidateQueries` instead of `refetch`:
+
+❌ **Don't** use `refetch()` on disabled queries:
+
+```typescript
+const { refetch, data } = useGetQuery({
+  enabled: isDefined(shift.agentId),
+  ...
+});
+
+// Will fetch even if agentId is undefined!
+refetch();
+```
+
+✅ **Do** use `invalidateQueries`:
+
+```typescript
+const queryClient = useQueryClient();
+
+const { data } = useGetQuery({
+  enabled: isDefined(shift.agentId),
+  ...
+});
+
+// Respects the enabled state
+queryClient.invalidateQueries({ queryKey: [myQueryKey] });
+```
+
+## Query Cancellation
+
+```typescript
+export function usePaginatedData() {
+  const queryClient = useQueryClient();
+
+  return useInfiniteQuery({
+    queryKey: ["data"],
+    queryFn: async ({ pageParam }) => {
+      // Cancel previous in-flight requests
+      await queryClient.cancelQueries({ queryKey: ["data"] });
+
+      const response = await get({
+        url: "/api/data",
+        queryParams: { cursor: pageParam },
+      });
+      return response.data;
+    },
+    // ...
+  });
+}
+```
+
+## Naming Conventions
+
+- **useGet\*** - Simple queries: `useGetUser`, `useGetShift`
+- **usePaginated\*** - Infinite queries: `usePaginatedPlacements`
+- **useFetch\*** - Complex fetching logic: `useFetchPaginatedInterviews`
+- **Mutations**: `useCreateDocument`, `useUpdateShift`, `useDeletePlacement`
+
+## Response Transformation
+
+```typescript
+export function useGetUser(userId: string) {
+  return useGetQuery({
+    url: `/api/users/${userId}`,
+    responseSchema: userResponseSchema,
+    select: (data) => {
+      // Transform response data
+      return {
+        ...data,
+        fullName: `${data.firstName} ${data.lastName}`,
+      };
+    },
+  });
+}
+```
+
+## Hook Location
+
+- **API hooks** → Place in `api/` folder within feature directory
+- **One endpoint = one hook** principle
+- Export types inferred from Zod: `export type User = z.infer<typeof userSchema>`
+
+Example:
+
+```text
+Feature/
+├── api/
+│   ├── useGetResource.ts
+│   ├── useCreateResource.ts
+│   └── schemas.ts  (optional)
+```
+
+<!-- Source: .ruler/frontend/error-handling.md -->
+
+# Error Handling Standards
+
+## React Query Error Handling
+
+### Basic Error Configuration
+
+```typescript
+useGetQuery({
+  url: "/api/resource",
+  responseSchema: schema,
+  meta: {
+    logErrorMessage: APP_V2_APP_EVENTS.GET_RESOURCE_FAILURE,
+  },
+  useErrorBoundary: (error) => {
+    // Show error boundary for 500s, not for 404s
+    return !(axios.isAxiosError(error) && error.response?.status === 404);
+  },
+  retry: (failureCount, error) => {
+    // Don't retry 404s or 401s
+    if (axios.isAxiosError(error)) {
+      const status = error.response?.status;
+      return ![404, 401].includes(status ?? 0);
+    }
+    return failureCount < 3;
+  },
+});
+```
+
+### Error Boundary Strategy
+
+- **Show error boundary** for unexpected errors (500s, network failures)
+- **Don't show error boundary** for expected errors (404s, validation errors)
+- Use `useErrorBoundary` to control this behavior
+
+```typescript
+useErrorBoundary: (error) => {
+  // Only show error boundary for server errors
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status;
+    return status !== undefined && status >= 500;
+  }
+  return true; // Show for non-Axios errors
+};
+```
+
+### Retry Configuration
+
+```typescript
+// Don't retry client errors
+retry: (failureCount, error) => {
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status;
+    // Don't retry 4xx errors
+    if (status !== undefined && status >= 400 && status < 500) {
+      return false;
+    }
+  }
+  // Retry server errors up to 3 times
+  return failureCount < 3;
+};
+```
+
+### Exponential Backoff
+
+```typescript
+import { type QueryClient } from "@tanstack/react-query";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 3,
+      retryDelay: (attemptIndex) => {
+        // Exponential backoff: 1s, 2s, 4s
+        return Math.min(1000 * 2 ** attemptIndex, 30000);
+      },
+    },
+  },
+});
+```
+
+## Component Error States
+
+### Pattern: Loading → Error → Success
+
+```typescript
+export function DataComponent() {
+  const { data, isLoading, isError, error, refetch } = useGetData();
+
+  if (isLoading) {
+    return <LoadingState />;
+  }
+
+  if (isError) {
+    return <ErrorState message="Failed to load data" onRetry={refetch} error={error} />;
+  }
+
+  // Happy path
+  return <DataDisplay data={data} />;
+}
+```
+
+### Inline Error Messages
+
+```typescript
+export function FormComponent() {
+  const mutation = useCreateResource();
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {mutation.isError && <Alert severity="error">Failed to save. Please try again.</Alert>}
+
+      <Button type="submit" loading={mutation.isLoading} disabled={mutation.isLoading}>
+        Save
+      </Button>
+    </form>
+  );
+}
+```
+
+### Graceful Degradation
+
+```typescript
+export function OptionalDataComponent() {
+  const { data, isError } = useGetOptionalData();
+
+  // Don't block UI for optional data
+  if (isError) {
+    logError("Failed to load optional data");
+    return null; // or show simplified version
+  }
+
+  if (!data) {
+    return null;
+  }
+
+  return <EnhancedView data={data} />;
+}
+```
+
+## Mutation Error Handling
+
+### onError Callback
+
+```typescript
+export function useCreateDocument() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createDocumentApi,
+    onSuccess: (data) => {
+      queryClient.invalidateQueries(["documents"]);
+      showSuccessToast("Document created");
+    },
+    onError: (error) => {
+      logEvent(APP_V2_APP_EVENTS.CREATE_DOCUMENT_FAILURE, {
+        error: error.message,
+      });
+      showErrorToast("Failed to create document");
+    },
+  });
+}
+```
+
+### Handling Specific Errors
+
+```typescript
+export function useUpdateProfile() {
+  return useMutation({
+    mutationFn: updateProfileApi,
+    onError: (error: AxiosError) => {
+      if (error.response?.status === 409) {
+        showErrorToast("Email already exists");
+      } else if (error.response?.status === 422) {
+        showErrorToast("Invalid data provided");
+      } else {
+        showErrorToast("Failed to update profile");
+      }
+    },
+  });
+}
+```
+
+## Logging and Monitoring
+
+### Event Logging
+
+```typescript
+import { logEvent } from '@/lib/analytics';
+import { APP_EVENTS } from '@/constants/events';
+
+// In query configuration
+meta: {
+  logErrorMessage: APP_V2_APP_EVENTS.GET_SHIFTS_FAILURE,
+}
+
+// In error handlers
+onError: (error) => {
+  logEvent(APP_V2_APP_EVENTS.BOOKING_FAILED, {
+    shiftId,
+    error: error.message,
+    userId: worker.id,
+  });
+}
+```
+
+### Error Context
+
+Always include relevant context when logging errors:
+
+```typescript
+logEvent(APP_V2_APP_EVENTS.API_ERROR, {
+  endpoint: "/api/shifts",
+  method: "GET",
+  statusCode: error.response?.status,
+  errorMessage: error.message,
+  userId: worker.id,
+  timestamp: new Date().toISOString(),
+});
+```
+
+## Validation Errors
+
+### Zod Validation
+
+```typescript
+import { z } from "zod";
+
+const formSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  age: z.number().min(18, "Must be 18 or older"),
+});
+
+try {
+  const validated = formSchema.parse(formData);
+  // Use validated data
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    // Handle validation errors
+    error.errors.forEach((err) => {
+      showFieldError(err.path.join("."), err.message);
+    });
+  }
+}
+```
+
+### API Validation Errors
+
+```typescript
+interface ApiValidationError {
+  field: string;
+  message: string;
+}
+
+function handleApiValidationError(error: AxiosError) {
+  const validationErrors = error.response?.data?.errors as ApiValidationError[];
+
+  if (validationErrors) {
+    validationErrors.forEach(({ field, message }) => {
+      setFieldError(field, message);
+    });
+  }
+}
+```
+
+## Network Errors
+
+### Offline Detection
+
+```typescript
+export function useNetworkStatus() {
+  const [isOnline, setIsOnline] = useState(navigator.onLine);
+
+  useEffect(() => {
+    function handleOnline() {
+      setIsOnline(true);
+    }
+
+    function handleOffline() {
+      setIsOnline(false);
+    }
+
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, []);
+
+  return isOnline;
+}
+```
+
+### Offline UI
+
+```typescript
+export function AppContainer() {
+  const isOnline = useNetworkStatus();
+
+  return (
+    <>
+      {!isOnline && (
+        <Banner severity="warning">You are offline. Some features may not be available.</Banner>
+      )}
+      <App />
+    </>
+  );
+}
+```
+
+## Timeout Handling
+
+### Request Timeouts
+
+```typescript
+import axios from "axios";
+
+const api = axios.create({
+  timeout: 30000, // 30 seconds
+});
+
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.code === "ECONNABORTED") {
+      showErrorToast("Request timed out. Please try again.");
+    }
+    return Promise.reject(error);
+  },
+);
+```
+
+## Error Boundaries
+
+### React Error Boundary
+
+```typescript
+import { Component, type ReactNode } from "react";
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    logEvent("ERROR_BOUNDARY_TRIGGERED", {
+      error: error.message,
+      componentStack: errorInfo.componentStack,
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || <ErrorFallback />;
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Handle Errors
+
+```typescript
+// ❌ Don't ignore errors
+const { data } = useGetData();
+
+// ✅ Handle error states
+const { data, isError, error } = useGetData();
+if (isError) {
+  return <ErrorState error={error} />;
+}
+```
+
+### 2. Provide User-Friendly Messages
+
+```typescript
+// ❌ Show technical errors to users
+<Alert>{error.message}</Alert>
+
+// ✅ Show helpful messages
+<Alert>
+  We couldn't load your shifts. Please check your connection and try again.
+</Alert>
+```
+
+### 3. Log Errors for Debugging
+
+```typescript
+// Always log errors for monitoring
+onError: (error) => {
+  logEvent(APP_V2_APP_EVENTS.ERROR, {
+    context: "shift-booking",
+    error: error.message,
+  });
+  showErrorToast("Booking failed");
+};
+```
+
+### 4. Provide Recovery Actions
+
+```typescript
+// ✅ Give users a way to recover
+<ErrorState message="Failed to load data" onRetry={refetch} onDismiss={() => navigate("/home")} />
+```
+
+### 5. Different Strategies for Different Errors
+
+```typescript
+// Critical errors: Show error boundary
+useErrorBoundary: (error) => isCriticalError(error);
+
+// Expected errors: Show inline message
+if (isError && error.response?.status === 404) {
+  return <NotFoundMessage />;
+}
+
+// Transient errors: Auto-retry with backoff
+retry: (failureCount) => failureCount < 3;
+```
+
+<!-- Source: .ruler/frontend/file-organization.md -->
+
+# File Organization Standards
+
+## Feature-Based Structure
+
+```text
+FeatureName/
+├── api/                          # Data fetching hooks
+│   ├── useGetFeature.ts
+│   ├── useUpdateFeature.ts
+│   └── useDeleteFeature.ts
+├── components/                   # Feature-specific components
+│   ├── FeatureCard.tsx
+│   ├── FeatureList.tsx
+│   └── FeatureHeader.tsx
+├── hooks/                        # Feature-specific hooks (non-API)
+│   ├── useFeatureLogic.ts
+│   └── useFeatureState.ts
+├── utils/                        # Feature utilities
+│   ├── formatFeature.ts
+│   ├── formatFeature.test.ts
+│   └── validateFeature.ts
+├── __tests__/                    # Integration tests (optional)
+│   └── FeatureFlow.test.tsx
+├── Page.tsx                      # Main page component
+├── Router.tsx                    # Feature routes
+├── paths.ts                      # Route paths
+├── types.ts                      # Shared types
+├── constants.ts                  # Constants
+└── README.md                     # Feature documentation (optional)
+```
+
+## File Naming Conventions
+
+### React Components
+
+- **PascalCase** for all React components
+- Examples: `Button.tsx`, `UserProfile.tsx`, `ShiftCard.tsx`
+
+### Avoid Path Stuttering
+
+Don't repeat directory names in file names - the full path provides enough context:
+
+❌ **Bad** - Path stuttering:
+
+```text
+Shift/
+  ShiftInvites/
+    ShiftInviteCard.tsx      // ❌ "Shift" repeated 3 times in path
+    ShiftInviteList.tsx      // ❌ Import: Shift/ShiftInvites/ShiftInviteCard
+```
+
+✅ **Good** - Clean, concise:
+
+```text
+Shift/
+  Invites/
+    Card.tsx                 // ✅ Path: Shift/Invites/Card
+    List.tsx                 // ✅ Import: Shift/Invites/List
+```
+
+**Reasoning:**
+
+- The full path already provides context (`Shift/Invites/Card` is clear)
+- Repeating names makes imports verbose: `import { ShiftInviteCard } from 'Shift/ShiftInvites/ShiftInviteCard'`
+- Shorter names are easier to work with in the editor
+
+### Utilities and Hooks
+
+- **camelCase** for utilities, hooks, and non-component files
+- Examples: `formatDate.ts`, `useAuth.ts`, `calculateTotal.ts`
+
+### Multi-word Non-Components
+
+- **camelCase** for multi-word utility and configuration files
+- Examples: `userProfileUtils.ts`, `apiHelpers.ts`
+
+### Test Files
+
+- Co-locate with source: `Button.test.tsx` next to `Button.tsx`
+- Test folder: `__tests__/` for integration tests
+- Pattern: `*.test.ts` or `*.test.tsx`
+
+### Constants and Types
+
+- `types.ts` - Shared types for the feature
+- `constants.ts` - Feature constants
+- `paths.ts` - Route path constants
+
+## Import Organization
+
+### Import Order
+
+```typescript
+// 1. External dependencies (React, third-party)
+import { useState, useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { parseISO, format } from "date-fns";
+
+// 2. Internal packages (@clipboard-health, @src)
+import { Button } from "@clipboard-health/ui-components";
+import { CbhIcon } from "@clipboard-health/ui-components";
+import { formatDate } from "@src/appV2/lib/dates";
+import { useDefinedWorker } from "@src/appV2/Worker/useDefinedWorker";
+
+// 3. Relative imports (same feature)
+import { useFeatureData } from "./hooks/useFeatureData";
+import { FeatureCard } from "./components/FeatureCard";
+import { FEATURE_PATHS } from "./paths";
+import { type FeatureData } from "./types";
+```
+
+### Import Grouping Rules
+
+- Add blank lines between groups
+- Sort alphabetically within each group (optional but recommended)
+- Group type imports with their module: `import { type User } from './types'`
+
+## Path Management
+
+### Defining Paths
+
+```typescript
+// paths.ts
+import { APP_PATHS } from "@/constants/paths";
+
+export const FEATURE_BASE_PATH = "feature";
+export const FEATURE_FULL_PATH = `${APP_PATHS.APP_V2_HOME}/${FEATURE_BASE_PATH}`;
+export const FEATURE_PATHS = {
+  ROOT: FEATURE_FULL_PATH,
+  DETAILS: `${FEATURE_FULL_PATH}/:id`,
+  EDIT: `${FEATURE_FULL_PATH}/:id/edit`,
+  CREATE: `${FEATURE_FULL_PATH}/create`,
+} as const;
+```
+
+### Using Paths
+
+```typescript
+import { useHistory } from "react-router-dom";
+import { FEATURE_PATHS } from "./paths";
+
+// Navigation
+history.push(FEATURE_PATHS.DETAILS.replace(":id", featureId));
+
+// Route definition
+<Route path={FEATURE_PATHS.DETAILS} component={FeatureDetailsPage} />;
+```
+
+## Types and Interfaces
+
+### Separate vs Co-located Types
+
+```typescript
+// Option 1: Separate types.ts for shared types
+// types.ts
+export interface Feature {
+  id: string;
+  name: string;
+}
+
+export type FeatureStatus = "active" | "inactive";
+
+// Option 2: Co-located with component for component-specific types
+// FeatureCard.tsx
+interface FeatureCardProps {
+  feature: Feature;
+  onSelect: (id: string) => void;
+}
+
+export function FeatureCard(props: FeatureCardProps) {
+  // ...
+}
+```
+
+## Constants
+
+### Defining Constants
+
+```typescript
+// constants.ts
+export const FEATURE_STATUS = {
+  ACTIVE: "active",
+  INACTIVE: "inactive",
+  PENDING: "pending",
+} as const;
+
+export type FeatureStatus = (typeof FEATURE_STATUS)[keyof typeof FEATURE_STATUS];
+
+export const MAX_ITEMS = 100;
+export const DEFAULT_PAGE_SIZE = 20;
+
+export const FEATURE_EVENTS = {
+  VIEWED: "FEATURE_VIEWED",
+  CREATED: "FEATURE_CREATED",
+  UPDATED: "FEATURE_UPDATED",
+} as const;
+```
+
+## Folder Depth Guidelines
+
+- **Maximum 3 levels deep** for feature folders
+- For deeper nesting, consider splitting into separate features
+- Use meaningful folder names that describe the content
+
+```text
+Good:
+├── Shift/
+│   ├── Calendar/
+│   │   └── ShiftCalendarCore.tsx
+│   └── Card/
+│       └── ShiftCard.tsx
+
+Avoid:
+├── Shift/
+│   ├── Components/
+│   │   ├── Display/
+│   │   │   ├── Calendar/
+│   │   │   │   └── Core/
+│   │   │   │       └── ShiftCalendarCore.tsx  # Too deep!
+```
+
+## Module Exports
+
+### Index Files
+
+Avoid using `index.ts` files in the redesign folder. Prefer explicit imports.
+
+```typescript
+// Avoid
+// index.ts
+export * from "./Button";
+export * from "./Card";
+
+// Prefer explicit imports
+import { Button } from "@/components/Button";
+import { Card } from "@/components/Card";
+```
+
+### Named Exports
+
+Always use named exports (not default exports) in redesign code.
+
+```typescript
+// Good
+export function Button(props: ButtonProps) {}
+
+// Avoid
+export default function Button(props: ButtonProps) {}
+```
+
+## API Folder Structure
+
+```text
+api/
+├── useGetFeatures.ts          # GET requests
+├── useCreateFeature.ts        # POST requests
+├── useUpdateFeature.ts        # PUT/PATCH requests
+├── useDeleteFeature.ts        # DELETE requests
+└── schemas.ts                 # Zod schemas (optional)
+```
+
+## Utils Folder Guidelines
+
+- Keep utilities pure functions when possible
+- Co-locate tests with utilities
+- Export individual functions (not as objects)
+
+```typescript
+// Good
+// utils/formatFeatureName.ts
+export function formatFeatureName(name: string): string {
+  return name.trim().toUpperCase();
+}
+
+// utils/formatFeatureName.test.ts
+import { formatFeatureName } from "./formatFeatureName";
+
+describe("formatFeatureName", () => {
+  it("should format name correctly", () => {
+    expect(formatFeatureName("  test  ")).toBe("TEST");
+  });
+});
+```
+
+<!-- Source: .ruler/frontend/imports.md -->
+
+# Import Standards
+
+## Component Wrapper Pattern
+
+Many projects wrap third-party UI library components to add app-specific functionality. This can be enforced via ESLint rules.
+
+## Restricted MUI Imports
+
+### ❌ Component Restrictions (Example)
+
+Some projects restrict direct imports of certain components from `@mui/material`:
+
+```typescript
+// ❌ Forbidden
+import {
+  Avatar,
+  Accordion,
+  AccordionDetails,
+  AccordionSummary,
+  Badge,
+  Button,
+  Card,
+  Chip,
+  Dialog,
+  DialogTitle,
+  Divider,
+  Drawer,
+  FilledInput,
+  Icon,
+  IconButton,
+  InputBase,
+  List,
+  ListItem,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  Modal,
+  OutlinedInput,
+  Rating,
+  Slider,
+  TextField,
+  Typography,
+  Tab,
+  Tabs,
+  SvgIcon,
+} from "@mui/material";
+```
+
+### ✅ Use Internal Wrappers
+
+```typescript
+// ✅ Correct - Use project wrappers
+import { Button } from "@clipboard-health/ui-components/Button";
+import { IconButton } from "@clipboard-health/ui-components/IconButton";
+import { LoadingButton } from "@clipboard-health/ui-components/LoadingButton";
+```
+
+### Rationale
+
+1. Wrappers provide app-specific functionality and consistent behavior
+2. Use `sx` prop for custom styles with theme access
+3. Prefer app-specific dialog components over generic Modal components
+
+## Icon Restrictions
+
+### ❌ Third-Party Icons (Example)
+
+```typescript
+// ❌ Avoid direct imports from icon libraries
+import SearchIcon from "@mui/icons-material/Search";
+import CloseIcon from "@mui/icons-material/Close";
+import AddIcon from "@mui/icons-material/Add";
+```
+
+### ✅ Use Project Icon Component
+
+```typescript
+// ✅ Correct - Use project's icon system
+import { Icon } from '@clipboard-health/ui-components';
+
+<Icon type="search" size="large" />
+<Icon type="close" size="medium" />
+<Icon type="plus" size="small" />
+```
+
+Many projects maintain their own icon system for consistency and customization.
+
+## Allowed MUI Imports
+
+### ✅ Safe to Import from MUI
+
+These components can be imported directly:
+
+```typescript
+import {
+  Box,
+  Stack,
+  Container,
+  Grid,
+  Paper,
+  Skeleton,
+  CircularProgress,
+  LinearProgress,
+  BottomNavigation,
+  BottomNavigationAction,
+  ThemeProvider,
+  useTheme,
+  useMediaQuery,
+} from "@mui/material";
+```
+
+Layout and utility components are generally safe.
+
+## Path Aliases
+
+### Use @ Prefix for Absolute Imports
+
+```typescript
+// ✅ Use path aliases configured in tsconfig
+import { formatDate } from "@/lib/dates";
+import { useUser } from "@/features/user/hooks/useUser";
+import { Button } from "@clipboard-health/ui-components/Button";
+import { theme } from "@/theme";
+
+// ❌ Avoid relative paths to distant folders
+import { formatDate } from "../../../lib/dates";
+```
+
+### Relative Imports for Same Feature
+
+```typescript
+// ✅ Relative imports within the same feature
+import { FeatureCard } from "./components/FeatureCard";
+import { useFeatureData } from "./hooks/useFeatureData";
+import { FEATURE_PATHS } from "./paths";
+import { type FeatureData } from "./types";
+```
+
+## Import Grouping
+
+### Standard Order
+
+```typescript
+// 1. External dependencies (React, third-party libraries)
+import { useState, useEffect, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { parseISO, format } from "date-fns";
+import { z } from "zod";
+
+// 2. Internal absolute imports (via path aliases)
+import { Button, Icon } from "@clipboard-health/ui-components";
+import { theme } from "@/theme";
+import { formatDate } from "@/lib/dates";
+import { useUser } from "@/features/user/hooks/useUser";
+import { APP_PATHS } from "@/constants/paths";
+
+// 3. Relative imports (same feature/module)
+import { useFeatureData } from "./hooks/useFeatureData";
+import { FeatureCard } from "./components/FeatureCard";
+import { FEATURE_PATHS } from "./paths";
+import { type FeatureData, type FeatureOptions } from "./types";
+```
+
+### Blank Lines Between Groups
+
+- Add blank line between each group
+- Helps with readability and organization
+- ESLint/Prettier can auto-format this
+
+## Type Imports
+
+### Inline Type Imports
+
+```typescript
+// ✅ Preferred: Inline type imports
+import { type User, type UserOptions } from "./types";
+import { formatUser } from "./utils";
+```
+
+### Separate Type Imports
+
+```typescript
+// ✅ Also acceptable
+import type { User, UserOptions } from "./types";
+import { formatUser } from "./utils";
+```
+
+## Barrel Exports (index.ts)
+
+### Consider Avoiding Barrel Exports
+
+```typescript
+// ❌ Barrel exports can slow build times
+// index.ts
+export * from "./Button";
+export * from "./Card";
+```
+
+### ✅ Use Explicit Imports
+
+```typescript
+// ✅ Import directly from files for better tree-shaking
+import { Button } from "@clipboard-health/ui-components/Button";
+import { Card } from "@clipboard-health/ui-components/Card";
+```
+
+Note: Barrel exports can cause issues with circular dependencies and slow down builds, especially in large projects.
+
+## Dynamic Imports
+
+### Code Splitting
+
+```typescript
+// For large components or routes
+const HeavyComponent = lazy(() => import("./HeavyComponent"));
+
+// In component
+<Suspense fallback={<Loading />}>
+  <HeavyComponent />
+</Suspense>;
+```
+
+## Common Import Patterns
+
+### API Utilities
+
+```typescript
+import { useQuery } from "@/lib/api/hooks";
+import { api } from "@/lib/api/client";
+```
+
+### React Query
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+```
+
+### Routing
+
+```typescript
+import { useHistory, useLocation, useParams } from "react-router-dom";
+import { type LocationState } from "history";
+```
+
+### Date Utilities
+
+```typescript
+import { parseISO, format, addDays, isBefore } from "date-fns";
+```
+
+### Validation
+
+```typescript
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+```
+
+## ESLint Configuration
+
+Import restrictions can be enforced with ESLint's `no-restricted-imports` rule:
+
+```javascript
+module.exports = {
+  rules: {
+    "no-restricted-imports": [
+      "error",
+      {
+        paths: [
+          {
+            name: "@mui/material",
+            importNames: ["Button", "TextField", "Dialog"],
+            message: "Use wrapper components from @/components",
+          },
+        ],
+        patterns: [
+          {
+            group: ["@mui/icons-material/*"],
+            message: "Use project icon component instead",
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+## Checking for Violations
+
+```bash
+# Lint your code
+npm run lint
+
+# Auto-fix import issues
+npm run lint:fix
+```
+
+## Migration Guide
+
+### When You See Import Errors
+
+1. **Wrapper Component Error**
+   - Check if wrapper exists in `@/components/`
+   - If yes, import from there
+   - If no, discuss with team about creating wrapper
+
+2. **Icon Error**
+   - Find equivalent in project icon system
+   - Use project's icon component
+   - Check available icon names in documentation
+
+3. **Deprecated Pattern Error**
+   - Follow the suggested replacement pattern
+   - Move to modern alternatives (e.g., `sx` prop instead of `styled`)
+
+## Summary
+
+✅ **DO**:
+
+- Use project wrapper components instead of third-party components directly
+- Use project icon system for consistency
+- Use path aliases (e.g., `@/`) for absolute imports
+- Group imports by external, internal, relative
+- Consider avoiding barrel exports for better build performance
+
+❌ **DON'T**:
+
+- Import third-party UI components directly if wrappers exist
+- Import icon libraries directly if project has custom icon system
+- Use deprecated styling patterns (check project guidelines)
+- Use relative imports for distant files
+- Create excessive barrel exports that hurt tree-shaking
+
+<!-- Source: .ruler/frontend/performance.md -->
+
+# Performance Standards
+
+## React Query Optimization
+
+### Stale Time Configuration
+
+```typescript
+// Set appropriate staleTime to avoid unnecessary refetches
+useGetQuery({
+  url: "/api/resource",
+  responseSchema: schema,
+  staleTime: minutesToMilliseconds(5), // Don't refetch for 5 minutes
+  cacheTime: minutesToMilliseconds(30), // Keep in cache for 30 minutes
+});
+```
+
+### Conditional Fetching
+
+```typescript
+// Only fetch when conditions are met
+const { data } = useGetQuery({
+  url: `/api/users/${userId}`,
+  responseSchema: userSchema,
+  enabled: isDefined(userId) && isFeatureEnabled, // Don't fetch until ready
+});
+```
+
+### Query Cancellation
+
+```typescript
+export function usePaginatedData(params: Params) {
+  const queryClient = useQueryClient();
+
+  return useInfiniteQuery({
+    queryKey: ["data", params],
+    queryFn: async ({ pageParam }) => {
+      // Cancel previous in-flight requests
+      await queryClient.cancelQueries({ queryKey: ["data"] });
+
+      const response = await get({
+        url: "/api/data",
+        queryParams: { cursor: pageParam, ...params },
+      });
+      return response.data;
+    },
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+  });
+}
+```
+
+### Prefetching
+
+```typescript
+export function usePreloadNextPage(nextUserId: string) {
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    if (nextUserId) {
+      // Prefetch next page in background
+      queryClient.prefetchQuery({
+        queryKey: ["user", nextUserId],
+        queryFn: () => fetchUser(nextUserId),
+        staleTime: minutesToMilliseconds(5),
+      });
+    }
+  }, [nextUserId, queryClient]);
+}
+```
+
+## React Optimization
+
+### useMemo for Expensive Computations
+
+```typescript
+export function DataList({ items }: { items: Item[] }) {
+  // Memoize expensive sorting/filtering
+  const sortedItems = useMemo(() => {
+    return items.filter((item) => item.isActive).sort((a, b) => a.priority - b.priority);
+  }, [items]);
+
+  return <List items={sortedItems} />;
+}
+```
+
+### useCallback for Event Handlers
+
+```typescript
+export function ParentComponent() {
+  const [selected, setSelected] = useState<string>();
+
+  // Memoize callback to prevent child re-renders
+  const handleSelect = useCallback((id: string) => {
+    setSelected(id);
+    logEvent("ITEM_SELECTED", { id });
+  }, []); // Stable reference
+
+  return <ChildComponent onSelect={handleSelect} />;
+}
+```
+
+### React.memo for Pure Components
+
+```typescript
+import { memo } from "react";
+
+interface ItemCardProps {
+  item: Item;
+  onSelect: (id: string) => void;
+}
+
+// Memoize component to prevent unnecessary re-renders
+export const ItemCard = memo(function ItemCard({ item, onSelect }: ItemCardProps) {
+  return (
+    <Card onClick={() => onSelect(item.id)}>
+      <h3>{item.name}</h3>
+    </Card>
+  );
+});
+```
+
+### Avoid Inline Object/Array Creation
+
+```typescript
+// ❌ Creates new object on every render
+<Component style={{ padding: 8 }} />
+<Component items={[1, 2, 3]} />
+
+// ✅ Define outside or use useMemo
+const style = { padding: 8 };
+const items = [1, 2, 3];
+<Component style={style} items={items} />
+
+// ✅ Or use useMemo for dynamic values
+const style = useMemo(() => ({ padding: spacing }), [spacing]);
+```
+
+## List Rendering
+
+### Key Prop for Lists
+
+```typescript
+// ✅ Use stable, unique keys
+items.map((item) => <ItemCard key={item.id} item={item} />);
+
+// ❌ Don't use index as key (unless list never changes)
+items.map((item, index) => <ItemCard key={index} item={item} />);
+```
+
+### Virtualization for Long Lists
+
+```typescript
+import { FixedSizeList } from "react-window";
+
+export function VirtualizedList({ items }: { items: Item[] }) {
+  return (
+    <FixedSizeList height={600} itemCount={items.length} itemSize={80} width="100%">
+      {({ index, style }) => (
+        <div style={style}>
+          <ItemCard item={items[index]} />
+        </div>
+      )}
+    </FixedSizeList>
+  );
+}
+```
+
+### Pagination Instead of Infinite Data
+
+```typescript
+// For large datasets, use pagination
+export function PaginatedList() {
+  const [page, setPage] = useState(1);
+  const pageSize = 20;
+
+  const { data, isLoading } = useGetPaginatedData({
+    page,
+    pageSize,
+  });
+
+  return (
+    <>
+      <List items={data?.items} />
+      <Pagination page={page} total={data?.total} pageSize={pageSize} onChange={setPage} />
+    </>
+  );
+}
+```
+
+## Data Fetching Patterns
+
+### Parallel Queries
+
+```typescript
+export function useParallelData() {
+  // Fetch in parallel
+  const users = useGetUsers();
+  const shifts = useGetShifts();
+  const workplaces = useGetWorkplaces();
+
+  // All queries run simultaneously
+  const isLoading = users.isLoading || shifts.isLoading || workplaces.isLoading;
+
+  return {
+    users: users.data,
+    shifts: shifts.data,
+    workplaces: workplaces.data,
+    isLoading,
+  };
+}
+```
+
+### Dependent Queries
+
+```typescript
+export function useDependentData(userId?: string) {
+  // First query
+  const { data: user } = useGetUser(userId, {
+    enabled: isDefined(userId),
+  });
+
+  // Second query depends on first
+  const { data: shifts } = useGetUserShifts(user?.id, {
+    enabled: isDefined(user?.id), // Only fetch when user is loaded
+  });
+
+  return { user, shifts };
+}
+```
+
+### Debouncing Search Queries
+
+```typescript
+import { useDebouncedValue } from "@/lib/hooks";
+
+export function SearchComponent() {
+  const [searchTerm, setSearchTerm] = useState("");
+  const debouncedSearch = useDebouncedValue(searchTerm, 300);
+
+  const { data } = useSearchQuery(debouncedSearch, {
+    enabled: debouncedSearch.length > 2,
+  });
+
+  return (
+    <>
+      <input value={searchTerm} onChange={(e) => setSearchTerm(e.target.value)} />
+      <Results data={data} />
+    </>
+  );
+}
+```
+
+## Code Splitting
+
+### Route-Based Splitting
+
+```typescript
+import { lazy, Suspense } from "react";
+
+// Lazy load route components
+const ShiftDetailsPage = lazy(() => import("./Shift/DetailsPage"));
+const ProfilePage = lazy(() => import("./Profile/Page"));
+
+export function Router() {
+  return (
+    <Suspense fallback={<LoadingScreen />}>
+      <Routes>
+        <Route path="/shifts/:id" element={<ShiftDetailsPage />} />
+        <Route path="/profile" element={<ProfilePage />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+### Component-Based Splitting
+
+```typescript
+// Split large components that aren't immediately needed
+const HeavyChart = lazy(() => import("./HeavyChart"));
+
+export function Dashboard() {
+  const [showChart, setShowChart] = useState(false);
+
+  return (
+    <div>
+      <Summary />
+      {showChart && (
+        <Suspense fallback={<ChartSkeleton />}>
+          <HeavyChart />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+## Image Optimization
+
+### Lazy Loading Images
+
+```typescript
+<img
+  src={imageUrl}
+  alt={alt}
+  loading="lazy" // Native lazy loading
+/>
+```
+
+### Responsive Images
+
+```typescript
+<img
+  srcSet={`
+    ${image_small} 480w,
+    ${image_medium} 800w,
+    ${image_large} 1200w
+  `}
+  sizes="(max-width: 480px) 480px, (max-width: 800px) 800px, 1200px"
+  src={image_medium}
+  alt={alt}
+/>
+```
+
+## State Management
+
+### Avoid Prop Drilling
+
+```typescript
+// ❌ Prop drilling
+<Parent>
+  <Child data={data}>
+    <GrandChild data={data}>
+      <GreatGrandChild data={data} />
+    </GrandChild>
+  </Child>
+</Parent>;
+
+// ✅ Use context for deeply nested data
+const DataContext = createContext<Data | undefined>(undefined);
+
+<DataContext.Provider value={data}>
+  <Parent>
+    <Child>
+      <GrandChild>
+        <GreatGrandChild />
+      </GrandChild>
+    </Child>
+  </Parent>
+</DataContext.Provider>;
+```
+
+### Local State Over Global State
+
+```typescript
+// ✅ Keep state as local as possible
+export function FormComponent() {
+  const [formData, setFormData] = useState({}); // Local state
+  // Only lift state up when needed by multiple components
+}
+```
+
+## Bundle Size Optimization
+
+### Tree Shaking
+
+```typescript
+// ✅ Import only what you need
+import { format } from "date-fns";
+
+// ❌ Imports entire library
+import * as dateFns from "date-fns";
+```
+
+### Avoid Large Dependencies
+
+```typescript
+// Check bundle size before adding dependencies
+// Use lighter alternatives when possible
+
+// ❌ Heavy library for simple task
+import moment from "moment";
+
+// ✅ Lighter alternative
+import { format } from "date-fns";
+```
+
+## Monitoring Performance
+
+### React DevTools Profiler
+
+```typescript
+// Wrap components to profile
+<Profiler id="ShiftList" onRender={onRenderCallback}>
+  <ShiftList />
+</Profiler>
+```
+
+### Web Vitals
+
+```typescript
+import { getCLS, getFID, getFCP, getLCP, getTTFB } from "web-vitals";
+
+// Track Core Web Vitals
+getCLS(console.log);
+getFID(console.log);
+getFCP(console.log);
+getLCP(console.log);
+getTTFB(console.log);
+```
+
+## Best Practices Summary
+
+### ✅ DO
+
+- Set appropriate `staleTime` and `cacheTime` for queries
+- Use `useMemo` for expensive computations
+- Use `useCallback` for callbacks passed to children
+- Use React.memo for pure components
+- Virtualize long lists
+- Lazy load routes and heavy components
+- Use pagination for large datasets
+- Debounce search inputs
+- Cancel queries when component unmounts
+- Prefetch data when predictable
+
+### ❌ DON'T
+
+- Fetch data unnecessarily
+- Create objects/arrays inline in props
+- Use index as key for dynamic lists
+- Render all items in very long lists
+- Import entire libraries when only need parts
+- Keep all state global
+- Ignore performance warnings in console
+- Skip memoization for expensive operations
+
+<!-- Source: .ruler/frontend/react-patterns.md -->
+
+# React Component Patterns
+
+## Core Principles
+
+- **Storybook is the single source of truth** for UI components, not Figma
+- **Named exports only** (prefer named exports over default exports)
+- **Explicit types** for all props and return values
+- **Handle all states**: loading, error, empty, success
+- **Composition over configuration** - prefer children over complex props
+
+## Component Structure
+
+Follow this consistent structure for all components:
+
+```typescript
+// 1. Imports (grouped with blank lines between groups)
+import { useState, useMemo, useCallback } from "react";
+import { Box, Typography } from "@mui/material";
+
+import { useGetUser } from "@/api/hooks/useGetUser";
+import { formatDate } from "@/utils/date";
+
+import { ChildComponent } from "./ChildComponent";
+
+// 2. Types (interfaces for props, types for unions)
+interface UserCardProps {
+  userId: string;
+  onAction: (action: string) => void;
+  isHighlighted?: boolean;
+}
+
+// 3. Component definition
+export function UserCard({ userId, onAction, isHighlighted = false }: UserCardProps) {
+  // A. React Query hooks first
+  const { data: user, isLoading, isError } = useGetUser(userId);
+
+  // B. Local state
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  // C. Derived values (with useMemo for expensive computations)
+  const displayName = useMemo(
+    () => (user ? `${user.firstName} ${user.lastName}` : "Unknown"),
+    [user]
+  );
+
+  // D. Event handlers (with useCallback when passed to children)
+  const handleToggle = useCallback(() => {
+    setIsExpanded((prev) => !prev);
+    onAction("toggle");
+  }, [onAction]);
+
+  // E. Early returns for loading/error states
+  if (isLoading) return <LoadingState />;
+  if (isError) return <ErrorState message="Failed to load user" />;
+  if (!user) return <EmptyState message="User not found" />;
+
+  // F. Render
+  return (
+    <Box sx={{ padding: 2, backgroundColor: isHighlighted ? "primary.light" : "background.paper" }}>
+      <Typography variant="h6">{displayName}</Typography>
+      <ChildComponent onClick={handleToggle} />
+    </Box>
+  );
+}
+```
+
+## Why This Structure?
+
+1. **Imports grouped** - Easy to see dependencies
+2. **Types first** - Documents component API
+3. **Hooks at top** - React rules of hooks
+4. **Derived values next** - Shows data flow
+5. **Handlers together** - Easy to find event logic
+6. **Early returns** - Fail fast, reduce nesting
+7. **Render last** - Main component logic
+
+## Component Naming
+
+- **PascalCase** for components: `UserProfile`, `DataCard`
+- **camelCase** for hooks and utilities: `useUserData`, `formatDate`
+- Prefer named exports over default exports for better refactoring support
+
+## Props
+
+- Always define explicit prop types
+- Use destructuring with types
+- Avoid prop spreading unless wrapping a component
+
+```typescript
+// Good
+interface ButtonProps {
+  onClick: () => void;
+  label: string;
+  disabled?: boolean;
+}
+
+export function Button({ onClick, label, disabled = false }: ButtonProps) {
+  return (
+    <button onClick={onClick} disabled={disabled}>
+      {label}
+    </button>
+  );
+}
+
+// Acceptable for wrappers
+export function CustomButton(props: ButtonProps) {
+  return <ButtonBase {...props} LinkComponent={InternalLink} />;
+}
+```
+
+## Wrappers
+
+- Wrap third-party components to add app-specific functionality
+- Example: Wrapping a third-party Button with custom link handling
+
+```typescript
+import {
+  Button as ButtonBase,
+  type ButtonProps as ButtonPropsBase,
+} from "@some-ui-library/components";
+import { type LocationState } from "history";
+
+import { InternalLink } from "./InternalLink";
+
+interface ButtonProps extends Omit<ButtonPropsBase, "LinkComponent"> {
+  locationState?: LocationState;
+}
+
+export function Button(props: ButtonProps) {
+  return <ButtonBase {...props} LinkComponent={InternalLink} />;
+}
+```
+
+## State Management
+
+- Use `useState` for local component state
+- Use `useMemo` for expensive computations
+- Use `useCallback` for functions passed to children
+- Lift state up when needed by multiple components
+
+## Conditional Rendering
+
+```typescript
+// Early returns for loading/error states
+if (isLoading) return <LoadingState />;
+if (isError) return <ErrorState />;
+
+// Ternary for simple conditions
+return isActive ? <ActiveView /> : <InactiveView />;
+
+// && for conditional rendering
+return <div>{hasData && <DataDisplay data={data} />}</div>;
+```
+
+## Component Composition
+
+Prefer composition over complex props. Build small, focused components that compose together.
+
+```typescript
+// ✅ Good - Composition pattern
+interface CardProps {
+  children: ReactNode;
+}
+
+export function Card({ children }: CardProps) {
+  return <Box sx={{ padding: 3, borderRadius: 2, boxShadow: 1 }}>{children}</Box>;
+}
+
+export function CardHeader({ children }: { children: ReactNode }) {
+  return (
+    <Box sx={{ marginBottom: 2 }}>
+      <Typography variant="h6">{children}</Typography>
+    </Box>
+  );
+}
+
+export function CardContent({ children }: { children: ReactNode }) {
+  return <Box>{children}</Box>;
+}
+
+// Usage - Flexible and composable
+<Card>
+  <CardHeader>User Profile</CardHeader>
+  <CardContent>
+    <UserDetails user={user} />
+    <UserActions onEdit={handleEdit} />
+  </CardContent>
+</Card>;
+
+// ❌ Bad - Complex props that limit flexibility
+interface ComplexCardProps {
+  title: string;
+  subtitle?: string;
+  actions?: ReactNode;
+  content: ReactNode;
+  variant?: "default" | "highlighted" | "error";
+  showBorder?: boolean;
+  elevation?: number;
+}
+
+export function ComplexCard(props: ComplexCardProps) {
+  // Too many props, hard to extend
+  // ...
+}
+```
+
+## Children Patterns
+
+### Render Props Pattern
+
+Use when child components need access to parent state:
+
+```typescript
+interface DataProviderProps {
+  children: (data: Data, isLoading: boolean) => ReactNode;
+}
+
+export function DataProvider({ children }: DataProviderProps) {
+  const { data, isLoading } = useGetData();
+
+  return <>{children(data, isLoading)}</>;
+}
+
+// Usage
+<DataProvider>
+  {(data, isLoading) => (isLoading ? <Loading /> : <DataDisplay data={data} />)}
+</DataProvider>;
+```
+
+### Compound Components Pattern
+
+For components that work together:
+
+```typescript
+interface TabsContextValue {
+  activeTab: string;
+  setActiveTab: (tab: string) => void;
+}
+
+const TabsContext = createContext<TabsContextValue | undefined>(undefined);
+
+export function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
+  const [activeTab, setActiveTab] = useState(defaultTab);
+
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      <Box>{children}</Box>
+    </TabsContext.Provider>
+  );
+}
+
+export function TabList({ children }: { children: ReactNode }) {
+  return <Box sx={{ display: "flex", gap: 1 }}>{children}</Box>;
+}
+
+export function Tab({ value, children }: { value: string; children: ReactNode }) {
+  const context = useContext(TabsContext);
+  if (!context) throw new Error("Tab must be used within Tabs");
+
+  const { activeTab, setActiveTab } = context;
+  const isActive = activeTab === value;
+
+  return (
+    <Button onClick={() => setActiveTab(value)} variant={isActive ? "contained" : "text"}>
+      {children}
+    </Button>
+  );
+}
+
+export function TabPanel({ value, children }: { value: string; children: ReactNode }) {
+  const context = useContext(TabsContext);
+  if (!context) throw new Error("TabPanel must be used within Tabs");
+
+  if (context.activeTab !== value) return null;
+  return <Box sx={{ padding: 2 }}>{children}</Box>;
+}
+
+// Usage - Intuitive API
+<Tabs defaultTab="profile">
+  <TabList>
+    <Tab value="profile">Profile</Tab>
+    <Tab value="settings">Settings</Tab>
+  </TabList>
+  <TabPanel value="profile">
+    <ProfileContent />
+  </TabPanel>
+  <TabPanel value="settings">
+    <SettingsContent />
+  </TabPanel>
+</Tabs>;
+```
+
+## Error Boundaries
+
+Use error boundaries for graceful error handling:
+
+```typescript
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error("Error caught by boundary:", error, errorInfo);
+    // Log to error tracking service
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || <ErrorFallback error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+}
+
+// Usage
+<ErrorBoundary fallback={<ErrorPage />}>
+  <App />
+</ErrorBoundary>;
+```
+
+## Handling Lists
+
+### Key Props
+
+Always use stable, unique keys (never index):
+
+```typescript
+// ✅ Good - Unique, stable ID
+{
+  users.map((user) => <UserCard key={user.id} user={user} />);
+}
+
+// ❌ Bad - Index as key (causes bugs when list changes)
+{
+  users.map((user, index) => <UserCard key={index} user={user} />);
+}
+
+// ✅ Acceptable - Composite key when no ID available
+{
+  items.map((item) => <ItemCard key={`${item.type}-${item.name}`} item={item} />);
+}
+```
+
+### Empty States
+
+Always handle empty lists:
+
+```typescript
+export function UserList({ users }: { users: User[] }) {
+  if (users.length === 0) {
+    return (
+      <EmptyState
+        icon={<PersonIcon />}
+        title="No users found"
+        description="Try adjusting your search criteria"
+      />
+    );
+  }
+
+  return (
+    <Box>
+      {users.map((user) => (
+        <UserCard key={user.id} user={user} />
+      ))}
+    </Box>
+  );
+}
+```
+
+## Conditional Rendering Best Practices
+
+```typescript
+export function ItemCard({ item }: { item: Item }) {
+  // ✅ Good - Early returns for invalid states
+  if (!item) return null;
+  if (item.isDeleted) return null;
+
+  // ✅ Good - Ternary for simple either/or
+  const statusColor = item.isUrgent ? "error" : "default";
+
+  return (
+    <Box>
+      <Typography color={statusColor}>{item.title}</Typography>
+
+      {/* ✅ Good - && for optional elements */}
+      {item.isFeatured && <FeaturedBadge />}
+
+      {/* ✅ Good - Ternary for alternate content */}
+      {item.isAvailable ? <AvailableStatus /> : <UnavailableStatus />}
+
+      {/* ❌ Bad - Nested ternaries (hard to read) */}
+      {item.status === "urgent" ? (
+        <UrgentBadge />
+      ) : item.status === "normal" ? (
+        <NormalBadge />
+      ) : (
+        <DefaultBadge />
+      )}
+
+      {/* ✅ Good - Extract to variable or switch */}
+      <StatusBadge status={item.status} />
+    </Box>
+  );
+}
+```
+
+## Performance Optimization
+
+### When to Use `useMemo`
+
+```typescript
+// ✅ Do - Expensive computation
+const sortedUsers = useMemo(() => [...users].sort((a, b) => a.name.localeCompare(b.name)), [users]);
+
+// ❌ Don't - Simple operations (premature optimization)
+const fullName = useMemo(() => `${firstName} ${lastName}`, [firstName, lastName]);
+```
+
+### When to Use `useCallback`
+
+```typescript
+// ✅ Do - Function passed to memoized child
+const MemoizedChild = React.memo(ChildComponent);
+
+function Parent() {
+  const handleClick = useCallback(() => {
+    console.log("clicked");
+  }, []);
+
+  return <MemoizedChild onClick={handleClick} />;
+}
+
+// ❌ Don't - Function not passed to children
+const handleSubmit = useCallback(() => {
+  // No child components use this
+}, []);
+```
+
+<!-- Source: .ruler/frontend/react.md -->
+
+# React
+
+- Destructure props in function body rather than in function signature
+- Prefer inline JSX rather than extracting variables and functions as variables outside of JSX
+- Use useModalState for any showing/hiding functionality like dialogs
+- Utilize custom hooks to encapsulate and reuse stateful logic
+- When performing data-fetching in a custom hook, always use Zod to define any request and response schemas
+- Use react-hook-form for all form UIs and use zod resolver for form schema validation
+- Use date-fns for any Date based operations like formatting
+
+<!-- Source: .ruler/frontend/styling.md -->
+
+# Styling Standards
+
+## Technology Stack
+
+- **Material UI (MUI)** with custom theme
+- **sx prop** for custom styles (NOT `styled()`)
+- Custom component wrappers for consistent UI
+- **Storybook** as single source of truth for UI components
+
+## Core Principles
+
+1. **Always use `sx` prop** - Never CSS/SCSS/SASS files
+2. **Use theme tokens** - Never hardcode colors, spacing, or sizes
+3. **Leverage meaningful tokens** - Use semantic names like `theme.palette.text.primary`, not `common.white`
+4. **Type-safe theme access** - Use `sx={(theme) => ({...})}`, not string paths like `"text.secondary"`
+5. **Follow spacing system** - Use indices 1-12 (4px-64px)
+6. **Storybook is source of truth** - Check Storybook before Figma
+
+## Restricted Patterns
+
+### ❌ DO NOT USE
+
+- `styled()` from MUI (deprecated in our codebase)
+- `makeStyles()` from MUI (deprecated)
+- CSS/SCSS/SASS files
+- Direct MUI icons from `@mui/icons-material`
+- Direct MUI components without wrappers (except layout primitives; see list below)
+- Inline styles via `style` prop (use `sx` instead)
+- String paths for theme tokens (not type-safe)
+
+### Rationale
+
+1. Component wrappers provide consistent behavior and app-specific functionality
+2. `sx` prop provides type-safe access to theme tokens
+3. Project-specific dialog components ensure consistent UX patterns
+
+## Storybook as Source of Truth
+
+**Important:** Storybook reflects what's actually implemented, not Figma designs.
+
+### When Storybook Differs from Figma
+
+1. **Check Storybook first** - It shows real, implemented components
+2. **Use closest existing variant** - Don't create one-off font sizes/colors
+3. **Confirm changes are intentional** - Consult with team before updating components
+4. **Create follow-up ticket** - If component needs updating but you're short on time
+5. **Make changes system-wide** - Component updates should benefit entire app
+
+### Process
+
+- **Minor differences** (font sizes, colors) → Stick to Storybook
+- **Component looks different** → Confirm with team, update component intentionally
+- **Missing component** → Check with team - it may exist with a different name
+
+## Use Internal Components
+
+### ✅ ALWAYS USE Project Wrappers
+
+Instead of importing directly from `@mui/material`, use project wrappers:
+
+```typescript
+// ❌ Don't
+import { Button, IconButton } from "@mui/material";
+
+// ✅ Do
+import { Button } from "@/components/Button";
+import { IconButton } from "@clipboard-health/ui-components";
+```
+
+### Component Wrapper List (Example)
+
+Common components that may have wrappers:
+
+- `Button`, `LoadingButton`, `IconButton`
+- `Avatar`, `Accordion`, `Badge`
+- `Card`, `Chip`, `Dialog`
+- `Drawer`, `List`, `ListItem`
+- `Rating`, `Slider`, `Switch`
+- `TextField`, `Typography`, `Tab`, `Tabs`
+
+Check your project's ESLint configuration for the full list.
+
+## Icons
+
+### Use Project Icon Component
+
+```typescript
+// ❌ Don't use third-party icons directly
+import SearchIcon from '@mui/icons-material/Search';
+
+// ✅ Use project's icon system
+import { CbhIcon } from '@clipboard-health/ui-components';
+
+<CbhIcon type="search" size="large" />
+<CbhIcon type="search-colored" size="medium" />
+```
+
+### Icon Variants
+
+- Many icon systems have variants for different states (e.g., `-colored` for active states)
+- Check your project's icon documentation for available variants
+
+## Styling with sx Prop
+
+### Basic Usage - Type-Safe Theme Access
+
+❌ **Never** hardcode values or use string paths:
+
+```typescript
+<Box
+  sx={{
+    backgroundColor: "red", // ❌ Raw color
+    color: "#ADFF11", // ❌ Hex code
+    padding: "16px", // ❌ Raw size
+    color: "text.secondary", // ❌ String path (no TypeScript support)
+  }}
+/>
+```
+
+✅ **Always** use theme with type safety:
+
+```typescript
+<Box
+  sx={(theme) => ({
+    backgroundColor: theme.palette.background.primary, // ✅ Semantic token
+    color: theme.palette.text.secondary, // ✅ Type-safe
+    padding: theme.spacing(4), // or just: padding: 4   // ✅ Spacing system
+  })}
+/>
+```
+
+### Use Meaningful Tokens
+
+❌ **Avoid** non-descriptive tokens:
+
+```typescript
+theme.palette.common.white; // ❌ No context about usage
+theme.palette.green300; // ❌ Which green? When to use?
+```
+
+✅ **Use** semantic tokens:
+
+```typescript
+theme.palette.background.tertiary; // ✅ Clear purpose
+theme.palette.instantPay.background; // ✅ Intent is obvious
+theme.palette.text.primary; // ✅ Meaningful
+```
+
+## Spacing System
+
+We use a strict index-based spacing system:
+
+| Index | 1   | 2   | 3   | 4    | 5    | 6    | 7    | 8    | 9    | 10   | 11   | 12   |
+| ----- | --- | --- | --- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
+| Size  | 4px | 6px | 8px | 12px | 16px | 20px | 24px | 32px | 40px | 48px | 56px | 64px |
+
+**Usage:**
+
+```typescript
+<Box sx={{ padding: 5 }} />    // → 16px
+<Box sx={{ marginX: 4 }} />    // → 12px left and right
+<Box sx={{ gap: 3 }} />        // → 8px
+```
+
+**Use `rem` for fonts and heights:**
+
+```typescript
+<Box
+  sx={(theme) => ({
+    height: "3rem", // ✅ Scales with user zoom
+    fontSize: theme.typography.body1.fontSize, // ✅ From theme
+    padding: 5, // ✅ px prevents overflow when zoomed
+  })}
+/>
+```
+
+**Reasoning:** Users who adjust device-wide zoom need `rem` for fonts/heights to scale properly, but `px` spacing prevents layout overflow.
+
+## Theme Integration
+
+### Responsive Styles
+
+```typescript
+<Box
+  sx={{
+    width: {
+      xs: "100%", // Mobile
+      sm: "75%", // Tablet
+      md: "50%", // Desktop
+    },
+    padding: {
+      xs: 1,
+      md: 3,
+    },
+  }}
+/>
+```
+
+### Pseudo-classes and Hover States
+
+```typescript
+<Box
+  sx={(theme) => ({
+    "&:hover": {
+      backgroundColor: theme.palette.primary.dark,
+      cursor: "pointer",
+    },
+    "&:disabled": {
+      opacity: 0.5,
+    },
+    "&.active": {
+      borderColor: theme.palette.primary.main,
+    },
+  })}
+/>
+```
+
+### Nested Selectors
+
+```typescript
+<Box
+  sx={(theme) => ({
+    "& .child-element": {
+      color: theme.palette.text.secondary,
+    },
+    "& > div": {
+      marginBottom: 1,
+    },
+    // Target nested MUI components
+    "& .MuiTypography-root": {
+      color: theme.palette.intent?.disabled.text,
+    },
+  })}
+/>
+```
+
+## Shorthand Properties
+
+MUI provides shorthand properties - use full names, not abbreviations:
+
+✅ **Use full names:**
+
+```typescript
+<Box
+  sx={{
+    padding: 2, // ✅ Clear
+    paddingX: 4, // ✅ Readable
+    marginY: 2, // ✅ Explicit
+  }}
+/>
+```
+
+❌ **Avoid abbreviations** (per naming conventions best practice):
+
+```typescript
+<Box
+  sx={{
+    p: 2, // ❌ Too terse
+    px: 4, // ❌ Not clear
+    my: 2, // ❌ What does this mean?
+  }}
+/>
+```
+
+[Full list of shorthand properties](https://mui.com/system/properties/)
+
+## Merging sx Props
+
+For generic components accepting an `sx` prop, merge default styles with custom styles:
+
+```typescript
+// Option 1: Array syntax (MUI native)
+<Box
+  sx={[
+    (theme) => ({
+      backgroundColor: theme.palette.background.tertiary,
+      padding: 2,
+    }),
+    sx, // User's custom sx prop
+  ]}
+  {...restProps}
+/>
+
+// Option 2: Use a utility function if your project provides one
+import { mergeSxProps } from "@clipboard-health/ui-components";
+
+<Box
+  sx={mergeSxProps(defaultStyles, sx)}
+  {...restProps}
+/>;
+```
+
+## Theme Access
+
+### Using useTheme Hook
+
+```typescript
+import { useTheme } from "@mui/material";
+
+export function Component() {
+  const theme = useTheme();
+
+  return (
+    <Box sx={{ color: theme.palette.primary.main }}>
+      {/* Your components */}
+    </Box>
+  );
+}
+```
+
+### Theme Properties
+
+```typescript
+const theme = useTheme();
+
+// Colors
+theme.palette.primary.main;
+theme.palette.secondary.main;
+theme.palette.error.main;
+theme.palette.text.primary;
+theme.palette.background.default;
+
+// Spacing
+theme.spacing(1); // Project-defined (see spacing system above)
+theme.spacing(2); // Project-defined (see spacing system above)
+
+// Typography
+theme.typography.h1;
+theme.typography.body1;
+
+// Breakpoints
+theme.breakpoints.up("md");
+theme.breakpoints.down("sm");
+```
+
+## Modal Patterns
+
+### ❌ Avoid Generic Modal
+
+```typescript
+// Avoid generic Modal when project has specific dialog components
+import { Modal } from "@mui/material";
+```
+
+### ✅ Use Project-Specific Dialog Components
+
+```typescript
+// For mobile-friendly modals
+import { BottomSheet } from "@/components/BottomSheet";
+
+// For full-screen views
+import { FullScreenDialog } from "@/components/FullScreenDialog";
+
+// For standard dialogs
+import { Dialog } from "@/components/Dialog";
+```
+
+Check your project's component library for available dialog/modal components.
+
+## Layout Components
+
+### Use MUI Layout Components
+
+These are safe to import directly from MUI:
+
+```typescript
+import { Box, Stack, Container, Grid } from '@mui/material';
+
+// Stack for vertical/horizontal layouts
+<Stack spacing={2} direction="row">
+  <Item />
+  <Item />
+</Stack>
+
+// Box for flexible containers
+<Box sx={{ display: 'flex', gap: 2 }}>
+  <Child />
+</Box>
+
+// Grid for responsive layouts
+<Grid container spacing={2}>
+  <Grid item xs={12} md={6}>
+    <Content />
+  </Grid>
+</Grid>
+```
+
+## MUI Theme Augmentation
+
+### Type Safety
+
+Projects often augment MUI's theme with custom properties:
+
+```typescript
+// Example: Custom theme augmentation
+declare module "@mui/material/styles" {
+  interface Theme {
+    customSpacing: {
+      large: string;
+      xlarge: string;
+    };
+  }
+  interface ThemeOptions {
+    customSpacing?: {
+      large?: string;
+      xlarge?: string;
+    };
+  }
+}
+```
+
+Check your project's type definitions for available theme augmentations.
+
+## Common Patterns
+
+### Card with Custom Styling
+
+```typescript
+import { Card, CardContent } from "@mui/material";
+
+<Card
+  sx={{
+    borderRadius: 2,
+    boxShadow: 2,
+    "&:hover": {
+      boxShadow: 4,
+    },
+  }}
+>
+  <CardContent>Content here</CardContent>
+</Card>;
+```
+
+### Buttons with Theme Colors
+
+```typescript
+import { Button } from "@/components/Button";
+
+<Button
+  variant="contained"
+  color="primary"
+  sx={{
+    textTransform: "none", // Override uppercase
+    fontWeight: "bold",
+  }}
+>
+  Submit
+</Button>;
+```
+
+### Conditional Styles
+
+```typescript
+<Box
+  sx={(theme) => ({
+    backgroundColor: isActive
+      ? theme.palette.primary.main
+      : theme.palette.grey[200],
+    padding: 2,
+  })}
+>
+  {content}
+</Box>
+```
+
+## Best Practices
+
+- **Check Storybook first** - It's the single source of truth
+- **Use theme tokens** - Never hardcode colors/spacing
+- **Type-safe access** - Function form: `sx={(theme) => ({...})}`
+- **Meaningful tokens** - Semantic names over raw colors
+- **Spacing system** - Indices 1-12 (or `theme.spacing(n)`)
+- **Use shorthand props** - `paddingX`, `marginY` (full names, not `px`, `my`)
+- **Leverage pseudo-classes** - For hover, focus, disabled states
+- **Prefer `sx` over direct props** - `sx` takes priority and is more flexible
+
+<!-- Source: .ruler/frontend/testing.md -->
+
+# Testing Standards
+
+## The Testing Trophy Philosophy
+
+Our testing strategy follows the **Testing Trophy** model:
+
+```text
+        /\_
+       /E2E\         ← End-to-End (smallest layer)
+      /-----\
+     / Integ \       ← Integration (largest layer - FOCUS HERE!)
+    /---------\
+   /   Unit    \     ← Unit Tests (helpers/utilities only)
+  /-------------\
+ /    Static     \   ← TypeScript + ESLint (foundation)
+```
+
+**Investment Priority:**
+
+1. **Static** (TypeScript/ESLint) - Free confidence, catches typos and type errors
+2. **Integration** - Most valuable, test how components work together as users experience them
+3. **Unit** - For pure helpers/utilities, NOT UI components
+4. **E2E** - Critical user flows only, slow and expensive
+
+**Key Principle:** Test as close to how users interact with your app as possible. Users don't shallow-render components or call functions in isolation - they interact with features.
+
+## Technology Stack
+
+- **Vitest** for test runner
+- **@testing-library/react** for component testing
+- **@testing-library/user-event** for user interactions
+- **Mock Service Worker (MSW)** for API mocking
+
+## Test File Structure
+
+```typescript
+import { render, screen, waitFor } from "@testing-library/react";
+import { renderHook } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+describe("ComponentName", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render correctly", () => {
+    render(<Component />);
+    expect(screen.getByText("Expected")).toBeInTheDocument();
+  });
+
+  it("should handle user interaction", async () => {
+    const user = userEvent.setup();
+    render(<Component />);
+
+    await user.click(screen.getByRole("button", { name: "Submit" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Success")).toBeInTheDocument();
+    });
+  });
+});
+```
+
+## Test Naming Conventions
+
+### Describe Blocks
+
+- Use the component/function name: `describe('ComponentName', ...)`
+- Nest describe blocks for complex scenarios
+
+```typescript
+describe("ShiftCard", () => {
+  describe("when shift is urgent", () => {
+    it("should display urgent badge", () => {
+      // ...
+    });
+  });
+
+  describe("when shift is booked", () => {
+    it("should show booked status", () => {
+      // ...
+    });
+  });
+});
+```
+
+### Test Names
+
+- Pattern: `'should [expected behavior] when [condition]'`
+- Be descriptive and specific
+
+```typescript
+// Good
+it("should show loading spinner when data is fetching", () => {});
+it("should display error message when API call fails", () => {});
+it("should enable submit button when form is valid", () => {});
+
+// Avoid
+it("works", () => {});
+it("loading state", () => {});
+```
+
+## Parameterized Tests
+
+### Using it.each
+
+```typescript
+it.each([
+  { input: { isUrgent: true }, expected: "URGENT" },
+  { input: { isUrgent: false }, expected: "REGULAR" },
+])("should return $expected when isUrgent is $input.isUrgent", ({ input, expected }) => {
+  expect(getShiftType(input)).toBe(expected);
+});
+```
+
+### Table-Driven Tests
+
+```typescript
+describe("calculateShiftPay", () => {
+  it.each([
+    { hours: 8, rate: 30, expected: 240 },
+    { hours: 10, rate: 25, expected: 250 },
+    { hours: 12, rate: 35, expected: 420 },
+  ])("should calculate $expected for $hours hours at $rate/hr", ({ hours, rate, expected }) => {
+    expect(calculateShiftPay(hours, rate)).toBe(expected);
+  });
+});
+```
+
+## Component Testing (Integration Tests)
+
+Integration tests form the largest part of the Testing Trophy. Test features, not isolated components.
+
+### Rendering Components
+
+```typescript
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+function renderWithProviders(component: ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  return render(<QueryClientProvider client={queryClient}>{component}</QueryClientProvider>);
+}
+
+it("should render user name", () => {
+  renderWithProviders(<UserProfile userId="123" />);
+  expect(screen.getByText("John Doe")).toBeInTheDocument();
+});
+```
+
+### Querying Elements - Priority Order
+
+Follow [Testing Library's query priority](https://testing-library.com/docs/queries/about#priority):
+
+1. **`getByRole`** - Best for accessibility (buttons, links, inputs)
+2. **`getByLabelText`** - For form fields with labels
+3. **`getByPlaceholderText`** - For inputs without labels
+4. **`getByText`** - For non-interactive content
+5. **`getByDisplayValue`** - For current input values
+6. **`getByAltText`** - For images
+7. **`getByTitle`** - Less common
+8. **`getByTestId`** - ⚠️ **LAST RESORT** - Use only when no other option exists
+
+```typescript
+// ✅ Prefer accessible queries
+screen.getByRole("button", { name: /submit/i });
+screen.getByLabelText("Email address");
+screen.getByText("Welcome back");
+
+// ❌ Avoid CSS selectors and implementation details
+screen.getByClassName("user-card"); // Users don't see classes
+wrapper.find("UserCard").prop("user"); // Testing implementation
+screen.getByTestId("custom-element"); // Last resort only
+```
+
+### User Interactions
+
+```typescript
+import userEvent from "@testing-library/user-event";
+
+it("should handle form submission", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+
+  render(<Form onSubmit={onSubmit} />);
+
+  // Type in input
+  await user.type(screen.getByLabelText("Name"), "John Doe");
+
+  // Click button
+  await user.click(screen.getByRole("button", { name: "Submit" }));
+
+  // Assert
+  expect(onSubmit).toHaveBeenCalledWith({ name: "John Doe" });
+});
+```
+
+## Hook Testing (Unit Tests)
+
+Only write unit tests for hooks that contain business logic, not for UI components.
+
+### Using renderHook
+
+```typescript
+import { renderHook, waitFor } from "@testing-library/react";
+
+describe("useCustomHook", () => {
+  it("should return loading state initially", () => {
+    const { result } = renderHook(() => useCustomHook());
+
+    expect(result.current.isLoading).toBe(true);
+  });
+
+  it("should return data after loading", async () => {
+    const { result } = renderHook(() => useCustomHook());
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.data).toEqual(expectedData);
+  });
+});
+```
+
+### Testing Hook Updates
+
+```typescript
+it("should update when dependencies change", async () => {
+  const { result, rerender } = renderHook(({ userId }) => useGetUser(userId), {
+    initialProps: { userId: "1" },
+  });
+
+  await waitFor(() => {
+    expect(result.current.data?.id).toBe("1");
+  });
+
+  // Update props
+  rerender({ userId: "2" });
+
+  await waitFor(() => {
+    expect(result.current.data?.id).toBe("2");
+  });
+});
+```
+
+## MSW (Mock Service Worker)
+
+### Factory Functions Pattern - IMPORTANT
+
+**Always export factory functions, not static handlers**. This allows tests to customize mock responses.
+
+❌ **Don't** export static handlers (ties tests to single response):
+
+```typescript
+// Bad - can only return this one mock
+export const facilityNotesSuccessScenario = rest.get(
+  `${TEST_API_URL}/facilityNotes`,
+  async (_, res, ctx) => res(ctx.status(200), ctx.json(mockFacilityNotes)),
+);
+```
+
+✅ **Do** export factory functions (flexible per test):
+
+```typescript
+// Good - each test can provide custom data
+export const createFacilityNotesTestHandler = (facilityNotes: FacilityNote[]) => {
+  return rest.get<string, Record<string, string>, FacilityNotesResponse>(
+    `${TEST_API_URL}/facilityNotes/:facilityId`,
+    async (_req, res, ctx) => {
+      return res(ctx.status(200), ctx.json(facilityNotes));
+    },
+  );
+};
+
+// Export default success scenario for convenience
+export const facilityNotesTestHandlers = [createFacilityNotesTestHandler(mockFacilityNotes)];
+```
+
+**Usage in tests:**
+
+```typescript
+// In test setup
+mockApiServer.use(
+  createFacilityNotesTestHandler(myCustomFacilityNotes),
+  createExtraTimePaySettingsTestHandler({ payload: customSettings }),
+);
+```
+
+**Rationale:** When endpoints need different responses for different test scenarios, factory functions avoid duplication and inline mocks that become hard to maintain.
+
+## Mocking
+
+### Mocking Modules
+
+```typescript
+import { vi } from "vitest";
+import * as useUserModule from "@/features/user/hooks/useUser";
+
+// Mock entire module
+vi.mock("@/features/user/hooks/useUser");
+
+// Spy on specific function
+const useDefinedWorkerSpy = vi.spyOn(useDefinedWorkerModule, "useDefinedWorker");
+useDefinedWorkerSpy.mockReturnValue(getMockWorker({ id: "123" }));
+```
+
+### Mocking Functions
+
+```typescript
+it("should call callback on success", async () => {
+  const onSuccess = vi.fn();
+
+  render(<Component onSuccess={onSuccess} />);
+
+  await user.click(screen.getByRole("button"));
+
+  await waitFor(() => {
+    expect(onSuccess).toHaveBeenCalledWith(expectedData);
+  });
+});
+```
+
+### Mocking API Calls
+
+```typescript
+import { vi } from "vitest";
+
+vi.mock("@/lib/api", () => ({
+  get: vi.fn().mockResolvedValue({
+    data: { id: "1", name: "Test" },
+  }),
+}));
+```
+
+## Async Testing
+
+### Using waitFor
+
+```typescript
+it("should display data after loading", async () => {
+  render(<AsyncComponent />);
+
+  expect(screen.getByText("Loading...")).toBeInTheDocument();
+
+  await waitFor(() => {
+    expect(screen.getByText("Data loaded")).toBeInTheDocument();
+  });
+});
+```
+
+### Using findBy Queries
+
+```typescript
+it("should display user name", async () => {
+  render(<UserProfile />);
+
+  // findBy automatically waits
+  const name = await screen.findByText("John Doe");
+  expect(name).toBeInTheDocument();
+});
+```
+
+## Test Organization
+
+### Co-location
+
+- Place test files next to source files
+- Use same name with `.test.ts` or `.test.tsx` extension
+
+```text
+Feature/
+├── Component.tsx
+├── Component.test.tsx
+├── utils.ts
+└── utils.test.ts
+```
+
+### Test Helpers
+
+- Create test utilities in `testUtils.ts` or `test-utils.ts`
+- Reusable mocks in `mocks/` folder
+
+```typescript
+// testUtils.ts
+export function getMockShift(overrides = {}): Shift {
+  return {
+    id: "1",
+    title: "Test Shift",
+    ...overrides,
+  };
+}
+```
+
+## What to Test
+
+### ✅ Do Test
+
+- **Integration tests for features** - Multiple components working together
+- **Unit tests for helpers/utilities** - Pure business logic
+- **All states** - Loading, success, error
+- **User interactions** - Clicks, typing, form submissions
+- **Conditional rendering** - Different states/permissions
+
+### ❌ Don't Test
+
+- **UI components in isolation** - Users never shallow-render
+- **Implementation details** - Internal state, function calls
+- **Third-party libraries** - Trust they're tested
+- **Styles/CSS** - Visual regression tests are separate
+
+## Coverage Guidelines
+
+- Aim for high coverage on business logic and utilities
+- Don't obsess over 100% coverage on UI components
+- **Focus on testing behavior**, not implementation
+- If you can't query it the way a user would, you're testing wrong
+
+## Common Patterns
+
+### Testing Loading States
+
+```typescript
+it("should show loading state", () => {
+  render(<Component />);
+  expect(screen.getByRole("progressbar")).toBeInTheDocument();
+});
+```
+
+### Testing Error States
+
+```typescript
+it("should display error message on failure", async () => {
+  // Mock API error
+  vi.mocked(get).mockRejectedValue(new Error("API Error"));
+
+  render(<Component />);
+
+  expect(await screen.findByText("Error loading data")).toBeInTheDocument();
+});
+```
+
+### Testing Conditional Rendering
+
+```typescript
+it("should show premium badge when user is premium", () => {
+  render(<UserCard user={{ ...mockUser, isPremium: true }} />);
+  expect(screen.getByText("Premium")).toBeInTheDocument();
+});
+
+it("should not show premium badge when user is not premium", () => {
+  render(<UserCard user={{ ...mockUser, isPremium: false }} />);
+  expect(screen.queryByText("Premium")).not.toBeInTheDocument();
+});
+```
+
+<!-- Source: .ruler/frontend/typeScript.md -->
+
+# TypeScript Standards
+
+## Core Principles
+
+- **Strict mode enabled** - no `any` unless absolutely necessary (document why)
+- **Prefer type inference** - let TypeScript infer when possible
+- **Explicit return types** for exported functions
+- **Zod for runtime validation** - single source of truth for types and validation
+- **No type assertions** unless unavoidable (prefer type guards)
+
+## Type vs Interface
+
+Use the right tool for the job:
+
+### Use `interface` for:
+
+- **Component props**
+- **Object shapes**
+- **Class definitions**
+- **Anything that might be extended**
+
+```typescript
+// ✅ Good - Interface for props
+interface UserCardProps {
+  user: User;
+  onSelect: (id: string) => void;
+  isHighlighted?: boolean;
+}
+
+// ✅ Good - Interface can be extended
+interface BaseEntity {
+  id: string;
+  createdAt: string;
+}
+
+interface User extends BaseEntity {
+  name: string;
+  email: string;
+}
+```
+
+### Use `type` for:
+
+- **Unions**
+- **Intersections**
+- **Tuples**
+- **Derived/conditional types**
+- **Type aliases**
+
+```typescript
+// ✅ Good - Type for unions
+type Status = "pending" | "active" | "completed" | "failed";
+
+// ✅ Good - Type for intersections
+type UserWithPermissions = User & { permissions: string[] };
+
+// ✅ Good - Type for tuples
+type Coordinate = [number, number];
+
+// ✅ Good - Derived types
+type UserKeys = keyof User;
+type PartialUser = Partial<User>;
+```
+
+## Naming Conventions
+
+### Types and Interfaces
+
+- **Suffix with purpose**: `Props`, `Response`, `Request`, `Options`, `Params`, `State`
+- **No `I` or `T` prefix** (we're not in C# or Java)
+- **PascalCase** for type names
+
+```typescript
+// ✅ Good
+interface ButtonProps { ... }
+type ApiResponse = { ... };
+type UserOptions = { ... };
+
+// ❌ Bad
+interface IButton { ... }  // No I prefix
+type TResponse = { ... };   // No T prefix
+interface buttonProps { ... }  // Wrong case
+```
+
+### Boolean Properties
+
+Always prefix with `is`, `has`, `should`, `can`, `will`:
+
+```typescript
+// ✅ Good
+interface User {
+  isActive: boolean;
+  hasPermission: boolean;
+  shouldNotify: boolean;
+  canEdit: boolean;
+  willExpire: boolean;
+}
+
+// ❌ Bad
+interface User {
+  active: boolean; // Unclear
+  permission: boolean; // Unclear
+  notify: boolean; // Unclear
+}
+```
+
+## Zod Integration
+
+```typescript
+// Define schema first
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+// Infer type from schema
+export type User = z.infer<typeof userSchema>;
+
+// Use for API validation
+const response = await get({
+  url: "/api/users",
+  responseSchema: userSchema,
+});
+```
+
+## Type Guards
+
+```typescript
+export function isEventKey(key: string): key is EventKey {
+  return VALID_EVENT_KEYS.includes(key as EventKey);
+}
+```
+
+## Constants
+
+```typescript
+// Use const assertions for readonly values
+export const STAGES = {
+  DRAFT: "draft",
+  PUBLISHED: "published",
+} as const;
+
+export type Stage = (typeof STAGES)[keyof typeof STAGES];
+```
+
+## Function Types
+
+```typescript
+// Explicit return types for exported functions
+export function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Prefer interfaces for function props
+interface HandleSubmitProps {
+  userId: string;
+  data: FormData;
+}
+
+export function handleSubmit(props: HandleSubmitProps): Promise<void> {
+  // ...
+}
+```
+
+## Utility Types
+
+TypeScript provides powerful built-in utility types. Use them:
+
+```typescript
+// Partial - Make all properties optional
+type PartialUser = Partial<User>;
+
+// Required - Make all properties required
+type RequiredUser = Required<User>;
+
+// Readonly - Make all properties readonly
+type ReadonlyUser = Readonly<User>;
+
+// Pick - Select specific properties
+type UserIdOnly = Pick<User, "id" | "name">;
+
+// Omit - Remove specific properties
+type UserWithoutPassword = Omit<User, "password">;
+
+// Record - Create object type with specific key/value types
+type UserMap = Record<string, User>;
+
+// NonNullable - Remove null and undefined
+type DefinedString = NonNullable<string | null | undefined>; // string
+
+// ReturnType - Extract return type from function
+function getUser() { return { id: '1', name: 'John' }; }
+type GetUserResult = ReturnType<typeof getUser>;
+
+// Parameters - Extract parameter types from function
+function updateUser(id: string, data: UserData) { ... }
+type UpdateUserParams = Parameters<typeof updateUser>; // [string, UserData]
+```
+
+## Avoiding `any`
+
+The `any` type defeats the purpose of TypeScript. Use alternatives:
+
+```typescript
+// ❌ Bad - Loses all type safety
+function process(data: any) {
+  return data.value; // No error if value doesn't exist!
+}
+
+// ✅ Good - Use unknown for truly unknown types
+function process(data: unknown) {
+  if (typeof data === "object" && data !== null && "value" in data) {
+    return (data as { value: string }).value;
+  }
+  throw new Error("Invalid data");
+}
+
+// ✅ Better - Use generics
+function process<T extends { value: string }>(data: T) {
+  return data.value; // Type safe!
+}
+
+// ✅ Best - Use Zod for runtime validation
+const dataSchema = z.object({ value: z.string() });
+function process(data: unknown) {
+  const parsed = dataSchema.parse(data); // Throws if invalid
+  return parsed.value; // Type safe!
+}
+```
+
+## Generics
+
+Use generics for reusable, type-safe code:
+
+```typescript
+// ✅ Good - Generic function
+function getFirst<T>(array: T[]): T | undefined {
+  return array[0];
+}
+
+const firstNumber = getFirst([1, 2, 3]); // number | undefined
+const firstName = getFirst(["a", "b"]); // string | undefined
+
+// ✅ Good - Generic component
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => ReactNode;
+  keyExtractor: (item: T) => string;
+}
+
+export function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
+  return (
+    <Box>
+      {items.map((item) => (
+        <Box key={keyExtractor(item)}>{renderItem(item)}</Box>
+      ))}
+    </Box>
+  );
+}
+
+// Usage - Type inferred!
+<List
+  items={users}
+  renderItem={(user) => <UserCard user={user} />} // user is User
+  keyExtractor={(user) => user.id}
+/>;
+
+// ✅ Good - Constrained generics
+interface HasId {
+  id: string;
+}
+
+function findById<T extends HasId>(items: T[], id: string): T | undefined {
+  return items.find((item) => item.id === id);
+}
+```
+
+## Runtime Type Checking
+
+Use type guards for runtime type checking:
+
+```typescript
+// ✅ Good - Type predicate
+export function isUser(value: unknown): value is User {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    "name" in value &&
+    typeof value.id === "string" &&
+    typeof value.name === "string"
+  );
+}
+
+// Usage
+function processData(data: unknown) {
+  if (isUser(data)) {
+    console.log(data.name); // TypeScript knows data is User
+  }
+}
+
+// ✅ Better - Use Zod (runtime validation + type guard)
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+export function isUser(value: unknown): value is User {
+  return userSchema.safeParse(value).success;
+}
+
+// ✅ Good - Discriminated unions
+type ApiResponse =
+  | { status: "success"; data: User }
+  | { status: "error"; error: string }
+  | { status: "loading" };
+
+function handleResponse(response: ApiResponse) {
+  switch (response.status) {
+    case "success":
+      console.log(response.data); // TypeScript knows data exists
+      break;
+    case "error":
+      console.log(response.error); // TypeScript knows error exists
+      break;
+    case "loading":
+      // TypeScript knows no data or error exists
+      break;
+  }
+}
+```
+
+## Const Assertions
+
+Use `as const` for readonly literal types:
+
+```typescript
+// ✅ Good - Const assertion for object
+export const STATUSES = {
+  PENDING: "pending",
+  ACTIVE: "active",
+  COMPLETED: "completed",
+} as const;
+
+// Type: 'pending' | 'active' | 'completed'
+export type Status = (typeof STATUSES)[keyof typeof STATUSES];
+
+// ✅ Good - Const assertion for array
+export const COLORS = ["red", "blue", "green"] as const;
+export type Color = (typeof COLORS)[number]; // 'red' | 'blue' | 'green'
+
+// ❌ Bad - Without const assertion
+export const STATUSES = {
+  PENDING: "pending", // Type: string (too loose!)
+  ACTIVE: "active",
+};
+```
+
+## Discriminated Unions
+
+Use for state machines and API responses:
+
+```typescript
+// ✅ Good - Discriminated union for query state
+type QueryState<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+
+function useQueryState<T>(): QueryState<T> {
+  // ...
+}
+
+// Usage - Type narrowing works automatically
+const state = useQueryState<User>();
+
+if (state.status === "success") {
+  console.log(state.data); // TypeScript knows data exists
+}
+
+// ✅ Good - Discriminated union for actions
+type Action =
+  | { type: "SET_USER"; payload: User }
+  | { type: "CLEAR_USER" }
+  | { type: "UPDATE_USER"; payload: Partial<User> };
+
+function reducer(state: State, action: Action) {
+  switch (action.type) {
+    case "SET_USER":
+      return { ...state, user: action.payload }; // payload is User
+    case "CLEAR_USER":
+      return { ...state, user: null }; // no payload
+    case "UPDATE_USER":
+      return { ...state, user: { ...state.user, ...action.payload } };
+  }
+}
+```
+
+## Function Overloads
+
+Use for functions with different parameter/return combinations:
+
+```typescript
+// ✅ Good - Function overloads
+function formatValue(value: string): string;
+function formatValue(value: number): string;
+function formatValue(value: Date): string;
+function formatValue(value: string | number | Date): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return value.toString();
+  return value.toISOString();
+}
+
+// TypeScript knows the return type based on input
+const str1 = formatValue("hello"); // string
+const str2 = formatValue(123); // string
+const str3 = formatValue(new Date()); // string
+```
+
+## Template Literal Types
+
+Use for type-safe string patterns:
+
+```typescript
+// ✅ Good - Event handler props with enforced naming
+type EventHandlers<T extends string> = {
+  [K in T as `on${Capitalize<K>}`]: () => void;
+};
+
+type Props = EventHandlers<"click" | "hover" | "submit">;
+// Results in: { onClick: () => void; onHover: () => void; onSubmit: () => void; }
+
+// ✅ Good - Validate event handler keys
+type ValidateEventKey<K extends string> = K extends `on${Capitalize<string>}` ? K : never;
+
+interface ComponentProps {
+  onClick: () => void; // ✅ Valid
+  onHover: () => void; // ✅ Valid
+  // click: () => void; // ❌ Does not satisfy ValidateEventKey
+}
+
+// ✅ Good - Route paths
+type Route = `/users/${string}` | `/posts/${string}` | "/";
+
+const validRoute: Route = "/users/123"; // ✅
+const invalidRoute: Route = "users/123"; // ❌ Error
+
+// ✅ Good - CSS properties
+type CSSProperty = `${"margin" | "padding"}${"Top" | "Bottom" | "Left" | "Right"}`;
+// 'marginTop' | 'marginBottom' | 'marginLeft' | 'marginRight' | 'paddingTop' | ...
+```
+
+## Mapped Types
+
+Create new types by transforming existing ones:
+
+```typescript
+// ✅ Good - Make all properties optional
+type Optional<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// ✅ Good - Make all properties readonly
+type Immutable<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+// ✅ Good - Add suffix to all keys
+type Prefixed<T, P extends string> = {
+  [K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
+};
+
+type User = { name: string; age: number };
+type PrefixedUser = Prefixed<User, "user">;
+// { userName: string; userAge: number }
+```
+
+## Type Narrowing
+
+Let TypeScript narrow types automatically:
+
+```typescript
+// ✅ Good - Typeof narrowing
+function format(value: string | number) {
+  if (typeof value === "string") {
+    return value.toUpperCase(); // TypeScript knows value is string
+  }
+  return value.toFixed(2); // TypeScript knows value is number
+}
+
+// ✅ Good - Truthiness narrowing
+function getLength(value: string | null) {
+  if (value) {
+    return value.length; // TypeScript knows value is string
+  }
+  return 0;
+}
+
+// ✅ Good - In narrowing
+interface Fish {
+  swim: () => void;
+}
+interface Bird {
+  fly: () => void;
+}
+
+function move(animal: Fish | Bird) {
+  if ("swim" in animal) {
+    animal.swim(); // TypeScript knows animal is Fish
+  } else {
+    animal.fly(); // TypeScript knows animal is Bird
+  }
+}
+
+// ✅ Good - Instanceof narrowing
+function handleError(error: unknown) {
+  if (error instanceof Error) {
+    console.log(error.message); // TypeScript knows error is Error
+  }
+}
+```
+
+## Common Patterns
+
+### Optional Chaining & Nullish Coalescing
+
+```typescript
+// ✅ Good - Optional chaining
+const userName = user?.profile?.name;
+
+// ✅ Good - Nullish coalescing (only null/undefined, not '')
+const displayName = userName ?? "Anonymous";
+
+// ❌ Bad - Logical OR (treats '' and 0 as falsy)
+const displayName = userName || "Anonymous";
+```
+
+### Non-null Assertion (Use Sparingly)
+
+```typescript
+// ⚠️ Use sparingly - Only when you're 100% sure
+const user = getUser()!; // Tells TS: trust me, it's not null
+
+// ✅ Better - Handle null case
+const user = getUser();
+if (!user) throw new Error("User not found");
+// Now TypeScript knows user exists
+```
+
+<!-- Source: .ruler/frontend/uiAndStyling.md -->
+
+# UI and Styling
+
+- Use Material UI for components and styling and a mobile-first approach.
+- Favor TanStack Query over "useEffect".