@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/scripts/classes/StylesToVirtual/StylesToVirtual.en.mdx

@@ -0,0 +1,36 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/StylesToVirtual - Pseudo-Element Generator'/>
+
+# StylesToVirtual Class
+
+The `StylesToVirtual` class is responsible for generating CSS pseudo-elements (like `::before`, `::after`) and their associated styles.
+
+## Key Features
+
+- **Pseudo-Element Wrapping** — Automatically wraps content within a `&::[name]` selector.
+- **Automatic Content Property** — For pseudo-elements like `before` and `after`, it automatically injects `content: ' ';` if not otherwise specified.
+- **Indentation Management** — Correctly handles block indentation and optional leading empty lines.
+
+## Initialization
+
+Initialize the `StylesToVirtual` converter with the required property and content callable.
+
+**Parameters:**
+- `property: PropertyItemsItem` — the current branch of the property tree being processed.
+- `space: string` — the indentation string.
+- `content?: () => string[]` — a callable function that returns an array of strings representing the style rules for the pseudo-element.
+- `first?: boolean` — indicates if this is the first element (optional).
+
+```typescript
+import { StylesToVirtual } from '@dxtmisha/scripts'
+
+const converter = new StylesToVirtual(property, '  ', contentCallable)
+const result = converter.make()
+```
+
+## Methods
+
+### Control
+
+- `make(): string[]` — The main entry point. Orchestrates the process of wrapping nested styles in a pseudo-element block.

package/src/media/functional/scripts/classes/StylesToVirtual/StylesToVirtual.ru.mdx

@@ -0,0 +1,36 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/StylesToVirtual - Генератор псевдоэлементов'/>
+
+# Класс StylesToVirtual
+
+Класс `StylesToVirtual` отвечает за создание CSS-псевдоэлементов (таких как `::before`, `::after`) и связанных с ними стилей.
+
+## Ключевые возможности
+
+- **Обертка псевдоэлементов** — Автоматически оборачивает контент в селектор `&::[name]`.
+- **Автоматическое свойство content** — Для псевдоэлементов, таких как `before` и `after`, автоматически внедряет `content: ' ';`, если иное не указано.
+- **Управление отступами** — Правильно обрабатывает отступы блоков и необязательные начальные пустые строки.
+
+## Инициализация
+
+Инициализируйте преобразователь `StylesToVirtual` с помощью необходимого свойства и функции контента.
+
+**Параметры:**
+- `property: PropertyItemsItem` — текущая обрабатываемая ветвь дерева свойств.
+- `space: string` — строка отступа.
+- `content?: () => string[]` — вызываемая функция, которая возвращает массив строк, представляющих стили для псевдоэлемента.
+- `first?: boolean` — указывает, является ли элемент первым (необязательно).
+
+```typescript
+import { StylesToVirtual } from '@dxtmisha/scripts'
+
+const converter = new StylesToVirtual(property, '  ', contentCallable)
+const result = converter.make()
+```
+
+## Методы
+
+### Управление
+
+- `make(): string[]` — Основная точка входа. Организует процесс обертывания вложенных стилей в блок псевдоэлемента.

package/src/media/functional/scripts/classes/StylesToVirtual/StylesToVirtual.vi.mdx

