Instruction file imported from Kriptomeen/Cursor-memory-Bank-NEXTJSV2 (.cursor/rules/css.mdc). Copyright stays with the author.

description: globs: /*.css,/.tsx,**/.jsx alwaysApply: false

Rule Type: Auto Select+desc description: Стандарты и лучшие практики для CSS и Tailwind CSS в ПРОЕКТЕ_ЗАПОЛНИТЕЛЬ. Применяется при работе с файлами стилей и JSX/TSX компонентами, использующими Tailwind. globs: "/*.css,/.tsx,**/.jsx" alwaysApply: false

CSS & Tailwind CSS Coding Standards & Best Practices (ПРОЕКТ_ЗАПОЛНИТЕЛЬ) - V2.1 (Template)

Применимость: Эти правила применяются при работе с CSS, включая использование фреймворка Tailwind CSS, либо через утилитарные классы в разметке HTML/JSX/TSX, либо внутри CSS-файлов (.css) с использованием директив Tailwind в проекте ПРОЕКТ_ЗАПОЛНИТЕЛЬ.

1. Подход "Tailwind First" (Tailwind в первую очередь)

• 1.1. Приоритет утилитам: В ПЕРВУЮ ОЧЕРЕДЬ используйте утилитарные классы Tailwind CSS непосредственно в вашей разметке JSX/TSX для стилизации.
  • Избегайте написания кастомных CSS-классов для простых задач стилизации, которые легко достигаются существующими утилитами Tailwind.
  • Обоснование (CoT): Это соответствует философии Tailwind, улучшает консистентность, уменьшает размер CSS-бандла (благодаря JIT) и упрощает понимание стилей непосредственно из разметки.

  // Хорошо: Использование утилит Tailwind
  <Button className="bg-primary hover:bg-primary/90 text-primary-foreground font-semibold py-2 px-4 rounded shadow-md transition-colors duration-150">
    Сохранить Изменения
  </Button>
  
  // Плохо: Создание кастомного класса для стилей, которые можно выразить утилитами
  <Button className="custom-save-button-styles">Сохранить Изменения</Button>
  /* globals.css или аналогичный файл:
  .custom-save-button-styles {
    background-color: var(--primary); // Можно заменить на bg-primary
    color: var(--primary-foreground); // Можно заменить на text-primary-foreground
    padding: 0.5rem 1rem;        // Можно заменить на py-2 px-4
    border-radius: 0.25rem;      // Можно заменить на rounded
    // ... и так далее
  }
  */

• 1.2. Конфигурация (tailwind.config.js или аналогичный):
  • Кастомизация Темы: Все специфичные для проекта ПРОЕКТ_ЗАПОЛНИТЕЛЬ дизайн-токены (например, основные цвета primary, secondary, destructive; кастомные отступы; размеры шрифтов; точки останова) ДОЛЖНЫ быть определены внутри объекта theme.extend в файле конфигурации Tailwind.
  • Используйте эти сконфигурированные значения через соответствующие утилиты Tailwind (например, bg-primary, text-destructive, p-custom-spacing).
  • Extend vs Override: Предпочитайте расширение (extend) дефолтной темы Tailwind, а не полное ее переопределение, чтобы сохранить доступ к стандартным утилитам.
