@omnisass/library 0.2.0

package/modules/utilities/getters/number/_get-number-width-by-ratio.scss

@@ -0,0 +1,223 @@
+@use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Вычисляет ширину на основе высоты и соотношения сторон.
+///
+/// Функция рассчитывает ширину элемента по заданной высоте и
+/// соотношению сторон (aspect ratio). Соотношение сторон
+/// определяется как `ширина / высота`. Эта функция является
+/// обратной к `get-number-height-by-ratio()` и используется в
+/// тех же сценариях адаптивного веб-дизайна, когда известна
+/// высота, но нужно вычислить соответствующую ширину для
+/// сохранения пропорций.
+///
+/// Математическая формула:
+/// - `width = height × ratio` (где `ratio = width / height`)
+///
+/// Свойства результата:
+/// - При `ratio = 1` (квадрат) → ширина равна высоте
+/// - При `ratio > 1` (альбомная ориентация) → ширина больше
+/// 	высоты
+/// - При `ratio < 1` (портретная ориентация) → ширина меньше
+/// 	высоты
+/// - Результат имеет те же единицы измерения, что и `$height`
+/// - Функция сохраняет пропорции исходного соотношения сторон
+///
+/// Важные особенности функции:
+/// - Вычисляет ширину по высоте и соотношению сторон
+/// - Использует умножение вместо деления (более эффективно)
+/// - Сохраняет единицы измерения высоты (px, rem, em, %, и т.д.)
+/// - Поддерживает дробные значения соотношения сторон
+/// - Идеально подходит для вертикально-ориентированных
+/// 	интерфейсов
+/// - Является парной функцией к `get-number-height-by-ratio()`
+///
+/// > Вычисление ширины по соотношению сторон особенно полезно
+/// > в мобильных интерфейсах и вертикальных макетах, где высота
+/// > может быть фиксированной или известной заранее. Этот подход
+/// > позволяет создавать адаптивные элементы, которые сохраняют
+/// > пропорции независимо от ориентации устройства.
+/// >
+/// > Пример: для отображения изображения 4:3 с высотой 300px,
+/// > ширина будет вычислена как 300 × (4/3) = 400px.
+/// ---
+/// @name get-number-width-by-ratio
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/values/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/modules/math См. также: Официальная документация Sass - Модуль math
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio См. также: MDN Web Docs - CSS свойство aspect-ratio
+/// @link https://css-tricks.com/aspect-ratio-boxes/ См. также: CSS-Tricks - Блоки с фиксированным соотношением сторон
+/// @link https://www.w3schools.com/howto/howto_css_aspect_ratio.asp См. также: W3Schools - Как создавать блоки с фиксированным соотношением сторон
+/// @example scss - Стандартные соотношения сторон видео
+/// 	@debug get-number-width-by-ratio(450px, math.div(16, 9));  // 800px
+/// 	@debug get-number-width-by-ratio(450px, 1.7777777778);    // 800.00000001px
+/// 	@debug get-number-width-by-ratio(600px, math.div(4, 3));   // 800px
+/// 	@debug get-number-width-by-ratio(600px, 1.3333333333);    // 799.99999998px
+/// 	@debug get-number-width-by-ratio(342.8571428571px, math.div(21, 9));  // 799.9999999999px
+/// 	@debug get-number-width-by-ratio(342.8571428571px, 2.3333333333);    // 799.9999999884714px
+/// @example scss - Квадратные и прямоугольные элементы
+/// 	@debug get-number-width-by-ratio(400px, 1);                // 400px (квадрат)
+/// 	@debug get-number-width-by-ratio(300px, 2);                // 600px (горизонтальный прямоугольник 2:1)
+/// 	@debug get-number-width-by-ratio(1200px, 0.5);             // 600px (вертикальный прямоугольник 1:2)
+/// 	@debug get-number-width-by-ratio(200px, math.div(3, 2));   // 300px (3:2)
+/// 	@debug get-number-width-by-ratio(450px, math.div(2, 3));   // 300px (2:3)
+/// @example scss - Разные единицы измерения
+/// 	@debug get-number-width-by-ratio(56.25%, math.div(16, 9)); // 100%
+/// 	@debug get-number-width-by-ratio(28.125rem, math.div(16, 9));  // 50rem
+/// 	@debug get-number-width-by-ratio(45vw, math.div(16, 9));   // 80vw
+/// 	@debug get-number-width-by-ratio(675px, math.div(16, 9));  // 1200px
+/// 	@debug get-number-width-by-ratio(48em, math.div(4, 3));    // 64em
+/// @example scss - Дробные значения высоты
+/// 	@debug get-number-width-by-ratio(422.15625px, math.div(16, 9)); // 750.5px
+/// 	@debug get-number-width-by-ratio(683.1666666667px, 1.5);    // 1024.75000000005px
+/// 	@debug get-number-width-by-ratio(205rem, math.div(5, 4));   // 256.25rem
+/// 	@debug get-number-width-by-ratio(61.7435117429%, 1.618);    // 99.9010020000122% (золотое сечение)
+/// @example scss - Популярные соотношения сторон (обратные вычисления)
+/// 	// 1:1 - Квадрат, Instagram фото
+/// 	@debug get-number-width-by-ratio(500px, 1);                // 500px
+///
+/// 	// 4:3 - Стандартный монитор, некоторые планшеты
+/// 	@debug get-number-width-by-ratio(768px, math.div(4, 3));   // 1024px
+///
+/// 	// 16:9 - Современное видео, Full HD
+/// 	@debug get-number-width-by-ratio(1080px, math.div(16, 9)); // 1920px
+///
+/// 	// 21:9 - Ультраширокий монитор, кинематографичный формат
+/// 	@debug get-number-width-by-ratio(1097.1428571429px, math.div(21, 9)); // 2560.0000000001005px
+///
+/// 	// 3:2 - Некоторые фотоаппараты, MacBook
+/// 	@debug get-number-width-by-ratio(1200px, math.div(3, 2));  // 1800px
+///
+/// 	// 1.618:1 - Золотое сечение
+/// 	@debug get-number-width-by-ratio(618.0463572312px, 1.618); // 999.9990060000816px
+/// @example scss - Для вертикальных адаптивных контейнеров
+/// 	.vertical-video-container {
+/// 		height: 100vh;
+/// 		width: get-number-width-by-ratio(100vh, math.div(9, 16));
+/// 	}
+///
+/// 	.portrait-image {
+/// 		height: 500px;
+/// 		width: get-number-width-by-ratio(500px, math.div(3, 4));
+/// 	}
+///
+/// 	.mobile-card {
+/// 		height: 200px;
+/// 		width: get-number-width-by-ratio(200px, math.div(4, 5));
+/// 	}
+/// @example css - Результат
+/// 	.vertical-video-container {
+/// 		height: 100vh;
+/// 		width: 56.25vh;
+/// 	}
+///
+/// 	.portrait-image {
+/// 		height: 500px;
+/// 		width: 375px;
+/// 	}
+///
+/// 	.mobile-card {
+/// 		height: 200px;
+/// 		width: 160px;
+/// 	}
+/// @example scss - Динамические вычисления для известной высоты
+/// 	$container-height: 675px;
+/// 	$aspect-ratio: math.div(16, 9);
+/// 	@debug get-number-width-by-ratio($container-height, $aspect-ratio); // 1200px
+///
+/// 	$mobile-height: 210.9375px;
+/// 	@debug get-number-width-by-ratio($mobile-height, $aspect-ratio); // 375px
+/// @example scss - Проверка граничных значений
+/// 	@debug get-number-width-by-ratio(0px, math.div(16, 9));    // 0px
+/// 	@debug get-number-width-by-ratio(1000px, 0);               // 0px (соотношение 0 означает нулевую ширину)
+/// 	// @debug get-number-width-by-ratio(1000px, math.infinity()); // infinity (теоретически), а так Error
+/// @example scss - Очень большие и малые соотношения
+/// 	@debug get-number-width-by-ratio(100px, 10);               // 1000px (очень широкий)
+/// 	@debug get-number-width-by-ratio(10000px, 0.1);            // 1000px (очень узкий)
+/// 	@debug get-number-width-by-ratio(5px, 100);                // 500px
+/// 	@debug get-number-width-by-ratio(50000px, 0.01);           // 500px
+/// @param {Number} $height - Высота элемента. Может быть
+/// 	любым числом с единицами измерения (`px`, `rem`, `em`,
+/// 	`%`, `vh`, и т.д.)
+/// 	или без них.
+/// @param {Number} $ratio - Соотношение сторон, вычисляемое
+/// 	как `ширина / высота`. Например:
+///   - 1.7777777778 для 16:9
+///   - 1.3333333333 для 4:3
+///   - 1 для квадрата
+///   - 0.75 для портретного формата 3:4
+/// @return {Number} - Ширина элемента, рассчитанная по формуле
+/// 	`width = height × ratio`. Сохраняет единицы измерения
+/// 	параметра `$height`.
+@function get-number-width-by-ratio($height, $ratio) {
+
+	@if not is-number($height) {
+
+		// Валидация первого параметра: высота.
+		// Функция ожидает числовое значение, которое может содержать
+		// единицы измерения (px, rem, em, %, и т.д.).
+		//
+		// Если $height не является числом (например, строка, булево
+		// значение), вызываем стандартизированную функцию
+		// логирования ошибок.
+		@return log-invalid-type(
+			'get-number-width-by-ratio',
+			$height,
+			'$height',
+			'number'
+		);
+
+	}
+
+	@else if not is-number($ratio) {
+
+		// Валидация второго параметра: соотношение сторон.
+		// Соотношение должно быть числом (чаще всего безразмерным).
+		//
+		// Проверка выполняется только если $height прошел валидацию.
+		// Это последовательный подход fail-fast (быстрая остановка
+		// при ошибке).
+		@return log-invalid-type(
+			'get-number-width-by-ratio',
+			$ratio,
+			'$ratio',
+			'number'
+		);
+
+	}
+
+	@else {
+
+		// Оба параметра валидны - выполняем вычисление.
+		//
+		// Формула: ширина = высота × соотношение.
+		//
+		// Важные аспекты:
+		// 1. Умножение $height (с единицами) на $ratio (безразмерное)
+		//    сохраняет единицы измерения из $height
+		// 2. Если $ratio также имеет единицы, Sass попытается их
+		//    перемножить, что может привести к неожиданным результатам
+		// 3. Рекомендуется передавать $ratio как безразмерное число
+		@return $height * $ratio;
+
+	}
+
+}
+
+/// @name get-width-by-ratio
+/// @alias get-number-width-by-ratio
+/// @group utilities-aliases
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+@function get-width-by-ratio($height, $ratio) {
+	@return get-number-width-by-ratio($height, $ratio);
+}

