Add docs

docs/design-system/customization.md

@@ -0,0 +1,41 @@
+# Customization without forking
+
+Цель: дать пользователю возможность менять дизайн **не изменяя библиотеку**.
+
+Есть три уровня кастомизации:
+
+## 1) Switch theme/platform/skin
+
+```tsx
+<UIProvider config={{ theme: "dark", platform: "vk", skin: "ios" }} />
+```
+
+## 2) Runtime overrides (vars)
+
+```tsx
+<UIProvider
+  config={{
+    vars: {
+      "--ui-primary": "#ff2d55",
+      "--btn-radius": "18px",
+      "--input-h-md": "46px",
+    }
+  }}
+/>
+```
+
+## 3) App-level CSS layer
+
+```css
+:root[data-platform="web"]{
+  --ui-primary: #8b5cf6;
+}
+```
+
+## Contract (совместимость)
+
+Мы считаем частью публичного контракта:
+- имена токенов `--ui-*` и `--btn-*`/`--input-*`/…
+- data attributes `data-theme`, `data-platform`, `data-skin`
+
+Изменения этих сущностей должны быть semver‑major.

docs/design-system/presets.md

@@ -0,0 +1,33 @@
+# Presets: web/vk/tg × ios/android × light/dark
+
+`presets.css` — слой, который задаёт значения токенов в зависимости от:
+
+- `data-theme`
+- `data-platform`
+- `data-skin`
+
+## iOS (Cupertino feel)
+
+Для `data-skin="ios"` характерно:
+- выше контролы (`--btn-h-md: 44px`, `--input-h-md: 44px`)
+- более мягкие радиусы (`--ui-radius: 16px`)
+- более “воздушные” отступы
+- умеренный blur/overlay в модалках
+
+## Android (Material feel)
+
+Для `data-skin="android"` характерно:
+- более компактные радиусы (`--ui-radius: 12px`)
+- высоты ближе к material baseline
+- более “плоское” ощущение
+
+## Platform accents
+
+- `vk` → `--ui-primary: #2d81e0`
+- `tg` → `--ui-primary: #3390ec`
+
+## Debug checklist
+
+1) Проверьте, что `UIProvider` ставит `data-*` на `documentElement`.
+2) Проверьте, что компоненты используют токены, а не захардкоженные px.
+3) Убедитесь, что `@tria/ui/styles` импортируется один раз.

docs/design-system/tokens.md

@@ -0,0 +1,43 @@
+# Tokens overview
+
+Tria UI строится на CSS переменных. База начинается с `--ui-*`, а компоненты используют специализированные токены.
+
+## Global tokens (`--ui-*`)
+
+- `--ui-bg`, `--ui-panel`, `--ui-fg`, `--ui-muted`
+- `--ui-border`, `--ui-shadow`
+- `--ui-primary`, `--ui-primary-fg`
+- `--ui-radius`, `--ui-radius-sm`, `--ui-radius-lg`
+- `--ui-space-1..4`
+- `--ui-ease`, `--ui-duration*`
+- `--safe-top/right/bottom/left`
+
+## Component tokens (examples)
+
+### Button
+- `--btn-h-sm/md/lg`
+- `--btn-px-sm/md/lg`
+- `--btn-radius`
+- `--btn-gap`
+
+### Input
+- `--input-h-sm/md/lg`
+- `--input-px`
+- `--input-radius`
+
+### Cell
+- `--cell-h`, `--cell-px`, `--cell-gap`
+- `--cell-before`, `--cell-chev`
+- `--cell-badge-*`
+
+### Modal
+- `--modal-w`, `--modal-p`, `--modal-radius`, `--modal-overlay`, `--modal-blur`
+
+### Calendar
+- `--cal-day`, `--cal-day-radius`, `--cal-gap`
+
+## Where tokens are set
+
+- `tokens.css` — базовые значения и алиасы
+- `presets.css` — значения под theme/platform/skin
+- кастомизация — через `UIProvider.config.vars` или отдельным CSS слоем в приложении