@dxtmisha/wiki 0.39.1 → 0.39.2

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

@@ -0,0 +1,118 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesPalette - Trình quản lý Bảng màu & Sắc độ'/>
+
+# Lớp PropertiesPalette
+
+Lớp `PropertiesPalette` là một trình quản lý chuyên biệt để xử lý các token thiết kế liên quan đến màu sắc. Nó tập trung vào hai lĩnh vực chính: quản lý các bước độ bão hòa màu (sắc độ - shades) và theo dõi việc sử dụng thực tế của các màu trong bảng màu (palette) bên trong các biến chức năng. Bằng cách phân tích cách các màu sắc được tham chiếu trong toàn bộ hệ thống thiết kế, nó giúp đảm bảo rằng các định nghĩa chủ đề vẫn nhất quán và các biến CSS được tạo ra trỏ chính xác đến các mục bảng màu tương ứng của chúng.
+
+## Các tính năng chính
+
+- **Khám phá độ bão hòa** — Tự động trích xuất các mức độ sắc độ có sẵn (ví dụ: 50, 100, 200) từ cây thuộc tính.
+- **Theo dõi sử dụng** — Xác định các màu bảng màu nào thực sự được ánh xạ tới các biến thành phần, hỗ trợ loại bỏ mã chết hoặc báo cáo kiểm tra.
+- **Ánh xạ nhận biết chủ đề (Theme-Aware Mapping)** — Phân giải các liên kết màu phức tạp, tính đến các ghi đè cụ thể của chủ đề (như `basic` hoặc `dark`).
+- **Tổng hợp biến CSS** — Chuyển đổi minh bạch các tham chiếu màu nội bộ thành các tên biến CSS chuẩn hóa (ví dụ: `--design-palette-theme-color`).
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesPalette(items)`.
+
+**Tham số:**
+- `items: PropertiesItems` — một thực thể của lớp điều phối chịu trách nhiệm duyệt và tìm kiếm cây thuộc tính.
+
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Chuẩn bị bộ điều phối tiên quyết
+const manager = new PropertiesItems(allTokenData)
+
+// 2. Tạo trình quản lý bảng màu
+const palette = new PropertiesPalette(manager)
+
+// 3. Trích xuất các sắc độ hoạt động hoặc các màu đã sử dụng
+const shades = palette.getShade()
+const usedColors = palette.getUsed()
+```
+
+## Các phương thức
+
+### `getShade`
+Truy xuất danh sách các mức độ bão hòa có sẵn (sắc độ - shades) được nhóm theo thiết kế. Phương thức này quét toàn bộ cây thuộc tính để tìm các mục được phân loại cụ thể là 'shade' và trả về cấu trúc đã phân giải của chúng. Các sắc độ này thường đại diện cho thang điểm định số của độ bão hòa màu (ví dụ: 50, 100, 200) được sử dụng trong hệ thống thiết kế.
+
+**Trả về:** `PropertyPaletteList` — một đối tượng chuyên biệt trong đó các khóa là tên thiết kế và giá trị là các mảng token sắc độ màu.
+
+```typescript
+const shades = palette.getShade();
+// Kết quả: { "basic": ["50", "100", ...], "premium": ["50", ...] }
+```
+
+### `getUsed`
+Tạo một báo cáo toàn diện về tất cả các màu bảng màu hiện đang được sử dụng trong các biến chức năng trên toàn bộ hệ thống thiết kế. Nó lặp qua tất cả các token, xác định các tham chiếu biến CSS trỏ đến các mục bảng màu và ánh xạ chúng tới các tên biến CSS được tạo ra. Điều này rất cần thiết để kiểm tra việc sử dụng màu sắc và xác định các mục bảng màu không được sử dụng.
+
+**Trả về:** `PropertyPaletteUsed[]` — một mảng các đối tượng, mỗi đối tượng chứa tên biến chức năng và tên biến CSS tương ứng được dẫn xuất từ bảng màu.
+
+```typescript
+const report = palette.getUsed();
+/* Kết quả: 
+[
+  { "name": "primaryBackground", "value": ["--basic-palette-basic-blue-50"] }
+] 
+*/
+```
+
+### `getFocusUsed`
+Phân giải đệ quy một giá trị thuộc tính cụ thể để xác định nguồn bảng màu cuối cùng của nó. Phương thức tiện ích này được sử dụng để theo dõi các liên kết qua nhiều lớp trừu tượng (chẳng hạn như các biến thành phần trỏ đến màu chủ đề, vốn lại trỏ đến các sắc độ bảng màu).
+
+**Tham số:**
+- `list: PropertyItem['value'][]` — danh sách các giá trị bảng màu đã biết để kiểm tra trong quá trình phân giải.
+- `design: string` — tên của chủ đề thiết kế hiện tại.
+- `component: string` — tên của ngữ cảnh thành phần đang được phân giải.
+- `value: string` — giá trị thô hoặc liên kết (ví dụ: `{color.primary}`) để truy xuất nguồn gốc trở lại bảng màu.
+
+**Trả về:** `string | undefined` — chuỗi giá trị đã phân giải cuối cùng nếu nó dẫn đến một mục bảng màu; nếu không sẽ là `undefined`.
+
+```typescript
+const source = palette.getFocusUsed(
+  paletteValueList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+);
+```
+
+## Các thao tác (Operations)
+
+### Luồng Phân giải Sử dụng Màu sắc (The Color Usage Resolution Flow)
+
+`PropertiesPalette` thực hiện phân tích sâu về cách màu sắc truyền từ bảng màu đến các thành phần:
+1. **Duyệt cây**: Sử dụng `PropertiesItems.each()`, lớp sẽ truy cập mọi nút trong hệ thống thiết kế.
+2. **Lọc biến**: Nó nhắm mục tiêu cụ thể vào các mục thuộc loại `var` không phải là loại `color`, nhưng giữ các giá trị chuỗi trông giống như các liên kết màu.
+3. **Phân giải liên kết đệ quy**: Khi tìm thấy một ứng cử viên, `getFocusUsed()` sẽ phân giải mọi liên kết trung gian (ví dụ: `primary` -> `theme.brand.main` -> `palette.blue.50`) cho đến khi nó đạt đến định nghĩa bảng màu thô hoặc xác nhận liên kết đó không phải bảng màu.
+4. **Phát hiện chủ đề**: Nó kiểm tra hệ thống phân cấp (`parents`) để xác định xem màu sắc có thuộc về một khối chủ đề cụ thể hay không, cho phép nó đặt tên chính xác cho biến CSS kết quả (ví dụ: thêm tên chủ đề vào trước).
+5. **Tổng hợp dữ liệu**: Kết quả được nhóm theo tên biến, cung cấp một bản đồ rõ ràng về các token chức năng nào tiêu thụ màu sắc bảng màu nào.
+
+## Ví dụ (Examples)
+
+### Trích xuất sắc độ và Cách sử dụng
+```typescript
+import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(allTokenData)
+const palette = new PropertiesPalette(manager)
+
+// 1. Lấy các sắc độ có sẵn
+const shades = palette.getShade()
+
+// 2. Quét các màu đã sử dụng trong các thành phần
+const report = palette.getUsed()
+```
+
+### Phân giải liên kết thủ công
+```typescript
+const isPaletteValue = palette.getFocusUsed(
+  paletteValueList, 
+  'basic', 
+  'button', 
+  '{color.primary}'
+)
+```

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

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesPath - Path & Environment Resolver'/>
+
+# PropertiesPath Class
+
+The `PropertiesPath` class is a core utility responsible for translating abstract design identities into concrete physical filesystem paths. It manages the directory mapping for both global design tokens and specific component overrides, ensuring that cross-platform path discovery remains consistent. By providing cached traversal methods like `to` and `toAll`, it coordinates the data loading sequence for multi-theme projects, acting as the primary source of environmental truth for the properties engine.
+
+## Key Features
+
+- **Multi-Design Mapping** — Automatically maps an array of design names to their corresponding token and component directories.
+- **Cross-Platform Root Discovery** — Leverages `PropertiesFile` to ensure paths are absolute and resolved correctly across different operating systems.
+- **Internal Optimization (Caching)** — Integrated with `PropertiesCache` to minimize redundant filesystem access during complex token transformation pipelines.
+- **Constructor Mode Detection** — Identifies and handles the special `_constructor` design, which serves as the common base for all themes.
+- **Flexible Data Traversal** — Provides high-level callbacks for processing design files without exposing raw filesystem details.
+
+## Initialization
+
+To initialize the object, call the `PropertiesPath(designs)` constructor.
+
+**Parameters:**
+- `designs: string[]` — a list of design names corresponding to folder names in the project structure.
+
+```typescript
+import { PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Define the designs to be managed
+const activeDesigns = ['basic', 'constructor', 'premium']
+
+// 2. Create the path resolver instance
+const pathResolver = new PropertiesPath(activeDesigns)
+
+// 3. Resolve paths for a specific design
+const basicPaths = pathResolver.getPath('basic')
+```
+
+## Methods
+
+- `isConstructor(): boolean` — checks if the current environment includes a base constructor design.
+- `getDesigns(): string[]` — returns the list of design names registered in the instance.
+- `getPath(name): PropertiesPathItem` — retrieves the specific paths (global and component) for a given design.
+- `getPaths(): PropertiesPathList` — returns the full registry of design-to-path mappings.
+- `to(name, design, callback): T` — executes a cached transformation callback for a specific design.
+- `toAll(name, callback): T` — orchestrates a global cached transformation across all registered designs.
+
+## Operations
+
+### The Environmental Discovery & Caching Flow
+
+`PropertiesPath` manages the mapping between high-level logic and physical storage:
+1. **Directory Aggregation**: Upon instantiation, the class normalizes design names to kebab-case and uses internal `getDir` logic to synthesize absolute paths to `UI_DIRS_TOKENS` and `UI_DIRS_COMPONENTS`.
+2. **Design Isolation**: The class distinguishes between standard themes and the `_constructor`. If a design is marked as a constructor, standard directory discovery is bypassed to allow for specialized base-layer processing.
+3. **Cached Transformation**: When `to()` or `toAll()` are called, the class doesn't just return paths—it attempts to retrieve previously processed data from `PropertiesCache`. If a cache miss occurs, the provided callback is executed with the resolved paths, and the new result is transparently stored.
+4. **Unified Hierarchy Synthesis**: Through `toAll()`, the class enables the "merge-up" pattern, where tokens from multiple designs (e.g., `constructor` + `basic` + `local-theme`) are fetched in sequence and combined into a single hierarchical structure using `replaceRecursive`.

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

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesPath - Резолвер путей и окружения'/>
+
+# Класс PropertiesPath
+
+Класс `PropertiesPath` — это основная утилита, отвечающая за преобразование абстрактных идентификаторов дизайна в конкретные физические пути файловой системы. Он управляет сопоставлением директорий как для глобальных токенов дизайна, так и для специфических переопределений компонентов, гарантируя согласованность обнаружения путей на разных платформах. Предоставляя кэшированные методы обхода, такие как `to` и `toAll`, он координирует последовательность загрузки данных для многотемных проектов, выступая в качестве основного источника информации об окружении для движка свойств.
+
+## Ключевые особенности
+
+- **Сопоставление нескольких дизайнов** — автоматически сопоставляет массив названий дизайнов с соответствующими директориями токенов и компонентов.
+- **Кроссплатформенное обнаружение корня** — использует `PropertiesFile` для обеспечения абсолютности путей и их правильного разрешения в различных операционных системах.
+- **Внутренняя оптимизация (кэширование)** — интегрирован с `PropertiesCache` для минимизации избыточных обращений к файловой системе во время сложных конвейеров трансформации токенов.
+- **Определение режима конструктора** — идентифицирует и обрабатывает специальный дизайн `_constructor`, который служит общей базой для всех тем.
+- **Гибкий обход данных** — предоставляет высокоуровневые обратные вызовы для обработки файлов дизайна без раскрытия деталей работы с файловой системой.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PropertiesPath(designs)`.
+
+**Параметры:**
+- `designs: string[]` — список названий дизайнов, соответствующих именам папок в структуре проекта.
+
+```typescript
+import { PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Определение дизайнов для управления
+const activeDesigns = ['basic', 'constructor', 'premium']
+
+// 2. Создание экземпляра резолвера путей
+const pathResolver = new PropertiesPath(activeDesigns)
+
+// 3. Получение путей для конкретного дизайна
+const basicPaths = pathResolver.getPath('basic')
+```
+
+## Методы
+
+- `isConstructor(): boolean` — проверяет, включает ли текущее окружение базовый дизайн конструктора.
+- `getDesigns(): string[]` — возвращает список названий дизайнов, зарегистрированных в экземпляре.
+- `getPath(name): PropertiesPathItem` — извлекает специфические пути (глобальные и компоненты) для данного дизайна.
+- `getPaths(): PropertiesPathList` — возвращает полный реестр сопоставлений дизайнов и путей.
+- `to(name, design, callback): T` — выполняет кэшированный обратный вызов трансформации для конкретного дизайна.
+- `toAll(name, callback): T` — координирует глобальную кэшированную трансформацию для всех зарегистрированных дизайнов.
+
+## Операции
+
+### Поток обнаружения окружения и кэширования
+
+`PropertiesPath` управляет сопоставлением между высокоуровневой логикой и физическим хранилищем:
+1. **Агрегация директорий**: При создании экземпляра класс нормализует названия дизайнов в kebab-case и использует внутреннюю логику `getDir` для синтеза абсолютных путей к `UI_DIRS_TOKENS` и `UI_DIRS_COMPONENTS`.
+2. **Изоляция дизайна**: Класс различает стандартные темы и `_constructor`. Если дизайн помечен как конструктор, стандартное обнаружение директорий обходится для обеспечения специализированной обработки базового слоя.
+3. **Кэшированная трансформация**: При вызове `to()` или `toAll()` класс не просто возвращает пути — он пытается получить ранее обработанные данные из `PropertiesCache`. Если данные в кэше отсутствуют, выполняется предоставленный callback с разрешенными путями, а новый результат прозрачно сохраняется.
+4. **Синтез унифицированной иерархии**: Через `toAll()` класс реализует паттерн «слияния вверх», когда токены из нескольких дизайнов (например, `constructor` + `basic` + `local-theme`) извлекаются последовательно и объединяются в единую иерархическую структуру с помощью `replaceRecursive`.

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

@@ -0,0 +1,54 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesPath - Bộ phân giải Đường dẫn & Môi trường'/>
+
+# Lớp PropertiesPath
+
+Lớp `PropertiesPath` là một tiện ích cốt lõi chịu trách nhiệm chuyển đổi các định danh thiết kế trừu tượng thành các đường dẫn vật lý thực tế trên hệ thống tệp. Nó quản lý việc ánh xạ thư mục cho cả token thiết kế toàn cầu và các ghi đè thành phần cụ thể, đảm bảo việc khám phá đường dẫn đa nền tảng luôn nhất quán. Bằng cách cung cấp các phương thức duyệt kề (traversal) có lưu bộ nhớ đệm (cached) như `to` và `toAll`, nó điều phối chuỗi tải dữ liệu cho các dự án đa chủ đề, đóng vai trò là nguồn thông tin môi trường chính cho engine thuộc tính.
+
+## Các tính năng chính
+
+- **Ánh xạ Đa thiết kế** — Tự động ánh xạ một mảng tên thiết kế tới các thư mục token và thành phần tương ứng của chúng.
+- **Khám phá Gốc đa nền tảng** — Cung cấp `PropertiesFile` để đảm bảo các đường dẫn là tuyệt đối và được phân giải chính xác trên các hệ điều hành khác nhau.
+- **Tối ưu hóa Nội bộ (Caching)** — Tích hợp với `PropertiesCache` để giảm thiểu việc truy cập hệ thống tệp dư thừa trong các quy trình chuyển đổi token phức tạp.
+- **Phát hiện Chế độ Constructor** — Xác định và xử lý thiết kế đặc biệt `_constructor`, đóng vai trò là cơ sở chung cho tất cả các chủ đề.
+- **Duyệt dữ liệu linh hoạt** — Cung cấp các lệnh gọi lại (callbacks) cấp cao để xử lý các tệp thiết kế mà không để lộ các chi tiết thô của hệ thống tệp.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesPath(designs)`.
+
+**Tham số:**
+- `designs: string[]` — một danh sách các tên thiết kế tương ứng với tên thư mục trong cấu trúc dự án.
+
+```typescript
+import { PropertiesPath } from '@dxtmisha/scripts'
+
+// 1. Xác định các thiết kế cần quản lý
+const activeDesigns = ['basic', 'constructor', 'premium']
+
+// 2. Tạo thực thể bộ phân giải đường dẫn
+const pathResolver = new PropertiesPath(activeDesigns)
+
+// 3. Phân giải đường dẫn cho một thiết kế cụ thể
+const basicPaths = pathResolver.getPath('basic')
+```
+
+## Các phương thức
+
+- `isConstructor(): boolean` — kiểm tra xem môi trường hiện tại có bao gồm thiết kế constructor cơ sở hay không.
+- `getDesigns(): string[]` — trả về danh sách tên thiết kế được đăng ký trong thực thể.
+- `getPath(name): PropertiesPathItem` — truy xuất các đường dẫn cụ thể (toàn cầu và thành phần) cho một thiết kế nhất định.
+- `getPaths(): PropertiesPathList` — trả về bản đăng ký đầy đủ của các ánh xạ từ thiết kế đến đường dẫn.
+- `to(name, design, callback): T` — thực thi một lệnh gọi lại chuyển đổi có lưu bộ nhớ đệm cho một thiết kế cụ thể.
+- `toAll(name, callback): T` — điều phối một quá trình chuyển đổi toàn cầu có lưu bộ nhớ đệm trên tất cả các thiết kế đã đăng ký.
+
+## Các thao tác (Operations)
+
+### Luồng Khám phá Môi trường & Lưu bộ nhớ đệm
+
+`PropertiesPath` quản lý việc ánh xạ giữa logic cấp cao và lưu trữ vật lý:
+1. **Tổng hợp thư mục**: Khi khởi tạo, lớp chuẩn hóa tên thiết kế thành kiểu kebab-case và sử dụng logic `getDir` nội bộ để tổng hợp các đường dẫn tuyệt đối đến `UI_DIRS_TOKENS` và `UI_DIRS_COMPONENTS`.
+2. **Cô lập Thiết kế**: Lớp phân biệt giữa các chủ đề tiêu chuẩn và `_constructor`. Nếu một thiết kế được đánh dấu là constructor, việc khám phá thư mục tiêu chuẩn sẽ bị bỏ qua để cho phép xử lý lớp cơ sở chuyên biệt.
+3. **Chuyển đổi có lưu bộ nhớ đệm**: Khi `to()` hoặc `toAll()` được gọi, lớp không chỉ trả về các đường dẫn — nó còn cố gắng lấy dữ liệu đã xử lý trước đó từ `PropertiesCache`. Nếu xảy ra tình trạng không tìm thấy trong bộ nhớ đệm (cache miss), lệnh gọi lại được cung cấp sẽ được thực thi với các đường dẫn đã phân giải và kết quả mới sẽ được lưu trữ một cách minh bạch.
+4. **Tổng hợp Hệ thống phân cấp Thống nhất**: Thông qua `toAll()`, lớp cho phép mẫu "hợp nhất ngược" (merge-up), trong đó các token từ nhiều thiết kế (ví dụ: `constructor` + `basic` + `local-theme`) được tải theo chuỗi và kết hợp thành một cấu trúc phân cấp duy nhất bằng `replaceRecursive`.

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

@@ -0,0 +1,74 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesScss - SCSS Generation'/>
+
+# PropertiesScss Class
+
+The `PropertiesScss` class is responsible for transforming design system tokens and properties into a structured SCSS format. The resulting code is used to integrate design variables into the library's stylesheets, ensuring synchronization between JSON definitions and Sass variables.
+
+## Key Features
+
+- **Automated Code Generation** — creates a complete SCSS structure for integration into stylesheets.
+- **Mixin Integration** — generates calls to special mixins (`setDesignsDesigns`, `setDesignsRoot`, etc.) for automatic configuration.
+- **Media Query Support** — transforms device sizes into an SCSS map.
+- **Palette Processing** — generates lists of utilized colors and saturation levels.
+- **Smart Formatting** — correctly handles value types (colors, dimensions, links) to match SCSS syntax.
+
+## Initialization
+
+To initialize the SCSS generator, pass a `PropertiesItems` instance to the constructor.
+
+**Parameters:**
+- `items: PropertiesItems` — the manager object for all property elements.
+
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(tokenData)
+const generator = new PropertiesScss(manager)
+```
+
+## Methods
+
+### `get`
+Returns a complete, formatted SCSS string ready to be written to a file. This string includes imports of core style variables and sequential mixin calls to register designs, root properties, media queries, classes, and the palette.
+
+**Returns:** `string` — the full text of the SCSS file.
+
+```typescript
+const scssContent = generator.get();
+// Result: "@use \"@dxtmisha/styles\" as variables; \n @include variables.setDesignsDesigns(...)"
+```
+
+### `getProperties`
+Generates a specialized SCSS map structure for all properties defined in the system. This method focuses on common tokens (variables) that should be available in the global CSS/SCSS scope.
+
+**Returns:** `string` — an SCSS snippet with a call to the `setDesignsProperties` mixin.
+
+```typescript
+const propertyMap = generator.getProperties();
+```
+
+## Operations
+
+### The SCSS Generation Process
+
+`PropertiesScss` performs a multi-stage data transformation:
+1. **Design Collection**: Identifies all active designs and forms a list for the `setDesignsDesigns` mixin.
+2. **Category Analysis**: Distributes properties by category (root, class, theme) to generate the corresponding blocks.
+3. **Palette Resolution**: Uses `PropertiesPalette` to obtain a list of actually used colors and saturation steps.
+4. **Value Parsing**: The `getValueItem` method checks each value against SCSS types (strings are quoted, HEX codes and dimensions with units remain unquoted).
+5. **Structure Assembly**: Forms nested SCSS maps, observing correct indentation and delimiters to ensure valid Sass code.
+
+## Examples
+
+### Full Generation Cycle
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const items = new PropertiesItems(data)
+const scss = new PropertiesScss(items)
+
+// Get the ready code for writing to variables.scss
+const fileData = scss.get()
+```

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

@@ -0,0 +1,74 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesScss - Генерация SCSS'/>
+
+# Класс PropertiesScss
+
+Класс `PropertiesScss` отвечает за преобразование токенов и свойств дизайн-системы в структурированный SCSS-код. Полученный код используется для интеграции переменных дизайна в стили библиотеки, обеспечивая синхронизацию между JSON-определениями и Sass-переменными.
+
+## Ключевые особенности
+
+- **Автоматическая кодогенерация** — создание полной SCSS-структуры для подключения в стили.
+- **Интеграция с миксинами** — генерирует вызовы специальных миксинов (`setDesignsDesigns`, `setDesignsRoot` и др.) для автоматической настройки.
+- **Поддержка медиа-запросов** — преобразует размеры устройств в SCSS-карту.
+- **Обработка палитры** — генерирует списки используемых цветов и уровней насыщенности.
+- **Умное форматирование** — корректно обрабатывает типы значений (цвета, размеры, ссылки) для соответствия синтаксису SCSS.
+
+## Инициализация
+
+Для инициализации генератора SCSS передайте экземпляр `PropertiesItems` в конструктор.
+
+**Параметры:**
+- `items: PropertiesItems` — объект управления всеми элементами свойств.
+
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(tokenData)
+const generator = new PropertiesScss(manager)
+```
+
+## Методы
+
+### `get`
+Возвращает полную отформатированную строку SCSS, готовую к записи в файл. Эта строка включает в себя импорт основных переменных стилей и последовательные вызовы миксинов для регистрации дизайнов, корневых свойств, медиа-запросов, классов и палитры.
+
+**Возвращает:** `string` — полный текст SCSS файла.
+
+```typescript
+const scssContent = generator.get();
+// Результат: "@use \"@dxtmisha/styles\" as variables; \n @include variables.setDesignsDesigns(...)"
+```
+
+### `getProperties`
+Генерирует специализированную структуру карты SCSS для всех свойств, определенных в системе. Этот метод фокусируется на общих токенах (переменных), которые должны быть доступны в глобальной области видимости CSS/SCSS.
+
+**Возвращает:** `string` — фрагмент SCSS с вызовом миксина `setDesignsProperties`.
+
+```typescript
+const propertyMap = generator.getProperties();
+```
+
+## Операции
+
+### Процесс генерации SCSS
+
+`PropertiesScss` выполняет многоэтапную трансформацию данных:
+1. **Сбор дизайнов**: Идентифицирует все активные дизайны и формирует список для миксина `setDesignsDesigns`.
+2. **Анализ категорий**: Распределяет свойства по категориям (root, class, theme) для генерации соответствующих блоков.
+3. **Разрешение палитры**: Использует `PropertiesPalette` для получения списка реально используемых цветов и шагов насыщенности.
+4. **Синтаксический анализ значений**: Метод `getValueItem` проверяет каждое значение на соответствие типам SCSS (строки оборачиваются в кавычки, HEX-коды и размеры с единицами измерения остаются без кавычек).
+5. **Сборка структуры**: Формирует вложенные карты (maps) SCSS, соблюдая правильные отступы и разделители для обеспечения валидности Sass-кода.
+
+## Примеры
+
+### Полный цикл генерации
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const items = new PropertiesItems(data)
+const scss = new PropertiesScss(items)
+
+// Получаем готовый код для записи в variables.scss
+const fileData = scss.get()
+```

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

@@ -0,0 +1,74 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesScss - Tạo SCSS'/>
+
+# Lớp PropertiesScss
+
+Lớp `PropertiesScss` chịu trách nhiệm chuyển đổi các token và thuộc tính của hệ thống thiết kế thành cấu trúc SCSS có tổ chức. Mã nguồn kết quả được sử dụng để tích hợp các biến thiết kế vào bảng kiểu của thư viện, đảm bảo sự đồng bộ giữa các định nghĩa JSON và các biến Sass.
+
+## Các tính năng chính
+
+- **Tự động tạo mã** — tạo một cấu trúc SCSS hoàn chỉnh để tích hợp vào các bảng kiểu.
+- **Tích hợp Mixin** — tạo các lệnh gọi đến các mixin đặc biệt (`setDesignsDesigns`, `setDesignsRoot`, v.v.) để cấu hình tự động.
+- **Hỗ trợ Media Query** — chuyển đổi kích thước thiết bị thành một bảng (map) SCSS.
+- **Xử lý Bảng màu (Palette)** — tạo danh sách các màu sắc được sử dụng và các mức độ bão hòa.
+- **Định dạng Thông minh** — xử lý chính xác các loại giá trị (màu sắc, kích thước, liên kết) để phù hợp với cú pháp SCSS.
+
+## Khởi tạo
+
+Để khởi tạo trình tạo SCSS, hãy truyền một thực thể `PropertiesItems` vào hàm khởi tạo.
+
+**Tham số:**
+- `items: PropertiesItems` — đối tượng quản lý cho tất cảnh các thành phần thuộc tính.
+
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const manager = new PropertiesItems(tokenData)
+const generator = new PropertiesScss(manager)
+```
+
+## Các phương thức
+
+### `get`
+Trả về một chuỗi SCSS đã được định dạng đầy đủ, sẵn sàng để ghi vào tệp. Chuỗi này bao gồm việc nhập các biến kiểu cốt lõi và các lệnh gọi mixin tuần tự để đăng ký các thiết kế, thuộc tính gốc, truy vấn phương tiện, các lớp và bảng màu.
+
+**Trả về:** `string` — toàn bộ nội dung của tệp SCSS.
+
+```typescript
+const scssContent = generator.get();
+// Kết quả: "@use \"@dxtmisha/styles\" as variables; \n @include variables.setDesignsDesigns(...)"
+```
+
+### `getProperties`
+Tạo một cấu trúc bảng SCSS chuyên biệt cho tất cả các thuộc tính được định nghĩa trong hệ thống. Phương thức này tập trung vào các token (biến) chung nên có sẵn trong phạm vi CSS/SCSS toàn cục.
+
+**Trả về:** `string` — một đoạn mã SCSS với lệnh gọi đến mixin `setDesignsProperties`.
+
+```typescript
+const propertyMap = generator.getProperties();
+```
+
+## Các thao tác (Operations)
+
+### Quy trình tạo SCSS
+
+`PropertiesScss` thực hiện chuyển đổi dữ liệu qua nhiều giai đoạn:
+1. **Thu thập Thiết kế**: Xác định tất cả các thiết kế đang hoạt động và tạo danh sách cho mixin `setDesignsDesigns`.
+2. **Phân tích Danh mục**: Phân phối các thuộc tính theo danh mục (root, class, theme) để tạo các khối tương ứng.
+3. **Phân giải Bảng màu**: Sử dụng `PropertiesPalette` để lấy danh sách các màu sắc và các bước bão hòa thực tế được sử dụng.
+4. **Phân tích Giá trị**: Phương thức `getValueItem` kiểm tra từng giá trị so với các loại SCSS (chuỗi được đặt trong dấu ngoặc kép, mã HEX và kích thước có đơn vị được giữ nguyên không dùng ngoặc kép).
+5. **Lắp ráp Cấu trúc**: Tạo các bảng SCSS lồng nhau, tuân thủ thụt lề và dấu phân cách chính xác để đảm bảo mã Sass hợp lệ.
+
+## Ví dụ (Examples)
+
+### Chu kỳ tạo mã đầy đủ
+```typescript
+import { PropertiesItems, PropertiesScss } from '@dxtmisha/scripts'
+
+const items = new PropertiesItems(data)
+const scss = new PropertiesScss(items)
+
+// Lấy mã đã sẵn sàng để ghi vào variables.scss
+const fileData = scss.get()
+```

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

@@ -0,0 +1,93 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesSeparator - Property Splitting'/>
+
+# PropertiesSeparator Class
+
+The `PropertiesSeparator` class is designed to automatically transform a flat structure of tokens with composite names (using separators) into a hierarchical structure of nested objects. This allows for logical property organization, such as turning `button.primary.background` into `{ button: { primary: { background: ... } } }`.
+
+## Key Features
+
+- **Automatic Nesting** — transforms flat keys with separators (default is `.`) into nested objects.
+- **Recursive Processing** — supports unlimited nesting depth (with an optional limit via configuration).
+- **Smart Merging** — correctly merges new sub-properties with existing objects using recursive replacement.
+- **Name Cleaning** — automatically removes technical prefixes and suffixes (e.g., separator basic names) before processing.
+
+## Initialization
+
+The class provides static methods, so it does not need to be initialized via `new`.
+
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+// Using static methods
+const results = PropertiesSeparator.to(rawProperties)
+```
+
+## Methods
+
+### `is`
+A static method to quickly check if the provided property list contains any keys that require splitting. It scans the top level (and nested levels up to the `limit`) for separator characters in the names.
+
+**Parameters:**
+- `properties: PropertyList` — the list of properties to analyze.
+- `limit: number` — the maximum depth of the check (default is taken from `PropertiesConfig`).
+
+**Returns:** `boolean` — `true` if at least one key contains a separator.
+
+```typescript
+const needsSplitting = PropertiesSeparator.is(myProperties);
+// Result: true if keys like "color.blue.50" exist
+```
+
+### `to`
+A static method that performs the actual transformation of a flat property list into a nested structure. The method recursively traverses all elements and, if it finds a key with a separator, "wraps" the property into a chain of nested objects according to the name segments.
+
+**Parameters:**
+- `properties: PropertyList` — the list of properties to transform.
+
+**Returns:** `PropertyList` — a new property list with a hierarchical structure.
+
+```typescript
+const nestedProperties = PropertiesSeparator.to({
+  'palette.blue.50': { value: '#e3f2fd' }
+});
+/* Result:
+{
+  palette: {
+    value: {
+      blue: {
+        value: {
+          '50': { value: '#e3f2fd', __wrap: true }
+        }
+      }
+    }
+  }
+}
+*/
+```
+
+## Operations
+
+### The Name Splitting Mechanism
+
+The transformation process in `PropertiesSeparator` involves several steps:
+1. **Separator Detection**: The `to` method checks each property name via `PropertiesKeys.isSeparator`.
+2. **Segmentation**: If a separator is found, the name is split into parts (e.g., `a.b.c` -> `['a', 'b', 'c']`). Technical characters are removed beforehand via `removeBasicName`.
+3. **Wrapping**: The `wrap` method recursively creates nested `value` objects, placing the original property element at the deepest level. Intermediate objects are marked with `__wrap: true` to indicate their structural nature.
+4. **Recursive Merging**: The resulting "branch" is merged with the main `data` object via `replaceRecursive`, allowing multiple properties with the same base (e.g., `blue.50` and `blue.100`) to correctly aggregate under a single `blue` object.
+
+## Examples
+
+### Grouping Palette Colors
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+const flatPalette = {
+  'blue.50': { value: '#eef' },
+  'blue.100': { value: '#ccf' }
+}
+
+const tree = PropertiesSeparator.to(flatPalette)
+// Properties are now grouped in the tree.blue.value object
+```