@dxtmisha/wiki 0.39.4 → 0.39.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/dist/WikiStorybookDescriptions-IKMchHA-.js +26959 -0
  2. package/dist/library.d.ts +0 -2
  3. package/dist/library.js +76 -35617
  4. package/dist/media.d.ts +2 -0
  5. package/dist/media.js +5523 -0
  6. package/dist/storybook.js +13 -0
  7. package/dist/storybookTypes-RNr8gPGw.js +8 -0
  8. package/dist/wikiDescriptions-Cv4WzSNL.js +2782 -0
  9. package/package.json +14 -12
  10. package/src/library.ts +0 -4
  11. package/src/media/functional/ui/properties/about/about.en.mdx +13 -12
  12. package/src/media/functional/ui/properties/about/about.ru.mdx +13 -12
  13. package/src/media/functional/ui/properties/about/about.vi.mdx +13 -12
  14. package/src/media/functional/ui/properties/quick-start/quick-start.en.mdx +62 -32
  15. package/src/media/functional/ui/properties/quick-start/quick-start.ru.mdx +62 -32
  16. package/src/media/functional/ui/properties/quick-start/quick-start.vi.mdx +62 -32
  17. package/src/media/functional/ui/properties/type-media/type-media.en.mdx +29 -0
  18. package/src/media/functional/ui/properties/type-media/type-media.ru.mdx +29 -0
  19. package/src/media/functional/ui/properties/type-media/type-media.vi.mdx +29 -0
  20. package/src/assets/demo/demo-pdf.pdf +0 -0
  21. package/src/assets/image/image-1.jpeg +0 -0
  22. package/src/assets/image/image-2.jpeg +0 -0
  23. package/src/assets/image/phone-1.png +0 -0
  24. package/src/assets/image/phone-2.png +0 -0
  25. package/src/assets/image/phone-3.png +0 -0
  26. package/src/documentation/storybook/StorybookDescriptions.tsx +0 -25
  27. package/src/documentation/storybook/StorybookMain.tsx +0 -28
  28. package/src/media.ts +0 -15
  29. package/src/storybook.tsx +0 -4
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@dxtmisha/wiki",
3
3
  "private": false,
4
- "version": "0.39.4",
4
+ "version": "0.39.6",
5
5
  "type": "module",
6
6
  "description": "Wiki documentation and storybook utilities for DXT UI design system",
7
7
  "keywords": [
@@ -30,16 +30,12 @@
30
30
  "build": "vue-tsc -b && vite build",
31
31
  "preview": "vite preview",
32
32
  "prepublishOnly": "npm run build",
33
- "publish": "npm publish --access public"
33
+ "publish-to-npm": "npm publish --access public"
34
34
  },
35
35
  "files": [
36
36
  "dist",
37
- "src/assets",
38
- "src/documentation",
39
37
  "src/media/functional",
40
- "src/styles/storybookStyle.scss",
41
- "src/media.ts",
42
- "src/storybook.tsx",
38
+ "src/styles",
43
39
  "README.md",
44
40
  "package.json",
45
41
  "LICENSE"
@@ -52,11 +48,16 @@
52
48
  "import": "./dist/library.js",
53
49
  "types": "./dist/library.d.ts"
54
50
  },
55
- "./media": "./src/media.ts",
51
+ "./media": {
52
+ "import": "./dist/media.js",
53
+ "types": "./dist/media.d.ts"
54
+ },
56
55
  "./functional/*": "./src/media/functional/*.mdx",
57
- "./storybook": "./src/storybook.tsx",
58
- "./storybook/styles": "./src/styles/storybookStyle.scss",
59
- "./package.json": "./package.json"
56
+ "./storybook": {
57
+ "import": "./dist/storybook.js",
58
+ "types": "./dist/storybook.d.ts"
59
+ },
60
+ "./storybook/styles": "./src/styles/storybookStyle.scss"
60
61
  },
