From 12e86ef7f193772069302475c89f82030e2eb82e Mon Sep 17 00:00:00 2001 From: StanisLove Date: Fri, 2 Jan 2026 16:43:29 +0300 Subject: [PATCH] feat: add docs --- ARCHITECTURE.md | 47 ++++++++++++++++ CONVENTIONS.md | 62 +++++++++++++++++++++ EXAMPLES.md | 87 +++++++++++++++++++++++++++++ README.md | 145 +++++++++++++++++------------------------------- 4 files changed, 246 insertions(+), 95 deletions(-) create mode 100644 ARCHITECTURE.md create mode 100644 CONVENTIONS.md create mode 100644 EXAMPLES.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..cc1c8b2 --- /dev/null +++ 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 diff --git a/CONVENTIONS.md b/CONVENTIONS.md new file mode 100644 index 0000000..fea6017 --- /dev/null +++ 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
{title}
; +} +``` + +## 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'; + + + ); +} +``` + +## Анимации + +### Fade in + Slide up + +```typescript + + Content + +``` diff --git a/README.md b/README.md index 4a8484e..8e2ed5e 100644 --- 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 ( - - Анимированный контент - +
+ +
); } ``` -Документация: [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)