feature-sliced-design

What this skill does

# Feature-Sliced Design (FSD) Skill - v2.1.0

An architectural methodology skill for scaffolding and organizing frontend applications using Feature-Sliced Design principles.

## Overview

Feature-Sliced Design v2.1 is a compilation of rules and conventions for organizing frontend code to make projects more understandable, maintainable, and stable in the face of changing business requirements.

**Version 2.1 introduces the "Pages First" approach** - keeping more code in pages and widgets rather than prematurely extracting it to features and entities.

## Core Principles

### The "Pages First" Approach (FSD v2.1)

**The fundamental principle of FSD v2.1: Keep code where it's used until you need to reuse it.**

Instead of immediately extracting everything into entities and features, start by keeping code in pages and widgets. Only move code to lower layers when you actually need to reuse it.

#### What stays in Pages and Widgets:

✅ **Large UI blocks** that are only used on one page
✅ **Forms and their validation logic** specific to a page
✅ **Data fetching and state management** for page-specific data
✅ **Business logic** that serves only this page/widget
✅ **API interactions** needed only here

#### When to extract to lower layers:

- **To Shared**: When you need the same *infrastructure* in multiple places (modal manager, date formatter, UI components)
- **To Entities**: When you have a clear *business domain model* that's used across multiple features
- **To Features**: When you have a complete *user interaction* that's reused in multiple places

#### Why "Pages First"?

1. **Better code cohesion** - related code stays together
2. **Easier to delete** - unused code is right there with its usage
3. **Less abstraction overhead** - no need to identify entities/features prematurely
4. **Natural decomposition** - pages are intuitive to understand
5. **Faster development** - no time wasted on premature optimization

### 1. Layered Architecture (Vertical Organization)

FSD uses **6 active standardized layers** organized by responsibility and dependencies. Layers are ordered from most specific (top) to most generic (bottom):

```
app/           ← Application initialization, providers, global styles
pages/         ← Full page compositions with their own logic, routing
widgets/       ← Large composite UI blocks with their own logic
features/      ← Reusable user interactions and business features
entities/      ← Reusable business entities (user, product, order)
shared/        ← Reusable infrastructure code (UI kit, utils, API)
```

**Note**: Historically, FSD included `processes/` as a 7th layer, but it is **deprecated** in v2.1. If you're using it, move the code to `features/` with help from `app/` if needed.

**Import Rule**: A module can only import from layers **strictly below** it.
- ✅ `features/` → `entities/`, `shared/`
- ✅ `pages/` → `widgets/`, `features/`, `entities/`, `shared/`
- ❌ `entities/` → `features/` (upward import)
- ❌ `features/comments/` → `features/posts/` (same-layer cross-import)

### 2. Slices (Horizontal Organization)

Slices group code by **business domain meaning**. Each slice represents a specific business concept:

```
features/
  ├── auth/           ← Authentication feature
  ├── comments/       ← Comments functionality
  └── post-editor/    ← Post editing feature

entities/
  ├── user/           ← User business entity
  ├── product/        ← Product business entity
  └── order/          ← Order business entity
```

**Key Rules**:
- Slices must be **independent** from other slices on the same layer (zero coupling)
- Slices should contain **most code related to their primary goal** (high cohesion)
- Slice names are **not standardized** - they reflect your business domain

### 3. Segments (Technical Organization)

Segments group code within slices by **technical purpose**:

```
features/
  └── auth/
      ├── ui/         ← React components, styles, formatters
      ├── api/        ← API requests, data types, mappers
      ├── model/      ← State management, business logic, stores
      ├── lib/        ← Internal utilities for this slice
      ├── config/     ← Configuration, feature flags
      └── index.ts    ← Public API (exports only what other slices need)
```

**Standard Segments**:
- `ui` - UI components, styles, date formatters
- `api` - Backend interactions, request functions, data types
- `model` - Data models, state stores, business logic
- `lib` - Utility functions needed by this slice
- `config` - Configuration files, feature flags

### 4. Public API

Every slice must define a **public API** through an index file:

```typescript
// features/auth/index.ts
export { LoginForm } from './ui/LoginForm';
export { useAuth } from './model/useAuth';
export { loginUser } from './api/loginUser';
// Internal files not exported remain private to the slice
```

**Rule**: Modules outside a slice can **only import from the public API**, not from internal files.

#### Public API for Cross-Imports (@x notation)

**New in v2.1**: You can now create explicit connections between slices on the same layer (typically entities) using the `@x` notation.

This allows entities to reference each other when there's a legitimate business relationship:

```typescript
// entities/user/index.ts
export { UserCard } from './ui/UserCard';
export { userModel } from './model';

// entities/user/@x/order.ts
// Cross-import API specifically for the order entity
export { UserOrderHistory } from './ui/UserOrderHistory';
export { getUserOrders } from './api/getUserOrders';

// entities/order/index.ts
import { UserOrderHistory } from '@/entities/user/@x/order';
// Now order can import from user's cross-import API
```

**When to use cross-imports**:
- There's a clear business relationship between entities (e.g., User and Order)
- The dependency is bidirectional or circular in the business domain
- You want to keep the code together while acknowledging the relationship

**Important**: Regular cross-imports between slices (without `@x`) are still not allowed. Use `@x` notation to make cross-dependencies explicit and controlled.

## Layer Definitions & Examples

### App Layer
Application-wide settings, providers, routing setup.

```
app/
  ├── providers/      ← Redux Provider, React Query, Theme Provider
  ├── styles/         ← Global CSS, resets, theme variables
  ├── index.tsx       ← Application entry point
  └── router.tsx      ← Route configuration
```

### Pages Layer
Route-level compositions with their own logic and data management.

```
pages/
  ├── home/
  │   ├── ui/
  │   │   ├── HomePage.tsx
  │   │   ├── HeroSection.tsx      ← Large UI blocks
  │   │   └── FeaturesGrid.tsx
  │   ├── model/
  │   │   └── useHomeData.ts       ← Page-specific state
  │   ├── api/
  │   │   └── fetchHomeData.ts     ← Page-specific API
  │   └── index.ts
  ├── profile/
  │   ├── ui/
  │   │   ├── ProfilePage.tsx
  │   │   ├── ProfileForm.tsx      ← Forms specific to this page
  │   │   └── ProfileStats.tsx
  │   ├── model/
  │   │   ├── profileStore.ts      ← State for profile page
  │   │   └── validation.ts        ← Form validation
  │   ├── api/
  │   │   ├── updateProfile.ts
  │   │   └── fetchProfile.ts
  │   └── index.ts
  └── settings/
```

**v2.1 Approach**: Pages can now contain:
- ✅ Large UI blocks used only on this page
- ✅ Forms and their validation logic
- ✅ Data fetching and state management
- ✅ Business logic that serves only this page
- ✅ API interactions specific to this page

**Only extract to lower layers when you need to reuse the code elsewhere.**

### Widgets Layer
Complex, composite UI blocks with their own logic, used across multiple pages.

```
widgets/
  ├── header/
  │   ├── ui/
  │   │   ├── Header.tsx
  │   │   ├── Navigation.tsx
  │   │   └── UserMenu.tsx
  │   ├── model/
  │   │   └── headerStore.ts       ← Widget state
  │   ├── api/
  │   │   └── fetchNotifications.ts ← Widget-specific API
  │   └── index.ts
  ├── sidebar/
  │   ├── ui/
  │