• 1.3. Just-In-Time (JIT) Engine:
  • Убедитесь, что все полные имена классов присутствуют в файлах, сканируемых JIT-компилятором (настраивается в content в файле конфигурации Tailwind).
  • Избегайте динамической конкатенации имен классов таким образом, чтобы JIT не мог их обнаружить (например, className={bg-${цветПеременная}-500} - JIT это не увидит). Вместо этого используйте полное перечисление классов или маппинг объекта на классы, как в примере с clsx`.

2. Написание Кастомного CSS с Использованием Директив Tailwind

• 2.1. Когда Писать Кастомный CSS: Только в случаях, когда это действительно необходимо и обоснованно:
  • Для создания переиспользуемых абстракций компонентов, где набор утилит становится слишком длинным или повторяющимся (см. использование @apply).
  • Для сложных макетов или специфических эффектов, которые трудно или невозможно чисто реализовать утилитами (например, некоторые виды градиентов, сложные анимации).
  • Для определения базовых стилей элементов HTML (@layer base), таких как сброс стилей браузера или установка дефолтных шрифтов и цветов для body, заголовков, ссылок.
  • Для стилей, которые не могут быть применены через классы (например, стили для ::selection, ::placeholder на глобальном уровне, если не управляются плагинами).
• 2.2. Использование @apply:
  • Применяйте @apply ОСТОРОЖНО и ОГРАНИЧЕННО внутри CSS-файлов (например, globals.css) для извлечения общих, часто повторяющихся паттернов утилит в переиспользуемые компонентные классы.
  • Избегайте чрезмерного использования @apply для простых случаев или для создания классов, которые по сути дублируют одну-две утилиты. Это противоречит философии Tailwind и может привести к раздуванию CSS.
  • Обоснование (CoT): @apply полезен для инкапсуляции стилей компонента в одном месте, но его избыточное применение может привести к тем же проблемам, что и традиционный CSS (сложность поддержки, конфликты).

  /* Хорошо: Абстрагирование сложного паттерна для компонента */
  .btn-primary-kgp { /* KGP - префикс для ПРОЕКТА_ЗАПОЛНИТЕЛЬ */
    @apply bg-primary text-primary-foreground font-semibold py-2 px-4 rounded shadow-md hover:bg-primary/90 transition-colors duration-150;
  }
  
  /* Плохо: Простое оборачивание одной-двух утилит */
  .text-error-kgp {
     @apply text-destructive; /* Лучше использовать text-destructive напрямую в разметке */
  }

• 2.3. Использование @layer:
  • Организуйте кастомный CSS, используя директивы @layer base, @layer components, @layer utilities для управления порядком генерации CSS и специфичностью.

  /* В вашем основном CSS файле, например, globals.css */
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  
  @layer base {
    body {
      @apply bg-background text-foreground font-sans antialiased;
    }
    /* Другие базовые стили для HTML-элементов */
  }
  
  @layer components {
    .card-kgp { /* Пример компонентного класса */
      @apply bg-card text-card-foreground rounded-lg border shadow-sm p-6;
    }
  }
  
  /* @layer utilities - обычно используется Tailwind плагинами или для очень специфичных кастомных утилит */

• 2.4. Использование theme():
  • Для доступа к значениям из tailwind.config.js (например, цветам, отступам) внутри ваших кастомных CSS-правил используйте функцию theme().

  .custom-border-color {
    border-color: theme('colors.primary');
  }

3. Читаемость и Поддерживаемость при Использовании Утилит

• 3.1. Абстракция Компонентов (React):
  • Если элемент в JSX/TSX имеет длинный список утилитарных классов, инкапсулируйте его в отдельный, хорошо именованный React-компонент. Это улучшает читаемость родительского компонента и способствует переиспользованию.
• 3.2. Форматирование Длинных Списков Классов:
  • Используйте Prettier с плагином prettier-plugin-tailwindcss. Он автоматически сортирует классы Tailwind в рекомендованном порядке, что значительно улучшает читаемость и предсказуемость.
• 3.3. Условное Применение Классов:
  • Используйте библиотеку clsx (или classnames) или шаблонные строки для чистого и читаемого условного применения классов.

  import clsx from 'clsx';
  
  interface StatusBadgeProps {
    status: 'PENDING' | 'ACTIVE' | 'INACTIVE'; // Используйте конкретные типы статусов
    className?: string;
  }
  
  function StatusBadge({ status, className }: StatusBadgeProps) {
    const baseClasses = 'px-2.5 py-0.5 rounded-full text-xs font-semibold inline-block';
    const statusClasses = clsx({
      'bg-yellow-100 text-yellow-800': status === 'PENDING',
      'bg-green-100 text-green-800': status === 'ACTIVE',
      'bg-gray-100 text-gray-800': status === 'INACTIVE',
    });
    return <span className={clsx(baseClasses, statusClasses, className)}>{status}</span>;
  }

4. Общие Лучшие Практики CSS

• 4.1. Специфичность: Старайтесь минимизировать специфичность селекторов. Использование @layer помогает управлять этим в контексте Tailwind.
• 4.2. Избегайте !important: Используйте !important только в крайних случаях, когда это абсолютно необходимо для переопределения стилей из сторонних библиотек или очень специфичных утилитарных нужд. Tailwind предоставляет ! префикс для утилит (например, !bg-red-500), который следует использовать с такой же осторожностью.
• 4.3. Комментарии: Используйте CSS-комментарии (/* ... */) для объяснения нетривиальных стилей или организации секций в ваших кастомных CSS файлах.
• 4.4. CSS Переменные (Custom Properties):
  • Активно используйте CSS Custom Properties, определенные в :root (обычно в globals.css) или на уровне компонентов, для легко настраиваемых и тематизируемых значений (цвета, отступы, размеры шрифтов), особенно если они используются в нескольких местах или должны динамически изменяться. Tailwind CSS сам хорошо работает с CSS переменными для цветов.
• 4.5. Доступность (Accessibility - A11y):
  • Всегда обеспечивайте правильные и заметные стили для состояний фокуса (focus:, focus-visible:).
  • Используйте утилиты motion-safe: и motion-reduce: для управления анимациями и переходами в зависимости от предпочтений пользователя.
• 4.6. Вендорные Префиксы: При написании кастомного CSS (вне @apply) полагайтесь на Autoprefixer (обычно интегрирован в процесс сборки Next.js) для автоматического добавления вендорных префиксов. Не добавляйте их вручную.

Цель этих правил – обеспечить консистентный, поддерживаемый, производительный и доступный подход к стилизации в проекте ПРОЕКТ_ЗАПОЛНИТЕЛЬ, максимально используя преимущества Tailwind CSS.