61
62
  "engines": {
62
63
  "node": ">=20.0.0"
@@ -64,10 +65,11 @@
64
65
  "peerDependencies": {
65
66
  "@dxtmisha/functional": "*",
66
67
  "@dxtmisha/media": "*",
68
+ "@dxtmisha/styles": "*",
67
69
  "@storybook/addon-docs": "*",
68
70
  "@mdx-js/react": "*",
69
71
  "react": "*",
70
72
  "vue": "*"
71
73
  },
72
74
  "dependencies": {}
73
- }
75
+ }
package/src/library.ts CHANGED
@@ -7,7 +7,3 @@ export * from './classes/WikiStorybookProp'
7
7
  // Types
8
8
  export * from './types/storybookTypes'
9
9
  export * from './types/wikiTypes'
10
-
11
- // Media
12
- export * from './media/props/wiki'
13
- export * from './media/descriptions/wikiDescriptions'
@@ -1,20 +1,21 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/en/# UI/properties/! About the module'/>
3
+ <Meta title='@dxtmisha/en/# UI/properties/! About properties.json'/>
4
4
 
5
- # Properties
5
+ # Configuration (properties.json)
6
6
 
7
- The `Properties` module is designed for declarative management of design system styles using JSON configurations. Component developers no longer need to manually write SCSS code for states, media queries, and variables—instead, all design tokens are described in a `properties.json` file.
7
+ The `properties.json` file is a declarative manifest of your component. In it, you describe the structure, styles, states, and parameters, which are then automatically transformed into production-ready SCSS code and typed TypeScript interfaces (`props.ts`).
8
8
 
9
- ## Why do we need this file?
9
+ ## How to work with this file?
10
10
 
11
- In every scalable UI component library, there is a common problem of managing spacing, colors, and states (hover, focus, disabled). Creating a `properties.json` file allows to:
12
- - Centralize all tokens in one clear place next to the component.
13
- - Automatically generate typed props for Vue/React from it.
14
- - Obtain ready-to-use SCSS classes, variables, and themes without code duplication.
11
+ Instead of manually writing hundreds of lines of CSS for every pseudo-class or media query, you populate a **property tree**. The system analyzes this file and performs all the routine work for you:
12
+ - **Style Generation (SCSS)**: Creates BEM-style classes, variables, and themes.
13
+ - **Interface Generation (Props)**: Forms public component properties for Vue/React.
14
+ - **Synchronization**: Ensures that styles and the programmatic interface always correspond to each other.
15
15
 
16
- ## Core Concepts
16
+ ## Core Concept
17
17
 
18
- - **Token**: A unit of style in the configuration object.
19
- - **Nesting**: The JSON structure determines the nesting of descendant CSS classes.
20
- - **Typing**: The JSON configuration is strictly divided by types: `var`, `state`, `media`, etc., which tells the generator exactly how the token will work in the output.
18
+ 1. **Tokens**: JSON tree nodes representing specific CSS properties or nested objects.
19
+ 2. **Types & Flags (_type, _var...)**: Service parameters defining the node processing logic (generating variables, states, or exporting to Props).
20
+ 3. **Links**: The `{...}` system for inheriting values from other tokens or global design variables.
21
+ 4. **Markers & Shortcuts**: Special prefixes (`~`, `group|`) and link placeholders (`?`, `??`) that accelerate the creation of complex configurations.
@@ -1,20 +1,21 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/ru/# UI/properties/! О модуле'/>
3
+ <Meta title='@dxtmisha/ru/# UI/properties/! О файле properties.json'/>
4
4
 
5
- # Properties
5
+ # Конфигурация (properties.json)
6
6
 
7
- Модуль `Properties` служит для декларативного управления стилями дизайн-системы с помощью JSON-конфигураций. Разработчику компонентов больше не нужно вручную прописывать SCSS-код для состояний, медиа-запросов и переменных вместо этого все дизайн-токены описываются в файле `properties.json`.
7
+ Файл `properties.json` является декларативным манифестом вашего компонента. В нем вы описываете структуру, стили, состояния и параметры, которые затем автоматически преобразуются в готовый SCSS-код и типизированные TypeScript-интерфейсы (`props.ts`).
8
8
 
