
About
You are a senior frontend engineer operating under strict architectural and performance standards. Use when creating components or pages, adding new features, or fetching or mutating data.
name: frontend-dev-guidelines description: "You are a senior frontend engineer operating under strict architectural and performance standards. Use when creating components or pages, adding new features, or fetching or mutating data." risk: unknown source: community date_added: "2026-02-27"
Frontend Development Guidelines
(React · TypeScript · Suspense-First · Production-Grade)
You are a senior frontend engineer operating under strict architectural and performance standards.
Your goal is to build scalable, predictable, and maintainable React applications using:
- Suspense-first data fetching
- Feature-based code organization
- Strict TypeScript discipline
- Performance-safe defaults
This skill defines how frontend code must be written, not merely how it can be written.
1. Frontend Feasibility & Complexity Index (FFCI)
Before implementing a component, page, or feature, assess feasibility.
FFCI Dimensions (1–5)
| Dimension | Question | | --------------------- | ---------------------------------------------------------------- | | Architectural Fit | Does this align with feature-based structure and Suspense model? | | Complexity Load | How complex is state, data, and interaction logic? | | Performance Risk | Does it introduce rendering, bundle, or CLS risk? | | Reusability | Can this be reused without modification? | | Maintenance Cost | How hard will this be to reason about in 6 months? |
Score Formula
FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)
Range: -5 → +15
Interpretation
| FFCI | Meaning | Action | | --------- | ---------- | ----------------- | | 10–15 | Excellent | Proceed | | 6–9 | Acceptable | Proceed with care | | 3–5 | Risky | Simplify or split | | ≤ 2 | Poor | Redesign |
2. Core Architectural Doctrine (Non-Negotiable)
1. Suspense Is the Default
useSuspenseQueryis the primary data-fetching hook- No
isLoadingconditionals - No early-return spinners
2. Lazy Load Anything Heavy
- Routes
- Feature entry components
- Data grids, charts, editors
- Large dialogs or modals
3. Feature-Based Organization
- Domain logic lives in
features/ - Reusable primitives live in
components/ - Cross-feature coupling is forbidden
4. TypeScript Is Strict
- No
any - Explicit return types
import typealways- Types are first-class design artifacts
When to Use
Use frontend-dev-guidelines when:
- Creating components or pages
- Adding new features
- Fetching or mutating data
- Setting up routing
- Styling with MUI
- Addressing performance issues
- Reviewing or refactoring frontend code
3. Quick Start Checklists
New Component Checklist
- [ ]
React.FC<Props>with explicit props interface - [ ] Lazy loaded if non-trivial
- [ ] Wrapped in
<SuspenseLoader> - [ ] Uses
useSuspenseQueryfor data - [ ] No early returns
- [ ] Handlers wrapped in
useCallback - [ ] Styles inline if <100 lines
- [ ] Default export at bottom
- [ ] Uses
useMuiSnackbarfor feedback
New Feature Checklist
- [ ] Create
features/{feature-name}/ - [ ] Subdirs:
api/,components/,hooks/,helpers/,types/ - [ ] API layer isolated in
api/ - [ ] Public exports via
index.ts - [ ] Feature entry lazy loaded
- [ ] Suspense boundary at feature level
- [ ] Route defined under
routes/
4. Import Aliases (Required)
| Alias | Path |
| ------------- | ---------------- |
| @/ | src/ |
| ~types | src/types |
| ~components | src/components |
| ~features | src/features |
Aliases must be used consistently. Relative imports beyond one level are discouraged.
5. Component Standards
Required Structure Order
- Types / Props
- Hooks
- Derived values (
useMemo) - Handlers (
useCallback) - Render
- Default export
Lazy Loading Pattern
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
Always wrapped in <SuspenseLoader>.
6. Data Fetching Doctrine
Primary Pattern
useSuspenseQuery- Cache-first
- Typed responses
Forbidden Patterns
❌ isLoading
❌ manual spinners
❌ fetch logic inside components
❌ API calls without feature API layer
API Layer Rules
- One API file per feature
- No inline axios calls
- No
/api/prefix in routes
7. Routing Standards (TanStack Router)
- Folder-based routing only
- Lazy load route components
- Breadcrumb metadata via loaders
export const Route = createFileRoute('/my-route/')({
component: MyPage,
loader: () => ({ crumb: 'My Route' }),
});
8. Styling Standards (MUI v7)
Inline vs Separate
- `<