@mr.slonn/my-scss-theme 1.0.0

package/scss/abstracts/_mixins.scss

@@ -0,0 +1,1142 @@
+////
+/// Миксины темы MOEXP
+/// Цвета, тени, градиенты, flex-gap, утилиты и фоновые изображения
+/// @group mixins
+/// @author MOEXP Team
+////
+
+// ============================================
+// MIXINS
+// local\common\theme-moexp\src\scss\abstracts\_mixins.scss
+// ============================================
+
+@use "sass:math";
+@use "sass:list";
+@use "sass:map";
+@use "sass:meta";
+@use "colors";
+@use "breakpoints";
+
+// ============================================
+// ЦВЕТОВЫЕ МИКСИНЫ
+// ============================================
+/// Генерирует fallback + modern hsl() для любого CSS-свойства
+/// Обеспечивает поддержку браузеров без CSS custom properties
+/// @param {String} $property - CSS-свойство (color, background-color, border-color и т.д.)
+/// @param {String} $var-name - Имя цвета из палитры (без "--")
+/// @param {Number} $alpha [1] - Прозрачность от 0 до 1
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Цвет текста
+///   .element {
+///     @include hsl-prop(color, 'primary');
+///   }
+///   // => color: hsl(209, 32%, 35%);
+///   // => color: hsl(var(--primary));
+/// @example scss - Полупрозрачный фон
+///   .overlay {
+///     @include hsl-prop(background-color, 'overlay', 0.5);
+///   }
+/// @output Два объявления: fallback и modern
+/// @group mixins-color
+/// @access public
+@mixin hsl-prop($property, $var-name, $alpha: 1) {
+  // Fallback: статический цвет для браузеров без CSS переменных
+  #{$property}: colors.color-static($var-name, $alpha);
+
+  // Modern: CSS переменные
+  #{$property}: colors.color-var($var-name, $alpha);
+}
+
+/// Shortcut для color с fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha [1] - Прозрачность от 0 до 1
+/// @require {mixin} hsl-prop
+/// @example scss - Основной текст
+///   .text {
+///     @include text-color('foreground-body');
+///   }
+/// @example scss - Приглушённый текст
+///   .muted {
+///     @include text-color('foreground-muted', 0.8);
+///   }
+/// @output color с fallback
+/// @group mixins-color
+/// @access public
+@mixin text-color($var-name, $alpha: 1) {
+  @include hsl-prop(color, $var-name, $alpha);
+}
+
+/// Shortcut для background-color с fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha [1] - Прозрачность от 0 до 1
+/// @require {mixin} hsl-prop
+/// @example scss - Фон карточки
+///   .card {
+///     @include bg-color('background-card');
+///   }
+/// @example scss - Полупрозрачный оверлей
+///   .overlay {
+///     @include bg-color('overlay', 0.7);
+///   }
+/// @output background-color с fallback
+/// @group mixins-color
+/// @access public
+@mixin bg-color($var-name, $alpha: 1) {
+  @include hsl-prop(background-color, $var-name, $alpha);
+}
+
+/// Border с полным объявлением и fallback
+/// @param {Number} $width - Толщина границы
+/// @param {String} $style - Стиль границы (solid, dashed, dotted и т.д.)
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha [1] - Прозрачность от 0 до 1
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Обычная граница
+///   .card {
+///     @include border-hsl(1px, solid, 'border');
+///   }
+/// @example scss - Полупрозрачная граница
+///   .subtle {
+///     @include border-hsl(1px, solid, 'border', 0.5);
+///   }
+/// @output border с fallback
+/// @group mixins-color
+/// @access public
+@mixin border-hsl($width, $style, $var-name, $alpha: 1) {
+  border: $width $style colors.color-static($var-name, $alpha);
+  border: $width $style colors.color-var($var-name, $alpha);
+}
+
+/// Только border-color с fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha [1] - Прозрачность от 0 до 1
+/// @require {mixin} hsl-prop
+/// @example scss - Изменение цвета границы при hover
+///   .input:focus {
+///     @include border-color-hsl('ring');
+///   }
+/// @output border-color с fallback
+/// @group mixins-color
+/// @access public
+@mixin border-color-hsl($var-name, $alpha: 1) {
+  @include hsl-prop(border-color, $var-name, $alpha);
+}
+
+// ============================================
+// BOX-SHADOW
+// ============================================
+
+/// Box-shadow с одной тенью и fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha - Прозрачность тени
+/// @param {Number} $x [0] - Смещение по X
+/// @param {Number} $y [4px] - Смещение по Y
+/// @param {Number} $blur [8px] - Радиус размытия
+/// @param {Number} $spread [0] - Радиус распространения
+/// @param {Boolean} $inset [false] - Внутренняя тень
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Обычная тень
+///   .card {
+///     @include box-shadow-hsl('shadow', 0.15);
+///   }
+/// @example scss - Внутренняя тень
+///   .input {
+///     @include box-shadow-hsl('shadow', 0.1, 0, 2px, 4px, 0, true);
+///   }
+/// @output box-shadow с fallback
+/// @group mixins-shadow
+/// @access public
+@mixin box-shadow-hsl($var-name, $alpha, $x: 0, $y: 4px, $blur: 8px, $spread: 0, $inset: false) {
+  @if $inset {
+    // Fallback
+    box-shadow: inset $x $y $blur $spread colors.color-static($var-name, $alpha);
+    // Modern
+    box-shadow: inset $x $y $blur $spread colors.color-var($var-name, $alpha);
+  } @else {
+    // Fallback
+    box-shadow: $x $y $blur $spread colors.color-static($var-name, $alpha);
+    // Modern
+    box-shadow: $x $y $blur $spread colors.color-var($var-name, $alpha);
+  }
+}
+
+/// Многослойная тень с fallback
+/// @param {String} $color - Имя цвета из палитры
+/// @param {List} $layers - Список слоёв: ((x, y, blur, spread, alpha), ...)
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Двухслойная тень
+///   .card {
+///     @include box-shadow-layers('shadow', (
+///       (0, 4px, 6px, -1px, 0.1),
+///       (0, 2px, 4px, -2px, 0.1)
+///     ));
+///   }
+/// @output box-shadow с несколькими слоями и fallback
+/// @group mixins-shadow
+/// @access public
+@mixin box-shadow-layers($color, $layers) {
+  $fallback: ();
+  $modern: ();
+
+  @each $layer in $layers {
+    $x: list.nth($layer, 1);
+    $y: list.nth($layer, 2);
+
+    $blur: 0;
+    @if list.length($layer) >= 3 {
+      $blur: list.nth($layer, 3);
+    }
+
+    $spread: 0;
+    @if list.length($layer) >= 4 {
+      $spread: list.nth($layer, 4);
+    }
+
+    $alpha: 0.15;
+    @if list.length($layer) >= 5 {
+      $alpha: list.nth($layer, 5);
+    }
+
+    $fallback: list.append($fallback, #{$x} #{$y} #{$blur} #{$spread} colors.color-static($color, $alpha), comma);
+    $modern: list.append($modern, #{$x} #{$y} #{$blur} #{$spread} colors.color-var($color, $alpha), comma);
+  }
+
+  box-shadow: $fallback;
+  box-shadow: $modern;
+}
+/// Маленькая тень (SM)
+/// @param {String} $color [shadow] - Имя цвета
+/// @require {mixin} box-shadow-hsl
+/// @example scss
+///   .button {
+///     @include shadow-sm;
+///   }
+/// @output box-shadow: 0 1px 2px 0 color/0.05
+/// @group mixins-shadow
+/// @access public
+@mixin shadow-sm($color: shadow) {
+  @include box-shadow-hsl($color, 0.05, 0, 1px, 2px, 0);
+}
+
+/// Средняя тень (MD) — двухслойная
+/// @param {String} $color [shadow] - Имя цвета
+/// @require {mixin} box-shadow-layers
+/// @example scss
+///   .card {
+///     @include shadow-md;
+///   }
+/// @group mixins-shadow
+/// @access public
+@mixin shadow-md($color: shadow) {
+  @include box-shadow-layers($color, ((0, 4px, 6px, -1px, 0.1), (0, 2px, 4px, -2px, 0.1)));
+}
+
+/// Большая тень (LG) — двухслойная
+/// @param {String} $color [shadow] - Имя цвета
+/// @require {mixin} box-shadow-layers
+/// @example scss
+///   .modal {
+///     @include shadow-lg;
+///   }
+/// @group mixins-shadow
+/// @access public
+@mixin shadow-lg($color: shadow) {
+  @include box-shadow-layers($color, ((0, 10px, 15px, -3px, 0.1), (0, 4px, 6px, -4px, 0.1)));
+}
+
+/// Очень большая тень (XL) — двухслойная
+/// @param {String} $color [shadow] - Имя цвета
+/// @require {mixin} box-shadow-layers
+/// @example scss
+///   .dropdown {
+///     @include shadow-xl;
+///   }
+/// @group mixins-shadow
+/// @access public
+@mixin shadow-xl($color: shadow) {
+  @include box-shadow-layers($color, ((0, 20px, 25px, -5px, 0.1), (0, 8px, 10px, -6px, 0.1)));
+}
+
+// ============================================
+// OUTLINE / FOCUS RING
+// ============================================
+
+/// Outline с fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha [1] - Прозрачность
+/// @param {Number} $width [2px] - Толщина
+/// @param {String} $style [solid] - Стиль
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss
+///   .input:focus {
+///     @include outline-hsl('ring', 0.5);
+///   }
+/// @output outline с fallback
+/// @group mixins-focus
+/// @access public
+@mixin outline-hsl($var-name, $alpha: 1, $width: 2px, $style: solid) {
+  outline: $width $style colors.color-static($var-name, $alpha);
+  outline: $width $style colors.color-var($var-name, $alpha);
+}
+
+/// Focus ring — современный подход для фокуса
+/// @param {String} $color [ring] - Имя цвета
+/// @param {Number} $width [2px] - Толщина кольца
+/// @param {Number} $offset [-2px] - Отступ от элемента
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - На кнопке
+///   .button:focus-visible {
+///     @include focus-ring;
+///   }
+/// @example scss - Кастомный цвет
+///   .link:focus-visible {
+///     @include focus-ring('accent', 2px, 2px);
+///   }
+/// @output outline + outline-offset
+/// @group mixins-focus
+/// @access public
+@mixin focus-ring($color: ring, $width: 2px, $offset: -2px) {
+  outline: $width solid colors.color-static($color, 0.5);
+  outline: $width solid colors.color-var($color, 0.5);
+  outline-offset: $offset;
+}
+
+// ============================================
+// TEXT-SHADOW
+// ============================================
+
+/// Text-shadow с fallback
+/// @param {String} $var-name - Имя цвета из палитры
+/// @param {Number} $alpha - Прозрачность
+/// @param {Number} $x [0] - Смещение по X
+/// @param {Number} $y [1px] - Смещение по Y
+/// @param {Number} $blur [2px] - Радиус размытия
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss
+///   .hero__title {
+///     @include text-shadow-hsl('shadow', 0.3, 0, 2px, 4px);
+///   }
+/// @output text-shadow с fallback
+/// @group mixins-shadow
+/// @access public
+@mixin text-shadow-hsl($var-name, $alpha, $x: 0, $y: 1px, $blur: 2px) {
+  text-shadow: $x $y $blur colors.color-static($var-name, $alpha);
+  text-shadow: $x $y $blur colors.color-var($var-name, $alpha);
+}
+
+// ============================================
+// ГРАДИЕНТЫ
+// ============================================
+
+/// Линейный градиент с двумя цветами
+/// @param {String} $direction - Направление (to right, to bottom, 45deg и т.д.)
+/// @param {String} $color1 - Имя первого цвета
+/// @param {String} $color2 - Имя второго цвета
+/// @param {Number} $alpha1 [1] - Прозрачность первого цвета
+/// @param {Number} $alpha2 [1] - Прозрачность второго цвета
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss
+///   .banner {
+///     @include gradient-linear(to right, 'primary', 'secondary');
+///   }
+/// @output background: linear-gradient с fallback
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-linear($direction, $color1, $color2, $alpha1: 1, $alpha2: 1) {
+  // Fallback
+  background: linear-gradient($direction, colors.color-static($color1, $alpha1), colors.color-static($color2, $alpha2));
+  // Modern
+  background: linear-gradient($direction, colors.color-var($color1, $alpha1), colors.color-var($color2, $alpha2));
+}
+
+/// Overlay градиент (для затемнения изображений)
+/// @param {String} $color [overlay] - Имя цвета
+/// @param {Number} $alpha-start [0.8] - Прозрачность начала
+/// @param {Number} $alpha-end [0.4] - Прозрачность конца
+/// @require {mixin} gradient-linear
+/// @example scss
+///   .hero::before {
+///     @include gradient-overlay('overlay', 0.9, 0.5);
+///   }
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-overlay($color: overlay, $alpha-start: 0.8, $alpha-end: 0.4) {
+  @include gradient-linear(to bottom, $color, $color, $alpha-start, $alpha-end);
+}
+
+/// Линейный градиент с 3 точками (from/via/to)
+/// @param {String} $direction - Направление (to right, to bottom, 45deg и т.д.)
+/// @param {String} $color - Имя цвета
+/// @param {Number} $alpha-from [1] - Прозрачность начала
+/// @param {Number} $alpha-via [0.5] - Прозрачность середины
+/// @param {Number} $alpha-to [0] - Прозрачность конца
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Fade эффект
+///   .fade-right {
+///     @include gradient-fade(to right, 'background', 1, 0.5, 0);
+///   }
+/// @output background: linear-gradient с 3 точками и fallback
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-fade($direction, $color, $alpha-from: 1, $alpha-via: 0.5, $alpha-to: 0) {
+  // Fallback
+  background: linear-gradient($direction, colors.color-static($color, $alpha-from), colors.color-static($color, $alpha-via), colors.color-static($color, $alpha-to));
+
+  // Modern
+  background: linear-gradient($direction, colors.color-var($color, $alpha-from), colors.color-var($color, $alpha-via), colors.color-var($color, $alpha-to));
+}
+
+/// Универсальный градиент с любым количеством точек
+/// @param {String} $direction - Направление
+/// @param {List} $stops - Список точек: ((color, alpha, position?), ...)
+/// @require {function} colors.color-static
+/// @require {function} colors.color-var
+/// @example scss - Сложный градиент
+///   .rainbow {
+///     @include gradient-multi(to right, (
+///       ('primary', 1, 0%),
+///       ('accent', 0.8, 50%),
+///       ('secondary', 1, 100%)
+///     ));
+///   }
+/// @output background: linear-gradient с несколькими точками
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-multi($direction, $stops) {
+  $fallback-stops: ();
+  $modern-stops: ();
+
+  @each $stop in $stops {
+    $color: list.nth($stop, 1);
+    $alpha: 1;
+    @if list.length($stop) >= 2 {
+      $alpha: list.nth($stop, 2);
+    }
+    $position: meta.if(length($stop) >= 3, list.nth($stop, 3), null);
+
+    $fallback-stop: colors.color-static($color, $alpha);
+    $modern-stop: colors.color-var($color, $alpha);
+
+    @if $position {
+      $fallback-stop: $fallback-stop $position;
+      $modern-stop: $modern-stop $position;
+    }
+
+    $fallback-stops: list.append($fallback-stops, $fallback-stop, comma);
+    $modern-stops: list.append($modern-stops, $modern-stop, comma);
+  }
+
+  background: linear-gradient($direction, $fallback-stops);
+  background: linear-gradient($direction, $modern-stops);
+}
+
+/// Fade overlay справа (для изображений)
+/// @param {String} $color [primary] - Имя цвета
+/// @require {mixin} gradient-fade
+/// @example scss
+///   .hero::after {
+///     @include gradient-overlay-right;
+///   }
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-overlay-right($color: primary) {
+  @include gradient-fade(to right, $color, 0.9, 0.7, 0.4);
+}
+
+/// Fade overlay снизу (для изображений)
+/// @param {String} $color [overlay] - Имя цвета
+/// @require {mixin} gradient-fade
+/// @example scss
+///   .card__image::after {
+///     @include gradient-overlay-bottom;
+///   }
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-overlay-bottom($color: overlay) {
+  @include gradient-fade(to bottom, $color, 0.8, 0.5, 0.2);
+}
+
+/// Hero gradient — диагональный fade
+/// @param {String} $color [primary] - Имя цвета
+/// @require {mixin} gradient-fade
+/// @example scss
+///   .hero::before {
+///     @include gradient-hero;
+///   }
+/// @group mixins-gradient
+/// @access public
+@mixin gradient-hero($color: primary) {
+  @include gradient-fade(135deg, $color, 0.95, 0.7, 0.4);
+}
+
+// ============================================
+// FLEX GAP FALLBACK
+// ============================================
+
+/// Flex gap с fallback через margin для старых браузеров
+/// @param {Number | List} $gap - Одно значение или (row-gap, column-gap)
+/// @param {String} $direction [both] - Направление: 'row', 'column', 'both'
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов
+/// @example scss - Одинаковый gap
+///   .flex-container {
+///     display: flex;
+///     @include flex-gap(1rem);
+///   }
+/// @example scss - Разный gap
+///   .flex-container {
+///     display: flex;
+///     @include flex-gap((1rem, 2rem)); // row: 1rem, column: 2rem
+///   }
+/// @example scss - Только горизонтальный
+///   .row {
+///     display: flex;
+///     @include flex-gap(1rem, 'row');
+///   }
+/// @output margin fallback + @supports (gap) modern
+/// @group mixins-layout
+/// @access public
+@mixin flex-gap($gap, $direction: both, $selector: "> *") {
+  // Нормализация gap в row и column
+  $row-gap: $gap;
+  $col-gap: $gap;
+
+  @if meta.type-of($gap) == list {
+    $row-gap: list.nth($gap, 1);
+    $col-gap: list.nth($gap, 1);
+    @if list.length($gap) >= 2 {
+      $col-gap: list.nth($gap, 2);
+    }
+  }
+
+  // Fallback через margin
+  #{$selector} {
+    @if $direction == both {
+      margin: math.div($row-gap, 2) math.div($col-gap, 2);
+
+      // Убираем внешние margin
+      &:first-child {
+        margin-left: 0;
+      }
+      &:last-child {
+        margin-right: 0;
+      }
+    } @else if $direction == row {
+      margin-left: math.div($col-gap, 2);
+      margin-right: math.div($col-gap, 2);
+
+      &:first-child {
+        margin-left: 0;
+      }
+      &:last-child {
+        margin-right: 0;
+      }
+    } @else if $direction == column {
+      margin-top: math.div($row-gap, 2);
+      margin-bottom: math.div($row-gap, 2);
+
+      &:first-child {
+        margin-top: 0;
+      }
+      &:last-child {
+        margin-bottom: 0;
+      }
+    }
+  }
+
+  // Modern: native gap (если поддерживается)
+  @supports (gap: 1px) {
+    #{$selector} {
+      margin: 0;
+    }
+
+    @if $direction == both {
+      gap: $row-gap $col-gap;
+    } @else if $direction == row {
+      column-gap: $col-gap;
+    } @else if $direction == column {
+      row-gap: $row-gap;
+    }
+  }
+}
+
+/// Flex gap с поддержкой wrap
+/// Использует отрицательный margin на контейнере для компенсации
+/// @param {Number | List} $gap - Одно значение или (row-gap, column-gap)
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов
+/// @example scss
+///   .tags {
+///     display: flex;
+///     flex-wrap: wrap;
+///     @include flex-gap-wrap(0.5rem);
+///   }
+/// @output Отрицательный margin + margin детей + @supports modern
+/// @group mixins-layout
+/// @access public
+@mixin flex-gap-wrap($gap, $selector: "> *") {
+  $row-gap: $gap;
+  $col-gap: $gap;
+
+  @if meta.type-of($gap) == list {
+    $row-gap: list.nth($gap, 1);
+    $col-gap: $row-gap;
+    @if list.length($gap) >= 2 {
+      $col-gap: list.nth($gap, 2);
+    }
+  }
+
+  $row-offset: math.div($row-gap, 2);
+  $col-offset: math.div($col-gap, 2);
+
+  // Отрицательный margin компенсирует margin детей
+  margin: -#{$row-offset} -#{$col-offset};
+
+  #{$selector} {
+    margin: $row-offset $col-offset;
+  }
+
+  // Modern
+  @supports (gap: 1px) {
+    margin: 0;
+    gap: $row-gap $col-gap;
+
+    #{$selector} {
+      margin: 0;
+    }
+  }
+}
+
+// ============================================
+// УТИЛИТЫ
+// ============================================
+
+/// Визуально скрытый элемент, но доступный для screen readers
+/// @example scss
+///   .skip-link {
+///     @include visually-hidden;
+///
+///     &:focus {
+///       // показать при фокусе
+///     }
+///   }
+/// @output Абсолютное позиционирование 1x1px с clip
+/// @group mixins-a11y
+/// @access public
+@mixin visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/// Сброс стилей кнопки
+/// @example scss
+///   .custom-button {
+///     @include button-reset;
+///     // кастомные стили
+///   }
+/// @output Сброс appearance, background, border, padding, margin
+/// @group mixins-reset
+/// @access public
+@mixin button-reset {
+  appearance: none;
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+
+  &:focus {
+    outline: none;
+  }
+}
+
+/// Обрезка текста с многоточием
+/// @param {Number} $lines [1] - Количество строк (1 = однострочная, >1 = многострочная)
+/// @example scss - Одна строка
+///   .title {
+///     @include text-truncate;
+///   }
+/// @example scss - Три строки
+///   .description {
+///     @include text-truncate(3);
+///   }
+/// @output overflow: hidden + text-overflow: ellipsis (или -webkit-line-clamp)
+/// @group mixins-text
+/// @access public
+@mixin text-truncate($lines: 1) {
+  @if $lines == 1 {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  } @else {
+    display: -webkit-box;
+    -webkit-line-clamp: $lines;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+}
+
+/// Background image с WebP и fallback
+/// Использует image-set для современных браузеров
+/// @param {String} $path - Путь к изображению без расширения
+/// @param {String} $ext [jpg] - Расширение fallback-изображения
+/// @param {Boolean} $fallback-is-first [true] - (не используется, для совместимости)
+/// @example scss
+///   .hero {
+///     @include bg-webp('/images/hero', 'jpg');
+///   }
+/// @output background-image с fallback и image-set
+/// @group mixins-image
+/// @access public
+@mixin bg-webp($path, $ext: "jpg", $fallback-is-first: true) {
+  // 1. Стандартный Fallback для совсем старых браузеров (IE11 и старые Safari),
+  // которые не понимают image-set. Они просто проигнорируют следующие строки.
+  background-image: url("#{$path}.#{$ext}");
+
+  // 2. Современное решение
+  // Синтаксис image-set позволяет указать варианты и их типы
+  $mime-ext: $ext;
+  @if $ext == "jpg" {
+    $mime-ext: "jpeg";
+  }
+  background-image: image-set(url("#{$path}.webp") type("image/webp"), url("#{$path}.#{$ext}") type("image/#{$mime-ext}"));
+}
+
+// ─────────────────────────────────────────
+// BACKGROUND IMAGE (через <img> в HTML)
+// ─────────────────────────────────────────
+
+/// Контейнер с фоновым изображением
+/// Применяется к секции (hero, banner)
+/// @example scss
+///   .hero {
+///     @include bg-image-container;
+///   }
+/// @output position: relative + overflow: hidden
+/// @group mixins-image
+/// @access public
+@mixin bg-image-container {
+  position: relative;
+  overflow: hidden;
+}
+
+/// Обёртка изображения (picture или div)
+/// Абсолютно позиционируется на весь контейнер
+/// @param {Number} $z-index [0] - z-index обёртки
+/// @example scss
+///   .hero__bg {
+///     @include bg-image-wrap(-1);
+///   }
+/// @output position: absolute + inset: 0
+/// @group mixins-image
+/// @access public
+@mixin bg-image-wrap($z-index: 0) {
+  position: absolute;
+  inset: 0;
+  z-index: $z-index;
+}
+
+/// Само изображение — заполняет контейнер
+/// С fallback для IE11 (translate) и modern (object-fit)
+/// @param {String} $position [center] - object-position
+/// @param {String} $fit [cover] - object-fit
+/// @example scss
+///   .hero__image {
+///     @include bg-image(center, cover);
+///   }
+/// @example scss - Верх изображения
+///   .portrait {
+///     @include bg-image(top, cover);
+///   }
+/// @output object-fit + object-position с fallback для IE11
+/// @group mixins-image
+/// @access public
+@mixin bg-image($position: center, $fit: cover) {
+  // FALLBACK: для IE11
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  min-width: 100%;
+  min-height: 100%;
+  width: auto;
+  height: auto;
+
+  // MODERN: object-fit
+  @supports (object-fit: #{$fit}) {
+    position: static;
+    transform: none;
+    width: 100%;
+    height: 100%;
+    object-fit: $fit;
+    object-position: $position;
+  }
+}
+
+/// Комбинированный миксин для picture элемента с img внутри
+/// @param {Number} $z-index [0] - z-index
+/// @param {String} $position [center] - object-position
+/// @require {mixin} bg-image-wrap
+/// @require {mixin} bg-image
+/// @example scss
+///   .hero__picture {
+///     @include bg-picture(-1, center);
+///   }
+/// @example html
+///   <picture class="hero__picture">
+///     <source srcset="image.webp" type="image/webp">
+///     <img src="image.jpg" alt="">
+///   </picture>
+/// @output Обёртка + стили для img внутри
+/// @group mixins-image
+/// @access public
+@mixin bg-picture($z-index: 0, $position: center) {
+  @include bg-image-wrap($z-index);
+
+  img {
+    @include bg-image($position);
+  }
+}
+
+// ─────────────────────────────────────────
+// FULL-BLEED SECTION (фон на всю ширину, контент в container)
+// ─────────────────────────────────────────
+
+/// Секция с фоном на всю ширину
+/// Применяется к внешней обёртке
+/// @example scss
+///   .about {
+///     @include section-full-bleed;
+///   }
+/// @output width: 100%
+/// @group mixins-layout
+/// @access public
+@mixin section-full-bleed {
+  width: 100%;
+}
+
+/// Внутренний контейнер секции
+/// Применяется к .container внутри
+/// @require {mixin} container
+/// @example scss
+///   .about__container {
+///     @include section-contained;
+///   }
+/// @output @include container
+/// @group mixins-layout
+/// @access public
+@mixin section-contained {
+  @include container;
+}
+
+/// Контейнер с ограниченной шириной
+/// Используется для центрирования контента
+/// @output width, max-width, margin-inline, padding-inline
+/// @group mixins-layout
+/// @access public
+@mixin container {
+  width: 100%;
+  max-width: breakpoints.$breakpoint-xxxxl;
+  margin-inline: auto;
+  padding-inline: 1rem;
+}
+
+/// Контейнер с шириной от края до края
+/// Используется растягивания
+/// @output margin
+/// @group mixins-layout
+/// @access public
+@mixin container-fluid {
+  margin: 0 auto;
+}
+
+// ─────────────────────────────────────────
+// FLEX SHORTCUTS
+// ─────────────────────────────────────────
+
+/// Flex row с gap и fallback
+/// Горизонтальный flex-контейнер
+/// @param {Number | List} $gap [0] - Gap или (row-gap, column-gap)
+/// @param {String} $justify [flex-start] - justify-content значение
+/// @param {String} $align [stretch] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss - Простой список
+///   .nav__list {
+///     @include flex-row($gap-sm);
+///   }
+/// @example scss - С выравниванием
+///   .card__actions {
+///     @include flex-row($gap-md, flex-end, center);
+///   }
+/// @example scss - С кастомным селектором
+///   .header__nav {
+///     @include flex-row($gap-lg, flex-start, center, ".nav__item");
+///   }
+/// @output display: flex + flex-direction: row + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-row($gap: 0, $justify: flex-start, $align: stretch, $selector: "> *") {
+  display: flex;
+  flex-direction: row;
+  justify-content: $justify;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, row, $selector);
+  }
+}
+
+/// Flex column с gap и fallback
+/// Вертикальный flex-контейнер (стек)
+/// @param {Number | List} $gap [0] - Gap или (row-gap, column-gap)
+/// @param {String} $justify [flex-start] - justify-content значение
+/// @param {String} $align [stretch] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss - Вертикальный стек
+///   .card__content {
+///     @include flex-column($gap-sm);
+///   }
+/// @example scss - Центрированный стек
+///   .hero__content {
+///     @include flex-column($gap-lg, center, center);
+///   }
+/// @example scss - Растянутый на всю высоту
+///   .sidebar {
+///     @include flex-column($gap-md, space-between);
+///   }
+/// @output display: flex + flex-direction: column + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-column($gap: 0, $justify: flex-start, $align: stretch, $selector: "> *") {
+  display: flex;
+  flex-direction: column;
+  justify-content: $justify;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, column, $selector);
+  }
+}
+
+/// Flex space-between с gap
+/// Элементы распределены по краям с промежутками между
+/// @param {Number | List} $gap [0] - Gap между элементами
+/// @param {String} $align [center] - align-items значение
+/// @param {Boolean} $wrap [false] - Включить flex-wrap
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @require {mixin} flex-gap-wrap
+/// @example scss - Без wrap
+///   .header__wrapper {
+///     @include flex-between($gap-md);
+///   }
+/// @example scss - С wrap
+///   .footer__links {
+///     @include flex-between($gap-md, center, true);
+///   }
+/// @example scss - С кастомным селектором
+///   .toolbar {
+///     @include flex-between($gap-lg, center, true, ".toolbar__item");
+///   }
+/// @output display: flex + justify-content: space-between + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-between($gap: 0, $align: center, $wrap: false, $selector: "> *") {
+  display: flex;
+  justify-content: space-between;
+  align-items: $align;
+
+  @if $wrap {
+    flex-wrap: wrap;
+
+    @if $gap != 0 {
+      @include flex-gap-wrap($gap, $selector);
+    }
+  } @else {
+    flex-wrap: nowrap;
+    @if $gap != 0 {
+      @include flex-gap($gap, row, $selector);
+    }
+  }
+}
+
+/// Flex space-around с gap
+/// Элементы распределены с равными промежутками вокруг
+/// @param {Number | List} $gap [0] - Gap между элементами
+/// @param {String} $align [center] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss
+///   .features__list {
+///     @include flex-around($gap-md);
+///   }
+/// @output display: flex + justify-content: space-around + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-around($gap: 0, $align: center, $selector: "> *") {
+  display: flex;
+  justify-content: space-around;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, row, $selector);
+  }
+}
+
+/// Flex center — центрирование по обеим осям
+/// Идеально для центрирования иконок, модалок, лоадеров
+/// @param {Number | List} $gap [0] - Gap между элементами (если несколько)
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss - Центрирование иконки
+///   .btn__icon-wrapper {
+///     @include flex-center;
+///   }
+/// @example scss - Группа элементов по центру
+///   .social-links {
+///     @include flex-center($gap-sm);
+///   }
+/// @example scss - Модальное окно
+///   .modal-overlay {
+///     @include flex-center;
+///   }
+/// @output display: flex + justify-content: center + align-items: center
+/// @group mixins-flex
+/// @access public
+@mixin flex-center($gap: 0, $selector: "> *") {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, both, $selector);
+  }
+}
+
+/// Flex wrap с gap и fallback
+/// Для элементов, которые переносятся на новую строку (теги, галереи)
+/// @param {Number | List} $gap [0] - Gap или (row-gap, column-gap)
+/// @param {String} $justify [flex-start] - justify-content значение
+/// @param {String} $align [stretch] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap-wrap
+/// @example scss - Теги
+///   .tags {
+///     @include flex-wrap($gap-xs);
+///   }
+/// @example scss - Галерея
+///   .gallery {
+///     @include flex-wrap($gap-sm, center);
+///   }
+/// @example scss - Разный gap по осям
+///   .grid-fallback {
+///     @include flex-wrap(($gap-lg, $gap-md));
+///   }
+/// @output display: flex + flex-wrap: wrap + gap с fallback через margin
+/// @group mixins-flex
+/// @access public
+@mixin flex-wrap($gap: 0, $justify: flex-start, $align: stretch, $selector: "> *") {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: $justify;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap-wrap($gap, $selector);
+  }
+}
+
+/// Flex end — выравнивание к концу
+/// Для кнопок действий, pagination и т.п.
+/// @param {Number | List} $gap [0] - Gap между элементами
+/// @param {String} $align [center] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss - Кнопки формы
+///   .form__actions {
+///     @include flex-end($gap-sm);
+///   }
+/// @example scss - Pagination
+///   .pagination {
+///     @include flex-end($gap-xs);
+///   }
+/// @output display: flex + justify-content: flex-end + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-end($gap: 0, $align: center, $selector: "> *") {
+  display: flex;
+  justify-content: flex-end;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, row, $selector);
+  }
+}
+
+/// Flex start — выравнивание к началу (явное)
+/// @param {Number | List} $gap [0] - Gap между элементами
+/// @param {String} $align [center] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss
+///   .breadcrumbs {
+///     @include flex-start($gap-xs);
+///   }
+/// @output display: flex + justify-content: flex-start + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin flex-start($gap: 0, $align: center, $selector: "> *") {
+  display: flex;
+  justify-content: flex-start;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, row, $selector);
+  }
+}
+
+/// Inline flex с gap
+/// Для инлайновых flex-контейнеров
+/// @param {Number | List} $gap [0] - Gap между элементами
+/// @param {String} $justify [flex-start] - justify-content значение
+/// @param {String} $align [center] - align-items значение
+/// @param {String} $selector ["> *"] - Селектор дочерних элементов для fallback
+/// @require {mixin} flex-gap
+/// @example scss - Иконка с текстом
+///   .link-with-icon {
+///     @include inline-flex($gap-xs);
+///   }
+/// @example scss - Badge
+///   .badge {
+///     @include inline-flex($gap-xs, center, center);
+///   }
+/// @output display: inline-flex + gap с fallback
+/// @group mixins-flex
+/// @access public
+@mixin inline-flex($gap: 0, $justify: flex-start, $align: center, $selector: "> *") {
+  display: inline-flex;
+  justify-content: $justify;
+  align-items: $align;
+
+  @if $gap != 0 {
+    @include flex-gap($gap, row, $selector);
+  }
+}