@flytedan/flytebot-design-system 0.93.2 → 0.94.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/DESIGN-PRINCIPLES.md +114 -0
- package/README.md +7 -0
- package/dist/index.cjs +1054 -1514
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +6 -64
- package/dist/index.d.ts +6 -64
- package/dist/index.js +1050 -1513
- package/dist/index.js.map +1 -1
- package/package.json +3 -1
- package/styles/components.css +7 -109
- package/styles/tokens.css +114 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Flytedesk design principles
|
|
2
|
+
|
|
3
|
+
These are the UI design and interaction rules for every Flytedesk app built on
|
|
4
|
+
`@flytedan/flytebot-design-system`. Read them before you design or build any
|
|
5
|
+
screen, a mini-app design included. A design that breaks one of them is not
|
|
6
|
+
ready to show anyone.
|
|
7
|
+
|
|
8
|
+
This file is the one home of these rules. It ships in the package
|
|
9
|
+
(`node_modules/@flytedan/flytebot-design-system/DESIGN-PRINCIPLES.md`) and is
|
|
10
|
+
shown in the docs site under **Guides › Design principles**. Each rule names
|
|
11
|
+
the component that carries it out; open that component's docs page before
|
|
12
|
+
using it.
|
|
13
|
+
|
|
14
|
+
## 1. Before you design
|
|
15
|
+
|
|
16
|
+
- **Study a polished app that solves the same problem, and look at it for
|
|
17
|
+
real.** For cards, comments, inputs and menus that app is 50 Arms. Open it,
|
|
18
|
+
take screenshots and note what it does before drawing anything; match it or
|
|
19
|
+
beat it. If you could not see it, say so plainly, and never call a design
|
|
20
|
+
modelled on something you did not look at.
|
|
21
|
+
Example: before designing a card's comment thread, open a 50 Arms card and
|
|
22
|
+
its comments sidebar.
|
|
23
|
+
- **Start from the design system's components.** Browse the docs site first.
|
|
24
|
+
When a component is missing or falls short, fix or add it in the design
|
|
25
|
+
system and release it, never hand-roll it in the app.
|
|
26
|
+
Example: a squeezed calendar grid is fixed in `Calendar`, not patched with
|
|
27
|
+
app CSS.
|
|
28
|
+
|
|
29
|
+
## 2. Show only what is needed
|
|
30
|
+
|
|
31
|
+
- **Never show an input before it is needed.** An add action is a subtle
|
|
32
|
+
button (`Button variant="ghost"` with a plus icon). Pressing it creates the
|
|
33
|
+
new item with its field focused, and the person types the value then.
|
|
34
|
+
Example: a checklist ends in a quiet "+ Add item" button, not an empty
|
|
35
|
+
"Add an item" field.
|
|
36
|
+
- **Put the important information up front and the rest one step away.** Use
|
|
37
|
+
`Tabs`, `Collapsible`, `Popover`, icon indicators that open a popover, or a
|
|
38
|
+
side panel. Never stack every part of an object in one long list.
|
|
39
|
+
Example: a card page shows its title, status and description; checklists,
|
|
40
|
+
links and activity sit behind tabs or collapsible sections with counts.
|
|
41
|
+
- **Properties live in compact indicators, not a separate properties panel.**
|
|
42
|
+
Each property is a small indicator (an icon, chip or avatar stack) where the
|
|
43
|
+
object is shown. Hovering it shows its quick details in a `Tooltip`, whose
|
|
44
|
+
`label` takes rich content (bold, icons, a short list). Clicking it opens a
|
|
45
|
+
`Popover` with all the details and the controls to change them.
|
|
46
|
+
`StatusIndicator` is the read-only form, a status chip that explains itself
|
|
47
|
+
in a popover.
|
|
48
|
+
Example: a card header's members indicator shows names on hover; a click
|
|
49
|
+
opens a popover listing every member, with search, add and remove.
|
|
50
|
+
- **Secondary panels open as a sidebar, never inline.** Comments, activity
|
|
51
|
+
and inspectors are a sidebar the person opens and closes. Its header is one
|
|
52
|
+
slim line (title, count, filter, close) and its footer one slim composer.
|
|
53
|
+
`AppShell`'s `sidePanel` docks a panel beside the page on desktop and lays
|
|
54
|
+
it over the page as a `Drawer` on a phone.
|
|
55
|
+
Example: a card's comments open from a Comments button in its header.
|
|
56
|
+
|
|
57
|
+
## 3. Edit in place
|
|
58
|
+
|
|
59
|
+
- **Every value is edited inline, where it is shown.** There is no separate
|
|
60
|
+
edit form or edit mode.
|
|
61
|
+
- **Starting an edit moves nothing.** The text keeps its exact position, size
|
|
62
|
+
and font; only the cursor appears. `EditableTitle` does this for a heading
|
|
63
|
+
(Enter or leaving the field saves, Escape cancels).
|
|
64
|
+
Example: clicking a card's title puts the cursor in it with no jump, no
|
|
65
|
+
border growth and no font change.
|
|
66
|
+
- **Save feedback matches the value's importance.** An important value shows a
|
|
67
|
+
subtle saving state beside it while the save runs. A minor one shows none.
|
|
68
|
+
Example: a card's title shows a small saving mark; toggling a checklist
|
|
69
|
+
item shows nothing.
|
|
70
|
+
- **A failed save says so and reverts.** Show a real error that says what
|
|
71
|
+
failed (`useToast().show(message, { tone: "error" })`, or the field's
|
|
72
|
+
`error`) and put the
|
|
73
|
+
value back to what is saved. A value that did not save never looks saved.
|
|
74
|
+
|
|
75
|
+
## 4. The right control for each value
|
|
76
|
+
|
|
77
|
+
- **Long text uses the Markdown editor.** A description or comment is a
|
|
78
|
+
`MarkdownEditor`, shown with `Markdown`; never a plain `Textarea`.
|
|
79
|
+
- **A choice is a rich labelled input with a rich popover, never a bare
|
|
80
|
+
select.** The input shows its value richly (icon, colour, avatar, short
|
|
81
|
+
description) and opens a popover with icons, descriptions, search and, where
|
|
82
|
+
it fits, a create action. Use `Select` (options with `icon`, `description`
|
|
83
|
+
and `group`, `searchable`, `multiple`), `Menu` and `MenuButton` (items with
|
|
84
|
+
`icon`, `description`, `meta`, submenus, `header` and `footer`), or
|
|
85
|
+
`Popover` and `AnchoredPopover` for custom content.
|
|
86
|
+
Example: a label picker shows coloured chips and opens a searchable list of
|
|
87
|
+
labels with "Create label".
|
|
88
|
+
- **Dates use the date picker.** `DatePicker`, or `Calendar` inside a
|
|
89
|
+
`Popover` when the popover also offers quick choices (Today, Next week) and
|
|
90
|
+
Remove date. Never a native date input or a typed date. Times use
|
|
91
|
+
`TimePicker`; numbers use `NumberInput`.
|
|
92
|
+
|
|
93
|
+
## 5. Direct manipulation
|
|
94
|
+
|
|
95
|
+
- **Reorder by dragging, never with up and down arrow buttons.** A row shows a
|
|
96
|
+
grab cursor, follows the pointer while dragged and shows where it will land.
|
|
97
|
+
A keyboard user gets an equal move action (a row menu's Move to). Moving an
|
|
98
|
+
item between lists is `TransferList`, with `EntityRow` as the draggable row.
|
|
99
|
+
Reordering within one list has no shared component yet: add one to the
|
|
100
|
+
design system rather than building it in an app.
|
|
101
|
+
Example: checklist items are dragged into order.
|
|
102
|
+
- **Resizable panels remember their size.** A panel or drawer people read
|
|
103
|
+
beside their work is resizable, and the width they choose is kept in
|
|
104
|
+
`localStorage`, so it is the same after a reload. `AppShell`'s `sidePanel`
|
|
105
|
+
has the resize handle and reports each new width through `onWidthChange`
|
|
106
|
+
for the app to save.
|
|
107
|
+
Example: a comments sidebar dragged wider stays that wide next visit.
|
|
108
|
+
|
|
109
|
+
## 6. Check it by using it
|
|
110
|
+
|
|
111
|
+
Every screen sits inside the app's real shell (navigation, signed-in identity,
|
|
112
|
+
sign-out, Appearance) and works at phone, tablet and desktop widths. Check a
|
|
113
|
+
design by opening it at each width and pressing every control a person would
|
|
114
|
+
use.
|
package/README.md
CHANGED
|
@@ -35,6 +35,13 @@ function Example() {
|
|
|
35
35
|
}
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
+
## Design principles
|
|
39
|
+
|
|
40
|
+
`DESIGN-PRINCIPLES.md` holds the UI design and interaction rules every
|
|
41
|
+
Flytedesk app follows. It ships in the package, so an app reads it at
|
|
42
|
+
`node_modules/@flytedan/flytebot-design-system/DESIGN-PRINCIPLES.md`, and the
|
|
43
|
+
docs site shows it under Guides. Read it before designing or building a screen.
|
|
44
|
+
|
|
38
45
|
## What's in the package
|
|
39
46
|
|
|
40
47
|
**32 core components** across seven groups — actions (Button, IconButton,
|