import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/# UI/properties/! Bắt đầu nhanh'/>

# Bắt đầu nhanh

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.

## 1. Thuộc tính cơ bản và Tokens

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ế.

```json
{
  "padding": "{sys.spacing.md}",
  "background-color": "{sys.palette.surface}",
  "border-radius": "{sys.rounded.md}"
}
```

**Kết quả (SCSS):**
```scss
.component {
  padding: var(--sys-spacing-md);
  background-color: var(--sys-palette-surface);
  border-radius: var(--sys-rounded-md);
}
```

## 2. Các trạng thái (States)

Sử dụng các khóa đã được quy định sẵn để mô tả tính tương tác (hover, focus, active, disabled).

```json
{
  "hover": {
    "background-color": "{sys.palette.surfaceVariant}"
  },
  "disabled": {
    "opacity": "{sys.opacity.disabled}",
    "cursor": "not-allowed"
  }
}
```

**Kết quả (SCSS):**
```scss
.component {
  &:hover { background-color: var(--sys-palette-surfaceVariant); }
  &:disabled { 
    opacity: var(--sys-opacity-disabled);
    cursor: not-allowed;
  }
}
```

## 3. Các biến thể (Dấu hiệu `~`)

Để 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.

```json
{
  "~primary": {
    "color": "{sys.palette.onPrimary}",
    "background-color": "{sys.palette.primary}",
    "_default": true
  }
}
```

**Kết quả (SCSS):**
```scss
.component {
  &--primary {
    color: var(--sys-palette-onPrimary);
    background-color: var(--sys-palette-primary);
  }
}
```

**Kết quả (TypeScript Props):**
```typescript
type PropsToken = {
  primary?: boolean // Được tạo tự động
}
```

## 4. Các biến tùy chỉnh (`_var`)

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`.

```json
{
  "height": {
    "value": "48px",
    "_var": true
  }
}
```

**Kết quả (SCSS):**
```scss
.component {
  --component-height: 48px;
  height: var(--component-height);
}
```

