@zonsh/ui 0.5.0 → 0.6.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.
Files changed (559) hide show
  1. package/CHANGELOG.md +639 -0
  2. package/README.md +49 -21
  3. package/dist/brand.d.ts +3 -0
  4. package/dist/brand.js +7 -0
  5. package/dist/components/_breadcrumb-more.d.ts +6 -0
  6. package/dist/components/_breadcrumb-more.js +5 -0
  7. package/dist/components/_drawing-svg.d.ts +11 -0
  8. package/dist/components/_drawing-svg.js +30 -0
  9. package/dist/components/_media.d.ts +159 -0
  10. package/dist/components/_media.js +266 -0
  11. package/dist/components/_overlay.d.ts +8 -5
  12. package/dist/components/_overlay.js +11 -6
  13. package/dist/components/_scheduler-calendar.d.ts +71 -0
  14. package/dist/components/_scheduler-calendar.js +940 -0
  15. package/dist/components/_scheduler-editor.d.ts +29 -0
  16. package/dist/components/_scheduler-editor.js +111 -0
  17. package/dist/components/_scheduler-menu.d.ts +16 -0
  18. package/dist/components/_scheduler-menu.js +18 -0
  19. package/dist/components/_scheduler-parts.d.ts +164 -0
  20. package/dist/components/_scheduler-parts.js +327 -0
  21. package/dist/components/_suggest-list.d.ts +142 -0
  22. package/dist/components/_suggest-list.js +159 -0
  23. package/dist/components/_toolbar-more.d.ts +24 -0
  24. package/dist/components/_toolbar-more.js +25 -0
  25. package/dist/components/accordion.d.ts +1 -1
  26. package/dist/components/accordion.js +6 -6
  27. package/dist/components/action-sheet.d.ts +88 -0
  28. package/dist/components/action-sheet.js +124 -0
  29. package/dist/components/alert-dialog.js +3 -1
  30. package/dist/components/alert.d.ts +11 -18
  31. package/dist/components/alert.js +9 -6
  32. package/dist/components/app-bar.d.ts +93 -0
  33. package/dist/components/app-bar.js +175 -0
  34. package/dist/components/audio-player.d.ts +134 -0
  35. package/dist/components/audio-player.js +618 -0
  36. package/dist/components/avatar.d.ts +6 -6
  37. package/dist/components/avatar.js +13 -11
  38. package/dist/components/badge.d.ts +12 -12
  39. package/dist/components/badge.js +7 -5
  40. package/dist/components/bottom-nav.d.ts +53 -11
  41. package/dist/components/bottom-nav.js +388 -23
  42. package/dist/components/breadcrumb.d.ts +11 -2
  43. package/dist/components/breadcrumb.js +60 -6
  44. package/dist/components/button-group.js +5 -1
  45. package/dist/components/button.d.ts +23 -6
  46. package/dist/components/button.js +63 -7
  47. package/dist/components/calendar.js +8 -6
  48. package/dist/components/card.d.ts +10 -8
  49. package/dist/components/card.js +15 -14
  50. package/dist/components/carousel.d.ts +2 -2
  51. package/dist/components/carousel.js +21 -8
  52. package/dist/components/chart.d.ts +27 -1
  53. package/dist/components/chart.js +15 -5
  54. package/dist/components/checkbox.js +2 -2
  55. package/dist/components/code-block.d.ts +9 -2
  56. package/dist/components/code-block.js +26 -7
  57. package/dist/components/collapsible.js +3 -3
  58. package/dist/components/color-picker.d.ts +2 -2
  59. package/dist/components/color-picker.js +5 -5
  60. package/dist/components/combobox.d.ts +26 -7
  61. package/dist/components/combobox.js +32 -13
  62. package/dist/components/command.d.ts +29 -5
  63. package/dist/components/command.js +35 -10
  64. package/dist/components/context-menu.d.ts +5 -2
  65. package/dist/components/context-menu.js +24 -3
  66. package/dist/components/conversation.d.ts +1 -1
  67. package/dist/components/conversation.js +67 -13
  68. package/dist/components/copy-button.d.ts +1 -1
  69. package/dist/components/copy-button.js +1 -1
  70. package/dist/components/data-table.d.ts +6 -6
  71. package/dist/components/data-table.js +41 -15
  72. package/dist/components/date-picker.d.ts +31 -9
  73. package/dist/components/date-picker.js +100 -18
  74. package/dist/components/dialog.d.ts +17 -10
  75. package/dist/components/dialog.js +20 -13
  76. package/dist/components/drawer.d.ts +26 -8
  77. package/dist/components/drawer.js +75 -16
  78. package/dist/components/drawing.d.ts +25 -0
  79. package/dist/components/drawing.js +32 -0
  80. package/dist/components/empty.js +2 -2
  81. package/dist/components/feature-list.d.ts +65 -13
  82. package/dist/components/feature-list.js +116 -15
  83. package/dist/components/field.js +2 -2
  84. package/dist/components/file-drop.d.ts +9 -7
  85. package/dist/components/file-drop.js +8 -43
  86. package/dist/components/filter-bar.d.ts +10 -9
  87. package/dist/components/filter-bar.js +42 -25
  88. package/dist/components/graph.d.ts +19 -3
  89. package/dist/components/graph.js +170 -25
  90. package/dist/components/illustration.js +3 -28
  91. package/dist/components/input-group.d.ts +5 -10
  92. package/dist/components/input-group.js +16 -16
  93. package/dist/components/input.d.ts +2 -2
  94. package/dist/components/input.js +3 -3
  95. package/dist/components/item.d.ts +9 -6
  96. package/dist/components/item.js +13 -8
  97. package/dist/components/kbd.d.ts +1 -1
  98. package/dist/components/kbd.js +1 -1
  99. package/dist/components/lightbox.d.ts +76 -9
  100. package/dist/components/lightbox.js +333 -45
  101. package/dist/components/locale.d.ts +6 -6
  102. package/dist/components/logo.d.ts +21 -1
  103. package/dist/components/logo.js +32 -2
  104. package/dist/components/markdown-editor.d.ts +275 -0
  105. package/dist/components/markdown-editor.js +831 -0
  106. package/dist/components/mentions.d.ts +153 -0
  107. package/dist/components/mentions.js +507 -0
  108. package/dist/components/menu.d.ts +2 -1
  109. package/dist/components/menu.js +5 -4
  110. package/dist/components/menubar.d.ts +23 -5
  111. package/dist/components/menubar.js +97 -22
  112. package/dist/components/message.d.ts +62 -11
  113. package/dist/components/message.js +49 -13
  114. package/dist/components/meter.js +1 -1
  115. package/dist/components/money-input.d.ts +1 -1
  116. package/dist/components/money-input.js +1 -1
  117. package/dist/components/native-select.d.ts +2 -2
  118. package/dist/components/native-select.js +4 -4
  119. package/dist/components/navigation-menu.d.ts +3 -1
  120. package/dist/components/navigation-menu.js +23 -12
  121. package/dist/components/number-field.d.ts +2 -9
  122. package/dist/components/number-field.js +86 -36
  123. package/dist/components/number-roll.d.ts +26 -0
  124. package/dist/components/number-roll.js +81 -0
  125. package/dist/components/otp-field.d.ts +1 -1
  126. package/dist/components/otp-field.js +24 -3
  127. package/dist/components/pagination.d.ts +11 -3
  128. package/dist/components/pagination.js +59 -13
  129. package/dist/components/pdf-viewer.d.ts +1 -1
  130. package/dist/components/pdf-viewer.js +8 -8
  131. package/dist/components/phone-input.d.ts +1 -1
  132. package/dist/components/phone-input.js +2 -2
  133. package/dist/components/popover.js +5 -3
  134. package/dist/components/preview-card.d.ts +37 -2
  135. package/dist/components/preview-card.js +226 -2
  136. package/dist/components/progress.js +1 -1
  137. package/dist/components/prompt-input.d.ts +1 -1
  138. package/dist/components/prompt-input.js +24 -14
  139. package/dist/components/pull-to-refresh.d.ts +50 -0
  140. package/dist/components/pull-to-refresh.js +189 -0
  141. package/dist/components/quote.d.ts +6 -1
  142. package/dist/components/quote.js +3 -2
  143. package/dist/components/radio-group.js +1 -1
  144. package/dist/components/rating.d.ts +4 -1
  145. package/dist/components/rating.js +131 -10
  146. package/dist/components/reasoning.d.ts +1 -1
  147. package/dist/components/reasoning.js +7 -3
  148. package/dist/components/resizable.d.ts +1 -1
  149. package/dist/components/resizable.js +2 -2
  150. package/dist/components/response.d.ts +1 -1
  151. package/dist/components/response.js +18 -6
  152. package/dist/components/scheduler.d.ts +352 -0
  153. package/dist/components/scheduler.js +1717 -0
  154. package/dist/components/scroll-area.js +1 -1
  155. package/dist/components/select.d.ts +17 -4
  156. package/dist/components/select.js +140 -9
  157. package/dist/components/separator.d.ts +1 -1
  158. package/dist/components/separator.js +3 -3
  159. package/dist/components/sidebar.d.ts +44 -3
  160. package/dist/components/sidebar.js +57 -17
  161. package/dist/components/site-header.d.ts +18 -13
  162. package/dist/components/site-header.js +23 -11
  163. package/dist/components/skeleton.d.ts +17 -7
  164. package/dist/components/skeleton.js +22 -7
  165. package/dist/components/slider.js +2 -2
  166. package/dist/components/sortable.d.ts +55 -4
  167. package/dist/components/sortable.js +172 -103
  168. package/dist/components/sources.d.ts +1 -1
  169. package/dist/components/sources.js +2 -2
  170. package/dist/components/spinner.d.ts +4 -4
  171. package/dist/components/spinner.js +4 -4
  172. package/dist/components/stat.d.ts +21 -4
  173. package/dist/components/stat.js +17 -8
  174. package/dist/components/stepper.d.ts +1 -1
  175. package/dist/components/stepper.js +8 -7
  176. package/dist/components/suggestions.d.ts +11 -3
  177. package/dist/components/suggestions.js +10 -4
  178. package/dist/components/swipe-actions.d.ts +66 -0
  179. package/dist/components/swipe-actions.js +292 -0
  180. package/dist/components/switch.js +1 -1
  181. package/dist/components/table.d.ts +12 -6
  182. package/dist/components/table.js +78 -30
  183. package/dist/components/tabs.js +7 -4
  184. package/dist/components/tag.d.ts +19 -20
  185. package/dist/components/tag.js +9 -5
  186. package/dist/components/tags-input.d.ts +2 -7
  187. package/dist/components/tags-input.js +11 -8
  188. package/dist/components/textarea.d.ts +3 -2
  189. package/dist/components/textarea.js +4 -3
  190. package/dist/components/theme.d.ts +49 -6
  191. package/dist/components/theme.js +147 -9
  192. package/dist/components/time-field.d.ts +4 -9
  193. package/dist/components/time-field.js +6 -6
  194. package/dist/components/timeline.d.ts +19 -3
  195. package/dist/components/timeline.js +21 -9
  196. package/dist/components/tippy.d.ts +17 -1
  197. package/dist/components/tippy.js +95 -15
  198. package/dist/components/toast.d.ts +2 -7
  199. package/dist/components/toast.js +12 -8
  200. package/dist/components/toggle-group.d.ts +7 -1
  201. package/dist/components/toggle-group.js +16 -5
  202. package/dist/components/toggle.d.ts +2 -2
  203. package/dist/components/toggle.js +3 -2
  204. package/dist/components/tool-call.d.ts +1 -1
  205. package/dist/components/tool-call.js +4 -4
  206. package/dist/components/toolbar.d.ts +57 -4
  207. package/dist/components/toolbar.js +216 -16
  208. package/dist/components/tooltip.d.ts +1 -1
  209. package/dist/components/tooltip.js +4 -2
  210. package/dist/components/tour.d.ts +1 -1
  211. package/dist/components/tour.js +36 -15
  212. package/dist/components/tree.js +5 -5
  213. package/dist/components/typography.d.ts +31 -8
  214. package/dist/components/typography.js +21 -10
  215. package/dist/components/video-player.d.ts +7 -2
  216. package/dist/components/video-player.js +121 -220
  217. package/dist/index.d.ts +99 -92
  218. package/dist/index.js +99 -92
  219. package/dist/lib/calendar.d.ts +153 -0
  220. package/dist/lib/calendar.js +312 -0
  221. package/dist/lib/cn.d.ts +3 -1
  222. package/dist/lib/cn.js +5 -0
  223. package/dist/lib/code-highlight.d.ts +14 -0
  224. package/dist/lib/code-highlight.js +81 -18
  225. package/dist/lib/drag.d.ts +39 -0
  226. package/dist/lib/drag.js +96 -0
  227. package/dist/lib/editorial-assets.js +16 -8
  228. package/dist/lib/figure/figures/automation.js +25 -6
  229. package/dist/lib/figure/figures/bar-chart.js +6 -1
  230. package/dist/lib/figure/figures/brackets-classic.js +4 -1
  231. package/dist/lib/figure/figures/city.js +12 -2
  232. package/dist/lib/figure/figures/conveyor.js +17 -4
  233. package/dist/lib/figure/figures/database.js +5 -2
  234. package/dist/lib/figure/figures/documents.js +11 -3
  235. package/dist/lib/figure/figures/inbox.js +5 -2
  236. package/dist/lib/figure/figures/laptop.js +3 -1
  237. package/dist/lib/figure/figures/pipeline.js +45 -10
  238. package/dist/lib/figure/figures/platform.js +62 -7
  239. package/dist/lib/figure/figures/server.js +21 -5
  240. package/dist/lib/figure/figures/spreadsheet.js +29 -5
  241. package/dist/lib/figure/kernel.d.ts +4 -2
  242. package/dist/lib/figure/kernel.js +10 -5
  243. package/dist/lib/figure/parts.js +6 -2
  244. package/dist/lib/files.d.ts +31 -0
  245. package/dist/lib/files.js +60 -0
  246. package/dist/lib/gesture.d.ts +70 -0
  247. package/dist/lib/gesture.js +141 -0
  248. package/dist/lib/glide.d.ts +5 -0
  249. package/dist/lib/glide.js +9 -1
  250. package/dist/lib/icons.d.ts +1 -0
  251. package/dist/lib/icons.js +6 -0
  252. package/dist/lib/illustration-library.js +1 -6
  253. package/dist/lib/markdown-edit.d.ts +112 -0
  254. package/dist/lib/markdown-edit.js +557 -0
  255. package/dist/lib/markdown-rich-editor.d.ts +188 -0
  256. package/dist/lib/markdown-rich-editor.js +1153 -0
  257. package/dist/lib/markdown-rich.d.ts +63 -0
  258. package/dist/lib/markdown-rich.js +534 -0
  259. package/dist/lib/mentions.d.ts +100 -0
  260. package/dist/lib/mentions.js +246 -0
  261. package/dist/lib/motion.d.ts +18 -0
  262. package/dist/lib/motion.js +43 -5
  263. package/dist/lib/number-roll.d.ts +89 -0
  264. package/dist/lib/number-roll.js +391 -0
  265. package/dist/lib/platform.d.ts +6 -0
  266. package/dist/lib/platform.js +14 -0
  267. package/dist/lib/portal-container.d.ts +9 -0
  268. package/dist/lib/portal-container.js +10 -0
  269. package/dist/lib/press.d.ts +5 -0
  270. package/dist/lib/press.js +186 -0
  271. package/dist/lib/scheduler.d.ts +128 -0
  272. package/dist/lib/scheduler.js +272 -0
  273. package/dist/lib/scroll-edges.d.ts +9 -0
  274. package/dist/lib/scroll-edges.js +50 -0
  275. package/dist/lib/table-fit.d.ts +1 -1
  276. package/dist/lib/table-fit.js +65 -8
  277. package/dist/lib/theme-preset.d.ts +267 -0
  278. package/dist/lib/theme-preset.js +1046 -0
  279. package/dist/lib/theme-script.d.ts +23 -3
  280. package/dist/lib/theme-script.js +17 -5
  281. package/dist/lib/tippy/sprite.d.ts +36 -4
  282. package/dist/lib/tippy/sprite.js +188 -15
  283. package/dist/lib/tone.d.ts +4 -0
  284. package/dist/lib/tone.js +1 -0
  285. package/dist/messages/de.d.ts +3 -3
  286. package/dist/messages/de.js +274 -3
  287. package/dist/skills/zon-ui/SKILL.md +279 -0
  288. package/dist/skills/zon-ui/references/authoring.md +265 -0
  289. package/dist/skills/zon-ui/references/brand.md +416 -0
  290. package/dist/skills/zon-ui/references/components/accordion.md +199 -0
  291. package/dist/skills/zon-ui/references/components/action-sheet.md +268 -0
  292. package/dist/skills/zon-ui/references/components/alert-dialog.md +276 -0
  293. package/dist/skills/zon-ui/references/components/alert.md +167 -0
  294. package/dist/skills/zon-ui/references/components/app-bar.md +307 -0
  295. package/dist/skills/zon-ui/references/components/ascii-field.md +121 -0
  296. package/dist/skills/zon-ui/references/components/aspect-ratio.md +112 -0
  297. package/dist/skills/zon-ui/references/components/audio-player.md +231 -0
  298. package/dist/skills/zon-ui/references/components/avatar.md +98 -0
  299. package/dist/skills/zon-ui/references/components/badge.md +227 -0
  300. package/dist/skills/zon-ui/references/components/bottom-nav.md +709 -0
  301. package/dist/skills/zon-ui/references/components/breadcrumb.md +143 -0
  302. package/dist/skills/zon-ui/references/components/button-group.md +216 -0
  303. package/dist/skills/zon-ui/references/components/button.md +309 -0
  304. package/dist/skills/zon-ui/references/components/calendar.md +296 -0
  305. package/dist/skills/zon-ui/references/components/card.md +158 -0
  306. package/dist/skills/zon-ui/references/components/carousel.md +297 -0
  307. package/dist/skills/zon-ui/references/components/chart.md +739 -0
  308. package/dist/skills/zon-ui/references/components/chat.md +417 -0
  309. package/dist/skills/zon-ui/references/components/checkbox.md +219 -0
  310. package/dist/skills/zon-ui/references/components/code-block.md +143 -0
  311. package/dist/skills/zon-ui/references/components/code-highlight.md +118 -0
  312. package/dist/skills/zon-ui/references/components/collapsible.md +146 -0
  313. package/dist/skills/zon-ui/references/components/color-picker.md +200 -0
  314. package/dist/skills/zon-ui/references/components/combobox.md +455 -0
  315. package/dist/skills/zon-ui/references/components/command.md +326 -0
  316. package/dist/skills/zon-ui/references/components/contact-form.md +562 -0
  317. package/dist/skills/zon-ui/references/components/context-menu.md +159 -0
  318. package/dist/skills/zon-ui/references/components/conversation.md +146 -0
  319. package/dist/skills/zon-ui/references/components/copy-button.md +162 -0
  320. package/dist/skills/zon-ui/references/components/crm.md +1022 -0
  321. package/dist/skills/zon-ui/references/components/dashboard.md +612 -0
  322. package/dist/skills/zon-ui/references/components/data-table.md +776 -0
  323. package/dist/skills/zon-ui/references/components/date-picker.md +444 -0
  324. package/dist/skills/zon-ui/references/components/dialog.md +335 -0
  325. package/dist/skills/zon-ui/references/components/direction.md +165 -0
  326. package/dist/skills/zon-ui/references/components/drawer.md +276 -0
  327. package/dist/skills/zon-ui/references/components/drawing.md +94 -0
  328. package/dist/skills/zon-ui/references/components/empty.md +225 -0
  329. package/dist/skills/zon-ui/references/components/feature-list.md +412 -0
  330. package/dist/skills/zon-ui/references/components/field.md +209 -0
  331. package/dist/skills/zon-ui/references/components/file-drop.md +234 -0
  332. package/dist/skills/zon-ui/references/components/filter-bar.md +485 -0
  333. package/dist/skills/zon-ui/references/components/form.md +970 -0
  334. package/dist/skills/zon-ui/references/components/graph.md +339 -0
  335. package/dist/skills/zon-ui/references/components/illustration.md +497 -0
  336. package/dist/skills/zon-ui/references/components/inbox.md +263 -0
  337. package/dist/skills/zon-ui/references/components/input-group.md +339 -0
  338. package/dist/skills/zon-ui/references/components/input.md +189 -0
  339. package/dist/skills/zon-ui/references/components/item.md +277 -0
  340. package/dist/skills/zon-ui/references/components/kanban.md +626 -0
  341. package/dist/skills/zon-ui/references/components/kbd.md +116 -0
  342. package/dist/skills/zon-ui/references/components/label.md +104 -0
  343. package/dist/skills/zon-ui/references/components/layout.md +291 -0
  344. package/dist/skills/zon-ui/references/components/lightbox.md +235 -0
  345. package/dist/skills/zon-ui/references/components/locale.md +279 -0
  346. package/dist/skills/zon-ui/references/components/logo.md +257 -0
  347. package/dist/skills/zon-ui/references/components/markdown-editor.md +558 -0
  348. package/dist/skills/zon-ui/references/components/mentions.md +512 -0
  349. package/dist/skills/zon-ui/references/components/menu.md +218 -0
  350. package/dist/skills/zon-ui/references/components/menubar.md +292 -0
  351. package/dist/skills/zon-ui/references/components/message.md +243 -0
  352. package/dist/skills/zon-ui/references/components/meter.md +105 -0
  353. package/dist/skills/zon-ui/references/components/money-input.md +333 -0
  354. package/dist/skills/zon-ui/references/components/native-select.md +197 -0
  355. package/dist/skills/zon-ui/references/components/navigation-menu.md +253 -0
  356. package/dist/skills/zon-ui/references/components/number-field.md +210 -0
  357. package/dist/skills/zon-ui/references/components/number-roll.md +175 -0
  358. package/dist/skills/zon-ui/references/components/onboarding.md +896 -0
  359. package/dist/skills/zon-ui/references/components/otp-field.md +166 -0
  360. package/dist/skills/zon-ui/references/components/pagination.md +109 -0
  361. package/dist/skills/zon-ui/references/components/pdf-viewer.md +177 -0
  362. package/dist/skills/zon-ui/references/components/phone-input.md +252 -0
  363. package/dist/skills/zon-ui/references/components/popover.md +176 -0
  364. package/dist/skills/zon-ui/references/components/preview-card.md +193 -0
  365. package/dist/skills/zon-ui/references/components/pricing.md +724 -0
  366. package/dist/skills/zon-ui/references/components/progress.md +92 -0
  367. package/dist/skills/zon-ui/references/components/prompt-input.md +307 -0
  368. package/dist/skills/zon-ui/references/components/pull-to-refresh.md +188 -0
  369. package/dist/skills/zon-ui/references/components/quote.md +115 -0
  370. package/dist/skills/zon-ui/references/components/radio-group.md +215 -0
  371. package/dist/skills/zon-ui/references/components/rating.md +260 -0
  372. package/dist/skills/zon-ui/references/components/reasoning.md +102 -0
  373. package/dist/skills/zon-ui/references/components/resizable.md +213 -0
  374. package/dist/skills/zon-ui/references/components/response.md +170 -0
  375. package/dist/skills/zon-ui/references/components/scheduler.md +732 -0
  376. package/dist/skills/zon-ui/references/components/scroll-area.md +122 -0
  377. package/dist/skills/zon-ui/references/components/select.md +351 -0
  378. package/dist/skills/zon-ui/references/components/separator.md +103 -0
  379. package/dist/skills/zon-ui/references/components/settings.md +793 -0
  380. package/dist/skills/zon-ui/references/components/shop.md +1715 -0
  381. package/dist/skills/zon-ui/references/components/sidebar.md +813 -0
  382. package/dist/skills/zon-ui/references/components/sign-in.md +1639 -0
  383. package/dist/skills/zon-ui/references/components/site-header.md +303 -0
  384. package/dist/skills/zon-ui/references/components/skeleton.md +256 -0
  385. package/dist/skills/zon-ui/references/components/slider.md +172 -0
  386. package/dist/skills/zon-ui/references/components/sortable.md +405 -0
  387. package/dist/skills/zon-ui/references/components/sources.md +106 -0
  388. package/dist/skills/zon-ui/references/components/spinner.md +222 -0
  389. package/dist/skills/zon-ui/references/components/stat.md +267 -0
  390. package/dist/skills/zon-ui/references/components/stepper.md +285 -0
  391. package/dist/skills/zon-ui/references/components/suggestions.md +146 -0
  392. package/dist/skills/zon-ui/references/components/swipe-actions.md +344 -0
  393. package/dist/skills/zon-ui/references/components/switch.md +160 -0
  394. package/dist/skills/zon-ui/references/components/table.md +999 -0
  395. package/dist/skills/zon-ui/references/components/tabs.md +258 -0
  396. package/dist/skills/zon-ui/references/components/tag.md +115 -0
  397. package/dist/skills/zon-ui/references/components/tags-input.md +216 -0
  398. package/dist/skills/zon-ui/references/components/textarea.md +95 -0
  399. package/dist/skills/zon-ui/references/components/theme-editor.md +3940 -0
  400. package/dist/skills/zon-ui/references/components/theme.md +362 -0
  401. package/dist/skills/zon-ui/references/components/time-field.md +222 -0
  402. package/dist/skills/zon-ui/references/components/timeline.md +285 -0
  403. package/dist/skills/zon-ui/references/components/tippy.md +243 -0
  404. package/dist/skills/zon-ui/references/components/toast.md +220 -0
  405. package/dist/skills/zon-ui/references/components/toggle-group.md +261 -0
  406. package/dist/skills/zon-ui/references/components/toggle.md +167 -0
  407. package/dist/skills/zon-ui/references/components/tool-call.md +146 -0
  408. package/dist/skills/zon-ui/references/components/toolbar.md +260 -0
  409. package/dist/skills/zon-ui/references/components/tooltip.md +172 -0
  410. package/dist/skills/zon-ui/references/components/tour.md +423 -0
  411. package/dist/skills/zon-ui/references/components/tree.md +481 -0
  412. package/dist/skills/zon-ui/references/components/typography.md +347 -0
  413. package/dist/skills/zon-ui/references/components/video-player.md +386 -0
  414. package/dist/skills/zon-ui/references/marketing.md +467 -0
  415. package/dist/skills/zon-ui/references/motion.md +455 -0
  416. package/dist/skills/zon-ui/references/recipes.md +1232 -0
  417. package/dist/skills/zon-ui/references/tokens.md +866 -0
  418. package/dist/sources/accordion.css +4 -0
  419. package/dist/sources/action-sheet.css +11 -0
  420. package/dist/sources/alert-dialog.css +6 -0
  421. package/dist/sources/alert.css +3 -0
  422. package/dist/sources/app-bar.css +14 -0
  423. package/dist/sources/ascii-field.css +3 -0
  424. package/dist/sources/aspect-ratio.css +3 -0
  425. package/dist/sources/audio-player.css +20 -0
  426. package/dist/sources/avatar.css +3 -0
  427. package/dist/sources/badge.css +3 -0
  428. package/dist/sources/bottom-nav.css +9 -0
  429. package/dist/sources/breadcrumb.css +14 -0
  430. package/dist/sources/button-group.css +3 -0
  431. package/dist/sources/button.css +9 -0
  432. package/dist/sources/calendar.css +13 -0
  433. package/dist/sources/card.css +3 -0
  434. package/dist/sources/carousel.css +11 -0
  435. package/dist/sources/chart.css +5 -0
  436. package/dist/sources/checkbox.css +6 -0
  437. package/dist/sources/code-block.css +13 -0
  438. package/dist/sources/collapsible.css +4 -0
  439. package/dist/sources/color-picker.css +13 -0
  440. package/dist/sources/combobox.css +13 -0
  441. package/dist/sources/command.css +13 -0
  442. package/dist/sources/context-menu.css +12 -0
  443. package/dist/sources/conversation.css +10 -0
  444. package/dist/sources/copy-button.css +10 -0
  445. package/dist/sources/data-table.css +27 -0
  446. package/dist/sources/date-picker.css +20 -0
  447. package/dist/sources/dialog.css +9 -0
  448. package/dist/sources/direction.css +2 -0
  449. package/dist/sources/drawer.css +9 -0
  450. package/dist/sources/drawing.css +5 -0
  451. package/dist/sources/empty.css +3 -0
  452. package/dist/sources/feature-list.css +4 -0
  453. package/dist/sources/field.css +4 -0
  454. package/dist/sources/file-drop.css +15 -0
  455. package/dist/sources/filter-bar.css +30 -0
  456. package/dist/sources/form.css +4 -0
  457. package/dist/sources/graph.css +19 -0
  458. package/dist/sources/illustration.css +28 -0
  459. package/dist/sources/input-group.css +7 -0
  460. package/dist/sources/input.css +3 -0
  461. package/dist/sources/item.css +4 -0
  462. package/dist/sources/kbd.css +5 -0
  463. package/dist/sources/label.css +3 -0
  464. package/dist/sources/layout.css +3 -0
  465. package/dist/sources/lightbox.css +33 -0
  466. package/dist/sources/locale.css +2 -0
  467. package/dist/sources/logo.css +4 -0
  468. package/dist/sources/markdown-editor.css +41 -0
  469. package/dist/sources/mentions.css +13 -0
  470. package/dist/sources/menu.css +11 -0
  471. package/dist/sources/menubar.css +14 -0
  472. package/dist/sources/message.css +16 -0
  473. package/dist/sources/meter.css +4 -0
  474. package/dist/sources/money-input.css +10 -0
  475. package/dist/sources/native-select.css +4 -0
  476. package/dist/sources/navigation-menu.css +8 -0
  477. package/dist/sources/number-field.css +8 -0
  478. package/dist/sources/number-roll.css +6 -0
  479. package/dist/sources/otp-field.css +5 -0
  480. package/dist/sources/pagination.css +11 -0
  481. package/dist/sources/pdf-viewer.css +30 -0
  482. package/dist/sources/phone-input.css +20 -0
  483. package/dist/sources/popover.css +7 -0
  484. package/dist/sources/preview-card.css +7 -0
  485. package/dist/sources/progress.css +4 -0
  486. package/dist/sources/prompt-input.css +15 -0
  487. package/dist/sources/pull-to-refresh.css +14 -0
  488. package/dist/sources/quote.css +3 -0
  489. package/dist/sources/radio-group.css +5 -0
  490. package/dist/sources/rating.css +6 -0
  491. package/dist/sources/reasoning.css +6 -0
  492. package/dist/sources/resizable.css +4 -0
  493. package/dist/sources/response.css +16 -0
  494. package/dist/sources/scheduler.css +44 -0
  495. package/dist/sources/scroll-area.css +3 -0
  496. package/dist/sources/select.css +12 -0
  497. package/dist/sources/separator.css +3 -0
  498. package/dist/sources/sidebar.css +19 -0
  499. package/dist/sources/site-header.css +15 -0
  500. package/dist/sources/skeleton.css +3 -0
  501. package/dist/sources/slider.css +6 -0
  502. package/dist/sources/sortable.css +12 -0
  503. package/dist/sources/sources.css +6 -0
  504. package/dist/sources/spinner.css +6 -0
  505. package/dist/sources/stat.css +9 -0
  506. package/dist/sources/stepper.css +6 -0
  507. package/dist/sources/suggestions.css +10 -0
  508. package/dist/sources/swipe-actions.css +20 -0
  509. package/dist/sources/switch.css +5 -0
  510. package/dist/sources/table.css +7 -0
  511. package/dist/sources/tabs.css +5 -0
  512. package/dist/sources/tag.css +3 -0
  513. package/dist/sources/tags-input.css +6 -0
  514. package/dist/sources/textarea.css +3 -0
  515. package/dist/sources/theme.css +13 -0
  516. package/dist/sources/time-field.css +7 -0
  517. package/dist/sources/timeline.css +7 -0
  518. package/dist/sources/tippy.css +6 -0
  519. package/dist/sources/toast.css +6 -0
  520. package/dist/sources/toggle-group.css +5 -0
  521. package/dist/sources/toggle.css +3 -0
  522. package/dist/sources/tool-call.css +16 -0
  523. package/dist/sources/toolbar.css +14 -0
  524. package/dist/sources/tooltip.css +6 -0
  525. package/dist/sources/tour.css +14 -0
  526. package/dist/sources/tree.css +6 -0
  527. package/dist/sources/typography.css +4 -0
  528. package/dist/sources/video-player.css +21 -0
  529. package/dist/styles/ai.css +3 -0
  530. package/dist/styles/brand.css +98 -0
  531. package/dist/styles/core.css +266 -0
  532. package/dist/styles/editor.css +3 -0
  533. package/dist/styles/expressive.css +35 -56
  534. package/dist/styles/fonts.css +61 -117
  535. package/dist/styles/graph.css +4 -0
  536. package/dist/styles/illustration.css +4 -0
  537. package/dist/styles/index.css +11 -201
  538. package/dist/styles/material.css +138 -12
  539. package/dist/styles/parts/ai.css +18 -13
  540. package/dist/styles/parts/brand.css +2 -2
  541. package/dist/styles/parts/controls.css +29 -20
  542. package/dist/styles/parts/data.css +13 -9
  543. package/dist/styles/parts/editor.css +372 -0
  544. package/dist/styles/parts/feedback.css +32 -2
  545. package/dist/styles/parts/foundations.css +12 -7
  546. package/dist/styles/parts/graph.css +25 -9
  547. package/dist/styles/parts/inputs.css +172 -9
  548. package/dist/styles/parts/isometric.css +6 -5
  549. package/dist/styles/parts/navigation.css +206 -27
  550. package/dist/styles/parts/overlays.css +19 -4
  551. package/dist/styles/parts/pdf.css +2 -2
  552. package/dist/styles/pdf.css +3 -0
  553. package/dist/styles/prose.css +3 -0
  554. package/dist/styles/tokens.css +89 -14
  555. package/dist/theme.d.ts +1 -0
  556. package/dist/theme.js +5 -0
  557. package/dist/vite.d.ts +48 -59
  558. package/dist/vite.js +54 -21
  559. package/package.json +69 -2
