@1337exp/taoui 4.0.0 → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +314 -216
- package/MIGRATION-5.md +133 -0
- package/README.md +828 -682
- package/README.ru.md +828 -687
- package/dist/index.d.ts +2009 -701
- package/dist/{index.mjs → index.js} +3865 -2836
- package/dist/index.js.map +1 -0
- package/dist/styles.css +1 -1
- package/package.json +100 -90
- package/skills/taoui/SKILL.md +131 -0
- package/skills/taoui/references/components.md +1105 -0
- package/src/styles/base.css +81 -81
- package/src/styles/contexts/atmosphere.css +29 -0
- package/src/styles/contexts/size.css +125 -0
- package/src/styles/{surface.css → contexts/surface.css} +68 -4
- package/src/styles/contexts/tone.css +118 -0
- package/src/styles/date-popup.css +2 -2
- package/src/styles/index.css +12 -5
- package/src/styles/palettes/index.css +11 -0
- package/src/styles/palettes/lagoon.css +105 -0
- package/src/styles/palettes/marple.css +105 -0
- package/src/styles/palettes/ocean-blue.css +105 -0
- package/src/styles/palettes/pinheiro.css +105 -0
- package/src/styles/palettes/sunset.css +105 -0
- package/src/styles/palettes/tokyo-night.css +105 -0
- package/src/styles/palettes/violet-dusk.css +105 -0
- package/src/styles/{semantic.css → themes/dark.css} +95 -93
- package/src/styles/themes/light.css +86 -74
- package/src/styles/{primitives.css → tokens/primitives.css} +162 -139
- package/src/styles/tokens/semantic.css +33 -0
- package/src/styles/typography.css +220 -0
- package/dist/index.cjs +0 -10602
- package/dist/index.cjs.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/src/styles/size.css +0 -57
package/README.md
CHANGED
|
@@ -1,682 +1,828 @@
|
|
|
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** — `primary` / `secondary` / `ghost` / `text
|
|
53
|
-
- **TaoCard** — card with
|
|
54
|
-
- **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
|
|
55
|
-
- **
|
|
56
|
-
- **
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
- **
|
|
61
|
-
- **
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- **
|
|
70
|
-
- **
|
|
71
|
-
- **
|
|
72
|
-
- **
|
|
73
|
-
- **
|
|
74
|
-
- **
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
- **
|
|
81
|
-
- **
|
|
82
|
-
- **
|
|
83
|
-
- **
|
|
84
|
-
- **
|
|
85
|
-
- **
|
|
86
|
-
- **
|
|
87
|
-
- **
|
|
88
|
-
- **
|
|
89
|
-
- **
|
|
90
|
-
- **
|
|
91
|
-
- **
|
|
92
|
-
- **
|
|
93
|
-
- **
|
|
94
|
-
- **
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
- **
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- **
|
|
103
|
-
- **
|
|
104
|
-
- **
|
|
105
|
-
- **
|
|
106
|
-
- **
|
|
107
|
-
- **
|
|
108
|
-
- **
|
|
109
|
-
- **
|
|
110
|
-
- **
|
|
111
|
-
- **
|
|
112
|
-
- **
|
|
113
|
-
- **
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- **
|
|
118
|
-
- **
|
|
119
|
-
- **
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
- **
|
|
125
|
-
- **
|
|
126
|
-
- **
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
</
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
<
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
<
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
</
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
<
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
</
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
<
|
|
515
|
-
<
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
<
|
|
520
|
-
<
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
<
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
#
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
#
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
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
|