feat: add docs

2026-01-02 16:43:29 +03:00
parent 202ac4627f
commit 12e86ef7f1
4 changed files with 246 additions and 95 deletions
--- a/README.md
+++ b/README.md
@@ -1,117 +1,72 @@
-## О проекте
+# 🚀 Универсальный шаблон лендинга TaskFlow

-Это проект на **Next.js** (App Router), использующий UI-компоненты **shadcn/ui**, утилитарную CSS-библиотеку **Tailwind CSS** и библиотеку анимаций **framer-motion**.
+Профессиональный шаблон продающей страницы по методологии **Feature-Sliced Design (FSD)**.

-## Стек и роль технологий
+## 📋 Архитектура

- **Next.js**: фреймворк для React с рендерингом на сервере, маршрутизацией и API-роутами.
-  - Документация: [nextjs.org/docs](https://nextjs.org/docs)
- **shadcn/ui**: коллекция доступных и настраиваемых компонентов на базе Radix UI и Tailwind.
-  - Документация: [ui.shadcn.com](https://ui.shadcn.com/)
- **Tailwind CSS**: утилитарные классы для быстрой стилизации интерфейсов.
-  - Документация: [tailwindcss.com/docs](https://tailwindcss.com/docs)
- **framer-motion**: мощная библиотека для анимаций в React-компонентах.
-  - Документация: [www.framer.com/motion](https://www.framer.com/motion)
+Проект построен по **FSD**:

-## Быстрый старт
+```
+src/
+├── app/              # Слой приложения
+├── widgets/          # Композитные секции
+├── features/         # Переиспользуемые блоки
+└── shared/           # Общий код (UI-kit, хуки)
+```

-1. Установите зависимости:
-   ```bash
-   pnpm install
-   ```
-2. Запустите дев-сервер:
-   ```bash
-   pnpm dev
-   ```
-3. Откройте `http://localhost:3000` в браузере.
+**Принципы:** Слоистая архитектура, изолированность, переиспользование.

-## Структура проекта (основное)
+## 🛠 Технологии

- `src/app/(frontend)`: публичные страницы, глобальные стили (`globals.css`), макеты и корневые компоненты фронтенда.
- `src/shared/ui`: библиотека переиспользуемых UI-компонентов на базе shadcn/ui.
- `src/shared/lib`: утилиты и вспомогательные функции.
+- **Next.js 14** - React framework
+- **TypeScript** - Type safety
+- **Tailwind CSS 4** - Utility-first CSS
+- **Framer Motion** - Анимации
+- **shadcn/ui** - UI компоненты

-## Архитектура: Feature‑Sliced Design (FSD)
+## 📁 Структура

-Проект следует принципам **Feature‑Sliced Design** для масштабируемой фронтенд-архитектуры. Подробнее: [feature-sliced.design/docs](https://feature-sliced.design/docs).
+```
+src/
+├── app/              # layout.tsx, page.tsx, globals.css
+├── widgets/          # header, hero-section, features-section
+├── features/         # section-container, feature-card
+└── shared/           # ui/, hooks/, lib/
+```

- **app**: инициализация приложения, провайдеры, глобальные стили и макеты (в проекте — `src/app`, в т.ч. `src/app/(frontend)`).
- **processes**: долгоживущие бизнес-процессы (слой появится при необходимости).
- **pages**: страницы и маршруты. В Next.js App Router это структурируется через `src/app` и сегменты маршрутов.
- **widgets**: составные блоки из нескольких features/entities (см. `src/widgets`).
- **features**: пользовательские сценарии и их логика/компоненты (см. `src/features`).
- **entities**: бизнес-сущности и их представления/модели (см. `src/entities`).
- **shared**: переиспользуемые модули, UI, утилиты, конфиги (см. `src/shared`).
+## 🧩 Паттерны компонентов

-Рекомендации:
+```typescript
+"use client";

- Импорты направлены сверху вниз: `shared → entities → shared → widgets → features → pages/app`.
- Публичный API каждого слайса/модуля экспортируется через `index`-файлы.
- Избегайте циклических зависимостей между слоями.
+import { Button } from "@/shared/ui/button";

-## Соглашения по наименованию
-
- Имена файлов компонентов: `kebab-case`.
-  - Примеры: `date-picker.tsx`, `user-card.tsx`, `navigation-menu.tsx`.
- Имена React-компонентов (идентификаторы): `PascalCase`.
-  - Примеры: `DatePicker`, `UserCard`, `NavigationMenu`.
-
-## UI на базе shadcn/ui
-
-Компоненты интерфейса собраны и переиспользуются в каталоге `src/shared/ui`. Они основаны на Tailwind и Radix UI, легко настраиваются через классы и токены дизайна. Рекомендуется ориентироваться на официальные примеры и паттерны из документации:
-
- Руководство и примеры: [ui.shadcn.com](https://ui.shadcn.com/)
-
-## Стилизация: Tailwind CSS
-
-Проект использует Tailwind для быстрой и согласованной стилизации. Ключевые ресурсы:
-
- Документация: [tailwindcss.com/docs](https://tailwindcss.com/docs)
- Руководства по best practices: [tailwindcss.com/blog](https://tailwindcss.com/blog)
-
-## Анимации: framer-motion
-
-Для анимаций используется `framer-motion`. Это мощная библиотека для создания плавных и производительных анимаций в React-компонентах.
-
-Пример использования:
-
-```tsx
-import { motion } from 'framer-motion';
-
-function AnimatedComponent() {
+export function MyFeature() {
  return (
-    <motion.div
-      initial={{ opacity: 0, y: 20 }}
-      animate={{ opacity: 1, y: 0 }}
-      transition={{ duration: 0.5 }}
-    >
-      Анимированный контент
-    </motion.div>
+    <section className="py-20">
+      <Button>Action</Button>
+    </section>
  );
 }
 ```

-Документация: [www.framer.com/motion](https://www.framer.com/motion)
+**Правила:** 'use client' для клиентских, @/ alias для импортов, PascalCase, Named exports.

-## Команды
+## 🎨 Стилизация
+
+Tailwind CSS 4 с CSS переменными в `globals.css`.
+
+## 📦 Импорты
+
+**ВСЕГДА используйте @/ alias:** `import { Button } from '@/shared/ui/button';`
+
+## 🎬 Анимации
+
+Framer Motion: `initial={{ opacity: 0, y: 20 }}` → `whileInView={{ opacity: 1, y: 0 }}`
+
+## 🚀 Команды

 ```bash
-# Запуск дев-сервера
-pnpm dev
-
-# Билд продакшн-версии
-pnpm build
-
-# Предпросмотр продакшн-сборки
-pnpm start
-
-# Линтинг
-pnpm lint
+pnpm dev      # Запуск dev сервера
+pnpm build    # Production build
 ```
-
-## Полезные ссылки
-
- Next.js: [nextjs.org/docs](https://nextjs.org/docs)
- shadcn/ui: [ui.shadcn.com](https://ui.shadcn.com/)
- Tailwind CSS: [tailwindcss.com/docs](https://tailwindcss.com/docs)
- framer-motion: [www.framer.com/motion](https://www.framer.com/motion)