Frontend Dev Guidelines

# 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

* `useSuspenseQuery` is the **primary** data-fetching hook

* No `isLoading` conditionals

* 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 type` always

* Types are first-class design artifacts

---

3. When to Use This Skill

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

---

4. Quick Start Checklists

New Component Checklist

* [ ] `React.FC<Props>` with explicit props interface

* [ ] Lazy loaded if non-trivial

* [ ] Wrapped in `<SuspenseLoader>`

* [ ] Uses `useSuspenseQuery` for data

* [ ] No early returns

* [ ] Handlers wrapped in `useCallback`

* [ ] Styles inline if <100 lines

* [ ] Default export at bottom

* [ ] Uses `useMuiSnackbar` for 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/`

---

5. 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.

---

6. Component Standards

Required Structure Order

1. Types / Props

2. Hooks

3. Derived values (`useMemo`)

4. Handlers (`useCallback`)

5. Render

6. Default export

Lazy Loading Pattern

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

Al