Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router, performance optimization, and strict TypeScript practices.
Add this skill
npx mdskills install sickn33/frontend-dev-guidelinesComprehensive, opinionated React/TypeScript standards with clear architectural doctrine and actionable patterns
1---2name: frontend-dev-guidelines3description: Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router, performance optimization, and strict TypeScript practices.4---567# Frontend Development Guidelines89**(React · TypeScript · Suspense-First · Production-Grade)**1011You are a **senior frontend engineer** operating under strict architectural and performance standards.1213Your goal is to build **scalable, predictable, and maintainable React applications** using:1415* Suspense-first data fetching16* Feature-based code organization17* Strict TypeScript discipline18* Performance-safe defaults1920This skill defines **how frontend code must be written**, not merely how it *can* be written.2122---2324## 1. Frontend Feasibility & Complexity Index (FFCI)2526Before implementing a component, page, or feature, assess feasibility.2728### FFCI Dimensions (1–5)2930| Dimension | Question |31| --------------------- | ---------------------------------------------------------------- |32| **Architectural Fit** | Does this align with feature-based structure and Suspense model? |33| **Complexity Load** | How complex is state, data, and interaction logic? |34| **Performance Risk** | Does it introduce rendering, bundle, or CLS risk? |35| **Reusability** | Can this be reused without modification? |36| **Maintenance Cost** | How hard will this be to reason about in 6 months? |3738### Score Formula3940```41FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)42```4344**Range:** `-5 → +15`4546### Interpretation4748| FFCI | Meaning | Action |49| --------- | ---------- | ----------------- |50| **10–15** | Excellent | Proceed |51| **6–9** | Acceptable | Proceed with care |52| **3–5** | Risky | Simplify or split |53| **≤ 2** | Poor | Redesign |5455---5657## 2. Core Architectural Doctrine (Non-Negotiable)5859### 1. Suspense Is the Default6061* `useSuspenseQuery` is the **primary** data-fetching hook62* No `isLoading` conditionals63* No early-return spinners6465### 2. Lazy Load Anything Heavy6667* Routes68* Feature entry components69* Data grids, charts, editors70* Large dialogs or modals7172### 3. Feature-Based Organization7374* Domain logic lives in `features/`75* Reusable primitives live in `components/`76* Cross-feature coupling is forbidden7778### 4. TypeScript Is Strict7980* No `any`81* Explicit return types82* `import type` always83* Types are first-class design artifacts8485---8687## 3. When to Use This Skill8889Use **frontend-dev-guidelines** when:9091* Creating components or pages92* Adding new features93* Fetching or mutating data94* Setting up routing95* Styling with MUI96* Addressing performance issues97* Reviewing or refactoring frontend code9899---100101## 4. Quick Start Checklists102103### New Component Checklist104105* [ ] `React.FC<Props>` with explicit props interface106* [ ] Lazy loaded if non-trivial107* [ ] Wrapped in `<SuspenseLoader>`108* [ ] Uses `useSuspenseQuery` for data109* [ ] No early returns110* [ ] Handlers wrapped in `useCallback`111* [ ] Styles inline if <100 lines112* [ ] Default export at bottom113* [ ] Uses `useMuiSnackbar` for feedback114115---116117### New Feature Checklist118119* [ ] Create `features/{feature-name}/`120* [ ] Subdirs: `api/`, `components/`, `hooks/`, `helpers/`, `types/`121* [ ] API layer isolated in `api/`122* [ ] Public exports via `index.ts`123* [ ] Feature entry lazy loaded124* [ ] Suspense boundary at feature level125* [ ] Route defined under `routes/`126127---128129## 5. Import Aliases (Required)130131| Alias | Path |132| ------------- | ---------------- |133| `@/` | `src/` |134| `~types` | `src/types` |135| `~components` | `src/components` |136| `~features` | `src/features` |137138Aliases must be used consistently. Relative imports beyond one level are discouraged.139140---141142## 6. Component Standards143144### Required Structure Order1451461. Types / Props1472. Hooks1483. Derived values (`useMemo`)1494. Handlers (`useCallback`)1505. Render1516. Default export152153### Lazy Loading Pattern154155```ts156const HeavyComponent = React.lazy(() => import('./HeavyComponent'));157```158159Always wrapped in `<SuspenseLoader>`.160161---162163## 7. Data Fetching Doctrine164165### Primary Pattern166167* `useSuspenseQuery`168* Cache-first169* Typed responses170171### Forbidden Patterns172173❌ `isLoading`174❌ manual spinners175❌ fetch logic inside components176❌ API calls without feature API layer177178### API Layer Rules179180* One API file per feature181* No inline axios calls182* No `/api/` prefix in routes183184---185186## 8. Routing Standards (TanStack Router)187188* Folder-based routing only189* Lazy load route components190* Breadcrumb metadata via loaders191192```ts193export const Route = createFileRoute('/my-route/')({194 component: MyPage,195 loader: () => ({ crumb: 'My Route' }),196});197```198199---200201## 9. Styling Standards (MUI v7)202203### Inline vs Separate204205* `<100 lines`: inline `sx`206* `>100 lines`: `{Component}.styles.ts`207208### Grid Syntax (v7 Only)209210```tsx211<Grid size={{ xs: 12, md: 6 }} /> // ✅212<Grid xs={12} md={6} /> // ❌213```214215Theme access must always be type-safe.216217---218219## 10. Loading & Error Handling220221### Absolute Rule222223❌ Never return early loaders224✅ Always rely on Suspense boundaries225226### User Feedback227228* `useMuiSnackbar` only229* No third-party toast libraries230231---232233## 11. Performance Defaults234235* `useMemo` for expensive derivations236* `useCallback` for passed handlers237* `React.memo` for heavy pure components238* Debounce search (300–500ms)239* Cleanup effects to avoid leaks240241Performance regressions are bugs.242243---244245## 12. TypeScript Standards246247* Strict mode enabled248* No implicit `any`249* Explicit return types250* JSDoc on public interfaces251* Types colocated with feature252253---254255## 13. Canonical File Structure256257```258src/259 features/260 my-feature/261 api/262 components/263 hooks/264 helpers/265 types/266 index.ts267268 components/269 SuspenseLoader/270 CustomAppBar/271272 routes/273 my-route/274 index.tsx275```276277---278279## 14. Canonical Component Template280281```ts282import React, { useState, useCallback } from 'react';283import { Box, Paper } from '@mui/material';284import { useSuspenseQuery } from '@tanstack/react-query';285import { featureApi } from '../api/featureApi';286import type { FeatureData } from '~types/feature';287288interface MyComponentProps {289 id: number;290 onAction?: () => void;291}292293export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {294 const [state, setState] = useState('');295296 const { data } = useSuspenseQuery<FeatureData>({297 queryKey: ['feature', id],298 queryFn: () => featureApi.getFeature(id),299 });300301 const handleAction = useCallback(() => {302 setState('updated');303 onAction?.();304 }, [onAction]);305306 return (307 <Box sx={{ p: 2 }}>308 <Paper sx={{ p: 3 }}>309 {/* Content */}310 </Paper>311 </Box>312 );313};314315export default MyComponent;316```317318---319320## 15. Anti-Patterns (Immediate Rejection)321322❌ Early loading returns323❌ Feature logic in `components/`324❌ Shared state via prop drilling instead of hooks325❌ Inline API calls326❌ Untyped responses327❌ Multiple responsibilities in one component328329---330331## 16. Integration With Other Skills332333* **frontend-design** → Visual systems & aesthetics334* **page-cro** → Layout hierarchy & conversion logic335* **analytics-tracking** → Event instrumentation336* **backend-dev-guidelines** → API contract alignment337* **error-tracking** → Runtime observability338339---340341## 17. Operator Validation Checklist342343Before finalizing code:344345* [ ] FFCI ≥ 6346* [ ] Suspense used correctly347* [ ] Feature boundaries respected348* [ ] No early returns349* [ ] Types explicit and correct350* [ ] Lazy loading applied351* [ ] Performance safe352353---354355## 18. Skill Status356357**Status:** Stable, opinionated, and enforceable358**Intended Use:** Production React codebases with long-term maintenance horizons359360
Full transparency — inspect the skill content before installing.