@cognite/aura 0.3.4 → 1.0.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 (540) hide show
  1. package/CHANGELOG.md +274 -0
  2. package/DESIGN.md +664 -281
  3. package/LICENSE +21 -0
  4. package/README.md +48 -13
  5. package/dist/colors-deprecated.css +618 -0
  6. package/dist/colors.css +803 -830
  7. package/dist/components/index.d.ts +63 -57
  8. package/dist/components/index.js +62 -59
  9. package/dist/components/index.js.map +1 -0
  10. package/dist/components/ui/core/accordion/accordion.d.ts +19 -18
  11. package/dist/components/ui/core/accordion/accordion.js +99 -78
  12. package/dist/components/ui/core/accordion/accordion.js.map +1 -0
  13. package/dist/components/ui/core/action-toolbar/action-toolbar-motion.d.ts +8 -0
  14. package/dist/components/ui/core/action-toolbar/action-toolbar-motion.js +132 -0
  15. package/dist/components/ui/core/action-toolbar/action-toolbar-motion.js.map +1 -0
  16. package/dist/components/ui/core/action-toolbar/action-toolbar.d.ts +31 -31
  17. package/dist/components/ui/core/action-toolbar/action-toolbar.js +156 -106
  18. package/dist/components/ui/core/action-toolbar/action-toolbar.js.map +1 -0
  19. package/dist/components/ui/core/alert/alert.d.ts +25 -25
  20. package/dist/components/ui/core/alert/alert.gallery.d.ts +2 -0
  21. package/dist/components/ui/core/alert/alert.gallery.js +54 -0
  22. package/dist/components/ui/core/alert/alert.gallery.js.map +1 -0
  23. package/dist/components/ui/core/alert/alert.js +181 -152
  24. package/dist/components/ui/core/alert/alert.js.map +1 -0
  25. package/dist/components/ui/core/avatar/avatar.d.ts +10 -9
  26. package/dist/components/ui/core/avatar/avatar.gallery.d.ts +2 -0
  27. package/dist/components/ui/core/avatar/avatar.gallery.js +67 -0
  28. package/dist/components/ui/core/avatar/avatar.gallery.js.map +1 -0
  29. package/dist/components/ui/core/avatar/avatar.js +75 -65
  30. package/dist/components/ui/core/avatar/avatar.js.map +1 -0
  31. package/dist/components/ui/core/badge/badge.d.ts +13 -12
  32. package/dist/components/ui/core/badge/badge.gallery.d.ts +2 -0
  33. package/dist/components/ui/core/badge/badge.gallery.js +64 -0
  34. package/dist/components/ui/core/badge/badge.gallery.js.map +1 -0
  35. package/dist/components/ui/core/badge/badge.js +88 -72
  36. package/dist/components/ui/core/badge/badge.js.map +1 -0
  37. package/dist/components/ui/core/banner/banner.d.ts +18 -18
  38. package/dist/components/ui/core/banner/banner.gallery.d.ts +2 -0
  39. package/dist/components/ui/core/banner/banner.gallery.js +56 -0
  40. package/dist/components/ui/core/banner/banner.gallery.js.map +1 -0
  41. package/dist/components/ui/core/banner/banner.js +179 -142
  42. package/dist/components/ui/core/banner/banner.js.map +1 -0
  43. package/dist/components/ui/core/breadcrumb/breadcrumb.d.ts +12 -12
  44. package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.d.ts +2 -0
  45. package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.js +31 -0
  46. package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.js.map +1 -0
  47. package/dist/components/ui/core/breadcrumb/breadcrumb.js +139 -104
  48. package/dist/components/ui/core/breadcrumb/breadcrumb.js.map +1 -0
  49. package/dist/components/ui/core/button/button.d.ts +7 -7
  50. package/dist/components/ui/core/button/button.gallery.d.ts +2 -0
  51. package/dist/components/ui/core/button/button.gallery.js +76 -0
  52. package/dist/components/ui/core/button/button.gallery.js.map +1 -0
  53. package/dist/components/ui/core/button/button.js +57 -47
  54. package/dist/components/ui/core/button/button.js.map +1 -0
  55. package/dist/components/ui/core/button-group/button-group.d.ts +9 -9
  56. package/dist/components/ui/core/button-group/button-group.gallery.d.ts +2 -0
  57. package/dist/components/ui/core/button-group/button-group.gallery.js +62 -0
  58. package/dist/components/ui/core/button-group/button-group.gallery.js.map +1 -0
  59. package/dist/components/ui/core/button-group/button-group.js +50 -40
  60. package/dist/components/ui/core/button-group/button-group.js.map +1 -0
  61. package/dist/components/ui/core/calendar/calendar-header.d.ts +7 -7
  62. package/dist/components/ui/core/calendar/calendar-header.js +102 -63
  63. package/dist/components/ui/core/calendar/calendar-header.js.map +1 -0
  64. package/dist/components/ui/core/calendar/calendar-utils.d.ts +30 -30
  65. package/dist/components/ui/core/calendar/calendar-utils.js +116 -39
  66. package/dist/components/ui/core/calendar/calendar-utils.js.map +1 -0
  67. package/dist/components/ui/core/calendar/calendar.d.ts +10 -10
  68. package/dist/components/ui/core/calendar/calendar.js +95 -66
  69. package/dist/components/ui/core/calendar/calendar.js.map +1 -0
  70. package/dist/components/ui/core/calendar/constants.js +3 -0
  71. package/dist/components/ui/core/calendar/constants.js.map +1 -0
  72. package/dist/components/ui/core/card/card.d.ts +20 -20
  73. package/dist/components/ui/core/card/card.js +133 -104
  74. package/dist/components/ui/core/card/card.js.map +1 -0
  75. package/dist/components/ui/core/chart/chart.d.ts +55 -53
  76. package/dist/components/ui/core/chart/chart.js +196 -116
  77. package/dist/components/ui/core/chart/chart.js.map +1 -0
  78. package/dist/components/ui/core/chart/index.d.ts +2 -2
  79. package/dist/components/ui/core/chart/index.js +3 -2
  80. package/dist/components/ui/core/chart/index.js.map +1 -0
  81. package/dist/components/ui/core/checkbox/checkbox.d.ts +9 -9
  82. package/dist/components/ui/core/checkbox/checkbox.gallery.d.ts +2 -0
  83. package/dist/components/ui/core/checkbox/checkbox.gallery.js +36 -0
  84. package/dist/components/ui/core/checkbox/checkbox.gallery.js.map +1 -0
  85. package/dist/components/ui/core/checkbox/checkbox.js +88 -68
  86. package/dist/components/ui/core/checkbox/checkbox.js.map +1 -0
  87. package/dist/components/ui/core/checkbox/checkbox.metadata.d.ts +1 -1
  88. package/dist/components/ui/core/checkbox/checkbox.metadata.js +6 -7
  89. package/dist/components/ui/core/checkbox/checkbox.metadata.js.map +1 -0
  90. package/dist/components/ui/core/code-block/code-block.d.ts +19 -19
  91. package/dist/components/ui/core/code-block/code-block.js +260 -175
  92. package/dist/components/ui/core/code-block/code-block.js.map +1 -0
  93. package/dist/components/ui/core/collapsible/collapsible.d.ts +5 -5
  94. package/dist/components/ui/core/collapsible/collapsible.gallery.d.ts +2 -0
  95. package/dist/components/ui/core/collapsible/collapsible.gallery.js +39 -0
  96. package/dist/components/ui/core/collapsible/collapsible.gallery.js.map +1 -0
  97. package/dist/components/ui/core/collapsible/collapsible.js +36 -30
  98. package/dist/components/ui/core/collapsible/collapsible.js.map +1 -0
  99. package/dist/components/ui/core/combobox/combobox.d.ts +13 -13
  100. package/dist/components/ui/core/combobox/combobox.js +89 -40
  101. package/dist/components/ui/core/combobox/combobox.js.map +1 -0
  102. package/dist/components/ui/core/command/command.d.ts +20 -18
  103. package/dist/components/ui/core/command/command.js +137 -85
  104. package/dist/components/ui/core/command/command.js.map +1 -0
  105. package/dist/components/ui/core/conversation/conversation.d.ts +14 -0
  106. package/dist/components/ui/core/conversation/conversation.js +51 -0
  107. package/dist/components/ui/core/conversation/conversation.js.map +1 -0
  108. package/dist/components/ui/core/count/count.d.ts +8 -6
  109. package/dist/components/ui/core/count/count.gallery.d.ts +2 -0
  110. package/dist/components/ui/core/count/count.gallery.js +55 -0
  111. package/dist/components/ui/core/count/count.gallery.js.map +1 -0
  112. package/dist/components/ui/core/count/count.js +51 -21
  113. package/dist/components/ui/core/count/count.js.map +1 -0
  114. package/dist/components/ui/core/data-grid/data-grid-cell.d.ts +5 -7
  115. package/dist/components/ui/core/data-grid/data-grid-cell.js +19 -0
  116. package/dist/components/ui/core/data-grid/data-grid-cell.js.map +1 -0
  117. package/dist/components/ui/core/data-grid/data-grid-column-filter.d.ts +4 -0
  118. package/dist/components/ui/core/data-grid/data-grid-column-filter.js +13 -0
  119. package/dist/components/ui/core/data-grid/data-grid-column-filter.js.map +1 -0
  120. package/dist/components/ui/core/data-grid/data-grid-column-resizer.d.ts +8 -0
  121. package/dist/components/ui/core/data-grid/data-grid-column-resizer.js +25 -0
  122. package/dist/components/ui/core/data-grid/data-grid-column-resizer.js.map +1 -0
  123. package/dist/components/ui/core/data-grid/data-grid-filter-clauses.d.ts +14 -0
  124. package/dist/components/ui/core/data-grid/data-grid-filter-clauses.js +36 -0
  125. package/dist/components/ui/core/data-grid/data-grid-filter-clauses.js.map +1 -0
  126. package/dist/components/ui/core/data-grid/data-grid-filter-panel.d.ts +43 -0
  127. package/dist/components/ui/core/data-grid/data-grid-filter-panel.js +287 -0
  128. package/dist/components/ui/core/data-grid/data-grid-filter-panel.js.map +1 -0
  129. package/dist/components/ui/core/data-grid/data-grid-footer.d.ts +6 -0
  130. package/dist/components/ui/core/data-grid/data-grid-footer.js +34 -0
  131. package/dist/components/ui/core/data-grid/data-grid-footer.js.map +1 -0
  132. package/dist/components/ui/core/data-grid/data-grid-header-row.d.ts +10 -10
  133. package/dist/components/ui/core/data-grid/data-grid-header-row.js +86 -0
  134. package/dist/components/ui/core/data-grid/data-grid-header-row.js.map +1 -0
  135. package/dist/components/ui/core/data-grid/data-grid-header.d.ts +11 -0
  136. package/dist/components/ui/core/data-grid/data-grid-header.js +67 -0
  137. package/dist/components/ui/core/data-grid/data-grid-header.js.map +1 -0
  138. package/dist/components/ui/core/data-grid/data-grid-row.d.ts +13 -15
  139. package/dist/components/ui/core/data-grid/data-grid-row.js +118 -0
  140. package/dist/components/ui/core/data-grid/data-grid-row.js.map +1 -0
  141. package/dist/components/ui/core/data-grid/data-grid-selection-state.d.ts +15 -0
  142. package/dist/components/ui/core/data-grid/data-grid-selection-state.js +32 -0
  143. package/dist/components/ui/core/data-grid/data-grid-selection-state.js.map +1 -0
  144. package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.d.ts +11 -0
  145. package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.js +129 -0
  146. package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.js.map +1 -0
  147. package/dist/components/ui/core/data-grid/data-grid-selection.types.d.ts +24 -0
  148. package/dist/components/ui/core/data-grid/data-grid-selection.types.js +3 -0
  149. package/dist/components/ui/core/data-grid/data-grid-selection.types.js.map +1 -0
  150. package/dist/components/ui/core/data-grid/data-grid.d.ts +125 -35
  151. package/dist/components/ui/core/data-grid/data-grid.fixtures.d.ts +7 -7
  152. package/dist/components/ui/core/data-grid/data-grid.fixtures.js +139 -0
  153. package/dist/components/ui/core/data-grid/data-grid.fixtures.js.map +1 -0
  154. package/dist/components/ui/core/data-grid/data-grid.js +542 -0
  155. package/dist/components/ui/core/data-grid/data-grid.js.map +1 -0
  156. package/dist/components/ui/core/data-grid/data-grid.utils.d.ts +3 -4
  157. package/dist/components/ui/core/data-grid/data-grid.utils.js +53 -0
  158. package/dist/components/ui/core/data-grid/data-grid.utils.js.map +1 -0
  159. package/dist/components/ui/core/data-grid/index.d.ts +6 -0
  160. package/dist/components/ui/core/data-grid/index.js +6 -0
  161. package/dist/components/ui/core/data-grid/index.js.map +1 -0
  162. package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.d.ts +11 -13
  163. package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.js +85 -61
  164. package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.js.map +1 -0
  165. package/dist/components/ui/core/date-time-pickers/date-picker/index.d.ts +3 -3
  166. package/dist/components/ui/core/date-time-pickers/date-picker/index.js +3 -0
  167. package/dist/components/ui/core/date-time-pickers/date-picker/index.js.map +1 -0
  168. package/dist/components/ui/core/date-time-pickers/date-picker/types.d.ts +14 -14
  169. package/dist/components/ui/core/date-time-pickers/date-picker/types.js +3 -0
  170. package/dist/components/ui/core/date-time-pickers/date-picker/types.js.map +1 -0
  171. package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.d.ts +2 -2
  172. package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.js +51 -36
  173. package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.js.map +1 -0
  174. package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.d.ts +11 -13
  175. package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.js +89 -64
  176. package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.js.map +1 -0
  177. package/dist/components/ui/core/date-time-pickers/date-range-picker/index.d.ts +3 -3
  178. package/dist/components/ui/core/date-time-pickers/date-range-picker/index.js +3 -0
  179. package/dist/components/ui/core/date-time-pickers/date-range-picker/index.js.map +1 -0
  180. package/dist/components/ui/core/date-time-pickers/date-range-picker/types.d.ts +20 -20
  181. package/dist/components/ui/core/date-time-pickers/date-range-picker/types.js +3 -0
  182. package/dist/components/ui/core/date-time-pickers/date-range-picker/types.js.map +1 -0
  183. package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.d.ts +4 -4
  184. package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.js +95 -60
  185. package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.js.map +1 -0
  186. package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.d.ts +15 -0
  187. package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.js +120 -0
  188. package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.js.map +1 -0
  189. package/dist/components/ui/core/date-time-pickers/date-time-picker/index.d.ts +3 -1
  190. package/dist/components/ui/core/date-time-pickers/date-time-picker/index.js +3 -0
  191. package/dist/components/ui/core/date-time-pickers/date-time-picker/index.js.map +1 -0
  192. package/dist/components/ui/core/date-time-pickers/date-time-picker/types.d.ts +25 -32
  193. package/dist/components/ui/core/date-time-pickers/date-time-picker/types.js +3 -0
  194. package/dist/components/ui/core/date-time-pickers/date-time-picker/types.js.map +1 -0
  195. package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.d.ts +2 -2
  196. package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.js +78 -0
  197. package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.js.map +1 -0
  198. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.d.ts +13 -15
  199. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.js +165 -119
  200. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.js.map +1 -0
  201. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.d.ts +3 -3
  202. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.js +3 -0
  203. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.js.map +1 -0
  204. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.d.ts +37 -37
  205. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.js +3 -0
  206. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.js.map +1 -0
  207. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.d.ts +3 -3
  208. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.js +163 -104
  209. package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.js.map +1 -0
  210. package/dist/components/ui/core/date-time-pickers/index.d.ts +17 -12
  211. package/dist/components/ui/core/date-time-pickers/index.js +10 -6
  212. package/dist/components/ui/core/date-time-pickers/index.js.map +1 -0
  213. package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.d.ts +5 -5
  214. package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.js +52 -42
  215. package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.js.map +1 -0
  216. package/dist/components/ui/core/date-time-pickers/shared/constants.d.ts +6 -1
  217. package/dist/components/ui/core/date-time-pickers/shared/constants.js +23 -0
  218. package/dist/components/ui/core/date-time-pickers/shared/constants.js.map +1 -0
  219. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.d.ts +16 -15
  220. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.js +87 -64
  221. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.js.map +1 -0
  222. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.d.ts +10 -9
  223. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.js +89 -38
  224. package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.js.map +1 -0
  225. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.d.ts +5 -5
  226. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.js +34 -23
  227. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.js.map +1 -0
  228. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.d.ts +23 -23
  229. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.js +95 -52
  230. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.js.map +1 -0
  231. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.d.ts +5 -5
  232. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.js +22 -18
  233. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.js.map +1 -0
  234. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.d.ts +19 -19
  235. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.js +41 -24
  236. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.js.map +1 -0
  237. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.d.ts +13 -13
  238. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.js +33 -24
  239. package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.js.map +1 -0
  240. package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.d.ts +5 -5
  241. package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.js +9 -4
  242. package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.js.map +1 -0
  243. package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.d.ts +13 -9
  244. package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.js +22 -17
  245. package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.js.map +1 -0
  246. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.d.ts +2 -2
  247. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.js +3 -0
  248. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.js.map +1 -0
  249. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.d.ts +13 -13
  250. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.js +49 -40
  251. package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.js.map +1 -0
  252. package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.d.ts +7 -7
  253. package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.js +41 -34
  254. package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.js.map +1 -0
  255. package/dist/components/ui/core/date-time-pickers/time-picker/index.d.ts +3 -3
  256. package/dist/components/ui/core/date-time-pickers/time-picker/index.js +3 -0
  257. package/dist/components/ui/core/date-time-pickers/time-picker/index.js.map +1 -0
  258. package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.d.ts +12 -14
  259. package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.js +99 -79
  260. package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.js.map +1 -0
  261. package/dist/components/ui/core/date-time-pickers/time-picker/types.d.ts +20 -20
  262. package/dist/components/ui/core/date-time-pickers/time-picker/types.js +3 -0
  263. package/dist/components/ui/core/date-time-pickers/time-picker/types.js.map +1 -0
  264. package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.d.ts +2 -2
  265. package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.js +63 -41
  266. package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.js.map +1 -0
  267. package/dist/components/ui/core/date-time-pickers/time-range-picker/index.d.ts +3 -1
  268. package/dist/components/ui/core/date-time-pickers/time-range-picker/index.js +3 -0
  269. package/dist/components/ui/core/date-time-pickers/time-range-picker/index.js.map +1 -0
  270. package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.d.ts +14 -0
  271. package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.js +115 -0
  272. package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.js.map +1 -0
  273. package/dist/components/ui/core/date-time-pickers/time-range-picker/types.d.ts +30 -36
  274. package/dist/components/ui/core/date-time-pickers/time-range-picker/types.js +3 -0
  275. package/dist/components/ui/core/date-time-pickers/time-range-picker/types.js.map +1 -0
  276. package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.d.ts +2 -2
  277. package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.js +145 -0
  278. package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.js.map +1 -0
  279. package/dist/components/ui/core/date-time-pickers/utils/date-input.d.ts +56 -0
  280. package/dist/components/ui/core/date-time-pickers/utils/date-input.js +67 -0
  281. package/dist/components/ui/core/date-time-pickers/utils/date-input.js.map +1 -0
  282. package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.d.ts +18 -18
  283. package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.js +42 -0
  284. package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.js.map +1 -0
  285. package/dist/components/ui/core/date-time-pickers/utils/format-utils.d.ts +31 -29
  286. package/dist/components/ui/core/date-time-pickers/utils/format-utils.js +56 -0
  287. package/dist/components/ui/core/date-time-pickers/utils/format-utils.js.map +1 -0
  288. package/dist/components/ui/core/date-time-pickers/utils/segment-utils.d.ts +21 -21
  289. package/dist/components/ui/core/date-time-pickers/utils/segment-utils.js +170 -0
  290. package/dist/components/ui/core/date-time-pickers/utils/segment-utils.js.map +1 -0
  291. package/dist/components/ui/core/date-time-pickers/utils/time-utils.d.ts +28 -28
  292. package/dist/components/ui/core/date-time-pickers/utils/time-utils.js +88 -7
  293. package/dist/components/ui/core/date-time-pickers/utils/time-utils.js.map +1 -0
  294. package/dist/components/ui/core/date-time-pickers/utils/time-validation.d.ts +17 -17
  295. package/dist/components/ui/core/date-time-pickers/utils/time-validation.js +43 -0
  296. package/dist/components/ui/core/date-time-pickers/utils/time-validation.js.map +1 -0
  297. package/dist/components/ui/core/dialog/dialog.d.ts +12 -9
  298. package/dist/components/ui/core/dialog/dialog.js +90 -82
  299. package/dist/components/ui/core/dialog/dialog.js.map +1 -0
  300. package/dist/components/ui/core/dropdown-menu/dropdown-menu.d.ts +22 -19
  301. package/dist/components/ui/core/dropdown-menu/dropdown-menu.js +204 -149
  302. package/dist/components/ui/core/dropdown-menu/dropdown-menu.js.map +1 -0
  303. package/dist/components/ui/core/empty-state/empty-state.context.d.ts +4 -4
  304. package/dist/components/ui/core/empty-state/empty-state.context.js +8 -5
  305. package/dist/components/ui/core/empty-state/empty-state.context.js.map +1 -0
  306. package/dist/components/ui/core/empty-state/empty-state.d.ts +14 -14
  307. package/dist/components/ui/core/empty-state/empty-state.js +96 -82
  308. package/dist/components/ui/core/empty-state/empty-state.js.map +1 -0
  309. package/dist/components/ui/core/helper-text/helper-text.d.ts +7 -7
  310. package/dist/components/ui/core/helper-text/helper-text.js +55 -36
  311. package/dist/components/ui/core/helper-text/helper-text.js.map +1 -0
  312. package/dist/components/ui/core/hover-card/hover-card.d.ts +7 -6
  313. package/dist/components/ui/core/hover-card/hover-card.js +56 -52
  314. package/dist/components/ui/core/hover-card/hover-card.js.map +1 -0
  315. package/dist/components/ui/core/inline-citation/inline-citation.d.ts +26 -25
  316. package/dist/components/ui/core/inline-citation/inline-citation.js +121 -97
  317. package/dist/components/ui/core/inline-citation/inline-citation.js.map +1 -0
  318. package/dist/components/ui/core/input/input.d.ts +2 -2
  319. package/dist/components/ui/core/input/input.gallery.d.ts +2 -0
  320. package/dist/components/ui/core/input/input.gallery.js +89 -0
  321. package/dist/components/ui/core/input/input.gallery.js.map +1 -0
  322. package/dist/components/ui/core/input/input.js +15 -13
  323. package/dist/components/ui/core/input/input.js.map +1 -0
  324. package/dist/components/ui/core/input-group/input-group.d.ts +25 -14
  325. package/dist/components/ui/core/input-group/input-group.js +149 -76
  326. package/dist/components/ui/core/input-group/input-group.js.map +1 -0
  327. package/dist/components/ui/core/item/item.d.ts +20 -0
  328. package/dist/components/ui/core/item/item.js +93 -0
  329. package/dist/components/ui/core/item/item.js.map +1 -0
  330. package/dist/components/ui/core/kbd/kbd.d.ts +3 -3
  331. package/dist/components/ui/core/kbd/kbd.js +24 -20
  332. package/dist/components/ui/core/kbd/kbd.js.map +1 -0
  333. package/dist/components/ui/core/label/label.d.ts +3 -3
  334. package/dist/components/ui/core/label/label.gallery.d.ts +2 -0
  335. package/dist/components/ui/core/label/label.gallery.js +57 -0
  336. package/dist/components/ui/core/label/label.gallery.js.map +1 -0
  337. package/dist/components/ui/core/label/label.js +33 -26
  338. package/dist/components/ui/core/label/label.js.map +1 -0
  339. package/dist/components/ui/core/loader/loader.d.ts +6 -6
  340. package/dist/components/ui/core/loader/loader.js +97 -80
  341. package/dist/components/ui/core/loader/loader.js.map +1 -0
  342. package/dist/components/ui/core/message/message-response-default-streamdown-controls.d.ts +8 -9
  343. package/dist/components/ui/core/message/message-response-default-streamdown-controls.js +18 -12
  344. package/dist/components/ui/core/message/message-response-default-streamdown-controls.js.map +1 -0
  345. package/dist/components/ui/core/message/message-response-math-plugin.d.ts +3 -0
  346. package/dist/components/ui/core/message/message-response-math-plugin.js +6 -0
  347. package/dist/components/ui/core/message/message-response-math-plugin.js.map +1 -0
  348. package/dist/components/ui/core/message/message.d.ts +27 -23
  349. package/dist/components/ui/core/message/message.js +458 -316
  350. package/dist/components/ui/core/message/message.js.map +1 -0
  351. package/dist/components/ui/core/overflow-list/overflow-list.d.ts +21 -0
  352. package/dist/components/ui/core/overflow-list/overflow-list.js +197 -0
  353. package/dist/components/ui/core/overflow-list/overflow-list.js.map +1 -0
  354. package/dist/components/ui/core/overflow-list/overflow-list.utils.d.ts +37 -35
  355. package/dist/components/ui/core/overflow-list/overflow-list.utils.js +206 -0
  356. package/dist/components/ui/core/overflow-list/overflow-list.utils.js.map +1 -0
  357. package/dist/components/ui/core/pagination/pagination-size-context.d.ts +2 -2
  358. package/dist/components/ui/core/pagination/pagination-size-context.js +6 -5
  359. package/dist/components/ui/core/pagination/pagination-size-context.js.map +1 -0
  360. package/dist/components/ui/core/pagination/pagination-teleport.d.ts +9 -9
  361. package/dist/components/ui/core/pagination/pagination-teleport.js +127 -84
  362. package/dist/components/ui/core/pagination/pagination-teleport.js.map +1 -0
  363. package/dist/components/ui/core/pagination/pagination-teleport.utils.js +6 -6
  364. package/dist/components/ui/core/pagination/pagination-teleport.utils.js.map +1 -0
  365. package/dist/components/ui/core/pagination/pagination.d.ts +39 -39
  366. package/dist/components/ui/core/pagination/pagination.js +294 -234
  367. package/dist/components/ui/core/pagination/pagination.js.map +1 -0
  368. package/dist/components/ui/core/popover/popover.d.ts +12 -11
  369. package/dist/components/ui/core/popover/popover.js +104 -89
  370. package/dist/components/ui/core/popover/popover.js.map +1 -0
  371. package/dist/components/ui/core/progress/progress.d.ts +9 -8
  372. package/dist/components/ui/core/progress/progress.js +50 -35
  373. package/dist/components/ui/core/progress/progress.js.map +1 -0
  374. package/dist/components/ui/core/prompt-input/prompt-input.d.ts +27 -27
  375. package/dist/components/ui/core/prompt-input/prompt-input.js +342 -271
  376. package/dist/components/ui/core/prompt-input/prompt-input.js.map +1 -0
  377. package/dist/components/ui/core/radio-group/radio-group.d.ts +12 -12
  378. package/dist/components/ui/core/radio-group/radio-group.gallery.d.ts +2 -0
  379. package/dist/components/ui/core/radio-group/radio-group.gallery.js +44 -0
  380. package/dist/components/ui/core/radio-group/radio-group.gallery.js.map +1 -0
  381. package/dist/components/ui/core/radio-group/radio-group.js +88 -58
  382. package/dist/components/ui/core/radio-group/radio-group.js.map +1 -0
  383. package/dist/components/ui/core/reasoning/reasoning.d.ts +7 -7
  384. package/dist/components/ui/core/reasoning/reasoning.js +68 -56
  385. package/dist/components/ui/core/reasoning/reasoning.js.map +1 -0
  386. package/dist/components/ui/core/scroll-area/scroll-area.d.ts +4 -4
  387. package/dist/components/ui/core/scroll-area/scroll-area.js +50 -40
  388. package/dist/components/ui/core/scroll-area/scroll-area.js.map +1 -0
  389. package/dist/components/ui/core/search/search.d.ts +8 -8
  390. package/dist/components/ui/core/search/search.js +122 -76
  391. package/dist/components/ui/core/search/search.js.map +1 -0
  392. package/dist/components/ui/core/segmented-control/segmented-control.d.ts +17 -11
  393. package/dist/components/ui/core/segmented-control/segmented-control.js +204 -108
  394. package/dist/components/ui/core/segmented-control/segmented-control.js.map +1 -0
  395. package/dist/components/ui/core/select/select.d.ts +33 -26
  396. package/dist/components/ui/core/select/select.js +262 -168
  397. package/dist/components/ui/core/select/select.js.map +1 -0
  398. package/dist/components/ui/core/separator/separator.d.ts +2 -2
  399. package/dist/components/ui/core/separator/separator.gallery.d.ts +2 -0
  400. package/dist/components/ui/core/separator/separator.gallery.js +63 -0
  401. package/dist/components/ui/core/separator/separator.gallery.js.map +1 -0
  402. package/dist/components/ui/core/separator/separator.js +13 -13
  403. package/dist/components/ui/core/separator/separator.js.map +1 -0
  404. package/dist/components/ui/core/shimmer/shimmer.d.ts +8 -8
  405. package/dist/components/ui/core/shimmer/shimmer.js +64 -40
  406. package/dist/components/ui/core/shimmer/shimmer.js.map +1 -0
  407. package/dist/components/ui/core/skeleton/skeleton.d.ts +2 -2
  408. package/dist/components/ui/core/skeleton/skeleton.gallery.d.ts +2 -0
  409. package/dist/components/ui/core/skeleton/skeleton.gallery.js +22 -0
  410. package/dist/components/ui/core/skeleton/skeleton.gallery.js.map +1 -0
  411. package/dist/components/ui/core/skeleton/skeleton.js +13 -13
  412. package/dist/components/ui/core/skeleton/skeleton.js.map +1 -0
  413. package/dist/components/ui/core/slider/slider.d.ts +7 -7
  414. package/dist/components/ui/core/slider/slider.gallery.d.ts +2 -0
  415. package/dist/components/ui/core/slider/slider.gallery.js +62 -0
  416. package/dist/components/ui/core/slider/slider.gallery.js.map +1 -0
  417. package/dist/components/ui/core/slider/slider.js +51 -39
  418. package/dist/components/ui/core/slider/slider.js.map +1 -0
  419. package/dist/components/ui/core/sonner-toast/sonner-toast.d.ts +2 -2
  420. package/dist/components/ui/core/sonner-toast/sonner-toast.js +67 -54
  421. package/dist/components/ui/core/sonner-toast/sonner-toast.js.map +1 -0
  422. package/dist/components/ui/core/sources/sources.d.ts +12 -12
  423. package/dist/components/ui/core/sources/sources.js +87 -58
  424. package/dist/components/ui/core/sources/sources.js.map +1 -0
  425. package/dist/components/ui/core/status-text/status-text.d.ts +4 -0
  426. package/dist/components/ui/core/status-text/status-text.js +14 -0
  427. package/dist/components/ui/core/status-text/status-text.js.map +1 -0
  428. package/dist/components/ui/core/switch/switch.d.ts +9 -9
  429. package/dist/components/ui/core/switch/switch.gallery.d.ts +2 -0
  430. package/dist/components/ui/core/switch/switch.gallery.js +67 -0
  431. package/dist/components/ui/core/switch/switch.gallery.js.map +1 -0
  432. package/dist/components/ui/core/switch/switch.js +83 -61
  433. package/dist/components/ui/core/switch/switch.js.map +1 -0
  434. package/dist/components/ui/core/switch/switch.metadata.d.ts +1 -1
  435. package/dist/components/ui/core/switch/switch.metadata.js +8 -0
  436. package/dist/components/ui/core/switch/switch.metadata.js.map +1 -0
  437. package/dist/components/ui/core/tabs/tabs.d.ts +20 -18
  438. package/dist/components/ui/core/tabs/tabs.js +176 -147
  439. package/dist/components/ui/core/tabs/tabs.js.map +1 -0
  440. package/dist/components/ui/core/tabs/tabs.utils.d.ts +1 -1
  441. package/dist/components/ui/core/tabs/tabs.utils.js +10 -6
  442. package/dist/components/ui/core/tabs/tabs.utils.js.map +1 -0
  443. package/dist/components/ui/core/textarea/textarea.d.ts +2 -2
  444. package/dist/components/ui/core/textarea/textarea.gallery.d.ts +2 -0
  445. package/dist/components/ui/core/textarea/textarea.gallery.js +51 -0
  446. package/dist/components/ui/core/textarea/textarea.gallery.js.map +1 -0
  447. package/dist/components/ui/core/textarea/textarea.js +13 -13
  448. package/dist/components/ui/core/textarea/textarea.js.map +1 -0
  449. package/dist/components/ui/core/toggle/toggle.d.ts +9 -9
  450. package/dist/components/ui/core/toggle/toggle.gallery.d.ts +2 -0
  451. package/dist/components/ui/core/toggle/toggle.gallery.js +32 -0
  452. package/dist/components/ui/core/toggle/toggle.gallery.js.map +1 -0
  453. package/dist/components/ui/core/toggle/toggle.js +60 -54
  454. package/dist/components/ui/core/toggle/toggle.js.map +1 -0
  455. package/dist/components/ui/core/tool/tool.d.ts +18 -18
  456. package/dist/components/ui/core/tool/tool.js +167 -126
  457. package/dist/components/ui/core/tool/tool.js.map +1 -0
  458. package/dist/components/ui/core/toolbar/toolbar.d.ts +37 -0
  459. package/dist/components/ui/core/toolbar/toolbar.js +171 -0
  460. package/dist/components/ui/core/toolbar/toolbar.js.map +1 -0
  461. package/dist/components/ui/core/tooltip/tooltip.d.ts +8 -7
  462. package/dist/components/ui/core/tooltip/tooltip.gallery.d.ts +2 -0
  463. package/dist/components/ui/core/tooltip/tooltip.gallery.js +52 -0
  464. package/dist/components/ui/core/tooltip/tooltip.gallery.js.map +1 -0
  465. package/dist/components/ui/core/tooltip/tooltip.js +53 -46
  466. package/dist/components/ui/core/tooltip/tooltip.js.map +1 -0
  467. package/dist/components/ui/core/topbar/topbar.d.ts +26 -26
  468. package/dist/components/ui/core/topbar/topbar.js +160 -105
  469. package/dist/components/ui/core/topbar/topbar.js.map +1 -0
  470. package/dist/components/ui/core/tree/tree.d.ts +20 -0
  471. package/dist/components/ui/core/tree/tree.js +100 -0
  472. package/dist/components/ui/core/tree/tree.js.map +1 -0
  473. package/dist/eslint/index.d.ts +5 -5
  474. package/dist/eslint/index.js +9 -5
  475. package/dist/eslint/index.js.map +1 -0
  476. package/dist/eslint/no-overriding-styles.d.ts +1 -1
  477. package/dist/eslint/no-overriding-styles.js +341 -201
  478. package/dist/eslint/no-overriding-styles.js.map +1 -0
  479. package/dist/icons/index.d.ts +1 -1
  480. package/dist/icons/index.js +2 -0
  481. package/dist/icons/index.js.map +1 -0
  482. package/dist/index.d.ts +1 -1
  483. package/dist/index.js +3 -0
  484. package/dist/index.js.map +1 -0
  485. package/dist/lib/ai/types.d.ts +43 -43
  486. package/dist/lib/ai/types.js +3 -0
  487. package/dist/lib/ai/types.js.map +1 -0
  488. package/dist/lib/decorative-variant-classes.d.ts +53 -0
  489. package/dist/lib/decorative-variant-classes.js +58 -0
  490. package/dist/lib/decorative-variant-classes.js.map +1 -0
  491. package/dist/lib/highlight-code.d.ts +11 -8
  492. package/dist/lib/highlight-code.js +58 -40
  493. package/dist/lib/highlight-code.js.map +1 -0
  494. package/dist/lib/portal-container-context.d.ts +1 -1
  495. package/dist/lib/portal-container-context.js +8 -8
  496. package/dist/lib/portal-container-context.js.map +1 -0
  497. package/dist/lib/shared-theme-from-url.d.ts +13 -0
  498. package/dist/lib/shared-theme-from-url.js +61 -0
  499. package/dist/lib/shared-theme-from-url.js.map +1 -0
  500. package/dist/lib/style-scope.d.ts +2 -2
  501. package/dist/lib/style-scope.js +6 -6
  502. package/dist/lib/style-scope.js.map +1 -0
  503. package/dist/lib/theme-share-url.d.ts +31 -0
  504. package/dist/lib/theme-share-url.js +116 -0
  505. package/dist/lib/theme-share-url.js.map +1 -0
  506. package/dist/lib/types.d.ts +39 -39
  507. package/dist/lib/types.js +3 -0
  508. package/dist/lib/types.js.map +1 -0
  509. package/dist/lib/use-controllable-state.d.ts +4 -7
  510. package/dist/lib/use-controllable-state.js +34 -21
  511. package/dist/lib/use-controllable-state.js.map +1 -0
  512. package/dist/lib/utils.d.ts +63 -34
  513. package/dist/lib/utils.js +134 -32
  514. package/dist/lib/utils.js.map +1 -0
  515. package/dist/styles.css +2 -1
  516. package/dist/styles.source.css +46 -16
  517. package/dist/utils/assign-ref.d.ts +3 -0
  518. package/dist/utils/assign-ref.js +13 -0
  519. package/dist/utils/assign-ref.js.map +1 -0
  520. package/package.json +53 -14
  521. package/src/components/ui/core/alert/alert.md +46 -0
  522. package/src/components/ui/core/avatar/avatar.md +30 -0
  523. package/src/components/ui/core/badge/badge.md +32 -0
  524. package/src/components/ui/core/banner/banner.md +51 -0
  525. package/src/components/ui/core/breadcrumb/breadcrumb.md +45 -0
  526. package/src/components/ui/core/button/button.md +93 -0
  527. package/src/components/ui/core/button-group/button-group.md +38 -0
  528. package/src/components/ui/core/checkbox/checkbox.md +37 -0
  529. package/src/components/ui/core/collapsible/collapsible.md +42 -0
  530. package/src/components/ui/core/count/count.md +33 -0
  531. package/src/components/ui/core/input/input.md +48 -0
  532. package/src/components/ui/core/label/label.md +35 -0
  533. package/src/components/ui/core/radio-group/radio-group.md +38 -0
  534. package/src/components/ui/core/separator/separator.md +32 -0
  535. package/src/components/ui/core/skeleton/skeleton.md +33 -0
  536. package/src/components/ui/core/slider/slider.md +41 -0
  537. package/src/components/ui/core/switch/switch.md +26 -0
  538. package/src/components/ui/core/textarea/textarea.md +42 -0
  539. package/src/components/ui/core/toggle/toggle.md +39 -0
  540. package/src/components/ui/core/tooltip/tooltip.md +41 -0