9
- ## Для чего нужен этот файл?
9
+ ## Как работать с этим файлом?
10
10
 
11
- В каждой масштабируемой библиотеке UI-компонентов присутствует общая проблема управления отступами, цветами и состояниями (hover, focus, disabled). Создание файла `properties.json` позволяет:
12
- - Централизовать все токены в одном понятном месте рядом с компонентом.
13
- - Автоматически генерировать из него типизированные пропсы для Vue/React.
14
- - Получать готовые SCSS-классы, переменные и темы без дублирования кода.
11
+ Вместо того чтобы вручную писать сотни строк CSS для каждого псевдокласса или медиа-запроса, вы наполняете **дерево свойств**. Система анализирует этот файл и выполняет всю рутинную работу:
12
+ - **Генерация стилей (SCSS)**: Создает классы по методологии BEM, переменные и темы.
13
+ - **Генерация интерфейса (Props)**: Формирует публичные свойства компонента для Vue/React.
14
+ - **Синхронизация**: Гарантирует, что стили и программный интерфейс всегда соответствуют друг другу.
15
15
 
16
- ## Основные концепции
16
+ ## Основная концепция
17
17
 
18
- - **Токен**: Единица стиля в объекте конфигурации.
19
- - **Вложенность**: Структура JSON определяет вложенность CSS классов-потомков.
20
- - **Типизация**: JSON-конфигурация строго разделена по типам: `var`, `state`, `media` и т.д., что подсказывает генератору, как именно будет работать токен на выходе.
18
+ 1. **Токены (Tokens)**: Узлы дерева JSON, описывающие конкретные CSS-свойства или вложенные объекты.
19
+ 2. **Типы и Флаги (_type, _var...)**: Служебные параметры, определяющие логику обработки узла (генерация переменной, состояния или экспорт в Props).
20
+ 3. **Ссылки (Links)**: Система `{...}`, позволяющая заимствовать значения из других токенов или глобальных переменных дизайна.
21
+ 4. **Маркеры и Шорткаты**: Специальные префиксы (`~`, `group|`) и подстановки (`?`, `??`), ускоряющие написание сложных конфигураций.
@@ -1,20 +1,21 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/vi/# UI/properties/! Về module'/>
3
+ <Meta title='@dxtmisha/vi/# UI/properties/! Về properties.json'/>
4
4
 
5
- # Properties
5
+ # Cấu hình (properties.json)
6
6
 
7
- Module `Properties` phục vụ cho việc quản lý khai báo các style của hệ thống thiết kế thông qua cấu hình JSON. Nhờ đó, người phát triển component không còn phải code SCSS cho các trạng thái, media-query hay biến theo cách thủ công thay vào đó, toàn bộ design-token được khai báo tại tệp `properties.json`.
7
+ Tệp `properties.json` bản tuyên ngôn khai báo cho thành phần của bạn. Trong đó, bạn tả cấu trúc, kiểu dáng, trạng thái tham số, sau đó chúng sẽ tự động được chuyển đổi thành SCSS hoàn chỉnh các giao diện TypeScript kiểu dữ liệu (`props.ts`).
8
8
 
9
- ## Tại sao cần tệp này?
9
+ ## Làm thế nào để làm việc với tệp này?
10
10
 
