@1337exp/taoui 4.0.1 → 5.0.0

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 (35) hide show
  1. package/CHANGELOG.md +314 -220
  2. package/MIGRATION-5.md +133 -0
  3. package/README.md +828 -682
  4. package/README.ru.md +828 -687
  5. package/dist/index.d.ts +2009 -701
  6. package/dist/{index.mjs → index.js} +3867 -2808
  7. package/dist/index.js.map +1 -0
  8. package/dist/styles.css +1 -1
  9. package/package.json +100 -90
  10. package/skills/taoui/SKILL.md +131 -0
  11. package/skills/taoui/references/components.md +1105 -0
  12. package/src/styles/base.css +81 -81
  13. package/src/styles/contexts/atmosphere.css +29 -0
  14. package/src/styles/contexts/size.css +125 -0
  15. package/src/styles/{surface.css → contexts/surface.css} +68 -4
  16. package/src/styles/contexts/tone.css +118 -0
  17. package/src/styles/date-popup.css +2 -2
  18. package/src/styles/index.css +12 -5
  19. package/src/styles/palettes/index.css +11 -0
  20. package/src/styles/palettes/lagoon.css +105 -0
  21. package/src/styles/palettes/marple.css +105 -0
  22. package/src/styles/palettes/ocean-blue.css +105 -0
  23. package/src/styles/palettes/pinheiro.css +105 -0
  24. package/src/styles/palettes/sunset.css +105 -0
  25. package/src/styles/palettes/tokyo-night.css +105 -0
  26. package/src/styles/palettes/violet-dusk.css +105 -0
  27. package/src/styles/{semantic.css → themes/dark.css} +95 -93
  28. package/src/styles/themes/light.css +86 -74
  29. package/src/styles/{primitives.css → tokens/primitives.css} +162 -139
  30. package/src/styles/tokens/semantic.css +33 -0
  31. package/src/styles/typography.css +220 -0
  32. package/dist/index.cjs +0 -10572
  33. package/dist/index.cjs.map +0 -1
  34. package/dist/index.mjs.map +0 -1
  35. package/src/styles/size.css +0 -57