@@ -0,0 +1,36 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/StylesToVirtual - Trình tạo Pseudo-Element'/>
+
+# Lớp StylesToVirtual
+
+Lớp `StylesToVirtual` chịu trách nhiệm tạo các phần tử giả CSS (như `::before`, `::after`) và các kiểu liên quan của chúng.
+
+## Các tính năng chính
+
+- **Bao bọc Pseudo-Element** — Tự động bao bọc nội dung bên trong bộ chọn `&::[name]`.
+- **Thuộc tính Content tự động** — Đối với các phần tử giả như `before` và `after`, nó tự động chèn `content: ' ';` nếu không có quy định khác.
+- **Quản lý thụt lề** — Xử lý chính xác thụt lề khối và các dòng trống dẫn đầu tùy chọn.
+
+## Khởi tạo
+
+Khởi tạo trình chuyển đổi `StylesToVirtual` với thuộc tính bắt buộc và hàm gọi nội dung.
+
+**Tham số:**
+- `property: PropertyItemsItem` — nhánh hiện tại của cây thuộc tính đang được xử lý.
+- `space: string` — chuỗi thụt lề.
+- `content?: () => string[]` — một hàm có thể gọi trả về một mảng các chuỗi đại diện cho các quy tắc style cho phần tử giả.
+- `first?: boolean` — cho biết đây có phải là phần tử đầu tiên hay không (tùy chọn).
+
+```typescript
+import { StylesToVirtual } from '@dxtmisha/scripts'
+
+const converter = new StylesToVirtual(property, '  ', contentCallable)
+const result = converter.make()
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `make(): string[]` — Điểm bắt đầu chính. Điều phối quá trình bao bọc các style lồng nhau trong một khối phần tử giả.

package/src/media/functional/scripts/classes/StylesTool/StylesTool.en.mdx

@@ -0,0 +1,130 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/StylesTool - Style Processing Utilities'/>
+
+# StylesTool Class
+
+The `StylesTool` class is a high-level static utility container providing essential functions for the design system's style generation pipeline. It encapsulates logic for directory management, indentation control, SCSS directive construction, and Sass-compatibility transformations.
+
+By centralizing these low-level string manipulations and path lookups, it ensures consistency across all `StylesTo*` converters and generator classes.
+
+## Key Features
+
+- **Indentation Control** — provides a standard 2-space indentation unit and methods to scale it based on nesting levels.
+- **Directive Builders** — standardizes the syntax for SCSS `@use`, `@import`, and `@forward` statements.
+- **Path Resolution** — integrates with global configuration to determine the output destination for generated files.
+- **Sass Compatibility** — handles automated transformations of custom CSS function syntax into Sass-safe interpolation.
+- **Vertical Formatting** — manages line joining with consistent CRLF characters for Windows/UNIX compatibility.
+
+## File and Directory Methods
+
+### `getDir`
+
+Determines the target directory structure for persisting the generated style files. It combines the core style directory with the specific project name defined in the properties configuration.
+
+**Returns:** `string[]` — An array representing the path segments of the target directory.
+
+## Indentation and Spacing Methods
+
+### `getSpace`
+
+Retrieves the base indentation unit used throughout the project's generated style files.
+
+**Returns:** `string` — Returns a string consisting of 2 spaces (`  `).
+
+### `addSpace`
+
+Generates an indentation string based on a specified nesting depth level. This is used to align blocks of code within nested structures like media queries or selector blocks.
+
+**Parameters:**
+- `level: number` — The desired nesting level (0 for no indentation, 1 for 2 spaces, 2 for 4 spaces, etc.).
+
+**Returns:** `string` — The resulting indentation string.
+
+### `increaseSpace`
+
+Appends one additional level of indentation (2 spaces) to an existing space string. This is useful during recursive tree traversal where the depth increases incrementally.
+
+**Parameters:**
+- `space: string` — The current indentation string to be expanded.
+
+**Returns:** `string` — The updated indentation string with one extra level.
+
+## SCSS Directive Methods
+
+### `addImport`
+
+Constructs a standard SCSS `@import` directive for a given file path.
+
+**Parameters:**
+- `path: string` — The file path to be imported.
+
+**Returns:** `string` — The formatted directive (e.g., `@import "path/to/file";`).
+
+### `addUse`
+
+Constructs a modern SCSS `@use` directive, which is the recommended way to load member functions, mixins, and variables in modern Sass.
+
+**Parameters:**
+- `path: string` — The module path to be used.
+
+**Returns:** `string` — The formatted directive (e.g., `@use "path/to/module";`).
+
+### `addForward`
+
+Constructs an SCSS `@forward` directive. This is typically used in index files to expose members of a sub-module to users of the package.
+
+**Parameters:**
+- `path: string` — The module path to be forwarded.
+
+**Returns:** `string` — The formatted directive (e.g., `@forward "path/to/module";`).
+
+### `addImportProperties`
+
+Generates a specialized `@use` directive for the core `@dxtmisha/styles` library, aliasing it as `ui` for use in generated property blocks.
+
+**Returns:** `string` — Always returns `'@use "@dxtmisha/styles" as ui;'`.
+
+## Formatting and Utilities
+
+### `join`
+
+Combines an array of generated code lines into a single formatted string. It uses CRLF (`\r\n`) as the line separator to ensure consistent formatting across environments.
+
+**Parameters:**
+- `data: string[]` — An array of strings representing individual lines of code.
+
+**Returns:** `string` — The resulting multiline string.
+
+### `toFunctionCss`
+
+A safety utility that transforms custom `@function` calls within property values into Sass interpolation syntax (`#{...}`). This prevents Sass compilation errors when custom functions are used in contexts that require raw CSS output.
+
+**Parameters:**
+- `value: string` — The CSS property value string containing potential custom function calls.
+
+**Returns:** `string` — The transformed string with interpolated function calls.
+
+## Example Usage
+
+```typescript
+import { StylesTool } from '@dxtmisha/scripts'
+
+// 1. Getting an indentation level
+const indent = StylesTool.addSpace(2) // "    "
+
+// 2. Creating an SCSS import
+const importLine = StylesTool.addImport('../tokens/colors')
+
+// 3. Transforming a custom function call
+const safeValue = StylesTool.toFunctionCss('@getOpacity(0.5)') // "#{getOpacity(0.5)}"
+
+// 4. Joining lines
+const fileContent = StylesTool.join([
+  StylesTool.addImportProperties(),
+  importLine,
+  `.element {`,
+  `${indent}color: red;`,
+  `}`
+])
+```

