code-ai-installer 1.3.1 → 1.4.0

package/.agents/styling_css_stack/SKILL.md

@@ -1,558 +0,0 @@
----
-name: styling_css_stack
-description: CSS практики — custom properties (design tokens), naming (BEM / CSS Modules), responsive, transitions, z-index scale, dark mode, a11y (focus-visible, prefers-reduced-motion, forced-colors). DO/DON'T примеры. Активируй при написании или ревью CSS/Less/Sass, при рефакторинге стилей, или при вопросах «как правильно стилизовать X».
----
-
-# Skill: Styling (CSS Stack) Beast Practices
-
-Конкретные DO/DON'T паттерны для CSS — от design tokens до a11y.
-
-**Разделы:**
-1. [Design Tokens (CSS Custom Properties)](#1-design-tokens)
-2. [Naming: BEM vs CSS Modules](#2-naming)
-3. [Responsive и Media Queries](#3-responsive)
-4. [Dark Mode](#4-dark-mode)
-5. [Transitions и Animations](#5-transitions-и-animations)
-6. [Z-index Scale](#6-z-index-scale)
-7. [Accessibility (a11y)](#7-accessibility)
-8. [Организация файлов](#8-организация-файлов)
-9. [Anti-patterns](#9-anti-patterns)
-
----
-
-## 1. Design Tokens
-
-### ✅ DO: CSS custom properties как единый источник правды
-
-```css
-/* tokens.css — глобальные design tokens */
-:root {
-  /* Colors */
-  --color-primary: hsl(220, 90%, 56%);
-  --color-primary-hover: hsl(220, 90%, 46%);
-  --color-secondary: hsl(280, 70%, 50%);
-  --color-surface: hsl(0, 0%, 100%);
-  --color-surface-elevated: hsl(0, 0%, 98%);
-  --color-text: hsl(220, 20%, 12%);
-  --color-text-muted: hsl(220, 10%, 50%);
-  --color-border: hsl(220, 15%, 88%);
-  --color-error: hsl(0, 80%, 55%);
-  --color-success: hsl(145, 70%, 40%);
-
-  /* Spacing (4px grid) */
-  --space-1: 0.25rem;   /* 4px */
-  --space-2: 0.5rem;    /* 8px */
-  --space-3: 0.75rem;   /* 12px */
-  --space-4: 1rem;      /* 16px */
-  --space-6: 1.5rem;    /* 24px */
-  --space-8: 2rem;      /* 32px */
-  --space-12: 3rem;     /* 48px */
-
-  /* Typography */
-  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
-  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
-  --text-xs: 0.75rem;    /* 12px */
-  --text-sm: 0.875rem;   /* 14px */
-  --text-base: 1rem;     /* 16px */
-  --text-lg: 1.125rem;   /* 18px */
-  --text-xl: 1.25rem;    /* 20px */
-  --text-2xl: 1.5rem;    /* 24px */
-  --line-height-tight: 1.25;
-  --line-height-normal: 1.5;
-
-  /* Borders */
-  --radius-sm: 4px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --radius-full: 9999px;
-
-  /* Shadows */
-  --shadow-sm: 0 1px 2px hsl(0 0% 0% / 0.05);
-  --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.07);
-  --shadow-lg: 0 10px 25px hsl(0 0% 0% / 0.1);
-
-  /* Transitions */
-  --duration-fast: 150ms;
-  --duration-normal: 250ms;
-  --duration-slow: 400ms;
-  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
-  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
-}
-```
-
-### ❌ DON'T: хардкод значений в компонентах
-
-```css
-/* ❌ Магические значения — невозможно поддерживать, нет dark mode */
-.card {
-  padding: 17px;
-  color: #333;
-  background: white;
-  border-radius: 6px;
-  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
-}
-
-/* ✅ Токены — единообразно, поддерживает тему */
-.card {
-  padding: var(--space-4);
-  color: var(--color-text);
-  background: var(--color-surface);
-  border-radius: var(--radius-md);
-  box-shadow: var(--shadow-md);
-}
-```
-
----
-
-## 2. Naming
-
-### ✅ DO: BEM для vanilla CSS
-
-```css
-/* Block */
-.coupon-card { }
-
-/* Element */
-.coupon-card__title { }
-.coupon-card__code { }
-.coupon-card__actions { }
-
-/* Modifier */
-.coupon-card--active { }
-.coupon-card--expired { }
-
-/* State (JS-driven) */
-.coupon-card.is-selected { }
-.coupon-card.is-loading { }
-```
-
-```html
-<div class="coupon-card coupon-card--active is-selected">
-  <h3 class="coupon-card__title">SAVE20</h3>
-  <span class="coupon-card__code">20% off</span>
-  <div class="coupon-card__actions">
-    <button>Apply</button>
-  </div>
-</div>
-```
-
-### ✅ DO: CSS Modules для React (scoped by default)
-
-```css
-/* CouponCard.module.css */
-.card {
-  padding: var(--space-4);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-}
-
-.card.active {
-  border-color: var(--color-primary);
-}
-
-.title {
-  font-size: var(--text-lg);
-  font-weight: 600;
-}
-
-.code {
-  font-family: var(--font-mono);
-  color: var(--color-text-muted);
-}
-```
-
-```jsx
-import styles from './CouponCard.module.css';
-import clsx from 'clsx';
-
-function CouponCard({ coupon }) {
-  return (
-    <div className={clsx(styles.card, coupon.active && styles.active)}>
-      <h3 className={styles.title}>{coupon.code}</h3>
-      <span className={styles.code}>{coupon.discount}%</span>
-    </div>
-  );
-}
-```
-
-### Когда что
-
-| Подход | Когда ✅ | Когда ❌ |
-|--------|---------|---------|
-| **BEM** | Vanilla CSS/HTML, виджеты, legacy | Большие SPA (нет scoping) |
-| **CSS Modules** | React/Vue SPA, компонентная архитектура | Статичные сайты |
-| **Tailwind** | Rapid prototyping, utility-first команды | Wix виджеты, сложные анимации |
-
----
-
-## 3. Responsive
-
-### ✅ DO: mobile-first с min-width breakpoints
-
-```css
-/* ✅ Mobile-first: базовые стили для mobile, расширяем вверх */
-.grid {
-  display: grid;
-  grid-template-columns: 1fr;
-  gap: var(--space-4);
-}
-
-@media (min-width: 640px) {  /* sm */
-  .grid {
-    grid-template-columns: repeat(2, 1fr);
-  }
-}
-
-@media (min-width: 1024px) { /* lg */
-  .grid {
-    grid-template-columns: repeat(3, 1fr);
-  }
-}
-```
-
-### ✅ DO: breakpoint tokens
-
-```css
-/* Breakpoints (не custom properties — media queries не поддерживают var()) */
-/* sm:  640px  — phone landscape / small tablet */
-/* md:  768px  — tablet portrait */
-/* lg:  1024px — tablet landscape / small desktop */
-/* xl:  1280px — desktop */
-/* 2xl: 1536px — wide desktop */
-```
-
-### ✅ DO: container queries для компонентов
-
-```css
-/* ✅ Компонент адаптируется к размеру КОНТЕЙНЕРА, а не экрана */
-.card-container {
-  container-type: inline-size;
-}
-
-.card {
-  display: flex;
-  flex-direction: column;
-}
-
-@container (min-width: 400px) {
-  .card {
-    flex-direction: row; /* Горизонтальный layout при достаточном месте */
-  }
-}
-```
-
-### ❌ DON'T: fixed width для layout
-
-```css
-/* ❌ Ломается на нестандартных экранах */
-.container {
-  width: 1200px;
-}
-
-/* ✅ Адаптивная ширина */
-.container {
-  width: 100%;
-  max-width: 1200px;
-  margin-inline: auto;
-  padding-inline: var(--space-4);
-}
-```
-
----
-
-## 4. Dark Mode
-
-### ✅ DO: dark mode через переопределение tokens
-
-```css
-/* ✅ Автоматический dark mode через media query */
-@media (prefers-color-scheme: dark) {
-  :root {
-    --color-surface: hsl(220, 20%, 10%);
-    --color-surface-elevated: hsl(220, 20%, 14%);
-    --color-text: hsl(220, 15%, 90%);
-    --color-text-muted: hsl(220, 10%, 60%);
-    --color-border: hsl(220, 15%, 25%);
-    --color-primary: hsl(220, 90%, 65%);
-    --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.3);
-  }
-}
-
-/* ✅ Или через class toggle (JS-controlled) */
-[data-theme="dark"] {
-  --color-surface: hsl(220, 20%, 10%);
-  --color-text: hsl(220, 15%, 90%);
-  /* ... */
-}
-```
-
-### ❌ DON'T: инвертировать цвета или жёстко кодить
-
-```css
-/* ❌ filter — ломает изображения, иконки, видео */
-.dark-mode {
-  filter: invert(1);
-}
-
-/* ❌ Дублирование стилей вместо переопределения tokens */
-.dark-mode .card {
-  background: #1a1a2e;
-  color: #eee;
-  border-color: #333;
-}
-```
-
----
-
-## 5. Transitions и Animations
-
-### ✅ DO: transition на конкретные свойства
-
-```css
-/* ✅ Явные свойства — производительно, предсказуемо */
-.button {
-  transition:
-    background-color var(--duration-fast) var(--ease-out),
-    transform var(--duration-fast) var(--ease-out),
-    box-shadow var(--duration-fast) var(--ease-out);
-}
-
-.button:hover {
-  background-color: var(--color-primary-hover);
-  transform: translateY(-1px);
-  box-shadow: var(--shadow-md);
-}
-
-.button:active {
-  transform: translateY(0);
-  box-shadow: var(--shadow-sm);
-}
-
-/* ❌ transition: all — анимирует всё подряд, включая width/height (layout thrashing) */
-.button {
-  transition: all 0.3s ease;  /* ❌ */
-}
-```
-
-### ✅ DO: анимировать только transform и opacity (GPU-accelerated)
-
-```css
-/* ✅ GPU: transform + opacity — не вызывают layout/paint */
-.fade-in {
-  animation: fadeIn var(--duration-normal) var(--ease-out);
-}
-
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(8px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-/* ❌ Анимирование width/height/top/left — вызывает layout recalculation */
-@keyframes bad {
-  from { width: 0; height: 0; }
-  to   { width: 100px; height: 100px; }
-}
-```
-
----
-
-## 6. Z-index Scale
-
-### ✅ DO: предсказуемая фиксированная шкала
-
-```css
-:root {
-  --z-base: 0;
-  --z-dropdown: 100;
-  --z-sticky: 200;
-  --z-overlay: 300;
-  --z-modal: 400;
-  --z-popover: 500;
-  --z-toast: 600;
-  --z-tooltip: 700;
-  --z-max: 9999;      /* только для critical overlays (fullscreen loader) */
-}
-
-/* Использование */
-.dropdown { z-index: var(--z-dropdown); }
-.modal-backdrop { z-index: var(--z-overlay); }
-.modal { z-index: var(--z-modal); }
-.toast { z-index: var(--z-toast); }
-```
-
-### ❌ DON'T: z-index wars
-
-```css
-/* ❌ Эскалация z-index — невозможно поддерживать */
-.header   { z-index: 100; }
-.dropdown { z-index: 999; }
-.modal    { z-index: 9999; }
-.toast    { z-index: 99999; }   /* когда-нибудь понадобится 999999 */
-```
-
----
-
-## 7. Accessibility
-
-### ✅ DO: focus-visible, не focus
-
-```css
-/* ✅ focus-visible — показывает фокус только при навигации клавиатурой */
-.button:focus-visible {
-  outline: 2px solid var(--color-primary);
-  outline-offset: 2px;
-}
-
-/* ❌ focus — показывает outline при клике мышью (раздражает пользователей) */
-.button:focus {
-  outline: 2px solid blue;
-}
-
-/* ❌ Убирать outline полностью — ломает keyboard navigation */
-*:focus {
-  outline: none;  /* ❌ НИКОГДА */
-}
-```
-
-### ✅ DO: prefers-reduced-motion
-
-```css
-/* ✅ Отключить анимации когда пользователь просит */
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
-}
-```
-
-### ✅ DO: forced-colors для Windows High Contrast
-
-```css
-/* ✅ Поддержка Windows High Contrast Mode */
-@media (forced-colors: active) {
-  .button {
-    border: 1px solid ButtonText;         /* Системный цвет */
-  }
-  .button:hover {
-    background: Highlight;
-    color: HighlightText;
-  }
-  .icon {
-    forced-color-adjust: auto;            /* Позволить системе раскрасить */
-  }
-}
-```
-
-### ✅ DO: достаточный контраст
-
-```css
-/* Минимальные требования WCAG 2.1 AA */
-/* Обычный текст: контраст ≥ 4.5:1 */
-/* Крупный текст (≥ 18px bold или ≥ 24px): контраст ≥ 3:1 */
-/* Интерактивные элементы: контраст ≥ 3:1 */
-
-/* ✅ Проверять через: https://webaim.org/resources/contrastchecker/ */
-```
-
----
-
-## 8. Организация файлов
-
-```
-src/
-├── styles/
-│   ├── tokens.css          # Design tokens (custom properties)
-│   ├── reset.css           # CSS reset / normalize
-│   ├── base.css            # Typography, base elements
-│   ├── utilities.css       # Utility classes (.sr-only, .truncate)
-│   └── z-index.css         # Z-index scale
-├── components/
-│   ├── Button/
-│   │   ├── Button.jsx
-│   │   └── Button.module.css
-│   └── CouponCard/
-│       ├── CouponCard.jsx
-│       └── CouponCard.module.css
-└── index.css               # Imports: tokens → reset → base → utilities
-```
-
-### index.css (entry point)
-
-```css
-/* Порядок важен! */
-@import './styles/tokens.css';
-@import './styles/reset.css';
-@import './styles/base.css';
-@import './styles/utilities.css';
-@import './styles/z-index.css';
-```
-
-### Utility classes
-
-```css
-/* utilities.css — переиспользуемые утилиты */
-
-/* Screen reader only */
-.sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
-
-/* Truncate text */
-.truncate {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-/* Line clamp */
-.line-clamp-2 {
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
-}
-```
-
----
-
-## 9. Anti-patterns
-
-| ❌ Anti-pattern | ✅ Решение |
-|----------------|-----------|
-| `!important` для layout | Увеличить специфичность через selectors |
-| `transition: all` | Перечислить конкретные свойства |
-| `outline: none` без замены | `focus-visible` + visible outline |
-| Хардкод цветов (`#333`, `red`) | CSS custom properties |
-| `px` для font-size | `rem` (доступность: уважает user settings) |
-| Глобальные селекторы (`div { }`) | Scoped: CSS Modules, BEM, или layer |
-| Вложенность > 3 уровней (Sass) | Flat selectors, BEM |
-| `@import` в runtime CSS | Бандлер (Vite) или `@layer` |
-| Анимация `width`/`height` | `transform: scale()` или `clip-path` |
-| Magic numbers (`margin: 17px`) | Spacing tokens (`var(--space-4)`) |
-
----
-
-## См. также
-- `$design_systems` — интеграция дизайн-систем (shadcn/ui, WDS)
-- `$a11y_baseline` — полный a11y чеклист
-- `$tailwind_beast_practices` — Tailwind-специфичные паттерны
-- `$design_parity_review` — сравнение реализации с дизайном