package/modules/utilities/helpers/color/_color-blend-steps.scss

@@ -0,0 +1,210 @@
+@use 'sass:math';
+@use 'sass:list';
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Создает последовательность равномерно распределенных
+/// цветов между двумя точками.
+///
+/// Функция `color-blend-steps()` генерирует список
+/// промежуточных цветов, равномерно распределенных между
+/// начальным и конечным цветами.
+///
+/// Каждый цвет в последовательности представляет собой
+/// линейную интерполяцию между `$color-start` и `$color-end` с
+/// определенным процентом смешивания. Полезно для создания
+/// цветовых градиентов с дискретными остановками, генерации
+/// палитр или построения систем цветовых переходов с
+/// контролируемым количеством шагов.
+///
+/// > Все шаги равномерно распределены математически, но визуально
+/// > могут восприниматься неравномерно в зависимости от цветового
+/// > пространства.
+/// ---
+/// @name color-blend-steps
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/color#mix См. также: Sass - Функция color.mix()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient См. также: MDN - Линейные градиенты
+/// @link https://www.w3.org/TR/css-color-5/#color-mix См. также: W3C - Спецификация color-mix
+/// @link https://css-tricks.com/striped-css-gradients/ См. также: CSS-Tricks - Полосатые CSS-градиенты
+/// @example scss - Использование для CSS-переменных
+/// 	@use 'sass:list';
+///
+/// 	:root {
+///
+/// 		$transition: color-blend-steps(#3498db, #2c3e50, 4);
+///
+/// 		@for $i from 1 through list.length($transition) {
+/// 			--color-step-#{$i}: #{list.nth($transition, $i)};
+/// 		}
+///
+/// 	}
+/// @example css - Результат
+/// 	:root {
+/// 		--color-step-1: #3498db;
+/// 		--color-step-2: rgb(50, 129.5, 184.25);
+/// 		--color-step-3: rgb(48, 107, 149.5);
+/// 		--color-step-4: rgb(46, 84.5, 114.75);
+/// 		--color-step-5: #2c3e50;
+/// 	}
+/// @example scss - Создание плавного hover-эффекта с шагами
+/// 	@use 'sass:list';
+///
+/// 	.progress-bar {
+/// 		$colors: color-blend-steps(#2ecc71, #e74c3c, 5);
+///
+/// 		@for $i from 1 through list.length($colors) {
+/// 			&--step-#{$i} {
+/// 				background-color: list.nth($colors, $i);
+/// 			}
+/// 		}
+///
+/// 	}
+/// @example css - Результат
+/// 	.progress-bar--step-1 {
+/// 		background-color: #2ecc71;
+/// 	}
+/// 	.progress-bar--step-2 {
+/// 		background-color: rgb(83, 178.4, 102.4);
+/// 	}
+/// 	.progress-bar--step-3 {
+/// 		background-color: rgb(120, 152.8, 91.8);
+/// 	}
+/// 	.progress-bar--step-4 {
+/// 		background-color: rgb(157, 127.2, 81.2);
+/// 	}
+/// 	.progress-bar--step-5 {
+/// 		background-color: rgb(194, 101.6, 70.6);
+/// 	}
+/// 	.progress-bar--step-6 {
+/// 		background-color: #e74c3c;
+/// 	}
+/// @example scss - Генерация градиента с дискретными остановками
+/// 	@use 'sass:list';
+///
+///		.gradient-stripes {
+///			background: linear-gradient(
+///				to right,
+///				#{list.nth(color-blend-steps(#ff0000, #00ff00, 5), 1)},
+///				#{list.nth(color-blend-steps(#ff0000, #00ff00, 5), 3)},
+///				#{list.nth(color-blend-steps(#ff0000, #00ff00, 5), 5)},
+///				#{list.nth(color-blend-steps(#ff0000, #00ff00, 5), 6)},
+///			);
+///		}
+/// @example css - Результат
+/// 	gradient-stripes {
+/// 		background: linear-gradient(to right, red, #996600, #33cc00, lime);
+/// 	}
+/// @param {Color} $color-start - Начальный цвет последовательности.
+/// 	Может быть в любом формате, поддерживаемом Sass (HEX, RGB,
+/// 	HSL и т.д.).
+/// @param {Color} $color-end - Конечный цвет последовательности.
+/// 	Должен быть совместим по цветовому пространству с `$color-start`.
+/// @param {Number} $steps [5] - Количество промежуточных шагов
+/// 	между цветами. Определяет, сколько цветов будет сгенерировано
+/// 	между начальным и конечным. Фактическое количество цветов в
+/// 	результате = `$steps + 2`. Минимальное значение - `0` (вернет
+/// 	только начальный и конечный цвета).
+/// @return {List} - Упорядоченный список (list) цветов, где:
+/// - Первый элемент: чистый `$color-start` (0% смешивания)
+/// - Последний элемент: чистый `$color-end` (100% смешивания)
+/// - Промежуточные элементы: равномерно распределенные смеси
+/// - Всего элементов: `$steps + 2`
+@function color-blend-steps($color-start, $color-end, $steps: 5) {
+
+	// Инициализация списка для хранения промежуточных цветов.
+	// Результатом функции будет список (массив) цветов,
+	// представляющих градиентный переход от начального цвета
+	// к конечному.
+	$-colors: ();
+
+	// Проверка типа первого параметра: ожидается начальный цвет.
+	// Функция is-color() проверяет, является ли $color-start
+	// валидным цветом CSS.
+	@if not is-color($color-start) {
+
+		// Если $color-start не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-blend-steps',
+			$color-start,
+			'$color-start',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается конечный цвет.
+	// Проверка выполняется только если $color-start прошел валидацию.
+	@else if not is-color($color-end) {
+
+		// Если $color-end не является цветом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-blend-steps',
+			$color-end,
+			'$color-end',
+			'color'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается количество шагов.
+	// $steps определяет, сколько промежуточных цветов будет сгенерировано
+	// между начальным и конечным цветом.
+	@else if not is-number($steps) {
+
+		// Если $steps не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-blend-steps',
+			$steps,
+			'$steps',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем генерацию цветов.
+	@else {
+
+		// Цикл генерации промежуточных цветов.
+		// Переменная $i принимает значения от 0 до $steps включительно.
+		// Это создает $steps + 1 цвет в итоговом списке
+		// (включая начальный и конечный цвета).
+		@for $i from 0 through $steps {
+
+			// Вычисление процентного соотношения для текущего шага.
+			// Формула: (текущий шаг) × (100% / общее количество шагов)
+			// Пример для 5 шагов: шаги будут на 0%, 20%, 40%, 60%, 80%, 100%
+			$-percentage: $i * math.div(100, $steps);
+
+			// Создание промежуточного цвета с помощью функции color.mix()
+			// color.mix() смешивает два цвета в указанной пропорции.
+			// Параметры:
+			// - $color-end: первый цвет для смешивания
+			// - $color-start: второй цвет для смешивания
+			// - $-percentage * 1%: процентное соотношение
+			//   (сколько процентов $color-start в смеси)
+			//
+			// Примечание: порядок параметров в color.mix() важен:
+			// - При $-percentage = 0% → 100% $color-end, 0% $color-start
+			// - При $-percentage = 100% → 0% $color-end, 100% $color-start
+			$-colors: list.append($-colors, color.mix($color-end, $color-start, $-percentage * 1%));
+
+		}
+
+		// Возвращаем список сгенерированных цветов.
+		// Список содержит $steps + 1 элементов, равномерно распределенных
+		// между начальным и конечным цветом.
+		@return $-colors;
+
+	}
+
+}

package/modules/utilities/helpers/color/_color-blend.scss

@@ -0,0 +1,183 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Линейная интерполяция (смешивание) между двумя цветами.
+///
+/// Функция `color-blend()` создает промежуточный цвет между
+/// двумя заданными точками, используя линейную интерполяцию.
+///
+/// Это упрощенная обертка над встроенной функцией
+/// `color.mix()` с автоматическим преобразованием процента.
+/// Полезно для создания плавных переходов, градиентов,
+/// оттенков или любого промежуточного состояния между двумя
+/// цветами.
+///
+/// > Функция автоматически добавляет единицы % к
+/// > параметру `$percentage`.
+///
+/// > Для сложных градиентов или смешивания в специфических
+/// > пространствах используйте встроенную функцию
+/// > `color.mix()` напрямую.
+///
+/// > Результат зависит от цветового пространства смешивания
+/// > по умолчанию. Для контроля пространства используйте
+/// > `color.mix()` с параметром `$space`.
+/// ---
+/// @name color-blend
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/color#mix См. также: Sass - Функция color.mix()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix См. также: MDN - CSS функция color-mix()
+/// @link https://www.w3.org/TR/css-color-5/#color-mix См. также: W3C - Спецификация color-mix
+/// @link https://css-tricks.com/color-mix-function/ См. также: CSS-Tricks - Функция color-mix()
+/// @example scss - Создание промежуточного оттенка
+/// 	$mid-color: color-blend(#ff0000, #0000ff, 50);
+///
+/// 	// Результат: #800080 (фиолетовый)
+/// 	.element {
+/// 		color: $mid-color;
+/// 	}
+/// @example css - Результат
+/// 	.element {
+/// 		color: rgb(127.5, 0, 127.5);
+/// 	}
+/// @example scss - Плавный hover-эффект
+/// 	.button {
+/// 		background-color: #3498db;
+///
+///			&:hover {
+///				// Плавное затемнение при наведении
+///				background-color: color-blend(#3498db, #2c3e50, 70);
+///			}
+///
+///		}
+/// @example css - Результат
+/// 	.button {
+/// 		background-color: #3498db;
+/// 	}
+///
+/// 	.button:hover {
+/// 		background-color: rgb(46.4, 89, 121.7);
+/// 	}
+/// @example scss - Создание градиента с несколькими остановками
+/// 	.gradient-box {
+///
+/// 		background: linear-gradient(
+/// 			to right,
+/// 			color-blend(#ff0000, #00ff00, 0),
+/// 			color-blend(#ff0000, #00ff00, 25),
+/// 			color-blend(#ff0000, #00ff00, 50),
+/// 			color-blend(#ff0000, #00ff00, 75),
+/// 			color-blend(#ff0000, #00ff00, 100)
+/// 		);
+///
+/// 	}
+/// @example css - Результат
+/// 	.gradient-box {
+/// 		background: linear-gradient(to right, red, rgb(191.25, 63.75, 0), rgb(127.5, 127.5, 0), rgb(63.75, 191.25, 0), lime);
+/// 	}
+/// @example scss - Осветление и затемнение через смешивание
+/// 	// Лучше использовать функции color-shade и color-tint
+/// 	// из набора OmniSass.
+///
+/// 	$base-color: #9b59b6;
+/// 	$lightened: color-blend($base-color, white, 30);  // Осветление на 30%
+/// 	$darkened: color-blend($base-color, black, 30);   // Затемнение на 30%
+/// @see color-shade
+/// @see color-tint
+/// @param {Color} $color-from - Исходный (начальный) цвет. Может
+/// 	быть в любом формате, поддерживаемом Sass (HEX, RGB,
+/// 	HSL и т.д.).
+/// @param {Color} $color-to - Целевой (конечный) цвет. Автоматически
+/// 	приводится к тому же цветовому пространству, что и
+/// 	`$color-from`.
+/// @param {Number} $percentage - Процент смешивания от
+/// 	`$color-from` к `$color-to` (0-100). Значение автоматически
+/// 	конвертируется в проценты с помощью умножения на 1%.
+/// - 0: возвращает чистый цвет `$color-from`
+/// - 100: возвращает чистый цвет `$color-to`
+/// - 50: возвращает ровную смесь `50/50`
+/// @return {Color} - Промежуточный цвет, полученный линейной
+/// 	интерполяцией между `$color-from` и `$color-to` в указанной пропорции.
+/// 	Использует цветовое пространство по умолчанию для
+/// 	смешивания (обычно sRGB).
+@function color-blend($color-from, $color-to, $percentage) {
+
+	// Проверка типа первого параметра: ожидается начальный цвет.
+	// Функция is-color() проверяет, является ли $color-from
+	// валидным цветом CSS.
+	@if not is-color($color-from) {
+
+		// Если $color-from не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-blend',
+			$color-from,
+			'$color-from',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается конечный цвет.
+	// Проверка выполняется только если $color-from прошел валидацию.
+	@else if not is-color($color-to) {
+
+		// Если $color-to не является цветом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-blend',
+			$color-to,
+			'$color-to',
+			'color'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается процент смешивания.
+	// $percentage определяет, сколько процентов начального цвета
+	// будет в итоговой смеси (от 0 до 100).
+	@else if not is-number($percentage) {
+
+		// Если $percentage не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-blend',
+			$percentage,
+			'$percentage',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем смешивание цветов.
+	@else {
+
+		// Формула смешивания: создаем промежуточный цвет между
+		// $color-from и $color-to с указанным процентным соотношением.
+		//
+		// Используем встроенную функцию color.mix():
+		// Параметры:
+		// - $color-to: первый цвет для смешивания
+		// - $color-from: второй цвет для смешивания
+		// - $percentage * 1%: процентное соотношение
+		//   (сколько процентов $color-from в смеси)
+		//
+		// Математика смешивания:
+		// - При $percentage = 0% → 100% $color-to, 0% $color-from
+		// - При $percentage = 50% → 50% $color-to, 50% $color-from
+		// - При $percentage = 100% → 0% $color-to, 100% $color-from
+		//
+		// Ключевая особенность: функция является оберткой над
+		// color.mix() с добавлением валидации параметров и
+		// преобразованием процентов в правильный формат.
+		@return color.mix($color-to, $color-from, $percentage * 1%);
+
+	}
+
+}