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

<Meta title='@dxtmisha/en/# UI/properties/! Quick start'/>

# Quick Start

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.

## 1. Base Properties and Tokens

Instead of fixed values (HEX, px), always use the design token system `{sys...}`. This ensures theme support and consistency.

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

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

## 2. States

Use reserved keys to describe interactivity (hover, focus, active, disabled).

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

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

## 3. Modifiers (Marker `~`)

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.

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

**Result (SCSS):**
```scss
.component {
  &--primary {
    color: var(--sys-palette-onPrimary);
    background-color: var(--sys-palette-primary);
  }
}
```

**Result (TypeScript Props):**
```typescript
type PropsToken = {
  primary?: boolean // Generated automatically
}
```

## 4. Custom Variables (`_var`)

If you need a property to be available as a CSS variable for external control or use in scripts, add the `_var: true` flag.

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

**Result (SCSS):**
```scss
.component {
  --component-height: 48px;
  height: var(--component-height);
}
```