11
- Trong bất thư viện UI component quy nào, vấn đề phổ biến nhất quản khoảng cách, màu sắctrạng thái (hover, focus, disabled). Tệp cấu hình `properties.json` cho phép:
12
- - Quản tập trung mọi token một cách dễ hiểu nằm ngay cạnh component.
13
- - Tự động sinh ra props chặt chẽ cho Vue/React.
14
- - Lấy SCSS class, biếntheme dựng sẵn không cần lặp code.
11
+ Thay viết hàng trăm dòng CSS thủ công cho mọi pseudo-class hoặc media query, bạn điền vào một **cây thuộc tính**. Hệ thống phân tích tệp này thực hiện mọi công việc lặp đi lặp lại:
12
+ - **Tạo kiểu dáng (SCSS)**: Tạo ra các lớp theo phương pháp BEM, các biến và chủ đề.
13
+ - **Tạo giao diện (Props)**: Hình thành các thuộc tính thành phần công khai cho Vue/React.
14
+ - **Đồng bộ hóa**: Đảm bảo rằng các kiểu dáng giao diện lập trình luôn tương ứng với nhau.
15
15
 
16
- ## Các khái niệm bản
16
+ ## Khái niệm cốt lõi
17
17
 
18
- - **Token**: Đơn vị khai báo style trong cấu hình đối tượng.
19
- - **Tính lồng nhau**: Cấu trúc lồng của JSON sẽ ánh xạ vào các lớp CSS lồng nhau khi render.
20
- - **Phân loại**: Khai báo JSON chia thành nhiều loại: `var`, `state`, `media`, v.v... định hướng chính xác kết quả đầu ra.
18
+ 1. **Token**: Các nút cấp độ JSON tả thuộc tính CSS cụ thể hoặc các đối tượng lồng nhau.
19
+ 2. **Loại Cờ (_type, _var...)**: Các tham số dịch vụ xác định logic xử nút (tạo biến, trạng thái hoặc xuất ra Props).
20
+ 3. **Liên kết (Links)**: Hệ thống `{...}` cho phép kế thừa giá trị từ các token khác hoặc các biến thiết kế toàn cục.
21
+ 4. **Dấu hiệu và Phím tắt**: Các tiền tố đặc biệt (`~`, `group|`) và các trình giữ chỗ liên kết (`?`, `??`) giúp tăng tốc độ viết các cấu hình phức tạp.
@@ -1,78 +1,108 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/en/# UI/properties/Quick start'/>
3
+ <Meta title='@dxtmisha/en/# UI/properties/! Quick start'/>
4
4
 
5
5
  # Quick Start
6
6
 
7
- This guide covers the basics of onboarding your UI components onto the properties generation pipeline via `properties.json`.
7
+ This guide helps you quickly master working with the `properties.json` file using a typical UI component as an example. The file serves as the **single source of truth** — both styles (SCSS) and the programmatic interface (TypeScript Props) are generated from it.
8
8
 
9
- ## 1. Setting Up Base Styles
9
+ ## 1. Base Properties and Tokens
10
10
 
11
- The simplest configuration pattern maps flat JSON keys directly to native CSS attributes. Let's declare standard background and padding values:
11
+ Instead of fixed values (HEX, px), always use the design token system `{sys...}`. This ensures theme support and consistency.
12
12
 
13
13
  ```json
14
14
  {
15
- "background-color": "#cccccc",
16
- "padding": "12px 24px"
15
+ "padding": "{sys.spacing.md}",
16
+ "background-color": "{sys.palette.surface}",
17
+ "border-radius": "{sys.rounded.md}"
17
18
  }
18
19
  ```
19
20
 
20
- During compilation, the pipeline processes this directly into functional SCSS layout classes binding to your setup namespace automatically:
21
+ **Result (SCSS):**
21
22
  ```scss
22
23
  .component {
23
- background-color: #cccccc;
24
- padding: 12px 24px;
24
+ padding: var(--sys-spacing-md);
25
+ background-color: var(--sys-palette-surface);
26
+ border-radius: var(--sys-rounded-md);
25
27
  }
26
28
  ```
27
29
 
28
- ## 2. Emitting CSS Variables
30
+ ## 2. States
29
31
 
