# Frontend Development Guidelines

> Best practices and coding standards for the Next.js + React project.

---

## Overview

This documentation serves as the single source of truth for frontend development within this project. It ensures consistency, maintainability, and high code quality across the team.

**Core Tech Stack:**
- **Framework**: Next.js (App Router)
- **Library**: React 18+
- **State Management**: Zustand
- **Styling**: SCSS (Scoped with unique root classes)
- **Type System**: TypeScript

---

## Guidelines Index

| Guide | Description | Status |
|-------|-------------|--------|
| [Directory Structure](./directory-structure.md) | Module organization, Next.js App Router layout, and naming rules. | ✅ Active |
| [Component Guidelines](./component-guidelines.md) | Naming, SCSS isolation, logic separation, and JSDoc standards. | ✅ Active |
| [Hook Guidelines](./hook-guidelines.md) | Business logic extraction, utility hooks, and naming conventions. | ✅ Active |
| [State Management](./state-management.md) | Usage of useState vs. Context vs. Zustand and persistence rules. | ✅ Active |
| [Type Safety](./type-safety.md) | Rules for Interfaces vs. Types, Generic usage, and API typing. | ✅ Active |
| [Quality Guidelines](./quality-guidelines.md) | Async patterns, defensive programming, and React best practices. | ✅ Active |

---

## How to Use These Guidelines

1.  **New Features**: Before starting a new module, review the [Directory Structure](./directory-structure.md) to ensure correct placement.
2.  **Code Reviews**: Use these documents as a checklist during PR reviews to ensure all code meets the project standards.
3.  **Development**: Follow the [Component Guidelines](./component-guidelines.md) for styling and logic extraction to keep the codebase clean.
4.  **AI Assistance**: Provide these documents to AI coding assistants to help them generate code that matches our project's specific style.

---

## Maintenance

These guidelines are not static. If you encounter a pattern that is more efficient or discover a recurring mistake not covered here:
- Discuss the change with the lead developer.
- Update the relevant `.md` file with examples.
- Notify the team of the update.

---

**Language**: All documentation and code comments must be written in **English**.