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/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,47 @@
+src/
+├── app/
+│ ├── layout.tsx # Root layout с провайдерами
+│ ├── page.tsx # Главная страница
+│ └── globals.css # Глобальные стили + CSS переменные
+│
+├── widgets/ # Композитные секции
+│ ├── header.tsx
+│ ├── hero-section.tsx
+│ ├── features-section.tsx
+│ ├── stats-section.tsx
+│ ├── how-it-works-section.tsx
+│ ├── comparison-section.tsx
+│ ├── gallery-section.tsx
+│ ├── social-proof-section.tsx
+│ ├── team-section.tsx
+│ ├── pricing-section.tsx
+│ ├── faq-section.tsx
+│ ├── cta-section.tsx
+│ └── footer.tsx
+│
+├── features/ # Переиспользуемые блоки
+│ ├── section-container.tsx
+│ ├── section-header.tsx
+│ ├── gradient-background.tsx
+│ ├── feature-card.tsx
+│ ├── testimonial-card.tsx
+│ ├── pricing-card.tsx
+│ ├── stat-card.tsx
+│ ├── step-card.tsx
+│ ├── team-member-card.tsx
+│ ├── comparison-item.tsx
+│ ├── portfolio-item.tsx
+│ └── logo-cloud.tsx
+│
+└── shared/ # Общий код
+├── ui/ # shadcn/ui компоненты
+│ ├── button.tsx
+│ ├── card.tsx
+│ ├── input.tsx
+│ └── ... (50+ компонентов)
+├── hooks/
+│ ├── use-in-view.ts
+│ ├── use-scroll-animation.ts
+│ └── theme-provider.tsx
+└── lib/
+└── utils.ts
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -0,0 +1,62 @@
+# 📐 Coding Conventions
+
+## Именование
+
+- **Компоненты:** PascalCase (`Button.tsx`)
+- **Утилиты:** kebab-case (`format-date.ts`)
+- **Хуки:** camelCase с use (`useInView.ts`)
+
+```typescript
+const userName = "John";
+const MAX_RETRIES = 3;
+```
+
+## Структура компонента
+
+```typescript
+"use client";
+
+import { Button } from "@/shared/ui/button";
+
+interface MyComponentProps {
+  title: string;
+}
+
+export function MyComponent({ title }: MyComponentProps) {
+  return <div>{title}</div>;
+}
+```
+
+## TypeScript
+
+Всегда типизируйте props:
+
+```typescript
+interface ButtonProps {
+  children: React.ReactNode;
+  variant?: "primary" | "secondary";
+}
+```
+
+## Импорты
+
+Порядок: React → Внешние → Наши (@/...)
+
+```typescript
+import { useState } from "react";
+import { motion } from "framer-motion";
+import { Button } from "@/shared/ui/button";
+```
+
+**ВСЕГДА используйте @/ для абсолютных импортов.**
+
+## Стилизация
+
+Порядок Tailwind: Layout → Sizing → Spacing → Typography → Colors
+
+Условные классы через cn():
+
+```typescript
+import { cn } from '@/shared/lib/utils';
+<button className={cn('px-4 py-2', variant === 'primary' && 'bg-primary')}>
+```
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -0,0 +1,87 @@
+# 📝 Code Examples
+
+## Создание компонента
+
+### Feature компонент
+
+```typescript
+// features/your-card.tsx
+"use client";
+
+import { motion } from "framer-motion";
+import { Card } from "@/shared/ui/card";
+
+interface YourCardProps {
+  title: string;
+  description: string;
+}
+
+export function YourCard({ title, description }: YourCardProps) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 20 }}
+      whileInView={{ opacity: 1, y: 0 }}
+      viewport={{ once: true }}
+    >
+      <Card className="p-6">
+        <h3 className="text-2xl font-bold">{title}</h3>
+        <p>{description}</p>
+      </Card>
+    </motion.div>
+  );
+}
+```
+
+### Widget секция
+
+```typescript
+// widgets/your-section.tsx
+"use client";
+
+import { SectionContainer } from "@/features/section-container";
+import { SectionHeader } from "@/features/section-header";
+
+export function YourSection() {
+  return (
+    <SectionContainer id="your-section">
+      <SectionHeader title="Заголовок" withGradient />
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+        {/* Контент */}
+      </div>
+    </SectionContainer>
+  );
+}
+```
+
+## Работа с состоянием
+
+```typescript
+"use client";
+
+import { useState } from "react";
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+    </div>
+  );
+}
+```
+
+## Анимации
+
+### Fade in + Slide up
+
+```typescript
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true }}
+  transition={{ duration: 0.5 }}
+>
+  Content
+</motion.div>
+```
--- 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**:

-## Быстрый старт
-
-1. Установите зависимости:
-   ```bash
-   pnpm install
 ```
-2. Запустите дев-сервер:
-   ```bash
-   pnpm dev
+src/
+├── app/              # Слой приложения
+├── widgets/          # Композитные секции
+├── features/         # Переиспользуемые блоки
+└── shared/           # Общий код (UI-kit, хуки)
 ```
-3. Откройте `http://localhost:3000` в браузере.

-## Структура проекта (основное)
+**Принципы:** Слоистая архитектура, изолированность, переиспользование.

- `src/app/(frontend)`: публичные страницы, глобальные стили (`globals.css`), макеты и корневые компоненты фронтенда.
- `src/shared/ui`: библиотека переиспользуемых UI-компонентов на базе shadcn/ui.
- `src/shared/lib`: утилиты и вспомогательные функции.
+## 🛠 Технологии

-## Архитектура: Feature‑Sliced Design (FSD)
+- **Next.js 14** - React framework
+- **TypeScript** - Type safety
+- **Tailwind CSS 4** - Utility-first CSS
+- **Framer Motion** - Анимации
+- **shadcn/ui** - UI компоненты

-Проект следует принципам **Feature‑Sliced Design** для масштабируемой фронтенд-архитектуры. Подробнее: [feature-sliced.design/docs](https://feature-sliced.design/docs).
+## 📁 Структура

- **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`).
+```
+src/
+├── app/              # layout.tsx, page.tsx, globals.css
+├── widgets/          # header, hero-section, features-section
+├── features/         # section-container, feature-card
+└── shared/           # ui/, hooks/, lib/
+```

-Рекомендации:
+## 🧩 Паттерны компонентов

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

-## Соглашения по наименованию
+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)