30
- Whenever an attribute must be dynamically manipulatable client-side (e.g. for custom scripting or interactive theming modes), utilize an object declaration bearing the `_var: true` flag.
32
+ Use reserved keys to describe interactivity (hover, focus, active, disabled).
31
33
 
32
34
  ```json
33
35
  {
34
- "border-radius": {
35
- "_var": true,
36
- "value": "8px"
36
+ "hover": {
37
+ "background-color": "{sys.palette.surfaceVariant}"
38
+ },
39
+ "disabled": {
40
+ "opacity": "{sys.opacity.disabled}",
41
+ "cursor": "not-allowed"
37
42
  }
38
43
  }
39
44
  ```
40
45
 
41
- Result pipeline mapping:
46
+ **Result (SCSS):**
42
47
  ```scss
43
48
  .component {
44
- --component-border-radius: 8px;
45
- border-radius: var(--component-border-radius);
49
+ &:hover { background-color: var(--sys-palette-surfaceVariant); }
50
+ &:disabled {
51
+ opacity: var(--sys-opacity-disabled);
52
+ cursor: not-allowed;
53
+ }
46
54
  }
47
55
  ```
48
56
 
49
- ## 3. Pseudo-classes and Variations
57
+ ## 3. Modifiers (Marker `~`)
50
58
 
51
- The generator inherently orchestrates logic-grouped structures into valid CSS pseudo-classes or exported modifier variants natively:
59
+ To create a variation of a component (e.g., `primary` or `secondary`), use the `~` prefix. These keys are automatically transformed into **Props** in Vue/React and BEM modifiers in CSS.
52
60
 
53
61
  ```json
54
62
  {
55
- "hover": {
56
- "background-color": "#aaaaaa"
57
- },
58
- "~active": {
59
- "background-color": "#555555"
63
+ "~primary": {
64
+ "color": "{sys.palette.onPrimary}",
65
+ "background-color": "{sys.palette.primary}",
66
+ "_default": true
60
67
  }
61
68
  }
62
69
  ```
63
70
 
64
- Compiled bindings logic:
71
+ **Result (SCSS):**
65
72
  ```scss
66
73
  .component {
67
- &:hover {
68
- background-color: #aaaaaa;
74
+ &--primary {
75
+ color: var(--sys-palette-onPrimary);
76
+ background-color: var(--sys-palette-primary);
69
77
  }
70
-
71
- /* BEM modifier mapped via TypeScript Props */
72
- &--active {
73
- background-color: #555555;
78
+ }
79
+ ```
80
+
81
+ **Result (TypeScript Props):**
82
+ ```typescript
83
+ type PropsToken = {
84
+ primary?: boolean // Generated automatically
85
+ }
86
+ ```
87
+
88
+ ## 4. Custom Variables (`_var`)
89
+
90
+ If you need a property to be available as a CSS variable for external control or use in scripts, add the `_var: true` flag.
91
+
92
+ ```json
93
+ {
94
+ "height": {
95
+ "value": "48px",
96
+ "_var": true
74
97
  }
75
98
  }
76
99
  ```
77
100
 
78
- > **Note:** To leverage deep referencing design tokens (`{sys...}`) and systematic TypeScript props interfaces exports, review the full **Structure description** documentation.
101
+ **Result (SCSS):**
102
+ ```scss
103
+ .component {
104
+ --component-height: 48px;
105
+ height: var(--component-height);
106
+ }
107
+ ```
108
+
@@ -1,78 +1,108 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/ru/# UI/properties/Быстрый старт'/>
3
+ <Meta title='@dxtmisha/ru/# UI/properties/! Быстрый старт'/>
4
4
 
5
5
  # Быстрый старт
6
6
 
7
- Данное руководство демонстрирует основы внедрения кодогенерации для вашего UI-компонента с помощью `properties.json`.
7
+ Данное руководство поможет вам быстро освоить работу с файлом `properties.json` на примере типичного UI-компонента. Файл является **единым источником истины** — из него генерируются как стили (SCSS), так и программный интерфейс (TypeScript Props).
8
8
 