package/src/media/functional/scripts/classes/StylesTool/StylesTool.ru.mdx

@@ -0,0 +1,130 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/StylesTool - Утилиты для обработки стилей'/>
+
+# Класс StylesTool
+
+Класс `StylesTool` представляет собой статическое хранилище утилит высокого уровня, предоставляющее основные функции для конвейера генерации стилей дизайн-системы. Он инкапсулирует логику управления директориями, контроля отступов, создания директив SCSS и преобразований для совместимости с Sass.
+
+Централизуя эти низкоуровневые манипуляции со строками и поиск путей, класс обеспечивает согласованность во всех преобразователях `StylesTo*` и классах-генераторах.
+
+## Ключевые возможности
+
+- **Контроль отступов** — предоставляет стандартную единицу отступа (2 пробела) и методы для её масштабирования в зависимости от уровня вложенности.
+- **Построители директив** — стандартизирует синтаксис для операторов SCSS `@use`, `@import` и `@forward`.
+- **Определение путей** — интегрируется с глобальной конфигурацией для определения места назначения генерируемых файлов.
+- **Совместимость с Sass** — выполняет автоматическое преобразование синтаксиса пользовательских CSS-функций в безопасную интерполяцию Sass.
+- **Вертикальное форматирование** — управляет объединением строк с использованием символов CRLF для совместимости между Windows и UNIX.
+
+## Методы работы с файлами и директориями
+
+### `getDir`
+
+Определяет структуру целевой директории для сохранения сгенерированных файлов стилей. Объединяет основной каталог стилей со специфическим именем проекта, определенным в конфигурации свойств.
+
+**Возвращает:** `string[]` — Массив, представляющий сегменты пути целевой директории.
+
+## Методы работы с отступами
+
+### `getSpace`
+
+Возвращает базовую единицу отступа, используемую во всех сгенерированных файлах стилей проекта.
+
+**Возвращает:** `string` — Строка, состоящая из 2 пробелов (`  `).
+
+### `addSpace`
+
+Генерирует строку отступа на основе указанного уровня вложенности. Используется для выравнивания блоков кода внутри вложенных структур, таких как медиа-запросы или блоки селекторов.
+
+**Параметры:**
+- `level: number` — Желаемый уровень вложенности (0 — без отступа, 1 — 2 пробела, 2 — 4 пробела и т.д.).
+
+**Возвращает:** `string` — Результирующая строка отступа.
+
+### `increaseSpace`
+
+Добавляет один дополнительный уровень отступа (2 пробела) к существующей строке отступов. Полезно при рекурсивном обходе дерева, где глубина увеличивается постепенно.
+
+**Параметры:**
+- `space: string` — Текущая строка отступа, которую необходимо расширить.
+
+**Возвращает:** `string` — Обновленная строка отступа с одним дополнительным уровнем.
+
+## Методы директив SCSS
+
+### `addImport`
+
+Создает стандартную директиву SCSS `@import` для заданного пути к файлу.
+
+**Параметры:**
+- `path: string` — Путь к импортируемому файлу.
+
+**Возвращает:** `string` — Отформатированная директива (например, `@import "path/to/file";`).
+
+### `addUse`
+
+Создает современную директиву SCSS `@use`, которая является рекомендуемым способом загрузки функций, миксинов и переменных в современном Sass.
+
+**Параметры:**
+- `path: string` — Путь к модулю.
+
+**Возвращает:** `string` — Отформатированная директива (например, `@use "path/to/module";`).
+
+### `addForward`
+
+Создает директиву SCSS `@forward`. Обычно используется в индексных файлах для предоставления доступа к членам подмодуля пользователям пакета.
+
+**Параметры:**
+- `path: string` — Путь к пересылаемому модулю.
+
+**Возвращает:** `string` — Отформатированная директива (например, `@forward "path/to/module";`).
+
+### `addImportProperties`
+
+Генерирует специализированную директиву `@use` для основной библиотеки `@dxtmisha/styles`, создавая псевдоним `ui` для использования в сгенерированных блоках свойств.
+
+**Возвращает:** `string` — Всегда возвращает `'@use "@dxtmisha/styles" as ui;'`.
+
+## Форматирование и утилиты
+
+### `join`
+
+Объединяет массив сгенерированных строк кода в одну отформатированную строку. Использует CRLF (`\r\n`) в качестве разделителя строк для обеспечения единообразного форматирования в различных средах.
+
+**Параметры:**
+- `data: string[]` — Массив строк, представляющих отдельные строки кода.
+
+**Возвращает:** `string` — Результирующая многострочная строка.
+
+### `toFunctionCss`
+
+Утилита безопасности, которая преобразует вызовы пользовательских функций `@function` внутри значений свойств CSS в синтаксис интерполяции Sass (`#{...}`). Это предотвращает ошибки компиляции Sass, когда пользовательские функции используются в контекстах, требующих чистого вывода CSS.
+
+**Параметры:**
+- `value: string` — Строка значения свойства CSS, содержащая потенциальные вызовы пользовательских функций.
+
+**Возвращает:** `string` — Преобразованная строка с интерполированными вызовами функций.
+
+## Пример использования
+
+```typescript
+import { StylesTool } from '@dxtmisha/scripts'
+
+// 1. Получение уровня отступа
+const indent = StylesTool.addSpace(2) // "    "
+
+// 2. Создание импорта SCSS
+const importLine = StylesTool.addImport('../tokens/colors')
+
+// 3. Преобразование вызова пользовательской функции
+const safeValue = StylesTool.toFunctionCss('@getOpacity(0.5)') // "#{getOpacity(0.5)}"
+
+// 4. Объединение строк
+const fileContent = StylesTool.join([
+  StylesTool.addImportProperties(),
+  importLine,
+  `.element {`,
+  `${indent}color: red;`,
+  `}`
+])
+```

