frontend-dev-guidelines

Use useSuspenseQuery inside a component wrapped in a SuspenseLoader boundary. The query's data is always defined, eliminating isLoading checks, while the Suspense boundary handles the loading indicator without layout shift.

Create a features/{name}/ directory with api/, components/, hooks/, helpers/, and types/ subdirectories, plus an index.ts exporting the public API. Put only truly reusable UI in the shared components/ directory.

Use useSuspenseQuery for all new components because it integrates with Suspense boundaries and guarantees defined data. Reserve useQuery for legacy code or cases without Suspense, paired with LoadingOverlay instead of early returns.

Early returns with spinners cause Cumulative Layout Shift because the rendered layout changes when loading completes. SuspenseLoader or LoadingOverlay reserves the content area, keeping layout stable and preserving scroll position.

Yes. MUI v7 uses the size prop, such as <Grid size={{ xs: 12, md: 6 }}>, instead of the old xs and md props directly on Grid. The guidelines require the v7 syntax for all grid layouts.

Keep styles inline as a Record<string, SxProps<Theme>> object when under 100 lines. Move them to a separate .styles.ts file when they exceed 100 lines, always using the sx prop with theme access.