9
- ## 1. Базовые стили
9
+ ## 1. Базовые свойства и токены
10
10
 
11
- Простейшая конфигурация строится на прямом соответствии ключей физическим CSS-свойствам. Добавим базовый фон и отступы:
11
+ Вместо фиксированных значений (HEX, px) всегда используйте систему дизайн-токенов `{sys...}`. Это гарантирует поддержку тем и консистентность.
12
12
 
13
13
  ```json
14
14
  {
15
- "background-color": "#cccccc",
16
- "padding": "12px 24px"
15
+ "padding": "{sys.spacing.md}",
16
+ "background-color": "{sys.palette.surface}",
17
+ "border-radius": "{sys.rounded.md}"
17
18
  }
18
19
  ```
19
20
 
20
- Генератор свойств автоматически сформирует следующий SCSS-класс (название класса выводится из базовых настроек вашей дизайн-системы):
21
+ **Результат (SCSS):**
21
22
  ```scss
22
23
  .component {
23
- background-color: #cccccc;
24
- padding: 12px 24px;
24
+ padding: var(--sys-spacing-md);
25
+ background-color: var(--sys-palette-surface);
26
+ border-radius: var(--sys-rounded-md);
25
27
  }
26
28
  ```
27
29
 
28
- ## 2. Генерация CSS переменных
30
+ ## 2. Состояния (States)
29
31
 
30
- Если вам нужно, чтобы свойство выводилось как динамическая CSS-переменная (например, для использования в скриптах или темах), используйте конфигурационный объект с флагом `_var: true` или `_type: "var"`.
32
+ Для описания интерактивности (hover, focus, active, disabled) используйте зарезервированные ключи.
31
33
 
32
34
  ```json
33
35
  {
34
- "border-radius": {
35
- "_var": true,
36
- "value": "8px"
36
+ "hover": {
37
+ "background-color": "{sys.palette.surfaceVariant}"
38
+ },
39
+ "disabled": {
40
+ "opacity": "{sys.opacity.disabled}",
41
+ "cursor": "not-allowed"
37
42
  }
38
43
  }
39
44
  ```
40
45
 
41
- Результат:
46
+ **Результат (SCSS):**
42
47
  ```scss
43
48
  .component {
44
- --component-border-radius: 8px;
45
- border-radius: var(--component-border-radius);
49
+ &:hover { background-color: var(--sys-palette-surfaceVariant); }
50
+ &:disabled {
51
+ opacity: var(--sys-opacity-disabled);
52
+ cursor: not-allowed;
53
+ }
46
54
  }
47
55
  ```
48
56
 
49
- ## 3. Состояния и модификаторы
57
+ ## 3. Модификаторы (Маркер `~`)
50
58
 
51
- Генератор автоматически транслирует вложенные древовидные структуры в псевдоклассы (состояния) и БЭМ-модификаторы:
59
+ Чтобы создать вариацию компонента (например, `primary` или `secondary`), используйте префикс `~`. Такие ключи автоматически преобразуются в **Props** во Vue/React и в BEM-модификаторы в CSS.
52
60
 
53
61
  ```json
54
62
  {
55
- "hover": {
56
- "background-color": "#aaaaaa"
57
- },
58
- "~active": {
59
- "background-color": "#555555"
63
+ "~primary": {
64
+ "color": "{sys.palette.onPrimary}",
65
+ "background-color": "{sys.palette.primary}",
66
+ "_default": true
60
67
  }
61
68
  }
62
69
  ```
63
70
 