package/src/media/functional/scripts/classes/StylesTool/StylesTool.vi.mdx

@@ -0,0 +1,130 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/StylesTool - Tiện ích xử lý Style'/>
+
+# Lớp StylesTool
+
+Lớp `StylesTool` là một container tiện ích tĩnh cấp cao cung cấp các chức năng thiết yếu cho quy trình tạo style của hệ thống thiết kế. Nó đóng gói logic quản lý thư mục, kiểm soát thụt lề, xây dựng các chỉ thị SCSS và các chuyển đổi tương thích với Sass.
+
+Bằng cách tập trung các thao tác chuỗi cấp thấp và tra cứu đường dẫn này, nó đảm bảo tính nhất quán trên tất cả các trình chuyển đổi `StylesTo*` và các lớp tạo mã.
+
+## Các tính năng chính
+
+- **Kiểm soát thụt lề** — cung cấp một đơn vị thụt lề chuẩn 2 khoảng trắng và các phương thức để mở rộng nó dựa trên mức độ lồng nhau.
+- **Trình dựng chỉ thị** — tiêu chuẩn hóa cú pháp cho các câu lệnh SCSS `@use`, `@import`, và `@forward`.
+- **Xác định đường dẫn** — tích hợp với cấu hình toàn cục để xác định đích đầu ra cho các tệp được tạo.
+- **Tính tương thích với Sass** — xử lý các chuyển đổi tự động của cú pháp hàm CSS tùy chỉnh thành nội suy an toàn trong Sass.
+- **Định dạng dọc** — quản lý việc kết hợp các dòng với ký tự CRLF nhất quán để tương thích giữa Windows/UNIX.
+
+## Các phương thức về Tệp và Thư mục
+
+### `getDir`
+
+Xác định cấu trúc thư mục đích để lưu trữ các tệp style được tạo. Nó kết hợp thư mục style cốt lõi với tên dự án cụ thể được định nghĩa trong cấu hình thuộc tính.
+
+**Trả về:** `string[]` — Một mảng đại diện cho các phân đoạn đường dẫn của thư mục đích.
+
+## Các phương thức về Thụt lề và Khoảng cách
+
+### `getSpace`
+
+Lấy đơn vị thụt lề cơ sở được sử dụng trong toàn bộ các tệp style được tạo của dự án.
+
+**Trả về:** `string` — Trả về một chuỗi bao gồm 2 khoảng trắng (`  `).
+
+### `addSpace`
+
+Tạo một chuỗi thụt lề dựa trên mức độ lồng nhau được chỉ định. Điều này được sử dụng để căn chỉnh các khối mã bên trong các cấu trúc lồng nhau như media queries hoặc các khối selector.
+
+**Tham số:**
+- `level: number` — Mức độ lồng nhau mong muốn (0 cho không thụt lề, 1 cho 2 khoảng trắng, 2 cho 4 khoảng trắng, v.v.).
+
+**Trả về:** `string` — Chuỗi thụt lề kết quả.
+
+### `increaseSpace`
+
+Thêm một cấp thụt lề bổ sung (2 khoảng trắng) vào một chuỗi khoảng trắng hiện có. Điều này hữu ích trong quá trình duyệt cây đệ quy nơi độ sâu tăng dần.
+
+**Tham số:**
+- `space: string` — Chuỗi thụt lề hiện tại cần được mở rộng.
+
+**Trả về:** `string` — Chuỗi thụt lề đã được cập nhật với một cấp bổ sung.
+
+## Các phương thức chỉ thị SCSS
+
+### `addImport`
+
+Xây dựng một chỉ thị SCSS `@import` tiêu chuẩn cho một đường dẫn tệp nhất định.
+
+**Tham số:**
+- `path: string` — Đường dẫn tệp cần được import.
+
+**Trả về:** `string` — Chỉ thị đã định dạng (ví dụ: `@import "path/to/file";`).
+
+### `addUse`
+
+Xây dựng một chỉ thị SCSS `@use` hiện đại, đây là cách được khuyến nghị để tải các member function, mixin và biến trong Sass hiện đại.
+
+**Tham số:**
+- `path: string` — Đường dẫn module cần được sử dụng.
+
+**Trả về:** `string` — Chỉ thị đã định dạng (ví dụ: `@use "path/to/module";`).
+
+### `addForward`
+
+Xây dựng một chỉ thị SCSS `@forward`. Điều này thường được sử dụng trong các tệp index để công khai các thành viên của một sub-module cho người dùng của package.
+
+**Tham số:**
+- `path: string` — Đường dẫn module cần được chuyển tiếp.
+
+**Trả về:** `string` — Chỉ thị đã định dạng (ví dụ: `@forward "path/to/module";`).
+
+### `addImportProperties`
+
+Tạo một chỉ thị `@use` chuyên biệt cho thư viện cốt lõi `@dxtmisha/styles`, đặt bí danh cho nó là `ui` để sử dụng trong các khối thuộc tính được tạo.
+
+**Trả về:** `string` — Luôn trả về `'@use "@dxtmisha/styles" as ui;'`.
+
+## Định dạng và Tiện ích
+
+### `join`
+
+Kết hợp một mảng các dòng mã được tạo thành một chuỗi văn bản duy nhất đã được định dạng. Nó sử dụng CRLF (`\r\n`) làm bộ phân tách dòng để đảm bảo định dạng nhất quán trên các môi trường.
+
+**Tham số:**
+- `data: string[]` — Một mảng các chuỗi đại diện cho từng dòng mã riêng lẻ.
+
+**Trả về:** `string` — Chuỗi văn bản nhiều dòng kết quả.
+
+### `toFunctionCss`
+
+Một tiện ích an toàn chuyển đổi các lời gọi `@function` tùy chỉnh bên trong các giá trị thuộc tính CSS thành cú pháp nội suy của Sass (`#{...}`). Điều này ngăn chặn các lỗi biên dịch Sass khi các hàm tùy chỉnh được sử dụng trong các ngữ cảnh yêu cầu đầu ra CSS thô.
+
+**Tham số:**
+- `value: string` — Chuỗi giá trị thuộc tính CSS chứa các lời gọi hàm tùy chỉnh tiềm năng.
+
+**Trả về:** `string` — Chuỗi đã được chuyển đổi với các lời gọi hàm được nội suy.
+
+## Ví dụ sử dụng
+
+```typescript
+import { StylesTool } from '@dxtmisha/scripts'
+
+// 1. Lấy một mức thụt lề
+const indent = StylesTool.addSpace(2) // "    "
+
+// 2. Tạo một SCSS import
+const importLine = StylesTool.addImport('../tokens/colors')
+
+// 3. Chuyển đổi một lời gọi hàm tùy chỉnh
+const safeValue = StylesTool.toFunctionCss('@getOpacity(0.5)') // "#{getOpacity(0.5)}"
+
+// 4. Kết hợp các dòng
+const fileContent = StylesTool.join([
+  StylesTool.addImportProperties(),
+  importLine,
+  `.element {`,
+  `${indent}color: red;`,
+  `}`
+])
+```