package/DESIGN.md CHANGED
@@ -228,7 +228,7 @@ Aura color behaves like instrumentation in a control room. Most of the interface
228
228
 
229
229
  Use **Base** color for the operating surface: page backgrounds, cards, text, borders, focus, and persistent chrome. This is ~80–90% of the UI.
230
230
 
231
- Use **Semantic** color only for status and feedback: info, success, warning, destructive, validation, and operational state. This is ~5–10% of the UI.
231
+ Use **Semantic** color only for status and feedback: info, success, warning, critical, validation, and operational state. This is ~5–10% of the UI.
232
232
 
233
233
  Use **Decorative** color only for non-status differentiation: accents, avatars, illustrations, and small visual markers that do not imply system health. This is ~5–10% of the UI.
234
234
 
@@ -236,179 +236,302 @@ Light-theme reference values for key roles are defined as `colors.*` tokens in t
236
236
 
237
237
  Do not hardcode hex, font sizes, or shadow strings in product UI when a token exists.
238
238
 
239
- Aura supports **light** (`:root`) and **dark** (`.dark` / `prefers-color-scheme: dark` per library setup). Semantic and base tokens **resolve to different ramps** per theme. **`background-fixed-dark`**, **`background-fixed-light`**, **`foreground-fixed-*`**, and related **fixed** tokens keep the same appearance in both themes (persistent chrome such as sidebars). Always verify contrast in both themes before shipping.
239
+ Aura supports **light** (`:root`) and **dark** (`.dark` / `prefers-color-scheme: dark` per library setup). Theme tokens **resolve to different ramp steps** per theme. **`*-fixed-dark`** tokens keep the same appearance in both themes (persistent dark chrome such as sidebars). Always verify contrast in both themes before shipping.
240
240
 
241
- Reference tokens by **full CSS name** or Tailwind token. Never use raw `hex` / `rgb` / `hsl` in product code. If no semantic token fits, use a documented **base** token; **step colors** on ramps (`mountain/*`, `fjord/*`, …) are only for custom, branding, or marketing surfaces where no semantic token exists yet.
241
+ Reference tokens by **full CSS name** or Tailwind utility (`bg-base-background`, `text-critical-foreground-strong`, `border-default`, …). Never use raw `hex` / `rgb` / `hsl` in product code. Use **step colors** on ramps (`mountain-*`, `fjord-*`, …) only for custom, branding, or marketing surfaces where no theme token exists yet.
242
242
 
243
243
  ### Common Tailwind mappings
244
244
 