package/README.ru.md CHANGED
@@ -1,687 +1,828 @@
1
- <h1 align="center">Tao UI</h1>
2
-
3
- <p align="center">
4
- <b>Библиотека Vue 3 компонентов на дизайн-токенах.</b><br>
5
- Поменял несколько CSS-переменных — поменялась тема всего набора.
6
- </p>
7
-
8
- <p align="center">
9
- <a href="https://www.npmjs.com/package/@1337exp/taoui"><img src="https://img.shields.io/npm/v/@1337exp/taoui?color=cb3837&logo=npm" alt="npm"></a>
10
- <a href="https://github.com/1337exp/taoui/actions/workflows/ci.yml"><img src="https://github.com/1337exp/taoui/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
- <a href="https://github.com/1337exp/taoui/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@1337exp/taoui" alt="license"></a>
12
- <img src="https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs&logoColor=white" alt="Vue 3">
13
- <img src="https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white" alt="TypeScript">
14
- </p>
15
-
16
- <p align="center">
17
- <a href="https://github.com/1337exp/taoui/blob/master/README.md">English</a> · <b>Русский</b> ·
18
- <a href="#установка">Установка</a> ·
19
- <a href="#демонстрация">Демонстрация</a> ·
20
- <a href="CHANGELOG.md">Список изменений</a>
21
- </p>
22
-
23
- <p align="center">
24
- <img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/overview-dark.webp" alt="Компоненты Tao UI в тёмной теме" width="860">
25
- </p>
26
-
27
- ## Почему Tao UI
28
-
29
- - **Сначала токены.** Цвета, радиусы, отступы и шрифты — CSS-переменные в три слоя (примитивы, семантика, тема). Перекрасить набор или одну панель можно, не трогая компоненты.
30
- - **Одна шкала, один API.** `small` / `medium` / `large` везде, одинаковые правила `v-model` / `change` / `*Text` / `*Label` для всех полей, тона вместо случайных цветов.
31
- - **Тёмная и светлая темы** из коробки и поверхности (`flat` / `grain` / `glass`) для HUD и лендингов.
32
- - **Встроенные языки.** Плейсхолдеры, даты и aria-подписи на русском и английском, переключаются на лету без перезагрузки.
33
- - **Nuxt и чистый Vue.** `TaoLink` сам выбирает `NuxtLink`, `RouterLink` или `<a>`. Полные типы, ES и CJS сборки.
34
- - **Клавиатура.** Ловушки фокуса, `role` / `aria-*` на контролах.
35
-
36
- <table>
37
- <tr>
38
- <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: квадрат, полоса тона, режимы HEX / RGB / HSL"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, пипетка, <code>v-model</code> — строка hex</sub></td>
39
- <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Переключение тёмной и светлой тем"><br><sub><b>Темы</b> — один атрибут, все компоненты следуют</sub></td>
40
- </tr>
41
- <tr>
42
- <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider с метками"><br><sub><b>TaoSlider / TaoRangeSlider</b> — метки, дискретные шкалы, вертикаль</sub></td>
43
- <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="Поверхности flat, grain и glass"><br><sub><b>Поверхности</b> — flat, grain, glass</sub></td>
44
- </tr>
45
- </table>
46
-
47
- ## Компоненты
48
-
49
- ### Базовые
50
-
51
- - **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
52
- - **TaoButton** — кнопка: `primary` / `secondary` / `ghost` / `text` / `danger`. `tone` красит ghost и text (danger, success, warning, info, neutral)
53
- - **TaoCard** — карточка со слотами cover / header / footer. В `#cover` — фото или `TaoCarousel`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на обложке
54
- - **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
55
- - **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
56
- - **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
57
- - **TaoModal** — модальное окно с анимацией и слотами
58
- - **TaoDrawer** — боковая панель (фильтры, настройки). Esc, клик по фону, ловушка фокуса — как у модалки
59
- - **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
60
- - **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
61
- - **TaoTabs** — вкладки для переключения между секциями контента
62
- - **TaoTooltip** — всплывающая подсказка при наведении. `top` / `bottom` / `left` / `right`, у края экрана переворачивается
63
- - **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи. Не тултип и не меню действий
64
-
65
- ### Layout
66
-
67
- - **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
68
- - **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
69
- - **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
70
- - **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. У item `col` / `row`; уже ~560px span сбрасывается. Не masonry
71
- - **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
72
- - **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
73
- - **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
74
- - **TaoAnimatedBorder** — контейнер с анимированной радужной рамкой (декоративный, не завязан на тему)
75
-
76
- ### Формы и ввод
77
-
78
- - **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
79
- - **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
80
- - **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
81
- - **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
82
- - **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
83
- - **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
84
- - **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select
85
- - **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
86
- - **TaoFormField** — общие label / hint / error для полей формы
87
- - **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
88
- - **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
89
- - **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум». `variant`: `bar` (по умолчанию) / `outline` (рамка как у Input) / `filled` / `plain`; `readonly`. `noBorder`, `noBackground`, `borderInverse`, `dummy` устарели
90
- - **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. `format="#-##-##"` рисует визуальные разделители (в значение не входят; вставка в таком виде или чистым кодом раскладывается по ячейкам). Последняя ячейка снимает фокус и эмитит `complete`
91
- - **TaoSlider** / **TaoRangeSlider** — один бегунок (`v-model` — число) или два (`[от, до]`, `minGap`). Мышь, тач, стрелки. `marks` (деления, числа, `{ value, label }`), `discrete` для ступенчатых шкал, `vertical`, `flat`, `format`; `variant="thin"` — тонкий трек для seek / громкости
92
- - **TaoColorPicker** — квадрат насыщенности и яркости, полосы тона и прозрачности, образцы, пипетка (где есть `EyeDropper`), режимы ввода HEX / RGB / HSL. `v-model` — строка hex; `colorModel()` подключает ваше собственное хранилище цвета
93
- - **TaoColorInput** — поле с образцом и hex-текстом; палитра открывается в поповере
94
- - **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
95
-
96
- ### Отображение данных
97
-
98
- - **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
99
- - **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
100
- - **TaoEmpty** — пустой список, нет результатов, нет прав
101
- - **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
102
- - **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
103
- - **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
104
- - **TaoCounter** — витрина числа с переворотом цифр (не инпут)
105
- - **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`, точки — `dots`
106
- - **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
107
- - **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
108
- - **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info)
109
- - **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
110
- - **TaoTimeline** — play / pause, слайдер по времени с метками событий, подпись «время / длина». Время сама не двигает: ведите `v-model` своими часами
111
- - **TaoLoader** — анимированный лоадер (четыре точки)
112
- - **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
113
- - **TaoIcon** — обёртка для icon-шрифта (см. раздел «Иконки» ниже)
114
-
115
- ### Навигация и взаимодействие
116
-
117
- - **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
118
- - **TaoBreadcrumb** — крошки: последний пункт — текущая страница
119
- - **TaoDropdownMenu** — выпадающее меню с авто-позиционированием у края экрана
120
- - **TaoScrollTop** — плавающая кнопка «наверх»: виды `solid` / `ghost` / `text`, `side`, подпись `label` при наведении мыши. Появляется при обратном скролле после `boundary`
121
-
122
- ### Обратная связь
123
-
124
- - **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
125
- - **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
126
- - **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
127
-
128
- ## Соглашения
129
-
130
- Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral` (тип `TaoTone`), всегда через проп `tone`: Button, Alert, Tag. `type` у Alert / Tag — устаревший алиас.
131
- `error` у Alert, Tag и `toast()` — синоним `danger`. Button уже `danger`.
132
- Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
133
-
134
- Размеры контролов: `small` | `medium` | `large` (тип `TaoSize`). Одна шкала для Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup и FormField — контролы одного размера встают в ряд ровно. Checkbox, Radio / RadioGroup и Switch масштабируют индикатор (14 / 18 / 22px) и подпись; Tag — высоту (18 / 20 / 24px); Tabs, кнопки Pagination и строки List берут высоту Button; Table масштабирует отступы ячеек (`size="small"` вместо `compact`); FileDrop — зону и строки файлов; Slider — трек и бегунок.
135
- Без `size` контрол берёт размер предков, в корне — `medium`. На целый блок размер задаётся классом `tao-size-small` / `-medium` / `-large` на любом элементе или `size` у `TaoFormField` / `TaoInputGroup`. Явный `size` у контрола главнее.
136
-
137
- ```vue
138
- <div class="tao-size-small">
139
- <TaoInput v-model="q" />
140
- <TaoButton>Найти</TaoButton>
141
- </div>
142
- ```
143
-
144
- Контент и раскладка держат свою шкалу и не наследуют: Avatar (24 / 32 / 48px; `s` / `m` / `l` устарели), Divider `gap` (`big` — устаревший алиас `large`), Loader / Icon / ScrollTop (пиксели).
145
- Container живёт на другой оси — ширина: `width="wide" | "slim" | "ultra-slim"` (`size` — устаревший алиас).
146
-
147
- Поверхности — из чего «сделана» панель: `flat` — заливка (по умолчанию), `grain` — статичное плёночное зерно, `glass` —
148
- полупрозрачное стекло с размытием того, что позади. Проп `surface` у TaoCard / TaoBlock или класс `tao-surface-grain` /
149
- `-glass` на любом элементе — HUD в игре, секция лендинга, сайдбар. Вид настраивается один раз токенами темы
150
- (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill` / `-border` / `-blur`). Поверхность принадлежит одному элементу:
151
- вложенные панели её не наследуют. Стеклу нужно что-то позади — используйте его для того, что лежит поверх контента; над
152
- ровным фоном это просто серая заливка, над анимацией размытие пересчитывается каждый кадр. Toast и confirm стеклянные по
153
- умолчанию, с оттенком своего тона; `toast.defaults({ surface: 'flat' })` и `confirm.defaults({ surface: 'flat' })`
154
- выключают стекло, `.surface('flat')` — для одного. Без поддержки размытия или при `prefers-reduced-transparency` стекло
155
- становится сплошной панелью.
156
-
157
- Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
158
- Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
159
-
160
- Правила API — им следуют все компоненты; старые имена остаются устаревшими алиасами:
161
-
162
- - **Поля** принимают `v-model`, `disabled`, `error` (красная рамка) и `size`. Подпись, подсказка и текст ошибки — через `TaoFormField`.
163
- - **События**: `update:X` для v-model плюс `change`, когда пользователь закончил изменение (Slider, Split — по отпусканию). Остальные события — глаголы в настоящем времени: `select`, `close`, `create`.
164
- - **Тексты**: видимые — `*Text` (`clearText`, `successText`), для скринридера — `*Label` (`closeLabel`).
165
- - **Списки**: массивы данных — `items`; выбираемые элементы несут `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Идентификаторы обычных данных (колонки таблицы, стадии) остаются `key`.
166
- - **Булевы** — прилагательные без `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Ось раскладки — `direction: 'row' | 'column'`, не `vertical`.
167
- - **Длины** (`padding`, `radius`, `gap`, `maxHeight`): число — пиксели, строка уходит в CSS как есть (тип `TaoLength`).
168
-
169
- ## Иконки
170
-
171
- `TaoIcon` не поставляет собственный набор иконок — он рендерит класс `icon-<name>`
172
- по соглашению, рассчитанному на подключение внешнего icon-шрифта (например,
173
- собранного через IcoMoon/Fontello). Чтобы иконки отображались, подключите
174
- свой шрифт с классами вида `.icon-arrow-up { ... }` в проекте.
175
-
176
- ## Установка
177
-
178
- ```bash
179
- npm install @1337exp/taoui
180
- ```
181
-
182
- Или локально из папки:
183
-
184
- ```bash
185
- npm install ../path-to-tao-ui
186
- ```
187
-
188
- ## Использование
189
-
190
- ### Подключение в Nuxt 3
191
-
192
- Создайте плагин `plugins/tao-ui.ts`:
193
-
194
- ```typescript
195
- import { defineNuxtPlugin } from '#app'
196
- import TaoUI from '@1337exp/taoui'
197
-
198
- export default defineNuxtPlugin((nuxtApp) => {
199
- nuxtApp.vueApp.use(TaoUI)
200
- })
201
- ```
202
-
203
- Импортируйте стили в `app.vue` или layout:
204
-
205
- ```vue
206
- <script setup>
207
- import '@1337exp/taoui/styles.css'
208
- </script>
209
- ```
210
-
211
- ### Подключение в Vue 3 проекте
212
-
213
- ```javascript
214
- // main.js
215
- import { createApp } from 'vue'
216
- import App from './App.vue'
217
- import TaoUI from '@1337exp/taoui'
218
- import '@1337exp/taoui/styles.css'
219
-
220
- const app = createApp(App)
221
- app.use(TaoUI)
222
- app.mount('#app')
223
- ```
224
-
225
- ### Язык
226
-
227
- Встроенные тексты (плейсхолдеры, «Очистить», aria-подписи, даты) по умолчанию английские. Русский идёт в комплекте:
228
-
229
- ```javascript
230
- import TaoUI, { localeRu } from '@1337exp/taoui'
231
-
232
- app.use(TaoUI, { locale: localeRu })
233
- ```
234
-
235
- Поменять отдельные тексты — остальное останется от локали по умолчанию:
236
-
237
- ```javascript
238
- app.use(TaoUI, { locale: { select: { placeholder: 'Выберите город' } } })
239
- ```
240
-
241
- Другой язык: скопируйте `localeEn` (или `localeRu`), переведите и передайте так же (тип `TaoLocale`). Ключи повторяют имена пропсов —
242
- `locale.select.placeholder` — значение по умолчанию для `placeholder` у TaoSelect, а переданный руками проп всегда главнее.
243
-
244
- Язык можно переключать в любой момент — из настроек, переключателя языка, по маршруту. Уже показанные компоненты
245
- обновятся сразу, без перезагрузки и без потери введённого:
246
-
247
- ```javascript
248
- import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
249
-
250
- function onLanguageChange(lang) {
251
- setTaoLocale(lang === 'ru' ? localeRu : localeEn)
252
- }
253
- ```
254
-
255
- Без плагина (отдельные компоненты) достаточно одного вызова `setTaoLocale()`.
256
-
257
- ### Переход с 3.x
258
-
259
- В 4.0 поменялся один умолчательный параметр: встроенные тексты теперь английские (раньше были русские). Чтобы остаться
260
- на русском, передайте локаль один раз: `app.use(TaoUI, { locale: localeRu })`, а без плагина — `setTaoLocale(localeRu)`.
261
- Хелперы дат и компоненты дат следуют локали и по умолчанию тоже `en-US`.
262
-
263
- ### Переход с 1.x
264
-
265
- Смотрите [CHANGELOG.md](CHANGELOG.md): что сломалось и таблица «старое имя → новое». В 2.x старые имена ещё работают
266
- и в режиме разработки пишут предупреждение в консоль.
267
-
268
- ### Использование отдельных компонентов
269
-
270
- ```vue
271
- <script setup>
272
- import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
273
- import '@1337exp/taoui/styles.css'
274
- </script>
275
-
276
- <template>
277
- <TaoButton variant="primary">Нажми меня</TaoButton>
278
- <TaoFormField label="Введите текст">
279
- <TaoInput v-model="text" />
280
- </TaoFormField>
281
- <TaoModal v-model="isOpen" title="Заголовок">
282
- Содержимое модального окна
283
- </TaoModal>
284
- </template>
285
- ```
286
-
287
- ## Split
288
-
289
- `TaoSplit` — две панели и полоса между ними. Это не `TaoDivider` (там только линия) и не раскладка на N панелей: три колонки — два вложенных сплита.
290
-
291
- `direction` как у Flex: `row` (start | end) или `column` (start над end). Слоты `#start` / `#end`.
292
-
293
- `v-model` — размер панели start. `unit` — `%` (по умолчанию, доля живёт при ресайзе контейнера) или `px` (сайдбар; вторая панель забирает остаток). Для `px` размер нужно задать явно: дефолт `50` — это 50px. `min` / `max` ограничивают start, `min-end` — минимум второй панели, все в той же единице. `resizable="false"` оставляет полосу, но без перетаскивания.
294
-
295
- Сплит заполняет родителя (`width` / `height: 100%`). Родитель должен ограничить размер по оси сплита: у `column` без высоты не из чего считать `%`. Панели с `min-width` / `min-height: 0` и `overflow: hidden`, чтобы контент не мешал сжатию. Скролл — на внутренней обёртке (`overflow: auto; height: 100%; min-height: 0`). Вложенный `TaoSplit` прямым ребёнком панели растягивается сам.
296
-
297
- ```vue
298
- <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
299
- <template #start>Навигация</template>
300
- <template #end>Основное</template>
301
- </TaoSplit>
302
- ```
303
-
304
- ## Toast
305
-
306
- Вызов — цепочка в одном тике, `setTimeout(0)` отправляет уведомление.
307
-
308
- ```javascript
309
- import { toast } from '@1337exp/taoui'
310
-
311
- toast().success().message('Сохранено')
312
- toast().error().title('Сеть').timeout(5000).message('Нет соединения')
313
- toast.success('Сохранено')
314
- toast.warning('Черновик', { timeout: 1000 })
315
- ```
316
-
317
- Позиция по умолчанию — `topCenter`. Глобально:
318
-
319
- ```javascript
320
- toast.defaults({ position: 'bottomRight' })
321
- toast.byBottomRight()
322
- ```
323
-
324
- `question` с оверлеем в kit нет — это confirm, не toast. Кнопки в тосте, если нужны:
325
-
326
- ```javascript
327
- toast().info().message('Удалить файл?').action('Удалить', onRemove)
328
- ```
329
-
330
- Viewport можно не вставлять: первый вызов сам создаст его. Если нужен явный контроль (тесты, свой layout):
331
-
332
- ```vue
333
- <TaoToastViewport />
334
- ```
335
-
336
- ## Confirm
337
-
338
- Вопрос с оверлеем: всплывает по центру и спрашивает. Это не toast — нет прогресс-бара и автозакрытия, есть `await`, Esc и клик по оверлею = отмена.
339
-
340
- ```javascript
341
- import { confirm } from '@1337exp/taoui'
342
-
343
- if (await confirm().title('Удалить файл?').message('Это нельзя отменить').danger()) {
344
- remove()
345
- }
346
-
347
- const ok = await confirm('Выйти без сохранения?', {
348
- ok: 'Выйти',
349
- cancel: 'Остаться',
350
- })
351
- ```
352
-
353
- Очередь: второй `confirm()`, пока открыт первый, подождёт. Подписи по умолчанию — «ОК» / «Отмена»:
354
-
355
- ```javascript
356
- confirm.defaults({ ok: 'Yes', cancel: 'No' })
357
- ```
358
-
359
- ## Формы
360
-
361
- `TaoFormField` вешает общий label / hint / error и прокидывает `id` во вложенный контрол.
362
-
363
- ```vue
364
- <TaoFormField label="Город" hint="Необязательно">
365
- <TaoSelect v-model="city" :options="cities" />
366
- </TaoFormField>
367
-
368
- <TaoSwitch v-model="dark" label="Тёмная тема" />
369
-
370
- <TaoRadioGroup v-model="plan" legend="Тариф">
371
- <TaoRadio value="free" label="Free" />
372
- <TaoRadio value="pro" label="Pro" />
373
- </TaoRadioGroup>
374
-
375
- <TaoSegmented v-model="period" legend="Период">
376
- <TaoSegmentedOption value="week">Неделя</TaoSegmentedOption>
377
- <TaoSegmentedOption value="month">Месяц</TaoSegmentedOption>
378
- <TaoSegmentedOption value="year">Год</TaoSegmentedOption>
379
- </TaoSegmented>
380
-
381
- <TaoAlert tone="warning" title="Черновик">Сохраните, прежде чем уйти.</TaoAlert>
382
- ```
383
-
384
- `TaoSegmented` — короткий взаимоисключающий выбор, все варианты видны сразу. Не для навигации по страницам: это `TaoTabs`. Длинные подписи или больше 5–6 пунктов — `TaoRadioGroup` или `TaoSelect`.
385
-
386
- `TaoSelect` открывается с клавиатуры (стрелки, Enter, Esc), список переворачивается у края экрана. Delete или «Очистить» внизу списка сбрасывает значение в `null`.
387
-
388
- Если `null` не допустим (шаг сетки, порядок сортировки), передайте `:clearable="false"`: строка сброса и Delete / Backspace пропадут. Подпись строки сброса — `clear-text`, для иконки или своей разметки есть слот `#clear`. `size` — `small` / `medium` / `large` (без него — от предков), масштабирует и раскрытый список.
389
-
390
- ```vue
391
- <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
392
-
393
- <TaoSelect v-model="city" :options="cities">
394
- <template #clear><TaoIcon name="close" /> Сбросить</template>
395
- </TaoSelect>
396
- ```
397
-
398
- `TaoCombobox` — то же меню, но с полем. Печатаете — варианты режутся. `allow-create` пишет введённое в `v-model`, если точного совпадения нет. Список сам не меняется: слушайте `create` и добавьте option снаружи.
399
-
400
- Подпись, подсказка и текст ошибки всегда идут через `TaoFormField`; `label` / `error-message` у `TaoInput` устарели. `TaoFormField` также оборачивает `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup` и `TaoSegmented` — id, hint и error прокидываются сами.
401
-
402
- `TaoTag` может быть чипом: `#prefix` слева (обычно `TaoAvatar`), `closable` рисует крестик и эмитит `close`. Клик по крестику наружу не всплывает. `flat` снимает рамку, заливка остаётся.
403
-
404
- ```vue
405
- <TaoTag tone="neutral" closable @close="remove">
406
- <template #prefix>
407
- <TaoAvatar name="Анна Козлова" size="small" />
408
- </template>
409
- Анна Козлова
410
- </TaoTag>
411
- ```
412
-
413
- ## Таблица и пагинация
414
-
415
- Таблица рендерит то, что передали: сама данные не режет и не сортирует. Это удобно и для серверной выборки, и для клиентской — страница режется снаружи.
416
-
417
- ```vue
418
- <TaoTable
419
- :columns="columns"
420
- :rows="pageRows"
421
- v-model:sort="sort"
422
- empty-text="Пока нет записей"
423
- >
424
- <template #cell-status="{ row }">
425
- <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
426
- {{ row.status }}
427
- </TaoTag>
428
- </template>
429
- </TaoTable>
430
-
431
- <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
432
- ```
433
-
434
- ```javascript
435
- const columns = [
436
- { key: 'name', label: 'Имя', sortable: true },
437
- { key: 'city', label: 'Город' },
438
- { key: 'status', label: 'Статус' },
439
- ]
440
- ```
441
-
442
- Слот `cell-<ключ>` перекрывает ячейку. `loading` показывает оверлей, пустой список — текст или слот `#empty`. Клик по шапке с `sortable` крутит `asc → desc → сброс`.
443
-
444
- ## Пустые состояния и загрузка
445
-
446
- ```vue
447
- <TaoEmpty title="Ничего не нашлось">
448
- Измените фильтр или сбросьте поиск.
449
- <template #action>
450
- <TaoButton variant="secondary">Сбросить</TaoButton>
451
- </template>
452
- </TaoEmpty>
453
-
454
- <TaoSkeleton variant="title" />
455
- <TaoSkeleton :lines="3" />
456
- <TaoSkeleton variant="circle" />
457
-
458
- <TaoStages :items="[
459
- { key: 'pay', label: 'Оплата', status: 'ok' },
460
- { key: 'pack', label: 'Сборка', status: 'work' },
461
- { key: 'ship', label: 'Доставка', status: 'wait' },
462
- ]" />
463
-
464
- <TaoList>
465
- <TaoListItem
466
- title="Анна Козлова"
467
- description="Дизайн · Москва"
468
- clickable
469
- :selected="picked === 'anna'"
470
- @click="picked = 'anna'"
471
- >
472
- <template #prefix>
473
- <TaoAvatar name="Анна Козлова" size="small" />
474
- </template>
475
- </TaoListItem>
476
- </TaoList>
477
- ```
478
-
479
- ```vue
480
- <TaoInput v-model="q" placeholder="Найти…">
481
- <template #prefix>⌕</template>
482
- </TaoInput>
483
-
484
- <TaoInputGroup>
485
- <template #before>https://</template>
486
- <TaoInput v-model="host" placeholder="example.com" />
487
- <template #after>
488
- <TaoButton>Проверить</TaoButton>
489
- </template>
490
- </TaoInputGroup>
491
-
492
- <form @submit.prevent="onSave">
493
- <TaoFormField label="Email">
494
- <TaoInput v-model="email" type="email" />
495
- </TaoFormField>
496
- <TaoButton type="submit">Сохранить</TaoButton>
497
- </form>
498
-
499
- <TaoFormField label="Количество">
500
- <TaoInputNumber v-model="qty" :min="1" :max="99" />
501
- </TaoFormField>
502
-
503
- <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
504
-
505
- <TaoFormField label="День доставки" hint="В модели всегда YYYY-MM-DD">
506
- <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
507
- </TaoFormField>
508
-
509
- <TaoFormField label="Даты поездки">
510
- <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
511
- </TaoFormField>
512
-
513
- <TaoCounter :value="score" :max-digits="6" />
514
-
515
- <TaoCarousel :autoplay="4000" loop dots>
516
- <article v-for="item in banners" :key="item.id" class="hero">
517
- <strong>{{ item.title }}</strong>
518
- <span>{{ item.text }}</span>
519
- </article>
520
- </TaoCarousel>
521
- <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
522
- <TaoCarousel v-model="slide" :per-view="5" :peek="28">
523
- <template #prev></template>
524
- <template #next="{ go, disabled }">
525
- <button type="button" :disabled="disabled" @click="go">вперёд</button>
526
- </template>
527
- <article v-for="item in products" :key="item.id">…</article>
528
- </TaoCarousel>
529
- ```
530
-
531
- `TaoDrawer` — лист сбоку, не модалка по центру:
532
-
533
- ```vue
534
- <TaoDrawer v-model="open" title="Фильтры">
535
- ...
536
- </TaoDrawer>
537
- ```
538
-
539
- ## Дизайн-токены и темизация
540
-
541
- Стили библиотеки построены в три слоя. Компоненты **никогда** не обращаются
542
- к цветам/размерам напрямую — только через переменные из семантического слоя.
543
- Это и есть механизм темизации: переопределяете 20-30 переменных — меняется
544
- внешний вид всех компонентов сразу, без правок самих компонентов.
545
-
546
- ```
547
- primitives.css → semantic.css → themes/*.css (опционально)
548
- сырые цвета публичный API готовые темы поверх
549
- и размеры, темизации: semantic — пример: light
550
- не трогать вот что менять
551
- ```
552
-
553
- ### Слои
554
-
555
- | Файл | Назначение | Трогать? |
556
- |---|---|---|
557
- | `primitives.css` | Сырая палитра, шкалы отступов/радиусов/теней (`--tao-orange-400`, `--tao-space-3`...) | Обычно нет |
558
- | `semantic.css` | Токены темы по умолчанию (dark): `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger` и т.д. | **Да — это и есть API темизации** |
559
- | `themes/light.css` | Пример альтернативной темы через `[data-tao-theme="light"]` | Да, как образец |
560
- | `base.css` | Глобальный reset (скроллбар, ссылки, box-sizing) | Редко |
561
-
562
- Все четыре подключаются одним файлом `@1337exp/taoui/styles.css`.
563
-
564
- ### Как сделать свою тему
565
-
566
- Тема — это просто переопределение семантических токенов под своим селектором.
567
- Ничего в компонентах менять не нужно:
568
-
569
- ```css
570
- /* my-brand-theme.css */
571
- [data-tao-theme="my-brand"] {
572
- --tao-color-accent: #6c5ce7;
573
- --tao-color-accent-hover: #5a4bd1;
574
- --tao-color-bg: #0f0f1a;
575
- --tao-color-surface: #0f0f1a;
576
- --tao-color-surface-raised: #1a1a2e;
577
- --tao-color-text: #d6d6e8;
578
- --tao-color-text-strong: #ffffff;
579
- /* остальные токены см. semantic.css */
580
- }
581
- ```
582
-
583
- ```vue
584
- <!-- app.vue -->
585
- <template>
586
- <div data-tao-theme="my-brand">
587
- <NuxtPage />
588
- </div>
589
- </template>
590
- ```
591
-
592
- Или переключайте тему целиком на `<html>`, чтобы стилизовать модалки/тултипы,
593
- которые телепортируются в `body`:
594
-
595
- ```javascript
596
- document.documentElement.setAttribute('data-tao-theme', 'light')
597
- ```
598
-
599
- ### Ключевые группы токенов
600
-
601
- - `--tao-color-accent*` — акцентный/брендовый цвет (кнопки primary, активные вкладки, ссылки)
602
- - `--tao-color-on-accent` — текст на акцентном фоне (`--tao-color-text-on-accent` — алиас)
603
- - `--tao-color-selection`, `--tao-color-selection-text` — выделение текста (`::selection`)
604
- - `--tao-color-surface*` — фоны контейнеров (обычный / приподнятый / утопленный / hover)
605
- - `--tao-color-border*` — границы
606
- - `--tao-color-text*` — текст (обычный / усиленный / subtle / приглушённый / disabled)
607
- - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — статусные цвета
608
- - `--tao-color-input-*` — поля ввода отдельно, т.к. фон/текст полей часто не совпадают с surface/text
609
- - `--tao-radius-control`, `--tao-radius-panel` — скругления (мелкие контролы vs крупные панели)
610
- - `--tao-shadow-panel`, `--tao-shadow-overlay` — тени
611
- - `--tao-font-size-*` — шкала кегля в `primitives.css`: `xs`–`xl` контролы, `2xl`–`4xl` заголовки / проза
612
- - `--tao-control-height-*` (26 / 36 / 44px), `--tao-control-padding-x-*`, `--tao-control-padding-y-*`, `--tao-control-font-size-*`, `--tao-control-font-size-secondary-*`, `--tao-button-padding-x-*`, `--tao-indicator-size-*`, `--tao-tag-height-*` / `-padding-x-*` / `-font-size-*` — шкала размеров в `primitives.css`. Компоненты читают текущие значения из `size.css`: `--tao-control-height`, `--tao-control-padding-x` / `-y`, `--tao-control-font-size`, `--tao-control-font-size-secondary`, `--tao-button-padding-x`, `--tao-indicator-size`, `--tao-tag-height` / `-padding-x` / `-font-size`. Используйте их в своих контролах, чтобы попасть в размер окружения. `--tao-field-height` — устаревший алиас `--tao-control-height`
613
-
614
- Полный список — в `src/styles/semantic.css`, он же единственный файл,
615
- который стоит открыть, чтобы понять весь доступный API темизации.
616
-
617
- ### Если нужна тема с нуля, без primitives
618
-
619
- ```javascript
620
- import '@1337exp/taoui/styles/primitives.css' // шкалы можно оставить
621
- import './my-semantic.css' // свой семантический слой вместо @1337exp/taoui/styles/semantic.css
622
- import '@1337exp/taoui/styles/base.css'
623
- ```
624
-
625
- ## Демонстрация
626
-
627
- Все компоненты с живыми примерами, таблицами пропсов и готовыми сниппетами. Язык (EN / RU) и тема (dark / light) переключаются в шапке.
628
-
629
- ```bash
630
- cd showcase
631
- npm install
632
- npm run dev # или из корня репозитория: npm run showcase
633
- ```
634
-
635
- Showcase смотрит прямо в `src/`, поэтому правки компонентов видны без
636
- `npm run build`. `npm run showcase:build` собирает статический сайт с относительными
637
- путями — его можно положить в любую папку (например, `/sandbox/taoui/`).
638
-
639
- Скриншоты и ролики в этом README сняты с showcase: см. [docs/media](docs/media/README.md).
640
-
641
- ## Разработка
642
-
643
- ```bash
644
- # Сборка библиотеки
645
- npm run build
646
-
647
- # Режим разработки (watch)
648
- npm run dev
649
-
650
- # Проверка типов
651
- npm run type-check
652
-
653
- # Тесты (Vitest)
654
- npm test
655
- ```
656
-
657
- ## Публикация в npm
658
-
659
- Публикуется только `dist/` (собранная библиотека) и `src/styles/` (сырые
660
- токены — чтобы можно было подключить `primitives.css` отдельно при
661
- кастомной теме), плюс `README.md`, `LICENSE` и `CHANGELOG.md`. Исходники компонентов (`src/components/*.vue`),
662
- конфиги сборки и `showcase/` в пакет не попадают — они остаются в
663
- репозитории; чтобы их получить, репозиторий клонируют.
664
-
665
- `npm publish` **сам** прогоняет проверку типов, тесты и полную пересборку перед
666
- публикацией (хук `prepublishOnly` в `package.json`) — так в реестр не
667
- уедет пакет со старым или отсутствующим `dist/`. Собирать вручную перед
668
- `npm publish` не нужно.
669
-
670
- Проверить, что именно попадёт в пакет, без реальной публикации:
671
-
672
- ```bash
673
- npm pack --dry-run
674
- ```
675
-
676
- Токен публикации не должен лежать в репозитории: в `.npmrc` ссылайтесь на него как
677
- `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` и задайте `NPM_TOKEN` в окружении.
678
- `.npmrc` в любом случае в `.gitignore`.
679
-
680
- ## Участие в проекте
681
-
682
- Issues и pull request'ы приветствуются — см. [CONTRIBUTING.md](CONTRIBUTING.md).
683
- Об уязвимостях: [SECURITY.md](SECURITY.md).
684
-
685
- ## Лицензия
686
-
687
- [MIT](LICENSE) © 2026 1337exp
1
+ <h1 align="center">Tao UI</h1>
2
+
3
+ <p align="center">
4
+ <b>Библиотека Vue 3 компонентов на дизайн-токенах.</b><br>
5
+ Поменял несколько CSS-переменных — поменялась тема всего набора.
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@1337exp/taoui"><img src="https://img.shields.io/npm/v/@1337exp/taoui?color=cb3837&logo=npm" alt="npm"></a>
10
+ <a href="https://github.com/1337exp/taoui/actions/workflows/ci.yml"><img src="https://github.com/1337exp/taoui/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="https://github.com/1337exp/taoui/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@1337exp/taoui" alt="license"></a>
12
+ <img src="https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs&logoColor=white" alt="Vue 3">
13
+ <img src="https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white" alt="TypeScript">
14
+ </p>
15
+
16
+ <p align="center">
17
+ <a href="https://github.com/1337exp/taoui/blob/master/README.md">English</a> · <b>Русский</b> ·
18
+ <a href="#установка">Установка</a> ·
19
+ <a href="#демонстрация">Демонстрация</a> ·
20
+ <a href="CHANGELOG.md">Список изменений</a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/overview-dark.webp" alt="Компоненты Tao UI в тёмной теме" width="860">
25
+ </p>
26
+
27
+ ## Почему Tao UI
28
+
29
+ - **Сначала токены.** Цвета, радиусы, отступы и шрифты — CSS-переменные в три слоя (примитивы, семантика, тема). Перекрасить набор или одну панель можно, не трогая компоненты.
30
+ - **Одна шкала, один API.** `small` / `medium` / `large` везде, одинаковые правила `v-model` / `change` / `*Text` / `*Label` для всех полей, тона вместо случайных цветов.
31
+ - **Тёмная и светлая темы** из коробки и поверхности (`flat` / `grain` / `glass`) для HUD и лендингов.
32
+ - **Встроенные языки.** Плейсхолдеры, даты и aria-подписи на русском и английском, переключаются на лету без перезагрузки.
33
+ - **Nuxt и чистый Vue.** `TaoLink` сам выбирает `NuxtLink`, `RouterLink` или `<a>`. Полные типы, ES и CJS сборки.
34
+ - **Клавиатура.** Ловушки фокуса, `role` / `aria-*` на контролах.
35
+
36
+ <table>
37
+ <tr>
38
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: квадрат, полоса тона, режимы HEX / RGB / HSL"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, пипетка, <code>v-model</code> — строка hex</sub></td>
39
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Переключение тёмной и светлой тем"><br><sub><b>Темы</b> — один атрибут, все компоненты следуют</sub></td>
40
+ </tr>
41
+ <tr>
42
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider с метками"><br><sub><b>TaoSlider / TaoRangeSlider</b> — метки, дискретные шкалы, вертикаль</sub></td>
43
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="Поверхности flat, grain и glass"><br><sub><b>Поверхности</b> — flat, grain, glass</sub></td>
44
+ </tr>
45
+ </table>
46
+
47
+ ## Компоненты
48
+
49
+ ### Базовые
50
+
51
+ - **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
52
+ - **TaoButton** — кнопка. `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` красит любой из них (по умолчанию акцент, neutral, success, danger, warning, info)
53
+ - **TaoCard** — карточка со слотами media / header / title / footer и `#corner` (тег, кнопка меню). В `#media` — фото или `TaoCarousel`; `closable` добавляет крестик и событие `close`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на media; `stripe="top | left | bottom"` со `stripeTone` (тон или `gradient` палитры) рисует цветную полосу, которую обрезают углы
54
+ - **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
55
+ - **TaoMarquee** — одна строка без переносов: не помещается — бежит по кругу с гаснущими краями и паузой в начале каждого круга, помещается — стоит. Останавливается при наведении, фокусе и тапе (WCAG 2.2.2); при «уменьшить движение» переносится; скринридер читает один раз. `text` или строчное содержимое в слоте, `speed`, `gap`, `fade` (левое затухание занимает столько места слева от текста: дайте родителю такой padding), `paused`
56
+ - **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
57
+ - **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
58
+ - **TaoModal** — модальное окно с анимацией и слотами
59
+ - **TaoDrawer** — боковая панель (фильтры, настройки). Esc, клик по фону, ловушка фокуса — как у модалки
60
+ - **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
61
+ - **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
62
+ - **TaoTabs** — вкладки для переключения между секциями контента
63
+ - **TaoNav** — навигация между разделами приложения: один список пунктов (`icon`, `href`, `badge`), три вида. `layout="auto"` выбирает по ширине самого TaoNav (container queries, без JS): нижняя панель до 600px (больше пяти пунктов: «Ещё» с меню), рейка с иконками до 840px, боковая панель с подписями от 840px. Со страницей в слоте раскладывает её сам: панель прилипает к низу (с учётом безопасной зоны), боковой список к верху. `select(id, event)` даёт роутеру перехватить ссылку
64
+ - **TaoTooltip** — всплывающая подсказка при наведении. `placement`: `top` / `bottom` / `left` / `right`, у каждого `-start` / `-end`; у края экрана переворачивается
65
+ - **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи; `placement` как у Tooltip. Не тултип и не меню действий
66
+
67
+ ### Layout
68
+
69
+ - **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
70
+ - **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
71
+ - **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
72
+ - **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. Адаптивный bento берёт значения по классам ширины самой сетки (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — на телефоне крупные блоки занимают ряд, мелкие плитки остаются по три, боковой уходит вниз. Простое число — одна колонка на телефоне. `rowHeight` задаёт высоту ряда, как нужно мозаике. Не masonry
73
+ - **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
74
+ - **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
75
+ - **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
76
+ - **TaoAnimatedBorder** — контейнер с анимированной рамкой: радуга, цвета `tone` (следует теме) или свои `colors`; при `prefers-reduced-motion` градиент стоит на месте
77
+
78
+ ### Формы и ввод
79
+
80
+ - **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
81
+ - **TaoChecklist** — чекбоксы с одной моделью (отмеченные значения): `select-all` с промежуточным состоянием, `counter` «3 из 5», `strike` для списка дел (только вид, состояние говорит чекбокс), `description` у пункта. Это fieldset: в `TaoFormField` группа берёт подпись и ошибку
82
+ - **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
83
+ - **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
84
+ - **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
85
+ - **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
86
+ - **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
87
+ - **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select
88
+ - **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
89
+ - **TaoCalendar** — сам календарь на месяц, встроенный (без всплывающего окна): `mode="single"` (`YYYY-MM-DD`) или `"range"` (`{ start, end }`), `min` / `max`, стрелки / PageUp / PageDown / Home / End. `TaoDate` и `TaoDateRange` — поле с этим календарём во всплывающем окне
90
+ - **TaoFormField** — общие label / hint / error для полей формы
91
+ - **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
92
+ - **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
93
+ - **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум». `variant`: `bar` (по умолчанию) / `outline` (рамка как у Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
94
+ - **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. `format="#-##-##"` рисует визуальные разделители (в значение не входят; вставка в таком виде или чистым кодом раскладывается по ячейкам). Последняя ячейка снимает фокус и эмитит `complete`; `status="success | error"` (после `complete`) подсвечивает или встряхивает ячейки и говорит об этом скринридеру
95
+ - **TaoSlider** / **TaoRangeSlider** — один бегунок (`v-model` — число) или два (`[от, до]`, `minGap`). Мышь, тач, стрелки. `marks` (деления, числа, `{ value, label }`), `discrete` для ступенчатых шкал, `vertical`, `flat`, `format`; `variant="thin"` — тонкий трек для seek / громкости
96
+ - **TaoColorPicker** — квадрат насыщенности и яркости, полосы тона и прозрачности, образцы, пипетка (где есть `EyeDropper`), режимы ввода HEX / RGB / HSL. `v-model` — строка hex; `colorModel()` подключает ваше собственное хранилище цвета
97
+ - **TaoColorInput** — поле с образцом и hex-текстом; палитра открывается в поповере
98
+ - **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
99
+
100
+ ### Отображение данных
101
+
102
+ - **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
103
+ - **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
104
+ - **TaoEmpty** — пустой список, нет результатов, нет прав
105
+ - **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
106
+ - **TaoTree** — файлы или объекты деревом: `v-model:expanded`, выбор `none | single | multiple` (`v-model:selected`), чекбоксы с промежуточным состоянием родителя (`checkable`, `v-model:checked`), ленивая подгрузка (`hasChildren` + `load`). ARIA tree: одна остановка Tab, стрелки, `→` / `←` внутрь и наружу, Home / End, `*`, поиск по буквам. Слоты `#icon`, `#label`, `#actions`; строки на токенах контролов (размер и плотность)
107
+ - **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
108
+ - **TaoTimeline** — вертикальная лента событий: шаги заказа, релизы, журнал. `active` заливает линию до текущего события (`aria-current="step"`), без него лента — журнал прошедшего; `tone` и `icon` у маркера, слоты `#marker` / `#title` / `#content`; `align="alternate"` раскладывает события по обе стороны и складывается в одну уже 480px своей ширины
109
+ - **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
110
+ - **TaoCounter** — витрина числа с переворотом цифр (не инпут)
111
+ - **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`; метки под лентой — `indicator` (`dots`, `bars` или `progress`). С `autoplay` текущая метка заполняется за интервал, по заполнении слайд меняется; hover, фокус с клавиатуры, касание, скрытая вкладка и кнопка паузы останавливают, `prefers-reduced-motion` выключает
112
+ - **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
113
+ - **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
114
+ - **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info); `collapsible` сворачивает тело под заголовок (поиск по странице его всё равно находит)
115
+ - **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
116
+ - **TaoScrubber** — play / pause, слайдер по времени с метками событий, подпись «время / длина». Время сама не двигает: ведите `v-model` своими часами
117
+ - **TaoLoader** — анимированный лоадер (четыре точки)
118
+ - **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
119
+ - **TaoIcon** — SVG-иконки (29 встроенных, свои через `registerTaoIcons`) или icon-шрифт (см. раздел «Иконки» ниже)
120
+
121
+ ### Навигация и взаимодействие
122
+
123
+ - **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
124
+ - **TaoBreadcrumb** — крошки: последний пункт — текущая страница
125
+ - **TaoDropdownMenu** / **TaoMenu** — меню из простого дерева данных `items`: подменю, чекбоксы, радио, разделители, подписи групп, сочетания для показа, недоступные пункты. Стрелки, Home / End, быстрый поиск по букве, `→` / `←` для подменю, Esc закрывает верхний уровень первым. `TaoMenu` — сама панель для своих оболочек (полоса меню, контекстное меню); у края экрана переворачивается
126
+ - **TaoMenubar** / **TaoContextMenu** — полоса меню редактора и меню по правой кнопке, на `TaoMenu`. Полоса — одна остановка Tab (`role="menubar"`): `←` / `→` ходят по ней, `↓` / Enter открывают, при открытом меню `←` / `→` и указатель переходят к соседнему; пункт без `items` — обычное действие. Контекстное меню открывается у указателя (или у элемента для клавиши Menu / Shift+F10) и оборачивает содержимое без своей коробки
127
+ - **TaoScrollTop** — плавающая кнопка «наверх»: виды `solid` / `ghost` / `text`, `side`, подпись `label` при наведении мыши. Появляется при обратном скролле после `boundary`
128
+
129
+ ### Обратная связь
130
+
131
+ - **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
132
+ - **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
133
+ - **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
134
+
135
+ ## Соглашения
136
+
137
+ Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral` (тип `TaoTone`), всегда через проп `tone`: Button, Alert, Tag (`toast.danger()` для тостов). Акцент — тоже тон и тон по умолчанию. Тон — контекстный класс, как размер: `.tao-tone-danger` на любом элементе выставляет `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (см. `styles/tone.css`). В отличие от размера, он **не** наследуется: кнопка внутри красного alert остаётся акцентной.
138
+ Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
139
+
140
+ Размеры контролов: `small` | `medium` | `large` (тип `TaoSize`). Одна шкала для Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup и FormField — контролы одного размера встают в ряд ровно. Checkbox, Radio / RadioGroup и Switch масштабируют индикатор (14 / 18 / 22px) и подпись; Tag — высоту (18 / 20 / 24px); Tabs, кнопки Pagination и строки List берут высоту Button; Table масштабирует отступы ячеек (`size="small"` для плотной); FileDrop — зону и строки файлов; Slider — трек и бегунок.
141
+ Без `size` контрол берёт размер предков, в корне — `medium`. На целый блок размер задаётся классом `tao-size-small` / `-medium` / `-large` на любом элементе или `size` у `TaoFormField` / `TaoInputGroup`. Явный `size` у контрола главнее.
142
+
143
+ ```vue
144
+ <div class="tao-size-small">
145
+ <TaoInput v-model="q" />
146
+ <TaoButton>Найти</TaoButton>
147
+ </div>
148
+ ```
149
+
150
+ Контент и раскладка держат свою шкалу и не наследуют: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (пиксели).
151
+ Container живёт на другой оси — ширина: `width="wide" | "slim" | "ultra-slim"`.
152
+
153
+ **Плотность** — вторая ось контролов поверх размера: класс `tao-density-compact` / `-comfortable` / `-auto` на контейнере (или на `<html>`) меняет высоту и отступы любого размера в нём, но не шрифт. `comfortable` даёт 34 / 44 / 52px (строки под палец), `compact` 22 / 32 / 40px (плотные инструменты и таблицы), `auto` — comfortable на сенсорном экране (`pointer: coarse`) и обычная с мышью. Select и Combobox переносят её в свои панели. Тип `TaoDensity`; шаги — токены `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
154
+
155
+ ```html
156
+ <html class="tao-density-auto">
157
+ ```
158
+
159
+
160
+ Поверхности — из чего «сделана» панель: `flat` — заливка (по умолчанию), `grain` — статичное плёночное зерно, `glass` —
161
+ полупрозрачное стекло с размытием того, что позади. Проп `surface` у TaoCard / TaoBlock или класс `tao-surface-grain` /
162
+ `-glass` на любом элементе — HUD в игре, секция лендинга, сайдбар. Вид настраивается один раз токенами темы
163
+ (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill` / `-border` / `-blur`). Поверхность принадлежит одному элементу:
164
+ вложенные панели её не наследуют. Стеклу нужно что-то позади — используйте его для того, что лежит поверх контента; над
165
+ ровным фоном это просто серая заливка, над анимацией размытие пересчитывается каждый кадр. Toast и confirm стеклянные по
166
+ умолчанию, с оттенком своего тона; `toast.defaults({ surface: 'flat' })` и `confirm.defaults({ surface: 'flat' })`
167
+ выключают стекло, `.surface('flat')` — для одного. Без поддержки размытия или при `prefers-reduced-transparency` стекло
168
+ становится сплошной панелью.
169
+
170
+ Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
171
+ Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
172
+
173
+ Правила API — им следуют все компоненты:
174
+
175
+ - **Поля** принимают `v-model`, `disabled`, `error` (красная рамка) и `size`. Подпись, подсказка и текст ошибки — через `TaoFormField`.
176
+ - **События**: `update:X` для v-model плюс `change`, когда пользователь закончил изменение (Slider, Split — по отпусканию). Остальные события — глаголы в настоящем времени: `select`, `close`, `create`.
177
+ - **Тексты**: видимые — `*Text` (`clearText`, `successText`), для скринридера — `*Label` (`closeLabel`).
178
+ - **Списки**: массивы данных — `items`; выбираемые элементы несут `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Идентификаторы обычных данных (колонки таблицы, стадии) остаются `key`.
179
+ - **Булевы** — прилагательные без `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Ось раскладки — `direction: 'row' | 'column'`, не `vertical`.
180
+ - **Длины** (`padding`, `radius`, `gap`, `maxHeight`): число — пиксели, строка уходит в CSS как есть (тип `TaoLength`).
181
+
182
+ ## Типографика
183
+
184
+ Слой включается явно: библиотека не оформляет голые `h1` и `p`. Поставьте `.tao-prose` на обёртку — и текст внутри
185
+ получит заголовки, абзацы, списки, цитаты, код, линии и ссылки в ролях темы, с отступами по близости (заголовок ближе
186
+ к своему тексту и дальше от блока перед ним). Все правила внутри в `:where()`, поэтому ваш CSS всегда главнее.
187
+
188
+ ```html
189
+ <article class="tao-prose">
190
+ <h1>Заголовок</h1>
191
+ <p>Текст со <a href="/docs">ссылкой</a>.</p>
192
+ </article>
193
+
194
+ <h2 class="tao-heading-5">h2 размером с уровень 5</h2>
195
+ ```
196
+
197
+ Шкала заголовков — из двух чисел: `--tao-text-base` (16px, текст и h6) и `--tao-text-ratio` (1.25), каждый уровень выше —
198
+ ещё один шаг: 16 / 20 / 25 / 31 / 39 / 49. Поставьте коэффициент на `:root` или на одну обёртку (1.2 спокойнее, 1.333
199
+ смелее) — шкала под ней последует; h1 и h2 уменьшаются на узком экране, но не ниже h3 / h4. Шаги — токены
200
+ `--tao-heading-1…6` для своих правил. `.tao-heading-1…6` даёт вид уровня любому тегу: тег говорит, что это, класс —
201
+ какого размера.
202
+
203
+ ### Для ИИ-ассистентов
204
+
205
+ В пакете есть skill, `skills/taoui/SKILL.md` с `references/components.md`: подключение, правила (роли, а не цвета; контексты, а не пропсы), каждый компонент и его пропсы, типичные ошибки. Покажите его ассистенту; для Claude Code скопируйте `node_modules/@1337exp/taoui/skills/taoui` в `.claude/skills/` проекта. Справочник компонентов генерируется из таблиц пропсов шоукейса (`npm run skill`), а тест следит, чтобы skill называл каждый компонент.
206
+
207
+ ## Иконки
208
+
209
+ Библиотека поставляет **29 SVG-иконок** (галочка, крестик, плюс, минус, шевроны, стрелки, поиск, глаз, «ещё», ручка,
210
+ play, pause, skip-back, копия, календарь, info, alert, кружки, папка, файл). Они рисуются через `currentColor`: иконка берёт цвет и
211
+ размер текста. Имена с зарезервированной приставкой `tao-`: `<TaoIcon name="tao-check" />`, список — `taoIconNames`.
212
+
213
+ ```vue
214
+ <TaoIcon name="tao-check" /> <!-- встроенная -->
215
+ <TaoIcon name="rocket" /> <!-- из registerTaoIcons или `icon-rocket` вашего шрифта -->
216
+ <TaoButton icon="tao-plus">Добавить</TaoButton>
217
+ <TaoButton icon="tao-close" aria-label="Закрыть" /> <!-- только иконка: квадрат, aria-label обязателен -->
218
+ ```
219
+
220
+ ```ts
221
+ registerTaoIcons({ rocket: { body: '<path d="M12 3l4 8-4 10-4-10z"/>' } }); // сетка 24x24, если не задан viewBox
222
+ ```
223
+
224
+ Имя без приставки `tao-` ищется среди зарегистрированных вами иконок, а затем рендерится классом `icon-<name>` для
225
+ внешнего icon-шрифта (IcoMoon / Fontello и т. п.), который приложение подключает само. Все встроенные части (крестики,
226
+ степперы, стрелки пагинации, тосты…) используют встроенные иконки, а слоты `#…-icon` позволяют заменить их чем угодно.
227
+
228
+ ## Установка
229
+
230
+ ```bash
231
+ npm install @1337exp/taoui
232
+ ```
233
+
234
+ Нужен Vue 3.4+. Пакет **только ESM** (Vite, Nuxt 3, webpack 5 и Node 18+ с `import` работают; голый `require('@1337exp/taoui')` — нет: используйте `import()`).
235
+
236
+ ### Поддержка браузеров
237
+
238
+ CSS использует `color-mix()`, контейнерные запросы и зарегистрированные свойства (`@property`), поэтому планка —
239
+ **Chrome / Edge 111, Safari 16.4, Firefox 128**: браузеры 2023–2024 годов. Ограничивает Firefox 128 (`@property`).
240
+ В более старом браузере всё остаётся читаемым, теряется мелочь: именно зарегистрированное свойство не даёт тону
241
+ (`.tao-tone-*`) и поверхности «протекать» в детей, поэтому без него Button внутри красного Alert может покраснеть.
242
+ Тот же список — поле `browserslist` пакета и целевая платформа сборки.
243
+
244
+ Или локально из папки:
245
+
246
+ ```bash
247
+ npm install ../path-to-tao-ui
248
+ ```
249
+
250
+ ## Использование
251
+
252
+ ### Подключение в Nuxt 3
253
+
254
+ Создайте плагин `plugins/tao-ui.ts`:
255
+
256
+ ```typescript
257
+ import { defineNuxtPlugin } from '#app'
258
+ import TaoUI from '@1337exp/taoui'
259
+
260
+ export default defineNuxtPlugin((nuxtApp) => {
261
+ nuxtApp.vueApp.use(TaoUI)
262
+ })
263
+ ```
264
+
265
+ Импортируйте стили в `app.vue` или layout:
266
+
267
+ ```vue
268
+ <script setup>
269
+ import '@1337exp/taoui/styles.css'
270
+ </script>
271
+ ```
272
+
273
+ ### Подключение в Vue 3 проекте
274
+
275
+ ```javascript
276
+ // main.js
277
+ import { createApp } from 'vue'
278
+ import App from './App.vue'
279
+ import TaoUI from '@1337exp/taoui'
280
+ import '@1337exp/taoui/styles.css'
281
+
282
+ const app = createApp(App)
283
+ app.use(TaoUI)
284
+ app.mount('#app')
285
+ ```
286
+
287
+ ### Язык
288
+
289
+ Встроенные тексты (плейсхолдеры, «Очистить», aria-подписи, даты) по умолчанию английские. Русский идёт в комплекте:
290
+
291
+ ```javascript
292
+ import TaoUI, { localeRu } from '@1337exp/taoui'
293
+
294
+ app.use(TaoUI, { locale: localeRu })
295
+ ```
296
+
297
+ Поменять отдельные тексты — остальное останется от локали по умолчанию:
298
+
299
+ ```javascript
300
+ app.use(TaoUI, { locale: { select: { placeholder: 'Выберите город' } } })
301
+ ```
302
+
303
+ Другой язык: скопируйте `localeEn` (или `localeRu`), переведите и передайте так же (тип `TaoLocale`). Ключи повторяют имена пропсов —
304
+ `locale.select.placeholder` — значение по умолчанию для `placeholder` у TaoSelect, а переданный руками проп всегда главнее.
305
+
306
+ Язык можно переключать в любой момент — из настроек, переключателя языка, по маршруту. Уже показанные компоненты
307
+ обновятся сразу, без перезагрузки и без потери введённого:
308
+
309
+ ```javascript
310
+ import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
311
+
312
+ function onLanguageChange(lang) {
313
+ setTaoLocale(lang === 'ru' ? localeRu : localeEn)
314
+ }
315
+ ```
316
+
317
+ Без плагина (отдельные компоненты) достаточно одного вызова `setTaoLocale()`.
318
+
319
+ ### Переход на 5.0
320
+
321
+ 5.0 удаляет все имена, которые устарели в 2.0 (и алиас тона `error`), таблица «старое → новое» в [MIGRATION-5.md](MIGRATION-5.md).
322
+
323
+ ### Переход с 3.x
324
+
325
+ В 4.0 поменялся один умолчательный параметр: встроенные тексты теперь английские (раньше были русские). Чтобы остаться
326
+ на русском, передайте локаль один раз: `app.use(TaoUI, { locale: localeRu })`, а без плагина — `setTaoLocale(localeRu)`.
327
+ Хелперы дат и компоненты дат следуют локали и по умолчанию тоже `en-US`.
328
+
329
+ ### Переход с 1.x
330
+
331
+ Смотрите запись 2.0.0 в [CHANGELOG.md](CHANGELOG.md): что сломалось. Старые имена удалены в 5.0.
332
+
333
+ ### Использование отдельных компонентов
334
+
335
+ ```vue
336
+ <script setup>
337
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
338
+ import '@1337exp/taoui/styles.css'
339
+ </script>
340
+
341
+ <template>
342
+ <TaoButton variant="primary">Нажми меня</TaoButton>
343
+ <TaoFormField label="Введите текст">
344
+ <TaoInput v-model="text" />
345
+ </TaoFormField>
346
+ <TaoModal v-model="isOpen" title="Заголовок">
347
+ Содержимое модального окна
348
+ </TaoModal>
349
+ </template>
350
+ ```
351
+
352
+ ## Split
353
+
354
+ `TaoSplit` — две панели и полоса между ними. Это не `TaoDivider` (там только линия) и не раскладка на N панелей: три колонки — два вложенных сплита.
355
+
356
+ `direction` как у Flex: `row` (start | end) или `column` (start над end). Слоты `#start` / `#end`.
357
+
358
+ `v-model` — размер панели start. `unit` — `%` (по умолчанию, доля живёт при ресайзе контейнера) или `px` (сайдбар; вторая панель забирает остаток). Для `px` размер нужно задать явно: дефолт `50` — это 50px. `min` / `max` ограничивают start, `min-end` — минимум второй панели, все в той же единице. `resizable="false"` оставляет полосу, но без перетаскивания.
359
+
360
+ Сплит заполняет родителя (`width` / `height: 100%`). Родитель должен ограничить размер по оси сплита: у `column` без высоты не из чего считать `%`. Панели с `min-width` / `min-height: 0` и `overflow: hidden`, чтобы контент не мешал сжатию. Скролл — на внутренней обёртке (`overflow: auto; height: 100%; min-height: 0`). Вложенный `TaoSplit` прямым ребёнком панели растягивается сам.
361
+
362
+ ```vue
363
+ <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
364
+ <template #start>Навигация</template>
365
+ <template #end>Основное</template>
366
+ </TaoSplit>
367
+ ```
368
+
369
+ ## Toast
370
+
371
+ Вызов — цепочка в одном тике, `setTimeout(0)` отправляет уведомление.
372
+
373
+ ```javascript
374
+ import { toast } from '@1337exp/taoui'
375
+
376
+ toast().success().message('Сохранено')
377
+ toast().danger().title('Сеть').timeout(5000).message('Нет соединения')
378
+ toast.success('Сохранено')
379
+ toast.warning('Черновик', { timeout: 1000 })
380
+ ```
381
+
382
+ Позиция по умолчанию — `topCenter`. Глобально:
383
+
384
+ ```javascript
385
+ toast.defaults({ position: 'bottomRight' })
386
+ toast.byBottomRight()
387
+ ```
388
+
389
+ `question` с оверлеем в kit нет — это confirm, не toast. Кнопки в тосте, если нужны:
390
+
391
+ ```javascript
392
+ toast().info().message('Удалить файл?').action('Удалить', onRemove)
393
+ ```
394
+
395
+ Viewport можно не вставлять: первый вызов сам создаст его. Если нужен явный контроль (тесты, свой layout):
396
+
397
+ ```vue
398
+ <TaoToastViewport />
399
+ ```
400
+
401
+ ## Confirm
402
+
403
+ Вопрос с оверлеем: всплывает по центру и спрашивает. Это не toast — нет прогресс-бара и автозакрытия, есть `await`, Esc и клик по оверлею = отмена.
404
+
405
+ ```javascript
406
+ import { confirm } from '@1337exp/taoui'
407
+
408
+ if (await confirm().title('Удалить файл?').message('Это нельзя отменить').danger()) {
409
+ remove()
410
+ }
411
+
412
+ const ok = await confirm('Выйти без сохранения?', {
413
+ ok: 'Выйти',
414
+ cancel: 'Остаться',
415
+ })
416
+ ```
417
+
418
+ Очередь: второй `confirm()`, пока открыт первый, подождёт. Подписи по умолчанию — «ОК» / «Отмена»:
419
+
420
+ ```javascript
421
+ confirm.defaults({ ok: 'Yes', cancel: 'No' })
422
+ ```
423
+
424
+ ## Формы
425
+
426
+ `TaoFormField` вешает общий label / hint / error и прокидывает `id` во вложенный контрол.
427
+
428
+ ```vue
429
+ <TaoFormField label="Город" hint="Необязательно">
430
+ <TaoSelect v-model="city" :options="cities" />
431
+ </TaoFormField>
432
+
433
+ <TaoSwitch v-model="dark" label="Тёмная тема" />
434
+
435
+ <TaoRadioGroup v-model="plan" legend="Тариф">
436
+ <TaoRadio value="free" label="Free" />
437
+ <TaoRadio value="pro" label="Pro" />
438
+ </TaoRadioGroup>
439
+
440
+ <TaoSegmented v-model="period" legend="Период">
441
+ <TaoSegmentedOption value="week">Неделя</TaoSegmentedOption>
442
+ <TaoSegmentedOption value="month">Месяц</TaoSegmentedOption>
443
+ <TaoSegmentedOption value="year">Год</TaoSegmentedOption>
444
+ </TaoSegmented>
445
+
446
+ <TaoAlert tone="warning" title="Черновик">Сохраните, прежде чем уйти.</TaoAlert>
447
+ ```
448
+
449
+ `TaoSegmented` — короткий взаимоисключающий выбор, все варианты видны сразу. Не для навигации по страницам: это `TaoTabs`. Длинные подписи или больше 5–6 пунктов — `TaoRadioGroup` или `TaoSelect`.
450
+
451
+ `TaoSelect` открывается с клавиатуры (стрелки, Enter, Esc), список переворачивается у края экрана. Delete или «Очистить» внизу списка сбрасывает значение в `null`.
452
+
453
+ Если `null` не допустим (шаг сетки, порядок сортировки), передайте `:clearable="false"`: строка сброса и Delete / Backspace пропадут. Подпись строки сброса — `clear-text`, для иконки или своей разметки есть слот `#clear`. `size` — `small` / `medium` / `large` (без него — от предков), масштабирует и раскрытый список.
454
+
455
+ ```vue
456
+ <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
457
+
458
+ <TaoSelect v-model="city" :options="cities">
459
+ <template #clear><TaoIcon name="close" /> Сбросить</template>
460
+ </TaoSelect>
461
+ ```
462
+
463
+ `TaoCombobox` — то же меню, но с полем. Печатаете — варианты режутся. `allow-create` пишет введённое в `v-model`, если точного совпадения нет. Список сам не меняется: слушайте `create` и добавьте option снаружи.
464
+
465
+ Подпись, подсказка и текст ошибки всегда идут через `TaoFormField`. `TaoFormField` также оборачивает `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup` и `TaoSegmented` — id, hint и error прокидываются сами.
466
+
467
+ `TaoTag` может быть чипом: `#prefix` слева (обычно `TaoAvatar`), `closable` рисует крестик и эмитит `close`. Клик по крестику наружу не всплывает. `flat` снимает рамку, заливка остаётся.
468
+
469
+ ```vue
470
+ <TaoTag tone="neutral" closable @close="remove">
471
+ <template #prefix>
472
+ <TaoAvatar name="Анна Козлова" size="small" />
473
+ </template>
474
+ Анна Козлова
475
+ </TaoTag>
476
+ ```
477
+
478
+ ## Таблица и пагинация
479
+
480
+ Таблица рендерит то, что передали: сама данные не режет и не сортирует. Это удобно и для серверной выборки, и для клиентской — страница режется снаружи.
481
+
482
+ ```vue
483
+ <TaoTable
484
+ :columns="columns"
485
+ :rows="pageRows"
486
+ v-model:sort="sort"
487
+ empty-text="Пока нет записей"
488
+ >
489
+ <template #cell-status="{ row }">
490
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
491
+ {{ row.status }}
492
+ </TaoTag>
493
+ </template>
494
+ </TaoTable>
495
+
496
+ <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
497
+ ```
498
+
499
+ ```javascript
500
+ const columns = [
501
+ { key: 'name', label: 'Имя', sortable: true },
502
+ { key: 'city', label: 'Город' },
503
+ { key: 'status', label: 'Статус' },
504
+ ]
505
+ ```
506
+
507
+ Слот `cell-<ключ>` перекрывает ячейку. `loading` показывает оверлей, пустой список — текст или слот `#empty`. Клик по шапке с `sortable` крутит `asc → desc → сброс`.
508
+
509
+ ## Пустые состояния и загрузка
510
+
511
+ ```vue
512
+ <TaoEmpty title="Ничего не нашлось">
513
+ Измените фильтр или сбросьте поиск.
514
+ <template #action>
515
+ <TaoButton variant="secondary">Сбросить</TaoButton>
516
+ </template>
517
+ </TaoEmpty>
518
+
519
+ <TaoSkeleton variant="title" />
520
+ <TaoSkeleton :lines="3" />
521
+ <TaoSkeleton variant="circle" />
522
+
523
+ <TaoStages :items="[
524
+ { key: 'pay', label: 'Оплата', status: 'ok' },
525
+ { key: 'pack', label: 'Сборка', status: 'work' },
526
+ { key: 'ship', label: 'Доставка', status: 'wait' },
527
+ ]" />
528
+
529
+ <TaoList>
530
+ <TaoListItem
531
+ title="Анна Козлова"
532
+ description="Дизайн · Москва"
533
+ clickable
534
+ :selected="picked === 'anna'"
535
+ @click="picked = 'anna'"
536
+ >
537
+ <template #prefix>
538
+ <TaoAvatar name="Анна Козлова" size="small" />
539
+ </template>
540
+ </TaoListItem>
541
+ </TaoList>
542
+ ```
543
+
544
+ ```vue
545
+ <TaoInput v-model="q" placeholder="Найти…">
546
+ <template #prefix>⌕</template>
547
+ </TaoInput>
548
+
549
+ <TaoInputGroup>
550
+ <template #before>https://</template>
551
+ <TaoInput v-model="host" placeholder="example.com" />
552
+ <template #after>
553
+ <TaoButton>Проверить</TaoButton>
554
+ </template>
555
+ </TaoInputGroup>
556
+
557
+ <form @submit.prevent="onSave">
558
+ <TaoFormField label="Email">
559
+ <TaoInput v-model="email" type="email" />
560
+ </TaoFormField>
561
+ <TaoButton type="submit">Сохранить</TaoButton>
562
+ </form>
563
+
564
+ <TaoFormField label="Количество">
565
+ <TaoInputNumber v-model="qty" :min="1" :max="99" />
566
+ </TaoFormField>
567
+
568
+ <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
569
+
570
+ <TaoFormField label="День доставки" hint="В модели всегда YYYY-MM-DD">
571
+ <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
572
+ </TaoFormField>
573
+
574
+ <TaoFormField label="Даты поездки">
575
+ <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
576
+ </TaoFormField>
577
+
578
+ <TaoCounter :value="score" :max-digits="6" />
579
+
580
+ <TaoCarousel :autoplay="4000" loop indicator="bars">
581
+ <article v-for="item in banners" :key="item.id" class="hero">
582
+ <strong>{{ item.title }}</strong>
583
+ <span>{{ item.text }}</span>
584
+ </article>
585
+ </TaoCarousel>
586
+ <TaoCarousel :peek="72" :controls="false" indicator="dots">…</TaoCarousel>
587
+ <TaoCarousel v-model="slide" :per-view="5" :peek="28">
588
+ <template #prev></template>
589
+ <template #next="{ go, disabled }">
590
+ <button type="button" :disabled="disabled" @click="go">вперёд</button>
591
+ </template>
592
+ <article v-for="item in products" :key="item.id">…</article>
593
+ </TaoCarousel>
594
+ ```
595
+
596
+ `TaoDrawer` — лист сбоку, не модалка по центру:
597
+
598
+ ```vue
599
+ <TaoDrawer v-model="open" title="Фильтры">
600
+ ...
601
+ </TaoDrawer>
602
+ ```
603
+
604
+ ## Дизайн-токены и темизация
605
+
606
+ Стили библиотеки построены слоями. Компоненты **никогда** не обращаются к цветам/размерам
607
+ напрямую: они читают семантические роли и контексты на них (размер, тон, поверхность).
608
+ Это и есть механизм темизации: переопределяете 20-30 переменных — меняется
609
+ внешний вид всех компонентов сразу, без правок самих компонентов.
610
+
611
+ ```
612
+ tokens/primitives.css → tokens/semantic.css → themes/*.css → contexts/*.css → base.css
613
+ сырые цвета, шкалы скругления, тени, цветовые роли классы размера, сброс
614
+ не трогать шрифт, движение каждой темы тона, поверхности
615
+ ```
616
+
617
+ ### Слои
618
+
619
+ | Файл (в `src/styles/`) | Назначение | Трогать? |
620
+ |---|---|---|
621
+ | `tokens/primitives.css` | Сырая палитра, шкалы отступов/радиусов/теней (`--tao-orange-400`, `--tao-space-3`...) | Обычно нет |
622
+ | `tokens/semantic.css` | Роли, не зависящие от темы: скругления, тени, шрифт, движение | Редко |
623
+ | `themes/dark.css` | Цветовые роли темы по умолчанию (dark): `--tao-color-accent`, `--tao-color-surface`, ... | **Да — это и есть API темизации** |
624
+ | `themes/light.css` | Те же роли под `[data-tao-theme="light"]` | Да, как образец |
625
+ | `contexts/size.css`, `tone.css`, `surface.css` | `.tao-size-*` и `.tao-density-*`, `.tao-tone-*`, `.tao-surface-*`: что контрол читает, чтобы знать размер, цвет и материал | Редко |
626
+ | `base.css` | Глобальный reset (скроллбар, ссылки, box-sizing) | Редко |
627
+
628
+ Всё подключается одним файлом `@1337exp/taoui/styles.css` (и dark, и light: light включается атрибутом `data-tao-theme="light"`).
629
+ Сырые файлы доступны как `@1337exp/taoui/styles/tokens/primitives.css` и так далее.
630
+
631
+ ### Как сделать свою тему
632
+
633
+ Тема — это просто переопределение семантических токенов под своим селектором.
634
+ Ничего в компонентах менять не нужно:
635
+
636
+ ```css
637
+ /* my-brand-theme.css */
638
+ [data-tao-theme="my-brand"] {
639
+ --tao-color-accent: #6c5ce7;
640
+ --tao-color-accent-hover: #5a4bd1;
641
+ --tao-color-bg: #0f0f1a;
642
+ --tao-color-surface: #0f0f1a;
643
+ --tao-color-surface-raised: #1a1a2e;
644
+ --tao-color-text: #d6d6e8;
645
+ --tao-color-text-strong: #ffffff;
646
+ /* остальные роли см. themes/dark.css */
647
+ }
648
+ ```
649
+
650
+ ```vue
651
+ <!-- app.vue -->
652
+ <template>
653
+ <div data-tao-theme="my-brand">
654
+ <NuxtPage />
655
+ </div>
656
+ </template>
657
+ ```
658
+
659
+ Или переключайте тему целиком на `<html>`, чтобы стилизовать модалки/тултипы,
660
+ которые телепортируются в `body`:
661
+
662
+ ```javascript
663
+ document.documentElement.setAttribute('data-tao-theme', 'light')
664
+ ```
665
+
666
+ ### Ключевые группы токенов
667
+
668
+ - `--tao-color-accent*` — акцентный/брендовый цвет (кнопки primary, активные вкладки, ссылки)
669
+ - `--tao-color-on-accent` — текст на акцентном фоне
670
+ - `--tao-color-selection`, `--tao-color-selection-text` — выделение текста (`::selection`)
671
+ - `--tao-color-surface*` — фоны контейнеров (обычный / приподнятый / утопленный / hover)
672
+ - `--tao-color-border*` — границы
673
+ - `--tao-color-text*` — текст (обычный / усиленный / subtle / приглушённый / disabled)
674
+ - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — статусные цвета
675
+ - `--tao-color-input-*` — поля ввода отдельно, т.к. фон/текст полей часто не совпадают с surface/text
676
+ - `--tao-radius-control`, `--tao-radius-panel` — скругления (мелкие контролы vs крупные панели)
677
+ - `--tao-shadow-panel`, `--tao-shadow-overlay` — тени
678
+ - `--tao-font-size-*` — шкала кегля в `primitives.css`: `xs`–`xl` контролы, `2xl`–`4xl` заголовки / проза
679
+ - `--tao-control-height-*` (26 / 36 / 44px), `--tao-control-padding-x-*`, `--tao-control-padding-y-*`, `--tao-control-font-size-*`, `--tao-control-font-size-secondary-*`, `--tao-button-padding-x-*`, `--tao-indicator-size-*`, `--tao-tag-height-*` / `-padding-x-*` / `-font-size-*` — шкала размеров в `primitives.css`. Компоненты читают текущие значения из `contexts/size.css`: `--tao-control-height`, `--tao-control-padding-x` / `-y`, `--tao-control-font-size`, `--tao-control-font-size-secondary`, `--tao-button-padding-x`, `--tao-indicator-size`, `--tao-tag-height` / `-padding-x` / `-font-size`. Используйте их в своих контролах, чтобы попасть в размер окружения.
680
+
681
+ Полный список цветовых ролей — в `src/styles/themes/dark.css`, это файл,
682
+ который стоит открыть, чтобы понять весь доступный API темизации.
683
+
684
+ ### Палитры
685
+
686
+ Палитра — это четыре цвета от самого тёмного к самому светлому: из них получается целый набор ролей для тёмного и светлого режимов.
687
+ Готовы семь (`sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon`; список — `taoPalettes`).
688
+
689
+ ```javascript
690
+ import '@1337exp/taoui/styles.css'
691
+ import '@1337exp/taoui/palettes.css' // все сразу, или '@1337exp/taoui/styles/palettes/sunset.css' для одной
692
+ ```
693
+
694
+ ```html
695
+ <html data-tao-theme="sunset"> <!-- тёмная -->
696
+ <html data-tao-theme="sunset" data-tao-mode="light"> <!-- её светлая версия -->
697
+ ```
698
+
699
+ `data-tao-mode="light" | "dark"` работает и сам по себе, с цветами по умолчанию; `data-tao-theme="light"` — старая запись того же.
700
+ Ставьте на `<html>` (чтобы модалки и тултипы, вынесенные в `body`, следовали) или на любой элемент для части страницы.
701
+
702
+ Что палитра решает за вас:
703
+
704
+ - **Акцент** — стоп, чья яркость подходит режиму (укажите `accent: 1`, если автоматический выбор не тот), сдвинутый только по яркости, пока он виден на странице (3:1), несёт читаемый текст (4.5:1) и сам читается как текст (`--tao-color-accent-text`, 4.5:1).
705
+ - **Страница и поверхности** — очень тёмный (или очень светлый) оттенок самого глубокого цвета палитры.
706
+ - **Статусы** (`danger`, `warning`, `success`, `info`) остаются в своём узнаваемом секторе оттенка, но делят с палитрой яркость и насыщенность, а статус, который спутали бы с акцентом, отодвигается (палитра может назвать свой цвет: `status: { success: '#7fbf2f' }`). У каждого статуса 4.5:1 для текста, как заливка и как текст.
707
+ - **`--tao-color-accent-2`, `--tao-glow`, `--tao-gradient`, `--tao-bg-atmosphere`:** второй акцент, цвет свечения, градиент через четыре стопа и мягкое свечение за страницей (рисует `class="tao-atmosphere"` на `<body>` или корне приложения; статичный слой, без blur).
708
+
709
+ Контраст — не обещание в README: `tests/palette.test.ts` держит каждую палитру в обоих режимах на этих числах.
710
+
711
+ Своя палитра в рантайме (редактор тем, цвет, выбранный пользователем):
712
+
713
+ ```javascript
714
+ import { applyTaoPalette } from '@1337exp/taoui'
715
+
716
+ const stop = applyTaoPalette({ name: 'mine', label: 'Mine', stops: ['#102030', '#306090', '#60c0f0', '#e0f4ff'] }, 'dark')
717
+ stop() // снимает её; третий аргумент кладёт палитру на один элемент вместо страницы
718
+ ```
719
+
720
+ или файлом: `taoPaletteCss(def)` возвращает CSS, из которого сделаны файлы пресетов. Чтобы добавить пресет в библиотеку, допишите его в `src/palettes.ts` и запустите `npm run palettes`.
721
+
722
+ #### Контраст: WCAG 2 и APCA
723
+
724
+ У каждой пары цветов два вопроса, и на них отвечают две разные модели.
725
+
726
+ **Допустимо ли?** Контраст WCAG 2: `(L1 + 0.05) / (L2 + 0.05)` от относительных яркостей, от 1 до 21. Это действующий
727
+ стандарт (его проверяют аудиты доступности), поэтому все числа, которые обещают палитры, — по WCAG 2: 4.5:1 для текста,
728
+ 3:1 для заливки, видимой на странице. Считает `contrastRatio(a, b)`.
729
+
730
+ **Что читается лучше?** У WCAG 2 известное слепое пятно: светлое и тёмное для неё симметричны, и на цветах средней
731
+ яркости она переоценивает чёрный. На зелёном `#2ea85c` она говорит «чёрный 6.4:1 против белого 3.1:1», хотя глаз явно
732
+ лучше читает белый. APCA (Accessible Perceptual Contrast Algorithm, модель черновика WCAG 3) следует тому, как мы видим:
733
+ светлый текст на тёмном и тёмный на светлом не симметричны, тонкому тексту нужно больше. Она даёт контраст яркости
734
+ **Lc** примерно от −108 до 106 (знак — полярность: минус — светлый текст на тёмном); около 75 — основной текст, 60 —
735
+ подпись, 45 — крупный заголовок. Считает `apcaContrast(text, background)`.
736
+
737
+ | На `#2ea85c` | WCAG 2 | APCA Lc |
738
+ |---|---|---|
739
+ | чёрный текст | **6.4 : 1** | 47 |
740
+ | белый текст | 3.1 : 1 | **62** |
741
+
742
+ Поэтому палитры берут обе модели, каждую для своего:
743
+
744
+ 1. **Полярность по APCA.** В светлом режиме подпись на заливке (акцент, статус) — тот цвет, который APCA читает лучше;
745
+ на средних тонах это белый.
746
+ 2. **Числа по WCAG 2.** Потом заливка сдвигается по яркости, пока подпись не наберёт 4.5:1: белая подпись на среднем
747
+ тоне получает чуть более глубокую заливку, а не слабую подпись.
748
+ 3. **В тёмном режиме подпись тёмная.** Там заливки светлые нарочно (чтобы их было видно на тёмной странице), а на
749
+ светлой заливке тёмный текст лучше в обеих моделях.
750
+
751
+ Проверки — в `tests/palette.test.ts`: каждая палитра, оба режима, каждая заливка. Если подбираете свои цвета, обе функции
752
+ экспортированы — пользуйтесь так же: APCA, чтобы выбрать, WCAG 2, чтобы обещать.
753
+
754
+ ### Если нужна тема с нуля, без primitives
755
+
756
+ ```javascript
757
+ import '@1337exp/taoui/styles/tokens/primitives.css' // шкалы можно оставить
758
+ import '@1337exp/taoui/styles/tokens/semantic.css' // скругления, тени, шрифт, движение
759
+ import './my-colour-roles.css' // ваши цветовые роли вместо themes/dark.css
760
+ import '@1337exp/taoui/styles/contexts/size.css' // контексты, которые читают компоненты
761
+ import '@1337exp/taoui/styles/contexts/tone.css'
762
+ import '@1337exp/taoui/styles/contexts/surface.css'
763
+ import '@1337exp/taoui/styles/base.css'
764
+ ```
765
+
766
+ ## Демонстрация
767
+
768
+ Все компоненты с живыми примерами, таблицами пропсов и готовыми сниппетами. Язык (EN / RU) и тема (dark / light) переключаются в шапке.
769
+
770
+ ```bash
771
+ cd showcase
772
+ npm install
773
+ npm run dev # или из корня репозитория: npm run showcase
774
+ ```
775
+
776
+ Showcase смотрит прямо в `src/`, поэтому правки компонентов видны без
777
+ `npm run build`. `npm run showcase:build` собирает статический сайт с относительными
778
+ путями — его можно положить в любую папку (например, `/sandbox/taoui/`).
779
+
780
+ Скриншоты и ролики в этом README сняты с showcase: см. [docs/media](docs/media/README.md).
781
+
782
+ ## Разработка
783
+
784
+ ```bash
785
+ # Сборка библиотеки
786
+ npm run build
787
+
788
+ # Режим разработки (watch)
789
+ npm run dev
790
+
791
+ # Проверка типов
792
+ npm run type-check
793
+
794
+ # Тесты (Vitest)
795
+ npm test
796
+ ```
797
+
798
+ ## Публикация в npm
799
+
800
+ Публикуется только `dist/` (собранная библиотека) и `src/styles/` (сырые
801
+ токены — чтобы можно было подключить `tokens/primitives.css` отдельно при
802
+ кастомной теме), плюс `README.md`, `LICENSE`, `CHANGELOG.md` и `MIGRATION-5.md`. Исходники компонентов (`src/components/*.vue`),
803
+ конфиги сборки и `showcase/` в пакет не попадают — они остаются в
804
+ репозитории; чтобы их получить, репозиторий клонируют.
805
+
806
+ `npm publish` **сам** прогоняет проверку типов, тесты и полную пересборку перед
807
+ публикацией (хук `prepublishOnly` в `package.json`) — так в реестр не
808
+ уедет пакет со старым или отсутствующим `dist/`. Собирать вручную перед
809
+ `npm publish` не нужно.
810
+
811
+ Проверить, что именно попадёт в пакет, без реальной публикации:
812
+
813
+ ```bash
814
+ npm pack --dry-run
815
+ ```
816
+
817
+ Токен публикации не должен лежать в репозитории: в `.npmrc` ссылайтесь на него как
818
+ `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` и задайте `NPM_TOKEN` в окружении.
819
+ `.npmrc` в любом случае в `.gitignore`.
820
+
821
+ ## Участие в проекте
822
+
823
+ Issues и pull request'ы приветствуются — см. [CONTRIBUTING.md](CONTRIBUTING.md).
824
+ Об уязвимостях: [SECURITY.md](SECURITY.md).
825
+
826
+ ## Лицензия
827
+
828
+ [MIT](LICENSE) © 2026 1337exp