# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ViteKit Universal - современный универсальный сборщик проектов с Vite + Twig + компонентами. Полнофункциональная система для быстрой разработки веб-приложений с готовыми UI компонентами и модульной архитектурой.

## Common Commands

```bash
# Development
npm run dev          # Запуск сервера разработки (localhost:3000)
npm run build        # Сборка для продакшена
npm run preview      # Предварительный просмотр сборки

# Code Quality
npm run lint         # ESLint проверка JavaScript
npm run lint:fix     # Автоисправление ESLint
npm run lint:css     # Stylelint проверка SCSS
npm run lint:css:fix # Автоисправление Stylelint
npm run format       # Prettier форматирование всех файлов

# Utilities
npm run clean        # Очистка папки dist
```

## Project Architecture

### Technology Stack
- **Vite** - быстрый сборщик с HMR
- **@vituum/vite-plugin-twig** - поддержка Twig шаблонов
- **SCSS** - CSS препроцессор с модульной архитектурой
- **Vanilla JavaScript** - нативный JS без фреймворков
- **MicroModal** - доступные модальные окна (~1.9kb)
- **Toastify** - уведомления

### Directory Structure
```
src/
├── components/         # UI компоненты (modal, tabs, accordion, toast)
├── layouts/           # Twig шаблоны (base.twig)
├── pages/             # Страницы (index.twig, components-demo.twig) 
├── data/              # JSON данные для Twig
├── assets/            # Статические ресурсы (images, icons, fonts)
├── styles/            # SCSS архитектура
│   ├── abstracts/     # Variables, mixins
│   ├── base/          # Reset, typography
│   ├── components/    # Component styles
│   ├── layout/        # Layout styles
│   └── pages/         # Page-specific styles
└── scripts/           # JavaScript модули
    ├── components/    # UI component logic
    └── utils/         # Utilities and helpers
```

### Component System
- **Модульная архитектура** - каждый компонент изолирован
- **Data attributes** - инициализация через `data-*` атрибуты
- **Event-driven** - компоненты используют custom events
- **Accessibility** - полная поддержка ARIA и клавиатурной навигации
- **Responsive** - адаптивное поведение (табы → аккордеон на мобильных)

### SCSS Architecture
- **Abstracts**: переменные, миксины, функции
- **Base**: reset, типографика, базовые стили
- **Components**: стили UI компонентов
- **Layout**: сетка, контейнеры, навигация
- **Pages**: специфичные стили страниц

### Key Features
- Автоматическая оптимизация изображений
- SVG sprite injection для иконок
- Live reload и HMR
- Code splitting и tree shaking
- Legacy browser support
- Automated linting с pre-commit hooks

## Development Guidelines

### Adding New Components
1. Создать SCSS в `src/styles/components/_component.scss`
2. Создать JS в `src/scripts/components/component.js`
3. Добавить импорт в `src/styles/main.scss`
4. Добавить в компонентную систему через data attributes

### Twig Development
- Использовать JSON данные из `src/data/` для динамического контента
- Шаблоны наследуются от `layouts/base.twig`
- Все страницы автоматически обрабатываются Vite

### SCSS Best Practices
- Использовать предопределенные миксины для медиа-запросов
- Следовать БЭМ методологии для классов
- Использовать CSS custom properties для динамических значений
- Все цвета и размеры через переменные

### JavaScript Guidelines
- ES6+ modules с импортами
- Page Controller Pattern для архитектуры
- Event-driven компоненты через EventBus
- Класс-ориентированные компоненты наследуются от Component
- Performance monitoring встроен
- Graceful degradation без JavaScript

## Testing & Deployment

### Quality Assurance
- ESLint + Prettier для JavaScript
- Stylelint для SCSS
- Husky pre-commit hooks
- Автоматическое форматирование

### Build Process
- Vite handles bundling and optimization
- Automatic asset optimization (images, SVG)
- CSS/JS minification and tree shaking
- Legacy browser polyfills via @vitejs/plugin-legacy

### Performance Optimization
- Image optimization с vite-plugin-image-optimizer
- SVG sprite generation для иконок
- CSS/JS code splitting
- Preload critical resources

## Page Controller Architecture

### Создание нового page controller
```javascript
// src/scripts/pages/mypage.js
import { Component } from '../core/Component.js';
import { eventBus } from '../core/EventBus.js';

export default class MyPage extends Component {
  constructor() {
    super(document.body);
  }

  beforeInit() {
    // Инициализация перед загрузкой
  }

  bindEvents() {
    // Привязка событий страницы
  }

  afterInit() {
    // Действия после инициализации
  }
}
```

### Page detection
- Автоматическое определение по filename (mypage.html → mypage.js)
- Или через data-page атрибут: `<body data-page="custom-name">`

### Component API
```javascript
// Создание компонента
const myComponent = Component.create(element, options);

// EventBus для связи между компонентами
eventBus.on('custom:event', callback);
eventBus.emit('custom:event', data);

// Performance monitoring
performanceMonitor.mark('my-action');
performanceMonitor.measure('my-action', 'start-mark', 'end-mark');
```

### Utilities
```javascript
// DOM utilities
import { ready, createElement, scrollToElement } from '@scripts/utils/dom.js';

// Performance utilities  
import { debounce, throttle, memoize } from '@scripts/utils/performance.js';

// Helper utilities
import { deepClone, formatDate, copyToClipboard } from '@scripts/utils/helpers.js';
```

## Special Considerations

- Команды терминала запускаются в фоновом режиме (не используйте циклические команды)
- Все пути используют алиасы (@, @styles, @components, @scripts, @assets)
- Responsive-first подход с мобильными брейкпоинтами
- Accessibility-first разработка с ARIA и keyboard support
- Page controllers загружаются автоматически по имени файла/страницы
- Используйте EventBus для связи между компонентами разных страниц