@1337exp/taoui 5.1.1 → 5.4.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.
package/README.md CHANGED
@@ -1,828 +1,833 @@
1
- <h1 align="center">Tao UI</h1>
2
-
3
- <p align="center">
4
- <b>A Vue 3 component library driven by design tokens.</b><br>
5
- Change a handful of CSS variables and the whole kit follows.
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
- <b>English</b> · <a href="https://github.com/1337exp/taoui/blob/master/README.ru.md">Русский</a> ·
18
- <a href="#install">Install</a> ·
19
- <a href="#showcase">Showcase</a> ·
20
- <a href="CHANGELOG.md">Changelog</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 components in the dark theme" width="860">
25
- </p>
26
-
27
- ## Why Tao UI
28
-
29
- - **Tokens first.** Colours, radii, spacing and type come from CSS variables in three layers (primitives, semantic, theme). Re-theme the kit, or one panel of it, without touching a component.
30
- - **One scale, one API.** `small` / `medium` / `large` everywhere, the same `v-model` / `change` / `*Text` / `*Label` rules for every field, tones instead of ad-hoc colours.
31
- - **Dark and light** out of the box, plus surfaces (`flat` / `grain` / `glass`) for HUDs and landing pages.
32
- - **Built-in languages.** Placeholders, dates and aria labels in English and Russian, switchable at runtime without a reload.
33
- - **Nuxt and plain Vue.** `TaoLink` picks `NuxtLink`, `RouterLink` or `<a>` by itself. Fully typed, ES and CJS builds.
34
- - **Keyboard friendly.** Focus traps, `role` / `aria-*` on the controls.
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: square, hue strip, HEX / RGB / HSL modes"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, eyedropper, <code>v-model</code> is a hex string</sub></td>
39
- <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Dark and light themes switching"><br><sub><b>Themes</b> — one attribute, every component follows</sub></td>
40
- </tr>
41
- <tr>
42
- <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider with marks"><br><sub><b>TaoSlider / TaoRangeSlider</b> — marks, discrete scales, vertical</sub></td>
43
- <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="flat, grain and glass surfaces"><br><sub><b>Surfaces</b> — flat, grain, glass</sub></td>
44
- </tr>
45
- </table>
46
-
47
- ## Components
48
-
49
- ### Basics
50
-
51
- - **TaoBlock** — container with padding and radius
52
- - **TaoButton** — `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` colours any of them (accent by default, neutral, success, danger, warning, info)
53
- - **TaoCard** — card with media / header / title / footer slots and a `#corner` (a tag, a menu button). `#media` can be a photo or `TaoCarousel`; `closable` adds a cross and the `close` event. `flush` is a tile (no padding/shadow, fills the cell); `#overlay` is a scrim on the media; `stripe="top | left | bottom"` with `stripeTone` (a tone or the palette `gradient`) draws a coloured stripe the corners clip
54
- - **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
55
- - **TaoMarquee** — one line that never wraps: when it does not fit it runs round with fading edges and a pause at the start of every round, when it fits it stands still. Stops on hover, on focus and on a tap (WCAG 2.2.2); wraps with «reduce motion»; a screen reader reads it once. `text` or inline content in the slot, `speed`, `gap`, `fade` (the left fade takes that much room left of the text: give the parent the padding), `paused`
56
- - **TaoInput** — text field with v-model, validation, and `#prefix` / `#suffix` slots (icon or text inside the frame)
57
- - **TaoInputGroup** — outer glue: `#before` | field | `#after` (protocol, unit, button)
58
- - **TaoModal** — modal with animation and slots
59
- - **TaoDrawer** — side panel (filters, settings). Esc, backdrop click, focus trap — same as the modal
60
- - **TaoSpoiler** — disclosure. `v-model` and `aria-expanded`. Neighbours do not close each other
61
- - **TaoSpoilerGroup** — accordion: `v-model` is the open panel key (`null` = all closed); spoilers take `name`. Without `v-model` the group keeps that key itself
62
- - **TaoTabs** — tabbed sections
63
- - **TaoNav** — navigation between the sections of an app: one list of items (`icon`, `href`, `badge`), three looks. `layout="auto"` picks by the width of TaoNav itself (container queries, no JS): a bottom bar below 600px (more than five items: «More» with a menu), a rail with icons below 840px, a side panel with labels from 840px. With the page in its slot it lays the page out: the bar sticks to the bottom (safe area kept), the side list to the top. `select(id, event)` lets a router take over a link
64
- - **TaoTooltip** — hover hint. `placement`: `top` / `bottom` / `left` / `right`, each with `-start` / `-end`; flips at the viewport edge
65
- - **TaoPopover** — click panel with any slot content, Esc and outside click; `placement` as Tooltip. Not a tooltip, not an action menu
66
-
67
- ### Layout
68
-
69
- - **TaoContainer** — max-width (wide / slim / ultra-slim) and centering
70
- - **TaoFlex** — flexbox wrapper: justify / align / direction / wrap / gap
71
- - **TaoSpace** — even gap between children
72
- - **TaoGrid** / **TaoGridItem** — tiles: `min` is a catalog (auto-fill), `cols` is a bento. An adaptive bento takes values per width class of the grid itself (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — on a phone the big blocks take the row, small tiles stay three in a row, a side block goes down. A plain number keeps one column on a phone. `rowHeight` fixes the row height, as a mosaic wants. Not masonry
73
- - **TaoDivider** — `solid` (plain border) / `dashed` / `colored` (accent) / `gap`. Optional `text` sits in the middle of any of them; `fade` softens the line ends; `size` is for `gap` (small / medium / large)
74
- - **TaoSplit** — two panes and a gutter. `row` / `column` like Flex. `v-model` is the start size in `%` or `px`; `resizable="false"` locks the gutter. Not Divider.
75
- - **TaoFieldset** — grouped frame: `legend` sits on the top border, `align` is start / center / end
76
- - **TaoAnimatedBorder** — animated border wrapper: the rainbow, the colours of a `tone` (follows the theme) or your own `colors`; a still gradient with `prefers-reduced-motion`
77
-
78
- ### Forms
79
-
80
- - **TaoCheckbox** — checkbox with v-model, pre/post slots, and `indeterminate`
81
- - **TaoChecklist** — checkboxes with one model (the checked values): `select-all` with a mixed state, a `counter` «3 of 5», `strike` for a to-do list (a look only, the checkbox tells the state), `description` per item. A fieldset: in a `TaoFormField` the group takes the label and the error
82
- - **TaoSwitch** — boolean toggle (`role="switch"`)
83
- - **TaoRadio** / **TaoRadioGroup** — classic radios: longer labels, can stack vertically
84
- - **TaoSegmented** / **TaoSegmentedOption** — compact exclusive choice among 2–5 short options. Not tabs
85
- - **TaoSelect** — dropdown with keyboard, same chrome as Input. `size` (`small` / `medium` / `large`, same scale as Button). Clear via “Clear” in the list or Delete; `clearable="false"` turns clearing off, `#clear` replaces the row content
86
- - **TaoCombobox** — Select with a field: type to filter, `allow-create` writes a custom value into `v-model`, `create` lets the parent append the list. Takes the same `size`, `clearable` and `#clear` as `TaoSelect`
87
- - **TaoDate** — a single day: `YYYY-MM-DD`, no time, no timezone. Calendar popup like Select
88
- - **TaoDateRange** — a period: `v-model` is `{ start, end }` or `null`. First click is start, second is end (they swap if end is earlier). An incomplete pick is not written to the model
89
- - **TaoCalendar** — the month calendar itself, inline (no popup): `mode="single"` (`YYYY-MM-DD`) or `"range"` (`{ start, end }`), `min` / `max`, arrows / PageUp / PageDown / Home / End. `TaoDate` and `TaoDateRange` are a field with this calendar in a popup
90
- - **TaoFormField** — shared label / hint / error for form controls
91
- - **TaoInputNumber** — number with min/max/step and ± on the right. Empty value is `null`. `@commit` fires once when an edit is finished (blur, Enter, ±, arrow), unlike `v-model`, which updates on every keystroke
92
- - **TaoQuantity** — cart quantity: `− | field | +`, integers, stock; minus at the minimum can remove the row
93
- - **TaoTextarea** — autosizing multiline. `maxlength` caps input, `count` shows “entered / max”. `variant`: `bar` (default) / `outline` (frame like Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
94
- - **TaoPinCode** — N cells. By default a click clears the cell and everything to the right (`clear-on="focus"`); `clear-on="input"` replaces the digit only when typing. `format="#-##-##"` draws visual separators (not part of the value; a paste in that shape or as a clean code is split into cells). The last cell blurs and emits `complete`; `status="success | error"` (set after `complete`) glows or shakes the cells and says it to a screen reader
95
- - **TaoSlider** / **TaoRangeSlider** — one thumb (`v-model` is a number) or two (`[from, to]`, `minGap`). Mouse, touch, arrows. `marks` (ticks, numbers, `{ value, label }`), `discrete` for stepped scales, `vertical`, `flat`, `format`; `variant="thin"` is a thin track for seek / volume
96
- - **TaoColorPicker** — saturation / brightness square, hue and opacity strips, swatches, eyedropper (where the browser has `EyeDropper`), HEX / RGB / HSL input modes. `v-model` is a hex string; `colorModel()` adapts your own colour storage
97
- - **TaoColorInput** — a field with a swatch and the hex text; the picker opens in a popover
98
- - **TaoFileDrop** — drop zone (drag & drop + click). File names listed under the zone, `v-model` is `File[]`. Clearing the whole batch is the parent’s job (`clear-request`)
99
-
100
- ### Data display
101
-
102
- - **TaoTable** — simple table: columns, empty, loading, sort via `v-model:sort`. `head` tints the header, `lines` draws row rules (both on by default). `striped` starts on the first row; `striped="even"` starts on the second. Not a datagrid.
103
- - **TaoPagination** — pages with ellipsis. Clicking “…” jumps `jump` pages (5 by default)
104
- - **TaoEmpty** — empty list, no results, no access
105
- - **TaoList** / **TaoListItem** — list row: icon, title, caption, hover action. Not Select, not a table
106
- - **TaoTree** — files or objects as a tree: `v-model:expanded`, selection `none | single | multiple` (`v-model:selected`), checkboxes with mixed parents (`checkable`, `v-model:checked`), lazy children (`hasChildren` + `load`). ARIA tree: one tab stop, arrows, `→` / `←` in and out, Home / End, `*`, type-ahead. Slots `#icon`, `#label`, `#actions`; rows on the control tokens (size and density)
107
- - **TaoStages** — stage list: `wait` / `work` / `ok` / `bad`. Not a linear stepper
108
- - **TaoTimeline** — a vertical feed of events: order steps, releases, a log. `active` fills the line up to the current event (`aria-current="step"`), without it the feed is a log of the past; `tone` and `icon` per marker, `#marker` / `#title` / `#content` slots; `align="alternate"` puts events on both sides and folds into one below 480px of its own width
109
- - **TaoSkeleton** — loading placeholder (text / title / circle / rect)
110
- - **TaoCounter** — flipping digits (not an input)
111
- - **TaoCarousel** — strip: full slide with `autoplay`, card with `peek`, row with `per-view`. Arrows via `controls` or `#prev` / `#next`; marks under the strip via `indicator` (`dots`, `bars` or `progress`). With `autoplay` the current mark fills over the interval and the slide changes when it is full; hover, keyboard focus, touch, a hidden tab and the pause button stop it, `prefers-reduced-motion` turns it off
112
- - **TaoAvatar** — photo or initials, sizes `small` / `medium` / `large`. Status `dot` and `count`
113
- - **TaoTag** — badge with tones. `#prefix` (avatar), `closable` dismisses the chip, `flat` drops the border
114
- - **TaoAlert** — inline page/form banner (success / error / warning / info); `collapsible` folds the body under the title (find-in-page still finds it)
115
- - **TaoProgress** — static bar (`progress` in %). Percent centered on top, or `showPercentage="right"`; `#left` / `#right` slots are captions, then the percent sits in parentheses on the right. `false` hides it. Width is `minWidth` / `maxWidth`, not the value domain
116
- - **TaoScrubber** — play / pause, a slider over time with event marks, a “time / length” label. Does not advance time by itself: drive `v-model` with your own clock
117
- - **TaoLoader** — four-dot spinner
118
- - **TaoImage** — `<img>` wrapper: fade-in and placeholder. `lazy` turns on native `loading="lazy"`
119
- - **TaoIcon** — SVG icons (29 built in, your own via `registerTaoIcons`) or an icon font (see Icons below)
120
-
121
- ### Navigation
122
-
123
- - **TaoLink** — `<NuxtLink>` in Nuxt, `<RouterLink>` with vue-router, otherwise a plain `<a>` — no extra setup
124
- - **TaoBreadcrumb** — crumbs: the last item is the current page
125
- - **TaoDropdownMenu** / **TaoMenu** — a menu from a plain data tree `items`: submenus, checkboxes, radios, separators, group labels, shortcuts to show, disabled items. Arrows, Home / End, type-ahead, `→` / `←` for submenus, Esc closes the top level first. `TaoMenu` is the panel itself, for your own shells (a menu bar, a context menu); flips at the viewport edge
126
- - **TaoMenubar** / **TaoContextMenu** — the menu bar of an editor and the menu on the right click, on `TaoMenu`. The bar is one tab stop (`role="menubar"`): `←` / `→` walk it, `↓` / Enter open, with a menu open `←` / `→` and the pointer move to the neighbour menu; an entry without `items` is a plain action. The context menu opens at the pointer (or at the element for the Menu key / Shift+F10) and wraps its content without a box of its own
127
- - **TaoScrollTop** — floating “back to top”: `solid` / `ghost` / `text` looks, `side`, a mouse-hover `label`. Appears on reverse scroll after `boundary`
128
-
129
- ### Feedback
130
-
131
- - **toast()** — fluent toasts: `toast().success().message('Saved')`
132
- - **confirm()** — overlay question: the same fluent API plus `await`. Not a toast — it waits for an answer and does not dismiss itself.
133
- - **TaoToastViewport** / **TaoConfirmHost** — hosts; if they are missing from the tree, the first call mounts them on `body`
134
-
135
- ## Conventions
136
-
137
- Visual tones: `success` | `danger` | `warning` | `info` | `neutral` (type `TaoTone`), always the `tone` prop: Button, Alert, Tag (`toast.danger()` for toasts). The accent is a tone too and the default one. A tone is a context class like a size: `.tao-tone-danger` on any element sets `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (see `styles/tone.css`). Unlike a size it does **not** inherit, so a button inside a red alert stays an accent button.
138
- Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
139
-
140
- Control sizes: `small` | `medium` | `large` (type `TaoSize`). One scale for Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup and FormField — controls of one size line up in a row. Checkbox, Radio / RadioGroup and Switch scale the indicator (14 / 18 / 22px) and the label; Tag scales its height (18 / 20 / 24px); Tabs, Pagination buttons and List rows take the Button height; Table scales cell padding (`size="small"` for the dense one); FileDrop scales the zone and file rows; Slider scales the track and thumb.
141
- Without `size` a control takes the size of its ancestors, `medium` at the root. Set it for a whole block with the class `tao-size-small` / `-medium` / `-large` on any element, or with `size` on `TaoFormField` / `TaoInputGroup`. An explicit `size` on a control wins.
142
-
143
- ```vue
144
- <div class="tao-size-small">
145
- <TaoInput v-model="q" />
146
- <TaoButton>Find</TaoButton>
147
- </div>
148
- ```
149
-
150
- Content and layout keep their own scale and do not inherit: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (pixels).
151
- Container lives on another axis — width: `width="wide" | "slim" | "ultra-slim"`.
152
-
153
- **Density** is the second axis of the controls, on top of the size: the class `tao-density-compact` / `-comfortable` / `-auto` on a container (or on `<html>`) changes the height and the padding of every size in it, not the font. `comfortable` gives 34 / 44 / 52px (touch-sized rows), `compact` 22 / 32 / 40px (dense tools and tables), `auto` is comfortable on a touch screen (`pointer: coarse`) and the default with a mouse. Select and Combobox carry it into their panels. Type `TaoDensity`; the steps are tokens `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
154
-
155
- ```html
156
- <html class="tao-density-auto">
157
- ```
158
-
159
-
160
- Surfaces — what a panel is made of: `flat` fill (default), `grain` (static film grain), `glass` (translucent, blurs what is
161
- behind). Use `surface` on TaoCard / TaoBlock or the class `tao-surface-grain` / `-glass` on any element — a game HUD, a
162
- landing section, a sidebar. Tune the look once with theme tokens (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill`
163
- / `-border` / `-blur`). A surface belongs to one element: nested panels do not inherit it. Glass needs something behind
164
- it — keep it for things that float over content; over a flat background it is just a grey fill, over animation it is
165
- re-blurred every frame. Toast and confirm are glass by default, tinted by their tone; `toast.defaults({ surface: 'flat' })`
166
- and `confirm.defaults({ surface: 'flat' })` turn it off, `.surface('flat')` does it for one. Without blur support or with
167
- `prefers-reduced-transparency` glass falls back to a solid panel.
168
-
169
- Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
170
- There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
171
-
172
- API rules — every component follows them:
173
-
174
- - **Fields** take `v-model`, `disabled`, `error` (red frame) and `size`. Label, hint and error text come from `TaoFormField`.
175
- - **Events**: `update:X` for v-model plus `change` when the user finished a change (Slider, Split — on release). Other events are verbs in the present tense: `select`, `close`, `create`.
176
- - **Texts**: visible ones are `*Text` (`clearText`, `successText`), screen-reader ones are `*Label` (`closeLabel`).
177
- - **Lists**: data arrays are `items`; selectable items carry `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Identifiers of plain data (table columns, stages) stay `key`.
178
- - **Booleans** are adjectives without `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Layout axis is `direction: 'row' | 'column'`, not `vertical`.
179
- - **Lengths** (`padding`, `radius`, `gap`, `maxHeight`): a number is pixels, a string goes to CSS as is (type `TaoLength`).
180
-
181
- ## Typography
182
-
183
- An opt-in layer: the library never styles a bare `h1` or `p`. Put `.tao-prose` on a wrapper and the text inside gets
184
- headings, paragraphs, lists, quotes, code, rules and links in the theme roles, spaced by proximity (a heading close to
185
- its text, far from the block before). Every rule inside is `:where()`, so your CSS always wins.
186
-
187
- ```html
188
- <article class="tao-prose">
189
- <h1>Title</h1>
190
- <p>Text with a <a href="/docs">link</a>.</p>
191
- </article>
192
-
193
- <h2 class="tao-heading-5">An h2 the size of level 5</h2>
194
- ```
195
-
196
- The heading scale comes from two numbers: `--tao-text-base` (16px, the text and h6) and `--tao-text-ratio` (1.25), each
197
- level up one more step: 16 / 20 / 25 / 31 / 39 / 49. Set the ratio on `:root` or on one wrapper (1.2 calmer, 1.333
198
- bolder) and the scale under it follows; h1 and h2 shrink on a narrow screen, never below h3 / h4. The steps are tokens
199
- `--tao-heading-1…6` for your own rules. `.tao-heading-1…6` gives the look of a level to any tag: the tag says what it is,
200
- the class how big.
201
-
202
- ### For AI assistants
203
-
204
- The package ships a skill, `skills/taoui/SKILL.md` with `references/components.md`: the setup, the rules (roles not colours, contexts not props), every component and its props, and the mistakes people make. Point your assistant at it; for Claude Code, copy `node_modules/@1337exp/taoui/skills/taoui` into your project's `.claude/skills/`. The component reference is generated from the showcase prop tables (`npm run skill`), and a test keeps the skill naming every component.
205
-
206
- ## Icons
207
-
208
- The library ships **29 SVG icons** (check, close, plus, minus, chevrons, arrows, search, eye, more, grip, play, pause,
209
- skip-back, copy, calendar, info, alert, circles, folder, file). They draw on `currentColor`, so an icon takes the text colour and the
210
- font size, and live under the reserved prefix `tao-`: `<TaoIcon name="tao-check" />`, the list is `taoIconNames`.
211
-
212
- ```vue
213
- <TaoIcon name="tao-check" /> <!-- built-in -->
214
- <TaoIcon name="rocket" /> <!-- registered with registerTaoIcons, or `icon-rocket` of your own font -->
215
- <TaoButton icon="tao-plus">Add</TaoButton>
216
- <TaoButton icon="tao-close" aria-label="Close" /> <!-- only an icon: a square, aria-label is required -->
217
- ```
218
-
219
- ```ts
220
- registerTaoIcons({ rocket: { body: '<path d="M12 3l4 8-4 10-4-10z"/>' } }); // 24x24 grid unless you pass viewBox
221
- ```
222
-
223
- A name without the `tao-` prefix is looked up among the icons you registered, and then rendered as the class
224
- `icon-<name>` for an external icon font (IcoMoon / Fontello and the like) that the host app connects itself. All
225
- built-in parts (close buttons, steppers, pagination arrows, toasts…) use the built-in icons and their `#…-icon` slots
226
- let you replace them with anything.
227
-
228
- ## Install
229
-
230
- ```bash
231
- npm install @1337exp/taoui
232
- ```
233
-
234
- Requires Vue 3.4+. The package is **ESM-only** (Vite, Nuxt 3, webpack 5 and Node 18+ with `import` all work; a plain `require('@1337exp/taoui')` does not: use `import()`).
235
-
236
- ### Browser support
237
-
238
- The CSS uses `color-mix()`, container queries and registered custom properties (`@property`), so the floor is
239
- **Chrome / Edge 111, Safari 16.4, Firefox 128**: the browsers of 2023–2024. Firefox 128 is the limiting one (`@property`).
240
- On an older browser everything stays readable; what you lose is small: a registered property is what keeps a tone
241
- (`.tao-tone-*`) and a surface from leaking into the children, so without it a Button inside a red Alert may turn red.
242
- The same list is the `browserslist` field of the package and the build target.
243
-
244
- From a local folder:
245
-
246
- ```bash
247
- npm install ../path-to-tao-ui
248
- ```
249
-
250
- ## Usage
251
-
252
- ### Nuxt 3
253
-
254
- Create `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
- Import styles in `app.vue` or a 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
- ### Language
288
-
289
- Built-in texts (placeholders, “Clear”, aria labels, dates) are English by default. Russian ships with the library:
290
-
291
- ```javascript
292
- import TaoUI, { localeRu } from '@1337exp/taoui'
293
-
294
- app.use(TaoUI, { locale: localeRu })
295
- ```
296
-
297
- Change single texts — the rest stays from the default:
298
-
299
- ```javascript
300
- app.use(TaoUI, { locale: { select: { placeholder: 'Pick one' } } })
301
- ```
302
-
303
- Another language: copy `localeEn` (or `localeRu`), translate, pass it the same way (type `TaoLocale`). Keys repeat prop names —
304
- `locale.select.placeholder` is the default of TaoSelect `placeholder`, and a prop passed by hand always wins.
305
-
306
- Switch the language at any moment — from your settings, a language picker, a route. Components already on the page
307
- update at once, without a reload and without losing what users typed:
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
- Without the plugin (individual components) `setTaoLocale()` is the only call you need.
318
-
319
- ### Upgrading to 5.0
320
-
321
- 5.0 deletes every name that 2.0 deprecated (plus the `error` tone alias), see [MIGRATION-5.md](MIGRATION-5.md) for the table old → new.
322
-
323
- ### Upgrading from 3.x
324
-
325
- 4.0 changes one default: the built-in texts are now English (they were Russian). To stay on Russian, pass the locale
326
- once — `app.use(TaoUI, { locale: localeRu })`, or `setTaoLocale(localeRu)` without the plugin. The date helpers and
327
- the date components follow the locale and default to `en-US` as well.
328
-
329
- ### Upgrading from 1.x
330
-
331
- See the 2.0.0 entry of [CHANGELOG.md](CHANGELOG.md) for what broke. Old names were removed in 5.0.
332
-
333
- ### Individual components
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">Press me</TaoButton>
343
- <TaoFormField label="Your text">
344
- <TaoInput v-model="text" />
345
- </TaoFormField>
346
- <TaoModal v-model="isOpen" title="Title">
347
- Modal body
348
- </TaoModal>
349
- </template>
350
- ```
351
-
352
- ## Split
353
-
354
- `TaoSplit` is two panes and a gutter. It is not `TaoDivider` (a line) and not an n-pane layout: three columns are two nested splits.
355
-
356
- `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
357
-
358
- `v-model` is the start pane size. `unit` is `%` (default — the ratio survives a container resize) or `px` (a sidebar; the end pane takes the rest). With `px`, pass an explicit size — the default `50` is 50px. `min` / `max` apply to start; `min-end` is the other pane's floor; all three use the same unit. `resizable="false"` keeps the gutter but locks it.
359
-
360
- The split fills the parent (`width` / `height: 100%`). Give the parent a bounded size on the split axis — a `column` split without a height has no `%` to compute. Panes use `min-width` / `min-height: 0` and `overflow: hidden`, so content cannot block shrinking. Scroll belongs on an inner wrapper (`overflow: auto; height: 100%; min-height: 0`). A nested `TaoSplit` as a direct child of a pane stretches on its own.
361
-
362
- ```vue
363
- <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
364
- <template #start>Nav</template>
365
- <template #end>Main</template>
366
- </TaoSplit>
367
- ```
368
-
369
- ## Toast
370
-
371
- The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
372
-
373
- ```javascript
374
- import { toast } from '@1337exp/taoui'
375
-
376
- toast().success().message('Saved')
377
- toast().danger().title('Network').timeout(5000).message('No connection')
378
- toast.success('Saved')
379
- toast.warning('Draft', { timeout: 1000 })
380
- ```
381
-
382
- Default position is `topCenter`. Globally:
383
-
384
- ```javascript
385
- toast.defaults({ position: 'bottomRight' })
386
- toast.byBottomRight()
387
- ```
388
-
389
- There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
390
-
391
- ```javascript
392
- toast().info().message('Delete the file?').action('Delete', onRemove)
393
- ```
394
-
395
- You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
396
-
397
- ```vue
398
- <TaoToastViewport />
399
- ```
400
-
401
- ## Confirm
402
-
403
- An overlay question in the center of the screen. This is not a toast: no progress bar, no auto-close, `await`, Esc and overlay click = cancel.
404
-
405
- ```javascript
406
- import { confirm } from '@1337exp/taoui'
407
-
408
- if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
409
- remove()
410
- }
411
-
412
- const ok = await confirm('Leave without saving?', {
413
- ok: 'Leave',
414
- cancel: 'Stay',
415
- })
416
- ```
417
-
418
- Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
419
-
420
- ```javascript
421
- confirm.defaults({ ok: 'Yes', cancel: 'No' })
422
- ```
423
-
424
- ## Forms
425
-
426
- `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
427
-
428
- ```vue
429
- <TaoFormField label="City" hint="Optional">
430
- <TaoSelect v-model="city" :options="cities" />
431
- </TaoFormField>
432
-
433
- <TaoSwitch v-model="dark" label="Dark theme" />
434
-
435
- <TaoRadioGroup v-model="plan" legend="Plan">
436
- <TaoRadio value="free" label="Free" />
437
- <TaoRadio value="pro" label="Pro" />
438
- </TaoRadioGroup>
439
-
440
- <TaoSegmented v-model="period" legend="Period">
441
- <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
442
- <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
443
- <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
444
- </TaoSegmented>
445
-
446
- <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
447
- ```
448
-
449
- `TaoSegmented` is a short exclusive choice with every option visible. It is not page navigation — that is `TaoTabs`. Longer labels or more than 5–6 items belong in `TaoRadioGroup` or `TaoSelect`.
450
-
451
- `TaoSelect` opens from the keyboard (arrows, Enter, Esc); the list flips at the viewport edge. Delete or “Clear” at the bottom of the list resets the value to `null`.
452
-
453
- When `null` is not a valid value (a grid step, a sort order), pass `:clearable="false"`: the clear row and the Delete / Backspace shortcut disappear. The clear row label is `clear-text`; for an icon or any markup use the `#clear` slot. `size` is `small` / `medium` / `large` (inherited from ancestors when not set) and also scales the open list.
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" /> Reset</template>
460
- </TaoSelect>
461
- ```
462
-
463
- `TaoCombobox` is the same menu with a field. Typing filters options. `allow-create` writes the typed string into `v-model` when there is no exact match. The list does not mutate itself: listen to `create` and append an option from the parent.
464
-
465
- Label, hint and error text always come from `TaoFormField`. `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
466
-
467
- `TaoTag` can be a chip: `#prefix` on the left (usually `TaoAvatar`), `closable` draws a cross and emits `close`. The close click does not bubble. `flat` drops the border and keeps the fill.
468
-
469
- ```vue
470
- <TaoTag tone="neutral" closable @close="remove">
471
- <template #prefix>
472
- <TaoAvatar name="Anna Kozlova" size="small" />
473
- </template>
474
- Anna Kozlova
475
- </TaoTag>
476
- ```
477
-
478
- ## Table and pagination
479
-
480
- The table renders what you pass in: it does not slice or sort the data. That works for both server-side and client-side paging — the page is cut outside.
481
-
482
- ```vue
483
- <TaoTable
484
- :columns="columns"
485
- :rows="pageRows"
486
- v-model:sort="sort"
487
- empty-text="No records yet"
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: 'Name', sortable: true },
502
- { key: 'city', label: 'City' },
503
- { key: 'status', label: 'Status' },
504
- ]
505
- ```
506
-
507
- The `cell-<key>` slot replaces a cell. `loading` shows an overlay; an empty list shows text or the `#empty` slot. Clicking a `sortable` header cycles `asc → desc → off`.
508
-
509
- ## Empty states and loading
510
-
511
- ```vue
512
- <TaoEmpty title="Nothing found">
513
- Change the filter or reset search.
514
- <template #action>
515
- <TaoButton variant="secondary">Reset</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: 'Payment', status: 'ok' },
525
- { key: 'pack', label: 'Packing', status: 'work' },
526
- { key: 'ship', label: 'Shipping', status: 'wait' },
527
- ]" />
528
-
529
- <TaoList>
530
- <TaoListItem
531
- title="Ann Kozlova"
532
- description="Design · Moscow"
533
- clickable
534
- :selected="picked === 'ann'"
535
- @click="picked = 'ann'"
536
- >
537
- <template #prefix>
538
- <TaoAvatar name="Ann Kozlova" size="small" />
539
- </template>
540
- </TaoListItem>
541
- </TaoList>
542
- ```
543
-
544
- ```vue
545
- <TaoInput v-model="q" placeholder="Search…">
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>Check</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">Save</TaoButton>
562
- </form>
563
-
564
- <TaoFormField label="Quantity">
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="Delivery day" hint="The model is always YYYY-MM-DD">
571
- <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
572
- </TaoFormField>
573
-
574
- <TaoFormField label="Stay">
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">next</button>
591
- </template>
592
- <article v-for="item in products" :key="item.id">…</article>
593
- </TaoCarousel>
594
- ```
595
-
596
- `TaoDrawer` is a side sheet, not a centered modal:
597
-
598
- ```vue
599
- <TaoDrawer v-model="open" title="Filters">
600
- ...
601
- </TaoDrawer>
602
- ```
603
-
604
- ## Design tokens and theming
605
-
606
- Library styles are layers. Components **never** touch raw colors or sizes: they read semantic roles, and
607
- the contexts built on them (size, tone, surface). That is the theming mechanism: override 20–30 variables
608
- and every component follows, with no edits inside the components themselves.
609
-
610
- ```
611
- tokens/primitives.css → tokens/semantic.css → themes/*.css → contexts/*.css → base.css
612
- raw colors, scales radii, shadows, colour roles size, tone, reset
613
- leave them alone type, motion per theme surface classes
614
- ```
615
-
616
- ### Layers
617
-
618
- | File (in `src/styles/`) | Role | Touch it? |
619
- |---|---|---|
620
- | `tokens/primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
621
- | `tokens/semantic.css` | Theme-independent roles: radii, shadows, type, motion | Rarely |
622
- | `themes/dark.css` | The colour roles of the default (dark) theme: `--tao-color-accent`, `--tao-color-surface`, … | **Yes — this is the theming API** |
623
- | `themes/light.css` | The same roles under `[data-tao-theme="light"]` | Yes, as a sample |
624
- | `contexts/size.css`, `tone.css`, `surface.css` | `.tao-size-*` and `.tao-density-*`, `.tao-tone-*`, `.tao-surface-*`: what a control reads to know its size, colour and material | Rarely |
625
- | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
626
-
627
- Everything comes in through `@1337exp/taoui/styles.css` (dark and light both: light turns on with `data-tao-theme="light"`).
628
- The raw files are importable as `@1337exp/taoui/styles/tokens/primitives.css` and so on.
629
-
630
- ### Your own theme
631
-
632
- A theme is just semantic tokens under your selector.
633
- Nothing in the components needs to change:
634
-
635
- ```css
636
- /* my-brand-theme.css */
637
- [data-tao-theme="my-brand"] {
638
- --tao-color-accent: #6c5ce7;
639
- --tao-color-accent-hover: #5a4bd1;
640
- --tao-color-bg: #0f0f1a;
641
- --tao-color-surface: #0f0f1a;
642
- --tao-color-surface-raised: #1a1a2e;
643
- --tao-color-text: #d6d6e8;
644
- --tao-color-text-strong: #ffffff;
645
- /* remaining roles: see themes/dark.css */
646
- }
647
- ```
648
-
649
- ```vue
650
- <!-- app.vue -->
651
- <template>
652
- <div data-tao-theme="my-brand">
653
- <NuxtPage />
654
- </div>
655
- </template>
656
- ```
657
-
658
- Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
659
-
660
- ```javascript
661
- document.documentElement.setAttribute('data-tao-theme', 'light')
662
- ```
663
-
664
- ### Token groups
665
-
666
- - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
667
- - `--tao-color-on-accent` — text on the accent
668
- - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
669
- - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
670
- - `--tao-color-border*` — borders
671
- - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
672
- - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
673
- - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
674
- - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
675
- - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
676
- - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
677
- - `--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-*` — the size scale in `primitives.css`. Components read the current values from `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`. Use them in your own controls to match the size around them.
678
-
679
- The full list of colour roles lives in `src/styles/themes/dark.css` — the file worth opening
680
- to see the whole theming API.
681
-
682
- ### Palettes
683
-
684
- A palette is four colours, from the darkest to the lightest: a whole set of roles comes out, for a dark and a light mode.
685
- Seven are ready (`sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon`; the list is `taoPalettes`).
686
-
687
- ```javascript
688
- import '@1337exp/taoui/styles.css'
689
- import '@1337exp/taoui/palettes.css' // all of them, or '@1337exp/taoui/styles/palettes/sunset.css' for one
690
- ```
691
-
692
- ```html
693
- <html data-tao-theme="sunset"> <!-- dark -->
694
- <html data-tao-theme="sunset" data-tao-mode="light"> <!-- its light twin -->
695
- ```
696
-
697
- `data-tao-mode="light" | "dark"` also works on its own, with the default colours; `data-tao-theme="light"` is the old spelling of the same.
698
- Put it on `<html>` (so modals and tooltips teleported to `body` follow) or on any element for a part of the page.
699
-
700
- What a palette decides, so you do not have to:
701
-
702
- - **The accent** is the stop whose lightness suits the mode (name it with `accent: 1` when the automatic choice is not the one you meant), moved along lightness only until it is seen on the page (3:1), carries a readable text (4.5:1) and reads as text itself (`--tao-color-accent-text`, 4.5:1).
703
- - **The page and the surfaces** are a very dark (or very light) tint of the palette's deepest hue.
704
- - **The statuses** (`danger`, `warning`, `success`, `info`) keep their recognisable hue sector but share the lightness and the chroma of the palette, and a status that would be mistaken for the accent is pushed away (a palette may name its own colour: `status: { success: '#7fbf2f' }`). Every status keeps 4.5:1 for its text, as a fill and as text.
705
- - **`--tao-color-accent-2`, `--tao-glow`, `--tao-gradient`, `--tao-bg-atmosphere`:** the second accent, the glow colour, a gradient through the four stops, and the soft glow behind the page (`class="tao-atmosphere"` on `<body>` or the app root paints it; a static layer, no blur).
706
-
707
- The contrast is not a promise in the README: `tests/palette.test.ts` holds every palette in both modes to these numbers.
708
-
709
- A palette of your own, at run time (a theme editor, a colour the user picked):
710
-
711
- ```javascript
712
- import { applyTaoPalette } from '@1337exp/taoui'
713
-
714
- const stop = applyTaoPalette({ name: 'mine', label: 'Mine', stops: ['#102030', '#306090', '#60c0f0', '#e0f4ff'] }, 'dark')
715
- stop() // takes it off again; a third argument puts it on one element instead of the page
716
- ```
717
-
718
- or as a file: `taoPaletteCss(def)` returns the CSS the preset files are made of. To add a preset to the library, add it to `src/palettes.ts` and run `npm run palettes`.
719
-
720
- #### Contrast: WCAG 2 and APCA
721
-
722
- Two questions are asked of every colour pair, and they are answered by two different models.
723
-
724
- **Is it allowed?** WCAG 2 contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` of the relative luminances, from 1 to 21. It is the
725
- legal standard (and the one accessibility audits check), so every number the palettes promise is a WCAG 2 ratio: 4.5:1
726
- for text, 3:1 for a fill seen on the page. `contrastRatio(a, b)` computes it.
727
-
728
- **Which reads better?** WCAG 2 has a known blind spot: it treats light and dark the same way, and on mid-tone colours it
729
- overrates black. On the green `#2ea85c` it says black 6.4:1 against white 3.1:1, while the eye clearly reads white better.
730
- APCA (Accessible Perceptual Contrast Algorithm, the model behind the WCAG 3 draft) follows how we see: it knows that
731
- light text on a dark background and dark text on a light one are not symmetric, and that thin text needs more. It gives
732
- a lightness contrast **Lc** from about −108 to 106 (the sign is the polarity: negative is light text on dark); about 75 is
733
- body text, 60 a label, 45 a large heading. `apcaContrast(text, background)` computes it.
734
-
735
- | On `#2ea85c` | WCAG 2 | APCA Lc |
736
- |---|---|---|
737
- | black text | **6.4 : 1** | 47 |
738
- | white text | 3.1 : 1 | **62** |
739
-
740
- So the palettes use both, each for what it is good at:
741
-
742
- 1. **The polarity by APCA.** In light mode the label on a fill (the accent, a status) is the colour APCA reads better;
743
- on mid-tones that is white.
744
- 2. **The numbers by WCAG 2.** The fill is then moved along lightness until that label reaches 4.5:1, so a white label
745
- on a mid-tone gets a slightly deeper fill, never a weaker label.
746
- 3. **Dark mode keeps a dark label.** There the fills are light on purpose (to be seen on a dark page), and a light fill
747
- carries dark text in both models.
748
-
749
- The checks are in `tests/palette.test.ts`: every palette, both modes, every fill. If you build your own colours, the two
750
- functions are exported, use them the same way: APCA to choose, WCAG 2 to promise.
751
-
752
- ### A theme from scratch, without primitives
753
-
754
- ```javascript
755
- import '@1337exp/taoui/styles/tokens/primitives.css' // keep the scales if you want
756
- import '@1337exp/taoui/styles/tokens/semantic.css' // radii, shadows, type, motion
757
- import './my-colour-roles.css' // your colour roles instead of themes/dark.css
758
- import '@1337exp/taoui/styles/contexts/size.css' // the contexts the components read
759
- import '@1337exp/taoui/styles/contexts/tone.css'
760
- import '@1337exp/taoui/styles/contexts/surface.css'
761
- import '@1337exp/taoui/styles/base.css'
762
- ```
763
-
764
- ## Showcase
765
-
766
- Every component with live examples, prop tables and copy-ready snippets. Language (EN / RU) and theme (dark / light) switch in the header.
767
-
768
- ```bash
769
- cd showcase
770
- npm install
771
- npm run dev # or, from the repo root: npm run showcase
772
- ```
773
-
774
- The showcase points at `src/` directly, so component edits show up without
775
- `npm run build`. `npm run showcase:build` produces a static site with relative
776
- paths, ready to drop into any folder (for example `/sandbox/taoui/`).
777
-
778
- Screenshots and clips in this README come from the showcase: see [docs/media](docs/media/README.md).
779
-
780
- ## Development
781
-
782
- ```bash
783
- # Build the library
784
- npm run build
785
-
786
- # Watch mode
787
- npm run dev
788
-
789
- # Type check
790
- npm run type-check
791
-
792
- # Tests (Vitest)
793
- npm test
794
- ```
795
-
796
- ## Publishing to npm
797
-
798
- Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
799
- import `tokens/primitives.css` on its own for a custom theme) are published, plus
800
- `README.md`, `LICENSE`, `CHANGELOG.md` and `MIGRATION-5.md`.
801
- Component sources (`src/components/*.vue`), build configs, and `showcase/`
802
- stay in the repo — clone it to get them.
803
-
804
- `npm publish` **itself** runs the type check, the tests and a full rebuild first
805
- (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
806
- reach the registry. You do not need to build by hand before `npm publish`.
807
-
808
- See what would go into the tarball, without publishing, and check the package the way a consumer meets it
809
- (`publint` for the manifest, `attw` for the type resolution):
810
-
811
- ```bash
812
- npm pack --dry-run
813
- npm run lint:package
814
- npm run smoke # installs the packed tarball into a clean Vite project and builds it
815
- ```
816
-
817
- Keep the publish token out of the repository: reference it from `.npmrc` as
818
- `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` and set `NPM_TOKEN` in your shell.
819
- `.npmrc` is git-ignored either way.
820
-
821
- ## Contributing
822
-
823
- Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
824
- Security reports: [SECURITY.md](SECURITY.md).
825
-
826
- ## License
827
-
828
- [MIT](LICENSE) © 2026 1337exp
1
+ <h1 align="center">Tao UI</h1>
2
+
3
+ <p align="center">
4
+ <b>A Vue 3 component library driven by design tokens.</b><br>
5
+ Change a handful of CSS variables and the whole kit follows.
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
+ <b>English</b> · <a href="https://github.com/1337exp/taoui/blob/master/README.ru.md">Русский</a> ·
18
+ <a href="#install">Install</a> ·
19
+ <a href="#showcase">Showcase</a> ·
20
+ <a href="CHANGELOG.md">Changelog</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 components in the dark theme" width="860">
25
+ </p>
26
+
27
+ ## Why Tao UI
28
+
29
+ - **Tokens first.** Colours, radii, spacing and type come from CSS variables in three layers (primitives, semantic, theme). Re-theme the kit, or one panel of it, without touching a component. Size and density are contexts too: set them once on a panel and everything inside follows.
30
+ - **Palettes.** Seven ready palettes built from four colours each, or your own at run time (`applyTaoPalette`). The status colours step away from the accent by themselves, and the charts recolour with the theme.
31
+ - **Contrast you can trust.** The colour pairs of the themes and palettes are checked by tests against WCAG 2 (4.5:1 for text, 3:1 for a label on a fill); APCA picks whether a label is dark or white.
32
+ - **Adapts without JS.** `TaoNav` turns from a bottom bar into a rail and a side panel, the bento grid reflows, the main action moves with the navigation — by the width of their own container (container queries), not of the window. Nothing jumps after hydration.
33
+ - **Keyboard and screen readers.** Menus, the menu bar, the toolbar, the tree and the navigation follow the WAI-ARIA patterns: one Tab stop and arrows inside (roving tabindex), `aria-pressed` toggles, `role="meter"`, focus traps in overlays.
34
+ - **Charts the honest way.** Small `TaoSparkline` / `TaoMeter` / `TaoDonut` for cards and lines of text; for real charts `taoChartTheme()` hands the theme colours to Chart.js, ECharts or uPlot.
35
+ - **Built-in languages.** Placeholders, dates and aria labels in English and Russian, switchable at runtime without a reload.
36
+ - **Nuxt and plain Vue.** `TaoLink` picks `NuxtLink`, `RouterLink` or `<a>` by itself. Fully typed ESM, every component tested for server rendering.
37
+ - **Ready for AI assistants.** The package ships a skill with a reference of every component, generated from these docs, so an assistant writes Tao UI code instead of guessing.
38
+
39
+ <table>
40
+ <tr>
41
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: square, hue strip, HEX / RGB / HSL modes"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, eyedropper, <code>v-model</code> is a hex string</sub></td>
42
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Dark and light themes switching"><br><sub><b>Themes</b> — one attribute, every component follows</sub></td>
43
+ </tr>
44
+ <tr>
45
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider with marks"><br><sub><b>TaoSlider / TaoRangeSlider</b> — marks, discrete scales, vertical</sub></td>
46
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="flat, grain and glass surfaces"><br><sub><b>Surfaces</b> — flat, grain, glass</sub></td>
47
+ </tr>
48
+ </table>
49
+
50
+ ## Components
51
+
52
+ ### Basics
53
+
54
+ - **TaoBlock** — container with padding and radius
55
+ - **TaoButton** — `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` colours any of them (accent by default, neutral, success, danger, warning, info). `v-model:pressed` makes it a toggle (`aria-pressed`)
56
+ - **TaoCard** — card with media / header / title / footer slots and a `#corner` (a tag, a menu button). `#media` can be a photo or `TaoCarousel`; `closable` adds a cross and the `close` event. `flush` is a tile (no padding/shadow, fills the cell); `#overlay` is a scrim on the media; `stripe="top | left | bottom"` with `stripeTone` (a tone or the palette `gradient`) draws a coloured stripe the corners clip
57
+ - **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
58
+ - **TaoMarquee** — one line that never wraps: when it does not fit it runs round with fading edges and a pause at the start of every round, when it fits it stands still. Stops on hover, on focus and on a tap (WCAG 2.2.2); wraps with «reduce motion»; a screen reader reads it once. `text` or inline content in the slot, `speed`, `gap`, `fade` (the left fade takes that much room left of the text: give the parent the padding), `paused`
59
+ - **TaoInput** — text field with v-model, validation, and `#prefix` / `#suffix` slots (icon or text inside the frame)
60
+ - **TaoInputGroup** — outer glue: `#before` | field | `#after` (protocol, unit, button)
61
+ - **TaoModal** — modal with animation and slots
62
+ - **TaoDrawer** — side panel (filters, settings). Esc, backdrop click, focus trap — same as the modal
63
+ - **TaoSpoiler** — disclosure. `v-model` and `aria-expanded`. Neighbours do not close each other
64
+ - **TaoSpoilerGroup** — accordion: `v-model` is the open panel key (`null` = all closed); spoilers take `name`. Without `v-model` the group keeps that key itself
65
+ - **TaoTabs** — tabbed sections
66
+ - **TaoNav** — navigation between the sections of an app: one list of items (`icon`, `href`, `badge`), three looks. `layout="auto"` picks by the width of TaoNav itself (container queries, no JS): a bottom bar below 600px (more than five items: «More» with a menu), a rail with icons below 840px, a side panel with labels from 840px. With the page in its slot it lays the page out: the bar sticks to the bottom (safe area kept), the side list to the top. `floating` lifts the bar into a detached pill with a shadow (the rail and the side panel stay). The `#action` slot is the screen's main action and moves with the navigation: round above the bar at the end side, at the top of the rail, extended with its text at the top of the side panel. `select(id, event)` lets a router take over a link
67
+ - **TaoTooltip** — hover hint. `placement`: `top` / `bottom` / `left` / `right`, each with `-start` / `-end`; flips at the viewport edge
68
+ - **TaoPopover** — click panel with any slot content, Esc and outside click; `placement` as Tooltip. Not a tooltip, not an action menu
69
+
70
+ ### Layout
71
+
72
+ - **TaoContainer** — max-width (wide / slim / ultra-slim) and centering
73
+ - **TaoFlex** — flexbox wrapper: justify / align / direction / wrap / gap
74
+ - **TaoSpace** — even gap between children
75
+ - **TaoGrid** / **TaoGridItem** — tiles: `min` is a catalog (auto-fill), `cols` is a bento. An adaptive bento takes values per width class of the grid itself (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — on a phone the big blocks take the row, small tiles stay three in a row, a side block goes down. A plain number keeps one column on a phone. `rowHeight` fixes the row height, as a mosaic wants. Not masonry
76
+ - **TaoDivider** — `solid` (plain border) / `dashed` / `colored` (accent) / `gap`. Optional `text` sits in the middle of any of them; `fade` softens the line ends; `size` is for `gap` (small / medium / large)
77
+ - **TaoSplit** — two panes and a gutter. `row` / `column` like Flex. `v-model` is the start size in `%` or `px`; `resizable="false"` locks the gutter. Not Divider.
78
+ - **TaoFieldset** — grouped frame: `legend` sits on the top border, `align` is start / center / end
79
+ - **TaoAnimatedBorder** — animated border wrapper: the rainbow, the colours of a `tone` (follows the theme) or your own `colors`; a still gradient with `prefers-reduced-motion`
80
+
81
+ ### Forms
82
+
83
+ - **TaoCheckbox** — checkbox with v-model, pre/post slots, and `indeterminate`
84
+ - **TaoChecklist** — checkboxes with one model (the checked values): `select-all` with a mixed state, a `counter` «3 of 5», `strike` for a to-do list (a look only, the checkbox tells the state), `description` per item. A fieldset: in a `TaoFormField` the group takes the label and the error
85
+ - **TaoSwitch** — boolean toggle (`role="switch"`)
86
+ - **TaoRadio** / **TaoRadioGroup** — classic radios: longer labels, can stack vertically
87
+ - **TaoSegmented** / **TaoSegmentedOption** — compact exclusive choice among 2–5 short options. Not tabs
88
+ - **TaoSelect** — dropdown with keyboard, same chrome as Input. `size` (`small` / `medium` / `large`, same scale as Button). Clear via “Clear” in the list or Delete; `clearable="false"` turns clearing off, `#clear` replaces the row content
89
+ - **TaoCombobox** — Select with a field: type to filter, `allow-create` writes a custom value into `v-model`, `create` lets the parent append the list. Takes the same `size`, `clearable` and `#clear` as `TaoSelect`
90
+ - **TaoDate** — a single day: `YYYY-MM-DD`, no time, no timezone. Calendar popup like Select
91
+ - **TaoDateRange** — a period: `v-model` is `{ start, end }` or `null`. First click is start, second is end (they swap if end is earlier). An incomplete pick is not written to the model
92
+ - **TaoCalendar** — the month calendar itself, inline (no popup): `mode="single"` (`YYYY-MM-DD`) or `"range"` (`{ start, end }`), `min` / `max`, arrows / PageUp / PageDown / Home / End. `TaoDate` and `TaoDateRange` are a field with this calendar in a popup
93
+ - **TaoFormField** — shared label / hint / error for form controls
94
+ - **TaoInputNumber** — number with min/max/step and ± on the right. Empty value is `null`. `@commit` fires once when an edit is finished (blur, Enter, ±, arrow), unlike `v-model`, which updates on every keystroke
95
+ - **TaoQuantity** — cart quantity: `− | field | +`, integers, stock; minus at the minimum can remove the row
96
+ - **TaoTextarea** — autosizing multiline. `maxlength` caps input, `count` shows “entered / max”. `variant`: `bar` (default) / `outline` (frame like Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
97
+ - **TaoPinCode** — N cells. By default a click clears the cell and everything to the right (`clear-on="focus"`); `clear-on="input"` replaces the digit only when typing. `format="#-##-##"` draws visual separators (not part of the value; a paste in that shape or as a clean code is split into cells). The last cell blurs and emits `complete`; `status="success | error"` (set after `complete`) glows or shakes the cells and says it to a screen reader
98
+ - **TaoSlider** / **TaoRangeSlider** — one thumb (`v-model` is a number) or two (`[from, to]`, `minGap`). Mouse, touch, arrows. `marks` (ticks, numbers, `{ value, label }`), `discrete` for stepped scales, `vertical`, `flat`, `format`; `variant="thin"` is a thin track for seek / volume
99
+ - **TaoColorPicker** — saturation / brightness square, hue and opacity strips, swatches, eyedropper (where the browser has `EyeDropper`), HEX / RGB / HSL input modes. `v-model` is a hex string; `colorModel()` adapts your own colour storage
100
+ - **TaoColorInput** — a field with a swatch and the hex text; the picker opens in a popover
101
+ - **TaoFileDrop** — drop zone (drag & drop + click). File names listed under the zone, `v-model` is `File[]`. Clearing the whole batch is the parent’s job (`clear-request`)
102
+
103
+ ### Data display
104
+
105
+ - **TaoTable** — simple table: columns, empty, loading, sort via `v-model:sort`. `head` tints the header, `lines` draws row rules (both on by default). `striped` starts on the first row; `striped="even"` starts on the second. Not a datagrid.
106
+ - **TaoSparkline** / **TaoMeter** / **TaoDonut** — small charts for a card or a line of text: a trend (`values` with `null` gaps, `area`, `dot`), a measured value in a range (`role="meter"`, coloured by `low` / `high` / `optimum` as the HTML `<meter>`), a share of a whole (`segments`, or one `value` of `max`, `legend`, a centre slot). The series colours are the roles `--tao-color-chart-1…6` (the first is the accent, so palettes recolour them). For axes and tooltips use a chart library: `taoChartTheme()` gives it the theme colours as `rgb()`, `watchTaoChartTheme(apply)` re-applies them on a theme or palette change
107
+ - **TaoPagination** — pages with ellipsis. Clicking “…” jumps `jump` pages (5 by default)
108
+ - **TaoEmpty** — empty list, no results, no access
109
+ - **TaoList** / **TaoListItem** — list row: icon, title, caption, hover action. Not Select, not a table
110
+ - **TaoTree** — files or objects as a tree: `v-model:expanded`, selection `none | single | multiple` (`v-model:selected`), checkboxes with mixed parents (`checkable`, `v-model:checked`), lazy children (`hasChildren` + `load`). ARIA tree: one tab stop, arrows, `→` / `←` in and out, Home / End, `*`, type-ahead. Slots `#icon`, `#label`, `#actions`; rows on the control tokens (size and density)
111
+ - **TaoStages** — stage list: `wait` / `work` / `ok` / `bad`. Not a linear stepper
112
+ - **TaoTimeline** — a vertical feed of events: order steps, releases, a log. `active` fills the line up to the current event (`aria-current="step"`), without it the feed is a log of the past; `tone` and `icon` per marker, `#marker` / `#title` / `#content` slots; `align="alternate"` puts events on both sides and folds into one below 480px of its own width
113
+ - **TaoSkeleton** — loading placeholder (text / title / circle / rect)
114
+ - **TaoCounter** — flipping digits (not an input)
115
+ - **TaoCarousel** — strip: full slide with `autoplay`, card with `peek`, row with `per-view`. Arrows via `controls` or `#prev` / `#next`; marks under the strip via `indicator` (`dots`, `bars` or `progress`). With `autoplay` the current mark fills over the interval and the slide changes when it is full; hover, keyboard focus, touch, a hidden tab and the pause button stop it, `prefers-reduced-motion` turns it off
116
+ - **TaoAvatar** — photo or initials, sizes `small` / `medium` / `large`. Status `dot` and `count`
117
+ - **TaoTag** — badge with tones. `#prefix` (avatar), `closable` dismisses the chip, `flat` drops the border
118
+ - **TaoAlert** — inline page/form banner (success / error / warning / info); `collapsible` folds the body under the title (find-in-page still finds it)
119
+ - **TaoProgress** — static bar (`progress` in %). Percent centered on top, or `showPercentage="right"`; `#left` / `#right` slots are captions, then the percent sits in parentheses on the right. `false` hides it. Width is `minWidth` / `maxWidth`, not the value domain
120
+ - **TaoScrubber** — play / pause, a slider over time with event marks, a “time / length” label. Does not advance time by itself: drive `v-model` with your own clock
121
+ - **TaoLoader** — four-dot spinner
122
+ - **TaoImage** — `<img>` wrapper: fade-in and placeholder. `lazy` turns on native `loading="lazy"`
123
+ - **TaoIcon** — SVG icons (29 built in, your own via `registerTaoIcons`) or an icon font (see Icons below)
124
+
125
+ ### Navigation
126
+
127
+ - **TaoLink** — `<NuxtLink>` in Nuxt, `<RouterLink>` with vue-router, otherwise a plain `<a>` — no extra setup
128
+ - **TaoBreadcrumb** — crumbs: the last item is the current page
129
+ - **TaoDropdownMenu** / **TaoMenu** — a menu from a plain data tree `items`: submenus, checkboxes, radios, separators, group labels, shortcuts to show, disabled items. Arrows, Home / End, type-ahead, `→` / `←` for submenus, Esc closes the top level first. `TaoMenu` is the panel itself, for your own shells (a menu bar, a context menu); flips at the viewport edge
130
+ - **TaoMenubar** / **TaoContextMenu** — the menu bar of an editor and the menu on the right click, on `TaoMenu`. The bar is one tab stop (`role="menubar"`): `←` / `→` walk it, `↓` / Enter open, with a menu open `←` / `→` and the pointer move to the neighbour menu; an entry without `items` is a plain action. The context menu opens at the pointer (or at the element for the Menu key / Shift+F10) and wraps its content without a box of its own
131
+ - **TaoToolbar** / **TaoToolbarGroup** / **TaoToolbarSeparator** — a bar of tools (`role="toolbar"`): one tab stop, `←` / `→` (or `↑` / `↓` when `orientation="vertical"`) walk the items, Home / End; inside a `TaoSegmented` the arrows pick the option and go on from its edge. Groups are split by a thin line across the bar; `inset` puts a sunken pill behind a group. Toggles are `TaoButton` with `v-model:pressed`
132
+ - **TaoScrollTop** — floating “back to top”: `solid` / `ghost` / `text` looks, `side`, a mouse-hover `label`. Appears on reverse scroll after `boundary`
133
+
134
+ ### Feedback
135
+
136
+ - **toast()** — fluent toasts: `toast().success().message('Saved')`
137
+ - **confirm()** — overlay question: the same fluent API plus `await`. Not a toast — it waits for an answer and does not dismiss itself.
138
+ - **TaoToastViewport** / **TaoConfirmHost** — hosts; if they are missing from the tree, the first call mounts them on `body`
139
+
140
+ ## Conventions
141
+
142
+ Visual tones: `success` | `danger` | `warning` | `info` | `neutral` (type `TaoTone`), always the `tone` prop: Button, Alert, Tag (`toast.danger()` for toasts). The accent is a tone too and the default one. A tone is a context class like a size: `.tao-tone-danger` on any element sets `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (see `styles/tone.css`). Unlike a size it does **not** inherit, so a button inside a red alert stays an accent button.
143
+ Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
144
+
145
+ Control sizes: `small` | `medium` | `large` (type `TaoSize`). One scale for Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup and FormField — controls of one size line up in a row. Checkbox, Radio / RadioGroup and Switch scale the indicator (14 / 18 / 22px) and the label; Tag scales its height (18 / 20 / 24px); Tabs, Pagination buttons and List rows take the Button height; Table scales cell padding (`size="small"` for the dense one); FileDrop scales the zone and file rows; Slider scales the track and thumb.
146
+ Without `size` a control takes the size of its ancestors, `medium` at the root. Set it for a whole block with the class `tao-size-small` / `-medium` / `-large` on any element, or with `size` on `TaoFormField` / `TaoInputGroup`. An explicit `size` on a control wins.
147
+
148
+ ```vue
149
+ <div class="tao-size-small">
150
+ <TaoInput v-model="q" />
151
+ <TaoButton>Find</TaoButton>
152
+ </div>
153
+ ```
154
+
155
+ Content and layout keep their own scale and do not inherit: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (pixels).
156
+ Container lives on another axis — width: `width="wide" | "slim" | "ultra-slim"`.
157
+
158
+ **Density** is the second axis of the controls, on top of the size: the class `tao-density-compact` / `-comfortable` / `-auto` on a container (or on `<html>`) changes the height and the padding of every size in it, not the font. `comfortable` gives 34 / 44 / 52px (touch-sized rows), `compact` 22 / 32 / 40px (dense tools and tables), `auto` is comfortable on a touch screen (`pointer: coarse`) and the default with a mouse. Select and Combobox carry it into their panels. Type `TaoDensity`; the steps are tokens `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
159
+
160
+ ```html
161
+ <html class="tao-density-auto">
162
+ ```
163
+
164
+
165
+ Surfaces — what a panel is made of: `flat` fill (default), `grain` (static film grain), `glass` (translucent, blurs what is
166
+ behind). Use `surface` on TaoCard / TaoBlock or the class `tao-surface-grain` / `-glass` on any element — a game HUD, a
167
+ landing section, a sidebar. Tune the look once with theme tokens (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill`
168
+ / `-border` / `-blur`). A surface belongs to one element: nested panels do not inherit it. Glass needs something behind
169
+ it — keep it for things that float over content; over a flat background it is just a grey fill, over animation it is
170
+ re-blurred every frame. Toast and confirm are glass by default, tinted by their tone; `toast.defaults({ surface: 'flat' })`
171
+ and `confirm.defaults({ surface: 'flat' })` turn it off, `.surface('flat')` does it for one. Without blur support or with
172
+ `prefers-reduced-transparency` glass falls back to a solid panel.
173
+
174
+ Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
175
+ There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
176
+
177
+ API rules — every component follows them:
178
+
179
+ - **Fields** take `v-model`, `disabled`, `error` (red frame) and `size`. Label, hint and error text come from `TaoFormField`.
180
+ - **Events**: `update:X` for v-model plus `change` when the user finished a change (Slider, Split — on release). Other events are verbs in the present tense: `select`, `close`, `create`.
181
+ - **Texts**: visible ones are `*Text` (`clearText`, `successText`), screen-reader ones are `*Label` (`closeLabel`).
182
+ - **Lists**: data arrays are `items`; selectable items carry `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Identifiers of plain data (table columns, stages) stay `key`.
183
+ - **Booleans** are adjectives without `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Layout axis is `direction: 'row' | 'column'`, not `vertical`.
184
+ - **Lengths** (`padding`, `radius`, `gap`, `maxHeight`): a number is pixels, a string goes to CSS as is (type `TaoLength`).
185
+
186
+ ## Typography
187
+
188
+ An opt-in layer: the library never styles a bare `h1` or `p`. Put `.tao-prose` on a wrapper and the text inside gets
189
+ headings, paragraphs, lists, quotes, code, rules and links in the theme roles, spaced by proximity (a heading close to
190
+ its text, far from the block before). Every rule inside is `:where()`, so your CSS always wins.
191
+
192
+ ```html
193
+ <article class="tao-prose">
194
+ <h1>Title</h1>
195
+ <p>Text with a <a href="/docs">link</a>.</p>
196
+ </article>
197
+
198
+ <h2 class="tao-heading-5">An h2 the size of level 5</h2>
199
+ ```
200
+
201
+ The heading scale comes from two numbers: `--tao-text-base` (16px, the text and h6) and `--tao-text-ratio` (1.25), each
202
+ level up one more step: 16 / 20 / 25 / 31 / 39 / 49. Set the ratio on `:root` or on one wrapper (1.2 calmer, 1.333
203
+ bolder) and the scale under it follows; h1 and h2 shrink on a narrow screen, never below h3 / h4. The steps are tokens
204
+ `--tao-heading-1…6` for your own rules. `.tao-heading-1…6` gives the look of a level to any tag: the tag says what it is,
205
+ the class how big.
206
+
207
+ ### For AI assistants
208
+
209
+ The package ships a skill, `skills/taoui/SKILL.md` with `references/components.md`: the setup, the rules (roles not colours, contexts not props), every component and its props, and the mistakes people make. Point your assistant at it; for Claude Code, copy `node_modules/@1337exp/taoui/skills/taoui` into your project's `.claude/skills/`. The component reference is generated from the showcase prop tables (`npm run skill`), and a test keeps the skill naming every component.
210
+
211
+ ## Icons
212
+
213
+ The library ships **29 SVG icons** (check, close, plus, minus, chevrons, arrows, search, eye, more, grip, play, pause,
214
+ skip-back, copy, calendar, info, alert, circles, folder, file). They draw on `currentColor`, so an icon takes the text colour and the
215
+ font size, and live under the reserved prefix `tao-`: `<TaoIcon name="tao-check" />`, the list is `taoIconNames`.
216
+
217
+ ```vue
218
+ <TaoIcon name="tao-check" /> <!-- built-in -->
219
+ <TaoIcon name="rocket" /> <!-- registered with registerTaoIcons, or `icon-rocket` of your own font -->
220
+ <TaoButton icon="tao-plus">Add</TaoButton>
221
+ <TaoButton icon="tao-close" aria-label="Close" /> <!-- only an icon: a square, aria-label is required -->
222
+ ```
223
+
224
+ ```ts
225
+ registerTaoIcons({ rocket: { body: '<path d="M12 3l4 8-4 10-4-10z"/>' } }); // 24x24 grid unless you pass viewBox
226
+ ```
227
+
228
+ A name without the `tao-` prefix is looked up among the icons you registered, and then rendered as the class
229
+ `icon-<name>` for an external icon font (IcoMoon / Fontello and the like) that the host app connects itself. All
230
+ built-in parts (close buttons, steppers, pagination arrows, toasts…) use the built-in icons and their `#…-icon` slots
231
+ let you replace them with anything.
232
+
233
+ ## Install
234
+
235
+ ```bash
236
+ npm install @1337exp/taoui
237
+ ```
238
+
239
+ Requires Vue 3.4+. The package is **ESM-only** (Vite, Nuxt 3, webpack 5 and Node 18+ with `import` all work; a plain `require('@1337exp/taoui')` does not: use `import()`).
240
+
241
+ ### Browser support
242
+
243
+ The CSS uses `color-mix()`, container queries and registered custom properties (`@property`), so the floor is
244
+ **Chrome / Edge 111, Safari 16.4, Firefox 128**: the browsers of 2023–2024. Firefox 128 is the limiting one (`@property`).
245
+ On an older browser everything stays readable; what you lose is small: a registered property is what keeps a tone
246
+ (`.tao-tone-*`) and a surface from leaking into the children, so without it a Button inside a red Alert may turn red.
247
+ The same list is the `browserslist` field of the package and the build target.
248
+
249
+ From a local folder:
250
+
251
+ ```bash
252
+ npm install ../path-to-tao-ui
253
+ ```
254
+
255
+ ## Usage
256
+
257
+ ### Nuxt 3
258
+
259
+ Create `plugins/tao-ui.ts`:
260
+
261
+ ```typescript
262
+ import { defineNuxtPlugin } from '#app'
263
+ import TaoUI from '@1337exp/taoui'
264
+
265
+ export default defineNuxtPlugin((nuxtApp) => {
266
+ nuxtApp.vueApp.use(TaoUI)
267
+ })
268
+ ```
269
+
270
+ Import styles in `app.vue` or a layout:
271
+
272
+ ```vue
273
+ <script setup>
274
+ import '@1337exp/taoui/styles.css'
275
+ </script>
276
+ ```
277
+
278
+ ### Vue 3
279
+
280
+ ```javascript
281
+ // main.js
282
+ import { createApp } from 'vue'
283
+ import App from './App.vue'
284
+ import TaoUI from '@1337exp/taoui'
285
+ import '@1337exp/taoui/styles.css'
286
+
287
+ const app = createApp(App)
288
+ app.use(TaoUI)
289
+ app.mount('#app')
290
+ ```
291
+
292
+ ### Language
293
+
294
+ Built-in texts (placeholders, “Clear”, aria labels, dates) are English by default. Russian ships with the library:
295
+
296
+ ```javascript
297
+ import TaoUI, { localeRu } from '@1337exp/taoui'
298
+
299
+ app.use(TaoUI, { locale: localeRu })
300
+ ```
301
+
302
+ Change single texts — the rest stays from the default:
303
+
304
+ ```javascript
305
+ app.use(TaoUI, { locale: { select: { placeholder: 'Pick one' } } })
306
+ ```
307
+
308
+ Another language: copy `localeEn` (or `localeRu`), translate, pass it the same way (type `TaoLocale`). Keys repeat prop names —
309
+ `locale.select.placeholder` is the default of TaoSelect `placeholder`, and a prop passed by hand always wins.
310
+
311
+ Switch the language at any moment — from your settings, a language picker, a route. Components already on the page
312
+ update at once, without a reload and without losing what users typed:
313
+
314
+ ```javascript
315
+ import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
316
+
317
+ function onLanguageChange(lang) {
318
+ setTaoLocale(lang === 'ru' ? localeRu : localeEn)
319
+ }
320
+ ```
321
+
322
+ Without the plugin (individual components) `setTaoLocale()` is the only call you need.
323
+
324
+ ### Upgrading to 5.0
325
+
326
+ 5.0 deletes every name that 2.0 deprecated (plus the `error` tone alias), see [MIGRATION-5.md](MIGRATION-5.md) for the table old → new.
327
+
328
+ ### Upgrading from 3.x
329
+
330
+ 4.0 changes one default: the built-in texts are now English (they were Russian). To stay on Russian, pass the locale
331
+ once — `app.use(TaoUI, { locale: localeRu })`, or `setTaoLocale(localeRu)` without the plugin. The date helpers and
332
+ the date components follow the locale and default to `en-US` as well.
333
+
334
+ ### Upgrading from 1.x
335
+
336
+ See the 2.0.0 entry of [CHANGELOG.md](CHANGELOG.md) for what broke. Old names were removed in 5.0.
337
+
338
+ ### Individual components
339
+
340
+ ```vue
341
+ <script setup>
342
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
343
+ import '@1337exp/taoui/styles.css'
344
+ </script>
345
+
346
+ <template>
347
+ <TaoButton variant="primary">Press me</TaoButton>
348
+ <TaoFormField label="Your text">
349
+ <TaoInput v-model="text" />
350
+ </TaoFormField>
351
+ <TaoModal v-model="isOpen" title="Title">
352
+ Modal body
353
+ </TaoModal>
354
+ </template>
355
+ ```
356
+
357
+ ## Split
358
+
359
+ `TaoSplit` is two panes and a gutter. It is not `TaoDivider` (a line) and not an n-pane layout: three columns are two nested splits.
360
+
361
+ `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
362
+
363
+ `v-model` is the start pane size. `unit` is `%` (default — the ratio survives a container resize) or `px` (a sidebar; the end pane takes the rest). With `px`, pass an explicit size — the default `50` is 50px. `min` / `max` apply to start; `min-end` is the other pane's floor; all three use the same unit. `resizable="false"` keeps the gutter but locks it.
364
+
365
+ The split fills the parent (`width` / `height: 100%`). Give the parent a bounded size on the split axis — a `column` split without a height has no `%` to compute. Panes use `min-width` / `min-height: 0` and `overflow: hidden`, so content cannot block shrinking. Scroll belongs on an inner wrapper (`overflow: auto; height: 100%; min-height: 0`). A nested `TaoSplit` as a direct child of a pane stretches on its own.
366
+
367
+ ```vue
368
+ <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
369
+ <template #start>Nav</template>
370
+ <template #end>Main</template>
371
+ </TaoSplit>
372
+ ```
373
+
374
+ ## Toast
375
+
376
+ The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
377
+
378
+ ```javascript
379
+ import { toast } from '@1337exp/taoui'
380
+
381
+ toast().success().message('Saved')
382
+ toast().danger().title('Network').timeout(5000).message('No connection')
383
+ toast.success('Saved')
384
+ toast.warning('Draft', { timeout: 1000 })
385
+ ```
386
+
387
+ Default position is `topCenter`. Globally:
388
+
389
+ ```javascript
390
+ toast.defaults({ position: 'bottomRight' })
391
+ toast.byBottomRight()
392
+ ```
393
+
394
+ There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
395
+
396
+ ```javascript
397
+ toast().info().message('Delete the file?').action('Delete', onRemove)
398
+ ```
399
+
400
+ You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
401
+
402
+ ```vue
403
+ <TaoToastViewport />
404
+ ```
405
+
406
+ ## Confirm
407
+
408
+ An overlay question in the center of the screen. This is not a toast: no progress bar, no auto-close, `await`, Esc and overlay click = cancel.
409
+
410
+ ```javascript
411
+ import { confirm } from '@1337exp/taoui'
412
+
413
+ if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
414
+ remove()
415
+ }
416
+
417
+ const ok = await confirm('Leave without saving?', {
418
+ ok: 'Leave',
419
+ cancel: 'Stay',
420
+ })
421
+ ```
422
+
423
+ Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
424
+
425
+ ```javascript
426
+ confirm.defaults({ ok: 'Yes', cancel: 'No' })
427
+ ```
428
+
429
+ ## Forms
430
+
431
+ `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
432
+
433
+ ```vue
434
+ <TaoFormField label="City" hint="Optional">
435
+ <TaoSelect v-model="city" :options="cities" />
436
+ </TaoFormField>
437
+
438
+ <TaoSwitch v-model="dark" label="Dark theme" />
439
+
440
+ <TaoRadioGroup v-model="plan" legend="Plan">
441
+ <TaoRadio value="free" label="Free" />
442
+ <TaoRadio value="pro" label="Pro" />
443
+ </TaoRadioGroup>
444
+
445
+ <TaoSegmented v-model="period" legend="Period">
446
+ <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
447
+ <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
448
+ <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
449
+ </TaoSegmented>
450
+
451
+ <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
452
+ ```
453
+
454
+ `TaoSegmented` is a short exclusive choice with every option visible. It is not page navigation — that is `TaoTabs`. Longer labels or more than 5–6 items belong in `TaoRadioGroup` or `TaoSelect`.
455
+
456
+ `TaoSelect` opens from the keyboard (arrows, Enter, Esc); the list flips at the viewport edge. Delete or “Clear” at the bottom of the list resets the value to `null`.
457
+
458
+ When `null` is not a valid value (a grid step, a sort order), pass `:clearable="false"`: the clear row and the Delete / Backspace shortcut disappear. The clear row label is `clear-text`; for an icon or any markup use the `#clear` slot. `size` is `small` / `medium` / `large` (inherited from ancestors when not set) and also scales the open list.
459
+
460
+ ```vue
461
+ <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
462
+
463
+ <TaoSelect v-model="city" :options="cities">
464
+ <template #clear><TaoIcon name="close" /> Reset</template>
465
+ </TaoSelect>
466
+ ```
467
+
468
+ `TaoCombobox` is the same menu with a field. Typing filters options. `allow-create` writes the typed string into `v-model` when there is no exact match. The list does not mutate itself: listen to `create` and append an option from the parent.
469
+
470
+ Label, hint and error text always come from `TaoFormField`. `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
471
+
472
+ `TaoTag` can be a chip: `#prefix` on the left (usually `TaoAvatar`), `closable` draws a cross and emits `close`. The close click does not bubble. `flat` drops the border and keeps the fill.
473
+
474
+ ```vue
475
+ <TaoTag tone="neutral" closable @close="remove">
476
+ <template #prefix>
477
+ <TaoAvatar name="Anna Kozlova" size="small" />
478
+ </template>
479
+ Anna Kozlova
480
+ </TaoTag>
481
+ ```
482
+
483
+ ## Table and pagination
484
+
485
+ The table renders what you pass in: it does not slice or sort the data. That works for both server-side and client-side paging — the page is cut outside.
486
+
487
+ ```vue
488
+ <TaoTable
489
+ :columns="columns"
490
+ :rows="pageRows"
491
+ v-model:sort="sort"
492
+ empty-text="No records yet"
493
+ >
494
+ <template #cell-status="{ row }">
495
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
496
+ {{ row.status }}
497
+ </TaoTag>
498
+ </template>
499
+ </TaoTable>
500
+
501
+ <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
502
+ ```
503
+
504
+ ```javascript
505
+ const columns = [
506
+ { key: 'name', label: 'Name', sortable: true },
507
+ { key: 'city', label: 'City' },
508
+ { key: 'status', label: 'Status' },
509
+ ]
510
+ ```
511
+
512
+ The `cell-<key>` slot replaces a cell. `loading` shows an overlay; an empty list shows text or the `#empty` slot. Clicking a `sortable` header cycles `asc → desc → off`.
513
+
514
+ ## Empty states and loading
515
+
516
+ ```vue
517
+ <TaoEmpty title="Nothing found">
518
+ Change the filter or reset search.
519
+ <template #action>
520
+ <TaoButton variant="secondary">Reset</TaoButton>
521
+ </template>
522
+ </TaoEmpty>
523
+
524
+ <TaoSkeleton variant="title" />
525
+ <TaoSkeleton :lines="3" />
526
+ <TaoSkeleton variant="circle" />
527
+
528
+ <TaoStages :items="[
529
+ { key: 'pay', label: 'Payment', status: 'ok' },
530
+ { key: 'pack', label: 'Packing', status: 'work' },
531
+ { key: 'ship', label: 'Shipping', status: 'wait' },
532
+ ]" />
533
+
534
+ <TaoList>
535
+ <TaoListItem
536
+ title="Ann Kozlova"
537
+ description="Design · Moscow"
538
+ clickable
539
+ :selected="picked === 'ann'"
540
+ @click="picked = 'ann'"
541
+ >
542
+ <template #prefix>
543
+ <TaoAvatar name="Ann Kozlova" size="small" />
544
+ </template>
545
+ </TaoListItem>
546
+ </TaoList>
547
+ ```
548
+
549
+ ```vue
550
+ <TaoInput v-model="q" placeholder="Search…">
551
+ <template #prefix>⌕</template>
552
+ </TaoInput>
553
+
554
+ <TaoInputGroup>
555
+ <template #before>https://</template>
556
+ <TaoInput v-model="host" placeholder="example.com" />
557
+ <template #after>
558
+ <TaoButton>Check</TaoButton>
559
+ </template>
560
+ </TaoInputGroup>
561
+
562
+ <form @submit.prevent="onSave">
563
+ <TaoFormField label="Email">
564
+ <TaoInput v-model="email" type="email" />
565
+ </TaoFormField>
566
+ <TaoButton type="submit">Save</TaoButton>
567
+ </form>
568
+
569
+ <TaoFormField label="Quantity">
570
+ <TaoInputNumber v-model="qty" :min="1" :max="99" />
571
+ </TaoFormField>
572
+
573
+ <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
574
+
575
+ <TaoFormField label="Delivery day" hint="The model is always YYYY-MM-DD">
576
+ <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
577
+ </TaoFormField>
578
+
579
+ <TaoFormField label="Stay">
580
+ <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
581
+ </TaoFormField>
582
+
583
+ <TaoCounter :value="score" :max-digits="6" />
584
+
585
+ <TaoCarousel :autoplay="4000" loop indicator="bars">
586
+ <article v-for="item in banners" :key="item.id" class="hero">
587
+ <strong>{{ item.title }}</strong>
588
+ <span>{{ item.text }}</span>
589
+ </article>
590
+ </TaoCarousel>
591
+ <TaoCarousel :peek="72" :controls="false" indicator="dots">…</TaoCarousel>
592
+ <TaoCarousel v-model="slide" :per-view="5" :peek="28">
593
+ <template #prev></template>
594
+ <template #next="{ go, disabled }">
595
+ <button type="button" :disabled="disabled" @click="go">next</button>
596
+ </template>
597
+ <article v-for="item in products" :key="item.id">…</article>
598
+ </TaoCarousel>
599
+ ```
600
+
601
+ `TaoDrawer` is a side sheet, not a centered modal:
602
+
603
+ ```vue
604
+ <TaoDrawer v-model="open" title="Filters">
605
+ ...
606
+ </TaoDrawer>
607
+ ```
608
+
609
+ ## Design tokens and theming
610
+
611
+ Library styles are layers. Components **never** touch raw colors or sizes: they read semantic roles, and
612
+ the contexts built on them (size, tone, surface). That is the theming mechanism: override 20–30 variables
613
+ and every component follows, with no edits inside the components themselves.
614
+
615
+ ```
616
+ tokens/primitives.css → tokens/semantic.css → themes/*.css → contexts/*.css → base.css
617
+ raw colors, scales radii, shadows, colour roles size, tone, reset
618
+ leave them alone type, motion per theme surface classes
619
+ ```
620
+
621
+ ### Layers
622
+
623
+ | File (in `src/styles/`) | Role | Touch it? |
624
+ |---|---|---|
625
+ | `tokens/primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
626
+ | `tokens/semantic.css` | Theme-independent roles: radii, shadows, type, motion | Rarely |
627
+ | `themes/dark.css` | The colour roles of the default (dark) theme: `--tao-color-accent`, `--tao-color-surface`, … | **Yes — this is the theming API** |
628
+ | `themes/light.css` | The same roles under `[data-tao-theme="light"]` | Yes, as a sample |
629
+ | `contexts/size.css`, `tone.css`, `surface.css` | `.tao-size-*` and `.tao-density-*`, `.tao-tone-*`, `.tao-surface-*`: what a control reads to know its size, colour and material | Rarely |
630
+ | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
631
+
632
+ Everything comes in through `@1337exp/taoui/styles.css` (dark and light both: light turns on with `data-tao-theme="light"`).
633
+ The raw files are importable as `@1337exp/taoui/styles/tokens/primitives.css` and so on.
634
+
635
+ ### Your own theme
636
+
637
+ A theme is just semantic tokens under your selector.
638
+ Nothing in the components needs to change:
639
+
640
+ ```css
641
+ /* my-brand-theme.css */
642
+ [data-tao-theme="my-brand"] {
643
+ --tao-color-accent: #6c5ce7;
644
+ --tao-color-accent-hover: #5a4bd1;
645
+ --tao-color-bg: #0f0f1a;
646
+ --tao-color-surface: #0f0f1a;
647
+ --tao-color-surface-raised: #1a1a2e;
648
+ --tao-color-text: #d6d6e8;
649
+ --tao-color-text-strong: #ffffff;
650
+ /* remaining roles: see themes/dark.css */
651
+ }
652
+ ```
653
+
654
+ ```vue
655
+ <!-- app.vue -->
656
+ <template>
657
+ <div data-tao-theme="my-brand">
658
+ <NuxtPage />
659
+ </div>
660
+ </template>
661
+ ```
662
+
663
+ Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
664
+
665
+ ```javascript
666
+ document.documentElement.setAttribute('data-tao-theme', 'light')
667
+ ```
668
+
669
+ ### Token groups
670
+
671
+ - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
672
+ - `--tao-color-on-accent` — text on the accent
673
+ - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
674
+ - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
675
+ - `--tao-color-border*` — borders
676
+ - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
677
+ - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
678
+ - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
679
+ - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
680
+ - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
681
+ - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
682
+ - `--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-*` — the size scale in `primitives.css`. Components read the current values from `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`. Use them in your own controls to match the size around them.
683
+
684
+ The full list of colour roles lives in `src/styles/themes/dark.css` — the file worth opening
685
+ to see the whole theming API.
686
+
687
+ ### Palettes
688
+
689
+ A palette is four colours, from the darkest to the lightest: a whole set of roles comes out, for a dark and a light mode.
690
+ Seven are ready (`sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon`; the list is `taoPalettes`).
691
+
692
+ ```javascript
693
+ import '@1337exp/taoui/styles.css'
694
+ import '@1337exp/taoui/palettes.css' // all of them, or '@1337exp/taoui/styles/palettes/sunset.css' for one
695
+ ```
696
+
697
+ ```html
698
+ <html data-tao-theme="sunset"> <!-- dark -->
699
+ <html data-tao-theme="sunset" data-tao-mode="light"> <!-- its light twin -->
700
+ ```
701
+
702
+ `data-tao-mode="light" | "dark"` also works on its own, with the default colours; `data-tao-theme="light"` is the old spelling of the same.
703
+ Put it on `<html>` (so modals and tooltips teleported to `body` follow) or on any element for a part of the page.
704
+
705
+ What a palette decides, so you do not have to:
706
+
707
+ - **The accent** is the stop whose lightness suits the mode (name it with `accent: 1` when the automatic choice is not the one you meant), moved along lightness only until it is seen on the page (3:1), carries a readable text (4.5:1) and reads as text itself (`--tao-color-accent-text`, 4.5:1).
708
+ - **The page and the surfaces** are a very dark (or very light) tint of the palette's deepest hue.
709
+ - **The statuses** (`danger`, `warning`, `success`, `info`) keep their recognisable hue sector but share the lightness and the chroma of the palette, and a status that would be mistaken for the accent is pushed away (a palette may name its own colour: `status: { success: '#7fbf2f' }`). Every status keeps 4.5:1 for its text, as a fill and as text.
710
+ - **`--tao-color-accent-2`, `--tao-glow`, `--tao-gradient`, `--tao-bg-atmosphere`:** the second accent, the glow colour, a gradient through the four stops, and the soft glow behind the page (`class="tao-atmosphere"` on `<body>` or the app root paints it; a static layer, no blur).
711
+
712
+ The contrast is not a promise in the README: `tests/palette.test.ts` holds every palette in both modes to these numbers.
713
+
714
+ A palette of your own, at run time (a theme editor, a colour the user picked):
715
+
716
+ ```javascript
717
+ import { applyTaoPalette } from '@1337exp/taoui'
718
+
719
+ const stop = applyTaoPalette({ name: 'mine', label: 'Mine', stops: ['#102030', '#306090', '#60c0f0', '#e0f4ff'] }, 'dark')
720
+ stop() // takes it off again; a third argument puts it on one element instead of the page
721
+ ```
722
+
723
+ or as a file: `taoPaletteCss(def)` returns the CSS the preset files are made of. To add a preset to the library, add it to `src/palettes.ts` and run `npm run palettes`.
724
+
725
+ #### Contrast: WCAG 2 and APCA
726
+
727
+ Two questions are asked of every colour pair, and they are answered by two different models.
728
+
729
+ **Is it allowed?** WCAG 2 contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` of the relative luminances, from 1 to 21. It is the
730
+ legal standard (and the one accessibility audits check), so every number the palettes promise is a WCAG 2 ratio: 4.5:1
731
+ for text, 3:1 for a fill seen on the page. `contrastRatio(a, b)` computes it.
732
+
733
+ **Which reads better?** WCAG 2 has a known blind spot: it treats light and dark the same way, and on mid-tone colours it
734
+ overrates black. On the green `#2ea85c` it says black 6.4:1 against white 3.1:1, while the eye clearly reads white better.
735
+ APCA (Accessible Perceptual Contrast Algorithm, the model behind the WCAG 3 draft) follows how we see: it knows that
736
+ light text on a dark background and dark text on a light one are not symmetric, and that thin text needs more. It gives
737
+ a lightness contrast **Lc** from about −108 to 106 (the sign is the polarity: negative is light text on dark); about 75 is
738
+ body text, 60 a label, 45 a large heading. `apcaContrast(text, background)` computes it.
739
+
740
+ | On `#2ea85c` | WCAG 2 | APCA Lc |
741
+ |---|---|---|
742
+ | black text | **6.4 : 1** | 47 |
743
+ | white text | 3.1 : 1 | **62** |
744
+
745
+ So the palettes use both, each for what it is good at:
746
+
747
+ 1. **The polarity by APCA.** In light mode the label on a fill (the accent, a status) is the colour APCA reads better;
748
+ on mid-tones that is white.
749
+ 2. **The numbers by WCAG 2.** The fill is then moved along lightness until that label reaches 4.5:1, so a white label
750
+ on a mid-tone gets a slightly deeper fill, never a weaker label.
751
+ 3. **Dark mode keeps a dark label.** There the fills are light on purpose (to be seen on a dark page), and a light fill
752
+ carries dark text in both models.
753
+
754
+ The checks are in `tests/palette.test.ts`: every palette, both modes, every fill. If you build your own colours, the two
755
+ functions are exported, use them the same way: APCA to choose, WCAG 2 to promise.
756
+
757
+ ### A theme from scratch, without primitives
758
+
759
+ ```javascript
760
+ import '@1337exp/taoui/styles/tokens/primitives.css' // keep the scales if you want
761
+ import '@1337exp/taoui/styles/tokens/semantic.css' // radii, shadows, type, motion
762
+ import './my-colour-roles.css' // your colour roles instead of themes/dark.css
763
+ import '@1337exp/taoui/styles/contexts/size.css' // the contexts the components read
764
+ import '@1337exp/taoui/styles/contexts/tone.css'
765
+ import '@1337exp/taoui/styles/contexts/surface.css'
766
+ import '@1337exp/taoui/styles/base.css'
767
+ ```
768
+
769
+ ## Showcase
770
+
771
+ Every component with live examples, prop tables and copy-ready snippets. Language (EN / RU) and theme (dark / light) switch in the header.
772
+
773
+ ```bash
774
+ cd showcase
775
+ npm install
776
+ npm run dev # or, from the repo root: npm run showcase
777
+ ```
778
+
779
+ The showcase points at `src/` directly, so component edits show up without
780
+ `npm run build`. `npm run showcase:build` produces a static site with relative
781
+ paths, ready to drop into any folder (for example `/sandbox/taoui/`).
782
+
783
+ Screenshots and clips in this README come from the showcase: see [docs/media](docs/media/README.md).
784
+
785
+ ## Development
786
+
787
+ ```bash
788
+ # Build the library
789
+ npm run build
790
+
791
+ # Watch mode
792
+ npm run dev
793
+
794
+ # Type check
795
+ npm run type-check
796
+
797
+ # Tests (Vitest)
798
+ npm test
799
+ ```
800
+
801
+ ## Publishing to npm
802
+
803
+ Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
804
+ import `tokens/primitives.css` on its own for a custom theme) are published, plus
805
+ `README.md`, `LICENSE`, `CHANGELOG.md` and `MIGRATION-5.md`.
806
+ Component sources (`src/components/*.vue`), build configs, and `showcase/`
807
+ stay in the repo — clone it to get them.
808
+
809
+ `npm publish` **itself** runs the type check, the tests and a full rebuild first
810
+ (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
811
+ reach the registry. You do not need to build by hand before `npm publish`.
812
+
813
+ See what would go into the tarball, without publishing, and check the package the way a consumer meets it
814
+ (`publint` for the manifest, `attw` for the type resolution):
815
+
816
+ ```bash
817
+ npm pack --dry-run
818
+ npm run lint:package
819
+ npm run smoke # installs the packed tarball into a clean Vite project and builds it
820
+ ```
821
+
822
+ Keep the publish token out of the repository: reference it from `.npmrc` as
823
+ `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` and set `NPM_TOKEN` in your shell.
824
+ `.npmrc` is git-ignored either way.
825
+
826
+ ## Contributing
827
+
828
+ Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
829
+ Security reports: [SECURITY.md](SECURITY.md).
830
+
831
+ ## License
832
+
833
+ [MIT](LICENSE) © 2026 1337exp