@flytedan/flytebot-design-system 0.93.2 → 0.93.3

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.
@@ -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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flytedan/flytebot-design-system",
3
- "version": "0.93.2",
3
+ "version": "0.93.3",
4
4
  "description": "flytedesk Design System — shared component library, tokens, and business-logic kits for flytedesk apps.",
5
5
  "type": "module",
6
6
  "license": "UNLICENSED",
@@ -21,6 +21,7 @@
21
21
  },
22
22
  "files": [
23
23
  "README.md",
24
+ "DESIGN-PRINCIPLES.md",
24
25
  "dist",
25
26
  "styles",
26
27
  "assets"