Enhance .continue/rules with comprehensive TanStack Start, TypeScript, and accessibility guidance (#68)

This PR significantly enhances the `.continue/rules` directory with
comprehensive guidance based on the improvements suggested for the
Copilot instructions. The changes expand developer guidance for TanStack
Start, TypeScript, React Query, Zod, Tailwind, and Shadcn/ui while
maintaining the existing structure and adding practical, AI-friendly
examples.

## Key Enhancements

### 🚀 TanStack Start Routing Improvements
- **Loader/Action Conventions**: Added comprehensive examples for typing
loader and action returns with proper TypeScript integration
- **Error and Loading Boundaries**: Implemented ErrorBoundary and
PendingBoundary usage patterns with practical examples
- **Loader-First Data Flow**: Detailed guidance on when to use loaders
vs React Query to avoid redundant fetching

```typescript
// Example: Properly typed loader with boundaries
export const Route = createFileRoute('/users/$id')({
  loader: async ({ params }): Promise<User> => {
    const userIdSchema = z.object({ id: z.string() })
    const { id } = userIdSchema.parse(params)
    return fetchUser(id)
  },
  errorComponent: ({ error }) => (
    <ErrorDisplay error={error} />
  ),
  pendingComponent: () => <LoadingSpinner />,
  component: UserDetail,
})
```

### 📦 Import Aliasing and Project Structure
- **Path Mapping**: Enhanced import patterns with `@/` aliasing best
practices
- **Clean Imports**: Examples showing preference for aliased imports
over relative paths
- **Module Organization**: Improved guidance on component and utility
organization

### ♿ Accessibility and ARIA Best Practices
- **ARIA Implementation**: Comprehensive examples for accessible
components
- **Focus Management**: Keyboard navigation and focus management
patterns
- **Semantic HTML**: Guidelines for proper HTML semantics before ARIA

```typescript
// Example: Accessible form with proper ARIA
<form onSubmit={handleSubmit} aria-labelledby="form-title">
  <h2 id="form-title">User Registration</h2>
  <input
    id="email"
    type="email"
    aria-describedby="email-error"
    aria-invalid={errors.email ? 'true' : 'false'}
  />
</form>
```

### 🔍 TypeScript and Zod Integration
- **Type Derivation**: Enhanced patterns for deriving TypeScript types
from Zod schemas
- **Schema Organization**: Comprehensive examples for centralized schema
management
- **Validation Patterns**: Practical examples for API validation and
external data handling

### 🧪 Testing Guidelines (New)
- **React Testing Library**: Patterns for testing user behavior over
implementation
- **TanStack Router Testing**: Examples for testing route components
with mocked loaders
- **Custom Hook Testing**: Comprehensive patterns for testing hooks and
utilities

## Files Updated

- **`file-structure-frameworks.md`**: Enhanced with TanStack Start
patterns, import aliasing, and boundaries
- **`validation-zod.md`**: Expanded with comprehensive examples and type
derivation patterns
- **`state-management.md`**: Updated with loader-first data flow
guidance
- **`styling-ui-guidelines.md`**: Enhanced with accessibility and ARIA
best practices
- **`mcp-app-demo-standards.md`**: Improved TypeScript patterns and
React component examples
- **`testing-guidelines.md`**: New file with comprehensive testing
patterns

## Benefits

✅ **Actionable Guidance**: 30+ practical, copy-paste ready TypeScript
examples
✅ **AI-Friendly**: Maintains existing structure while improving clarity
for AI assistants
✅ **Comprehensive Coverage**: Addresses all modern React development
patterns
✅ **Accessibility Focus**: Ensures inclusive development practices  
✅ **Type Safety**: Emphasizes proper TypeScript usage throughout the
stack

The enhancements maintain backward compatibility while significantly
improving the developer experience and code quality guidance for the MCP
App Demo project.

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: nickytonline <833231+nickytonline@users.noreply.github.com>

Author: Copilot

.continue/rules/file-structure-frameworks.md

@@ -15,14 +15,98 @@ You are an expert in TanStack Start routing and modern React project organizatio
 • Use bracket notation like `[id].tsx` for dynamic routes
 • Use `_layout.tsx` files for shared layouts across route groups
 
-## Route File Structure
+## Route File Structure and Patterns
 
 • Export `loader` functions for data fetching before route renders
 • Export `action` functions for handling form submissions and mutations
 • Export `meta` objects for page metadata (title, description, etc.)
 • Keep route components focused on layout and data orchestration
 • Extract complex logic into custom hooks or utility functions
 
+### Loader and Action Typing
+
+• Always type loader and action returns explicitly for better type safety
+• Use Zod schemas for validating loader parameters and action inputs
+• Leverage `useLoaderData()` with proper typing for accessing loader data
+
+```typescript
+// ✅ Good: Properly typed loader with validation
+export const Route = createFileRoute('/users/$id')({
+  loader: async ({ params }): Promise<User> => {
+    const userIdSchema = z.object({ id: z.string() })
+    const { id } = userIdSchema.parse(params)
+    return fetchUser(id)
+  },
+  component: UserDetail,
+})
+
+function UserDetail() {
+  const user = Route.useLoaderData() // Automatically typed as User
+  return <div>{user.name}</div>
+}
+```
+
+### Loader-First Data Flow
+
+• Prefer loaders over React Query for initial page data to avoid redundant fetching
+• Use React Query only for data that needs frequent updates or client-side caching
+• Implement loader-first pattern to ensure data is available before component renders
+
+```typescript
+// ✅ Good: Loader-first approach
+export const Route = createFileRoute('/dashboard')({
+  loader: async (): Promise<DashboardData> => {
+    // Fetch initial data in loader
+    return {
+      user: await fetchUser(),
+      metrics: await fetchMetrics(),
+    }
+  },
+  component: Dashboard,
+})
+
+// ❌ Avoid: Redundant React Query when loader data is sufficient
+function Dashboard() {
+  const data = Route.useLoaderData()
+  // Don't use React Query here if loader data is sufficient
+  return <DashboardView data={data} />
+}
+```
+
+### Error and Loading Boundaries
+
+• Use ErrorBoundary for handling route-level errors gracefully
+• Implement PendingBoundary for loading states during navigation
+• Provide meaningful error messages and recovery options
+
+```typescript
+// ✅ Good: Route with error and pending boundaries
+export const Route = createFileRoute('/users/$id')({
+  loader: async ({ params }) => {
+    try {
+      return await fetchUser(params.id)
+    } catch (error) {
+      throw new Error(`Failed to load user: ${error.message}`)
+    }
+  },
+  errorComponent: ({ error }) => (
+    <div className="text-center p-6">
+      <h2 className="text-xl font-semibold text-red-600 mb-2">Error</h2>
+      <p className="text-gray-600">{error.message}</p>
+      <Link to="/users" className="text-blue-600 hover:underline mt-4 inline-block">
+        Back to Users
+      </Link>
+    </div>
+  ),
+  pendingComponent: () => (
+    <div className="flex items-center justify-center p-6">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+    </div>
+  ),
+  component: UserDetail,
+})
+```
+
 ## Component Organization
 
 • Keep shared UI components in `src/components`
@@ -45,7 +129,27 @@ You are an expert in TanStack Start routing and modern React project organizatio
 • Prefer named exports for utilities and hooks
 • Use default exports for React components
 • Implement proper module boundaries between features
-• Use path mapping for clean import statements when necessary
+• Use path mapping (`@/`) for clean import statements - configured in tsconfig.json
+
+### Import Aliasing Best Practices
+
+• Use `@/components` for importing UI components
+• Use `@/lib` for utilities, schemas, and helper functions
+• Use `@/hooks` for custom React hooks
+• Use `@/contexts` for React Context providers
+• Always prefer aliased imports over relative paths for better maintainability
+
+```typescript
+// ✅ Good: Clean aliased imports
+import { Button } from '@/components/ui/button'
+import { userSchema } from '@/lib/schemas'
+import { useLocalStorage } from '@/hooks/useLocalStorage'
+import { UserProvider } from '@/contexts/UserContext'
+
+// ❌ Avoid: Relative path imports for shared code
+import { Button } from '../../../components/ui/button'
+import { userSchema } from '../../lib/schemas'
+```
 
 ## File Naming Conventions
 

.continue/rules/mcp-app-demo-standards.md

@@ -9,17 +9,50 @@ You are an expert in TypeScript, React, TanStack Start, Vite, Tailwind CSS, and
 
 ## Technology Stack
 
-• This project uses TypeScript, Vite, TanStack Start, Tailwind CSS, and Shadcn/ui components
+• This project uses TypeScript, Vite, TanStack Start, Tailwind CSS, Shadcn/ui components, Zod validation, and React Query
 • All AI-generated code must follow these technologies and existing linting/Prettier rules
-• Run `npm run lint:fix` before committing any changes
+• Run `npm run check` for formatting and linting before committing any changes
 • Follow the established project structure and conventions
+• Use import aliasing (`@/`) for clean, maintainable imports
 
 ## Type Safety
 
 • Never introduce the `any` type - use proper generics or let TypeScript infer types
 • Use explicit type annotations for function parameters and return types where beneficial
 • Leverage TypeScript's strict mode for maximum type safety
 • Use type guards for runtime type checking when needed
+• Derive all types from Zod schemas to maintain consistency between runtime validation and compile-time types
+
+### TypeScript Best Practices
+
+• Prefer type inference when TypeScript can reliably determine the type
+• Use union types and discriminated unions for complex state modeling
+• Implement proper error handling with typed error objects
+• Use generic constraints to create reusable, type-safe utilities
+
+```typescript
+// ✅ Good: Proper typing with interface
+interface UserProps {
+  id: string
+  name: string
+  email?: string
+  onUpdate: (user: User) => void
+}
+
+// ✅ Good: Type inference where appropriate
+const users = await fetchUsers() // Let TypeScript infer User[]
+
+// ✅ Good: Generic constraints for reusable utilities
+function createApiResponse<T extends Record<string, unknown>>(
+  data: T,
+  status: 'success' | 'error' = 'success'
+): ApiResponse<T> {
+  return { data, status, timestamp: Date.now() }
+}
+
+// ❌ Bad: Using any type
+const data: any = await fetchData()
+```
 
 ## Code Quality
 
@@ -34,3 +67,46 @@ You are an expert in TypeScript, React, TanStack Start, Vite, Tailwind CSS, and
 • Keep functions and components focused on a single responsibility
 • Use meaningful names for variables, functions, and components
 • Implement proper error handling for all operations
+• Write self-documenting code that clearly expresses intent
+• Follow established patterns for testing when tests exist in the project
+
+### React Component Patterns
+
+• Use function components with TypeScript for all new components
+• Implement proper prop typing with interfaces or type definitions
+• Use hooks appropriately for state management and side effects
+• Follow the component composition pattern over prop drilling
+
+```typescript
+// ✅ Good: Well-typed function component
+interface ButtonProps {
+  children: React.ReactNode
+  onClick: () => void
+  variant?: 'primary' | 'secondary'
+  disabled?: boolean
+}
+
+export default function Button({ 
+  children, 
+  onClick, 
+  variant = 'primary',
+  disabled = false 
+}: ButtonProps) {
+  return (
+    <button 
+      onClick={onClick}
+      disabled={disabled}
+      className={cn(buttonVariants({ variant }), disabled && 'opacity-50')}
+    >
+      {children}
+    </button>
+  )
+}
+
+// ✅ Good: Custom hook for shared logic
+function useToggle(initialValue = false) {
+  const [value, setValue] = useState(initialValue)
+  const toggle = useCallback(() => setValue(prev => !prev), [])
+  return [value, toggle] as const
+}
+```

.continue/rules/state-management.md

@@ -23,6 +23,50 @@ You are an expert in React state management patterns and modern React developmen
 • Use mutations for server state changes with optimistic updates when appropriate
 • Configure appropriate cache times and stale-while-revalidate policies
 
+### Loader-First Data Flow Pattern
+
+• Prefer route loaders over React Query for initial page data to avoid redundant fetching
+• Use React Query for data that needs frequent updates, real-time syncing, or client-side caching
+• Combine loaders with React Query strategically - loaders for initial data, queries for dynamic updates
+• Avoid unnecessary API calls by leveraging loader data when appropriate
+
+```typescript
+// ✅ Good: Loader-first approach for initial data
+export const Route = createFileRoute('/dashboard')({
+  loader: async (): Promise<DashboardData> => {
+    // Load critical initial data in the loader
+    return {
+      user: await fetchUser(),
+      metrics: await fetchDashboardMetrics(),
+    }
+  },
+  component: Dashboard,
+})
+
+function Dashboard() {
+  const initialData = Route.useLoaderData()
+  
+  // Use React Query only for data that needs frequent updates
+  const { data: liveMetrics } = useQuery({
+    queryKey: ['live-metrics'],
+    queryFn: fetchLiveMetrics,
+    initialData: initialData.metrics,
+    refetchInterval: 30000, // Update every 30 seconds
+  })
+  
+  return <DashboardView user={initialData.user} metrics={liveMetrics} />
+}
+
+// ❌ Avoid: Redundant fetching when loader data is sufficient
+function BadDashboard() {
+  // Don't use React Query if loader already provides the data
+  const { data: user } = useQuery({
+    queryKey: ['user'],
+    queryFn: fetchUser, // Redundant if loader already fetched this
+  })
+}
+```
+
 ## Local Component State
 
 • Use `useState` for simple local component state

.continue/rules/styling-ui-guidelines.md

@@ -39,6 +39,108 @@ You are an expert in Tailwind CSS and Shadcn/ui component development.
 • Use consistent border radius and shadow patterns
 • Follow accessibility guidelines for color contrast and focus states
 
+## Accessibility and ARIA Best Practices
+
+• Implement proper ARIA labels and descriptions for interactive elements
+• Use semantic HTML elements before adding ARIA attributes
+• Ensure all interactive elements are keyboard accessible
+• Maintain proper color contrast ratios (4.5:1 for normal text, 3:1 for large text)
+• Provide alternative text for images and visual content
+• Use proper heading hierarchy (h1, h2, h3) for screen readers
+
+### Accessibility Implementation Examples
+
+```typescript
+// ✅ Good: Accessible button with proper ARIA
+<Button
+  onClick={handleSubmit}
+  disabled={isLoading}
+  aria-label="Submit user registration form"
+  aria-describedby="submit-help"
+>
+  {isLoading ? 'Submitting...' : 'Submit'}
+</Button>
+<div id="submit-help" className="sr-only">
+  This will create your account and send a confirmation email
+</div>
+
+// ✅ Good: Accessible form with proper labeling
+<form onSubmit={handleSubmit} aria-labelledby="form-title">
+  <h2 id="form-title">User Registration</h2>
+  <div className="space-y-4">
+    <div>
+      <label htmlFor="email" className="block text-sm font-medium">
+        Email Address <span aria-hidden="true">*</span>
+      </label>
+      <input
+        id="email"
+        type="email"
+        required
+        aria-describedby="email-error"
+        aria-invalid={errors.email ? 'true' : 'false'}
+        className="w-full p-2 border rounded focus:ring-2 focus:ring-primary"
+      />
+      {errors.email && (
+        <div id="email-error" role="alert" className="text-red-600 text-sm">
+          {errors.email}
+        </div>
+      )}
+    </div>
+  </div>
+</form>
+
+// ✅ Good: Accessible navigation with skip link
+<nav aria-label="Main navigation">
+  <a href="#main-content" className="sr-only focus:not-sr-only">
+    Skip to main content
+  </a>
+  <ul role="list">
+    <li><Link to="/" aria-current={pathname === '/' ? 'page' : undefined}>Home</Link></li>
+    <li><Link to="/about">About</Link></li>
+  </ul>
+</nav>
+```
+
+### Focus Management and Keyboard Navigation
+
+• Ensure proper focus management when content changes dynamically
+• Implement logical tab order throughout the application
+• Provide visible focus indicators that meet accessibility standards
+• Use `focus-visible` for keyboard-only focus indication
+
+```typescript
+// ✅ Good: Accessible modal with focus management
+function AccessibleModal({ isOpen, onClose, children }) {
+  const modalRef = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (isOpen && modalRef.current) {
+      modalRef.current.focus()
+    }
+  }, [isOpen])
+  
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent
+        ref={modalRef}
+        tabIndex={-1}
+        aria-labelledby="modal-title"
+        aria-describedby="modal-description"
+        className="focus:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+      >
+        <DialogHeader>
+          <DialogTitle id="modal-title">Confirm Action</DialogTitle>
+          <DialogDescription id="modal-description">
+            This action cannot be undone.
+          </DialogDescription>
+        </DialogHeader>
+        {children}
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
 ## Custom Styling Guidelines
 
 • Avoid writing custom CSS unless absolutely necessary