64
- Результат:
71
+ **Результат (SCSS):**
65
72
  ```scss
66
73
  .component {
67
- &:hover {
68
- background-color: #aaaaaa;
74
+ &--primary {
75
+ color: var(--sys-palette-onPrimary);
76
+ background-color: var(--sys-palette-primary);
69
77
  }
70
-
71
- /* БЭМ модификатор для Vue Props */
72
- &--active {
73
- background-color: #555555;
78
+ }
79
+ ```
80
+
81
+ **Результат (TypeScript Props):**
82
+ ```typescript
83
+ type PropsToken = {
84
+ primary?: boolean // Генерируется автоматически
85
+ }
86
+ ```
87
+
88
+ ## 4. Кастомные переменные (`_var`)
89
+
90
+ Если вам нужно, чтобы свойство было доступно как CSS-переменная для внешнего управления или использования в скриптах, добавьте флаг `_var: true`.
91
+
92
+ ```json
93
+ {
94
+ "height": {
95
+ "value": "48px",
96
+ "_var": true
74
97
  }
75
98
  }
76
99
  ```
77
100
 
78
- > **Важно:** Для более сложной конфигурации, работы с дизайн-токенами `{sys...}` и автоматической типизации интерфейса, изучите раздел **Описание структуры**.
101
+ **Результат (SCSS):**
102
+ ```scss
103
+ .component {
104
+ --component-height: 48px;
105
+ height: var(--component-height);
106
+ }
107
+ ```
108
+
@@ -1,78 +1,108 @@
1
1
  import {Meta} from '@storybook/addon-docs/blocks'
2
2
 
3
- <Meta title='@dxtmisha/vi/# UI/properties/Bắt đầu nhanh'/>
3
+ <Meta title='@dxtmisha/vi/# UI/properties/! Bắt đầu nhanh'/>
4
4
 
5
5
  # Bắt đầu nhanh
6
6
 
7
- Hướng dẫn này cung cấp nền tảng thiết lập gen-code bản cho Component UI của bạn thông qua tệp hệ thống `properties.json`.
7
+ Hướng dẫn này giúp bạn nhanh chóng nắm vững cách làm việc với tệp `properties.json` thông qua ví dụ về một UI component điển hình. Tệp này đóng vai trò là **nguồn chân lý duy nhất (single source of truth)** — từ đó cả style (SCSS) và giao diện lập trình (TypeScript Props) đều được tạo ra tự động.
8
8
 
9
- ## 1. Thiết lập CSS cơ bản
9
+ ## 1. Thuộc tính cơ bản và Tokens
10
10
 
11
- Cấu hình dạng cấp trực tiếp dựa dẫm vào gốc thuộc tính HTML CSS thông dụng làm khoá mã. Thiết đặt thử màu nền (background) và tuỳ chỉnh viền viền (padding):
11
+ Thay sử dụng các giá trị cố định (HEX, px), hãy luôn sử dụng hệ thống design token `{sys...}`. Điều này đảm bảo hỗ trợ thay đổi giao diện (themes) và tính nhất quán của thiết kế.
12
12
 
13
13
  ```json
14
14
  {
15
- "background-color": "#cccccc",
16
- "padding": "12px 24px"
15
+ "padding": "{sys.spacing.md}",
16
+ "background-color": "{sys.palette.surface}",
17
+ "border-radius": "{sys.rounded.md}"
17
18
  }
18
19
  ```
19
20
 
20
- Máy biên dịch framework tiến hành trích xuất tự động qua block code hệ quy chiếu SCSS chuẩn của module (khóa parent):
21
+ **Kết quả (SCSS):**
21
22
  ```scss
22
23
  .component {
23
- background-color: #cccccc;
24
- padding: 12px 24px;
24
+ padding: var(--sys-spacing-md);
25
+ background-color: var(--sys-palette-surface);
26
+ border-radius: var(--sys-rounded-md);
25
27
  }
26
28
  ```
27
29
 
28
- ## 2. Khai báo biến CSS Variables Động
30
+ ## 2. Các trạng thái (States)
29
31
 