package/src/media/functional/scripts/classes/convectorColor/convectorColor.en.mdx

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Functions/convectorColor - Color Conversion'/>
+
+# convectorColor Function
+
+The `convectorColor` function is part of the convector system for processing property tokens. Its primary role is to extract specific color metadata from 'studio.tokens' extensions and apply it to the property object. Currently, the function specializes in handling opacity (alpha) modifications.
+
+## Key Features
+
+- **Studio Tokens Integration** — works with `$extensions['studio.tokens']` extensions.
+- **Opacity Modification** — extracts the `alpha` value from modification parameters and saves it in the system key `cssColorOpacity`.
+- **Automation** — called during the property standardization process when corresponding metadata is detected.
+
+## Parameters
+
+The function accepts a single argument:
+
+- `item: PropertyItemInput` — the property input data object, which will be mutated during execution.
+
+## Examples
+
+### Handling Opacity Modification
+
+If a token contains color modification information, `convectorColor` will extract it:
+
+```typescript
+import { convectorColor, PropertyKey } from '@dxtmisha/scripts'
+
+const item = {
+  value: '#ff0000',
+  $extensions: {
+    'studio.tokens': {
+      modify: {
+        type: 'alpha',
+        value: '0.5'
+      }
+    }
+  }
+};
+
+convectorColor(item);
+
+console.log(item[PropertyKey.cssColorOpacity]); // '0.5'
+```
+
+## Operations
+
+### Processing Mechanism
+
+The data processing in `convectorColor` involves the following steps:
+1. **Extension Lookup**: The function searches for the path `$extensions['studio.tokens'].modify`.
+2. **Type Identification**: If the modification type is set to `alpha`, the function proceeds to process it.
+3. **Data Persistence**: The opacity value (`value`) is written to the `item` object property using the `_o` key (stored in `PropertyKey.cssColorOpacity`). If no value is specified, it defaults to `'1'`.
+
+## Scope of Application
+
+The function is used within property processing classes (e.g., `PropertiesStandard`) to enrich token data with opacity information derived from design tools.

