sync

OLD_parts/11-css.md

@@ -0,0 +1,227 @@
+---
+title: CSS
+---
+
+# CSS
+
+## Правила оформления и стилизации CSS-кода
+
+- **Препроцессоры**  
+  Используй PostCSS и модули для стилизации.
+
+- **Архитектура написания стилей**  
+  Используй подход **Mobile First**  
+  Используй CSS переменные для стилизации.  
+  Используй Custom Media Queries для адаптивных стилей.  
+  Используй BEM для именования классов.  
+  Между каждым CSS-правилом (селектором) должен быть один пустой сброс строки, пример:
+  ```css
+  .todo-list {
+    max-width: 600px;
+    padding: var(--space-3);
+
+    @media (--md) {
+      max-width: 800px;
+    }
+  }
+
+  .todo-list__text {
+    font-size: 18px;
+
+    @media (--md) {
+      font-size: 22px;
+    }
+  }
+  ```
+  Запрещено писать правила подряд без пустой строки:
+  ```css
+  /* Так делать нельзя! */
+  .todo-list { ... }
+  .todo-list__text { ... }
+  ```
+
+- **Методология именования классов**  
+  Использовать методологию **BEM** для именования классов.
+    - Блок: kebab-case, пример `.user-bar { }`
+    - Елемент: kebab-case, соеденный с блоком двойным нижним подчеркиванием, пример `.user-bar__slide { }`
+    - Модификатор: kebab-case, отдельный самостоятельный класс, **не соединяется** с блоком/елементом, имя модификатора всегда начинается с нижнего подчеркивания, пример: `._red { }`
+
+- **Единицы измерения**  
+  Используй `px` как основная единица измирения, так-же допускается использовать остальные единицы измерения если того требует реализуемый дизайн.
+
+- **Импорт стилей**  
+  Стили компонента должны импортироваться только внутри соответствующего компонента.  
+  Запрещено импортировать стили одного компонента в другой.
+  Запрещено импортировать `css переменные` в файлы стилей, они доступны глобально.
+  Запрещено импортировать `custom media` в файлы стилей, они доступны глобально.
+
+- **Переменные**  
+  Все значения переменных нужно писать в `/shared/styles` или в Mantine ThemeProvider. 
+  Все что не является цветами, брекпоинтами, отступами, скруглением допускаются использоваться в компонентах.
+  Обязательное создавай CSS перменные для:
+   - "Цветов", пример: `--color-danger: red;`.  
+   - "Брекпоинты", описываем в (Сustom media) пример: `@custom-media --md (min-width: 62em);`.
+   - "Отспупы (--space)", , пример: `--space-1: 4px;`, `--space-2: 8px;`, `--space-3: 12px;` итд.. 
+   - "Скругление углов (--radius)", пример: `--radius-1: 4px;`,`--radius-2: 8px;`,`--radius-3: 12px;` итд..  
+
+- **Вложенность селекторов**
+  Запрещено использовать вложенность селекторов.
+  Разрешено использовать вложенность только для:
+    - Псевдо-классов `:hover`, `:active` итд..
+    - Псевдо-елементов `::before`, `::after`
+    - Медиа запросов `@media`
+    - Классы **модификаторы** по методологии BEM
+  Каждый вложенный селектор отделяется 1 пустой строкой.
+
+- **Медиа запросы**  
+  Строго запрещено использовать `@media` без вложения в селектор.  
+  Строго запрещено использовать в теле `@media` любые селекторы.  
+  Разрешено использовать только Custom Media Queries (например, `@media (--md) {}`).  
+  Запрещено использовать любые произвольные значения breakpoints (например, max-width: 768px).  
+  **Пример как правильно писать @media**
+  ```css
+  .todo-list {
+    max-width: 600px;
+    padding: 24px;
+
+    @media (--md) {
+      max-width: 800px;
+    }
+  }
+
+  .todo-list__text {
+    font-size: 18px;
+
+    @media (--md) {
+      font-size: 22px;
+    }
+  }
+  
+  ```
+  **Пример как неправильно писать @media**
+  ```css
+  // Медиа запрос не вложен в селектор
+  @media (--md) {
+    .todo-list {
+      max-width: 600px;
+      padding: 24px;
+    }
+    .todo-list__text {
+      font-size: 18px;
+    }
+  }
+  // Используется стандартный `min-width: 992px` вмето Custom Media Queries
+  @media (min-width: 992px) {
+    // Внутри @media запроса используются селекторы
+    .todo-list {
+      max-width: 600px;
+      padding: 24px;
+    }
+    .todo-list__text {
+      font-size: 18px;
+    }
+  }
+  ```
+
+- **Глобальные стили и сбросы**  
+  Все глобальные стили (например, сбросы) должны располагаться в отдельном файле, например, `src/app/styles/global.css`.  
+
+- **Использование Mantine и PostCSS**  
+  Для стандартных визуальных компонентов (кнопки, инпуты, layout, grid, notifications и т.д.) использовать только Mantine и его ThemeProvider.
+  Запрещено использовать в Mantine компонентах его props/styling, вмето этого нужно добавлять кастомные стили PostCSS.
+  Кастомные стили допускаются только в случае, если требуемый дизайн невозможно реализовать средствами Mantine.  
+  При написании кастомных стилей стараться использовать переменные и токены Mantine, если это возможно.
+
+- **Порядок CSS-свойств**  
+  В стилях рекомендуется придерживаться логического порядка свойств:  
+  1. Позиционирование (position, top, left, z-index и т.д.)  
+  2. Блочная модель (display, width, height, margin, padding и т.д.)  
+  3. Оформление (background, border, box-shadow и т.д.)  
+  4. Текст (font, color, text-align и т.д.)  
+  5. Прочее (transition, animation и т.д.)
+
+- **Комментарии**  
+  В стилях запрещено использовать комментарии.
+
+- **Дублирования**  
+  Не дублировать стили между компонентами. Общие стили выносить в shared/styles или использовать переменные.
+
+- **Примеры кода стилей**
+  Пример как хорошо:
+  ```css
+  /* Блок BEM */
+  .user-bar {
+    display: none;
+    color: black;
+
+    /* Медиа запрос custom media и отделяется 1 пустой строкой */
+    @media (--md) {
+      display: flex;
+    }
+  }
+
+  /* Елемент BEM отделяется 1 пустой строкой*/
+  .user-bar__button-next {
+    background-color: #f0f0f0;
+
+    /* Псевдо-класс отделяется 1 пустой строкой*/
+    &:hover {
+      background-color: #e0e0e0;
+    }
+
+    /* Модификатор BEM отделяется 1 пустой строкой*/
+    &._blue {
+      background-color: #2b2bbe;
+    }
+
+    /* Модификатор BEM отделяется 1 пустой строкой*/
+    &._green {
+      background-color: #29c53d;
+    }
+  }
+  ```
+  Пример как плохо писать:
+  ```css
+  .user-bar {
+    display: none;
+    color: black;
+    &__button {
+      &_next {
+        background-color: #f0f0f0;
+        &:hover {
+          background-color: #e0e0e0;
+        }
+        &._blue {
+          background-color: #2b2bbe;
+        }
+        &._green {
+          background-color: #29c53d;
+        }
+      }
+    } 
+  }
+  @media (min-width: 992px) {
+    .user-bar {
+      display: flex;
+    }
+  }
+  ```
+
+**Чек лист для проверки стилизации.**
+- [ ] Используется PostCSS и CSS-модули для стилизации.
+- [ ] Применён подход Mobile First.
+- [ ] Именование классов строго по BEM:
+  - [ ] Модификатор — отдельный класс, начинается с нижнего подчёркивания (например, `._red`, `._active`)
+- [ ] Все CSS-переменные (цвета, брейкпоинты, отступы, скругления) определены только в `/shared/styles` или через Mantine ThemeProvider.
+- [ ] Для медиа-запросов используются только custom media переменные из `/shared/styles/media.css`.
+- [ ] Соблюдается правила вложености селекторов.
+- [ ] Соблюдается правила отступов селекторов.
+- [ ] Глобальные стили (reset) вынесены в отдельный файл, остальные стили — модульные.
+- [ ] Для стандартных UI-элементов используются только компоненты Mantine, кастомные стили — только при необходимости.
+- [ ] В Mantine-компонентах не используются props/styling для стилизации, только PostCSS.
+- [ ] Кастомные стили используют переменные и токены Mantine, если это возможно.
+- [ ] В стилях нет комментариев.
+- [ ] Стили компонента импортируются только внутри соответствующего компонента.
+- [ ] Нет импорта стилей одного компонента в другой.
+- [ ] Нет импорта файлов переменных и custom media — они доступны глобально.
+- [ ] Нет дублирования стилей между компонентами, общие стили вынесены в shared/styles или используются переменные.