245
- Tables in this section use **CSS role names** (e.g. `link-foreground`, `card-background`). Each role maps to a `--color-{role}` custom property and Tailwind v4 utilities (`text-{role}`, `bg-{role}`, `border-{role}`, and `ring-{role}` where applicable). Prefer these utilities over raw `var(--…)` when the theme wire-up matches.
246
-
247
- | Role (suffix after `text-` / `bg-` / `border-`) | Typical utilities | Notes |
248
- | ----------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
249
- | `background` | `bg-background` | Page base |
250
- | `foreground` | `text-foreground` | Primary text |
251
- | `muted-foreground` | `text-muted-foreground` | Tertiary copy |
252
- | `card-background` | `bg-card-background` | Cards (see **Card** component) |
253
- | `muted-background` | `bg-muted-background` | Static fills, inputs, secondary chrome |
254
- | `border` | `border-border` | Default strokes |
255
- | `link-foreground` (`{colors.link-foreground}`) | `text-link-foreground` | Text links — same value as `{colors.tertiary}` |
256
- | `primary-background` | `bg-primary-background`, `text-foreground-on-primary` | Default **Button** (`variant="default"`) pattern |
257
- | `destructive-background` | `bg-destructive-background`, `text-destructive-foreground-on-critical` (on surface) | Destructive actions — pairings in **Semantic colors** |
258
- | `info-background`, `success-background`, … | `bg-info-background`, `text-info-foreground`, … | Full names match **Semantic colors** token columns |
259
-
260
- Semantic utilities use the **full token name** as the Tailwind segment (e.g. `bg-info-background`, not `bg-info`). For **charts**, utilities follow the **Chart tokens** names (`bg-chart-fjord-color-1`, `bg-chart-gridlines`, …).
261
-
262
- Tables below list **light-theme** values as `{colors.<name>}` token references in the YAML front matter and **dark-theme** resolved values in the second column; the published `colors.css` is the runtime source of truth (some entries are `rgba()`).
263
-
264
- ### Base — Background
265
-
266
- | Token | Light (reference) | Dark (reference) | Use |
267
- | ------------------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------ |
268
- | `background` | `{colors.background}` | `#191B1D` | Primary surface — lowest layer |
269
- | `alternate-background` | `{colors.alternate-background}` | `#111213` | Distinct layer or block separate from `background` |
270
- | `card-background` | `{colors.card-background}` | `#212426` | Cards without drop shadow on `background` / `alternate-background` |
271
- | `muted-background` | `{colors.muted-background}` | `#2D3134` | Static fills for controls, rows, segmented controls |
272
- | `primary-background` | `{colors.primary}` | `#F9FAFA` | Primary actions (default button); use sparingly |
273
- | `primary-background-hover` | `{colors.primary-background-hover}` | `#E4E6E8` | Hover on `primary-background` |
274
- | `secondary-background` | `#E4E6E8` | `#40464A` | Secondary actions, switch track |
275
- | `secondary-background-hover` | `{colors.secondary-background-hover}` | `#5E666D` | Hover on `secondary-background` |
276
- | `accent-background` | `#F1F2F3` | `#2D3134` | Neutral hover on `background` / `card-background` (e.g. tabs) |
277
- | `accent-background-strong` | `#E4E6E8` | `#40464A` | Neutral hover on `muted-background` / `active-muted-background` |
278
- | `highlight-background` | `#F1F2F3` | `#2D3134` | Focused / active fields (inputs, selects, comboboxes) |
279
- | `highlight-background-strong` | `#E4E6E8` | `#40464A` | Stronger focused / active field fill |
280
- | `active-background` | `#191B1D` | `#F9FAFA` | High-contrast “on” (switch, checkbox, radio) |
281
- | `active-background-hover` | `#2D3134` | `#F1F2F3` | Hover on `active-background` |
282
- | `active-muted-background` | `#F1F2F3` | `#2D3134` | Lower-contrast selected (e.g. tabs) |
283
- | `active-muted-background-hover` | `#E4E6E8` | `#40464A` | Hover on `active-muted-background` |
284
- | `popover-background` | `#FFFFFF` | `#212426` | Top-layer surfaces with shadow (dialogs, popovers) |
285
- | `raised-background` | `#2D3134` | `#40464A` | Tooltips, Sonner toasts — floats above page |
286
- | `disabled-background` | `#F1F2F3` | `#2D3134` | Disabled inputs and controls |
287
- | `overlay-background` | `{colors.overlay-background}` | `#7C868E80` | Scrim behind modals |
288
- | `background-fixed-dark` | `#212426` | `#212426` | Must stay **dark** in both themes |
289
- | `background-fixed-light` | `#FFFFFF` | `#FFFFFF` | Must stay **light** in both themes |
290
- | `accent-background-fixed-dark` | `#2D3134` | `#2D3134` | Persistent dark accent chrome (e.g. sidebar) |
291
-
292
- ### Base — Foreground
293
-
294
- | Token | Light (reference) | Dark (reference) | Use |
295
- | ---------------------------------- | -------------------------------- | ---------------- | ------------------------------ |
296
- | `foreground` | `{colors.foreground}` | `#F1F2F3` | Primary text and icons |
297
- | `secondary-foreground` | `{colors.secondary-foreground}` | `#D4D7D9` | Supporting text and icons |
298
- | `muted-foreground` | `{colors.muted-foreground}` | `#A5ABB1` | Tertiary / low emphasis |
299
- | `disabled-foreground` | `#D4D7D9` | `#5E666D` | Disabled text and icons |
300
- | `link-foreground` | `{colors.link-foreground}` | `#1742E7` | Text links |
301
- | `foreground-on-primary` | `{colors.foreground-on-primary}` | `#191B1D` | On `primary-background` |
302
- | `foreground-on-active` | `#F1F2F3` | `#191B1D` | On `active-background` |
303
- | `active-foreground` | `#191B1D` | `#F1F2F3` | On `active-muted-background` |
304
- | `foreground-fixed-dark` | `#191B1D` | `#191B1D` | Must stay dark in both themes |
305
- | `foreground-fixed-light` | `#FFFFFF` | `#FFFFFF` | Must stay light in both themes |
306
- | `foreground-secondary-fixed-dark` | `#40464A` | `#40464A` | Secondary copy, always dark |
307
- | `secondary-foreground-fixed-light` | `#D4D7D9` | `#D4D7D9` | Secondary copy, always light |
308
- | `muted-foreground-fixed-light` | `#BBC0C4` | `#BBC0C4` | Muted copy, always light |
309
-
310
- ### Base — Borders and focus
311
-
312
- | Token | Light (reference) | Dark (reference) | Use |
313
- | ------------------- | ---------------------------- | ---------------- | ------------------------------------------------ |
314
- | `border` | `{colors.border}` | `#2D3134` | Default strokes |
315
- | `border-emphasized` | `{colors.border-emphasized}` | `#40464A` | Stronger separation |
316
- | `border-on-dark` | `#2D3134` | `#2D3134` | Strokes on dark chrome (both themes) |
317
- | `border-active` | `#191B1D` | `#F9FAFA` | Active / toggled outlines |
318
- | `ring` | `{colors.ring}` | `#7081C7` | Focus ring outer (maps to `--shadow-focus-ring`) |
319
- | `ring-muted` | `{colors.ring-muted}` | `#B5BEE2` | Focus ring inner companion |
320
-
321
- Also generated: `ring-destructive`, `ring-destructive-muted` for destructive / invalid focus (see **Effects — Focus rings**).
322
-
323
- ### Semantic colors
324
-
325
- Semantic tokens are **only** for status and system feedback (Alert, Banner, Sonner, badge status variants, validation). Do not use them as generic fills or decoration.
326
-
327
- Each family has **default** pairings (theme-switching surfaces) and **muted** pairings (blocks on **persistent dark chrome**). On muted surfaces, use the same `*-foreground-on-*` token names with the muted background; verify contrast in context.
328
-
329
- **Info**
330
-
331
- | Token | Light (reference) | Dark (reference) | Use |
332
- | ------------------------- | ---------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
333
- | `info-background` | `{colors.info-background}` | `#B5BEE2` | Info surface |
334
- | `info-background-hover` | `#B5BEE2` | `#D0D6ED` | Hover on `info-background` |
335
- | `info-foreground` | `#4A5FB8` | `#9DA9D9` | Text near info context on standard surfaces |
336
- | `info-foreground-on-info` | `{colors.info-foreground-on-info}` | `#1A2242` | Text **on** `info-background` |
337
- | `info-muted-background` | `#F0F2F9` | `#2D3134` | Info tint on dark chrome |
338
- | _(pairing)_ | — | — | On `info-muted-background`, use `info-foreground-on-info` for on-surface copy |
339
-
340
- **Success**
341
-
342
- | Token | Light (reference) | Dark (reference) | Use |
343
- | ------------------------------- | ---------------------------------------- | ---------------- | ------------------------------------------------------------------ |
344
- | `success-background` | `{colors.success-background}` | `#8BDEAE` | Success surface |
345
- | `success-background-hover` | `#8BDEAE` | `#BBF3D0` | Hover on `success-background` |
346
- | `success-foreground` | `#1C984A` | `#24C45E` | Text near success on standard surfaces |
347
- | `success-foreground-on-success` | `{colors.success-foreground-on-success}` | `#0A381C` | Text **on** `success-background` |
348
- | `success-muted-background` | `#DDF9E7` | `#2D3134` | Success on dark chrome |
349
- | _(pairing)_ | — | — | On `success-muted-background`, use `success-foreground-on-success` |
350
-
351
- **Warning**
352
-
353
- | Token | Light (reference) | Dark (reference) | Use |
354
- | ------------------------------- | ---------------------------------------- | ---------------- | -------------------------------------- |
355
- | `warning-background` | `{colors.warning-background}` | `#FFE3A2` | Warning surface |
356
- | `warning-background-hover` | `#FFD062` | `#FFF1D0` | Hover on `warning-background` |
357
- | `warning-foreground` | `#C18800` | `#D8BF00` | Text near warning on standard surfaces |
358
- | `warning-foreground-on-warning` | `{colors.warning-foreground-on-warning}` | `#5B4000` | Text **on** `warning-background` |
359
- | `warning-muted-background` | `#FFF1D0` | `#2D3134` | Warning on dark chrome |
360
-
361
- **Destructive**
362
-
363
- | Token | Light (reference) | Dark (reference) | Use |
364
- | ------------------------------------ | --------------------------------------------- | ---------------- | -------------------------------------------------- |
365
- | `destructive-background` | `{colors.destructive-background}` | `#FAA9B7` | Error / destructive surface |
366
- | `destructive-background-hover` | `#FAA9B7` | `#FCCAD2` | Hover on `destructive-background` |
367
- | `destructive-foreground` | `#CB0B2C` | `#F65E78` | Text near destructive context on standard surfaces |
368
- | `destructive-foreground-on-critical` | `{colors.destructive-foreground-on-critical}` | `#8D081F` | Text **on** `destructive-background` |
369
- | `destructive-muted-background` | `#FDDEE4` | `#2D3134` | Destructive on dark chrome |
370
- | `destructive-muted-background-hover` | `#FCCAD2` | `#40464A` | Hover on `destructive-muted-background` |
371
-
372
- **Neutral** (status: draft, archived — not “semantic calm” in the same sense as info/success)
373
-
374
- | Token | Light (reference) | Dark (reference) | Use |
375
- | ------------------------------- | ----------------- | ---------------- | -------------------------------- |
376
- | `neutral-background` | `#E4E6E8` | `#D4D7D9` | Neutral status surface |
377
- | `neutral-background-hover` | `#D4D7D9` | `#E4E6E8` | Hover on `neutral-background` |
378
- | `neutral-foreground` | `#52595F` | `#A5ABB1` | Text near neutral status |
379
- | `neutral-foreground-on-neutral` | `#40464A` | `#2D3134` | Text **on** `neutral-background` |
380
- | `neutral-muted-background` | `#F1F2F3` | `#2D3134` | Neutral on dark chrome |
381
-
382
- **Naming:** CSS uses full role names (`info-foreground-on-info`, `neutral-foreground-on-neutral`, `destructive-foreground-on-critical`). There is no shortened alias in the theme.
245
+ Theme tables below use **CSS token names** from Figma Reflect. Each maps to `--color-{name}` and Tailwind v4 utilities (`text-{name}`, `bg-{name}`, `border-{name}`, `ring-{name}`). Prefer utilities over raw `var(--…)`.
246
+
247
+ | Pattern | Example utilities | Notes |
248
+ | --------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
249
+ | `base-*` | `bg-base-background`, `text-base-foreground` | Page surface and primary text |
250
+ | `medium-*` | `bg-medium-background`, `text-medium-foreground` | Inputs, fields, subtle elevation |
251
+ | `muted-*` | `bg-muted-background`, `text-muted-foreground` | Secondary chrome, segmented tracks |
252
+ | `primary-*` / `secondary-*` | `bg-primary-background`, `text-primary-foreground` | Brand actions |
253
+ | `popover-*` / `card-*` | `bg-popover-background`, `bg-card-background` | Elevated surfaces |
254
+ | `critical-*` | `bg-critical-background` + `text-critical-foreground`; flat status text: `text-critical-foreground-strong` | Errors / critical status (not `destructive-*`) |
255
+ | `border-*` | `border-default`, `border-emphasized`, `border-disabled` | Strokes (`default` → `--default` in CSS) |
256
+ | `ring-*` | `ring-ring-default`, shadow focus utilities | Focus rings |
257
+ | `decorative-{n}-*` | `bg-decorative-1-background` | Non-status accents (slot `n` = ramp in table) |
258
+ | `chart-*` | `bg-chart-1-200`, `bg-chart-gridlines` | Plotted data only |
259
+
260
+ Light and dark columns in the tables show the **ramp step** each token resolves to in `colors.css` (e.g. `mountain-50`, `fjord-500`).
261
+
262
+ ### Base
263
+
264
+ | Token | Light (ramp) | Dark (ramp) | Use |
265
+ | ------------------------------------- | --------------------------- | -------------- | ------------------------------- |
266
+ | `base-background` | `mountain-white` | `mountain-950` | Primary page surface |
267
+ | `base-background-hover` | `mountain-50` | `mountain-800` | Hover on base surface |
268
+ | `base-background-hover-fixed-dark` | `mountain-700` | `mountain-700` | Hover on persistent dark chrome |
269
+ | `base-background-disabled` | `mountain-50` | `mountain-800` | Disabled control fill |
270
+ | `base-background-disabled-fixed-dark` | `mountain-700` | `mountain-700` | Disabled on dark chrome |
271
+ | `base-background-overlay` | `rgba(124, 134, 142, 0.55)` | same | Modal scrim |
272
+ | `base-foreground` | `mountain-950` | `mountain-10` | Primary text and icons |
273
+ | `base-foreground-disabled` | `mountain-300` | `mountain-600` | Disabled text |
274
+ | `base-foreground-disabled-fixed-dark` | `mountain-600` | `mountain-600` | Disabled text on dark chrome |
275
+
276
+ ### Medium
277
+
278
+ | Token | Light (ramp) | Dark (ramp) | Use |
279
+ | ------------------------------ | -------------- | -------------- | -------------------------------- |
280
+ | `medium-background` | `mountain-50` | `mountain-800` | Inputs, comboboxes, subtle fills |
281
+ | `medium-background-hover` | `mountain-100` | `mountain-700` | Hover on medium surfaces |
282
+ | `medium-foreground` | `mountain-700` | `mountain-300` | Text on medium surfaces |
283
+ | `medium-foreground-hover` | `mountain-500` | `mountain-500` | Hover text on medium |
284
+ | `medium-foreground-fixed-dark` | `mountain-300` | `mountain-300` | Medium text on dark chrome |
285
+
286
+ ### Muted
287
+
288
+ | Token | Light (ramp) | Dark (ramp) | Use |
289
+ | ----------------------------- | -------------- | -------------- | ------------------------------- |
290
+ | `muted-background` | `mountain-10` | `mountain-900` | Secondary chrome, switch tracks |
291
+ | `muted-background-hover` | `mountain-50` | `mountain-800` | Hover on muted surfaces |
292
+ | `muted-foreground` | `mountain-550` | `mountain-400` | Tertiary text |
293
+ | `muted-foreground-hover` | `mountain-700` | `mountain-100` | Hover tertiary text |
294
+ | `muted-foreground-fixed-dark` | `mountain-400` | `mountain-400` | Muted text on dark chrome |
295
+
296
+ ### Primary (brand)
297
+
298
+ | Token | Light (ramp) | Dark (ramp) | Use |
299
+ | ------------------------------------- | -------------- | -------------- | -------------------------------- |
300
+ | `primary-background` | `mountain-900` | `mountain-10` | Primary actions (default button) |
301
+ | `primary-background-hover` | `mountain-650` | `mountain-100` | Hover on primary |
302
+ | `primary-background-fixed-dark` | `mountain-10` | `mountain-10` | Primary fill on dark chrome |
303
+ | `primary-background-hover-fixed-dark` | `mountain-100` | `mountain-100` | Hover primary on dark chrome |
304
+ | `primary-foreground` | `mountain-50` | `mountain-950` | Text on `primary-background` |
305
+ | `primary-foreground-fixed-dark` | `mountain-950` | `mountain-950` | Text on primary on dark chrome |
306
+
307
+ ### Secondary (brand)
308
+
309
+ | Token | Light (ramp) | Dark (ramp) | Use |
310
+ | --------------------------------------- | -------------- | -------------- | ------------------------------ |
311
+ | `secondary-background` | `mountain-100` | `mountain-700` | Secondary actions, quiet fills |
312
+ | `secondary-background-hover` | `mountain-50` | `mountain-600` | Hover on secondary |
313
+ | `secondary-background-fixed-dark` | `mountain-700` | `mountain-700` | Secondary on dark chrome |
314
+ | `secondary-background-hover-fixed-dark` | `mountain-600` | `mountain-600` | Hover secondary on dark chrome |
315
+ | `secondary-foreground` | `mountain-700` | `mountain-200` | Text on secondary |
316
+ | `secondary-foreground-fixed-dark` | `mountain-200` | `mountain-200` | Secondary text on dark chrome |
317
+
318
+ ### Popover
319
+
320
+ | Token | Light (ramp) | Dark (ramp) | Use |
321
+ | ------------------------------- | ---------------- | ---------------- | --------------------------------- |
322
+ | `popover-background` | `mountain-white` | `mountain-900` | Dialogs, menus, shadowed surfaces |
323
+ | `popover-background-hover` | `mountain-50` | `mountain-800` | Hover on popover surface |
324
+ | `popover-background-fixed-dark` | `mountain-800` | `mountain-800` | Popover on dark chrome |
325
+ | `popover-foreground` | `mountain-950` | `mountain-50` | Text on popover |
326
+ | `popover-foreground-fixed-dark` | `mountain-white` | `mountain-white` | Text on popover on dark chrome |
327
+
328
+ ### Card
329
+
330
+ | Token | Light (ramp) | Dark (ramp) | Use |
331
+ | ----------------------- | -------------- | -------------- | -------------------- |
332
+ | `card-background` | `mountain-10` | `mountain-800` | Card surface on base |
333
+ | `card-background-hover` | `mountain-50` | `mountain-700` | Hover on card |
334
+ | `card-foreground` | `mountain-950` | `mountain-50` | Card text |
335
+
336
+ ### Link
337
+
338
+ | Token | Light (ramp) | Dark (ramp) | Use |
339
+ | ----------------------- | ------------ | ----------- | ---------- |
340
+ | `link-foreground` | `fjord-600` | `fjord-450` | Text links |
341
+ | `link-foreground-hover` | `fjord-700` | `fjord-200` | Link hover |
342
+
343
+ ### Border
344
+
345
+ | Token | Light (ramp) | Dark (ramp) | Use |
346
+ | ------------ | -------------- | -------------- | ----------------------------------------- |
347
+ | `default` | `mountain-100` | `mountain-700` | Default strokes (`border-default`) |
348
+ | `emphasized` | `mountain-200` | `mountain-600` | Stronger separation (`border-emphasized`) |
349
+ | `disabled` | `mountain-50` | `mountain-800` | Disabled outlines (`border-disabled`) |
350
+
351
+ ### Ring (focus)
352
+
353
+ | Token | Light (ramp) | Dark (ramp) | Use |
354
+ | --------------------- | ------------ | ----------- | --------------------------- |
355
+ | `ring-default` | `fjord-500` | `fjord-400` | Default focus ring |
356
+ | `ring-muted` | `gray-200` | `gray-800` | Focus ring inner / muted |
357
+ | `ring-critical` | `red-600` | `red-450` | Invalid / destructive focus |
358
+ | `ring-critical-muted` | `red-100` | `red-900` | Destructive focus companion |
359
+
360
+ Each **status family** (success, warning, critical, info, neutral) shares the same foreground pairing pattern:
361
+
362
+ | Suffix | Use |
363
+ | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
364
+ | `*-foreground` | Text and icons **on** `*-background` (Alert fills, filled Badge, status chips with a tint) |
365
+ | `*-foreground-strong` | Status text and icons **without** a tinted background — on `base-background`, `card-background`, or inline in body copy |
366
+
367
+ Example: `bg-critical-background` + `text-critical-foreground` for a filled error badge; `text-critical-foreground-strong` for a red error label on a plain card.
368
+
369
+ ### Success
370
+
371
+ | Token | Light (ramp) | Dark (ramp) | Use |
372
+ | --------------------------- | ------------ | ----------- | ---------------------------------------------------------- |
373
+ | `success-background` | `green-100` | `green-900` | Success surface |
374
+ | `success-background-hover` | `green-200` | `green-800` | Hover on success |
375
+ | `success-foreground` | `green-650` | `green-400` | Text and icons **on** `success-background` |
376
+ | `success-foreground-strong` | `green-500` | `green-400` | Success status text/icons **without** `success-background` |
377
+
378
+ ### Warning
379
+
380
+ | Token | Light (ramp) | Dark (ramp) | Use |
381
+ | --------------------------- | ------------ | ------------ | ---------------------------------------------------------- |
382
+ | `warning-background` | `orange-100` | `orange-900` | Warning surface |
383
+ | `warning-background-hover` | `orange-200` | `orange-800` | Hover on warning |
384
+ | `warning-foreground` | `orange-650` | `orange-400` | Text and icons **on** `warning-background` |
385
+ | `warning-foreground-strong` | `orange-500` | `orange-400` | Warning status text/icons **without** `warning-background` |
386
+
387
+ ### Critical
388
+
389
+ | Token | Light (ramp) | Dark (ramp) | Use |
390
+ | ---------------------------- | ------------ | ----------- | ------------------------------------------------------------ |
391
+ | `critical-background` | `red-100` | `red-900` | Error / critical surface |
392
+ | `critical-background-hover` | `red-200` | `red-800` | Hover on critical |
393
+ | `critical-foreground` | `red-650` | `red-400` | Text and icons **on** `critical-background` |
394
+ | `critical-foreground-strong` | `red-500` | `red-400` | Critical status text/icons **without** `critical-background` |
395
+
396
+ ### Info
397
+
398
+ | Token | Light (ramp) | Dark (ramp) | Use |
399
+ | ------------------------ | ------------ | ----------- | ---------------------------------------------------- |
400
+ | `info-background` | `blue-100` | `blue-900` | Info surface |
401
+ | `info-background-hover` | `blue-200` | `blue-800` | Hover on info |
402
+ | `info-foreground` | `blue-650` | `blue-400` | Text and icons **on** `info-background` |
403
+ | `info-foreground-strong` | `blue-500` | `blue-400` | Info status text/icons **without** `info-background` |
404
+
405
+ ### Neutral (status)
383
406
 
384
- ### Decorative colors
407
+ | Token | Light (ramp) | Dark (ramp) | Use |
408
+ | --------------------------- | -------------- | -------------- | ---------------------------------------------------------- |
409
+ | `neutral-background` | `mountain-100` | `mountain-900` | Draft / archived status |
410
+ | `neutral-background-hover` | `mountain-200` | `mountain-800` | Hover on neutral status |
411
+ | `neutral-foreground` | `mountain-650` | `mountain-400` | Text and icons **on** `neutral-background` |
412
+ | `neutral-foreground-strong` | `mountain-550` | `mountain-400` | Neutral status text/icons **without** `neutral-background` |
413
+
414
+ **Naming:** `*-foreground` replaces legacy `*-foreground-on-*` (copy on tinted status surfaces). `*-foreground-strong` is the flat-surface status color (replaces legacy bare `*-foreground` / `destructive-foreground` used near status on standard surfaces). Critical replaces legacy `destructive-*` in theme tokens.
385
415
 
