@1337exp/taoui 5.31.0 → 5.32.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1337exp/taoui",
3
- "version": "5.31.0",
3
+ "version": "5.32.1",
4
4
  "description": "Design-token driven Vue 3 / Nuxt component library: palettes with tested contrast, accessible menus and toolbars, navigation that adapts without JS, small charts, built-in locales.",
5
5
  "keywords": [
6
6
  "vue",
@@ -31,6 +31,9 @@ createApp(App).use(TaoUI, { locale: localeRu }).mount('#app') // locale option
31
31
 
32
32
  1. **Colours come from roles**, never hex: `var(--tao-color-text-muted)`, `--tao-color-accent`, `--tao-color-surface`,
33
33
  `--tao-color-border`, `--tao-color-danger`… A hex in app CSS breaks the light mode and every palette.
34
+ **Pick the text step by its job** (patterns.md, "The text ladder"): `text-strong` for headings and the value that is the
35
+ point, `text` for body copy and every control at rest, `text-muted` for hints and captions; hover goes one step up.
36
+ Never paint body copy `strong` to make it important.
34
37
  2. **Status is `tone`**, the same everywhere: `success | danger | warning | info | neutral` (the accent when omitted) on
35
38
  TaoButton, TaoAlert, TaoTag, the stripe of TaoCard / TaoBlock (`stripeTone`), TaoTimeline markers; `toast().danger()`. Say the status in words
36
39
  too: colour alone is not a message.
@@ -85,7 +88,7 @@ choose a text colour, WCAG 2 to promise a number.
85
88
 
86
89
  - Every field takes `size`, `disabled`, `error` (a red frame). The message, the label and the hint go through
87
90
  **`TaoFormField`** (`label`, `hint`, `error`), which also wires `id`, `aria-describedby` and `aria-invalid`.
88
- - `TaoInput`, `TaoTextarea`, `TaoInputNumber`, `TaoQuantity`, `TaoSelect`, `TaoCombobox`, `TaoDate` (`editable` to type `5`, `5.3`, `05.03.26`) / `TaoDateRange`
91
+ - `TaoInput`, `TaoTextarea`, `TaoInputNumber`, `TaoQuantity`, `TaoSelect`, `TaoCombobox`, `TaoPresetInput` (a field with presets and two arrows, e.g. font size or zoom: `options` with `default: true` for «Auto», `loop`, `custom`), `TaoDate` (`editable` to type `5`, `5.3`, `05.03.26`) / `TaoDateRange`
89
92
  (`YYYY-MM-DD` strings), `TaoCalendar` (the inline month calendar, `mode="single" | "range"`), `TaoCheckbox`,
90
93
  `TaoChecklist` (one model for a group), `TaoRadioGroup` + `TaoRadio`, `TaoSwitch`, `TaoSegmented`, `TaoSlider` /
91
94
  `TaoRangeSlider`, `TaoPinCode` (`status="success | error"` after `complete`), `TaoColorInput` / `TaoColorPicker`,
@@ -119,7 +122,7 @@ choose a text colour, WCAG 2 to promise a number.
119
122
  `TaoTree` (expand, select, tri-state `checkable`, lazy `load`), `TaoStages`, `TaoTimeline` (`active` makes it a progress),
120
123
  `TaoTag`, `TaoAvatar`, `TaoImage`, `TaoCarousel`, `TaoCard` (`#media`, `#title`, `#sub`, `#footer`, `#corner`, `closable`,
121
124
  `stripe` + `stripeTone`), `TaoBlock`, `TaoTabs`, `TaoBreadcrumb`, `TaoLink`, `TaoStretchedLink` (a whole card or row as one link, the buttons inside still work: `tao-stretched` on the container, `tao-stretched-raise` on a control that must click by itself; never `filter` / `transform` on the link), `TaoSpoiler` / `TaoSpoilerGroup`, `TaoCounter`,
122
- `TaoCopy`, `TaoTour` (a guided tour: `:step` / `:index` / `:count`, events `next` / `prev` / `skip`; it only draws, the state is yours or TaoUX `useTour`; a step is `{ id, target?, title?, text?, placement? }`), `TaoThemeToggle` (the light / dark switch as an icon button: flips `data-tao-mode` of `<html>`, or `v-model` with `:apply="false"`; `#icon="{ mode, next }"` for your own glyph), `TaoMarquee` (one line that runs round only when it does not fit), `TaoScrubber` (play / pause + time),
125
+ `TaoCopy`, `TaoTour` (a guided tour: `:step` / `:index` / `:count`, events `next` / `prev` / `skip`; it only draws, the state is yours or TaoUX `useTour`; a step is `{ id, target?, title?, text?, placement? }`), `TaoThemeToggle` (the light / dark switch as an icon button: flips `data-tao-mode` of `<html>`, or `v-model` with `:apply="false"`; `system` adds a third state, «follow the OS» (click: system → light → dark; `v-model` then holds `'system'` too, resolve it with `resolveTaoMode()`); `#icon="{ mode, choice, next }"` for your own glyph), `TaoMarquee` (one line that runs round only when it does not fit), `TaoScrubber` (play / pause + time),
123
126
  `TaoScrollTop`, `TaoAnimatedBorder`, `TaoIcon`.
124
127
 
125
128
  Small charts only: `TaoSparkline` (a trend), `TaoMeter` (a value in a range, `low` / `high` / `optimum`), `TaoDonut`
@@ -129,7 +132,7 @@ library and feed it `taoChartTheme()` / `watchTaoChartTheme(apply)`; do not buil
129
132
 
130
133
  ## Icons
131
134
 
132
- `<TaoIcon name="tao-check" />`: 42 built-in SVG icons under the `tao-` prefix (incl. `tao-settings`, `tao-edit`, `tao-trash`, `tao-bell`, `tao-tag`, `tao-repeat`, `tao-undo`, `tao-redo`, `tao-sun`, `tao-moon`) (`taoIconNames`). Your own:
135
+ `<TaoIcon name="tao-check" />`: 43 built-in SVG icons under the `tao-` prefix (incl. `tao-settings`, `tao-edit`, `tao-trash`, `tao-bell`, `tao-tag`, `tao-repeat`, `tao-undo`, `tao-redo`, `tao-sun`, `tao-moon`, `tao-monitor`) (`taoIconNames`). Your own:
133
136
  `registerTaoIcons({ rocket: { body: '<path d="…"/>' } })` on a 24 grid with `currentColor`; add `grid: true` for icons made
134
137
  only of straight lines through the middle (a plus), so they stay crisp when small. Any other name renders the class
135
138
  `icon-<name>` for an icon font you bring.
@@ -142,14 +142,17 @@ Showcase section: `#theme-toggle`
142
142
 
143
143
  | Prop | Type | Default | Notes |
144
144
  |---|---|---|---|
145
- | `v-model` | `'dark' \| 'light'` | page mode | The mode. Without it the button reads the mode of <html> (data-tao-mode) and follows it |
145
+ | `v-model` | `'dark' \| 'light' \| 'system'` | page mode | The mode ('system' only with system). Without it the button reads the mode of <html> (data-tao-mode) and follows it |
146
146
  | `apply` | `boolean` | true | Write the mode to <html>. Turn it off to do it yourself from v-model (save the choice, change a class) |
147
+ | `system` | `boolean` | false | A third state, "system": the page follows the operating system (prefers-color-scheme, live). The click goes system → light → dark; the icon is the state the toggle is in (a monitor for the system) |
147
148
  | `size` | `'small' \| 'medium' \| 'large'` | from ancestors | Button size |
148
149
  | `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'text'` | 'ghost' | Button look |
149
- | `toLightLabel` | `string` | 'Switch to the light theme' | aria-label while the theme is dark (what a click does) |
150
- | `toDarkLabel` | `string` | 'Switch to the dark theme' | aria-label while the theme is light |
150
+ | `tone` | `'accent' \| 'neutral' \| …` | 'neutral' | The colour of the button, as for TaoButton. neutral by default: a switch is a quiet tool, the accent is not for it |
151
+ | `toLightLabel` | `string` | 'Switch to the light theme' | aria-label while a click leads to the light theme |
152
+ | `toDarkLabel` | `string` | 'Switch to the dark theme' | aria-label while a click leads to the dark theme |
153
+ | `toSystemLabel` | `string` | 'Switch to the system theme' | aria-label while a click leads to the system theme (system) |
151
154
 
152
- **Slots, events, notes.** icon: your own glyph, { mode, next } (the current mode and the one a click leads to); the button stays a square and keeps its label. update:modelValue and change: the new mode ("dark" \| "light"). The icon is the theme a click leads to (a sun while dark, a moon while light).
155
+ **Slots, events, notes.** icon: your own glyph, { mode, choice, next } (the mode on the page, the pick — "system" included —, and the pick a click leads to); the button stays a square and keeps its label. update:modelValue and change: the new pick ("dark" \| "light", and "system" with system). Without system the icon is the theme a click leads to (a sun while dark, a moon while light).
153
156
 
154
157
  ## TaoInput
155
158
 
@@ -376,6 +379,27 @@ Showcase section: `#combobox`
376
379
 
377
380
  **Slots, events, notes.** create — an event when a new value is typed: the parent extends options itself.
378
381
 
382
+ ## TaoPresetInput
383
+
384
+ Showcase section: `#preset-input`
385
+
386
+ | Prop | Type | Default | Notes |
387
+ |---|---|---|---|
388
+ | `v-model` | `string \| number \| null` | null | The value: the value of an option, or a number typed by hand (custom) |
389
+ | `options` | `{ value, label, disabled?, default? }[]` | [] | The presets. They go in this order in the pop-up, and the arrows walk them in it («up» is the next one). The option with default is what an empty field means («Auto»): the pop-up shows it first, and the arrows reach it after the last one |
390
+ | `loop` | `boolean` | false | The arrows go round: past the last one the first, before the first one the last. Without it the ends hold |
391
+ | `custom` | `boolean` | true | A whole number that is not in the list is a value too (between min and max). Off: only the presets |
392
+ | `min` | `number` | 1 | The lowest typed number (custom) |
393
+ | `max` | `number` | 999 | The highest typed number (custom) |
394
+ | `size` | `'small' \| 'medium' \| 'large'` | from ancestors | Size, the same scale as TaoButton |
395
+ | `variant` | `'filled' \| 'outline'` | 'filled' | filled: a fill, the frame shows while the field is edited; outline: a frame |
396
+ | `disabled` | `boolean` | false | Disabled |
397
+ | `error` | `boolean` | false | A red border. The error text is error on TaoFormField |
398
+ | `nextLabel` | `string` | 'Next value' | aria-label of the up arrow |
399
+ | `prevLabel` | `string` | 'Previous value' | aria-label of the down arrow |
400
+
401
+ **Slots, events, notes.** aria-label, name, autocomplete and listeners reach the input, class and style the wrapper. The width of the input is the variable --tao-preset-input-width (4.5rem). update:modelValue and change: the new value. Keys: ↑ ↓ step, Home End go to the ends, Enter applies, Esc throws the text away; Tab applies and goes on. The arrows are not tab stops.
402
+
379
403
  ## TypeaheadPlayground
380
404
 
381
405
  Showcase section: `#typeahead`
@@ -1,163 +1,210 @@
1
- # TaoUI patterns: what to use when, and why
2
-
3
- Generated from the Guide of the showcase (`showcase/guide/patterns/`) by `npm run skill`; do not edit by hand.
4
- Read it before you compose a screen. The page with the live examples: showcase `#patterns` (the Guide book).
5
- The examples use your own icons (`bold`, `italic`) registered with `registerTaoIcons`; `tao-*` icons are built in.
6
-
7
- ## The accent budget
8
-
9
- The accent colour (amber by default) is a signal, and a signal that is on everywhere says nothing. Spend it on three things only: the one main action of a region, the current or selected item, the focus ring.
10
-
11
- 1. One filled accent button (`variant="primary"`) per region. Next to it: `secondary`, or `ghost` with `tone="neutral"`, or `text`.
12
- 2. Quiet tools (a toolbar, the actions of a row, icon buttons in a header) are `variant="ghost" tone="neutral"`. A `ghost` or `text` button without `tone` is accent-coloured: use it only for an action that really is the main one in its place.
13
- 3. Status is `tone` (`success`, `danger`, `warning`, `info`), always with words, never colour alone. A destructive action is `tone="danger"` on the button that destroys; the safe button stays quiet.
14
- 4. Colours come from roles (`var(--tao-color-…)`), never a hex or an `rgba()` in app CSS.
15
-
16
- ## Choosing a size
17
-
18
- Medium is the default, and the right answer unless there is a reason. A size is a decision about a region of the screen, not about a button: how many controls sit close together, how much they matter, and what presses them (a mouse or a finger).
19
-
20
- | Size | Height | Text | Side padding | Use it for | What it costs |
21
- |---|---|---|---|---|---|
22
- | `small` | 26px | 12px | 12px | Only where a lot sits close together and a mouse is the pointer: the actions in a row of a dense table or list, a power-user tool with dozens of controls. Not a toolbar or an editor panel, not a filter or settings bar, not a popover or a menu: an editor that people use all day, above all one for clients, stays medium, or it grows small buttons that are hard to hit. | A small hit area (26px: above the 24px WCAG 2.2 minimum, below the 44px a finger needs) and 12px text. Not for the main action of a screen, not where the only pointer is a finger. |
23
- | `medium` | 36px | 14px | 16px | Forms and the content of the page. The default: do not set `size` at all. | None; it is the scale everything else is drawn for. |
24
- | `large` | 44px | 16px | 24px | The one thing the screen is for: a sign-in or checkout button, a call to action on a landing page, a kiosk, a form people fill in on a phone, a reader who needs bigger targets. | Takes room and is loud: in a dense panel it pushes the rest out. |
25
-
26
- Density is added on top of the size (the height and the padding, not the font), as a class on a container or on `<html>`:
27
-
28
- | Density | small | medium | large | |
29
- |---|---|---|---|---|
30
- | `tao-density-compact` | 22px | 32px | 40px | dense tools and tables |
31
- | `tao-density-default` | 26px | 36px | 44px | the default |
32
- | `tao-density-comfortable` | 34px | 44px | 52px | a touch-sized row |
33
- | `tao-density-auto` | comfortable under a finger (`pointer: coarse`), default with a mouse | | | |
34
-
35
- 1. Do not change the size unless you know exactly why. Leave medium: it is the scale everything is drawn for. A small control is a deliberate choice for a dense region, and you should be able to name the region and what is crowded in it; "it looks big" is not a reason, and neither is "it is a utility thing".
36
- 2. Decide for a region, with one class on the container (`class="tao-size-small"`), never for a control (see "Controls side by side").
37
- 3. Importance is `variant` and `tone`, not size. Inside one region the main action is as tall as its neighbours; a bigger control belongs to a different region (a hero block), not to emphasis in a row.
38
- 4. Small is for the supporting cast. If the control is why the person came to the screen, it is medium or large.
39
- 5. A phone is a question of density, not of size: put `tao-density-auto` on `<html>`. The same medium becomes 44px under a finger and stays 36px with a mouse; the font does not change. `large` on a phone is for the hero action only.
40
- 6. Do not shrink to fit. If it does not fit, wrap, scroll or move the rest into a menu: small controls that are cramped are still cramped.
41
- 7. Where did the small come from? The size is inherited. In DevTools read the computed `--tao-size` and `--tao-density` on the element, then walk up to the ancestor that sets `tao-size-*` / `tao-density-*` (or a `size` on a `TaoFormField` / `TaoInputGroup`, or a pinned `--tao-control-height`). Nothing else changes the size of a control.
42
-
43
- ## A toolbar of tools
44
-
45
- **When.** A bar of formatting or editing tools: text style toggles, undo and redo, a few actions.
46
-
47
- **Rule.** Every button is `variant="ghost" tone="neutral"`, an icon with an `aria-label`. A toggle is `v-model:pressed`. Group related tools with `TaoToolbarGroup` and split the groups with `TaoToolbarSeparator`. Leave the size medium: a small toolbar is hard to hit (see "Choosing a size"). If it has to stay one row (a phone), add `overflow` to the toolbar instead of making the buttons smaller: the groups that do not fit go under «⋮», and `pinned` keeps a group (undo and redo) in sight.
48
-
49
- **Do:**
50
-
51
- ```vue
52
- <TaoToolbar label="Formatting">
53
- <TaoToolbarGroup label="Text style">
54
- <TaoButton v-model:pressed="bold" variant="ghost" tone="neutral" icon="bold" aria-label="Bold" />
55
- <TaoButton v-model:pressed="italic" variant="ghost" tone="neutral" icon="italic" aria-label="Italic" />
56
- </TaoToolbarGroup>
57
- <TaoToolbarSeparator />
58
- <TaoButton variant="ghost" tone="neutral" icon="tao-undo" aria-label="Undo" />
59
- <TaoButton variant="ghost" tone="neutral" icon="tao-redo" aria-label="Redo" />
60
- </TaoToolbar>
61
- ```
62
-
63
- **Don't** (No `tone`: every tool is amber):
64
-
65
- ```vue
66
- <TaoToolbar label="Formatting">
67
- <TaoToolbarGroup label="Text style">
68
- <TaoButton v-model:pressed="bold" variant="ghost" icon="bold" aria-label="Bold" />
69
- <TaoButton v-model:pressed="italic" variant="ghost" icon="italic" aria-label="Italic" />
70
- </TaoToolbarGroup>
71
- <TaoToolbarSeparator />
72
- <TaoButton variant="ghost" icon="tao-undo" aria-label="Undo" />
73
- <TaoButton variant="ghost" icon="tao-redo" aria-label="Redo" />
74
- </TaoToolbar>
75
- ```
76
-
77
- **Why.** In a toolbar every button is a tool and none is the main one, so none may take the accent. Left amber, the bar shouts, and the one thing that must stand out, which toggles are on, is lost: it is the same colour as the rest. In neutral the pressed toggle is the only lit thing.
78
-
79
- ## The footer of a form or dialog
80
-
81
- **When.** The buttons at the bottom of a form, a modal or a drawer: confirm and cancel.
82
-
83
- **Rule.** The confirming action is the one primary button, at the end. Cancel is `secondary` (or `ghost` with `tone="neutral"`), before it.
84
-
85
- **Do:**
86
-
87
- ```vue
88
- <TaoFlex justify="flex-end" :gap="8">
89
- <TaoButton variant="secondary">Cancel</TaoButton>
90
- <TaoButton>Save</TaoButton>
91
- </TaoFlex>
92
- ```
93
-
94
- **Don't** (Two filled accent buttons: Cancel looks as important as Save):
95
-
96
- ```vue
97
- <TaoFlex justify="flex-end" :gap="8">
98
- <TaoButton>Cancel</TaoButton>
99
- <TaoButton>Save</TaoButton>
100
- </TaoFlex>
101
- ```
102
-
103
- **Why.** Two filled accent buttons side by side make the eye choose between them. The footer has one answer the user is expected to give; the other button is the way out, and it looks like one.
104
-
105
- ## Controls side by side: one size
106
-
107
- **When.** A row or a panel with several controls: a segmented switch, a select, buttons, inputs. Also the content of a popover.
108
-
109
- **Rule.** Put one context class on the container: `class="tao-size-small"` (and `tao-density-*`). Do not pass `size` to some of the controls, and do not pin a height (`--tao-control-height: 32px`, `height: 32px`) on one of them. An explicit `size` is for the one control that must stand out. A `TaoPopover` panel, a select list and a combobox list carry the size and the density of where they hang from.
110
-
111
- **Do:**
112
-
113
- ```vue
114
- <TaoFlex class="tao-size-small" align="center" :gap="8">
115
- <TaoSegmented v-model="mode" aria-label="Mode">
116
- <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
117
- <TaoSegmentedOption value="list">List</TaoSegmentedOption>
118
- </TaoSegmented>
119
- <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
120
- <TaoButton variant="secondary">Apply</TaoButton>
121
- </TaoFlex>
122
- ```
123
-
124
- **Don't** (On purpose: `size="small"` on the switch only, so it is shorter than the select and the button beside it):
125
-
126
- ```vue
127
- <TaoFlex align="center" :gap="8">
128
- <TaoSegmented v-model="mode" size="small" aria-label="Mode">
129
- <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
130
- <TaoSegmentedOption value="list">List</TaoSegmentedOption>
131
- </TaoSegmented>
132
- <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
133
- <TaoButton variant="secondary">Apply</TaoButton>
134
- </TaoFlex>
135
- ```
136
-
137
- **Why.** `size` is a prop with a default of medium. Set it on the controls you remember and the rest stay medium: the row comes out uneven, a small switch beside a tall select. A pinned height is the same thing by hand. The class makes them one by construction, also for the controls added later and for a panel in the body.
138
-
139
- ## A destructive action
140
-
141
- **When.** Delete, discard, reset: something that cannot be taken back.
142
-
143
- **Rule.** `tone="danger"` on the button that destroys, the safe choice quiet (`secondary`). For a question in its own window use `await confirm().title(…).message(…).danger()`: it resolves to a boolean.
144
-
145
- **Do:**
146
-
147
- ```vue
148
- <TaoFlex justify="flex-end" :gap="8">
149
- <TaoButton variant="secondary">Keep</TaoButton>
150
- <TaoButton tone="danger" icon="tao-trash">Delete</TaoButton>
151
- </TaoFlex>
152
- ```
153
-
154
- **Don't** (Red on the safe button, the accent on the one that deletes):
155
-
156
- ```vue
157
- <TaoFlex justify="flex-end" :gap="8">
158
- <TaoButton variant="secondary" tone="danger">Keep</TaoButton>
159
- <TaoButton icon="tao-trash">Delete</TaoButton>
160
- </TaoFlex>
161
- ```
162
-
163
- **Why.** The accent says "the normal main thing", and a delete wearing it looks like any other action. Red on the safe button inverts the warning: the colour then points at the wrong choice.
1
+ # TaoUI patterns: what to use when, and why
2
+
3
+ Generated from the Guide of the showcase (`showcase/guide/patterns/`) by `npm run skill`; do not edit by hand.
4
+ Read it before you compose a screen. The page with the live examples: showcase `#patterns` (the Guide book).
5
+ The examples use your own icons (`bold`, `italic`) registered with `registerTaoIcons`; `tao-*` icons are built in.
6
+
7
+ ## The accent budget
8
+
9
+ The accent colour (amber by default) is a signal, and a signal that is on everywhere says nothing. Spend it on three things only: the one main action of a region, the current or selected item, the focus ring.
10
+
11
+ 1. One filled accent button (`variant="primary"`) per region. Next to it: `secondary`, or `ghost` with `tone="neutral"`, or `text`.
12
+ 2. Quiet tools (a toolbar, the actions of a row, icon buttons in a header) are `variant="ghost" tone="neutral"`. A `ghost` or `text` button without `tone` is accent-coloured: use it only for an action that really is the main one in its place.
13
+ 3. Status is `tone` (`success`, `danger`, `warning`, `info`), always with words, never colour alone. A destructive action is `tone="danger"` on the button that destroys; the safe button stays quiet.
14
+ 4. Colours come from roles (`var(--tao-color-…)`), never a hex or an `rgba()` in app CSS.
15
+
16
+ ## The text ladder
17
+
18
+ Text has five steps, from `text-strong` to `text-disabled`, and each says one thing. Body copy and quiet controls sit on `text` (a soft grey, easy on a dark page); white is kept for what must stand out, so it still does. This is the order in the kit: pick the step by the job of the text, never by taste, and never write a colour of your own.
19
+
20
+ | Role | Dark theme | Use it for |
21
+ |---|---|---|
22
+ | `--tao-color-text-strong` | #ffffff | Headings, titles of a card, a modal or an alert, the value that is the point (a figure, a slider value), and the hover of a quiet control. Never a control at rest. |
23
+ | `--tao-color-text` | #bfbfbf | Body copy and every control at rest: buttons (`secondary`, `ghost` and `text` with `tone="neutral"`), field values, form labels, menu items, table cells. |
24
+ | `--tao-color-text-subtle` | #999999 | The option that is not chosen in a group: idle tabs and segments. |
25
+ | `--tao-color-text-muted` | #8a8a8a | Captions, hints, descriptions, table headers, placeholders, breadcrumb links, icons that do nothing. |
26
+ | `--tao-color-text-disabled` | #444444 | What cannot be used now. |
27
+
28
+ 1. Hover moves one step up the ladder: `muted` to `text`, `text` to `strong`. A control never gets dimmer under the pointer.
29
+ 2. The accent is not a step of the ladder. It is for the main action, what is selected or current, the focus and a link in running text. A quiet tool is never accent-coloured at rest.
30
+ 3. Status colours (`success`, `danger`, `warning`, `info`) say a status, with words beside them. They are not a way to make text louder.
31
+ 4. Your own markup takes the same roles: `color: var(--tao-color-text)` for body, `var(--tao-color-text-strong)` for a heading, `var(--tao-color-text-muted)` for a hint. Do not paint a whole block `strong` to make it important: when everything is white, nothing is.
32
+
33
+ ## Choosing a size
34
+
35
+ Medium is the default, and the right answer unless there is a reason. A size is a decision about a region of the screen, not about a button: how many controls sit close together, how much they matter, and what presses them (a mouse or a finger).
36
+
37
+ | Size | Height | Text | Side padding | Use it for | What it costs |
38
+ |---|---|---|---|---|---|
39
+ | `small` | 26px | 12px | 12px | Only where a lot sits close together and a mouse is the pointer: the actions in a row of a dense table or list, a power-user tool with dozens of controls. Not a toolbar or an editor panel, not a filter or settings bar, not a popover or a menu: an editor that people use all day, above all one for clients, stays medium, or it grows small buttons that are hard to hit. | A small hit area (26px: above the 24px WCAG 2.2 minimum, below the 44px a finger needs) and 12px text. Not for the main action of a screen, not where the only pointer is a finger. |
40
+ | `medium` | 36px | 14px | 16px | Forms and the content of the page. The default: do not set `size` at all. | None; it is the scale everything else is drawn for. |
41
+ | `large` | 44px | 16px | 24px | The one thing the screen is for: a sign-in or checkout button, a call to action on a landing page, a kiosk, a form people fill in on a phone, a reader who needs bigger targets. | Takes room and is loud: in a dense panel it pushes the rest out. |
42
+
43
+ Density is added on top of the size (the height and the padding, not the font), as a class on a container or on `<html>`:
44
+
45
+ | Density | small | medium | large | |
46
+ |---|---|---|---|---|
47
+ | `tao-density-compact` | 22px | 32px | 40px | dense tools and tables |
48
+ | `tao-density-default` | 26px | 36px | 44px | the default |
49
+ | `tao-density-comfortable` | 34px | 44px | 52px | a touch-sized row |
50
+ | `tao-density-auto` | comfortable under a finger (`pointer: coarse`), default with a mouse | | | |
51
+
52
+ 1. Do not change the size unless you know exactly why. Leave medium: it is the scale everything is drawn for. A small control is a deliberate choice for a dense region, and you should be able to name the region and what is crowded in it; "it looks big" is not a reason, and neither is "it is a utility thing".
53
+ 2. Decide for a region, with one class on the container (`class="tao-size-small"`), never for a control (see "Controls side by side").
54
+ 3. Importance is `variant` and `tone`, not size. Inside one region the main action is as tall as its neighbours; a bigger control belongs to a different region (a hero block), not to emphasis in a row.
55
+ 4. Small is for the supporting cast. If the control is why the person came to the screen, it is medium or large.
56
+ 5. A phone is a question of density, not of size: put `tao-density-auto` on `<html>`. The same medium becomes 44px under a finger and stays 36px with a mouse; the font does not change. `large` on a phone is for the hero action only.
57
+ 6. Do not shrink to fit. If it does not fit, wrap, scroll or move the rest into a menu: small controls that are cramped are still cramped.
58
+ 7. Where did the small come from? The size is inherited. In DevTools read the computed `--tao-size` and `--tao-density` on the element, then walk up to the ancestor that sets `tao-size-*` / `tao-density-*` (or a `size` on a `TaoFormField` / `TaoInputGroup`, or a pinned `--tao-control-height`). Nothing else changes the size of a control.
59
+
60
+ ## A toolbar of tools
61
+
62
+ **When.** A bar of formatting or editing tools: text style toggles, undo and redo, a few actions.
63
+
64
+ **Rule.** Every button is `variant="ghost" tone="neutral"`, an icon with an `aria-label`. A toggle is `v-model:pressed`. Group related tools with `TaoToolbarGroup` and split the groups with `TaoToolbarSeparator`. Leave the size medium: a small toolbar is hard to hit (see "Choosing a size"). If it has to stay one row (a phone), add `overflow` to the toolbar instead of making the buttons smaller: the groups that do not fit go under «⋮», and `pinned` keeps a group (undo and redo) in sight.
65
+
66
+ **Do:**
67
+
68
+ ```vue
69
+ <TaoToolbar label="Formatting">
70
+ <TaoToolbarGroup label="Text style">
71
+ <TaoButton v-model:pressed="bold" variant="ghost" tone="neutral" icon="bold" aria-label="Bold" />
72
+ <TaoButton v-model:pressed="italic" variant="ghost" tone="neutral" icon="italic" aria-label="Italic" />
73
+ </TaoToolbarGroup>
74
+ <TaoToolbarSeparator />
75
+ <TaoButton variant="ghost" tone="neutral" icon="tao-undo" aria-label="Undo" />
76
+ <TaoButton variant="ghost" tone="neutral" icon="tao-redo" aria-label="Redo" />
77
+ </TaoToolbar>
78
+ ```
79
+
80
+ **Don't** (No `tone`: every tool is amber):
81
+
82
+ ```vue
83
+ <TaoToolbar label="Formatting">
84
+ <TaoToolbarGroup label="Text style">
85
+ <TaoButton v-model:pressed="bold" variant="ghost" icon="bold" aria-label="Bold" />
86
+ <TaoButton v-model:pressed="italic" variant="ghost" icon="italic" aria-label="Italic" />
87
+ </TaoToolbarGroup>
88
+ <TaoToolbarSeparator />
89
+ <TaoButton variant="ghost" icon="tao-undo" aria-label="Undo" />
90
+ <TaoButton variant="ghost" icon="tao-redo" aria-label="Redo" />
91
+ </TaoToolbar>
92
+ ```
93
+
94
+ **Why.** In a toolbar every button is a tool and none is the main one, so none may take the accent. Left amber, the bar shouts, and the one thing that must stand out, which toggles are on, is lost: it is the same colour as the rest. In neutral the pressed toggle is the only lit thing.
95
+
96
+ ## A block of text and a quiet action
97
+
98
+ **When.** A panel with a title, a few lines of copy, a hint and one quiet action: a settings block, an info card.
99
+
100
+ **Rule.** Title `text-strong`, copy `text`, hint `text-muted`, and the action `variant="ghost" tone="neutral"`. Every step does its own job, and the colours are roles, not hex.
101
+
102
+ **Do:**
103
+
104
+ ```vue
105
+ <div class="tao-panel" style="padding: 16px; display: grid; gap: 6px; justify-items: start">
106
+ <strong style="color: var(--tao-color-text-strong)">Billing</strong>
107
+ <span style="color: var(--tao-color-text)">Your plan renews on 1 December.</span>
108
+ <small style="color: var(--tao-color-text-muted)">Invoices go to the owner of the account.</small>
109
+ <TaoButton variant="ghost" tone="neutral">Change plan</TaoButton>
110
+ </div>
111
+ ```
112
+
113
+ **Don't** (The copy is `text-strong`, the hint is accent, the action has no `tone`: three colours, no order):
114
+
115
+ ```vue
116
+ <div class="tao-panel" style="padding: 16px; display: grid; gap: 6px; justify-items: start">
117
+ <strong style="color: var(--tao-color-text-muted)">Billing</strong>
118
+ <span style="color: var(--tao-color-text-strong)">Your plan renews on 1 December.</span>
119
+ <small style="color: var(--tao-color-accent)">Invoices go to the owner of the account.</small>
120
+ <TaoButton variant="ghost">Change plan</TaoButton>
121
+ </div>
122
+ ```
123
+
124
+ **Why.** The eye reads the colour as rank. With the copy as bright as the title the title no longer leads; an accent hint and an amber action look like two main things on one panel. With the ladder the title leads, the copy reads, the hint steps back, and the one quiet action is found when it is needed.
125
+
126
+ ## The footer of a form or dialog
127
+
128
+ **When.** The buttons at the bottom of a form, a modal or a drawer: confirm and cancel.
129
+
130
+ **Rule.** The confirming action is the one primary button, at the end. Cancel is `secondary` (or `ghost` with `tone="neutral"`), before it.
131
+
132
+ **Do:**
133
+
134
+ ```vue
135
+ <TaoFlex justify="flex-end" :gap="8">
136
+ <TaoButton variant="secondary">Cancel</TaoButton>
137
+ <TaoButton>Save</TaoButton>
138
+ </TaoFlex>
139
+ ```
140
+
141
+ **Don't** (Two filled accent buttons: Cancel looks as important as Save):
142
+
143
+ ```vue
144
+ <TaoFlex justify="flex-end" :gap="8">
145
+ <TaoButton>Cancel</TaoButton>
146
+ <TaoButton>Save</TaoButton>
147
+ </TaoFlex>
148
+ ```
149
+
150
+ **Why.** Two filled accent buttons side by side make the eye choose between them. The footer has one answer the user is expected to give; the other button is the way out, and it looks like one.
151
+
152
+ ## Controls side by side: one size
153
+
154
+ **When.** A row or a panel with several controls: a segmented switch, a select, buttons, inputs. Also the content of a popover.
155
+
156
+ **Rule.** Put one context class on the container: `class="tao-size-small"` (and `tao-density-*`). Do not pass `size` to some of the controls, and do not pin a height (`--tao-control-height: 32px`, `height: 32px`) on one of them. An explicit `size` is for the one control that must stand out. A `TaoPopover` panel, a select list and a combobox list carry the size and the density of where they hang from.
157
+
158
+ **Do:**
159
+
160
+ ```vue
161
+ <TaoFlex class="tao-size-small" align="center" :gap="8">
162
+ <TaoSegmented v-model="mode" aria-label="Mode">
163
+ <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
164
+ <TaoSegmentedOption value="list">List</TaoSegmentedOption>
165
+ </TaoSegmented>
166
+ <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
167
+ <TaoButton variant="secondary">Apply</TaoButton>
168
+ </TaoFlex>
169
+ ```
170
+
171
+ **Don't** (On purpose: `size="small"` on the switch only, so it is shorter than the select and the button beside it):
172
+
173
+ ```vue
174
+ <TaoFlex align="center" :gap="8">
175
+ <TaoSegmented v-model="mode" size="small" aria-label="Mode">
176
+ <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
177
+ <TaoSegmentedOption value="list">List</TaoSegmentedOption>
178
+ </TaoSegmented>
179
+ <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
180
+ <TaoButton variant="secondary">Apply</TaoButton>
181
+ </TaoFlex>
182
+ ```
183
+
184
+ **Why.** `size` is a prop with a default of medium. Set it on the controls you remember and the rest stay medium: the row comes out uneven, a small switch beside a tall select. A pinned height is the same thing by hand. The class makes them one by construction, also for the controls added later and for a panel in the body.
185
+
186
+ ## A destructive action
187
+
188
+ **When.** Delete, discard, reset: something that cannot be taken back.
189
+
190
+ **Rule.** `tone="danger"` on the button that destroys, the safe choice quiet (`secondary`). For a question in its own window use `await confirm().title(…).message(…).danger()`: it resolves to a boolean.
191
+
192
+ **Do:**
193
+
194
+ ```vue
195
+ <TaoFlex justify="flex-end" :gap="8">
196
+ <TaoButton variant="secondary">Keep</TaoButton>
197
+ <TaoButton tone="danger" icon="tao-trash">Delete</TaoButton>
198
+ </TaoFlex>
199
+ ```
200
+
201
+ **Don't** (Red on the safe button, the accent on the one that deletes):
202
+
203
+ ```vue
204
+ <TaoFlex justify="flex-end" :gap="8">
205
+ <TaoButton variant="secondary" tone="danger">Keep</TaoButton>
206
+ <TaoButton icon="tao-trash">Delete</TaoButton>
207
+ </TaoFlex>
208
+ ```
209
+
210
+ **Why.** The accent says "the normal main thing", and a delete wearing it looks like any other action. Red on the safe button inverts the warning: the colour then points at the wrong choice.
@@ -73,7 +73,9 @@
73
73
  /* white on the mid grey in both themes (5.7:1); the page colour was dark on dark in the dark theme (3.4:1)
74
74
  белое на среднем сером в обеих темах; цвет страницы в тёмной теме давал тёмное на тёмном */
75
75
  --tao-tone-on: var(--tao-color-on-neutral);
76
- --tao-tone-text: var(--tao-color-text-strong);
76
+ /* the text contract: the body colour at rest, one step up (strong) on hover; strong at rest is for titles
77
+ контракт текста: в покое цвет основного текста, при наведении ступенью выше (strong); strong в покое — для заголовков */
78
+ --tao-tone-text: var(--tao-color-text);
77
79
  --tao-tone-text-hover: var(--tao-color-text-strong);
78
80
  --tao-tone-subtle: color-mix(in srgb, var(--tao-color-neutral) 15%, transparent);
79
81
  --tao-tone-wash: var(--tao-color-accent-subtle-hover);