30
- Để đảm bảo giá trị giao diện thể dễ dàng gọi tự động phục vụ đổi tham số Theme linh động ngay trên client, khai báo cấu trúc theo chuẩn Object mở rộng gắn cờ thuộc tính `_var: true`.
32
+ Sử dụng các khóa đã được quy định sẵn để tả tính tương tác (hover, focus, active, disabled).
31
33
 
32
34
  ```json
33
35
  {
34
- "border-radius": {
35
- "_var": true,
36
- "value": "8px"
36
+ "hover": {
37
+ "background-color": "{sys.palette.surfaceVariant}"
38
+ },
39
+ "disabled": {
40
+ "opacity": "{sys.opacity.disabled}",
41
+ "cursor": "not-allowed"
37
42
  }
38
43
  }
39
44
  ```
40
45
 
41
- Kết quả gen-code block SCSS:
46
+ **Kết quả (SCSS):**
42
47
  ```scss
43
48
  .component {
44
- --component-border-radius: 8px;
45
- border-radius: var(--component-border-radius);
49
+ &:hover { background-color: var(--sys-palette-surfaceVariant); }
50
+ &:disabled {
51
+ opacity: var(--sys-opacity-disabled);
52
+ cursor: not-allowed;
53
+ }
46
54
  }
47
55
  ```
48
56
 
49
- ## 3. Tổ hợp Trạng thái Modifiers BEM
57
+ ## 3. Các biến thể (Dấu hiệu `~`)
50
58
 
51
- Tiến trình phân bổ tự động nội suy nhóm mảng cho phần nhánh cấp thấp thành Pseudo-classes chuột hay các biến thể modifiers class:
59
+ Để tạo ra một biến thể của component (ví dụ: `primary` hoặc `secondary`), hãy sử dụng tiền tố `~`. Các khóa này sẽ tự động được chuyển đổi thành **Props** trong Vue/React các BEM modifiers trong CSS.
52
60
 
53
61
  ```json
54
62
  {
55
- "hover": {
56
- "background-color": "#aaaaaa"
57
- },
58
- "~active": {
59
- "background-color": "#555555"
63
+ "~primary": {
64
+ "color": "{sys.palette.onPrimary}",
65
+ "background-color": "{sys.palette.primary}",
66
+ "_default": true
60
67
  }
61
68
  }
62
69
  ```
63
70
 
64
- Thành phẩm sau quy trình module framework nhận được:
71
+ **Kết quả (SCSS):**
65
72
  ```scss
66
73
  .component {
67
- &:hover {
68
- background-color: #aaaaaa;
74
+ &--primary {
75
+ color: var(--sys-palette-onPrimary);
76
+ background-color: var(--sys-palette-primary);
69
77
  }
70
-
71
- /* Chuỗi BEM modifier tự động chuẩn bị map prop TypeScript */
72
- &--active {
73
- background-color: #555555;
78
+ }
79
+ ```
80
+
81
+ **Kết quả (TypeScript Props):**
82
+ ```typescript
83
+ type PropsToken = {
84
+ primary?: boolean // Được tạo tự động
85
+ }
86
+ ```
87
+
88
+ ## 4. Các biến tùy chỉnh (`_var`)
89
+
90
+ Nếu bạn cần một thuộc tính có sẵn dưới dạng biến CSS để điều khiển từ bên ngoài hoặc sử dụng trong script, hãy thêm cờ `_var: true`.
91
+
92
+ ```json
93
+ {
94
+ "height": {
95
+ "value": "48px",
96
+ "_var": true
74
97
  }
75
98
  }
76
99
  ```
77
100
 
78
- > **Ghi chú quan trọng:** Để phát huy sức mạnh gán biến ảo Token-System format (`{sys...}`) bằng cơ chế kết xuất nhanh Interface Types, bạn hãy tra cứu sâu thư viện **Mô tả cấu trúc**.
101
+ **Kết quả (SCSS):**
102
+ ```scss
103
+ .component {
104
+ --component-height: 48px;
105
+ height: var(--component-height);
106
+ }
107
+ ```
108
+