386
- For **small accents** (badges, avatars, empty states) where color differentiates but does **not** signal status — use **Chart tokens** for plot colors, not this ramp, unless a design explicitly maps a tile to a series color. Pattern: `decorative-background-{ramp}`, `decorative-background-{ramp}-hover`, `decorative-foreground-{ramp}`.
416
+ ### Decorative colors
387
417
 
388
- **Preference order for new work:**
418
+ For **small accents** (badges, avatars, empty states) where color differentiates but does **not** signal status — use **decorative-{1..7}-\*** semantic slots, not chart series colors, unless a design explicitly maps a tile to a plot series. Pattern: `decorative-{n}-background`, `decorative-{n}-background-hover`, `decorative-{n}-foreground` (slot `n` matches the ramp in the table below).
389
419
 
390
- | Priority | Ramp | Background | Foreground |
391
- | -------- | -------- | -------------------------------- | -------------------------------- |
392
- | 1 | Fjord | `decorative-background-fjord` | `decorative-foreground-fjord` |
393
- | 2 | Nordic | `decorative-background-nordic` | `decorative-foreground-nordic` |
394
- | 3 | Aurora | `decorative-background-aurora` | `decorative-foreground-aurora` |
395
- | 4 | Dusk | `decorative-background-dusk` | `decorative-foreground-dusk` |
396
- | 5 | Orange | `decorative-background-orange` | `decorative-foreground-orange` |
397
- | 6 | Sky | `decorative-background-sky` | `decorative-foreground-sky` |
398
- | 7 | Mountain | `decorative-background-mountain` | `decorative-foreground-mountain` |
420
+ **CSS token slots** (Figma Reflect naming):
399
421
 
400
- Example (fjord ramp): light `decorative-background-fjord` → `#CCD5FA` (fjord-200), `decorative-foreground-fjord` → `#1234B6` (fjord-700); dark → `#AEBDF7` / `#0D2582` (fjord-300 / fjord-800).
422
+ | Slot | Ramp | Background | Foreground |
423
+ | ---- | -------- | ---------------------------------------------------------- | ------------------------- |
424
+ | 1 | Mountain | `decorative-1-background`, `decorative-1-background-hover` | `decorative-1-foreground` |
425
+ | 2 | Fjord | `decorative-2-background`, `decorative-2-background-hover` | `decorative-2-foreground` |
426
+ | 3 | Nordic | `decorative-3-background`, `decorative-3-background-hover` | `decorative-3-foreground` |
427
+ | 4 | Aurora | `decorative-4-background`, `decorative-4-background-hover` | `decorative-4-foreground` |
428
+ | 5 | Dusk | `decorative-5-background`, `decorative-5-background-hover` | `decorative-5-foreground` |
429
+ | 6 | Amber | `decorative-6-background`, `decorative-6-background-hover` | `decorative-6-foreground` |
430
+ | 7 | Pink | `decorative-7-background`, `decorative-7-background-hover` | `decorative-7-foreground` |
401
431
 
402
- ### Chart tokens
432
+ **Avatar and Badge** expose a unified `decorative-1` … `decorative-7` **variant prop** (labels “Decorative 1” … “Decorative 7” in Storybook). Default is `decorative-1` (Mountain). Each prop maps to the matching CSS slot (e.g. prop `decorative-2` → `decorative-2-*` tokens / Fjord).
403
433
 
404
- **Priority rule:** use `chart-*` for any data plotted on axes or series; use `decorative-*` for non-data visual differentiation (tiles, avatars, accents); use semantic tokens (`info-*`, `success-*`, `warning-*`, `destructive-*`) for operational status and feedback only. Never swap between these groups.
434
+ Example (Fjord slot 2): light `decorative-2-background` → `fjord-200`, hover → `fjord-300`, `decorative-2-foreground` → `fjord-800`; dark → `fjord-300` / `fjord-200` / `fjord-900`.
405
435
 
406
- | Token | Use |
407
- | ----------------------------------------------- | ----------------------------------------------------------- |
408
- | `chart-{ramp}-color-1` … `chart-{ramp}-color-6` | Alpha-based series / area-fill steps (strongest → lightest) |
409
- | `chart-gridlines` | Grid lines |
436
+ ### Chart tokens
410
437
 