@@ -0,0 +1,455 @@
1
+ # Motion
2
+
3
+ How zon/ui moves, and how to decide whether something should move at all. It is the motion part of
4
+ the brief (`docs/brand.md`, section 06) worked out in detail, and it describes the library as it
5
+ is: every value below is one the code uses. Agents follow it when they build or review a component
6
+ (`docs/authoring.md`, rule 7).
7
+
8
+ Much of it is learned from Emil Kowalski's skills for designers and engineers
9
+ ([emilkowalski/skills](https://github.com/emilkowalski/skills), MIT). The skills we use are copied
10
+ into `.claude/skills/` (see `.claude/skills/EMIL-KOWALSKI.md`). They go further than this page.
11
+ Where they and this page differ, this page decides for zon/ui, and the reasons are given at the end.
12
+
13
+ ## Should it move?
14
+
15
+ Motion has to answer "why does this move?". Valid answers:
16
+
17
+ - **Where it came from.** A popover grows from its trigger. A step enters from the side it is
18
+ coming from.
19
+ - **What changed.** The current tab's tile travels to the new tab. A copy icon turns into a check.
20
+ - **That we heard you.** A button sinks when pressed.
21
+ - **So nothing jumps.** Content that would appear in one frame and shift the page fades in instead.
22
+
23
+ "It looks good" is not an answer for something people see all day. How often a thing is seen
24
+ decides how much it may move:
25
+
26
+ | Seen | Motion |
27
+ | -------------------------------------------------------------------------------- | -------------------------------------- |
28
+ | A hundred times a day, or from the keyboard (⌘K, arrow keys, shortcuts) | None, but for the two signatures below |
29
+ | Tens of times a day (hovers, list navigation, a highlight following the pointer) | Little and fast |
30
+ | Now and then (dialogs, drawers, toasts, menus) | The standard motion below |
31
+ | Rarely (a first run, a hero, a confirmation) | Room for a little more |
32
+
33
+ **Nothing the keyboard does animates**, with two exceptions. The command palette opens at once. The
34
+ sidebar's ⌘B folds at once, and the trigger click still glides. A Tree folds at once from the arrow
35
+ keys. A focused expandable button unfolds at once. Parts mark these moments with `data-instant`,
36
+ which turns their transitions off.
37
+
38
+ The exceptions are two signatures that show what a key just changed: digits roll when an arrow key
39
+ steps a NumberField or a TimeField, and an OtpField's ring glides to the slot the next character
40
+ goes in. Neither restarts on a held key. A NumberField step that comes while its digits still roll
41
+ carries on from where each digit is to the new value, so a held key or stepper keeps rolling and
42
+ lands exactly on the last value; a TimeField segment's steps closer together than the roll change
43
+ in place.
44
+
45
+ ## Curves and durations
46
+
47
+ All motion uses the tokens in `packages/ui/src/styles/tokens.css`. Never hand-type a curve or a
48
+ millisecond value.
49
+
50
+ | Token | Value | For |
51
+ | ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | `--ease` | `cubic-bezier(0.16, 1, 0.3, 1)` | Things entering and leaving, and colour. A strong ease-out: the movement starts at once, where the eye already is. Tailwind: `ease-(--ease)` (`ease-brand` is an older name for it, kept for code that uses it). |
53
+ | `--ease-glide` | `cubic-bezier(0.33, 1, 0.68, 1)` | Things that travel under the eye and land softly: the gliding indicators (tabs, segments, the sidebar's current row, the bottom nav tile), a height that opens, a value that follows the pointer, a pressed material rising back. A milder ease-out, so a long glide doesn't jump and then crawl. |
54
+ | `--ease-move` | `cubic-bezier(0.77, 0, 0.175, 1)` | Moves the interface makes on its own from one place to another (a graph tidying itself), and loops (a skeleton's sweep, an indeterminate bar, a spinner's reduced-motion pulse, the glow orb's breathing, the stars' twinkle). |
55
+ | `--ease-pop` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | An overshoot, for a small mark that lands with a little give: a stepper's finished check, BottomNav's icon springing back. Only on a mark a few pixels across. |
56
+ | `--ease-in` | `cubic-bezier(0.32, 0, 0.67, 0)` | Something going away that nobody is watching: BottomNav sliding off as the page scrolls, a Tour bubble going back into its tail. Never on something someone did. |
57
+ | `--duration` | 150ms | Controls, popups, movement. |
58
+ | `--duration-glide` | 240ms (1.6 × `--duration`) | Every gliding indicator, at the same speed, and opening heights. |
59
+ | `--duration-exit` | 105ms (0.7 × `--duration`) | Leaving. Leaving is quicker than arriving: the person has already moved on. |
60
+ | `--duration-fade` | 150ms | Opacity and colour only. Unlike the others, it is kept under reduced motion. |
61
+ | `--duration-reveal` | 420ms | Reveals that answer nothing, such as a spec sheet's light coming on, and a page's one entrance (`ep-reveal`, below). |
62
+ | `--duration-settle` | 700ms | Decoration's long settle: which part of an illustration is lit, the blueprint grid's light under the pointer. Never for anything that answers an action. |
63
+
64
+ Longer motion is built from `--duration` by a factor, so it still turns to 0 under reduced motion.
65
+ The factors in use:
66
+
67
+ | Factor | Time | Where |
68
+ | ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ |
69
+ | 0.6 × `--duration-fade` | 90ms | A material going down when pressed (Toolbar buttons too); a phone part shrinking under the finger |
70
+ | 0.6 × | 90ms | BottomNav's icon pressing in |
71
+ | 1.2 × | 180ms | A chart's cursor, active dot and tooltip following the pointer |
72
+ | 4/3 × | 200ms | A Sortable copy landing; the PromptInput growing into its stacked bar |
73
+ | 1.5 × | 225ms | An expandable button unfolding its label |
74
+ | 1.6 × | 240ms | A checkbox drawing its tick; a stepper's connector filling |
75
+ | 1.7 × `--duration-fade` | 255ms | A material rising back after a press |
76
+ | 2 × | 300ms | Large travel: drawers, toasts, a graph tidying, BottomNav sliding away; BottomNav's icon springing back; VideoPlayer's play or pause flash |
77
+ | 3.5 × `--duration-fade` | 525ms | A streamed word coming into focus (a reading pace, kept under reduced motion) |
78
+
79
+ 300ms is the ceiling for anything that answers an action.
80
+
81
+ Never ease-in on something someone did: it starts slow at the moment they are watching. The
82
+ exception is something going away that nobody is looking at, on `--ease-in`: a bar that slides away
83
+ as the page scrolls (BottomNav's `hideOnScroll`), a Tour bubble going back into its tail. It should
84
+ start gently and go.
85
+
86
+ Reading time is not motion. A readout that stays to be read (VideoPlayer's "+20s" after a jump,
87
+ held for a second) answers the press within the budget, and only then waits.
88
+
89
+ Faster feels faster: a 180ms menu feels quicker than a 400ms one, even though both open as soon as
90
+ they are asked.
91
+
92
+ ## What moves, and how
93
+
94
+ ### State changes: hover, press, focus
95
+
96
+ A state change is a change of material, not of place.
97
+
98
+ - **Hover** changes the fill and the ink, on `--duration-fade` with `--ease`. Rows, menu items and
99
+ nav items "lift" into the raised material: a fill, never a movement. Every hover is behind
100
+ `@media (hover: hover)`, so a tap never leaves one behind.
101
+ - **Press** sinks the material. Pressed, the fill dips and the inset shadow deepens in 90ms (0.6 ×
102
+ `--duration-fade`). Released, it rises back over 255ms (1.7 ×) on `--ease-glide`, so even a quick
103
+ click is seen to press and settle. Buttons, rows, toolbar buttons, segments and tabs answer a
104
+ press this way. Tabs and segments don't show it: their tile is already on its way, and a press
105
+ under it reads as lag.
106
+ - **On a phone, the press lands with the finger.** The browser shows `:active` on a touch only once
107
+ it is sure the touch is not a scroll, and iOS Safari not at all without a touch listener. The
108
+ phone parts (AppBar, ActionSheet, SwipeActions, BottomNav, PullToRefresh) mark what they press
109
+ with `data-press`; `lib/press.ts` sets `data-pressing` on it at pointer-down and takes it away on
110
+ release, or at once, with no ease, when the finger moves 8px or anything scrolls, so a list being
111
+ scrolled never lights its rows. A tap holds the press for its 90ms, so even a quick one is seen.
112
+ The materials sink on `data-pressing` as on `:active`; a flat row or tile that has no material
113
+ takes `press-shade`, a 10% shade of its own ink over it (a red tile deepens its red). A button
114
+ inside a pressable row presses itself, not the row.
115
+ - **On a phone, what the finger presses also gives.** Everything marked `data-press` (AppBar
116
+ actions, ActionSheet choices and Cancel, SwipeActions rows and tiles, BottomNav items,
117
+ PullToRefresh's button, and so the Inbox block's rows) shrinks a little as it is pressed: to 97%
118
+ for a small target, 98.5% for a row or a card 200px and wider, in 90ms (0.6 ×
119
+ `--duration-fade`), and springs back over `--duration` on `--ease` when it is let go, from
120
+ wherever it had got to. It is written once, in `lib/press.ts`, on a scripted animation of
121
+ `scale`: transform only, so nothing around it moves, and no component has CSS of its own for it.
122
+ A choice in a card of choices (`data-press-group`) shrinks its whole card, so its shade still
123
+ meets the card's edge. A part with a press scale of its own sets `--press-scale: 1`
124
+ (BottomNavAction gives like a key, to 92%). Under reduced motion nothing shrinks; the shade
125
+ stays.
126
+ - **Focus** never animates. The 2px `--control-focus` outline is there at once, and a text field's
127
+ softer edge changes colour on `--duration-fade`.
128
+ - **A control's geometry stays fixed.** Controls don't scale on press, hover or focus. The
129
+ exceptions are the phone parts, above, which a finger presses, and BottomNav's icon, below.
130
+ - **A theme change is instant.** Transitions are switched off for the moment the theme flips, so
131
+ the page never shows two themes at once.
132
+ - **Small turns** are on `--duration` with `--ease`: a chevron turning as its panel opens, an
133
+ accordion's plus turning into ×, a checkbox's tick drawing in 240ms and undrawing in about 110ms.
134
+ - **Face swaps** cross-fade in one grid cell, so the control never changes size: CopyButton's copy
135
+ icon and check, ToolCall's status, PromptInput's arrow, spinner and stop. The old face fades out
136
+ and the new one grows from 85%, with a 2px blur on CopyButton to hide the moment both are half
137
+ there.
138
+ - **Figures roll.** NumberRoll (and a Stat with `roll`) rolls the digits of a figure that changed
139
+ in front of someone, like a cart total: up as it grows, down as it falls, on `--duration-glide`
140
+ with `--ease`, the least significant digit first and the next 20ms after, three steps at most.
141
+ A place that comes or goes opens or closes; separators and currency signs only fade. A change
142
+ that comes mid-roll rolls on from where each digit is, never snapping or starting over, so fast
143
+ clicks keep rolling and land on the last value. NumberField draws its steps with the same
144
+ engine.
145
+
146
+ ### Popups: menus, popovers, selects, tooltips, dialogs
147
+
148
+ Popups use the `popup-motion` utility, and nothing else.
149
+
150
+ - **They grow from their trigger.** From Base UI's `--transform-origin`, from 97% and transparent,
151
+ never from nothing. Dialogs have no trigger, so they grow from the centre.
152
+ - **They arrive in `--duration` and leave in `--duration-exit`.** Opacity on `--duration-fade` in,
153
+ 0.7 of it out. Every popup is quicker going than coming.
154
+ - **The backdrop only dims.** `bg-black/40` (60% in dark) fades in and out. No blur: the page stays
155
+ legible, it just recedes.
156
+ - **Tooltips wait 150ms**, so passing over a control on the way somewhere doesn't flash one. A
157
+ `TooltipProvider` shares the delay, so moving along a row of tooltips shows the next at once.
158
+ - **One surface for a menu bar and a navigation menu.** Moving from one trigger's menu to the next,
159
+ the open surface travels and resizes instead of closing and opening, as a gliding indicator does:
160
+ `--duration-glide` on `--ease-glide`, for Menubar's surface and NavigationMenu's panel alike. The
161
+ new contents fade in under it.
162
+ - **Keyboard opens are instant.** The command palette, opened with ⌘K, appears without motion; its
163
+ backdrop too.
164
+
165
+ ### Drawers and toasts
166
+
167
+ Drawers and toasts travel further than a popup, so they take twice as long: 300ms on `--ease`. A
168
+ drawer closed by a button or Escape, and a toast leaving, take 0.7 of that, 210ms.
169
+
170
+ - **A drawer slides from its edge.** A bottom sheet rises from below; a side panel comes in from its
171
+ side. Its backdrop fades with it, and lightens as the sheet is pulled down.
172
+ - **Gestures follow the finger exactly.** While a drawer or a toast is swiped, its transition is
173
+ off and it tracks the pointer 1:1. Let go, it finishes at the pace of the release, not the
174
+ default duration. A flick is enough to dismiss (about 0.11px per millisecond), whatever the
175
+ distance. Past an edge, the drag slows rather than stops.
176
+ - **Toasts rise from below the stack**, 150% of their height, and leave the way they are swiped.
177
+ Behind the front toast, each one is 5% smaller and peeks 10px out; their contents fade out until
178
+ the stack expands on hover.
179
+
180
+ ### Gliding indicators
181
+
182
+ One indicator travels between items to show what changed: the current tab (Tabs), the current
183
+ segment (ToggleGroup), the current page (Pagination), the sidebar's current row, the bottom nav
184
+ tile, the menu bar's hover, the OTP ring, a menu's radio dot, and, at the same speed, the shared
185
+ surface of a menu bar or navigation menu, a stepper's connector filling, and a Tour's popover and
186
+ spotlight moving to the next target.
187
+
188
+ - **One speed for all of them**: `--duration-glide` on `--ease-glide`. They move translate, width
189
+ and height, never `left` or `top`.
190
+ - **They are built on `useGlide`** (`packages/ui/src/lib/glide.ts`) and its `glideMotion` classes,
191
+ with no duration of their own on top.
192
+ The hook measures the target, and marks the indicator `data-instant` before its first placement
193
+ and when it comes back after having no target, so it never flies in from a stale place.
194
+ - **Only the indicator moves.** The items under it change ink on `--duration-fade`.
195
+
196
+ ### Layout changes: heights, folds and columns
197
+
198
+ Animate a size only when nothing else can say it: a panel that opens and pushes the content down.
199
+
200
+ - **Collapsible, Accordion and the Reasoning panel** open and close their height over
201
+ `--duration-glide` on `--ease-glide`, from Base UI's measured panel height. A tall panel
202
+ collapsing in 150ms reads as a jump.
203
+ - **Sidebar** folds its width over `--duration`. Its inset page moves its margin with it.
204
+ - **Table groups** show their rows at once when opened, then fade them in, each dropping 4px, the
205
+ first three 15ms apart. Closing is instant: the rows go as they were asked to.
206
+ - **A fitting Table** rearranges its columns as one beat of `--duration-glide`: a leaving cell
207
+ fades and drifts 8px to its side while its neighbours close the gap; an entering one grows from
208
+ 90% a moment later; rows follow each other 30ms apart, three at most, so the table settles
209
+ within 300ms.
210
+ - **A Graph tidying itself** moves every node and the camera together, twice `--duration` on
211
+ `--ease-move`.
212
+
213
+ ### Drag
214
+
215
+ Dragging is the person's own motion. The interface keeps up and stays out of the way.
216
+
217
+ - **The copy is lifted, not moved.** Sortable's copy under the pointer grows to 102% and takes its
218
+ shadow as it is picked up, on `--duration`. It is placed by the pointer every frame, with no
219
+ transition.
220
+ - **The others slide aside** with their own translate on `--duration`, opening a gap where the
221
+ item will land.
222
+ - **Drop lands it.** Released, the copy glides into its place over 4/3 × `--duration` (200ms) and
223
+ sets down to its size. Put back, everything glides home.
224
+ - **A drop zone takes the copy in.** Over a zone, the copy glides to the zone's middle and shrinks
225
+ to fit 8px inside its edges; out again, it glides back under the pointer.
226
+ - **Autoscroll** near an edge runs at the same speed per millisecond at 60Hz and 120Hz.
227
+
228
+ ### Springs
229
+
230
+ Springs are for things a finger holds, where the motion must carry on from the hand's speed. They
231
+ are written frame by frame in script, never as a CSS curve.
232
+
233
+ - **BottomNav's liquid mark.** Pressed, the mark swells past the capsule and lifts. Dragged, it
234
+ trails the finger on a slightly under-damped spring (stiffness 420, damping 30), stretching along
235
+ its path by its speed and squashing across it so it keeps its volume, rubber-banding past the
236
+ ends. Let go, one spring a touch under critical damping (stiffness 320, damping 34) takes over
237
+ from where it is and how fast it moves: it carries on to the item the finger was heading for,
238
+ shrinks back and sets its lift down together, and ends on the pixel where it then rests. The
239
+ shadow of its lift is drawn from its size each frame, never on a transition of its own.
240
+ - **Slider's `squash`.** A held thumb pinches wider and flatter, stretches as it moves, and springs
241
+ round again with a small wobble when let go. Only for pointer drags; keyboard steps leave it
242
+ alone.
243
+ - **Illustrations** follow the pointer on a spring, and change which part is chosen on a separate,
244
+ long 700ms ease (below).
245
+
246
+ An overshoot curve, `--ease-pop`, is used for a few small, celebratory marks: a stepper's finished
247
+ check popping in, BottomNav's icon springing back after a tap (300ms, 2 × `--duration`). Keep it to
248
+ a mark a few pixels across.
249
+
250
+ ### Streaming text
251
+
252
+ A reply streamed from a model arrives in bursts. Response shows it at an even pace instead.
253
+
254
+ - **Paced, a word at a time.** Every frame reveals text at the pace it has been arriving at (an
255
+ average of the last bursts), plus a share of what is waiting, and never slower than 32 characters
256
+ a second. When the stream ends, what is left is revealed quickly.
257
+ - **Each word comes into focus**, from transparent and at most 2px blurred to sharp, over 3.5 ×
258
+ `--duration-fade` (525ms).
259
+ The words don't rise: they are inline, and moving them would lay the line out every frame.
260
+ - **The log follows.** Conversation eases its view to the end each frame while the reply grows,
261
+ stops when the reader scrolls up, and offers a round button to come back.
262
+ - **Thinking says so in words.** Reasoning's "Thinking…" label carries a soft 1.6s shimmer while it
263
+ runs, and its panel closes itself when the thinking is done, on the glide.
264
+
265
+ ### Loading
266
+
267
+ Something busy keeps moving for as long as it is busy. These are the only motions that loop in a
268
+ product interface, and they use keyframes.
269
+
270
+ - **Spinner** has eleven faces, all CSS, each 0.5 to 2.4 seconds a cycle. Turning faces (the ring,
271
+ the orbit, the crescent) turn linearly; the others pulse, step or draw.
272
+ - **Skeleton** sweeps a soft highlight across its block every 1.6s on `--ease-move`.
273
+ - **Progress**, indeterminate, sweeps its bar every 1.4s on `--ease-move`.
274
+ - **A Graph's flowing edges** run their dashes linearly while the flow is on.
275
+
276
+ ### Arrival and reveal
277
+
278
+ A page may arrive with a little ceremony, once, where nobody is waiting on it.
279
+
280
+ - **The docs home page** brings its hero in, in reading order: each piece fades in and rises 12px
281
+ over 600ms, and comes into focus out of a deep blur over 1.6s. The headline starts, the lead
282
+ follows at 400ms and the buttons at 800ms. The page below only fades in, from 1.4s, because
283
+ moving or blurring that much at once would stutter. It waits for the fonts and the first paint,
284
+ and never more than 1.2s.
285
+ - **A spec sheet's light** comes on over `--duration-reveal`.
286
+ - **A marketing page's entrance** uses the `ep-reveal` keyframes (`expressive.css`): a piece rises
287
+ `--reveal-distance` (16px by default) as it fades in, over `--duration-reveal` on `--ease`, with
288
+ delays written as fractions of `--duration-reveal` (`docs/marketing.md`). `ep-draw` draws a
289
+ stroke in from `--len`, its dash length, the same way. Both are 0 under reduced motion, so the
290
+ page is simply there.
291
+ - **One-off sequences may use keyframes.** A transition can't say "pop in past its size, then
292
+ settle", so a stepper's marker (its check popping in, an error's shake, the next step settling
293
+ as the line reaches it) runs keyframes once on `--ease-pop` or `--ease`, timed on `--duration`.
294
+ Keep them within 300ms and to small marks.
295
+ - **A sticky SiteHeader** takes the page ground and a hairline as the page scrolls past, tied to
296
+ the scroll position itself, not to a timer. Its mobile panel's links come in 30ms apart, four
297
+ steps at most, rising 8px, so all of them are in within 300ms. Each link is usable at once.
298
+ - **Stagger never blocks a click.** A list may stagger in by 30ms an item, for four items at most.
299
+
300
+ ### Decorative motion
301
+
302
+ Decoration moves slowly, answers the pointer at most, and stops when it is not seen.
303
+
304
+ - **Grain.** The page's grain is still. The `grain` utility and `Grain` flicker in five steps every
305
+ 0.8s, on a desktop only.
306
+ - **AsciiField** re-rolls its characters slowly at about 30 frames a second and brightens near the
307
+ pointer. It pauses off screen.
308
+ - **Illustrations** answer the pointer: a spring follows where it is, and `--duration-settle`
309
+ (700ms) on `--ease` settles which part is chosen, spreading from the pointer 30 to 60ms a part.
310
+ A lit part fills fast (0.8 × `--duration-fade`, 120ms) and fades back over `--duration-settle`.
311
+ Only ambient figures move without input, and only on screen.
312
+ - **The blueprint grid** lights a patch under a fine pointer, fading over `--duration-settle`.
313
+ - **The glow orb** breathes, 3.5% larger and back over 16 seconds. **Stars** twinkle in opacity
314
+ over about six. Both loop on `--ease-move`.
315
+
316
+ ## Distances and sizes
317
+
318
+ Motion that answers someone travels a little. These are the distances the library uses; stay
319
+ within them.
320
+
321
+ | What | How far |
322
+ | ---------------------------------------- | ------------------------------- |
323
+ | A popup arriving or leaving | From and to 97% |
324
+ | A face swapping in a control | From 85% |
325
+ | A Sortable copy picked up | To 102% |
326
+ | A pie slice marked | 4px out and 103% |
327
+ | A row, a step's content, a link arriving | 4 to 8px |
328
+ | A fitting table's cell leaving | Drifts 8px; enters from 90% |
329
+ | A hero piece arriving | 12px |
330
+ | A drawer, a toast | Their own size, from off screen |
331
+
332
+ Nothing that someone uses all day grows past its size. A control's height and radius never change
333
+ in motion.
334
+
335
+ ## Reduced motion
336
+
337
+ Reduced motion means less movement, not no change. Under `prefers-reduced-motion: reduce`,
338
+ `--duration`, `--duration-glide`, `--duration-exit`, `--duration-reveal` and `--duration-settle`
339
+ are 0, and `--duration-fade` stays. So, by kind:
340
+
341
+ | Kind | Under reduced motion |
342
+ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
343
+ | Hover, press, focus | Fills and inks still fade (`--duration-fade`); turns and draws happen at once |
344
+ | Popups | Fade in place, no scale |
345
+ | Drawers, toasts | Fade where they rest, leaving in 0.7 of the fade; no travel |
346
+ | Gliding indicators | Jump to the new item; the ink still fades |
347
+ | Heights, folds, columns | At once; Table groups' rows only fade in |
348
+ | Drag | The copy is simply lifted; the others move aside at once; a drop lands at once |
349
+ | Springs | None: BottomNav's lens moves without springs or swelling; Slider's squash is off; a tapped icon only changes ink |
350
+ | Streaming text | Still paced, so it doesn't jerk; words fade in without the blur; the log jumps to the end instead of easing |
351
+ | Loading | Spinners (a loading toast's ring too), skeletons and indeterminate bars pulse their opacity gently instead of travelling |
352
+ | Text | Never pulses: for part of each beat it would fall below a readable contrast. Reasoning's shimmer stops, and "Thinking…" says it in words |
353
+ | Arrival, reveal | None: the page is there from its first paint (the docs home hero too) |
354
+ | Decoration | Still: grain, AsciiField, the orb, the stars, the blueprint's light, the figures' motion (they still answer, landing at once) |
355
+ | Scrolling | Carousels, the conversation, a Tour, a jump to a section and a table of contents keeping its entry in view jump instead of gliding. Nothing sets `scroll-behavior: smooth` on the page |
356
+
357
+ Script that animates reads the token, not the media query alone, from
358
+ `packages/ui/src/lib/motion.ts`: `cssDuration()` returns `--duration` in milliseconds as the
359
+ element sees it, 0 under reduced motion; `cssTime(name)` reads any time token the same way
360
+ (`--duration-glide`, `--duration-fade` …, calc() included); `cssEase(name)` returns a curve for an
361
+ animation's `easing`. Where a movement's time is 0, skip it, and fade on `--duration-fade` instead
362
+ if something would otherwise pop in or out.
363
+
364
+ One value can't be read: Recharts takes its timing as plain props, so `chartAnimation` (`@zonsh/ui/chart`)
365
+ writes 300ms and the `--ease` curve out, mirroring 2 × `--duration`. Recharts turns it off under
366
+ reduced motion itself. A figure (`lib/figure/kernel.ts`) has no DOM to read from either; it copies
367
+ `--duration-settle` and `--ease`.
368
+
369
+ ## Phones and touch
370
+
371
+ A phone is held close, often on battery, and has no hover. What stays still there:
372
+
373
+ - **Hover.** Every hover effect is behind `@media (hover: hover)`. Anything that moves on hover (an
374
+ expandable button's label) also needs a fine pointer.
375
+ - **Backdrops and decoration.** Grain, AsciiField, the glow orb and the blueprint's light move only
376
+ on a desktop (a fine pointer, 768px or wider). On a phone they are a still picture.
377
+ - **Filters.** No continuous blur or filter animation on a phone. Response blurs new words only
378
+ with a fine pointer on a wide screen; on a phone they fade. Modal backdrops never blur.
379
+ - **What the finger holds moves with it.** Drawers, toasts, BottomNav's mark and Sortable follow
380
+ the finger 1:1, and a long press picks a Sortable item up.
381
+
382
+ ## Doing it right
383
+
384
+ When a new part moves:
385
+
386
+ 1. Ask why it moves. If the answer is not "where it came from", "what changed", "we heard you" or
387
+ "so nothing jumps", leave it still.
388
+ 2. Use the tokens: `--ease`, `--ease-glide`, `--ease-move`, and the durations or a factor of
389
+ `--duration`. Never hand-type a curve or a time.
390
+ 3. Colour and opacity on `--duration-fade`; movement on `--duration`. Then reduced motion works
391
+ without a line of its own.
392
+ 4. Popups: `popup-motion`. Gliding indicators: `useGlide` and `glideMotion`. Heights:
393
+ `--duration-glide` on `--ease-glide`.
394
+ 5. Leave quicker than you arrive (`--duration-exit`, or 0.7 of the time).
395
+ 6. Answer an action within 300ms, delays included, on an ease-out.
396
+ 7. Transitions for anything that can be interrupted. Keyframes only for loops, a one-off sequence
397
+ on a small mark (a stepper's check), and a page's one entrance (`ep-reveal`).
398
+ 8. Animate transform and opacity. Change size only where content must be pushed.
399
+ 9. Nothing from the keyboard animates: mark it `data-instant`.
400
+ 10. Hover only behind `(hover: hover)`; decorative motion only on a desktop.
401
+ 11. Under reduced motion, check that nothing pops in or out, and that anything busy still pulses.
402
+ 12. In script, read `cssDuration()`, `cssTime()` and `cssEase()`; skip the movement when it is 0.
403
+
404
+ ## Do and don't
405
+
406
+ Do: let a popover grow from 97% at its trigger.
407
+
408
+ Don't: scale a popup from 0, or slide it in from far away.
409
+
410
+ Do: show a press as the material sinking: a darker fill, a deeper inset.
411
+
412
+ Don't: scale a button down when it is pressed, on a desktop. On a phone the phone parts give a
413
+ little under the finger, through `lib/press.ts`, never a scale of a component's own.
414
+
415
+ Do: fade a colour change on `--duration-fade`.
416
+
417
+ Don't: put a hover's colour on `--duration`, which reduced motion turns into a snap.
418
+
419
+ Do: glide the current tab's tile to the new tab over `--duration-glide`.
420
+
421
+ Don't: fade one tab out and the next in, or give each indicator a speed of its own.
422
+
423
+ Do: open the command palette at once from ⌘K.
424
+
425
+ Don't: animate what the keyboard does, because it is done a hundred times a day.
426
+
427
+ Do: close a dialog in 0.7 of the time it took to open.
428
+
429
+ Don't: let anything that answers an action run past 300ms.
430
+
431
+ Do: pulse a skeleton's opacity under reduced motion.
432
+
433
+ Don't: stop a loading indicator dead, or pulse text.
434
+
435
+ Do: keep a hero's grain and glow still on a phone.
436
+
437
+ Don't: animate a large blur or filter on a mobile page.
438
+
439
+ ## Where we differ from Emil's skills
440
+
441
+ - **Scale on press only on a phone.** He scales pressed elements to 97%. On a desktop our
442
+ materials show the press in the fill and the inset shadow, and the brand keeps control geometry
443
+ fixed. On a phone, where the finger hides the fill, the phone parts give as he has it: 97% for a
444
+ small target, 98.5% for a full-width row or card, as well as the shade.
445
+ - **One ease-out, and a softer one for glides.** His curves are a strong ease-out for UI and a
446
+ strong ease-in-out for movement on screen. Our `--ease` is close to his ease-out, so we kept it
447
+ rather than add a second, nearly identical curve. Our glides follow the pointer, so they ease out
448
+ softly (`--ease-glide`). Moves the interface makes on its own use his ease-in-out (`--ease-move`).
449
+ - **Some keys still animate.** He never animates a keyboard action. We keep the digit roll and the
450
+ OTP ring's glide on keys, because they show what changed. A held key carries the roll on from
451
+ where it is instead of restarting it.
452
+ - **A stricter cap.** He allows 200–500ms for modals and drawers. We keep anything that answers an
453
+ action within 300ms. Drawers glide over twice `--duration`, 300ms.
454
+ - **The sticky header keeps its hairline.** His Apple notes prefer a fading scroll edge to a
455
+ divider. Our brand groups content with hairlines.