package/src/media/functional/scripts/classes/convectorColor/convectorColor.ru.mdx

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Functions/convectorColor - Конвертация цвета'/>
+
+# Функция convectorColor
+
+Функция `convectorColor` является частью системы конвекторов для обработки токенов свойств. Её основная роль — извлечение специфических метаданных цвета из расширений 'studio.tokens' и их применение к объекту свойства. На данный момент функция специализируется на обработке модификаций прозрачности (alpha).
+
+## Ключевые особенности
+
+- **Интеграция со Studio Tokens** — работает с расширениями `$extensions['studio.tokens']`.
+- **Модификация прозрачности** — извлекает значение `alpha` из параметров модификации и сохраняет его в системном ключе `cssColorOpacity`.
+- **Автоматизация** — вызывается в процессе стандартизации свойств при обнаружении соответствующих метаданных.
+
+## Параметры
+
+Функция принимает один аргумент:
+
+- `item: PropertyItemInput` — объект входных данных свойства, который будет мутирован в процессе выполнения.
+
+## Примеры
+
+### Обработка модификации прозрачности
+
+Если токен содержит информацию о модификации цвета, `convectorColor` извлечет её:
+
+```typescript
+import { convectorColor, PropertyKey } from '@dxtmisha/scripts'
+
+const item = {
+  value: '#ff0000',
+  $extensions: {
+    'studio.tokens': {
+      modify: {
+        type: 'alpha',
+        value: '0.5'
+      }
+    }
+  }
+};
+
+convectorColor(item);
+
+console.log(item[PropertyKey.cssColorOpacity]); // '0.5'
+```
+
+## Операции
+
+### Механизм обработки
+
+Процесс обработки данных в `convectorColor` включает следующие шаги:
+1. **Поиск расширений**: Функция ищет путь `$extensions['studio.tokens'].modify`.
+2. **Определение типа**: Если тип модификации установлен в `alpha`, функция приступает к обработке.
+3. **Сохранение данных**: Значение прозрачности (`value`) записывается в свойство объекта `item` по ключу `_o` (хранится в `PropertyKey.cssColorOpacity`). Если значение не указано, по умолчанию используется `'1'`.
+
+## Область применения
+
+Функция используется внутри классов обработки свойств (например, `PropertiesStandard`) для обогащения данных токенов информацией о прозрачности, полученной из инструментов дизайна.