@dxtmisha/wiki 0.39.1 → 0.39.2

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesItems - Bộ điều phối cây thuộc tính'/>
+
+# Lớp PropertiesItems
+
+Lớp `PropertiesItems` đóng vai trò là bộ điều phối trung tâm để điều hướng và tìm kiếm qua các cây thuộc tính thiết kế phức tạp. Nó cung cấp một lớp trừu tượng cấp cao giúp ẩn đi các chi tiết phức tạp của việc duyệt cây, giải mã chỉ mục và lọc theo thiết kế cụ thể. Cho dù bạn cần tìm một token cụ thể theo đường dẫn dấu chấm, thực hiện tìm kiếm toàn cục theo danh mục hay thực thi các thao tác đệ quy sâu, `PropertiesItems` đóng vai trò là công cụ chính để khám phá thuộc tính.
+
+## Các tính năng chính
+
+- **Tập trung vào Thiết kế (Design Focusing)** — Cho phép lọc toàn bộ phạm vi tương tác thuộc tính vào một chủ đề thiết kế hoặc cụm thành phần duy nhất.
+- **Phân giải Siêu dữ liệu Sâu** — Chuyển đổi các chuỗi chỉ mục đơn giản (ví dụ: `theme.colors.primary`) thành các đối tượng thông tin toàn diện với ngữ cảnh cha đầy đủ.
+- **Công cụ Duyệt thống nhất** — Cung cấp các cơ chế `each` và `find` nhất quán cho cả việc khám phá phân cấp token theo kiểu nông và đệ quy sâu.
+- **Chuyển đổi Ngữ nghĩa Đường dẫn** — Tự động xử lý chuẩn hóa đường dẫn, chuyển đổi kebab-to-camelCase và hỗ trợ các biểu tượng liên kết đặc biệt như `?`.
+- **Lọc theo Danh mục & Biến** — Bao gồm các phương pháp tìm kiếm được tối ưu hóa để trích xuất các tập hợp con token dựa trên danh mục chức năng hoặc loại biến của chúng.
+
+## Khởi tạo
+
+Để khởi khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesItems(properties)`.
+
+**Tham số:**
+- `properties: PropertyList` — danh sách đầy đủ các thuộc tính (cây token) cần quản lý.
+
+```typescript
+import { PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Khởi tạo manager với cây token
+const manager = new PropertiesItems(allTokenData)
+
+// 2. (Tùy chọn) Tập trung môi trường vào một thiết kế cụ thể
+manager.setFocusDesign('my-theme')
+
+// 3. Truy xuất cấu trúc đã lọc
+const currentTokens = manager.get()
+```
+
+## Các phương thức
+
+- `get(): PropertyList` — trả về cấu trúc thuộc tính hiện tại (hỗ trợ lọc focus).
+- `getDesigns(): string[]` — trả về danh sách các tên thiết kế có sẵn.
+- `getItem(index): PropertyItem` — truy xuất một bản ghi thuộc tính cụ thể theo chỉ mục của nó.
+- `getInfo(index): PropertyItemsItem` — phân giải siêu dữ liệu đầy đủ và phân cấp cha cho một chỉ mục nhất định.
+- `getKeys(index): string[]` — giải mã một chuỗi đường dẫn thành các phân đoạn khóa đã chuẩn hóa.
+- `getName(name, item): string` — trả về tên hiển thị của một thuộc tính, có tính đến việc đổi tên.
+- `each(callback, property?): T[]` — thực hiện duyệt đệ quy sâu của cây.
+- `find(callback): PropertyItemsItem[]` — tìm kiếm các bản ghi khớp với các điều kiện tùy chỉnh.
+- `findCategory(category): PropertyItemsItem[]` — trích xuất các token thuộc về các danh mục chức năng cụ thể.
+- `setFocusDesign(design): this` — giới hạn phạm vi hoạt động ở một thiết kế cụ thể.
+
+## Các thao tác (Operations)
+
+### Luồng Khám phá Siêu dữ liệu & Duyệt cây
+
+`PropertiesItems` điều phối một số luồng logic phức tạp:
+1. **Giải mã chỉ mục**: Khi một chỉ mục như `theme.button-main.color` được yêu cầu, nó chuẩn hóa các phân đoạn thành camelCase và phân giải chúng dựa trên các đối tượng `value` lồng nhau của cây.
+2. **Quản lý Ngữ cảnh Đường dẫn**: Trong quá trình duyệt cây (`each`), lớp duy trì một ngăn xếp `parents`, cho phép mọi nút được khám phá biết chính xác vị trí của nó trong hệ thống phân cấp (quan trọng để tạo các biến CSS hoặc đường dẫn tài liệu).
+3. **Cô lập Thiết kế**: Bằng cách gọi `setFocusDesign()`, người dùng có thể chuyển đổi "chế độ xem" của toàn bộ cây. Các cuộc gọi tiếp theo đến `get()` hoặc `each()` sẽ tự động bỏ qua các thiết kế KHÔNG phải là thiết kế đang tập trung hoặc `_constructor` chung.
+4. **Chuẩn hóa liên kết**: Các phương thức như `getLink()` xử lý việc chuyển đổi các ký hiệu đường dẫn cũ (như `??` và `?`) thành các chỉ mục thuộc tính tuyệt đối, đủ điều kiện bằng cách thêm ngữ cảnh thiết kế và thành phần hiện tại vào trước.

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

@@ -0,0 +1,47 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesKeys - Key Semantic Transformer'/>
+
+# PropertiesKeys Class
+
+The `PropertiesKeys` class is a specialized static utility designed to parse and transform the semantic meaning of design token keys. It acts as the "grammatical engine" for property names, distinguishing between functional data keys and architectural metadata keys. By providing mechanisms for normalization, type-aware prefixing, and special symbol detection, it ensures that token keys remain consistent and predictable regardless of their source format (JSON, SCSS, or internal state).
+
+## Key Features
+
+- **Metadata Identification** — Detects protected system keys like `value`, `type`, and underscored internal properties.
+- **Prefix Normalization** — Automatically strips architectural symbols (like `=` or `|`) to extract the pure semantic name.
+- **Casing Orchestration** — Integrates with `toCamelCase` to maintain consistent naming conventions across the token tree.
+- **Type-Aware Re-keying** — Dynamically transforms keys based on their category (e.g., prepending `media-` to media tokens or `container-` to container queries).
+- **SCSS Compatibility** — Handles special formatting for SCSS-compatible keys, including leading ampersands.
+
+## Initialization
+
+As a static utility class, `PropertiesKeys` does not require instantiation and is ready to use upon import.
+
+```typescript
+import { PropertiesKeys } from '@dxtmisha/scripts'
+
+// Check if a key is a metadata field
+const isReserved = PropertiesKeys.isSpecialKey('type')
+
+// Resolve a clean semantic name
+const cleanName = PropertiesKeys.getName('=primary-color')
+// Returns: "primaryColor"
+```
+
+## Methods
+
+- `isSpecialKey(key): boolean` — checks if the key is a reserved system metadata field.
+- `isFull(name): boolean` — determines if the name is an absolute/complete definition.
+- `getName(name, camelCase?): string` — normalizes a key by stripping prefixes and optionally applying camelCase.
+- `reKey(key, type?): string` — transforms a key based on its architectural type (media, container, scss, etc.).
+
+## Operations
+
+### The Key Transformation Pipeline
+
+`PropertiesKeys` manages the translation logic between raw input formats and standardized internal tokens:
+1. **Semantic Extraction**: When `getName()` is called, the class uses `PropertiesTypes` regex triggers to identify and remove control symbols (like `=` which signifies an immutable value).
+2. **Contextual Prefixing**: In the `reKey()` flow, the class checks the `_type` of the token. If it identifies a `media` type, it intelligently ensures the key reflects this role (e.g., `desktop` becomes `mediaDesktop`), avoiding redundant prefixes if they already exist.
+3. **Internal State Protection**: The `isSpecialKey()` check is crucial for traversal engines; it prevents the processing of internal machinery (keys starting with `_`) as if they were actual user-defined design tokens.
+4. **Platform Adaptation**: For SCSS generation, the class specifically handles prefixing with `&`, allowing design tokens to be directly usable in nested style declarations.

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

@@ -0,0 +1,47 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesKeys - Семантический трансформер ключей'/>
+
+# Класс PropertiesKeys
+
+Класс `PropertiesKeys` — это специализированная статическая утилита, предназначенная для парсинга и трансформации семантического значения ключей токенов дизайна. Он выступает в роли «грамматического движка» для имен свойств, различая ключи функциональных данных и ключи архитектурных метаданных. Предоставляя механизмы нормализации, типизированного добавления префиксов и обнаружения специальных символов, он гарантирует, что ключи токенов остаются последовательными и предсказуемыми независимо от их исходного формата (JSON, SCSS или внутреннее состояние).
+
+## Ключевые особенности
+
+- **Идентификация метаданных** — обнаруживает защищенные системные ключи, такие как `value`, `type`, и внутренние свойства, начинающиеся с подчеркивания.
+- **Нормализация префиксов** — автоматически удаляет архитектурные символы (такие как `=` или `|`) для извлечения чистого семантического имени.
+- **Оркестрация регистра** — интегрируется с `toCamelCase` для поддержания единых соглашений об именовании во всем дереве токенов.
+- **Типизированное переименование (Re-keying)** — динамически преобразует ключи на основе их категории (например, добавляя `media-` к токенам медиа или `container-` к контейнерным запросам).
+- **Совместимость с SCSS** — обрабатывает специальное форматирование для ключей, совместимых с SCSS, включая ведущие амперсанды.
+
+## Инициализация
+
+Являясь статическим сервисным классом, `PropertiesKeys` не требует создания экземпляра и готов к использованию сразу после импорта.
+
+```typescript
+import { PropertiesKeys } from '@dxtmisha/scripts'
+
+// Проверка, является ли ключ полем метаданных
+const isReserved = PropertiesKeys.isSpecialKey('type')
+
+// Получение чистого семантического имени
+const cleanName = PropertiesKeys.getName('=primary-color')
+// Возвращает: "primaryColor"
+```
+
+## Методы
+
+- `isSpecialKey(key): boolean` — проверяет, является ли ключ зарезервированным системным полем метаданных.
+- `isFull(name): boolean` — определяет, является ли имя абсолютным/полным определением.
+- `getName(name, camelCase?): string` — нормализует ключ, удаляя префиксы и опционально применяя camelCase.
+- `reKey(key, type?): string` — преобразует ключ на основе его архитектурного типа (media, container, scss и т.д.).
+
+## Операции
+
+### Конвейер трансформации ключей
+
+`PropertiesKeys` управляет логикой перевода между необработанными входными форматами и стандартизированными внутренними токенами:
+1. **Семантическое извлечение**: При вызове `getName()` класс использует регулярные выражения `PropertiesTypes` для идентификации и удаления управляющих символов (таких как `=`, означающий неизменяемое значение).
+2. **Контекстное добавление префиксов**: В потоке `reKey()` класс проверяет `_type` токена. Если идентифицирован тип `media`, он интеллектуально гарантирует, что ключ отражает эту роль (например, `desktop` становится `mediaDesktop`), избегая избыточных префиксов, если они уже существуют.
+3. **Защита внутреннего состояния**: Проверка `isSpecialKey()` критически важна для движков обхода; она предотвращает обработку внутренних механизмов (ключи, начинающиеся с `_`) как если бы они были реальными токенами дизайна, определенными пользователем.
+4. **Адаптация под платформы**: Для генерации SCSS класс специально обрабатывает добавление префикса `&`, позволяя использовать токены дизайна напрямую во вложенных объявлениях стилей.

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

@@ -0,0 +1,47 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesKeys - Bộ chuyển đổi ngữ nghĩa khóa'/>
+
+# Lớp PropertiesKeys
+
+Lớp `PropertiesKeys` là một tiện ích tĩnh chuyên biệt được thiết kế để phân tích và chuyển đổi ý nghĩa ngữ nghĩa của các khóa token thiết kế. Nó đóng vai trò là "công cụ ngữ pháp" cho các tên thuộc tính, phân biệt giữa các khóa dữ liệu chức năng và các khóa siêu dữ liệu kiến trúc. Bằng cách cung cấp các cơ chế chuẩn hóa, thêm tiền tố dựa trên loại và phát hiện ký hiệu đặc biệt, nó đảm bảo rằng các khóa token luôn nhất quán và có thể dự đoán được bất kể định dạng nguồn của chúng (JSON, SCSS hoặc trạng thái nội bộ).
+
+## Các tính năng chính
+
+- **Nhận dạng siêu dữ liệu** — Phát hiện các khóa hệ thống được bảo vệ như `value`, `type` và các thuộc tính nội bộ bắt đầu bằng dấu gạch dưới.
+- **Chuẩn hóa tiền tố** — Tự động loại bỏ các ký hiệu kiến trúc (như `=` hoặc `|`) để trích xuất tên ngữ nghĩa thuần túy.
+- **Điều phối kiểu chữ** — Tích hợp với `toCamelCase` để duy trì các quy ước đặt tên nhất quán trong toàn bộ cây token.
+- **Đổi khóa nhận biết loại (Type-Aware Re-keying)** — Chuyển đổi linh hoạt các khóa dựa trên danh mục của chúng (ví dụ: thêm tiền tố `media-` cho các token media hoặc `container-` cho các truy vấn container).
+- **Khả năng tương thích SCSS** — Xử lý định dạng đặc biệt cho các khóa tương thích với SCSS, bao gồm cả các dấu và (`&`) ở đầu.
+
+## Khởi tạo
+
+Là một lớp tiện ích tĩnh, `PropertiesKeys` không yêu cầu khởi tạo thực thể và sẵn sàng sử dụng ngay sau khi nhập.
+
+```typescript
+import { PropertiesKeys } from '@dxtmisha/scripts'
+
+// Kiểm tra xem một khóa có phải là trường siêu dữ liệu không
+const isReserved = PropertiesKeys.isSpecialKey('type')
+
+// Phân giải một tên ngữ nghĩa sạch
+const cleanName = PropertiesKeys.getName('=primary-color')
+// Trả về: "primaryColor"
+```
+
+## Các phương thức
+
+- `isSpecialKey(key): boolean` — Kiểm tra xem khóa có phải là trường siêu dữ liệu hệ thống được bảo vệ hay không.
+- `isFull(name): boolean` — Xác định xem tên có phải là một định nghĩa tuyệt đối/đầy đủ hay không.
+- `getName(name, camelCase?): string` — Chuẩn hóa một khóa bằng cách loại bỏ các tiền tố và áp dụng camelCase tùy chọn.
+- `reKey(key, type?): string` — Chuyển đổi một khóa dựa trên loại kiến trúc của nó (media, container, scss, v.v.).
+
+## Các thao tác (Operations)
+
+### Quy trình chuyển đổi khóa (The Key Transformation Pipeline)
+
+`PropertiesKeys` quản lý logic chuyển đổi giữa các định dạng đầu vào thô và các token nội bộ chuẩn hóa:
+1. **Trích xuất ngữ nghĩa**: Khi `getName()` được gọi, lớp sử dụng các regex của `PropertiesTypes` để xác định và loại bỏ các ký hiệu điều khiển (như `=` biểu thị một giá trị bất biến).
+2. **Thêm tiền tố theo ngữ cảnh**: Trong luồng `reKey()`, lớp kiểm tra `_type` của token. Nếu xác định được loại `media`, nó sẽ đảm bảo khóa phản ánh vai trò này một cách thông minh (ví dụ: `desktop` trở thành `mediaDesktop`), tránh các tiền tố dư thừa nếu chúng đã tồn tại.
+3. **Bảo vệ trạng thái nội bộ**: Kiểm tra `isSpecialKey()` là rất quan trọng đối với các công cụ duyệt cây; nó ngăn chặn việc xử lý các cơ chế nội bộ (các khóa bắt đầu bằng `_`) như thể chúng là các token thiết kế thực sự do người dùng định nghĩa.
+4. **Thích ứng nền tảng**: Để tạo SCSS, lớp xử lý cụ thể việc thêm tiền tố `&`, cho phép các token thiết kế có thể sử dụng trực tiếp trong các khai báo kiểu lồng nhau.

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

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesMain - Global Token Orchestrator'/>
+
+# PropertiesMain Class
+
+The `PropertiesMain` class is the high-level orchestrator responsible for synthesizing the global design token tree. It manages the entire lifecycle of "main" tokens—from filesystem discovery and raw reading to multi-stage semantic transformation and hierarchical merging. By abstracting the complexities of modular property loading, it provides a unified entry point for obtaining fully resolved and standardized design configurations.
+
+## Key Features
+
+- **Automated Pipeline Orchestration** — Integrates multiple utilities (`Import`, `Standard`, `Convector`) into a single cohesive loading sequence.
+- **Design-Centric Discovery** — Leverages `PropertiesPath` to automatically locate and process tokens for all active design themes.
+- **Dynamic Configuration Merging** — Supports hot-swapping or layering settings onto the global tree through deep recursive synchronization.
+- **Structural Integrity Enforcement** — Automatically applies structural wrapping and separators to ensure tokens are correctly categorized and accessible.
+- **Internal State Synchronization** — Preserves internal engine flags (properties starting with `_`) during configuration updates.
+
+## Initialization
+
+To initialize the object, call the `PropertiesMain(path)` constructor.
+
+**Parameters:**
+- `path: PropertiesPath` — an instance of the class responsible for filesystem discovery and path resolution.
+
+```typescript
+import { PropertiesMain, PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Initialize the prerequisite path manager
+const pathManager = new PropertiesPath(['packages', 'tokens'])
+
+// 2. Create the main token orchestrator
+const main = new PropertiesMain(pathManager)
+
+// 3. Resolve the complete global property tree
+const globalTokens = main.get()
+```
+
+## Methods
+
+- `get(): PropertyList` — performs the full transformation pipeline and returns all resolved main tokens.
+- `getBySettings(list): PropertyList` — merges a custom settings cluster into the global token tree.
+
+## Operations
+
+### The Global Transformation Pipeline
+
+When `get()` is invoked, `PropertiesMain` executes the following sequence for every design discovered:
+1. **Reading**: Fetches raw data from the filesystem using `PropertiesTool`.
+2. **Semantic Conversion**: Passes data through `PropertiesConvector` to transform raw values into tokens.
+3. **Standardization**: Normalizes structures via `PropertiesStandard` to ensure consistent object shapes.
+4. **Link Resolution**: Utilizes `PropertiesImport` to recursively fetch and merge any external file references.
+5. **Structural Finalization**: If necessary, it splits keys via `PropertiesSeparator` and applies `PropertiesWrap` to organize tokens into their final hierarchical containers.
+6. **Unified Synthesis**: Combines processed data from all designs into a single `PropertyList` where keys represent top-level design names.

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

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesMain - Оркестратор глобальных токенов'/>
+
+# Класс PropertiesMain
+
+Класс `PropertiesMain` — это высокоуровневый оркестратор, отвечающий за синтез глобального дерева токенов дизайна. Он управляет всем жизненным циклом «основных» (main) токенов — от обнаружения в файловой системе и необработанного чтения до многоэтапной семантической трансформации и иерархического слияния. Абстрагируя сложности модульной загрузки свойств, он предоставляет единую точку входа для получения полностью разрешенных и стандартизированных конфигураций дизайна.
+
+## Ключевые особенности
+
+- **Автоматизированная оркестровка конвейера** — объединяет несколько утилит (`Import`, `Standard`, `Convector`) в единую последовательность загрузки.
+- **Дизайн-центричное обнаружение** — использует `PropertiesPath` для автоматического поиска и обработки токенов для всех активных тем дизайна.
+- **Динамическое слияние конфигураций** — поддерживает «горячую» замену или наслоение настроек на глобальное дерево через глубокую рекурсивную синхронизацию.
+- **Обеспечение структурной целостности** — автоматически применяет структурную обертку и разделители, чтобы гарантировать правильную категоризацию и доступность токенов.
+- **Синхронизация внутреннего состояния** — сохраняет внутренние флаги движка (свойства, начинающиеся с `_`) во время обновления конфигурации.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PropertiesMain(path)`.
+
+**Параметры:**
+- `path: PropertiesPath` — экземпляр класса, отвечающего за обнаружение в файловой системе и разрешение путей.
+
+```typescript
+import { PropertiesMain, PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Инициализация необходимого менеджера путей
+const pathManager = new PropertiesPath(['packages', 'tokens'])
+
+// 2. Создание оркестратора основных токенов
+const main = new PropertiesMain(pathManager)
+
+// 3. Разрешение полного глобального дерева свойств
+const globalTokens = main.get()
+```
+
+## Методы
+
+- `get(): PropertyList` — выполняет полный конвейер трансформации и возвращает все разрешенные основные токены.
+- `getBySettings(list): PropertyList` — объединяет кастомный кластер настроек с глобальным деревом токенов.
+
+## Операции
+
+### Глобальный конвейер трансформации
+
+При вызове `get()` класс `PropertiesMain` выполняет следующую последовательность для каждого обнаруженного дизайна:
+1. **Чтение**: Получает необработанные данные из файловой системы с помощью `PropertiesTool`.
+2. **Семантическая конвертация**: Пропускает данные через `PropertiesConvector` для преобразования сырых значений в токены.
+3. **Стандартизация**: Нормализует структуры через `PropertiesStandard` для обеспечения единообразия объектов.
+4. **Разрешение ссылок**: Использует `PropertiesImport` для рекурсивного получения и слияния любых ссылок на внешние файлы.
+5. **Структурное завершение**: При необходимости разделяет ключи через `PropertiesSeparator` и применяет `PropertiesWrap` для организации токенов в итоговые иерархические контейнеры.
+6. **Унифицированный синтез**: Объединяет обработанные данные всех дизайнов в единый `PropertyList`, где ключами являются названия дизайнов верхнего уровня.

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

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesMain - Bộ điều phối Token toàn cầu'/>
+
+# Lớp PropertiesMain
+
+Lớp `PropertiesMain` là bộ điều phối cấp cao chịu trách nhiệm tổng hợp cây token thiết kế toàn cầu. Nó quản lý toàn bộ vòng đời của các token "chính" (main) — từ việc khám phá hệ thống tệp và đọc dữ liệu thô đến việc chuyển đổi ngữ nghĩa nhiều giai đoạn và hợp nhất phân cấp. Bằng cách trừu tượng hóa các phức tạp của việc tải thuộc tính mô-đun, nó cung cấp một điểm nhập thống nhất để có được các cấu hình thiết kế đã được phân giải đầy đủ và chuẩn hóa.
+
+## Các tính năng chính
+
+- **Điều phối quy trình tự động** — Tích hợp nhiều tiện ích (`Import`, `Standard`, `Convector`) vào một chuỗi tải gắn kết duy nhất.
+- **Khám phá tập trung vào Thiết kế** — Cung cấp `PropertiesPath` để tự động định vị và xử lý các token cho tất cả các chủ đề thiết kế đang hoạt động.
+- **Hợp nhất cấu hình linh hoạt** — Hỗ trợ thay thế nóng hoặc xếp lớp các cài đặt lên cây toàn cầu thông qua đồng bộ hóa đệ quy sâu.
+- **Thực thi tính toàn vẹn cấu trúc** — Tự động áp dụng bao bọc cấu trúc và dấu phân cách để đảm bảo các token được phân loại và truy cập chính xác.
+- **Đồng bộ hóa trạng thái nội bộ** — Bảo toàn các cờ nội bộ của engine (các thuộc tính bắt đầu bằng `_`) trong quá trình cập nhật cấu hình.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesMain(path)`.
+
+**Tham số:**
+- `path: PropertiesPath` — một thực thể của lớp chịu trách nhiệm khám phá hệ thống tệp và phân giải đường dẫn.
+
+```typescript
+import { PropertiesMain, PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Khởi tạo trình quản lý đường dẫn tiên quyết
+const pathManager = new PropertiesPath(['packages', 'tokens'])
+
+// 2. Tạo bộ điều phối token chính
+const main = new PropertiesMain(pathManager)
+
+// 3. Phân giải cây thuộc tính toàn cầu hoàn chỉnh
+const globalTokens = main.get()
+```
+
+## Các phương thức
+
+- `get(): PropertyList` — thực hiện quy trình chuyển đổi đầy đủ và trả về tất cả các token chính đã được phân giải.
+- `getBySettings(list): PropertyList` — hợp nhất một cụm cài đặt tùy chỉnh vào cây token toàn cầu.
+
+## Các thao tác (Operations)
+
+### Quy trình Chuyển đổi Toàn cầu (Global Transformation Pipeline)
+
+Khi `get()` được gọi, `PropertiesMain` sẽ thực thi chuỗi hành động sau cho mọi thiết kế được khám phá:
+1. **Đọc**: Lấy dữ liệu thô từ hệ thống tệp bằng `PropertiesTool`.
+2. **Chuyển đổi ngữ nghĩa**: Truyền dữ liệu qua `PropertiesConvector` để chuyển đổi các giá trị thô thành các token.
+3. **Chuẩn hóa**: Chuẩn hóa cấu trúc thông qua `PropertiesStandard` để đảm bảo hình dạng đối tượng nhất quán.
+4. **Phân giải liên kết**: Sử dụng `PropertiesImport` để lấy và hợp nhất đệ quy mọi tham chiếu tệp bên ngoài.
+5. **Hoàn thiện cấu trúc**: Nếu cần, nó sẽ tách các khóa qua `PropertiesSeparator` và áp dụng `PropertiesWrap` để tổ chức các token vào các vùng chứa phân cấp cuối cùng của chúng.
+6. **Tổng hợp thống nhất**: Kết hợp dữ liệu đã xử lý từ tất cả các thiết kế vào một `PropertyList` duy nhất, trong đó các khóa đại diện cho tên thiết kế cấp cao nhất.

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

@@ -0,0 +1,118 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesPalette - Palette & Shade Manager'/>
+
+# PropertiesPalette Class
+
+The `PropertiesPalette` class is a specialized manager for handling color-related design tokens. It focuses on two primary areas: managing color saturation steps (shades) and tracking the actual usage of palette colors within functional variables. By analyzing how colors are referenced throughout the design system, it helps ensure that theme definitions remain consistent and that generated CSS variables correctly point to their corresponding palette entries.
+
+## Key Features
+
+- **Saturation Discovery** — Automatically extracts available shade levels (e.g., 50, 100, 200) from the property tree.
+- **Usage Tracking** — Identifies which palette colors are actually mapped to component variables, facilitating dead-code elimination or audit reports.
+- **Theme-Aware Mapping** — Resolves complex color links, accounting for theme-specific overrides (like `basic` or `dark`).
+- **CSS Variable Synthesis** — Transparently converts internal color references into standardized CSS variable names (e.g., `--design-palette-theme-color`).
+
+## Initialization
+
+To initialize the object, call the `PropertiesPalette(items)` constructor.
+
+**Parameters:**
+- `items: PropertiesItems` — an instance of the coordinator class responsible for property tree traversal and searching.
+
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Prepare the dependency coordinator
+const manager = new PropertiesItems(allTokenData)
+
+// 2. Create the palette manager
+const palette = new PropertiesPalette(manager)
+
+// 3. Extract active shades or used colors
+const shades = palette.getShade()
+const usedColors = palette.getUsed()
+```
+
+## Methods
+
+### `getShade`
+Retrieves a list of available saturation levels (shades) grouped by design. This method scans the entire property tree for items categorized specifically as 'shade' and returns their resolved structures. These shades typically represent the numerical scale of color saturation (e.g., 50, 100, 200) used in the design system.
+
+**Returns:** `PropertyPaletteList` — a specialized object where keys are design names and values are arrays of color shade tokens.
+
+```typescript
+const shades = palette.getShade();
+// Result: { "basic": ["50", "100", ...], "premium": ["50", ...] }
+```
+
+### `getUsed`
+Generates a comprehensive report of all palette colors currently utilized in functional variables across the entire design system. It iterates through all tokens, identifying CSS variable references that point to palette entries, and maps them to their generated CSS variable names. This is essential for auditing color usage and identifying orphaned palette entries.
+
+**Returns:** `PropertyPaletteUsed[]` — an array of objects, each containing a functional variable name and its corresponding palette-derived CSS variable name.
+
+```typescript
+const report = palette.getUsed();
+/* Result: 
+[
+  { "name": "primaryBackground", "value": ["--basic-palette-basic-blue-50"] }
+] 
+*/
+```
+
+### `getFocusUsed`
+Recursively resolves a specific property value to determine its ultimate palette source. This utility method is used to trace links through multiple layers of abstraction (such as component variables pointing to theme colors, which in turn point to palette shades).
+
+**Parameters:**
+- `list: PropertyItem['value'][]` — a list of known palette values to check against during resolution.
+- `design: string` — the name of the current design theme.
+- `component: string` — the name of the component context being resolved.
+- `value: string` — the raw value or link (e.g., `{color.primary}`) to trace back to the palette.
+
+**Returns:** `string | undefined` — the ultimate resolved value string if it leads to a palette entry; otherwise, `undefined`.
+
+```typescript
+const source = palette.getFocusUsed(
+  paletteList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+);
+```
+
+## Operations
+
+### The Color Usage Resolution Flow
+
+`PropertiesPalette` performs a deep analysis of how colors flow from the palette to components:
+1. **Tree Traversal**: Using `PropertiesItems.each()`, the class visits every node in the design system.
+2. **Variable Filtering**: It specifically targets items of type `var` that are NOT themselves categorized as `color`, yet hold string values that look like color links.
+3. **Recursive Link Resolution**: When a candidate is found, `getFocusUsed()` resolves any intermediate links (e.g., `primary` -> `theme.brand.main` -> `palette.blue.50`) until it reaches the raw palette definition or confirms the link is non-palette.
+4. **Theme Detection**: It examines the hierarchy (`parents`) to identify if the color belongs to a specific theme block, allowing it to correctly name the resulting CSS variable (e.g., prepending the theme name).
+5. **Data Aggregation**: Results are grouped by variable name, providing a clear map of which functional tokens consume which palette colors.
+
+## Examples
+
+### Extracting Shades and Usage
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(allTokenData)
+const palette = new PropertiesPalette(manager)
+
+// 1. Get available shades
+const shades = palette.getShade()
+
+// 2. Scan for used colors in components
+const report = palette.getUsed()
+```
+
+### Manual Link Resolution
+```typescript
+const isPaletteValue = palette.getFocusUsed(
+  paletteValueList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+)
+```

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

@@ -0,0 +1,118 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesPalette - Менеджер палитры и оттенков'/>
+
+# Класс PropertiesPalette
+
+Класс `PropertiesPalette` — это специализированный менеджер для работы с токенами дизайна, связанными с цветом. Он фокусируется на двух основных областях: управлении шагами насыщенности цвета (оттенками) и отслеживании фактического использования цветов палитры в функциональных переменных. Анализируя способы использования цветов в системе дизайна, он помогает гарантировать согласованность определений тем и правильность ссылок сгенерированных CSS-переменных на соответствующие записи в палитре.
+
+## Ключевые особенности
+
+- **Обнаружение насыщенности** — автоматически извлекает доступные уровни оттенков (например, 50, 100, 200) из дерева свойств.
+- **Отслеживание использования** — идентифицирует, какие цвета палитры фактически сопоставлены с переменными компонентов, упрощая удаление неиспользуемого кода или проведение аудита.
+- **Сопоставление с учетом темы** — разрешает сложные ссылки на цвета, учитывая специфические для темы переопределения (например, `basic` или `dark`).
+- **Синтез CSS-переменных** — прозрачно преобразует внутренние ссылки на цвета в стандартизированные имена CSS-переменных (например, `--design-palette-theme-color`).
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PropertiesPalette(items)`.
+
+**Параметры:**
+- `items: PropertiesItems` — экземпляр координационного класса, отвечающего за обход и поиск в дереве свойств.
+
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Подготовка необходимого координатора
+const manager = new PropertiesItems(allTokenData)
+
+// 2. Создание менеджера палитры
+const palette = new PropertiesPalette(manager)
+
+// 3. Извлечение активных оттенков или используемых цветов
+const shades = palette.getShade()
+const usedColors = palette.getUsed()
+```
+
+## Методы
+
+### `getShade`
+Извлекает список доступных уровней насыщенности (оттенков), сгруппированных по дизайну. Метод сканирует все дерево свойств на наличие элементов, классифицированных именно как 'shade' (оттенок), и возвращает их разрешенные структуры. Эти оттенки обычно представляют числовую шкалу насыщенности цвета (например, 50, 100, 200), используемую в дизайн-системе.
+
+**Возвращает:** `PropertyPaletteList` — специализированный объект, где ключами являются названия дизайнов, а значениями — массивы токенов оттенков цветов.
+
+```typescript
+const shades = palette.getShade();
+// Результат: { "basic": ["50", "100", ...], "premium": ["50", ...] }
+```
+
+### `getUsed`
+Генерирует исчерпывающий отчет обо всех цветах палитры, используемых в данный момент в функциональных переменных во всей системе дизайна. Он выполняет итерацию по всем токенам, идентифицируя ссылки на CSS-переменные, которые указывают на записи палитры, и сопоставляет их с сгенерированными именами CSS-переменных. Это необходимо для аудита использования цветов и выявления неиспользуемых записей палитры.
+
+**Возвращает:** `PropertyPaletteUsed[]` — массив объектов, каждый из которых содержит имя функциональной переменной и соответствующее ей имя CSS-переменной, производное от палитры.
+
+```typescript
+const report = palette.getUsed();
+/* Результат: 
+[
+  { "name": "primaryBackground", "value": ["--basic-palette-basic-blue-50"] }
+] 
+*/
+```
+
+### `getFocusUsed`
+Рекурсивно разрешает конкретное значение свойства для определения его конечного источника в палитре. Этот вспомогательный метод используется для отслеживания ссылок через несколько уровней абстракции (например, переменные компонентов, указывающие на цвета темы, которые, в свою очередь, указывают на оттенки палитры).
+
+**Параметры:**
+- `list: PropertyItem['value'][]` — список известных значений палитры для проверки в процессе разрешения.
+- `design: string` — название текущей темы дизайна.
+- `component: string` — имя контекста компонента, для которого выполняется разрешение.
+- `value: string` — необработанное значение или ссылка (например, `{color.primary}`) для отслеживания до палитры.
+
+**Возвращает:** `string | undefined` — конечная разрешенная строка значения, если она ведет к записи в палитре; в противном случае — `undefined`.
+
+```typescript
+const source = palette.getFocusUsed(
+  paletteList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+);
+```
+
+## Операции
+
+### Поток разрешения использования цветов
+
+`PropertiesPalette` выполняет глубокий анализ того, как цвета переходят из палитры к компонентам:
+1. **Обход дерева**: Используя `PropertiesItems.each()`, класс посещает каждый узел в системе дизайна.
+2. **Фильтрация переменных**: Он нацелен именно на элементы типа `var`, которые сами не классифицируются как `color`, но содержат строковые значения, похожие на ссылки на цвета.
+3. **Рекурсивное разрешение ссылок**: При обнаружении кандидата `getFocusUsed()` разрешает любые промежуточные ссылки (например, `primary` -> `theme.brand.main` -> `palette.blue.50`), пока не достигнет необработанного определения палитры или не подтвердит, что ссылка не относится к палитре.
+4. **Определение темы**: Он исследует иерархию (`parents`), чтобы определить, принадлежит ли цвет конкретному блоку темы, что позволяет правильно назвать результирующую CSS-переменную (например, добавив имя темы в начало).
+5. **Агрегация данных**: Результаты группируются по имени переменной, предоставляя четкую карту того, какие функциональные токены потребляют те или иные цвета палитры.
+
+## Примеры
+
+### Извлечение оттенков и использования
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(allTokenData)
+const palette = new PropertiesPalette(manager)
+
+// 1. Получение доступных оттенков
+const shades = palette.getShade()
+
+// 2. Сканирование используемых цветов в компонентах
+const report = palette.getUsed()
+```
+
+### Ручное разрешение ссылки
+```typescript
+const isPaletteValue = palette.getFocusUsed(
+  paletteValueList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+)
+```