411
- Default series order: **fjord → nordic → aurora → dusk → orange**.
438
+ **Priority rule:** use `chart-*` for any data plotted on axes or series; use `decorative-*` for non-data visual differentiation (tiles, avatars, accents); use semantic tokens (`info-*`, `success-*`, `warning-*`, `critical-*`) for operational status and feedback only. Never swap between these groups.
439
+
440
+ | Token | Underlying ramp (light) | Use |
441
+ | ---------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- |
442
+ | `chart-gridlines` | `mountain-100` (`mountain-800` dark) | Axis grid lines |
443
+ | `chart-1-{50,100,200,300,400,450}` | `fjord-alpha-*` | Default series 1 — line/area alpha steps (50 lightest → 450 strongest) |
444
+ | `chart-2-{50…450}` | `nordic-alpha-*` | Series 2 |
445
+ | `chart-3-{50…450}` | `aurora-alpha-*` | Series 3 |
446
+ | `chart-4-{50…450}` | `dusk-alpha-*` | Series 4 |
447
+ | `chart-5-{50…450}` | `amber-alpha-*` | Series 5 |
448
+ | `chart-success-{50…450}` | `green-alpha-*` | Status-colored series (success) |
449
+ | `chart-warning-{50…450}` | `orange-alpha-*` | Status-colored series (warning) |
450
+ | `chart-critical-{50…450}` | `red-alpha-*` | Status-colored series (critical) |
451
+ | `chart-info-{50…450}` | `blue-alpha-*` | Status-colored series (info) |
452
+ | `chart-neutral-{50…450}` | `mountain-alpha-*` | Neutral / baseline series |
453
+
454
+ Default multi-series order: **chart-1 (Fjord) → chart-2 (Nordic) → chart-3 (Aurora) → chart-4 (Dusk) → chart-5 (Amber)**.
455
+
456
+ Utilities: `bg-chart-1-200`, `fill-chart-3-450`, `stroke-chart-gridlines`, etc.
457
+
458
+ ### Heat map
459
+
460
+ | Token | Light (ramp) | Dark (ramp) | Use |
461
+ | ------------------- | ------------ | ----------- | --------------- |
462
+ | `heat-map-intense` | `fjord-600` | `fjord-300` | Highest density |
463
+ | `heat-map-strong` | `fjord-450` | `fjord-450` | Strong density |
464
+ | `heat-map-moderate` | `fjord-300` | `fjord-650` | Mid density |
465
+ | `heat-map-mild` | `fjord-100` | `fjord-800` | Lowest density |
466
+
467
+ ### Shadow (elevation overlays)
468
+
469
+ | Token | Light | Dark | Use |
470
+ | ----------- | ------------------ | ------------------ | ----------------- |
471
+ | `shadow-sm` | `rgba(0,0,0,0.04)` | `rgba(0,0,0,0.2)` | Subtle elevation |
472
+ | `shadow-md` | `rgba(0,0,0,0.05)` | `rgba(0,0,0,0.3)` | Cards, popovers |
473
+ | `shadow-lg` | `rgba(0,0,0,0.06)` | `opacity-black-40` | Modals |
474
+ | `shadow-xl` | `rgba(0,0,0,0.1)` | `opacity-black-60` | Highest elevation |
475
+
476
+ Focus rings compose `ring-default` + `ring-muted` (or `ring-critical` + `ring-critical-muted` for invalid fields). See [Focus rings](#focus-rings).
477
+
478
+ ### Color ramps (step tokens)
479
+
480
+ Raw ramp steps live in `colors.css` and appear in Storybook **Color ramps**. Figma uses slash paths (`mountain/500`); CSS/Tailwind use hyphen steps (`mountain-500`, `bg-fjord-200`).
481
+
482
+ | Ramp | Role | Typical steps |
483
+ | ------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
484
+ | **Mountain** | Primary neutral (base, card, neutral status) | `10`, `50`–`950`, `550` (mid-gray), `white`, `black`, `alpha-10`, `alpha-50`–`alpha-450` |
485
+ | **Fjord** | Brand blue; chart series 1; links; heat map | `50`–`950`, `alpha-50`–`alpha-450` |
486
+ | **Nordic** | Brand teal; chart series 2; decorative slot 3 | same |
487
+ | **Aurora** | Brand green; chart series 3; decorative slot 4 | same |
488
+ | **Dusk** | Brand purple; chart series 4; decorative slot 5 | same |
489
+ | **Amber** | Brand yellow-orange; chart series 5; decorative slot 6 | same |
490
+ | **Pink** | Brand pink; decorative slot 7 | same |
491
+ | **Blue** | Info status + `chart-info-*` | same |
492
+ | **Green** | Success status + `chart-success-*` | same |
493
+ | **Red** | Critical status + `chart-critical-*` | same |
494
+ | **Orange** | Warning status + `chart-warning-*` | same |
495
+ | **Gray** | Ring muted, secondary neutrals | same |
496
+ | **Sky**, **Yellow** | Extended palette (rare in theme tokens) | same |
497
+ | **Opacity** | `opacity-black-*`, `opacity-white-*` | Overlay and shadow building blocks |
498
+
499
+ Use ramp steps only when no theme token covers the surface. Prefer theme tokens for all product UI.
500
+
501
+ ### Figma ↔ implementation discrepancies
502
+
503
+ Compared to [Figma Reflect theme tokens](https://www.figma.com/design/pMnMQvfErZDJzWgrcWCIwZ/Aura-Design-System?node-id=18097-28085) and `colors.css` (runtime source of truth):
504
+
505
+ | Item | Figma | `colors.css` / Storybook | Notes |
506
+ | -------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
507
+ | `base-foreground-contrast` | Present (`base/foreground-contrast`) | **Missing** | Not wired in CSS or `colors.stories.tsx` `THEME_TOKEN_ORDER` |
508
+ | `*-muted-background` (semantic) | Removed in Reflect | **Removed** | Legacy `info-muted-background`, `destructive-muted-background`, etc. — use `*-background` on dark chrome or `medium-*` / `popover-*-fixed-dark` |
509
+ | `destructive-*` theme names | Renamed to `critical-*` | `critical-*` | Deprecated aliases may remain in `colors-deprecated.css` until 1.0.0 |
510
+ | `*-foreground-on-*` | `*-foreground` | e.g. `info-foreground-on-info` → `info-foreground` (on `info-background`) |
511
+ | `destructive-foreground`, `info-foreground`, … (flat status on base) | `*-foreground-strong` | e.g. `destructive-foreground` → `critical-foreground-strong` |
512
+ | Path vs name | Slash paths (`border/default`, `chart/1/50`) | Hyphen tokens (`border-default`, `chart-1-50`) | Same tokens; naming convention only |
513
+ | Chart series 5 ramp | Amber in Figma/CSS | Amber (not orange) | Default series 5 maps to `amber-alpha-*`, not `orange-*` |
514
+
515
+ If you need a token that exists in Figma but not in CSS, treat it as a **design–engineering gap** until added to `colors.css`.
516
+
517
+ ### Deprecated color tokens (removed in 1.0.0)
518
+
519
+ Legacy names remain in `colors-deprecated.css` until Aura **1.0.0**. Migrate direct Tailwind usage to Reflect names:
520
+
521
+ | Pattern (deprecated) | Migrate to |
522
+ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
523
+ | `text-foreground`, `bg-background`, `border-border` | `text-base-foreground`, `bg-base-background`, `border-default` |
524
+ | `destructive-background`, `destructive-foreground-on-critical` | `critical-background`, `critical-foreground` |
525
+ | `ring-destructive`, `ring-destructive-muted` | `ring-critical`, `ring-critical-muted` |
526
+ | `bg-accent-background`, `bg-highlight-background`, `bg-active-background` | `bg-base-background-hover`, `bg-medium-background`, `bg-primary-background` (context-dependent) |
527
+ | `bg-muted-background` (legacy page fill) | `bg-muted-background` (Reflect) or `bg-medium-background` |
528
+ | `text-disabled-foreground`, `bg-disabled-background` | `text-base-foreground-disabled`, transparent + `border-disabled` |
529
+ | `bg-background-fixed-dark`, `text-foreground-fixed-dark` | `bg-popover-background-fixed-dark`, `text-popover-foreground-fixed-dark` (or category-specific `*-fixed-dark`) |
530
+ | `decorative-background-{ramp}`, `decorative-foreground-{ramp}` | `decorative-{1..7}-background`, `decorative-{1..7}-foreground` (see slot table above) |
531
+ | `chart-{ramp}-color-{n}` | `chart-{series}-{step}` (e.g. `chart-fjord-color-1` → `chart-1-50` … `chart-1-450`) |
532
+ | `opacity-{10,20,…}` utilities | Use semantic surfaces or ramp alpha steps |
533
+
534
+ Full per-token list: `colors-deprecated.css`. Badge/Avatar variant props `mountain`, `fjord`, `gray` are removed — use `decorative-1` … `decorative-7`.
412
535
 
413
536
  ---
414
537
 
@@ -444,7 +567,7 @@ Aura uses **Inter** for product UI, **Space Grotesk** for marketing display, and
444
567
 
445
568
  For pages with data-heavy layouts — cards, charts, metric tiles — work through these steps before writing component code.
446
569
 
447
- - [ ] **Tokens** — confirm all colors use semantic or chart tokens, no raw hex. Metric tiles: `decorative-*`. Data series: `chart-*`. Status: `info-*`, `success-*`, `warning-*`, `destructive-*`. See [Colors](#colors).
570
+ - [ ] **Tokens** — confirm all colors use semantic or chart tokens, no raw hex. Metric tiles: `decorative-*`. Data series: `chart-*`. Status: `info-*`, `success-*`, `warning-*`, `critical-*`. See [Colors](#colors).
448
571
  - [ ] **Layout** — use a 12-column grid with `gap-4` or `gap-6`. Tile widths: `col-span-12 sm:col-span-6 lg:col-span-3`. Cap the page frame with `max-w-[min(100%,var(--container-8xl))]`.
449
572
  - [ ] **Cards** — use the `Card` component with title, description, and a primary action. Do not stack unrelated actions in the same card. See [Layout and hierarchy](#6-layout-and-hierarchy).
450
573
  - [ ] **Loading states** — every data region must show `Shimmer` (known layout) or `Loader` (unknown layout) while fetching. See [Feedback and system status](#1-feedback-and-system-status).
@@ -465,23 +588,27 @@ Width and spacing values in this subsection follow the **`{spacing.base}`-based*
465
588
  Standard layout primitives used across all patterns:
466
589
 
467
590
  **Content max widths**
591
+
468
592
  - max-w-7xl — dashboards, full-width layouts
469
593
  - max-w-4xl — detail pages
470
594
  - max-w-2xl — forms, wizard step content
471
595
  - max-w-sm — search inputs, narrow controls
472
596
 
473
597
  **Section spacing**
598
+
474
599
  - space-y-8 — between major page sections (e.g. form groups)
475
600
  - space-y-6 — between sections within a page
476
601
  - space-y-4 — between items within a section
477
602
  - space-y-2 — between label and field, tight groupings
478
603
 
479
604
  **Grid gaps**
605
+
480
606
  - gap-6 — dashboard grids, chart grids, panel gaps
481
607
  - gap-4 — card grids, metric grids
482
608
  - gap-3 — toolbar items, button groups
483
609
 
484
610
  **Page padding**
611
+
485
612
  - px-6 py-8 — standard content area (desktop)
486
613
  - px-4 py-6 — mobile content area
487
614
  - p-4 — card/panel internal padding
@@ -490,6 +617,7 @@ Standard layout primitives used across all patterns:
490
617
  ### Layout patterns
491
618
 
492
619
  #### Sidebar content
620
+
493
621
  3+ top-level sections. Persistent navigation needed.
494
622
  Most common for multi-page apps.
495
623
 
@@ -510,9 +638,10 @@ Most common for multi-page apps.
510
638
  Desktop (1440px+): Sidebar 240px, content fills rest.
511
639
  Tablet (768px-1439px): Sidebar collapsible via hamburger.
512
640
  Mobile (below 768px): Sidebar hidden. Hamburger menu.
513
- Consider bottom nav for 3-5 primary sections.
641
+ Consider bottom nav for 3-5 primary sections.
514
642
 
515
643
  #### Full-width dashboard
644
+
516
645
  Data visualizations, metrics, monitoring. Maximum horizontal space needed.
517
646
 
518
647
  **Structure**
@@ -539,6 +668,7 @@ Tablet: 2-column grid. Charts stack.
539
668
  Mobile: Single column. Metrics as horizontal scroll.
540
669
 
541
670
  #### Form page
671
+
542
672
  Data entry, creation flows, configuration, settings with form fields.
543
673
 
544
674
  **Structure**
@@ -588,8 +718,8 @@ Desktop: Two-column (grid-cols-3, main span-2, sidebar span-1).
588
718
  Tablet: Sidebar below main content.
589
719
  Mobile: Single column. Sidebar collapses.
590
720
 
591
-
592
721
  #### Settings page
722
+
593
723
  App preferences, account settings, notification config.
594
724
 
595
725
  **Structure**
@@ -609,6 +739,7 @@ Tablet: Top tabs replacing left nav.
609
739
  Mobile: Category list → tap opens section full-screen.
610
740
 
611
741
  #### Split screen
742
+
612
743
  Comparison views, editor + preview, master-detail with equal emphasis on both sides.
613
744
 
614
745
  **Structure**
@@ -627,8 +758,8 @@ Desktop: grid-cols-2, equal columns.
627
758
  Tablet: grid-cols-2 with narrower gap.
628
759
  Mobile: Stack vertically (grid-cols-1), or use Segmented Control to switch between panels.
629
760
 
630
-
631
761
  #### Three panel
762
+
632
763
  Navigation + content + properties panel. IDE-style layouts. Complex editing workflows with context panels.
633
764
 
634
765
  **Structure**
@@ -649,8 +780,8 @@ Tablet (768-1439px): Hide right panel, toggle via button.
649
780
  Mobile (below 768px): Single panel with navigation as Drawer, right panel as bottom sheet or separate route.
650
781
 
651
782
  #### List page
652
- Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications.
653
783
 
784
+ Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications.
654
785
 
655
786
  **Structure**
656
787
 
@@ -673,8 +804,8 @@ Tablet: Hide non-essential columns, allow horizontal scroll.
673
804
  Mobile: Switch to card/list view with stackable filters.
674
805
 
675
806
  #### Wizard
676
- Multi-step creation flows, onboarding, configuration wizards, setup processes.
677
807
 
808
+ Multi-step creation flows, onboarding, configuration wizards, setup processes.
678
809
 
679
810
  **Structure**
680
811
 
@@ -716,10 +847,10 @@ Layout helpers in theme: `--container-2xl` (`{spacing.container-2xl}`), `--conta
716
847
 
717
848
  Aura adjusts Tailwind **container** breakpoints where the default scale is too wide or too narrow for data-dense product surfaces:
718
849
 
719
- | Token | Value | Role |
720
- | ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
721
- | `--container-2xl` | `{spacing.container-2xl}` | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **`{spacing.prose-max}`** reading rule above |
722
- | `--container-8xl` | `{spacing.container-8xl}` | Wide upper bound for dashboards and full-bleed marketing rows |
850
+ | Token | Value | Role |
851
+ | ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
852
+ | `--container-2xl` | `{spacing.container-2xl}` | Narrower than Tailwind’s default `2xl` container — useful outer bound for regions; **body copy** inside can still follow the **`{spacing.prose-max}`** reading rule above |
853
+ | `--container-8xl` | `{spacing.container-8xl}` | Wide upper bound for dashboards and full-bleed marketing rows |
723
854
 
724
855
  Prefer **`max-w-*`** (and other width utilities) tied to the theme over ad-hoc pixel `max-width` on wrappers. **Global frame** width (host chrome) is defined by the **host application**; **inside** the frame, combine these tokens with responsive utilities so regions reflow predictably.
725
856
 
@@ -840,8 +971,6 @@ Heights are **not** always single CSS variables; primitives use Tailwind height
840
971
 
841
972
  **Topbar** height is **application-defined** (not a single Aura token). **Table / list row** density varies by product; menu and command patterns often use **`{components.button-primary.height}`** (`h-9`) rows.
842
973
 
843
-
844
-
845
974
  ### Global primitive rules
846
975
 
847
976
  1. Prefer primitives over custom components.
@@ -855,11 +984,19 @@ Heights are **not** always single CSS variables; primitives use Tailwind height
855
984
  Sections are in alphabetical order. For each component, the Storybook link is the primary reference for variants and props; the docs link is the primary reference for usage and design guidance.
856
985
 
857
986
  #### Storybook reference
987
+
858
988
  Anytime you need to reference a component in Storybook, use the following URL and replace the slug with the component's Storybook slug: https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-{storybook-slug}--docs
859
989
 
860
- #### Docs reference
990
+ #### Docs reference
991
+
861
992
  Anytime you need to reference a component in docs, use the following URL and replace the slug with the component's doc slug: https://docs.cognite.com/aura-design-system/primitives/{docs-slug}
862
993
 
994
+ #### Component guidance files
995
+
996
+ Some components have full usage guidance in a Markdown file next to their source, linked from their section below as **Full guidance**.
997
+ These files ship in the npm package and are importable as `@cognite/aura/docs/{component}`, with a matching example gallery at `@cognite/aura/examples/{component}`.
998
+ When a component has a guidance file, treat it as the primary reference and its section below as a summary.
999
+
863
1000
  #### Accordion
864
1001
 
865
1002
  **Storybook-slug:** accordion
@@ -869,28 +1006,33 @@ Anytime you need to reference a component in docs, use the following URL and rep
869
1006
  Accordion reveals and hides grouped content sections to reduce cognitive load and page density.
870
1007
 
871
1008
  **Use when**
1009
+
872
1010
  - Grouping settings in side/config panels.
873
1011
  - Breaking long forms into manageable sections.
874
1012
  - Organizing docs/FAQ/help content.
875
1013
  - Showing nested information hierarchies.
876
1014
 
877
1015
  **Use something else when**
1016
+
878
1017
  - All content must stay visible for comparison/scanning.
879
1018
  - Content is short and easy to read without progressive disclosure.
880
1019
  - Users are making high-stakes or multi-step decisions where hidden content can cause errors.
881
1020
 
882
1021
  **Dos and don'ts**
1022
+
883
1023
  - Do use clear, specific section titles.
884
1024
  - Do keep icon and heading behavior consistent.
885
1025
  - Do not use for very short/simple content.
886
1026
  - Do not nest accordions.
887
1027
 
888
1028
  **Behavior**
1029
+
889
1030
  - Header controls expand/collapse via click/tap/Enter/Space.
890
1031
  - Support multi-expand unless product pattern requires single-expand.
891
1032
  - Keep expanded content available to assistive tech.
892
1033
 
893
1034
  **Often used with**
1035
+
894
1036
  - `Separator`, section headings, and form controls inside panel content.
895
1037
 
896
1038
  #### Action Toolbar
@@ -902,56 +1044,67 @@ Accordion reveals and hides grouped content sections to reduce cognitive load an
902
1044
  Action toolbar is a transient bottom-aligned action row that appears when users select items (for example in data-heavy views).
903
1045
 
904
1046
  **Use when**
1047
+
905
1048
  - Actions apply only to selected items.
906
1049
  - You need to reduce persistent toolbar clutter in tables/lists/cards.
907
1050
  - The workflow depends on selected state before next actions are valid.
908
1051
 
909
1052
  **Use something else when**
1053
+
910
1054
  - Actions are page-level and do not require selection first (use a standard toolbar/page actions).
911
1055
 
912
1056
  **Dos and don'ts**
1057
+
913
1058
  - Do keep actions contextual to the current selection.
914
1059
  - Do keep the set focused (use overflow when needed).
915
1060
  - Do center it in the container/page scope.
916
1061
  - Do not make it draggable.
917
1062
 
918
1063
  **Behavior**
1064
+
919
1065
  - Hidden by default; appears after selection.
920
1066
  - Anchored to bottom area; remains until selection clears, action completes, or user navigates away.
921
1067
  - If no reload occurs, it exits after action completion.
922
1068
 
923
1069
  **Often used with**
1070
+
924
1071
  - Selection patterns in data views, `Checkbox`, `Button`, `Menu`, and `Tooltip` for icon-only actions.
925
1072
 
926
1073
  #### Alert
927
1074
 
928
1075
  **Storybook-slug:** alert
929
1076
  **Docs-slug:** alert
1077
+ **Full guidance:** [alert.md](./src/components/ui/core/alert/alert.md)
930
1078
 
931
1079
  **Definition**
932
1080
  Alert communicates contextual, medium-emphasis information inside page/task flow. It is not a blocking modal.
933
1081
 
934
1082
  **Use when**
1083
+
935
1084
  - Providing inline guidance/recommendations in the current task.
936
1085
  - Calling attention to warnings/issues that need awareness but are not blocking.
937
1086
  - Offering direct actions that resolve the issue in context.
938
1087
 
939
1088
  **Dos and don'ts**
1089
+
940
1090
  - Do include action buttons only when actions are directly related to resolving/dismissing the alert.
941
1091
  - Do evaluate simpler feedback methods first (for example field-level validation).
942
1092
  - Do not attach unrelated actions.
943
1093
 
944
1094
  **Placement**
1095
+
945
1096
  - Align with surrounding content; do not pin flush against dividers.
946
1097
  - Use card style for wrapped content in constrained areas.
947
1098
  - Use strip style for short messages in wider areas.
948
1099
 
949
1100
  **Behavior**
1101
+
950
1102
  - Inline with page flow (not full-screen blocking).
951
1103
  - Dismissal removes/hides alert per variant.
952
1104
  - Action path should be clear and minimal.
953
1105
 
954
1106
  **Often used with**
1107
+
955
1108
  - `Button` for direct resolution actions.
956
1109
 
957
1110
  #### Alert Dialog
@@ -962,71 +1115,85 @@ Alert communicates contextual, medium-emphasis information inside page/task flow
962
1115
  Short, focused confirmation or acknowledgment that interrupts the user for a clear binary or limited choice.
963
1116
 
964
1117
  **Use when**
1118
+
965
1119
  - Confirming destructive or irreversible actions.
966
1120
  - Blocking until the user chooses from a small set of options.
967
1121
 
968
1122
  **Use something else when**
1123
+
969
1124
  - Inline persistence is enough (`Alert`).
970
1125
  - The flow requires a form or multi-field input (`Dialog`).
971
1126
  - A quick acknowledgment is sufficient (`Sonner Toast`).
972
1127
 
973
1128
  **Often used with**
1129
+
974
1130
  - `Button` (destructive variant) as the trigger.
975
1131
 
976
1132
  #### Avatar
977
1133
 
978
1134
  **Storybook-slug:** avatar
979
1135
  **Docs-slug:** avatar
1136
+ **Full guidance:** [avatar.md](./src/components/ui/core/avatar/avatar.md)
980
1137
 
981
1138
  **Definition**
982
1139
  Avatar visually represents a user, team, or concept and helps recognition in collaborative UI.
983
1140
 
984
1141
  **Use when**
1142
+
985
1143
  - Showing people in comments, chat, sharing, or collaborators.
986
1144
  - Representing accounts, teams, or organizations.
987
1145
  - Displaying AI/agent identities in conversational interfaces.
988
1146
 
989
1147
  **Behavior**
1148
+
990
1149
  - Choose size based on context density.
991
1150
  - Use overflow patterns for constrained spaces (for example +N with menu).
992
1151
  - Can be informational or interactive based on context.
993
1152
  - Can include status badges/dots.
994
1153
 
995
1154
  **Often used with**
1155
+
996
1156
  - `Badge`, `Tooltip`, `Menu`.
997
1157
 
998
1158
  #### Badge
999
1159
 
1000
1160
  **Storybook-slug:** badge
1001
1161
  **Docs-slug:** badge
1162
+ **Full guidance:** [badge.md](./src/components/ui/core/badge/badge.md)
1002
1163
 
1003
1164
  **Definition**
1004
1165
  Compact label for status, category, or metadata.
1005
1166
 
1006
1167
  **Use when**
1168
+
1007
1169
  - Surfacing state at a glance (for example active, draft, error).
1008
1170
  - Tagging items without taking primary focus from the page.
1009
1171
 
1010
1172
  **Use something else when**
1173
+
1011
1174
  - The message needs explanation or recovery steps (consider `Alert` or inline text).
1012
1175
  - You need a primary action (use `Button`).
1013
1176
 
1014
1177
  **Often used with**
1178
+
1015
1179
  - `Avatar`, tables and lists, filter chips.
1016
1180
 
1017
1181
  #### Banner
1018
1182
 
1019
1183
  **Storybook-slug:** banner
1020
1184
  **Docs-slug:** banner-alert
1185
+ **Full guidance:** [banner.md](./src/components/ui/core/banner/banner.md)
1021
1186
 
1022
1187
  **Definition**
1023
1188
  Persistent or dismissible message scoped at page or section level — stronger than inline helper text, broader than a single-field `Alert` in some layouts.
1024
1189
 
1025
1190
  **Use when**
1191
+
1026
1192
  - Announcing environment or product state (maintenance, trial, feature preview).
1027
1193
  - Page-wide outcomes that should stay visible while the user continues.
1028
1194
 
1029
1195
  **Use something else when**
1196
+
1030
1197
  - Task-specific guidance inside a flow (`Alert`).
1031
1198
  - Brief confirmation after an action (`Sonner Toast`).
1032
1199
 
@@ -1034,69 +1201,83 @@ Persistent or dismissible message scoped at page or section level — stronger t
1034
1201
 
1035
1202
  **Storybook-slug:** breadcrumb
1036
1203
  **Docs-slug:** breadcrumbs
1204
+ **Full guidance:** [breadcrumb.md](./src/components/ui/core/breadcrumb/breadcrumb.md)
1037
1205
 
1038
1206
  **Definition**
1039
1207
  Hierarchical navigation aid that shows users their current location within the product's structure. Location-based, not path-based.
1040
1208
 
1041
1209
  **Use when**
1210
+
1042
1211
  - Users need to return to a parent page.
1043
1212
  - Users need clarity on their current position in the product hierarchy.
1044
1213
  - Quick access to ancestor pages is useful.
1045
1214
 
1046
1215
  **Use something else when**
1216
+
1047
1217
  - The page structure is flat — there is no hierarchy to show.
1048
1218
  - Users are switching between same-level content (use `Tabs` or `Segmented Control`).
1049
1219
 
1050
1220
  **Dos and don'ts**
1221
+
1051
1222
  - Do not make the current breadcrumb clickable.
1052
1223
  - Do not pair with a back button.
1053
1224
  - Do not wrap breadcrumb labels to multiple lines; truncate and use `Tooltip` for full text.
1054
1225
  - Show only one breadcrumb trail per page.
1055
1226
 
1056
1227
  **Behavior**
1228
+
1057
1229
  - All links except the current page are interactive (Tab, Shift+Tab, Enter).
1058
1230
  - When space is limited, condense middle items into an overflow menu showing the first and last two links.
1059
1231
  - The active page link always remains visible.
1060
1232
 
1061
1233
  **Often used with**
1234
+
1062
1235
  - `Tooltip` for truncated labels, `Menu` for overflow segments, `Topbar`.
1063
1236
 
1064
1237
  #### Button
1065
1238
 
1066
1239
  **Storybook-slug:** button
1067
1240
  **Docs-slug:** button
1241
+ **Full guidance:** [button.md](./src/components/ui/core/button/button.md)
1068
1242
 
1069
1243
  **Definition**
1070
1244
  Primary control for discrete actions.
1071
1245
 
1072
1246
  **Use when**
1247
+
1073
1248
  - Committing, navigating a clear next step, or triggering destructive work (with confirmation pattern).
1074
1249
 
1075
1250
  **Dos and don'ts**
1251
+
1076
1252
  - One primary action per logical section when possible.
1077
1253
  - Match variant to risk: destructive actions use destructive variant and confirmation.
1078
1254
  - Label with verb + object (see Content guidelines in `./DESIGN.md`).
1079
1255
  - Icon-only actions need an accessible name (`aria-label`).
1080
1256
 
1081
1257
  **Often used with**
1258
+
1082
1259
  - `Button Group`, `Dialog`, forms.
1083
1260
 
1084
1261
  #### Button Group
1085
1262
 
1086
1263
  **Storybook-slug:** button-group
1264
+ **Full guidance:** [button-group.md](./src/components/ui/core/button-group/button-group.md)
1087
1265
 
1088
1266
  **Definition**
1089
1267
  Visually joins related buttons into a connected row, clarifying that the actions belong to the same context.
1090
1268
 
1091
1269
  **Use when**
1270
+
1092
1271
  - Two or more actions are closely related and operate on the same target (for example, a split-button or segmented action row).
1093
1272
  - Conserving horizontal space compared to individually spaced buttons.
1094
1273
 
1095
1274
  **Use something else when**
1275
+
1096
1276
  - Actions are unrelated and should not appear grouped.
1097
1277
  - You need more than a small set of actions (consider `Toolbar` or `Dropdown Menu`).
1098
1278
 
1099
1279
  **Often used with**
1280
+
1100
1281
  - `Button`, `Tooltip` for icon-only variants.
1101
1282
 
1102
1283
  #### Card
@@ -1108,40 +1289,48 @@ Visually joins related buttons into a connected row, clarifying that the actions
1108
1289
  A structural container with optional header, body, and footer slots for displaying data artifacts, widgets, or media. The Card with Count variant adds a numeric indicator to the header.
1109
1290
 
1110
1291
  **Use when**
1292
+
1111
1293
  - Presenting charts, visualizations, or data widgets.
1112
1294
  - Building grids of comparable items where list/grid view toggling is needed.
1113
1295
  - Displaying media content (images, videos).
1114
1296
 
1115
1297
  **Use something else when**
1298
+
1116
1299
  - You just need visual separation between sections — use `Separator` and spacing instead.
1117
1300
  - You are comparing dense metadata across rows — use `Table` or a data grid instead.
1118
1301
 
1119
1302
  **Dos and don'ts**
1303
+
1120
1304
  - Cards are structural containers only; interactive elements (`Button`, `Checkbox`) go inside the body or actions area.
1121
1305
  - Exception: the entire card can serve as a single focusable target when it acts as a link or selection item.
1122
1306
 
1123
1307
  **Often used with**
1308
+
1124
1309
  - `Button`, `Badge`, `Avatar`, `Separator`, charts, lists, or form fields in the body.
1125
1310
 
1126
1311
  #### Checkbox
1127
1312
 
1128
1313
  **Storybook-slug:** checkbox
1129
1314
  **Docs-slug:** checkbox
1315
+ **Full guidance:** [checkbox.md](./src/components/ui/core/checkbox/checkbox.md)
1130
1316
 
1131
1317
  **Definition**
1132
1318
  Enables users to independently select one or multiple options. Can appear standalone or within menus, tree views, tables, or cards.
1133
1319
 
1134
1320
  **Use when**
1321
+
1135
1322
  - Multiple independent selections are required (for example, column visibility in a table).
1136
1323
  - Enabling or disabling settings where changes do not take immediate effect.
1137
1324
  - Confirming agreement before an action (for example, delete verification).
1138
1325
 
1139
1326
  **Use something else when**
1327
+
1140
1328
  - Only one option can be selected at a time (use `Radio`).
1141
1329
  - Options are not displayed simultaneously (use `Select`).
1142
1330
  - You need an immediate on/off toggle (use `Switch`).
1143
1331
 
1144
1332
  **Dos and don'ts**
1333
+
1145
1334
  - Do provide a label for every checkbox.
1146
1335
  - Do implement indeterminate states for partial group selection.
1147
1336
  - Do not pre-select checkboxes automatically.
@@ -1149,41 +1338,49 @@ Enables users to independently select one or multiple options. Can appear standa
1149
1338
  - Do not use card variants for long option lists.
1150
1339
 
1151
1340
  **Behavior**
1341
+
1152
1342
  - Space key toggles focused checkboxes.
1153
1343
  - Indeterminate state is set programmatically, not by user interaction.
1154
1344
  - Parent-child relationships follow selection cascading rules.
1155
1345
 
1156
1346
  **Often used with**
1347
+
1157
1348
  - `Label`, helper text for groups, `Card` variant for options needing descriptions.
1158
1349
 
1159
1350
  #### Collapsible
1160
1351
 
1161
1352
  **Storybook-slug:** collapsible
1162
1353
  **Docs-slug:** collapsible
1354
+ **Full guidance:** [collapsible.md](./src/components/ui/core/collapsible/collapsible.md)
1163
1355
 
1164
1356
  **Definition**
1165
1357
  A single inline expandable block that toggles content visibility. Designed for one independent optional section, not multiple stacked areas.
1166
1358
 
1167
1359
  **Use when**
1360
+
1168
1361
  - Showing one optional or secondary block of content (for example, AI reasoning, advanced settings, a preview).
1169
1362
  - Content is useful but not essential to the primary task.
1170
1363
 
1171
1364
  **Use something else when**
1365
+
1172
1366
  - You have multiple expandable sections (use `Accordion`).
1173
1367
  - Content is essential — show it by default.
1174
1368
  - Users are navigating or filtering (use `Tabs` or filter controls).
1175
1369
 
1176
1370
  **Dos and don'ts**
1371
+
1177
1372
  - Do default to collapsed unless the collapsible content is the main purpose of the view.
1178
1373
  - Do keep the trigger label descriptive — it should communicate what's inside.
1179
1374
  - Do not nest collapsibles; use `Accordion` for layered disclosure.
1180
1375
  - Do not hide errors or required information.
1181
1376
 
1182
1377
  **Behavior**
1378
+
1183
1379
  - One trigger controls one associated region with optional animation.
1184
1380
  - State changes must be exposed to assistive technology.
1185
1381
 
1186
1382
  **Often used with**
1383
+
1187
1384
  - `Separator` when stacking multiple collapsible regions on a page.
1188
1385
 
1189
1386
  #### Combobox
@@ -1195,27 +1392,32 @@ A single inline expandable block that toggles content visibility. Designed for o
1195
1392
  A searchable select input that filters options as users type. Supports single and multi-select modes with optional ability to add new items.
1196
1393
 
1197
1394
  **Use when**
1395
+
1198
1396
  - More than approximately 12 options where search efficiency beats scrolling.
1199
1397
  - Users have a general sense of what they're looking for (country, asset name, tag).
1200
1398
  - Users need to add new options not in the predefined list.
1201
1399
 
1202
1400
  **Use something else when**
1401
+
1203
1402
  - Fewer than ~12 options: prefer `Select`, `Radio`, or `Checkbox`.
1204
1403
  - Users are unfamiliar with available options and need a visible list.
1205
1404
  - Very large datasets risk performance lag: use a data grid with filtering.
1206
1405
  - Pure text entry without selection (use `Input` or `Textarea`).
1207
1406
 
1208
1407
  **Dos and don'ts**
1408
+
1209
1409
  - Do group related options into categories.
1210
1410
  - Do position checkmarks right-aligned in menus.
1211
1411
  - Do not use for simple binary choices or small option sets.
1212
1412
  - Do not place icons or badges on the left side of menu items.
1213
1413
 
1214
1414
  **Behavior**
1415
+
1215
1416
  - Single-select closes immediately on selection.
1216
1417
  - Multi-select stays open until the user clicks outside, presses Escape, or Enter.
1217
1418
 
1218
1419
  **Often used with**
1420
+
1219
1421
  - `Label`, helper text, `Badge`.
1220
1422
 
1221
1423
  #### Command
@@ -1227,16 +1429,19 @@ A searchable select input that filters options as users type. Supports single an
1227
1429
  A keyboard-first search interface for discovering and executing actions, navigating pages, or looking up content application-wide. Typically activated via ⌘K / Ctrl+K and displayed inside a `Dialog` or `Popover`.
1228
1430
 
1229
1431
  **Use when**
1432
+
1230
1433
  - Enabling keyboard-driven workflows across an entire application.
1231
1434
  - Providing power-user shortcuts to actions and destinations.
1232
1435
  - The application has too many actions or pages to surface in a standard nav.
1233
1436
 
1234
1437
  **Use something else when**
1438
+
1235
1439
  - Filtering a specific list or dataset (use `Search`).
1236
1440
  - Selecting from known form options (use `Combobox` or `Select`).
1237
1441
  - Navigating between a small number of pages (use `Tabs` or nav links).
1238
1442
 
1239
1443
  **Dos and don'ts**
1444
+
1240
1445
  - Do organize results into logical categories.
1241
1446
  - Do use action-oriented labels ("Create asset," "Switch to dark mode").
1242
1447
  - Do display the keyboard shortcut on triggering elements.
@@ -1245,27 +1450,33 @@ A keyboard-first search interface for discovering and executing actions, navigat
1245
1450
  - Do require confirmation steps for destructive actions.
1246
1451
 
1247
1452
  **Behavior**
1453
+
1248
1454
  - Keyboard-first interface presenting categorized, scannable action lists.
1249
1455
  - Shows loading indicators for async results and meaningful empty states.
1250
1456
 
1251
1457
  **Often used with**
1458
+
1252
1459
  - `Dialog`, `Popover`, `Search`, `Empty State`.
1253
1460
 
1254
1461
  #### Count
1255
1462
 
1256
1463
  **Storybook-slug:** count
1464
+ **Full guidance:** [count.md](./src/components/ui/core/count/count.md)
1257
1465
 
1258
1466
  **Definition**
1259
1467
  A compact numeric indicator used to surface quantities inline — for example, unread messages, selected items, or totals attached to labels or tabs.
1260
1468
 
1261
1469
  **Use when**
1470
+
1262
1471
  - Showing a quantity associated with a label, tab, or list item.
1263
1472
  - Surfacing unread counts or selection totals without taking primary focus.
1264
1473
 
1265
1474
  **Use something else when**
1475
+
1266
1476
  - The value represents status or category rather than a quantity (use `Badge`).
1267
1477
 
1268
1478
  **Often used with**
1479
+
1269
1480
  - `Tabs`, `Badge`, `Label`, list items.
1270
1481
 
1271
1482
  #### Date Picker
@@ -1277,20 +1488,24 @@ A compact numeric indicator used to surface quantities inline — for example, u
1277
1488
  Allows users to select a single date through a calendar interface, ensuring proper formatting and avoiding input errors.
1278
1489
 
1279
1490
  **Use when**
1491
+
1280
1492
  - Users need to select an exact date.
1281
1493
  - Preventing manual date-formatting errors is important.
1282
1494
 
1283
1495
  **Use something else when**
1496
+
1284
1497
  - Relative dates are more appropriate ("Last week") — add shortcut options instead.
1285
1498
  - The date is fixed or recurring (consider a cron expression or plain `Input`).
1286
1499
  - Exact timing is not critical (use basic `Input`).
1287
1500
 
1288
1501
  **Behavior**
1502
+
1289
1503
  - Opens a calendar anchored to the input field.
1290
1504
  - Keyboard users can type valid values directly without using the picker.
1291
1505
  - Values commit in the configured locale format.
1292
1506
 
1293
1507
  **Often used with**
1508
+
1294
1509
  - `Label`, helper text, `Date Range Picker`.
1295
1510
 
1296
1511
  #### Date Range Picker
@@ -1302,18 +1517,22 @@ Allows users to select a single date through a calendar interface, ensuring prop
1302
1517
  Allows users to select a start and end date from a calendar interface. Used for filtering by date ranges, comparing periods, or scheduling.
1303
1518
 
1304
1519
  **Use when**
1520
+
1305
1521
  - Users need to specify a date range for filtering or reporting.
1306
1522
  - Comparing data across a period.
1307
1523
 
1308
1524
  **Use something else when**
1525
+
1309
1526
  - Only a single date is needed (use `Date Picker`).
1310
1527
  - Relative ranges like "Last 7 days" cover most use cases — add shortcut options.
1311
1528
 
1312
1529
  **Behavior**
1530
+
1313
1531
  - Enforces start/end ordering with validation messages.
1314
1532
  - Keyboard users can type valid values directly.
1315
1533
 
1316
1534
  **Often used with**
1535
+
1317
1536
  - `Label`, helper text, `Date Picker`.
1318
1537
 
1319
1538
  #### Date Time Range Picker
@@ -1325,17 +1544,21 @@ Allows users to select a start and end date from a calendar interface. Used for
1325
1544
  Allows users to select start and end date and time values. Used when precise time boundaries matter, for example scheduling or time-series filtering.
1326
1545
 
1327
1546
  **Use when**
1547
+
1328
1548
  - Users must specify both a date and time for a range (scheduling, time-series queries).
1329
1549
 
1330
1550
  **Use something else when**
1551
+
1331
1552
  - Time precision is not required (use `Date Range Picker`).
1332
1553
  - Only a single point in time is needed (use `Date Picker` or `Time Picker`).
1333
1554
 
1334
1555
  **Behavior**
1556
+
1335
1557
  - Enforces start/end ordering; validates that end is after start.
1336
1558
  - Keyboard users can type valid values directly.
1337
1559
 
1338
1560
  **Often used with**
1561
+
1339
1562
  - `Label`, helper text, `Date Range Picker`.
1340
1563
 
1341
1564
  #### Dialog
@@ -1347,14 +1570,17 @@ Allows users to select start and end date and time values. Used when precise tim
1347
1570
  Richer content surface: forms, multi-field flows, or explanations that do not fit a strip or inline pattern.
1348
1571
 
1349
1572
  **Use when**
1573
+
1350
1574
  - Collecting input or showing structured content that needs focus without leaving the page.
1351
1575
 
1352
1576
  **Use something else when**
1577
+
1353
1578
  - Inline persistence is enough (`Alert`).
1354
1579
  - Only a quick acknowledgement is needed (`Sonner Toast`).
1355
1580
  - The action is binary and destructive (use `Alert Dialog`).
1356
1581
 
1357
1582
  **Often used with**
1583
+
1358
1584
  - `Button`, `Form`, `Alert Dialog` for confirmation steps.
1359
1585
 
1360
1586
  #### Drawer
@@ -1365,9 +1591,11 @@ Richer content surface: forms, multi-field flows, or explanations that do not fi
1365
1591
  Secondary surface that slides in for filters, detail, or medium-length tasks without a full page change.
1366
1592
 
1367
1593
  **Use when**
1594
+
1368
1595
  - Supporting the main view (filters, record details, auxiliary forms).
1369
1596
 
1370
1597
  **Use something else when**
1598
+
1371
1599
  - The task needs full attention or multi-step wizard treatment (full page or `Dialog`).
1372
1600
  - Content is very short (consider `Popover` or inline).
1373
1601
 
@@ -1379,20 +1607,24 @@ Secondary surface that slides in for filters, detail, or medium-length tasks wit
1379
1607
  A button-triggered overlay listing a set of related actions or options. One of the two menu variants (the other being a context menu, which is right-click triggered). See also: `Menu`.
1380
1608
 
1381
1609
  **Use when**
1610
+
1382
1611
  - A button needs to reveal secondary or overflow actions without persistent UI.
1383
1612
  - Grouping related actions behind a single trigger to reduce visual clutter.
1384
1613
 
1385
1614
  **Use something else when**
1615
+
1386
1616
  - Options require complex selection or rich descriptions (use `Select Panel`).
1387
1617
  - Actions need user confirmation (use `Dialog` or `Alert Dialog`).
1388
1618
  - The action set is always visible and primary (use `Toolbar`).
1389
1619
 
1390
1620
  **Behavior**
1621
+
1391
1622
  - Closes after selection by default.
1392
1623
  - Positions above, below, or beside the trigger depending on viewport space.
1393
1624
  - Submenus open on hover.
1394
1625
 
1395
1626
  **Often used with**
1627
+
1396
1628
  - `Button`, `Separator`, `Badge`, checkbox toggles.
1397
1629
 
1398
1630
  #### Empty State
@@ -1404,9 +1636,11 @@ A button-triggered overlay listing a set of related actions or options. One of t
1404
1636
  Placeholder when there is no data yet or results are empty.
1405
1637
 
1406
1638
  **Use when**
1639
+
1407
1640
  - Lists, tables, charts, or artifacts have zero rows/points.
1408
1641
 
1409
1642
  **Dos and don'ts**
1643
+
1410
1644
  - Explain what will appear and how to get started.
1411
1645
  - Include a single clear CTA when creation/import applies.
1412
1646
 
@@ -1418,71 +1652,124 @@ Placeholder when there is no data yet or results are empty.
1418
1652
  A structural wrapper for form fields that manages layout, spacing, validation state propagation, and submission handling.
1419
1653
 
1420
1654
  **Use when**
1655
+
1421
1656
  - Collecting structured user input across one or more fields.
1422
1657
  - Grouping related fields with shared validation and submission logic.
1423
1658
 
1424
1659
  **Dos and don'ts**
1660
+
1425
1661
  - Do group semantically related fields together.
1426
1662
  - Do associate every field with a `Label`.
1427
1663
  - Do not use `Form` as a generic container when no submission or validation is needed.
1428
1664
 
1429
1665
  **Often used with**
1666
+
1430
1667
  - `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Label`, `Button` (submit), `Dialog`.
1431
1668
 
1432
1669
  #### Input
1433
1670
 
1434
1671
  **Storybook-slug:** input
1435
1672
  **Docs-slug:** input
1673
+ **Full guidance:** [input.md](./src/components/ui/core/input/input.md)
1436
1674
 
1437
1675
  **Definition**
1438
1676
  Single-line text field for capturing short text-based information in forms and toolbars.
1439
1677
 
1440
1678
  **Use when**
1679
+
1441
1680
  - Collecting specific text data (names, credentials, asset identifiers).
1442
1681
  - A form field requires free text that doesn't fit a structured picker.
1443
1682
 
1444
1683
  **Use something else when**
1684
+
1445
1685
  - Selecting from predefined options (use `Select`, `Combobox`, `Checkbox`, or `Radio`).
1446
1686
  - Suggestions as the user types are needed (use `Combobox`).
1447
1687
  - Selecting dates or times (use `Date Picker` / `Time Picker`).
1448
1688
  - Multi-line text is expected (use `Textarea`).
1449
1689
 
1450
1690
  **Dos and don'ts**
1691
+
1451
1692
  - Do not use long placeholder text that duplicates the label.
1452
1693
  - Do not mimic pre-filled content with placeholder text.
1453
1694
  - Do not wrap text in an input; truncate or switch to `Textarea`.
1454
1695
 
1455
1696
  **Behavior**
1697
+
1456
1698
  - Single-line only; updates as the user types.
1457
1699
  - Validation messages associate with the field for accessibility.
1458
1700
  - Supports leading (icon, prefix) and trailing (button, suffix, stepper) slots.
1459
1701
 
1460
1702
  **Often used with**
1703
+
1461
1704
  - `Label`, helper text, `Button`, `Tooltip`.
1462
1705
 
1706
+ #### Item
1707
+
1708
+ **Storybook-slug:** item
1709
+ **Docs-slug:** item
1710
+
1711
+ **Definition**
1712
+ A flexible list-row primitive for displaying a title, optional description, leading media, and trailing actions. Composes into groups for lists, trees, cards, and popovers.
1713
+
1714
+ **Use when**
1715
+
1716
+ - Building selectable or navigable rows in lists and tree views.
1717
+ - Showing a compact row with icon or avatar, title, and optional description.
1718
+ - Revealing row actions on hover or keyboard focus.
1719
+
1720
+ **Use something else when**
1721
+
1722
+ - Selecting from predefined options in a dropdown (use `Select` or `Dropdown Menu`).
1723
+ - Displaying form inputs inline (use `Field` patterns with `Checkbox`, `Radio`, or `Switch`).
1724
+ - Presenting dense tabular data across many columns (use `Table` or `DataGrid`).
1725
+
1726
+ **Dos and don'ts**
1727
+
1728
+ - Compose rows with `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, and `ItemDescription`.
1729
+ - Use `ItemActions` for hover-revealed icon buttons.
1730
+ - Place `ItemSectionHeader` as a sibling of `ItemGroup`, not inside it — `ItemGroup` renders a `<ul>`, which only accepts `<li>` children.
1731
+ - Do not use `Item` as a generic card container (use `Card`).
1732
+
1733
+ **Behavior**
1734
+
1735
+ - `ItemGroup` renders a `<ul>` and `Item` a `<li>`; place interactive elements (links, buttons) inside the row rather than replacing it.
1736
+ - Hover and keyboard focus-within apply `accent-background` unless the row is disabled; selected rows use the stronger `secondary-background`.
1737
+ - Disabled rows use `base-foreground-disabled` without opacity reduction. `disabled` is presentational — disable interactive children (buttons, links, checkboxes) yourself when the row is unavailable.
1738
+ - Row actions appear on hover and when the row receives keyboard focus.
1739
+ - Set `Avatar` `sizes` on the `Avatar` itself; `Item` and `ItemMedia` do not size media from description presence.
1740
+
1741
+ **Often used with**
1742
+
1743
+ - `Button`, `Avatar`, `Checkbox`, `Separator`, `List`, `Tree`.
1744
+
1463
1745
  #### Label
1464
1746
 
1465
1747
  **Storybook-slug:** label
1466
1748
  **Docs-slug:** label
1749
+ **Full guidance:** [label.md](./src/components/ui/core/label/label.md)
1467
1750
 
1468
1751
  **Definition**
1469
1752
  A form label that identifies and is programmatically associated with an input field. Not intended as general-purpose text.
1470
1753
 
1471
1754
  **Use when**
1755
+
1472
1756
  - Every `Input`, `Select`, `Combobox`, `Textarea`, `Checkbox` group, `Radio` group, `Switch`, `Slider`, or `Date Picker` needs one.
1473
1757
 
1474
1758
  **Use something else when**
1759
+
1475
1760
  - You need a heading or section title (use appropriate heading levels).
1476
1761
  - You need descriptive text below a field (use helper text).
1477
1762
  - You are labeling a non-interactive element like a status indicator (use plain text or `Badge`).
1478
1763
 
1479
1764
  **Dos and don'ts**
1765
+
1480
1766
  - Do associate labels with fields via `htmlFor`/`id` for accessibility.
1481
1767
  - Do mark required fields consistently (asterisk or explicit text).
1482
1768
  - Do not replace labels with placeholder text — placeholders disappear and are inaccessible.
1483
1769
  - Do not hide labels for visual cleanliness; use `Tooltip` to supplement shortened labels.
1484
1770
 
1485
1771
  **Often used with**
1772
+
1486
1773
  - `Input`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Switch`, `Slider`, `Textarea`, `Date Picker`.
1487
1774
 
1488
1775
  #### Menu
@@ -1494,24 +1781,29 @@ A form label that identifies and is programmatically associated with an input fi
1494
1781
  Presents a list of actions, options, or states for the current selection or context. Two variants: context menu (right-click/long-press trigger) and dropdown menu (button trigger). See also: `Dropdown Menu`.
1495
1782
 
1496
1783
  **Use when**
1784
+
1497
1785
  - Offering action choices from a button, select, or combobox when space is constrained.
1498
1786
  - Exposing contextual actions via right-click without dedicated trigger UI.
1499
1787
 
1500
1788
  **Use something else when**
1789
+
1501
1790
  - Options require reordering or rich descriptions (use `Select Panel`).
1502
1791
  - Actions need user confirmation before executing (use `Dialog`, `Alert Dialog`, or `Popover`).
1503
1792
 
1504
1793
  **Dos and don'ts**
1794
+
1505
1795
  - Do keep items left-aligned and styled consistently within sections.
1506
1796
  - Do separate actions into labeled sections using `Separator`.
1507
1797
  - Do not mix items with and without leading content (icons/toggles) in the same section.
1508
1798
 
1509
1799
  **Behavior**
1800
+
1510
1801
  - Closes after selection unless multi-select is enabled.
1511
1802
  - Positions above, below, left, or right of the trigger with a 4px gap, adapting to viewport space.
1512
1803
  - Submenus open on hover.
1513
1804
 
1514
1805
  **Often used with**
1806
+
1515
1807
  - `Button`, `Select`, `Combobox`, `Separator`, `Badge`, checkbox toggles.
1516
1808
 
1517
1809
  #### Pagination
@@ -1523,28 +1815,33 @@ Presents a list of actions, options, or states for the current selection or cont
1523
1815
  Divides large datasets into pages, giving users control over navigation and improving load performance.
1524
1816
 
1525
1817
  **Use when**
1818
+
1526
1819
  - Datasets are large (tables, search results, galleries).
1527
1820
  - Performance concerns rule out infinite scroll.
1528
1821
  - Users need to bookmark or return to a specific page position.
1529
1822
 
1530
1823
  **Use something else when**
1824
+
1531
1825
  - The context is a discovery feed (use infinite scroll or "Load more").
1532
1826
  - Users are completing a sequential task (use a wizard/stepper).
1533
1827
  - You need to switch between unrelated modes (use `Segmented Control` or `Tabs`).
1534
1828
 
1535
1829
  **Dos and don'ts**
1830
+
1536
1831
  - Do place pagination below content, left-aligned.
1537
1832
  - Do provide "Next" and "Previous" buttons, disabled when irrelevant.
1538
1833
  - Do include "Results per page" options for large datasets.
1539
1834
  - Do not use pagination when fewer than ~20 items per page exist.
1540
1835
 
1541
1836
  **Behavior**
1837
+
1542
1838
  - Each page should have its own shareable URL.
1543
1839
  - Content loads without full page reloads; use loaders and skeletons while data fetches.
1544
1840
  - Teleport variant allows direct page number entry.
1545
1841
  - Filters, searches, and selections persist across pages.
1546
1842
 
1547
1843
  **Often used with**
1844
+
1548
1845
  - `Table`, data grids, `Search`, `Skeleton`.
1549
1846
 
1550
1847
  #### Popover
@@ -1556,41 +1853,50 @@ Divides large datasets into pages, giving users control over navigation and impr
1556
1853
  A click-triggered panel for interactive or structured supplemental content. Stays open until dismissed.
1557
1854
 
1558
1855
  **Use when**
1856
+
1559
1857
  - User needs to pick options, fill short fields, or read formatted content on demand without leaving the page.
1560
1858
 
1561
1859
  **Use something else when**
1860
+
1562
1861
  - Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
1563
1862
  - A brief, non-interactive hint is needed (use `Tooltip`).
1564
1863
 
1565
1864
  **Often used with**
1865
+
1566
1866
  - `Button` or icon as trigger, `Command`, form controls inside the panel.
1567
1867
 
1568
1868
  #### Radio
1569
1869
 
1570
1870
  **Storybook-slug:** radio
1571
1871
  **Docs-slug:** radio
1872
+ **Full guidance:** [radio-group.md](./src/components/ui/core/radio-group/radio-group.md)
1572
1873
 
1573
1874
  **Definition**
1574
1875
  Allows users to select exactly one option from a small set of mutually exclusive choices.
1575
1876
 
1576
1877
  **Use when**
1878
+
1577
1879
  - Single selection from a small, visible set of predefined options.
1578
1880
  - All options should be visible side by side for comparison.
1579
1881
 
1580
1882
  **Use something else when**
1883
+
1581
1884
  - Multiple selections are needed (use `Checkbox`).
1582
1885
  - There are more than ~5 options or space is limited (use `Select` or `Combobox`).
1583
1886
  - The choice is binary and takes immediate effect (use `Switch`).
1584
1887
 
1585
1888
  **Dos and don'ts**
1889
+
1586
1890
  - Do pair each radio with a descriptive label.
1587
1891
  - Do not group unrelated options.
1588
1892
  - Do not exceed 5 options.
1589
1893
 
1590
1894
  **Behavior**
1895
+
1591
1896
  - Clicking or pressing Space selects the focused option and deselects others in the group.
1592
1897
 
1593
1898
  **Often used with**
1899
+
1594
1900
  - `Label`, helper text, `Card` variant for options needing supporting descriptions.
1595
1901
 
1596
1902
  #### Search
@@ -1602,16 +1908,19 @@ Allows users to select exactly one option from a small set of mutually exclusive
1602
1908
  A specialized input for locating and filtering content, with built-in search and clear affordances.
1603
1909
 
1604
1910
  **Use when**
1911
+
1605
1912
  - Lists, tables, or datasets need quick item location.
1606
1913
  - Content-heavy pages where scrolling is impractical.
1607
1914
  - Application-wide search (in conjunction with `Command`).
1608
1915
 
1609
1916
  **Use something else when**
1917
+
1610
1918
  - Selecting from predefined options (use `Combobox` or `Select`).
1611
1919
  - Multi-attribute filtering requires dedicated filter controls.
1612
1920
  - General text input unrelated to content discovery (use `Input`).
1613
1921
 
1614
1922
  **Dos and don'ts**
1923
+
1615
1924
  - Do make it clear whether search covers the current list, the page, or the whole app.
1616
1925
  - Do display a no-results state when queries return nothing.
1617
1926
  - Do debounce live search to avoid excessive requests.
@@ -1619,6 +1928,7 @@ A specialized input for locating and filtering content, with built-in search and
1619
1928
  - Do not leave empty results without explanation.
1620
1929
 
1621
1930
  **Often used with**
1931
+
1622
1932
  - `Table`, data grids, `Command`, adjacent filter controls (`Select`, `Combobox`).
1623
1933
 
1624
1934
  #### Segmented Control
@@ -1630,13 +1940,16 @@ A specialized input for locating and filtering content, with built-in search and
1630
1940
  Switches between a small number of peer views or modes on the same page.
1631
1941
 
1632
1942
  **Use when**
1943
+
1633
1944
  - Two to several comparable sections (for example overview vs details vs activity).
1634
1945
 
1635
1946
  **Use something else when**
1947
+
1636
1948
  - Content is hierarchical or lengthy and users must open multiple sections at once (consider `Accordion` or visible sections).
1637
1949
  - Navigating separate routes (tabs/sidebar patterns — see `building-pages.md`).
1638
1950
 
1639
1951
  **Relationship to Accordion**
1952
+
1640
1953
  - Segmented control swaps visibility of peer panels; accordion stacks expandable sections. Prefer segmented control when users switch modes frequently; accordion when progressive disclosure matters.
1641
1954
 
1642
1955
  #### Select
@@ -1648,11 +1961,13 @@ Switches between a small number of peer views or modes on the same page.
1648
1961
  Enables users to choose one or more predefined options from a dropdown list. Used in forms and filtering when space is constrained.
1649
1962
 
1650
1963
  **Use when**
1964
+
1651
1965
  - Multiple predefined options exist and space prevents showing them all at once.
1652
1966
  - Options are familiar and don't require explanation.
1653
1967
  - A single or multi-select form input is needed.
1654
1968
 
1655
1969
  **Use something else when**
1970
+
1656
1971
  - 12+ options or search is needed (use `Combobox`).
1657
1972
  - Few options or a binary choice (use `Checkbox`, `Radio`, or `Switch`).
1658
1973
  - User-created values are needed (use `Combobox`).
@@ -1660,86 +1975,104 @@ Enables users to choose one or more predefined options from a dropdown list. Use
1660
1975
  - Selection triggers immediate mode-switch (use `Segmented Control` or `Tabs`).
1661
1976
 
1662
1977
  **Dos and don'ts**
1978
+
1663
1979
  - Do provide a clear label and placeholder.
1664
1980
  - Do use helper text when clarification is needed.
1665
1981
  - Exercise caution with default selections — users may overlook them.
1666
1982
 
1667
1983
  **Behavior**
1984
+
1668
1985
  - Single-select closes after selection; multi-select may remain open.
1669
1986
  - Checkmarks appear right-aligned in the list.
1670
1987
 
1671
1988
  **Often used with**
1989
+
1672
1990
  - `Label`, helper text, `Button`.
1673
1991
 
1674
1992
  #### Separator
1675
1993
 
1676
1994
  **Storybook-slug:** separator
1677
1995
  **Docs-slug:** separator
1996
+ **Full guidance:** [separator.md](./src/components/ui/core/separator/separator.md)
1678
1997
 
1679
1998
  **Definition**
1680
1999
  A 1px visual divider between distinct content sections. Improves readability while remaining visually subtle.
1681
2000
 
1682
2001
  **Use when**
2002
+
1683
2003
  - Creating visual relief between related groups of content.
1684
2004
  - Dividing sections within toolbars, menus, cards, or forms.
1685
2005
 
1686
2006
  **Use something else when**
2007
+
1687
2008
  - The layout is sparse — whitespace alone is sufficient.
1688
2009
  - Sections need semantic grouping (use headings, `Card`, or background regions instead).
1689
2010
 
1690
2011
  **Dos and don'ts**
2012
+
1691
2013
  - Do use 16px vertical separators for button or horizontal form element separation.
1692
2014
  - Do not place separators between every element.
1693
2015
  - Do not use bold or colorful separators — keep them subtle.
1694
2016
  - Do not replace semantic headings or landmarks with separators.
1695
2017
 
1696
2018
  **Often used with**
2019
+
1697
2020
  - `Toolbar`, `Card` headers/footers, `Accordion`, menus, dense form sections.
1698
2021
 
1699
2022
  #### Skeleton
1700
2023
 
1701
2024
  **Storybook-slug:** skeleton
2025
+ **Full guidance:** [skeleton.md](./src/components/ui/core/skeleton/skeleton.md)
1702
2026
 
1703
2027
  **Definition**
1704
2028
  A loading placeholder that mimics the shape of incoming content, reducing perceived wait time and preventing layout shift.
1705
2029
 
1706
2030
  **Use when**
2031
+
1707
2032
  - Content is loading and the shape of the result is predictable (cards, lists, table rows).
1708
2033
  - Reducing layout shift while data fetches in the background.
1709
2034
 
1710
2035
  **Use something else when**
2036
+
1711
2037
  - The loading duration is very short (<300ms) — no loader is needed.
1712
2038
  - The content shape is unpredictable (use a spinner or progress indicator).
1713
2039
 
1714
2040
  **Dos and don'ts**
2041
+
1715
2042
  - Do match skeleton shapes to the actual content layout.
1716
2043
  - Do not animate excessively — subtle pulse is sufficient.
1717
2044
 
1718
2045
  **Often used with**
2046
+
1719
2047
  - `Card`, `Table`, `Pagination`, lists.
1720
2048
 
1721
2049
  #### Slider
1722
2050
 
1723
2051
  **Storybook-slug:** slider
1724
2052
  **Docs-slug:** slider
2053
+ **Full guidance:** [slider.md](./src/components/ui/core/slider/slider.md)
1725
2054
 
1726
2055
  **Definition**
1727
2056
  An interactive control for selecting a single value or a range from a continuous scale. Provides visual feedback and quick approximate value selection.
1728
2057
 
1729
2058
  **Use when**
2059
+
1730
2060
  - Adjusting continuous values where precision is less important than visual feedback (volume, brightness, pricing filter).
1731
2061
  - Providing immediate visual feedback (media scrubbing, live previews).
1732
2062
  - Selecting a minimum and maximum range.
1733
2063
 
1734
2064
  **Use something else when**
2065
+
1735
2066
  - Precise numeric entry is required (use `Input` or `Select`).
1736
2067
  - The choice is categorical, not continuous (use `Radio` or `Select`).
1737
2068
 
1738
2069
  **Behavior**
2070
+
1739
2071
  - Supports immediate feedback (changes apply as the user drags) and deferred feedback (changes apply on submit).
1740
2072
  - Use deferred feedback when slider adjustments trigger screen reloads or visual disruptions; pair with helper text explaining that the user must submit to apply.
1741
2073
 
1742
2074
  **Often used with**
2075
+
1743
2076
  - `Label`, helper text, optional adjacent `Input` for precise numeric entry.
1744
2077
 
1745
2078
  #### Sonner Toast
@@ -1751,37 +2084,45 @@ An interactive control for selecting a single value or a range from a continuous
1751
2084
  Lightweight, auto-dismiss feedback for outcomes that do not need a blocking surface.
1752
2085
 
1753
2086
  **Use when**
2087
+
1754
2088
  - Confirming save, delete, or background completion.
1755
2089
  - Non-critical notices the user can miss without breaking a workflow.
1756
2090
 
1757
2091
  **Use something else when**
2092
+
1758
2093
  - User must read and act before continuing (`Alert Dialog`, `Dialog`, or persistent `Alert` / `Banner`).
1759
2094
 
1760
2095
  #### Switch
1761
2096
 
1762
2097
  **Storybook-slug:** switch
1763
2098
  **Docs-slug:** switch
2099
+ **Full guidance:** [switch.md](./src/components/ui/core/switch/switch.md)
1764
2100
 
1765
2101
  **Definition**
1766
2102
  A binary toggle control that turns a setting on or off, with changes taking effect immediately.
1767
2103
 
1768
2104
  **Use when**
2105
+
1769
2106
  - Toggling a setting that takes immediate effect (for example, dark mode, notifications).
1770
2107
 
1771
2108
  **Use something else when**
2109
+
1772
2110
  - The change is form-dependent and deferred (use `Checkbox` or `Button`).
1773
2111
  - The action is one-time or destructive (use `Button`).
1774
2112
  - Multiple related toggles need grouping (use `Toggle Group`, `Checkbox`, or `Select`).
1775
2113
 
1776
2114
  **Dos and don'ts**
2115
+
1777
2116
  - Do apply a clear, descriptive label explaining the switch's function.
1778
2117
  - Do not embed switches inside `Menu` components — use menu checkmarks instead.
1779
2118
  - Do not use for destructive actions.
1780
2119
 
1781
2120
  **Behavior**
2121
+
1782
2122
  - Responds instantly to user interaction without requiring separate form submission.
1783
2123
 
1784
2124
  **Often used with**
2125
+
1785
2126
  - `Label`, helper text.
1786
2127
 
1787
2128
  #### Table
@@ -1792,13 +2133,16 @@ A binary toggle control that turns a setting on or off, with changes taking effe
1792
2133
  Dense, scannable display of rows and columns with optional selection and actions.
1793
2134
 
1794
2135
  **Use when**
2136
+
1795
2137
  - Comparing rows, scanning many attributes, or operating on multiple items.
1796
2138
 
1797
2139
  **Use something else when**
2140
+
1798
2141
  - A simple fixed list of links or single-column items (`List`).
1799
2142
  - A primary chart or narrative view (`Card`, charts — see Storybook).
1800
2143
 
1801
2144
  **Often used with**
2145
+
1802
2146
  - Selection + `Action Toolbar` (when selection-gated actions apply), `Pagination`, `Empty State`, row `Checkbox`, `Dropdown Menu` for row actions.
1803
2147
 
1804
2148
  #### Tabs
@@ -1810,16 +2154,19 @@ Dense, scannable display of rows and columns with optional selection and actions
1810
2154
  Organizes related content into switchable sections, allowing users to navigate between different views without leaving the page.
1811
2155
 
1812
2156
  **Use when**
2157
+
1813
2158
  - Organizing content into sections users switch between frequently.
1814
2159
  - Displaying related, mutually exclusive content.
1815
2160
  - Navigation within pages, dashboards, settings, or data views.
1816
2161
 
1817
2162
  **Use something else when**
2163
+
1818
2164
  - Filtering a list or dataset (use `Segmented Control`, `Button`, or `Menu`).
1819
2165
  - Multiple sections must be visible simultaneously (use `Accordion` or filters).
1820
2166
  - The choice is a binary toggle (use `Switch`).
1821
2167
 
1822
2168
  **Dos and don'ts**
2169
+
1823
2170
  - Do use a minimum of two tabs.
1824
2171
  - Do keep content above tabs stable across all tab states.
1825
2172
  - Do use leading icons consistently across all tabs or not at all.
@@ -1827,41 +2174,49 @@ Organizes related content into switchable sections, allowing users to navigate b
1827
2174
  - Do not apply to binary options.
1828
2175
 
1829
2176
  **Behavior**
2177
+
1830
2178
  - Exactly one tab panel is visible at a time.
1831
2179
  - Tab buttons manage selection state and keyboard focus.
1832
2180
  - Supports default, vertical, and full-width alignment options.
1833
2181
 
1834
2182
  **Often used with**
2183
+
1835
2184
  - `Table`, `Form`, `Card`, `Empty State`. Keep global page actions outside tab panels.
1836
2185
 
1837
2186
  #### Textarea
1838
2187
 
1839
2188
  **Storybook-slug:** textarea
1840
2189
  **Docs-slug:** textarea
2190
+ **Full guidance:** [textarea.md](./src/components/ui/core/textarea/textarea.md)
1841
2191
 
1842
2192
  **Definition**
1843
2193
  A multi-line text field for extended free-form input such as comments, feedback, messages, descriptions, or notes.
1844
2194
 
1845
2195
  **Use when**
2196
+
1846
2197
  - Multi-line text is expected (comments, notes, bios, explanations).
1847
2198
  - Editing large chunks of existing text.
1848
2199
 
1849
2200
  **Use something else when**
2201
+
1850
2202
  - A single line of text is all that is needed (use `Input`).
1851
2203
  - Structured data is expected (use masked `Input`, `Date Picker`, `Select`, or `Combobox`).
1852
2204
  - Rich formatting is needed (use a rich-text editor).
1853
2205
 
1854
2206
  **Dos and don'ts**
2207
+
1855
2208
  - Do use concise labels and placeholder text.
1856
2209
  - Do allow scroll when content exceeds the maximum height.
1857
2210
  - Do not set a small fixed height for expected lengthy input.
1858
2211
  - Do not pre-fill with default text users might overlook.
1859
2212
 
1860
2213
  **Behavior**
2214
+
1861
2215
  - Supports optional user resizing via a drag handle.
1862
2216
  - Restrict resizing when layout integrity is critical (forms in modals or sidebars) or when the textarea auto-expands programmatically.
1863
2217
 
1864
2218
  **Often used with**
2219
+
1865
2220
  - `Label`, helper text (optionally with character count).
1866
2221
 
1867
2222
  #### Time Picker
@@ -1873,36 +2228,44 @@ A multi-line text field for extended free-form input such as comments, feedback,
1873
2228
  Allows users to select a time value through a clock interface.
1874
2229
 
1875
2230
  **Use when**
2231
+
1876
2232
  - Users need to select a precise time without a date.
1877
2233
  - Scheduling tasks, alarms, or time-of-day settings.
1878
2234
 
1879
2235
  **Use something else when**
2236
+
1880
2237
  - Both date and time are required (use `Date Picker` or `Date Time Range Picker`).
1881
2238
  - Exact timing is not important (use basic `Input`).
1882
2239
 
1883
2240
  **Behavior**
2241
+
1884
2242
  - Keyboard users can type valid values directly.
1885
2243
  - Values commit in the configured locale format.
1886
2244
 
1887
2245
  **Often used with**
2246
+
1888
2247
  - `Label`, helper text, `Date Picker`.
1889
2248
 
1890
2249
  #### Toggle
1891
2250
 
1892
2251
  **Storybook-slug:** toggle
2252
+ **Full guidance:** [toggle.md](./src/components/ui/core/toggle/toggle.md)
1893
2253
 
1894
2254
  **Definition**
1895
2255
  A single pressable button with active/inactive state, used to toggle one option or formatting command on or off.
1896
2256
 
1897
2257
  **Use when**
2258
+
1898
2259
  - A single binary option needs a visible pressed/unpressed state (for example, bold text, mute).
1899
2260
 
1900
2261
  **Use something else when**
2262
+
1901
2263
  - Two or more related toggles should be grouped (use `Toggle Group`).
1902
2264
  - The change takes immediate app-level effect (use `Switch`).
1903
2265
  - The action is a one-time command (use `Button`).
1904
2266
 
1905
2267
  **Often used with**
2268
+
1906
2269
  - `Toolbar`, `Tooltip` for icon-only variants, `Toggle Group`.
1907
2270
 
1908
2271
  #### Toggle Group
@@ -1913,10 +2276,12 @@ A single pressable button with active/inactive state, used to toggle one option
1913
2276
  A set of 2–4 related toggle options for mutually exclusive or multi-select settings that are always visible.
1914
2277
 
1915
2278
  **Use when**
2279
+
1916
2280
  - Toggling between 2–4 always-visible, mutually exclusive modes (for example, grid lines, text alignment, ruler visibility).
1917
2281
  - The current selection must always be immediately clear.
1918
2282
 
1919
2283
  **Use something else when**
2284
+
1920
2285
  - More than ~4–5 options exist (use `Select` or `Menu`).
1921
2286
  - Options execute one-time commands (use `Button`).
1922
2287
  - Multi-select filtering across a larger set (use `Checkbox` or filter chips).
@@ -1924,14 +2289,17 @@ A set of 2–4 related toggle options for mutually exclusive or multi-select set
1924
2289
  - The context is page navigation (use `Tabs` or routing).
1925
2290
 
1926
2291
  **Dos and don'ts**
2292
+
1927
2293
  - Do keep labels concise — one or two words or icons only.
1928
2294
  - Do not mix icons and text labels within the same group.
1929
2295
 
1930
2296
  **Behavior**
2297
+
1931
2298
  - Selection updates instantly.
1932
2299
  - Supports single-select and multi-select configurations.
1933
2300
 
1934
2301
  **Often used with**
2302
+
1935
2303
  - `Toolbar`, `Tooltip` for icon-only variants.
1936
2304
 
1937
2305
  #### Toolbar
@@ -1942,10 +2310,12 @@ A set of 2–4 related toggle options for mutually exclusive or multi-select set
1942
2310
  Persistent strip of primary tools or filters for a page or region — available without selecting rows first.
1943
2311
 
1944
2312
  **Use when**
2313
+
1945
2314
  - Page-level create/filter/export actions.
1946
2315
  - Tools that apply to the whole view or the current query.
1947
2316
 
1948
2317
  **Use something else when**
2318
+
1949
2319
  - Actions apply only after row/item selection (use `Action Toolbar`).
1950
2320
 
1951
2321
  #### Topbar
@@ -1957,15 +2327,18 @@ Persistent strip of primary tools or filters for a page or region — available
1957
2327
  The single, persistent navigation bar at the top of every authenticated CDF and Flows custom app. Provides the primary orientation layer across three fixed regions: left (identity/breadcrumbs), middle (optional global navigation), and right (system controls).
1958
2328
 
1959
2329
  **Use when**
2330
+
1960
2331
  - Every authenticated screen in a CDF or Flows app — this component is mandatory.
1961
2332
  - The app has two or more top-level views requiring global switching.
1962
2333
  - Actions apply consistently across all app pages (for example, a persistent "Add data" button).
1963
2334
 
1964
2335
  **Use something else when**
2336
+
1965
2337
  - Login or authentication-only screens.
1966
2338
  - Full-screen flows or modals that intentionally hide global chrome.
1967
2339
 
1968
2340
  **Dos and don'ts**
2341
+
1969
2342
  - Do use the middle section for primary global app navigation.
1970
2343
  - Do use `Tabs` for distinct pages, `Segmented Control` for mode switching in the middle section.
1971
2344
  - Do not place page-specific actions in the action slot.
@@ -1973,30 +2346,36 @@ The single, persistent navigation bar at the top of every authenticated CDF and
1973
2346
  - Do not use multiple topbars per page.
1974
2347
 
1975
2348
  **Behavior**
2349
+
1976
2350
  - Left: app mark (small `Avatar`), breadcrumbs, optional inline metadata.
1977
2351
  - Middle: optional; omit for single-view apps.
1978
2352
  - Right (fixed order): Share → Notifications → Theme → Atlas.
1979
2353
 
1980
2354
  **Often used with**
2355
+
1981
2356
  - `Breadcrumb`, `Tabs`, `Segmented Control`, `Avatar`.
1982
2357
 
1983
2358
  #### Tooltip
1984
2359
 
1985
2360
  **Storybook-slug:** tooltip
1986
2361
  **Docs-slug:** tooltip
2362
+ **Full guidance:** [tooltip.md](./src/components/ui/core/tooltip/tooltip.md)
1987
2363
 
1988
2364
  **Definition**
1989
2365
  A short hint that appears on hover or focus. No heavy interaction inside.
1990
2366
 
1991
2367
  **Use when**
2368
+
1992
2369
  - Clarifying a control or icon in one line or sentence.
1993
2370
  - Providing the full text of a truncated label (for example in `Breadcrumb`).
1994
2371
 
1995
2372
  **Use something else when**
2373
+
1996
2374
  - Content is essential to the task — surface it inline or in `Dialog` / `Drawer`.
1997
2375
  - Users need to interact with the content (use `Popover`).
1998
2376
 
1999
2377
  **Often used with**
2378
+
2000
2379
  - Icon-only `Button`, `Toggle`, `Breadcrumb`, `Label`.
2001
2380
 
2002
2381
  #### Tree
@@ -2005,30 +2384,34 @@ A short hint that appears on hover or focus. No heavy interaction inside.
2005
2384
  **Docs-slug:** tree-view
2006
2385
 
2007
2386
  **Definition**
2008
- Displays hierarchical data in a nested structure with expandable/collapsible rows. Supports optional selection and drag-and-drop.
2387
+ Displays hierarchical data in a nested structure with expandable/collapsible rows. Supports optional cascading checkboxes.
2009
2388
 
2010
2389
  **Use when**
2390
+
2011
2391
  - Presenting large structures with multiple nesting levels (folders, files, organizational hierarchies).
2012
2392
  - Progressive disclosure of complex hierarchical relationships.
2013
2393
 
2014
2394
  **Use something else when**
2395
+
2015
2396
  - Data is not hierarchical (use lists or `Table`).
2016
2397
  - A sortable, tabular layout with multiple columns is needed (use `Table`).
2017
2398
  - Non-hierarchical filtering is the goal (use `Tabs` or `Segmented Control`).
2018
2399
  - Showing location in site hierarchy (use `Breadcrumb`).
2019
2400
 
2020
2401
  **Behavior**
2021
- - Nodes expand and collapse independently.
2402
+
2403
+ - Nodes expand and collapse independently via chevron; row click focuses only.
2022
2404
  - Keyboard navigation follows tree semantics (arrow keys, Home/End).
2023
- - Supports single and multi-selection.
2024
- - Optional drag-and-drop reordering (must maintain accessibility).
2405
+ - Optional checkboxes cascade to descendants; checked and indeterminate rows receive row fill.
2025
2406
 
2026
2407
  **Often used with**
2027
- - Row checkboxes, row menus, `Badge` for status, drag handles, selection highlights connecting to a side panel or `Table` in split-view layouts.
2408
+
2409
+ - Row checkboxes, row menus, `Badge` for status, checkbox highlights connecting to a side panel or `Table` in split-view layouts.
2028
2410
 
2029
2411
  ## Escalation guidance
2030
2412
 
2031
2413
  If a primitive does not fit:
2414
+
2032
2415
  1. Check Storybook variants/props first.
2033
2416
  2. Compose with existing primitives.
2034
2417
  3. If still blocked, note the gap and keep implementation consistent with Aura foundations.
@@ -2154,53 +2537,53 @@ System icons are **functional** shorthand for actions, state, and navigation. Au
2154
2537
 
2155
2538
  Action icons represent operations a user can perform that trigger a change in state, content, or system behavior. They typically appear in interactive, contextual components like buttons, toolbars, context menus, dropdown menus, and inline controls.
2156
2539
 
2157
- | Concept | Icon name | Source | Keywords / aliases | Accepted labels |
2158
- |---|---|---|---|---|
2159
- | Add / New | `plus` | [Tabler](https://tabler.io/icons?icon=plus) | create, add, new, insert | Add, Create |
2160
- | Cancel | `cancel` | [Tabler](https://tabler.io/icons?icon=cancel) | abort, stop | Cancel |
2161
- | Collapse (window) | `arrows-diagonal-minimize-2` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal-minimize-2) | exit fullscreen, collapse, minimize | Collapse |
2162
- | Copy | `copy` | [Tabler](https://tabler.io/icons?icon=copy) | duplicate, clone | Copy |
2163
- | Delete | `trash` | [Tabler](https://tabler.io/icons?icon=trash) | delete, destroy | Delete |
2164
- | Download | `download` | [Tabler](https://tabler.io/icons?icon=download) | save to file, export file | Download |
2165
- | Edit | `pencil` | [Tabler](https://tabler.io/icons?icon=pencil) | modify, rename, update | Edit |
2166
- | Expand (window) | `arrows-diagonal` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal) | fullscreen, expand, maximize | Expand |
2167
- | Filter | `filter` | [Tabler](https://tabler.io/icons?icon=filter) | narrow, refine, search filters | Filter |
2168
- | Hide | `eye-off` | [Tabler](https://tabler.io/icons?icon=eye-off) | hide; conceal, invisible, toggle visibility | Hide |
2169
- | Link | `link` | [Tabler](https://tabler.io/icons?icon=link) | hyperlink, relationship, connected | — |
2170
- | More options (menu opens above or below) | `dots-vertical` | [Tabler](https://tabler.io/icons?icon=dots-vertical) | overflow, actions, kebab menu | — |
2171
- | Notifications | `bell` | [Tabler](https://tabler.io/icons?icon=bell) | alerts, notification center | Notifications |
2172
- | Open external link | `external-link` | [Tabler](https://tabler.io/icons?icon=external-link) | open in new tab, link out | Open |
2173
- | Publish | `rocket` | [Tabler](https://tabler.io/icons?icon=rocket) | deploy, release, go live, launch | Publish |
2174
- | Redo | `arrow-forward-up` | [Tabler](https://tabler.io/icons?icon=arrow-forward-up) | step forward, redo | Redo |
2175
- | Refresh | `reload` | [Tabler](https://tabler.io/icons?icon=reload) | reload page, refresh view | Refresh |
2176
- | Remove / Close | `x` | [Tabler](https://tabler.io/icons?icon=x) | close, dismiss, remove, exit | Close, Remove |
2177
- | Save | `check` | [Tabler](https://tabler.io/icons?icon=check) | save changes, confirm, persist, write | Save |
2178
- | Search | `search` | [Tabler](https://tabler.io/icons?icon=search) | find, look up, query | Search |
2179
- | Settings | `settings` | [Tabler](https://tabler.io/icons?icon=settings) | configure, preferences, gear | Settings |
2180
- | Share | `share` | [Tabler](https://tabler.io/icons?icon=share) | send, distribute, invite | Share |
2181
- | Show | `eye` | [Tabler](https://tabler.io/icons?icon=eye) | show; reveal, visible, unhide | Show |
2182
- | Sync | `refresh` | [Tabler](https://tabler.io/icons?icon=refresh) | synchronize, pull latest, update data | Sync |
2183
- | Undo | `arrow-back-up` | [Tabler](https://tabler.io/icons?icon=arrow-back-up) | revert, undo, step back | Undo |
2184
- | Upload | `upload` | [Tabler](https://tabler.io/icons?icon=upload) | import from file, attach | Upload |
2540
+ | Concept | Icon name | Source | Keywords / aliases | Accepted labels |
2541
+ | ---------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------- | --------------- |
2542
+ | Add / New | `plus` | [Tabler](https://tabler.io/icons?icon=plus) | create, add, new, insert | Add, Create |
2543
+ | Cancel | `cancel` | [Tabler](https://tabler.io/icons?icon=cancel) | abort, stop | Cancel |
2544
+ | Collapse (window) | `arrows-diagonal-minimize-2` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal-minimize-2) | exit fullscreen, collapse, minimize | Collapse |
2545
+ | Copy | `copy` | [Tabler](https://tabler.io/icons?icon=copy) | duplicate, clone | Copy |
2546
+ | Delete | `trash` | [Tabler](https://tabler.io/icons?icon=trash) | delete, destroy | Delete |
2547
+ | Download | `download` | [Tabler](https://tabler.io/icons?icon=download) | save to file, export file | Download |
2548
+ | Edit | `pencil` | [Tabler](https://tabler.io/icons?icon=pencil) | modify, rename, update | Edit |
2549
+ | Expand (window) | `arrows-diagonal` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal) | fullscreen, expand, maximize | Expand |
2550
+ | Filter | `filter` | [Tabler](https://tabler.io/icons?icon=filter) | narrow, refine, search filters | Filter |
2551
+ | Hide | `eye-off` | [Tabler](https://tabler.io/icons?icon=eye-off) | hide; conceal, invisible, toggle visibility | Hide |
2552
+ | Link | `link` | [Tabler](https://tabler.io/icons?icon=link) | hyperlink, relationship, connected | — |
2553
+ | More options (menu opens above or below) | `dots-vertical` | [Tabler](https://tabler.io/icons?icon=dots-vertical) | overflow, actions, kebab menu | — |
2554
+ | Notifications | `bell` | [Tabler](https://tabler.io/icons?icon=bell) | alerts, notification center | Notifications |
2555
+ | Open external link | `external-link` | [Tabler](https://tabler.io/icons?icon=external-link) | open in new tab, link out | Open |
2556
+ | Publish | `rocket` | [Tabler](https://tabler.io/icons?icon=rocket) | deploy, release, go live, launch | Publish |
2557
+ | Redo | `arrow-forward-up` | [Tabler](https://tabler.io/icons?icon=arrow-forward-up) | step forward, redo | Redo |
2558
+ | Refresh | `reload` | [Tabler](https://tabler.io/icons?icon=reload) | reload page, refresh view | Refresh |
2559
+ | Remove / Close | `x` | [Tabler](https://tabler.io/icons?icon=x) | close, dismiss, remove, exit | Close, Remove |
2560
+ | Save | `check` | [Tabler](https://tabler.io/icons?icon=check) | save changes, confirm, persist, write | Save |
2561
+ | Search | `search` | [Tabler](https://tabler.io/icons?icon=search) | find, look up, query | Search |
2562
+ | Settings | `settings` | [Tabler](https://tabler.io/icons?icon=settings) | configure, preferences, gear | Settings |
2563
+ | Share | `share` | [Tabler](https://tabler.io/icons?icon=share) | send, distribute, invite | Share |
2564
+ | Show | `eye` | [Tabler](https://tabler.io/icons?icon=eye) | show; reveal, visible, unhide | Show |
2565
+ | Sync | `refresh` | [Tabler](https://tabler.io/icons?icon=refresh) | synchronize, pull latest, update data | Sync |
2566
+ | Undo | `arrow-back-up` | [Tabler](https://tabler.io/icons?icon=arrow-back-up) | revert, undo, step back | Undo |
2567
+ | Upload | `upload` | [Tabler](https://tabler.io/icons?icon=upload) | import from file, attach | Upload |
2185
2568
 
2186
2569
  **Navigation icons**
2187
2570
 
2188
2571
  Navigation icons represent spatial or positional concepts that help users understand where they are, where they can go, or how to move through an interface. They typically appear in structural, persistent components like sidebars, top bars, breadcrumbs, tabs, and pagination controls.
2189
2572
 
2190
- | Concept | Icon name | Source | Keywords / aliases | Accepted labels |
2191
- |---|---|---|---|---|
2192
- | App switcher | `grid-dots` | [Tabler](https://tabler.io/icons?icon=grid-dots) | apps, modules, switcher, launcher | — |
2193
- | Back | `arrow-left` | [Tabler](https://tabler.io/icons?icon=arrow-left) | back, go back, previous, navigate back | Back |
2194
- | Home | `home` | [Tabler](https://tabler.io/icons?icon=home) | root, dashboard, start, homepage | Home |
2195
- | Open | `chevron-down` | [Tabler](https://tabler.io/icons?icon=chevron-down) | expand, open, closed or opened state | — |
2196
- | Close | `chevron-up` | [Tabler](https://tabler.io/icons?icon=chevron-up) | collapse, close, opened state | — |
2197
- | Open, Next page | `chevron-right` | [Tabler](https://tabler.io/icons?icon=chevron-right) | expand, open, closed state, next, right | — |
2198
- | Last page, skip | `chevrons-right` | [Tabler](https://tabler.io/icons?icon=chevrons-right) | last page, pagination, skip to end | — |
2199
- | Previous page | `chevron-left` | [Tabler](https://tabler.io/icons?icon=chevron-left) | previous, left | — |
2200
- | First page, skip | `chevrons-left` | [Tabler](https://tabler.io/icons?icon=chevrons-left) | first page, pagination, skip to start | — |
2201
- | Location | `map-pin` | [Tabler](https://tabler.io/icons?icon=map-pin) | place, geographic, anchor, location, plant, site, rig, factory, warehouse | — |
2202
- | Sign in | `login-2` | [Tabler](https://tabler.io/icons?icon=login-2) | log in, authenticate, sign in | Sign in |
2203
- | Sign out | `login` | [Tabler](https://tabler.io/icons?icon=login) | log out, sign out, exit session | Sign out |
2573
+ | Concept | Icon name | Source | Keywords / aliases | Accepted labels |
2574
+ | ---------------- | ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------- |
2575
+ | App switcher | `grid-dots` | [Tabler](https://tabler.io/icons?icon=grid-dots) | apps, modules, switcher, launcher | — |
2576
+ | Back | `arrow-left` | [Tabler](https://tabler.io/icons?icon=arrow-left) | back, go back, previous, navigate back | Back |
2577
+ | Home | `home` | [Tabler](https://tabler.io/icons?icon=home) | root, dashboard, start, homepage | Home |
2578
+ | Open | `chevron-down` | [Tabler](https://tabler.io/icons?icon=chevron-down) | expand, open, closed or opened state | — |
2579
+ | Close | `chevron-up` | [Tabler](https://tabler.io/icons?icon=chevron-up) | collapse, close, opened state | — |
2580
+ | Open, Next page | `chevron-right` | [Tabler](https://tabler.io/icons?icon=chevron-right) | expand, open, closed state, next, right | — |
2581
+ | Last page, skip | `chevrons-right` | [Tabler](https://tabler.io/icons?icon=chevrons-right) | last page, pagination, skip to end | — |
2582
+ | Previous page | `chevron-left` | [Tabler](https://tabler.io/icons?icon=chevron-left) | previous, left | — |
2583
+ | First page, skip | `chevrons-left` | [Tabler](https://tabler.io/icons?icon=chevrons-left) | first page, pagination, skip to start | — |
2584
+ | Location | `map-pin` | [Tabler](https://tabler.io/icons?icon=map-pin) | place, geographic, anchor, location, plant, site, rig, factory, warehouse | — |
2585
+ | Sign in | `login-2` | [Tabler](https://tabler.io/icons?icon=login-2) | log in, authenticate, sign in | Sign in |
2586
+ | Sign out | `login` | [Tabler](https://tabler.io/icons?icon=login) | log out, sign out, exit session | Sign out |
2204
2587
 
2205
2588
  **Branded icons**
2206
2589
 
@@ -2210,14 +2593,14 @@ Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs
2210
2593
 
2211
2594
  - **Must** meet **4.5:1** contrast against the icon’s background (same bar as body text when the icon communicates meaning).
2212
2595
  - **Must** give icon-only controls an accessible name (`aria-label` / `aria-labelledby`) **and** a
2213
- **Tooltip** on hover/focus where the design hides the text label.
2596
+ **Tooltip** on hover/focus where the design hides the text label.
2214
2597
  - Icons that only repeat the meaning of adjacent visible text **should** be `aria-hidden="true"`.
2215
2598
 
2216
2599
  ### Motion (reference)
2217
2600
 
2218
2601
  #### Motion
2219
2602
 
2220
- **What this is:** the rules for **when**, **how fast**, and **how** something should move in Aura-based UIs — durations, easing curves, and which properties to animate — so engineers and agents pick consistent motion instead of inventing values per component.
2603
+ **What this is:** the rules for **when**, **how fast**, and **how** something should move in Aura-based UIs — durations, easing curves, and which properties to animate — so engineers and agents pick consistent motion instead of inventing values per component.
2221
2604
 
2222
2605
  **Motion roles**
2223
2606
 
@@ -2239,12 +2622,12 @@ Every animation plays one of two roles. Role determines how visible, fast, and e
2239
2622
 
2240
2623
  Easing is the rate of speed change — it makes motion feel physical rather than mechanical. Use `cubic-bezier` curves, not linear or default browser easing.
2241
2624
 
2242
- | Curve | cubic-bezier | Use |
2243
- | :--- | :--- | :--- |
2244
- | Standard | `(0.40, 0.00, 0.15, 1.00)` | Motion between two states — most repositioning and in-view transitions |
2245
- | Entrance | `(0.00, 0.00, 0.15, 1.00)` | Elements appearing — decelerates into place, arrives with momentum and lands softly |
2246
- | Exit | `(0.67, 0.00, 0.83, 0.83)` | Elements leaving — accelerates away, lifts off and clears the view decisively |
2247
- | Sine | `(0.33, 0.00, 0.67, 1.00)` | Near-linear; opacity fades and subtle color shifts where a strong ease would distract |
2625
+ | Curve | cubic-bezier | Use |
2626
+ | :------- | :------------------------- | :------------------------------------------------------------------------------------ |
2627
+ | Standard | `(0.40, 0.00, 0.15, 1.00)` | Motion between two states — most repositioning and in-view transitions |
2628
+ | Entrance | `(0.00, 0.00, 0.15, 1.00)` | Elements appearing — decelerates into place, arrives with momentum and lands softly |
2629
+ | Exit | `(0.67, 0.00, 0.83, 0.83)` | Elements leaving — accelerates away, lifts off and clears the view decisively |
2630
+ | Sine | `(0.33, 0.00, 0.67, 1.00)` | Near-linear; opacity fades and subtle color shifts where a strong ease would distract |
2248
2631
 
2249
2632
  - **Should** treat heavier or larger elements as slower to start and more settled on arrival; lighter, smaller elements can respond and land more quickly.
2250
2633
  - **Must not** let easings overshoot or bounce — restraint is part of the Aura feel (see **Animation anchors**, Calm).
@@ -2253,25 +2636,25 @@ Easing is the rate of speed change — it makes motion feel physical rather than
2253
2636
 
2254
2637
  Aura has no custom `duration-*`/`ease-*` theme tokens — use [Tailwind's transition utilities](https://tailwindcss.com/docs/transition-duration) directly, matching existing components (`accordion.tsx`, `tabs.tsx`, `segmented-control.tsx`):
2255
2638
 
2256
- | Concept | Tailwind utility |
2257
- | :--- | :--- |
2258
- | Duration | `duration-150` / `duration-200` / `duration-300`, or an arbitrary value like `duration-[233ms]` for values off the default scale |
2259
- | Standard / Entrance / Exit / Sine easing | Tailwind's built-in `ease-*` keywords don't match Aura's curves — use an arbitrary value, e.g. `ease-[cubic-bezier(0.40,0.00,0.15,1.00)]` |
2260
- | Which properties animate | `transition-[property-list]`, e.g. `transition-[top,left,width,height]` (see `tabs.tsx`), rather than the broader `transition-all` |
2261
- | Stagger | `delay-[Nms]` per item (arbitrary value, since Tailwind has no stagger primitive), or `[animation-delay:Nms]` when using `@keyframes` |
2262
- | Respect reduced motion | Prefix with `motion-safe:` (already used in `tabs.tsx`, `segmented-control.tsx`) so the transition is skipped for users with reduced-motion enabled |
2639
+ | Concept | Tailwind utility |
2640
+ | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
2641
+ | Duration | `duration-150` / `duration-200` / `duration-300`, or an arbitrary value like `duration-[233ms]` for values off the default scale |
2642
+ | Standard / Entrance / Exit / Sine easing | Tailwind's built-in `ease-*` keywords don't match Aura's curves — use an arbitrary value, e.g. `ease-[cubic-bezier(0.40,0.00,0.15,1.00)]` |
2643
+ | Which properties animate | `transition-[property-list]`, e.g. `transition-[top,left,width,height]` (see `tabs.tsx`), rather than the broader `transition-all` |
2644
+ | Stagger | `delay-[Nms]` per item (arbitrary value, since Tailwind has no stagger primitive), or `[animation-delay:Nms]` when using `@keyframes` |
2645
+ | Respect reduced motion | Prefix with `motion-safe:` (already used in `tabs.tsx`, `segmented-control.tsx`) so the transition is skipped for users with reduced-motion enabled |
2263
2646
 
2264
2647
  **What to animate**
2265
2648
 
2266
2649
  Every animation is built from a combination of these properties:
2267
2650
 
2268
- | Property | Use |
2269
- | :--- | :--- |
2270
- | Position | Moving elements on screen — the most common property for entrances, exits, and layout transitions |
2271
- | Scale | Growing or shrinking — drawing attention or showing hierarchy |
2272
- | Rotation | Less common in UI; adds dynamism when used with restraint |
2273
- | Opacity | Fading in/out — often paired with position or scale for softer transitions |
2274
- | Color | Shifting an element's color — state changes, hover feedback, the aurora accent language |
2651
+ | Property | Use |
2652
+ | :----------- | :----------------------------------------------------------------------------------------------------------- |
2653
+ | Position | Moving elements on screen — the most common property for entrances, exits, and layout transitions |
2654
+ | Scale | Growing or shrinking — drawing attention or showing hierarchy |
2655
+ | Rotation | Less common in UI; adds dynamism when used with restraint |
2656
+ | Opacity | Fading in/out — often paired with position or scale for softer transitions |
2657
+ | Color | Shifting an element's color — state changes, hover feedback, the aurora accent language |
2275
2658
  | Mask / morph | Revealing through a mask or transforming one shape into another — expressive moments, progressive disclosure |
2276
2659
 
2277
2660
  - **Should** combine 2–3 properties per transition (e.g. position + opacity) rather than relying on one alone.
@@ -2281,9 +2664,9 @@ Every animation is built from a combination of these properties:
2281
2664
 
2282
2665
  Three qualities every Aura animation should reinforce. Use them to test a motion design, not as literal component names.
2283
2666
 
2284
- - **Flow** — continuity. Elements arrive and leave with direction and connection; nothing jumps or teleports. Groups reveal with a natural stagger. *Test: can I follow the motion with my eyes without losing my place?*
2285
- - **Calm** — confidence in restraint. Motion never competes with the industrial data it's presenting. Easings don't overshoot, staggers don't drag, nothing bounces when it should settle. Calm does not mean slow — most motion is quiet **and** fast. *Test: does this still feel good after 8 hours of use?*
2286
- - **Tactile** — motion builds intuition. Buttons snap, panels slide from the edge they belong to, cards lift when selected — the way something moves signals what's possible before the user thinks about it. *Test: can I tell what's interactive just by how it moves?*
2667
+ - **Flow** — continuity. Elements arrive and leave with direction and connection; nothing jumps or teleports. Groups reveal with a natural stagger. _Test: can I follow the motion with my eyes without losing my place?_
2668
+ - **Calm** — confidence in restraint. Motion never competes with the industrial data it's presenting. Easings don't overshoot, staggers don't drag, nothing bounces when it should settle. Calm does not mean slow — most motion is quiet **and** fast. _Test: does this still feel good after 8 hours of use?_
2669
+ - **Tactile** — motion builds intuition. Buttons snap, panels slide from the edge they belong to, cards lift when selected — the way something moves signals what's possible before the user thinks about it. _Test: can I tell what's interactive just by how it moves?_
2287
2670
 
2288
2671
  **Reference example — anatomy of a transition**
2289
2672
 
@@ -2307,15 +2690,15 @@ These rules apply to Aura primitives, host-shell components themed with Aura tok
2307
2690
 
2308
2691
  Aura components handle many accessibility concerns automatically. Composition, copy, focus management, and page structure remain the implementer's job.
2309
2692
 
2310
- | Concern | Aura handles | You verify |
2311
- | --------------------- | --------------------------------------------------- | --------------------------------------------- |
2312
- | Focus indicators | `shadow-focus-ring` on interactive elements | Not hidden by `overflow` or `z-index` |
2313
- | Keyboard activation | Button: Enter/Space. Input: standard keys | Custom elements also respond |
2314
- | ARIA roles | Correct roles on Dialog, SegmentedControl, etc. | Custom components declare correct roles |
2315
- | Color contrast | Token pairs designed for AA compliance | Page backgrounds don't reduce contrast |
2316
- | Dark mode | Semantic tokens adapt automatically | Custom colors also work in dark mode |
2317
- | Disabled states | Communicated via `aria-disabled` | Reason for disabled is accessible |
2318
- | Focus trapping | Dialog traps focus while open | Focus returns to the trigger element on close |
2693
+ | Concern | Aura handles | You verify |
2694
+ | ------------------- | ----------------------------------------------- | --------------------------------------------- |
2695
+ | Focus indicators | `shadow-focus-ring` on interactive elements | Not hidden by `overflow` or `z-index` |
2696
+ | Keyboard activation | Button: Enter/Space. Input: standard keys | Custom elements also respond |
2697
+ | ARIA roles | Correct roles on Dialog, SegmentedControl, etc. | Custom components declare correct roles |
2698
+ | Color contrast | Token pairs designed for AA compliance | Page backgrounds don't reduce contrast |
2699
+ | Dark mode | Semantic tokens adapt automatically | Custom colors also work in dark mode |
2700
+ | Disabled states | Communicated via `aria-disabled` | Reason for disabled is accessible |
2701
+ | Focus trapping | Dialog traps focus while open | Focus returns to the trigger element on close |
2319
2702
 
2320
2703
  ---
2321
2704
 
@@ -2396,18 +2779,18 @@ Prevent errors where possible. When errors happen, users must understand what fa
2396
2779
 
2397
2780
  Not every field type needs every validation kind. Use this to scope what to implement:
2398
2781
 
2399
- | Field type | Required | Format | Length | Range | Uniqueness |
2400
- | ------------- | -------- | ------ | -------- | ------------ | ---------- |
2401
- | Text input | Yes | — | Optional | — | Optional |
2402
- | Email input | Yes | Yes | — | — | Optional |
2403
- | Password | Yes | Yes | Yes | — | — |
2404
- | Number input | Yes | — | — | Yes | — |
2405
- | Date picker | Yes | — | — | Yes | — |
2406
- | Textarea | Yes | — | Yes | — | — |
2407
- | Select | Yes | — | — | — | — |
2408
- | Combobox | Yes | — | — | — | — |
2409
- | Checkbox | — | — | — | — | — |
2410
- | File upload | Yes | Yes | — | Yes (size) | — |
2782
+ | Field type | Required | Format | Length | Range | Uniqueness |
2783
+ | ------------ | -------- | ------ | -------- | ---------- | ---------- |
2784
+ | Text input | Yes | — | Optional | — | Optional |
2785
+ | Email input | Yes | Yes | — | — | Optional |
2786
+ | Password | Yes | Yes | Yes | — | — |
2787
+ | Number input | Yes | — | — | Yes | — |
2788
+ | Date picker | Yes | — | — | Yes | — |
2789
+ | Textarea | Yes | — | Yes | — | — |
2790
+ | Select | Yes | — | — | — | — |
2791
+ | Combobox | Yes | — | — | — | — |
2792
+ | Checkbox | — | — | — | — | — |
2793
+ | File upload | Yes | Yes | — | Yes (size) | — |
2411
2794
 
2412
2795
  **Edge cases**
2413
2796
 
@@ -2460,22 +2843,22 @@ Aura targets **WCAG AA** for primitives — usage must preserve that.
2460
2843
 
2461
2844
  **Alt text and icon naming**
2462
2845
 
2463
- | Type | Approach | Example |
2464
- | ------------------------ | ---------------------------- | ------------------------------------- |
2465
- | Informational image | Describe the content | `alt="Chart: output up 20%"` |
2466
- | Decorative image | Empty | `alt=""` |
2467
- | Icon-only control | `aria-label` on the control | `aria-label="Delete report"` |
2468
- | Icon paired with a label | Hide the icon | `aria-hidden="true"` on the icon |
2846
+ | Type | Approach | Example |
2847
+ | ------------------------ | --------------------------- | -------------------------------- |
2848
+ | Informational image | Describe the content | `alt="Chart: output up 20%"` |
2849
+ | Decorative image | Empty | `alt=""` |
2850
+ | Icon-only control | `aria-label` on the control | `aria-label="Delete report"` |
2851
+ | Icon paired with a label | Hide the icon | `aria-hidden="true"` on the icon |
2469
2852
 
2470
2853
  **Announcing dynamic content**
2471
2854
 
2472
- | Scenario | Method |
2473
- | ---------------------- | --------------------------------------------- |
2474
- | Search/list results update | `aria-live="polite"` |
2475
- | Form error | `aria-live="assertive"` |
2476
- | Toast | Handled by the toast component |
2477
- | Dialog opens | Focus moves into the dialog (Aura handles) |
2478
- | Dialog closes | Return focus to the trigger element |
2855
+ | Scenario | Method |
2856
+ | -------------------------- | ------------------------------------------ |
2857
+ | Search/list results update | `aria-live="polite"` |
2858
+ | Form error | `aria-live="assertive"` |
2859
+ | Toast | Handled by the toast component |
2860
+ | Dialog opens | Focus moves into the dialog (Aura handles) |
2861
+ | Dialog closes | Return focus to the trigger element |
2479
2862
 
2480
2863
  ### Common pitfalls (agent guidance)
2481
2864
 
@@ -2583,7 +2966,7 @@ Persistent **on/off**, **selected**, **active filter**, or **applied setting** u
2583
2966
 
2584
2967
  **Guidance**
2585
2968
 
2586
- - **Must** use **`active-background`** / **`active-background-hover`** or **`active-muted-background`** / **`active-muted-background-hover`** (and matching foreground tokens such as **`foreground-on-active`**, **`active-foreground`**) — **not** semantic status colors (`info-`*, `success-`*, …) for generic toggles.
2969
+ - **Must** use **`active-background`** / **`active-background-hover`** or **`active-muted-background`** / **`active-muted-background-hover`** (and matching foreground tokens such as **`foreground-on-active`**, **`active-foreground`**) — **not** semantic status colors (`info-`_, `success-`_, …) for generic toggles.
2587
2970
  - **Must not** rely on **color alone** — combine fill with icon, checkmark, label, or border treatment where the pattern is ambiguous.
2588
2971
  - **Must** implement **hover**, **pressed**, and **focus** for the **selected** variant as well as the default variant when both exist.
2589
2972
  - **Must not** show “selected” visuals for controls that are not actually in a selected state.