@1337exp/taoui 5.28.0 → 5.30.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 +22 -0
- package/README.md +1 -1
- package/README.ru.md +1 -1
- package/dist/index.d.ts +20 -3
- package/dist/index.js +242 -98
- package/dist/index.js.map +1 -1
- package/dist/styles.css +1 -1
- package/package.json +2 -2
- package/skills/taoui/SKILL.md +8 -2
- package/skills/taoui/references/components.md +1297 -1295
- package/skills/taoui/references/patterns.md +163 -0
|
@@ -0,0 +1,163 @@
|
|
|
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 | Tools that serve the content, not the task itself: a toolbar or an editor panel, a filter or settings bar, the actions in a table or list row, a utility panel (the bar of this showcase). Many controls close together, a mouse first. A popover or a menu with a few controls is not that: it stays medium, small ones stick together there. | 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`.
|
|
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.
|