@dxtmisha/wiki 0.25.1 → 0.39.2

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

@@ -0,0 +1,51 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/Properties - Bộ điều phối Token thiết kế'/>
+
+# Lớp Properties
+
+Lớp `Properties` là công cụ xử lý cốt lõi của cơ sở hạ tầng token trong hệ thống thiết kế. Nó đóng vai trò là bộ điều phối trung tâm để phối hợp việc tải, hợp nhất cấu trúc và biến đổi đệ quy các định nghĩa thuộc tính thô thành trạng thái cuối cùng đã được phân giải. Bằng cách trừu tượng hóa sự phức tạp của hàng chục quy tắc biến đổi chuyên biệt, nó cung cấp một "nguồn sự thật" ổn định cho tất cả các thành phần và công cụ xây dựng.
+
+## Các tính năng chính
+
+- **Quy trình xử lý đa giai đoạn** — Thực thi các bộ biến đổi chuyên biệt để thay thế, sao chép, kéo và liên kết các token thiết kế.
+- **Hợp nhất cấu trúc** — Phân giải và hợp nhất một cách thông minh các cài đặt, giá trị mặc định toàn cầu và các ghi đè (overrides) dành riêng cho thành phần.
+- **Quản lý bộ nhớ đệm tăng dần** — Sử dụng `PropertiesCache` để lưu trữ kết quả đã xử lý, cải thiện đáng kể hiệu suất xây dựng.
+- **Tổng hợp SCSS** — Biên dịch các token đã phân giải thành định dạng SCSS có cấu trúc để sử dụng trực tiếp trong các lớp tạo kiểu.
+- **Siêu dữ liệu tối ưu cho AI** — Chuẩn bị các cấu trúc thuộc tính dễ dàng tiêu thụ bởi các công cụ tài liệu và trình tạo dựa trên AI.
+
+## Khởi tạo
+
+Khởi tạo bộ điều phối để bắt đầu xử lý ngay lập tức các token được định nghĩa trong cấu hình dự án.
+
+```typescript
+import { Properties } from '@dxtmisha/scripts'
+
+const engine = new Properties()
+const tokens = engine.get() // Trả về PropertiesItems đã được xử lý đầy đủ
+```
+
+## Các phương thức
+
+### Truy cập dữ liệu
+
+- `get(): PropertiesItems` — Trả về container cốt lõi chứa tất cả các token thiết kế đã xử lý.
+- `getScss(): string` — Trả về biểu diễn SCSS đã biên dịch của bộ token hiện tại.
+
+## Các thao tác (Operations)
+
+### Quy trình xử lý Token (The Token Processing Pipeline)
+
+Khi được khởi tạo, `Properties` điều phối một luồng biến đổi đa lớp toàn diện:
+1. **Thu thập nguồn**: Nó đọc và hợp nhất dữ liệu thô từ `PropertiesSettings`, `PropertiesMain` và các tệp JSON bên ngoài.
+2. **Chuẩn hóa cơ bản**: Kích hoạt các biến đổi nền tảng:
+    - **Thay thế (Replacement)**: Phân giải các mẫu alias.
+    - **Phân giải bảng màu (Palette Resolution)**: Tiêm các giá trị bảng màu.
+    - **Sao chép & Tổng hợp thuộc tính con**: Xử lý các bản sao thuộc tính phức tạp.
+3. **Biến đổi nâng cao**: Thực thi logic cấp cao cho:
+    - **Phân giải thành phần**: Ánh xạ các thuộc tính vào các cấu trúc thành phần cụ thể.
+    - **Ánh xạ Trạng thái & Lớp (State & Class Mapping)**: Tạo siêu dữ liệu cho các trạng thái UI (hover, active) và các lớp BEM.
+    - **Tổng hợp Media & Animation**: Phân giải các điểm dừng (breakpoints) phản hồi và các token chuyển động.
+4. **Tối ưu hóa & Làm sạch**: Sắp xếp các thuộc tính, xử lý các bản trùng lặp và loại bỏ các nút trống.
+5. **Lưu trữ**: Kết quả cuối cùng được lưu vào `PropertiesCache` bằng một mã hash duy nhất dựa trên cấu hình thiết kế hiện tại.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesCache - Persistent Cache Orchestrator'/>
+
+# PropertiesCache Class
+
+The `PropertiesCache` class is a high-performance static utility designed to manage persistent file-based caching for the design system toolchain. It ensures that complex token transformations are only performed when necessary, significantly reducing build times for large-scale projects by tracking file dependencies and maintaining a structured cache hierarchy.
+
+## Key Features
+
+- **Dependency Tracking** — Automatically monitors source file changes and invalidates the cache if any dependency is modified.
+- **Hierarchical Storage** — Organizes cached data into a hidden `.cache` directory with specialized sub-folders for different processing steps.
+- **Incremental Builds** — Enables partial re-computation by storing intermediate transformation results.
+- **System Integrity** — Maintains a `system.json` registry to track cache timestamps and file metadata.
+- **Generic Support** — Provides full TypeScript support for type-safe retrieval of cached data structures.
+
+## Initialization
+
+As a static class, `PropertiesCache` does not require instantiation. Its methods are accessed directly.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Retrieve data with automatic cache management
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Clear all cached data
+PropertiesCache.clear()
+```
+
+## Methods
+
+### Cache Operations
+
+- `get<T>(path, name, callback, extension): T` — Retrieves data from the cache or regenerates it via the callback.
+- `read<R>(path): R | undefined` — Reads a file and registers it as a cache dependency.
+- `write<T>(name, value): void` — Saves intermediate processing results to the temporary cache.
+- `clear(): void` — Recursively deletes the entire cache directory.
+
+## Operations
+
+### The Cache Synchronization Flow
+
+`PropertiesCache` operates through a sophisticated internal lifecycle to ensure data consistency:
+1. **Request (`get`)**: When data is requested, the class first checks for the existence of the physical cache file.
+2. **System Validation**: It consults the internal `system` registry to compare the cache's creation timestamp against the modification times of all registered dependency files.
+3. **Regeneration**: If the file is missing or outdated:
+    - It pushes the current cache `name` onto an internal `listenerName` stack.
+    - Any subsequent file read via `PropertiesCache.read()` during the callback execution is automatically logged as a dependency for this specific cache entry.
+    - The callback result is written to disk.
+4. **Finalization**: After the callback completes, it updates the `system.json` with the new timestamp and dependency list, ensuring the next request remains valid unless a source file changes.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesCache - Оркестратор постоянного кэша'/>
+
+# Класс PropertiesCache
+
+Класс `PropertiesCache` — это высокопроизводительная статическая утилита, предназначенная для управления постоянным файловым кэшированием в инструментарии дизайн-системы. Он гарантирует, что сложные трансформации токенов выполняются только при необходимости, значительно сокращая время сборки для крупных проектов за счет отслеживания зависимостей файлов и поддержки структурированной иерархии кэша.
+
+## Ключевые особенности
+
+- **Отслеживание зависимостей** — автоматически отслеживает изменения исходных файлов и аннулирует кэш, если любая зависимость была изменена.
+- **Иерархическое хранение** — организует кэшированные данные в скрытой директории `.cache` со специализированными подпапками для различных этапов обработки.
+- **Инкрементальные сборки** — позволяет выполнять частичное перевычисление за счет хранения промежуточных результатов трансформации.
+- **Целостность системы** — ведет реестр `system.json` для отслеживания временных меток кэша и метаданных файлов.
+- **Поддержка Generic** — обеспечивает полную поддержку TypeScript для типобезопасного извлечения кэшированных структур данных.
+
+## Инициализация
+
+Являясь статическим классом, `PropertiesCache` не требует создания экземпляра. Доступ к его методам осуществляется напрямую.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Извлечение данных с автоматическим управлением кэшем
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Очистка всех кэшированных данных
+PropertiesCache.clear()
+```
+
+## Методы
+
+### Операции с кэшем
+
+- `get<T>(path, name, callback, extension): T` — извлекает данные из кэша или регенерирует их через функцию обратного вызова.
+- `read<R>(path): R | undefined` — читает файл и регистрирует его как зависимость кэша.
+- `write<T>(name, value): void` — сохраняет промежуточные результаты обработки во временный кэш.
+- `clear(): void` — рекурсивно удаляет всю директорию кэша.
+
+## Операции
+
+### Поток синхронизации кэша
+
+`PropertiesCache` работает через сложный внутренний жизненный цикл для обеспечения согласованности данных:
+1. **Запрос (`get`)**: При запросе данных класс сначала проверяет наличие физического файла кэша.
+2. **Системная валидация**: Он обращается к внутреннему реестру `system`, чтобы сравнить временную метку создания кэша с временем изменения всех зарегистрированных файлов зависимостей.
+3. **Регенерация**: Если файл отсутствует или устарел:
+    - Класс помещает текущее имя кэша `name` во внутренний стек `listenerName`.
+    - Любое последующее чтение файла через `PropertiesCache.read()` во время выполнения callback автоматически регистрируется как зависимость для этой конкретной записи кэша.
+    - Результат callback записывается на диск.
+4. **Завершение**: После завершения callback обновляется `system.json` с новой временной меткой и списком зависимостей, гарантируя, что следующий запрос останется валидным, пока не изменится исходный файл.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesCache - Bộ điều phối bộ nhớ đệm vĩnh viễn'/>
+
+# Lớp PropertiesCache
+
+Lớp `PropertiesCache` là một tiện ích tĩnh hiệu suất cao được thiết kế để quản lý việc lưu trữ bộ nhớ đệm (caching) dựa trên tệp vĩnh viễn cho bộ công cụ hệ thống thiết kế. Nó đảm bảo rằng các biến đổi token phức tạp chỉ được thực hiện khi cần thiết, giúp giảm đáng kể thời gian xây dựng cho các dự án quy mô lớn bằng cách theo dõi các phụ thuộc tệp và duy trì một cấu trúc phân cấp bộ nhớ đệm chặt chẽ.
+
+## Các tính năng chính
+
+- **Theo dõi phụ thuộc** — Tự động giám sát các thay đổi của tệp nguồn và vô hiệu hóa bộ nhớ đệm nếu bất kỳ phụ thuộc nào bị sửa đổi.
+- **Lưu trữ phân cấp** — Tổ chức dữ liệu đã lưu vào thư mục ẩn `.cache` với các thư mục con chuyên biệt cho các bước xử lý khác nhau.
+- **Xây dựng tăng dần** — Cho phép tính toán lại một phần bằng cách lưu trữ kết quả biến đổi trung gian.
+- **Tính toàn vẹn hệ thống** — Duy trì sổ đăng ký `system.json` để theo dõi dấu thời gian của bộ nhớ đệm và siêu dữ liệu tệp.
+- **Hỗ trợ Generic** — Cung cấp hỗ trợ TypeScript đầy đủ để truy xuất các cấu trúc dữ liệu đã lưu một cách an toàn về kiểu.
+
+## Khởi tạo
+
+Là một lớp tĩnh, `PropertiesCache` không yêu cầu khởi tạo instance. Các phương thức của nó được truy cập trực tiếp.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Truy xuất dữ liệu với quản lý bộ nhớ đệm tự động
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Xóa tất cả dữ liệu đã lưu
+PropertiesCache.clear()
+```
+
+## Các phương thức
+
+### Các thao tác bộ nhớ đệm
+
+- `get<T>(path, name, callback, extension): T` — Truy xuất dữ liệu từ bộ nhớ đệm hoặc tạo lại dữ liệu đó thông qua hàm callback.
+- `read<R>(path): R | undefined` — Đọc một tệp và đăng ký nó như một phụ thuộc của bộ nhớ đệm.
+- `write<T>(name, value): void` — Lưu kết quả xử lý trung gian vào bộ nhớ đệm tạm thời.
+- `clear(): void` — Xóa đệ quy toàn bộ thư mục bộ nhớ đệm.
+
+## Các thao tác (Operations)
+
+### Luồng đồng bộ hóa bộ nhớ đệm (The Cache Synchronization Flow)
+
+`PropertiesCache` hoạt động thông qua một vòng đời nội bộ tinh vi để đảm bảo tính nhất quán của dữ liệu:
+1. **Yêu cầu (`get`)**: Khi dữ liệu được yêu cầu, lớp trước tiên sẽ kiểm tra sự tồn tại của tệp bộ nhớ đệm vật lý.
+2. **Xác thực hệ thống**: Nó tham khảo sổ đăng ký `system` nội bộ để so sánh dấu thời gian tạo của bộ nhớ đệm với thời gian sửa đổi của tất cả các tệp phụ thuộc đã đăng ký.
+3. **Tạo lại**: Nếu tệp bị thiếu hoặc lỗi thời:
+    - Nó đẩy `name` bộ nhớ đệm hiện tại vào một ngăn xếp `listenerName` nội bộ.
+    - Bất kỳ lần đọc tệp tiếp theo nào thông qua `PropertiesCache.read()` trong khi thực thi callback sẽ tự động được ghi lại như một phụ thuộc cho mục bộ nhớ đệm cụ thể này.
+    - Kết quả callback được ghi vào đĩa.
+4. **Hoàn tất**: Sau khi callback hoàn tất, nó cập nhật `system.json` với dấu thời gian và danh sách phụ thuộc mới, đảm bảo yêu cầu tiếp theo vẫn hợp lệ trừ khi tệp nguồn thay đổi.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesConfig - Global Configuration Orchestrator'/>
+
+# PropertiesConfig Class
+
+The `PropertiesConfig` class is a centralized static utility responsible for managing the design system's operational parameters. It handles the discovery and recursive merging of `design-ui.json` configuration files, providing a consistent API for accessing naming conventions, AI integration keys, and documentation routing rules across the entire library.
+
+## Key Features
+
+- **Recursive Extension** — Supports an `extends` mechanism, allowing configurations to inherit and override settings from parent directories.
+- **Auto-Discovery** — Searches up the directory tree to find the nearest `design-ui.json` entry point.
+- **Centralized Settings** — Provides unified access to project identifiers, design names, and path separators.
+- **AI Integration** — Manages credentials and model parameters for AI-driven documentation and code generation.
+- **Documentation Routing** — Configures target directories and Storybook paths for the automated wiki system.
+
+## Initialization
+
+As a static class, `PropertiesConfig` initializes itself automatically upon the first import. You don't need to call a constructor.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Access global settings
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Methods
+
+### General Configuration
+
+- `getProjectName(): string` — Retrieves the project's root identifier.
+- `getDesignName(): string` — Returns the primary design system identifier.
+- `getDesignAlternativeName(): string[]` — Returns alternative aliases for the design.
+- `getSeparator(): string` — Returns the path separator used in token definitions.
+- `getWikiLanguage(): string` — Returns the target language code for documentation.
+
+### AI & Documentation
+
+- `getAiType(): AiType` — Returns the configured AI provider (e.g., 'gemini').
+- `getAiModel(): string` — Returns the specific AI model name.
+- `getAiDocDirectory(): string[]` — Returns directories targeted for doc generation.
+- `getAiDocStorybookPath(): string` — Returns the export destination for Storybook MDX files.
+
+## Operations
+
+### The Configuration Resolution Flow
+
+`PropertiesConfig` uses a robust strategy to resolve system settings:
+1. **File Discovery**: Upon loading, it attempts to find `design-ui.json` by traversing upwards from the current working directory (up to 32 levels).
+2. **Recursive Merging**: If the discovered file contains an `extends` property:
+    - It recursively loads the referenced parent configuration.
+    - It intelligently merges settings, where local properties override inherited ones.
+3. **Static Availability**: The final merged configuration is stored in a private static field, making all settings immediately available through public getters.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesConfig - Оркестратор глобальной конфигурации'/>
+
+# Класс PropertiesConfig
+
+Класс `PropertiesConfig` — это централизованная статическая утилита, отвечающая за управление рабочими параметрами дизайн-системы. Он управляет поиском и рекурсивным слиянием файлов конфигурации `design-ui.json`, предоставляя единый API для доступа к соглашениям об именовании, ключам интеграции ИИ и правилам маршрутизации документации во всей библиотеке.
+
+## Ключевые особенности
+
+- **Рекурсивное расширение** — поддерживает механизм `extends`, позволяя конфигурациям наследовать и переопределять настройки из родительских директорий.
+- **Автоматическое обнаружение** — выполняет поиск вверх по дереву каталогов для нахождения ближайшей точки входа `design-ui.json`.
+- **Централизованные настройки** — обеспечивает унифицированный доступ к идентификаторам проекта, названиям дизайна и разделителям путей.
+- **Интеграция с ИИ** — управляет учетными данными и параметрами моделей для генерации документации и кода на базе ИИ.
+- **Маршрутизация документации** — настраивает целевые директории и пути Storybook для автоматизированной системы вики.
+
+## Инициализация
+
+Являясь статическим классом, `PropertiesConfig` инициализируется автоматически при первом импорте. Вам не нужно вызывать конструктор.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Доступ к глобальным настройкам
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Методы
+
+### Общая конфигурация
+
+- `getProjectName(): string` — получает корневой идентификатор проекта.
+- `getDesignName(): string` — возвращает основной идентификатор дизайн-системы.
+- `getDesignAlternativeName(): string[]` — возвращает альтернативные алиасы для дизайна.
+- `getSeparator(): string` — возвращает символ-разделитель путей в токенах.
+- `getWikiLanguage(): string` — возвращает код целевого языка для документации.
+
+### ИИ и Документация
+
+- `getAiType(): AiType` — возвращает настроенного ИИ-провайдера (например, 'gemini').
+- `getAiModel(): string` — возвращает название конкретной модели ИИ.
+- `getAiDocDirectory(): string[]` — возвращает директории, предназначенные для генерации документации.
+- `getAiDocStorybookPath(): string` — возвращает путь экспорта для MDX-файлов Storybook.
+
+## Операции
+
+### Поток разрешения конфигурации
+
+`PropertiesConfig` использует надежную стратегию для разрешения системных настроек:
+1. **Поиск файла**: При загрузке класс пытается найти `design-ui.json`, поднимаясь вверх от текущей рабочей директории (до 32 уровней).
+2. **Рекурсивное слияние**: Если найденный файл содержит свойство `extends`:
+    - Он рекурсивно загружает указанную родительскую конфигурацию.
+    - Интеллектуально объединяет настройки, где локальные свойства переопределяют унаследованные.
+3. **Статическая готовность**: Итоговая объединенная конфигурация сохраняется в приватном статическом поле, делая все настройки немедленно доступными через публичные геттеры.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesConfig - Bộ điều phối cấu hình toàn cầu'/>
+
+# Lớp PropertiesConfig
+
+Lớp `PropertiesConfig` là một tiện ích tĩnh tập trung chịu trách nhiệm quản lý các tham số vận hành của hệ thống thiết kế. Nó xử lý việc khám phá và hợp nhất đệ quy các tệp cấu hình `design-ui.json`, cung cấp một API nhất quán để truy cập các quy ước đặt tên, khóa tích hợp AI và các quy tắc định tuyến tài liệu trên toàn bộ thư viện.
+
+## Các tính năng chính
+
+- **Mở rộng đệ quy** — Hỗ trợ cơ chế `extends`, cho phép các cấu hình kế thừa và ghi đè các cài đặt từ các thư mục cha.
+- **Tự động khám phá** — Tìm kiếm ngược lên cây thư mục để tìm điểm nhập `design-ui.json` gần nhất.
+- **Cài đặt tập trung** — Cung cấp quyền truy cập thống nhất vào các định danh dự án, tên thiết kế và các ký tự phân tách đường dẫn.
+- **Tích hợp AI** — Quản lý thông tin xác thực và các tham số mô hình cho việc tạo tài liệu và mã nguồn bằng AI.
+- **Định tuyến tài liệu** — Cấu hình các thư mục đích và đường dẫn Storybook cho hệ thống wiki tự động.
+
+## Khởi tạo
+
+Là một lớp tĩnh, `PropertiesConfig` tự động khởi tạo khi được import lần đầu tiên. Bạn không cần phải gọi hàm khởi tạo.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Truy cập các cài đặt toàn cầu
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Các phương thức
+
+### Cấu hình chung
+
+- `getProjectName(): string` — Truy xuất định danh gốc của dự án.
+- `getDesignName(): string` — Trả về định danh chính của hệ thống thiết kế.
+- `getDesignAlternativeName(): string[]` — Trả về các alias thay thế cho thiết kế.
+- `getSeparator(): string` — Trả về ký tự phân tách đường dẫn được sử dụng trong các token.
+- `getWikiLanguage(): string` — Trả về mã ngôn ngữ đích cho tài liệu.
+
+### AI & Tài liệu
+
+- `getAiType(): AiType` — Trả về nhà cung cấp AI đã cấu hình (ví dụ: 'gemini').
+- `getAiModel(): string` — Trả về tên mô hình AI cụ thể.
+- `getAiDocDirectory(): string[]` — Trả về các thư mục mục tiêu để tạo tài liệu.
+- `getAiDocStorybookPath(): string` — Trả về đích xuất cho các tệp MDX của Storybook.
+
+## Các thao tác (Operations)
+
+### Luồng phân giải cấu hình (The Configuration Resolution Flow)
+
+`PropertiesConfig` sử dụng một chiến lược mạnh mẽ để phân giải các cài đặt hệ thống:
+1. **Khám phá tệp**: Khi tải, nó cố gắng tìm `design-ui.json` bằng cách duyệt ngược lên từ thư mục làm việc hiện tại (tối đa 32 cấp).
+2. **Hợp nhất đệ quy**: Nếu tệp được tìm thấy có chứa thuộc tính `extends`:
+    - Nó tải đệ quy cấu hình cha được tham chiếu.
+    - Nó hợp nhất các cài đặt một cách thông minh, trong đó các thuộc tính cục bộ ghi đè các thuộc tính kế thừa.
+3. **Tính sẵn sàng tĩnh**: Cấu hình hợp nhất cuối cùng được lưu trữ trong một trường tĩnh riêng tư, giúp tất cả các cài đặt có sẵn ngay lập tức thông qua các getter công khai.
+

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesConvector - Semantic Token Transformer'/>
+
+# PropertiesConvector Class
+
+The `PropertiesConvector` class is a specialized static utility designed to handle complex semantic transformations of design tokens. It acts as a dispatcher for the token processing engine, identifying specific property types (like colors, shadows, or typography) and applying specialized conversion logic to Ensure raw data is normalized into usable design system structures.
+
+## Key Features
+
+- **Semantic Dispatching** — Automatically routes tokens to specialized convectors based on their `type` metadata.
+- **Recursive Traversal** — Deeply traverses nested property objects to ensure all child tokens are processed.
+- **Specialized Converters** — Integrates dedicated logic for `color`, `boxShadow`, `fontFamilies`, and `typography`.
+- **In-Place Transformation** — Modifies property objects directly to maintain structural integrity during the build process.
+
+## Initialization
+
+As a static utility class, `PropertiesConvector` does not require instantiation. Its primary function is accessed directly.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Transform a set of raw properties
+PropertiesConvector.to(rawProperties)
+```
+
+## Methods
+
+### Transformation
+
+- `to(properties): void` — Recursively processes a property list, applying type-specific transformations to each item.
+
+## Operations
+
+### The Conversion Dispatch Flow
+
+`PropertiesConvector` manages the transformation lifecycle through a recursive matching strategy:
+1. **Type Detection**: For each item in the provided property cluster, it checks if a corresponding convector exists in its internal registry (e.g., matching `color` to `convectorColor`).
+2. **Specialized Execution**: If a match is found, the specific convector logic is executed on the item, transforming its raw values into finalized formats.
+3. **Recursive Branching**:
+    - If the item has a `value` that is an object, it recursively calls `to()` on that object.
+    - If the item itself is an object without a recognized type, it continues the traversal to find nested tokens.
+4. **Data Integrity**: The process ensures that complex structures (like typography maps or multi-layered shadows) are fully resolved before the next stage of the pipeline.

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesConvector - Трансформер семантических токенов'/>
+
+# Класс PropertiesConvector
+
+Класс `PropertiesConvector` — это специализированная статическая утилита, предназначенная для выполнения сложных семантических преобразований токенов дизайна. Он выступает в роли диспетчера для движка обработки токенов, определяя специфические типы свойств (такие как цвета, тени или типографика) и применяя специализированную логику преобразования для нормализации необработанных данных в пригодные для использования структуры дизайн-системы.
+
+## Ключевые особенности
+
+- **Семантическая диспетчеризация** — автоматически направляет токены в специализированные конвертеры на основе метаданных их `type`.
+- **Рекурсивный обход** — глубоко обходит вложенные объекты свойств, гарантируя обработку всех дочерних токенов.
+- **Специализированные конвертеры** — интегрирует выделенную логику для `color`, `boxShadow`, `fontFamilies` и `typography`.
+- **Преобразование «на месте»** — напрямую модифицирует объекты свойств для сохранения структурной целостности в процессе сборки.
+
+## Инициализация
+
+Являясь статической утилитой, `PropertiesConvector` не требует создания экземпляра. Доступ к его основной функции осуществляется напрямую.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Преобразование набора необработанных свойств
+PropertiesConvector.to(rawProperties)
+```
+
+## Методы
+
+### Трансформация
+
+- `to(properties): void` — рекурсивно обрабатывает список свойств, применяя специфические для типа преобразования к каждому элементу.
+
+## Операции
+
+### Поток диспетчеризации преобразования
+
+`PropertiesConvector` управляет жизненным циклом трансформации через стратегию рекурсивного сопоставления:
+1. **Определение типа**: Для каждого элемента в предоставленном кластере свойств класс проверяет наличие соответствующего конвертера во внутреннем реестре (например, сопоставление `color` с `convectorColor`).
+2. **Специализированное выполнение**: Если совпадение найдено, на элементе выполняется логика конкретного конвертера, преобразующая необработанные значения в финальные форматы.
+3. **Рекурсивное ветвление**:
+    - Если у элемента есть `value`, являющееся объектом, класс рекурсивно вызывает `to()` для этого объекта.
+    - Если сам элемент является объектом без распознанного типа, он продолжает обход для поиска вложенных токенов.
+4. **Целостность данных**: Процесс гарантирует, что сложные структуры (такие как карты типографики или многослойные тени) будут полностью разрешены перед следующим этапом конвейера.

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesConvector - Bộ chuyển đổi Token ngữ nghĩa'/>
+
+# Lớp PropertiesConvector
+
+Lớp `PropertiesConvector` là một tiện ích tĩnh chuyên biệt được thiết kế để xử lý các phép biến đổi ngữ nghĩa phức tạp của các token thiết kế. Nó đóng vai trò như một bộ điều phối cho động cơ xử lý token, xác định các loại thuộc tính cụ thể (như màu sắc, bóng đổ hoặc kiểu chữ) và áp dụng logic chuyển đổi chuyên biệt để đảm bảo dữ liệu thô được chuẩn hóa thành các cấu trúc hệ thống thiết kế có thể sử dụng được.
+
+## Các tính năng chính
+
+- **Điều phối ngữ nghĩa** — Tự động định tuyến các token đến các bộ chuyển đổi chuyên biệt dựa trên siêu dữ liệu `type` của chúng.
+- **Duyệt đệ quy** — Duyệt sâu qua các đối tượng thuộc tính lồng nhau để đảm bảo tất cả các token con đều được xử lý.
+- **Bộ chuyển đổi chuyên biệt** — Tích hợp logic dành riêng cho `color`, `boxShadow`, `fontFamilies` và `typography`.
+- **Biến đổi tại chỗ (In-Place)** — Sửa đổi trực tiếp các đối tượng thuộc tính để duy trì tính toàn vẹn của cấu trúc trong quá trình xây dựng.
+
+## Khởi tạo
+
+Là một lớp tiện ích tĩnh, `PropertiesConvector` không yêu cầu khởi tạo instance. Chức năng chính của nó được truy cập trực tiếp.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Biến đổi một tập hợp các thuộc tính thô
+PropertiesConvector.to(rawProperties)
+```
+
+## Các phương thức
+
+### Biến đổi
+
+- `to(properties): void` — Xử lý đệ quy danh sách thuộc tính, áp dụng các phép biến đổi cụ thể theo loại cho từng mục.
+
+## Các thao tác (Operations)
+
+### Luồng điều phối chuyển đổi (The Conversion Dispatch Flow)
+
+`PropertiesConvector` quản lý vòng đời biến đổi thông qua chiến lược khớp đệ quy:
+1. **Phát hiện loại**: Đối với mỗi mục trong cụm thuộc tính được cung cấp, nó kiểm tra xem một bộ chuyển đổi tương ứng có tồn tại trong sổ đăng ký nội bộ hay không (ví dụ: khớp `color` với `convectorColor`).
+2. **Thực thi chuyên biệt**: Nếu tìm thấy kết quả khớp, logic bộ chuyển đổi cụ thể sẽ được thực thi trên mục đó, biến đổi các giá trị thô của nó thành các định dạng cuối cùng.
+3. **Phân nhánh đệ quy**:
+    - Nếu mục có `value` là một đối tượng, nó sẽ gọi đệ quy `to()` trên đối tượng đó.
+    - Nếu bản thân mục đó là một đối tượng không có loại được công nhận, nó sẽ tiếp tục duyệt để tìm các token lồng nhau.
+4. **Tính toàn vẹn dữ liệu**: Quy trình đảm bảo rằng các cấu trúc phức tạp (như bản đồ kiểu chữ hoặc các lớp bóng đổ đa tầng) được phân giải hoàn toàn trước giai đoạn tiếp theo của quy trình.