---

name: frontend-design-patterns description: Enterprise React architecture combining DDD and FSD patterns. Use when (1) designing or structuring React applications, (2) implementing Index/Types/Styles component pattern, (3) setting up Service/Hook 1:1 mapping with React Query and Axios, (4) configuring Zustand state management, (5) applying TypeScript conventions for maintainable codebases. Triggers include architectural decisions, folder structure planning, data layer design, and code organization tasks.

Frontend Design Patterns

Enterprise-grade React architecture combining Domain-Driven Design (DDD) and Feature-Sliced Design (FSD) with strict TypeScript conventions.

Core Patterns

1. DDD + FSD Hybrid Architecture

• Philosophy: Think in domains, not pages
• Structure: Layered architecture with unidirectional dependencies
• Key Concept: Features (user actions) vs Entities (data representation)

Reference: See references/ddd-fsd-fundamentals.md for detailed DDD/FSD fusion strategy.

2. FSD Layer Hierarchy

CopyApp -> Pages -> Widgets -> Features -> Entities -> Shared

Each layer only depends on layers below it. No upward dependencies.

• Slices: Domain-based directories (e.g., features/cart, features/auth)
• Segments: ui/, model/, api/, lib/, config/, index.ts

Reference: See references/fsd-layers-guide.md for complete layer definitions.

3. Component Structure: Index/Types/Styles

CopyComponentName/
├── index.tsx    # React logic & JSX
├── types.ts     # TypeScript interfaces
└── styles.ts    # CSS-in-JS (Emotion/styled-components)

Separates concerns at filesystem level. Improves collaboration and reduces merge conflicts.

Reference: See references/component-structure.md for implementation details.

4. Data Layer: Service/Hook 1:1 Mapping

CopyService Layer (Pure TS) -> Hook Layer (React Query) -> Components

• Service: API calls, DTOs (React-agnostic)
• Hook: React Query integration, caching, loading/error states
• Rule: One service function = one custom hook
• Query Keys: Use factory pattern

Reference: See references/data-layer-architecture.md for Axios/React Query setup.

5. State Management: Zustand + React Query

• React Query: Server state (API data, caching)
• Zustand: Client state (theme, modals, complex forms)
• Store Location: Domain-specific in model/ segment
• Pattern: Slice pattern with selector optimization

Reference: See references/state-management.md for Zustand patterns.

6. TypeScript Conventions

Reference: See references/typescript-conventions.md for complete rules.

Workflow

Load references based on current task:

Scripts

Create FSD Structure

Copypython scripts/create_fsd_structure.py <project-root> [--slices cart auth user]

Creates complete FSD folder structure with standard segments.

Create Component

Copypython scripts/create_component.py <path> <ComponentName>

Generates Index/Types/Styles pattern component.

Create Service/Hook Pair

Copypython scripts/create_service_hook.py <feature-path> <service-name>

Generates Service Layer + Hook Layer with Query Key factory.

Create Zustand Store

Copypython scripts/create_zustand_store.py <feature-path> <store-name>

Generates Zustand store with selectors and actions.

Key Principles

1. Separation of Concerns: UI, logic, styles separated at filesystem level
2. Unidirectional Dependencies: Layers only depend on lower layers
3. Explicit Dependencies: No circular references
4. Type Safety: Strict TypeScript, no any
5. Single Responsibility: Each file/module has one clear purpose