antigravity-claudekit/skills/ck-frontend-development/SKILL.md

name, description

name	description
ck-frontend-development	Build React/TypeScript frontends with modern patterns. Use for components, Suspense-based data fetching, lazy loading, MUI v7 styling, TanStack Router, performance optimization, feature organization.

ck-frontend-development

Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.

When to Use

• Creating new components or pages
• Building new features with data fetching
• Setting up routing with TanStack Router
• Styling components with MUI v7
• Performance optimization of existing components
• Organizing frontend code structure

Don't Use When

• Purely visual/design work with no data logic — use ck-frontend-design
• Backend API work — use ck-backend-development
• Testing existing components — use ck-web-testing

New Component Checklist

• Use React.FC<Props> pattern with TypeScript
• Lazy load if heavy: React.lazy(() => import())
• Wrap in <SuspenseLoader> for loading states
• Use useSuspenseQuery for data fetching
• Use useCallback for event handlers passed to children
• Default export at bottom
• No early returns with loading spinners (causes layout shift)

New Feature Checklist

• Create features/{feature-name}/ directory
• Create subdirs: api/, components/, hooks/, helpers/, types/
• Create API service file: api/{feature}Api.ts
• Set up TypeScript types in types/
• Create route in routes/{feature-name}/index.tsx
• Lazy load feature components
• Export public API from feature index.ts

Core Patterns

Data Fetching — Primary Pattern: useSuspenseQuery

const { data } = useSuspenseQuery({
  queryKey: ['feature', id],
  queryFn: () => featureApi.getFeature(id),
});

• Use with Suspense boundaries
• Cache-first strategy
• Replaces isLoading checks

Lazy Loading

const Heavy = React.lazy(() => import('./Heavy'));
// Always wrap in SuspenseLoader

Loading States — CRITICAL RULE: No Early Returns

// NEVER — causes layout shift
if (isLoading) return <LoadingSpinner />;

// ALWAYS — consistent layout
<SuspenseLoader><Content /></SuspenseLoader>

MUI v7 Grid (breaking change)

<Grid size={{ xs: 12, md: 6 }}>  // v7 correct
<Grid xs={12} md={6}>             // old — wrong

File Structure

src/
  features/
    my-feature/
      api/          # API service layer
      components/   # Feature components
      hooks/        # Custom hooks
      helpers/      # Utility functions
      types/        # TypeScript types
      index.ts      # Public exports
  components/       # Truly reusable components
  routes/           # TanStack Router routes

Import Aliases

Alias	Resolves To
@/	src/
~types	src/types
~components	src/components
~features	src/features

Performance Patterns

• useMemo: Expensive computations (filter, sort, map)
• useCallback: Event handlers passed to children
• React.memo: Expensive pure components
• Debounced search: 300–500ms
• Memory leak prevention: cleanup in useEffect

TypeScript Standards

• Strict mode enabled — no any type
• Explicit return types on functions
• Type imports: import type { User } from '~types/user'
• Component prop interfaces with JSDoc comments

User Notifications

Always use useMuiSnackbar — never react-toastify or other toast libraries.

Core Principles

1. Lazy load everything heavy: routes, DataGrid, charts, editors
2. Suspense for loading: use SuspenseLoader, not early returns
3. useSuspenseQuery: primary data fetching pattern
4. Features are organized: api/, components/, hooks/, helpers/
5. Styles based on size: < 100 lines inline, > 100 lines separate file