@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.
- package/dist/WikiStorybookDescriptions-IKMchHA-.js +26959 -0
- package/dist/library.d.ts +0 -2
- package/dist/library.js +76 -35617
- package/dist/media.d.ts +2 -0
- package/dist/media.js +5523 -0
- package/dist/storybook.js +13 -0
- package/dist/storybookTypes-RNr8gPGw.js +8 -0
- package/dist/wikiDescriptions-Cv4WzSNL.js +2782 -0
- package/package.json +14 -12
- package/src/library.ts +0 -4
- package/src/media/functional/ui/properties/about/about.en.mdx +13 -12
- package/src/media/functional/ui/properties/about/about.ru.mdx +13 -12
- package/src/media/functional/ui/properties/about/about.vi.mdx +13 -12
- package/src/media/functional/ui/properties/quick-start/quick-start.en.mdx +62 -32
- package/src/media/functional/ui/properties/quick-start/quick-start.ru.mdx +62 -32
- package/src/media/functional/ui/properties/quick-start/quick-start.vi.mdx +62 -32
- package/src/media/functional/ui/properties/type-media/type-media.en.mdx +29 -0
- package/src/media/functional/ui/properties/type-media/type-media.ru.mdx +29 -0
- package/src/media/functional/ui/properties/type-media/type-media.vi.mdx +29 -0
- package/src/assets/demo/demo-pdf.pdf +0 -0
- package/src/assets/image/image-1.jpeg +0 -0
- package/src/assets/image/image-2.jpeg +0 -0
- package/src/assets/image/phone-1.png +0 -0
- package/src/assets/image/phone-2.png +0 -0
- package/src/assets/image/phone-3.png +0 -0
- package/src/documentation/storybook/StorybookDescriptions.tsx +0 -25
- package/src/documentation/storybook/StorybookMain.tsx +0 -28
- package/src/media.ts +0 -15
- 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
|
+
"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
|
|
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":
|
|
51
|
+
"./media": {
|
|
52
|
+
"import": "./dist/media.js",
|
|
53
|
+
"types": "./dist/media.d.ts"
|
|
54
|
+
},
|
|
56
55
|
"./functional/*": "./src/media/functional/*.mdx",
|
|
57
|
-
"./storybook":
|
|
58
|
-
|
|
59
|
-
|
|
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
|
@@ -1,20 +1,21 @@
|
|
|
1
1
|
import {Meta} from '@storybook/addon-docs/blocks'
|
|
2
2
|
|
|
3
|
-
<Meta title='@dxtmisha/en/# UI/properties/! About
|
|
3
|
+
<Meta title='@dxtmisha/en/# UI/properties/! About properties.json'/>
|
|
4
4
|
|
|
5
|
-
#
|
|
5
|
+
# Configuration (properties.json)
|
|
6
6
|
|
|
7
|
-
The `
|
|
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
|
-
##
|
|
9
|
+
## How to work with this file?
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
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
|
|
16
|
+
## Core Concept
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
#
|
|
5
|
+
# Конфигурация (properties.json)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Файл `properties.json` является декларативным манифестом вашего компонента. В нем вы описываете структуру, стили, состояния и параметры, которые затем автоматически преобразуются в готовый SCSS-код и типизированные TypeScript-интерфейсы (`props.ts`).
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Как работать с этим файлом?
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
11
|
+
Вместо того чтобы вручную писать сотни строк CSS для каждого псевдокласса или медиа-запроса, вы наполняете **дерево свойств**. Система анализирует этот файл и выполняет всю рутинную работу:
|
|
12
|
+
- **Генерация стилей (SCSS)**: Создает классы по методологии BEM, переменные и темы.
|
|
13
|
+
- **Генерация интерфейса (Props)**: Формирует публичные свойства компонента для Vue/React.
|
|
14
|
+
- **Синхронизация**: Гарантирует, что стили и программный интерфейс всегда соответствуют друг другу.
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Основная концепция
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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ề
|
|
3
|
+
<Meta title='@dxtmisha/vi/# UI/properties/! Về properties.json'/>
|
|
4
4
|
|
|
5
|
-
#
|
|
5
|
+
# Cấu hình (properties.json)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Tệp `properties.json` là bản tuyên ngôn khai báo cho thành phần của bạn. Trong đó, bạn mô tả cấu trúc, kiểu dáng, trạng thái và tham số, sau đó chúng sẽ tự động được chuyển đổi thành mã SCSS hoàn chỉnh và các giao diện TypeScript có kiểu dữ liệu (`props.ts`).
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Làm thế nào để làm việc với tệp này?
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
11
|
+
Thay vì 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 và 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 và giao diện lập trình luôn tương ứng với nhau.
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Khái niệm cốt lõi
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
1. **Token**: Các nút cấp độ JSON mô tả thuộc tính CSS cụ thể hoặc các đối tượng lồng nhau.
|
|
19
|
+
2. **Loại và Cờ (_type, _var...)**: Các tham số dịch vụ xác định logic xử lý 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
|
|
3
|
+
<Meta title='@dxtmisha/en/# UI/properties/! Quick start'/>
|
|
4
4
|
|
|
5
5
|
# Quick Start
|
|
6
6
|
|
|
7
|
-
This guide
|
|
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.
|
|
9
|
+
## 1. Base Properties and Tokens
|
|
10
10
|
|
|
11
|
-
|
|
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
|
-
"
|
|
16
|
-
"
|
|
15
|
+
"padding": "{sys.spacing.md}",
|
|
16
|
+
"background-color": "{sys.palette.surface}",
|
|
17
|
+
"border-radius": "{sys.rounded.md}"
|
|
17
18
|
}
|
|
18
19
|
```
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
**Result (SCSS):**
|
|
21
22
|
```scss
|
|
22
23
|
.component {
|
|
23
|
-
|
|
24
|
-
|
|
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.
|
|
30
|
+
## 2. States
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
Use reserved keys to describe interactivity (hover, focus, active, disabled).
|
|
31
33
|
|
|
32
34
|
```json
|
|
33
35
|
{
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
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
|
|
46
|
+
**Result (SCSS):**
|
|
42
47
|
```scss
|
|
43
48
|
.component {
|
|
44
|
-
--
|
|
45
|
-
|
|
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. Modifiers (Marker `~`)
|
|
50
58
|
|
|
51
|
-
|
|
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
|
-
"
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
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
|
+
**Result (SCSS):**
|
|
65
72
|
```scss
|
|
66
73
|
.component {
|
|
67
|
-
|
|
68
|
-
|
|
74
|
+
&--primary {
|
|
75
|
+
color: var(--sys-palette-onPrimary);
|
|
76
|
+
background-color: var(--sys-palette-primary);
|
|
69
77
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
-
Данное руководство
|
|
7
|
+
Данное руководство поможет вам быстро освоить работу с файлом `properties.json` на примере типичного UI-компонента. Файл является **единым источником истины** — из него генерируются как стили (SCSS), так и программный интерфейс (TypeScript Props).
|
|
8
8
|
|
|
9
|
-
## 1. Базовые
|
|
9
|
+
## 1. Базовые свойства и токены
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Вместо фиксированных значений (HEX, px) всегда используйте систему дизайн-токенов `{sys...}`. Это гарантирует поддержку тем и консистентность.
|
|
12
12
|
|
|
13
13
|
```json
|
|
14
14
|
{
|
|
15
|
-
"
|
|
16
|
-
"
|
|
15
|
+
"padding": "{sys.spacing.md}",
|
|
16
|
+
"background-color": "{sys.palette.surface}",
|
|
17
|
+
"border-radius": "{sys.rounded.md}"
|
|
17
18
|
}
|
|
18
19
|
```
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
**Результат (SCSS):**
|
|
21
22
|
```scss
|
|
22
23
|
.component {
|
|
23
|
-
|
|
24
|
-
|
|
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.
|
|
30
|
+
## 2. Состояния (States)
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
Для описания интерактивности (hover, focus, active, disabled) используйте зарезервированные ключи.
|
|
31
33
|
|
|
32
34
|
```json
|
|
33
35
|
{
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
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
|
-
--
|
|
45
|
-
|
|
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
|
-
"
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
68
|
-
|
|
74
|
+
&--primary {
|
|
75
|
+
color: var(--sys-palette-onPrimary);
|
|
76
|
+
background-color: var(--sys-palette-primary);
|
|
69
77
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
9
|
+
## 1. Thuộc tính cơ bản và Tokens
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Thay vì 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
|
-
"
|
|
16
|
-
"
|
|
15
|
+
"padding": "{sys.spacing.md}",
|
|
16
|
+
"background-color": "{sys.palette.surface}",
|
|
17
|
+
"border-radius": "{sys.rounded.md}"
|
|
17
18
|
}
|
|
18
19
|
```
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
**Kết quả (SCSS):**
|
|
21
22
|
```scss
|
|
22
23
|
.component {
|
|
23
|
-
|
|
24
|
-
|
|
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.
|
|
30
|
+
## 2. Các trạng thái (States)
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
Sử dụng các khóa đã được quy định sẵn để mô tả tính tương tác (hover, focus, active, disabled).
|
|
31
33
|
|
|
32
34
|
```json
|
|
33
35
|
{
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
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ả
|
|
46
|
+
**Kết quả (SCSS):**
|
|
42
47
|
```scss
|
|
43
48
|
.component {
|
|
44
|
-
--
|
|
45
|
-
|
|
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. Các biến thể (Dấu hiệu `~`)
|
|
50
58
|
|
|
51
|
-
|
|
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 và các BEM modifiers trong CSS.
|
|
52
60
|
|
|
53
61
|
```json
|
|
54
62
|
{
|
|
55
|
-
"
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
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
|
+
**Kết quả (SCSS):**
|
|
65
72
|
```scss
|
|
66
73
|
.component {
|
|
67
|
-
|
|
68
|
-
|
|
74
|
+
&--primary {
|
|
75
|
+
color: var(--sys-palette-onPrimary);
|
|
76
|
+
background-color: var(--sys-palette-primary);
|
|
69
77
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
101
|
+
**Kết quả (SCSS):**
|
|
102
|
+
```scss
|
|
103
|
+
.component {
|
|
104
|
+
--component-height: 48px;
|
|
105
|
+
height: var(--component-height);
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|