@cognite/aura 0.3.5 → 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.
- package/CHANGELOG.md +274 -0
- package/DESIGN.md +664 -281
- package/LICENSE +21 -0
- package/README.md +21 -13
- package/dist/colors-deprecated.css +618 -0
- package/dist/colors.css +803 -830
- package/dist/components/index.d.ts +63 -57
- package/dist/components/index.js +62 -59
- package/dist/components/index.js.map +1 -0
- package/dist/components/ui/core/accordion/accordion.d.ts +19 -18
- package/dist/components/ui/core/accordion/accordion.js +99 -78
- package/dist/components/ui/core/accordion/accordion.js.map +1 -0
- package/dist/components/ui/core/action-toolbar/action-toolbar-motion.d.ts +8 -0
- package/dist/components/ui/core/action-toolbar/action-toolbar-motion.js +132 -0
- package/dist/components/ui/core/action-toolbar/action-toolbar-motion.js.map +1 -0
- package/dist/components/ui/core/action-toolbar/action-toolbar.d.ts +31 -31
- package/dist/components/ui/core/action-toolbar/action-toolbar.js +156 -106
- package/dist/components/ui/core/action-toolbar/action-toolbar.js.map +1 -0
- package/dist/components/ui/core/alert/alert.d.ts +25 -25
- package/dist/components/ui/core/alert/alert.gallery.d.ts +2 -0
- package/dist/components/ui/core/alert/alert.gallery.js +54 -0
- package/dist/components/ui/core/alert/alert.gallery.js.map +1 -0
- package/dist/components/ui/core/alert/alert.js +181 -152
- package/dist/components/ui/core/alert/alert.js.map +1 -0
- package/dist/components/ui/core/avatar/avatar.d.ts +10 -9
- package/dist/components/ui/core/avatar/avatar.gallery.d.ts +2 -0
- package/dist/components/ui/core/avatar/avatar.gallery.js +67 -0
- package/dist/components/ui/core/avatar/avatar.gallery.js.map +1 -0
- package/dist/components/ui/core/avatar/avatar.js +75 -65
- package/dist/components/ui/core/avatar/avatar.js.map +1 -0
- package/dist/components/ui/core/badge/badge.d.ts +13 -12
- package/dist/components/ui/core/badge/badge.gallery.d.ts +2 -0
- package/dist/components/ui/core/badge/badge.gallery.js +64 -0
- package/dist/components/ui/core/badge/badge.gallery.js.map +1 -0
- package/dist/components/ui/core/badge/badge.js +88 -72
- package/dist/components/ui/core/badge/badge.js.map +1 -0
- package/dist/components/ui/core/banner/banner.d.ts +18 -18
- package/dist/components/ui/core/banner/banner.gallery.d.ts +2 -0
- package/dist/components/ui/core/banner/banner.gallery.js +56 -0
- package/dist/components/ui/core/banner/banner.gallery.js.map +1 -0
- package/dist/components/ui/core/banner/banner.js +179 -142
- package/dist/components/ui/core/banner/banner.js.map +1 -0
- package/dist/components/ui/core/breadcrumb/breadcrumb.d.ts +12 -12
- package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.d.ts +2 -0
- package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.js +31 -0
- package/dist/components/ui/core/breadcrumb/breadcrumb.gallery.js.map +1 -0
- package/dist/components/ui/core/breadcrumb/breadcrumb.js +139 -104
- package/dist/components/ui/core/breadcrumb/breadcrumb.js.map +1 -0
- package/dist/components/ui/core/button/button.d.ts +7 -7
- package/dist/components/ui/core/button/button.gallery.d.ts +2 -0
- package/dist/components/ui/core/button/button.gallery.js +76 -0
- package/dist/components/ui/core/button/button.gallery.js.map +1 -0
- package/dist/components/ui/core/button/button.js +57 -47
- package/dist/components/ui/core/button/button.js.map +1 -0
- package/dist/components/ui/core/button-group/button-group.d.ts +9 -9
- package/dist/components/ui/core/button-group/button-group.gallery.d.ts +2 -0
- package/dist/components/ui/core/button-group/button-group.gallery.js +62 -0
- package/dist/components/ui/core/button-group/button-group.gallery.js.map +1 -0
- package/dist/components/ui/core/button-group/button-group.js +50 -40
- package/dist/components/ui/core/button-group/button-group.js.map +1 -0
- package/dist/components/ui/core/calendar/calendar-header.d.ts +7 -7
- package/dist/components/ui/core/calendar/calendar-header.js +102 -63
- package/dist/components/ui/core/calendar/calendar-header.js.map +1 -0
- package/dist/components/ui/core/calendar/calendar-utils.d.ts +30 -30
- package/dist/components/ui/core/calendar/calendar-utils.js +116 -39
- package/dist/components/ui/core/calendar/calendar-utils.js.map +1 -0
- package/dist/components/ui/core/calendar/calendar.d.ts +10 -10
- package/dist/components/ui/core/calendar/calendar.js +95 -66
- package/dist/components/ui/core/calendar/calendar.js.map +1 -0
- package/dist/components/ui/core/calendar/constants.js +3 -0
- package/dist/components/ui/core/calendar/constants.js.map +1 -0
- package/dist/components/ui/core/card/card.d.ts +20 -20
- package/dist/components/ui/core/card/card.js +133 -104
- package/dist/components/ui/core/card/card.js.map +1 -0
- package/dist/components/ui/core/chart/chart.d.ts +55 -53
- package/dist/components/ui/core/chart/chart.js +196 -116
- package/dist/components/ui/core/chart/chart.js.map +1 -0
- package/dist/components/ui/core/chart/index.d.ts +2 -2
- package/dist/components/ui/core/chart/index.js +3 -2
- package/dist/components/ui/core/chart/index.js.map +1 -0
- package/dist/components/ui/core/checkbox/checkbox.d.ts +9 -9
- package/dist/components/ui/core/checkbox/checkbox.gallery.d.ts +2 -0
- package/dist/components/ui/core/checkbox/checkbox.gallery.js +36 -0
- package/dist/components/ui/core/checkbox/checkbox.gallery.js.map +1 -0
- package/dist/components/ui/core/checkbox/checkbox.js +88 -68
- package/dist/components/ui/core/checkbox/checkbox.js.map +1 -0
- package/dist/components/ui/core/checkbox/checkbox.metadata.d.ts +1 -1
- package/dist/components/ui/core/checkbox/checkbox.metadata.js +6 -7
- package/dist/components/ui/core/checkbox/checkbox.metadata.js.map +1 -0
- package/dist/components/ui/core/code-block/code-block.d.ts +19 -19
- package/dist/components/ui/core/code-block/code-block.js +260 -175
- package/dist/components/ui/core/code-block/code-block.js.map +1 -0
- package/dist/components/ui/core/collapsible/collapsible.d.ts +5 -5
- package/dist/components/ui/core/collapsible/collapsible.gallery.d.ts +2 -0
- package/dist/components/ui/core/collapsible/collapsible.gallery.js +39 -0
- package/dist/components/ui/core/collapsible/collapsible.gallery.js.map +1 -0
- package/dist/components/ui/core/collapsible/collapsible.js +36 -30
- package/dist/components/ui/core/collapsible/collapsible.js.map +1 -0
- package/dist/components/ui/core/combobox/combobox.d.ts +13 -13
- package/dist/components/ui/core/combobox/combobox.js +89 -40
- package/dist/components/ui/core/combobox/combobox.js.map +1 -0
- package/dist/components/ui/core/command/command.d.ts +20 -18
- package/dist/components/ui/core/command/command.js +137 -85
- package/dist/components/ui/core/command/command.js.map +1 -0
- package/dist/components/ui/core/conversation/conversation.d.ts +14 -0
- package/dist/components/ui/core/conversation/conversation.js +51 -0
- package/dist/components/ui/core/conversation/conversation.js.map +1 -0
- package/dist/components/ui/core/count/count.d.ts +8 -6
- package/dist/components/ui/core/count/count.gallery.d.ts +2 -0
- package/dist/components/ui/core/count/count.gallery.js +55 -0
- package/dist/components/ui/core/count/count.gallery.js.map +1 -0
- package/dist/components/ui/core/count/count.js +51 -21
- package/dist/components/ui/core/count/count.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-cell.d.ts +5 -7
- package/dist/components/ui/core/data-grid/data-grid-cell.js +18 -22
- package/dist/components/ui/core/data-grid/data-grid-cell.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-column-filter.d.ts +4 -0
- package/dist/components/ui/core/data-grid/data-grid-column-filter.js +13 -0
- package/dist/components/ui/core/data-grid/data-grid-column-filter.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-column-resizer.d.ts +8 -0
- package/dist/components/ui/core/data-grid/data-grid-column-resizer.js +25 -0
- package/dist/components/ui/core/data-grid/data-grid-column-resizer.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-clauses.d.ts +14 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-clauses.js +36 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-clauses.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-panel.d.ts +43 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-panel.js +287 -0
- package/dist/components/ui/core/data-grid/data-grid-filter-panel.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-footer.d.ts +6 -0
- package/dist/components/ui/core/data-grid/data-grid-footer.js +34 -0
- package/dist/components/ui/core/data-grid/data-grid-footer.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-header-row.d.ts +10 -10
- package/dist/components/ui/core/data-grid/data-grid-header-row.js +85 -55
- package/dist/components/ui/core/data-grid/data-grid-header-row.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-header.d.ts +11 -0
- package/dist/components/ui/core/data-grid/data-grid-header.js +67 -0
- package/dist/components/ui/core/data-grid/data-grid-header.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-row.d.ts +13 -15
- package/dist/components/ui/core/data-grid/data-grid-row.js +117 -76
- package/dist/components/ui/core/data-grid/data-grid-row.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-state.d.ts +15 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-state.js +32 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-state.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.d.ts +11 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.js +129 -0
- package/dist/components/ui/core/data-grid/data-grid-selection-toolbar.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid-selection.types.d.ts +24 -0
- package/dist/components/ui/core/data-grid/data-grid-selection.types.js +3 -0
- package/dist/components/ui/core/data-grid/data-grid-selection.types.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid.d.ts +125 -35
- package/dist/components/ui/core/data-grid/data-grid.fixtures.d.ts +7 -7
- package/dist/components/ui/core/data-grid/data-grid.fixtures.js +139 -0
- package/dist/components/ui/core/data-grid/data-grid.fixtures.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid.js +540 -132
- package/dist/components/ui/core/data-grid/data-grid.js.map +1 -0
- package/dist/components/ui/core/data-grid/data-grid.utils.d.ts +3 -4
- package/dist/components/ui/core/data-grid/data-grid.utils.js +46 -33
- package/dist/components/ui/core/data-grid/data-grid.utils.js.map +1 -0
- package/dist/components/ui/core/data-grid/index.d.ts +6 -1
- package/dist/components/ui/core/data-grid/index.js +6 -2
- package/dist/components/ui/core/data-grid/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.d.ts +11 -13
- package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.js +85 -61
- package/dist/components/ui/core/date-time-pickers/date-picker/date-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/index.d.ts +3 -3
- package/dist/components/ui/core/date-time-pickers/date-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/types.d.ts +14 -14
- package/dist/components/ui/core/date-time-pickers/date-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.d.ts +2 -2
- package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.js +51 -36
- package/dist/components/ui/core/date-time-pickers/date-picker/use-date-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.d.ts +11 -13
- package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.js +89 -64
- package/dist/components/ui/core/date-time-pickers/date-range-picker/date-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/index.d.ts +3 -3
- package/dist/components/ui/core/date-time-pickers/date-range-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/types.d.ts +20 -20
- package/dist/components/ui/core/date-time-pickers/date-range-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.d.ts +4 -4
- package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.js +95 -60
- package/dist/components/ui/core/date-time-pickers/date-range-picker/use-date-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.d.ts +15 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.js +120 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/date-time-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/index.d.ts +3 -1
- package/dist/components/ui/core/date-time-pickers/date-time-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/types.d.ts +25 -32
- package/dist/components/ui/core/date-time-pickers/date-time-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.d.ts +2 -2
- package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.js +78 -0
- package/dist/components/ui/core/date-time-pickers/date-time-picker/use-date-time-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.d.ts +13 -15
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.js +165 -119
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/date-time-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.d.ts +3 -3
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.d.ts +37 -37
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.d.ts +3 -3
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.js +163 -104
- package/dist/components/ui/core/date-time-pickers/date-time-range-picker/use-date-time-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/index.d.ts +17 -12
- package/dist/components/ui/core/date-time-pickers/index.js +10 -6
- package/dist/components/ui/core/date-time-pickers/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.d.ts +5 -5
- package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.js +52 -42
- package/dist/components/ui/core/date-time-pickers/shared/am-pm-scroll/am-pm-scroll.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/constants.d.ts +6 -1
- package/dist/components/ui/core/date-time-pickers/shared/constants.js +23 -0
- package/dist/components/ui/core/date-time-pickers/shared/constants.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.d.ts +16 -15
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.js +87 -64
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/date-time-input.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.d.ts +10 -9
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.js +89 -38
- package/dist/components/ui/core/date-time-pickers/shared/date-time-input/range-input-display.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.d.ts +5 -5
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.js +34 -23
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-popover-state.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.d.ts +23 -23
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.js +95 -52
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-date-state.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.d.ts +5 -5
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.js +22 -18
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-range-step-manager.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.d.ts +19 -19
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.js +41 -24
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-single-date-state.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.d.ts +13 -13
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.js +33 -24
- package/dist/components/ui/core/date-time-pickers/shared/hooks/use-time-state.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.d.ts +5 -5
- package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.js +9 -4
- package/dist/components/ui/core/date-time-pickers/shared/scroll-cell-classes.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.d.ts +13 -9
- package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.js +22 -17
- package/dist/components/ui/core/date-time-pickers/shared/shortcuts-panel/shortcuts-panel.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.d.ts +2 -2
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.d.ts +13 -13
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.js +49 -40
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-panel/time-picker-panel.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.d.ts +7 -7
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.js +41 -34
- package/dist/components/ui/core/date-time-pickers/shared/time-picker-scroll/time-picker-scroll.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/index.d.ts +3 -3
- package/dist/components/ui/core/date-time-pickers/time-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.d.ts +12 -14
- package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.js +99 -79
- package/dist/components/ui/core/date-time-pickers/time-picker/time-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/types.d.ts +20 -20
- package/dist/components/ui/core/date-time-pickers/time-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.d.ts +2 -2
- package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.js +63 -41
- package/dist/components/ui/core/date-time-pickers/time-picker/use-time-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/index.d.ts +3 -1
- package/dist/components/ui/core/date-time-pickers/time-range-picker/index.js +3 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/index.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.d.ts +14 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.js +115 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/time-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/types.d.ts +30 -36
- package/dist/components/ui/core/date-time-pickers/time-range-picker/types.js +3 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/types.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.d.ts +2 -2
- package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.js +145 -0
- package/dist/components/ui/core/date-time-pickers/time-range-picker/use-time-range-picker.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/date-input.d.ts +56 -0
- package/dist/components/ui/core/date-time-pickers/utils/date-input.js +67 -0
- package/dist/components/ui/core/date-time-pickers/utils/date-input.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.d.ts +18 -18
- package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.js +42 -0
- package/dist/components/ui/core/date-time-pickers/utils/date-range-utils.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/format-utils.d.ts +31 -29
- package/dist/components/ui/core/date-time-pickers/utils/format-utils.js +56 -0
- package/dist/components/ui/core/date-time-pickers/utils/format-utils.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/segment-utils.d.ts +21 -21
- package/dist/components/ui/core/date-time-pickers/utils/segment-utils.js +170 -0
- package/dist/components/ui/core/date-time-pickers/utils/segment-utils.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/time-utils.d.ts +28 -28
- package/dist/components/ui/core/date-time-pickers/utils/time-utils.js +88 -7
- package/dist/components/ui/core/date-time-pickers/utils/time-utils.js.map +1 -0
- package/dist/components/ui/core/date-time-pickers/utils/time-validation.d.ts +17 -17
- package/dist/components/ui/core/date-time-pickers/utils/time-validation.js +43 -0
- package/dist/components/ui/core/date-time-pickers/utils/time-validation.js.map +1 -0
- package/dist/components/ui/core/dialog/dialog.d.ts +12 -9
- package/dist/components/ui/core/dialog/dialog.js +90 -82
- package/dist/components/ui/core/dialog/dialog.js.map +1 -0
- package/dist/components/ui/core/dropdown-menu/dropdown-menu.d.ts +22 -19
- package/dist/components/ui/core/dropdown-menu/dropdown-menu.js +204 -149
- package/dist/components/ui/core/dropdown-menu/dropdown-menu.js.map +1 -0
- package/dist/components/ui/core/empty-state/empty-state.context.d.ts +4 -4
- package/dist/components/ui/core/empty-state/empty-state.context.js +8 -5
- package/dist/components/ui/core/empty-state/empty-state.context.js.map +1 -0
- package/dist/components/ui/core/empty-state/empty-state.d.ts +14 -14
- package/dist/components/ui/core/empty-state/empty-state.js +96 -82
- package/dist/components/ui/core/empty-state/empty-state.js.map +1 -0
- package/dist/components/ui/core/helper-text/helper-text.d.ts +7 -7
- package/dist/components/ui/core/helper-text/helper-text.js +55 -36
- package/dist/components/ui/core/helper-text/helper-text.js.map +1 -0
- package/dist/components/ui/core/hover-card/hover-card.d.ts +7 -6
- package/dist/components/ui/core/hover-card/hover-card.js +56 -52
- package/dist/components/ui/core/hover-card/hover-card.js.map +1 -0
- package/dist/components/ui/core/inline-citation/inline-citation.d.ts +26 -25
- package/dist/components/ui/core/inline-citation/inline-citation.js +121 -97
- package/dist/components/ui/core/inline-citation/inline-citation.js.map +1 -0
- package/dist/components/ui/core/input/input.d.ts +2 -2
- package/dist/components/ui/core/input/input.gallery.d.ts +2 -0
- package/dist/components/ui/core/input/input.gallery.js +89 -0
- package/dist/components/ui/core/input/input.gallery.js.map +1 -0
- package/dist/components/ui/core/input/input.js +15 -13
- package/dist/components/ui/core/input/input.js.map +1 -0
- package/dist/components/ui/core/input-group/input-group.d.ts +25 -14
- package/dist/components/ui/core/input-group/input-group.js +149 -76
- package/dist/components/ui/core/input-group/input-group.js.map +1 -0
- package/dist/components/ui/core/item/item.d.ts +20 -0
- package/dist/components/ui/core/item/item.js +93 -0
- package/dist/components/ui/core/item/item.js.map +1 -0
- package/dist/components/ui/core/kbd/kbd.d.ts +3 -3
- package/dist/components/ui/core/kbd/kbd.js +24 -20
- package/dist/components/ui/core/kbd/kbd.js.map +1 -0
- package/dist/components/ui/core/label/label.d.ts +3 -3
- package/dist/components/ui/core/label/label.gallery.d.ts +2 -0
- package/dist/components/ui/core/label/label.gallery.js +57 -0
- package/dist/components/ui/core/label/label.gallery.js.map +1 -0
- package/dist/components/ui/core/label/label.js +33 -26
- package/dist/components/ui/core/label/label.js.map +1 -0
- package/dist/components/ui/core/loader/loader.d.ts +6 -6
- package/dist/components/ui/core/loader/loader.js +97 -80
- package/dist/components/ui/core/loader/loader.js.map +1 -0
- package/dist/components/ui/core/message/message-response-default-streamdown-controls.d.ts +8 -9
- package/dist/components/ui/core/message/message-response-default-streamdown-controls.js +18 -12
- package/dist/components/ui/core/message/message-response-default-streamdown-controls.js.map +1 -0
- package/dist/components/ui/core/message/message-response-math-plugin.d.ts +3 -0
- package/dist/components/ui/core/message/message-response-math-plugin.js +6 -0
- package/dist/components/ui/core/message/message-response-math-plugin.js.map +1 -0
- package/dist/components/ui/core/message/message.d.ts +27 -23
- package/dist/components/ui/core/message/message.js +458 -316
- package/dist/components/ui/core/message/message.js.map +1 -0
- package/dist/components/ui/core/overflow-list/overflow-list.d.ts +21 -0
- package/dist/components/ui/core/overflow-list/overflow-list.js +197 -0
- package/dist/components/ui/core/overflow-list/overflow-list.js.map +1 -0
- package/dist/components/ui/core/overflow-list/overflow-list.utils.d.ts +37 -35
- package/dist/components/ui/core/overflow-list/overflow-list.utils.js +206 -0
- package/dist/components/ui/core/overflow-list/overflow-list.utils.js.map +1 -0
- package/dist/components/ui/core/pagination/pagination-size-context.d.ts +2 -2
- package/dist/components/ui/core/pagination/pagination-size-context.js +6 -5
- package/dist/components/ui/core/pagination/pagination-size-context.js.map +1 -0
- package/dist/components/ui/core/pagination/pagination-teleport.d.ts +9 -9
- package/dist/components/ui/core/pagination/pagination-teleport.js +127 -84
- package/dist/components/ui/core/pagination/pagination-teleport.js.map +1 -0
- package/dist/components/ui/core/pagination/pagination-teleport.utils.js +6 -6
- package/dist/components/ui/core/pagination/pagination-teleport.utils.js.map +1 -0
- package/dist/components/ui/core/pagination/pagination.d.ts +39 -39
- package/dist/components/ui/core/pagination/pagination.js +294 -234
- package/dist/components/ui/core/pagination/pagination.js.map +1 -0
- package/dist/components/ui/core/popover/popover.d.ts +12 -11
- package/dist/components/ui/core/popover/popover.js +104 -89
- package/dist/components/ui/core/popover/popover.js.map +1 -0
- package/dist/components/ui/core/progress/progress.d.ts +9 -8
- package/dist/components/ui/core/progress/progress.js +50 -35
- package/dist/components/ui/core/progress/progress.js.map +1 -0
- package/dist/components/ui/core/prompt-input/prompt-input.d.ts +27 -27
- package/dist/components/ui/core/prompt-input/prompt-input.js +342 -271
- package/dist/components/ui/core/prompt-input/prompt-input.js.map +1 -0
- package/dist/components/ui/core/radio-group/radio-group.d.ts +12 -12
- package/dist/components/ui/core/radio-group/radio-group.gallery.d.ts +2 -0
- package/dist/components/ui/core/radio-group/radio-group.gallery.js +44 -0
- package/dist/components/ui/core/radio-group/radio-group.gallery.js.map +1 -0
- package/dist/components/ui/core/radio-group/radio-group.js +88 -58
- package/dist/components/ui/core/radio-group/radio-group.js.map +1 -0
- package/dist/components/ui/core/reasoning/reasoning.d.ts +7 -7
- package/dist/components/ui/core/reasoning/reasoning.js +68 -56
- package/dist/components/ui/core/reasoning/reasoning.js.map +1 -0
- package/dist/components/ui/core/scroll-area/scroll-area.d.ts +4 -4
- package/dist/components/ui/core/scroll-area/scroll-area.js +50 -40
- package/dist/components/ui/core/scroll-area/scroll-area.js.map +1 -0
- package/dist/components/ui/core/search/search.d.ts +8 -8
- package/dist/components/ui/core/search/search.js +122 -76
- package/dist/components/ui/core/search/search.js.map +1 -0
- package/dist/components/ui/core/segmented-control/segmented-control.d.ts +10 -10
- package/dist/components/ui/core/segmented-control/segmented-control.js +203 -149
- package/dist/components/ui/core/segmented-control/segmented-control.js.map +1 -0
- package/dist/components/ui/core/select/select.d.ts +33 -26
- package/dist/components/ui/core/select/select.js +262 -168
- package/dist/components/ui/core/select/select.js.map +1 -0
- package/dist/components/ui/core/separator/separator.d.ts +2 -2
- package/dist/components/ui/core/separator/separator.gallery.d.ts +2 -0
- package/dist/components/ui/core/separator/separator.gallery.js +63 -0
- package/dist/components/ui/core/separator/separator.gallery.js.map +1 -0
- package/dist/components/ui/core/separator/separator.js +13 -13
- package/dist/components/ui/core/separator/separator.js.map +1 -0
- package/dist/components/ui/core/shimmer/shimmer.d.ts +8 -8
- package/dist/components/ui/core/shimmer/shimmer.js +64 -40
- package/dist/components/ui/core/shimmer/shimmer.js.map +1 -0
- package/dist/components/ui/core/skeleton/skeleton.d.ts +2 -2
- package/dist/components/ui/core/skeleton/skeleton.gallery.d.ts +2 -0
- package/dist/components/ui/core/skeleton/skeleton.gallery.js +22 -0
- package/dist/components/ui/core/skeleton/skeleton.gallery.js.map +1 -0
- package/dist/components/ui/core/skeleton/skeleton.js +13 -13
- package/dist/components/ui/core/skeleton/skeleton.js.map +1 -0
- package/dist/components/ui/core/slider/slider.d.ts +7 -7
- package/dist/components/ui/core/slider/slider.gallery.d.ts +2 -0
- package/dist/components/ui/core/slider/slider.gallery.js +62 -0
- package/dist/components/ui/core/slider/slider.gallery.js.map +1 -0
- package/dist/components/ui/core/slider/slider.js +51 -39
- package/dist/components/ui/core/slider/slider.js.map +1 -0
- package/dist/components/ui/core/sonner-toast/sonner-toast.d.ts +2 -2
- package/dist/components/ui/core/sonner-toast/sonner-toast.js +67 -54
- package/dist/components/ui/core/sonner-toast/sonner-toast.js.map +1 -0
- package/dist/components/ui/core/sources/sources.d.ts +12 -12
- package/dist/components/ui/core/sources/sources.js +87 -58
- package/dist/components/ui/core/sources/sources.js.map +1 -0
- package/dist/components/ui/core/status-text/status-text.d.ts +4 -0
- package/dist/components/ui/core/status-text/status-text.js +14 -0
- package/dist/components/ui/core/status-text/status-text.js.map +1 -0
- package/dist/components/ui/core/switch/switch.d.ts +9 -9
- package/dist/components/ui/core/switch/switch.gallery.d.ts +2 -0
- package/dist/components/ui/core/switch/switch.gallery.js +67 -0
- package/dist/components/ui/core/switch/switch.gallery.js.map +1 -0
- package/dist/components/ui/core/switch/switch.js +83 -61
- package/dist/components/ui/core/switch/switch.js.map +1 -0
- package/dist/components/ui/core/switch/switch.metadata.d.ts +1 -1
- package/dist/components/ui/core/switch/switch.metadata.js +8 -0
- package/dist/components/ui/core/switch/switch.metadata.js.map +1 -0
- package/dist/components/ui/core/tabs/tabs.d.ts +20 -18
- package/dist/components/ui/core/tabs/tabs.js +176 -147
- package/dist/components/ui/core/tabs/tabs.js.map +1 -0
- package/dist/components/ui/core/tabs/tabs.utils.d.ts +1 -1
- package/dist/components/ui/core/tabs/tabs.utils.js +10 -6
- package/dist/components/ui/core/tabs/tabs.utils.js.map +1 -0
- package/dist/components/ui/core/textarea/textarea.d.ts +2 -2
- package/dist/components/ui/core/textarea/textarea.gallery.d.ts +2 -0
- package/dist/components/ui/core/textarea/textarea.gallery.js +51 -0
- package/dist/components/ui/core/textarea/textarea.gallery.js.map +1 -0
- package/dist/components/ui/core/textarea/textarea.js +13 -13
- package/dist/components/ui/core/textarea/textarea.js.map +1 -0
- package/dist/components/ui/core/toggle/toggle.d.ts +9 -9
- package/dist/components/ui/core/toggle/toggle.gallery.d.ts +2 -0
- package/dist/components/ui/core/toggle/toggle.gallery.js +32 -0
- package/dist/components/ui/core/toggle/toggle.gallery.js.map +1 -0
- package/dist/components/ui/core/toggle/toggle.js +60 -54
- package/dist/components/ui/core/toggle/toggle.js.map +1 -0
- package/dist/components/ui/core/tool/tool.d.ts +18 -18
- package/dist/components/ui/core/tool/tool.js +167 -126
- package/dist/components/ui/core/tool/tool.js.map +1 -0
- package/dist/components/ui/core/toolbar/toolbar.d.ts +37 -0
- package/dist/components/ui/core/toolbar/toolbar.js +171 -0
- package/dist/components/ui/core/toolbar/toolbar.js.map +1 -0
- package/dist/components/ui/core/tooltip/tooltip.d.ts +8 -7
- package/dist/components/ui/core/tooltip/tooltip.gallery.d.ts +2 -0
- package/dist/components/ui/core/tooltip/tooltip.gallery.js +52 -0
- package/dist/components/ui/core/tooltip/tooltip.gallery.js.map +1 -0
- package/dist/components/ui/core/tooltip/tooltip.js +53 -46
- package/dist/components/ui/core/tooltip/tooltip.js.map +1 -0
- package/dist/components/ui/core/topbar/topbar.d.ts +26 -26
- package/dist/components/ui/core/topbar/topbar.js +160 -105
- package/dist/components/ui/core/topbar/topbar.js.map +1 -0
- package/dist/components/ui/core/tree/tree.d.ts +20 -0
- package/dist/components/ui/core/tree/tree.js +100 -0
- package/dist/components/ui/core/tree/tree.js.map +1 -0
- package/dist/eslint/index.d.ts +5 -5
- package/dist/eslint/index.js +9 -5
- package/dist/eslint/index.js.map +1 -0
- package/dist/eslint/no-overriding-styles.d.ts +1 -1
- package/dist/eslint/no-overriding-styles.js +341 -201
- package/dist/eslint/no-overriding-styles.js.map +1 -0
- package/dist/icons/index.d.ts +1 -1
- package/dist/icons/index.js +2 -0
- package/dist/icons/index.js.map +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/ai/types.d.ts +43 -43
- package/dist/lib/ai/types.js +3 -0
- package/dist/lib/ai/types.js.map +1 -0
- package/dist/lib/decorative-variant-classes.d.ts +53 -0
- package/dist/lib/decorative-variant-classes.js +58 -0
- package/dist/lib/decorative-variant-classes.js.map +1 -0
- package/dist/lib/highlight-code.d.ts +11 -8
- package/dist/lib/highlight-code.js +58 -40
- package/dist/lib/highlight-code.js.map +1 -0
- package/dist/lib/portal-container-context.d.ts +1 -1
- package/dist/lib/portal-container-context.js +8 -8
- package/dist/lib/portal-container-context.js.map +1 -0
- package/dist/lib/shared-theme-from-url.d.ts +13 -0
- package/dist/lib/shared-theme-from-url.js +61 -0
- package/dist/lib/shared-theme-from-url.js.map +1 -0
- package/dist/lib/style-scope.d.ts +2 -2
- package/dist/lib/style-scope.js +6 -6
- package/dist/lib/style-scope.js.map +1 -0
- package/dist/lib/theme-share-url.d.ts +31 -0
- package/dist/lib/theme-share-url.js +116 -0
- package/dist/lib/theme-share-url.js.map +1 -0
- package/dist/lib/types.d.ts +39 -39
- package/dist/lib/types.js +3 -0
- package/dist/lib/types.js.map +1 -0
- package/dist/lib/use-controllable-state.d.ts +4 -7
- package/dist/lib/use-controllable-state.js +34 -21
- package/dist/lib/use-controllable-state.js.map +1 -0
- package/dist/lib/utils.d.ts +63 -34
- package/dist/lib/utils.js +134 -32
- package/dist/lib/utils.js.map +1 -0
- package/dist/styles.css +2 -1
- package/dist/styles.source.css +46 -16
- package/dist/utils/assign-ref.d.ts +3 -0
- package/dist/utils/assign-ref.js +13 -0
- package/dist/utils/assign-ref.js.map +1 -0
- package/package.json +49 -14
- package/src/components/ui/core/alert/alert.md +46 -0
- package/src/components/ui/core/avatar/avatar.md +30 -0
- package/src/components/ui/core/badge/badge.md +32 -0
- package/src/components/ui/core/banner/banner.md +51 -0
- package/src/components/ui/core/breadcrumb/breadcrumb.md +45 -0
- package/src/components/ui/core/button/button.md +93 -0
- package/src/components/ui/core/button-group/button-group.md +38 -0
- package/src/components/ui/core/checkbox/checkbox.md +37 -0
- package/src/components/ui/core/collapsible/collapsible.md +42 -0
- package/src/components/ui/core/count/count.md +33 -0
- package/src/components/ui/core/input/input.md +48 -0
- package/src/components/ui/core/label/label.md +35 -0
- package/src/components/ui/core/radio-group/radio-group.md +38 -0
- package/src/components/ui/core/separator/separator.md +32 -0
- package/src/components/ui/core/skeleton/skeleton.md +33 -0
- package/src/components/ui/core/slider/slider.md +41 -0
- package/src/components/ui/core/switch/switch.md +26 -0
- package/src/components/ui/core/textarea/textarea.md +42 -0
- package/src/components/ui/core/toggle/toggle.md +39 -0
- 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,
|
|
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).
|
|
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
|
|
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
|
-
|
|
246
|
-
|
|
247
|
-
|
|
|
248
|
-
|
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `muted
|
|
252
|
-
| `
|
|
253
|
-
| `
|
|
254
|
-
| `
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
|
267
|
-
|
|
|
268
|
-
| `background`
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `
|
|
273
|
-
| `
|
|
274
|
-
| `
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
|
279
|
-
|
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
|
289
|
-
|
|
|
290
|
-
| `
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
|
299
|
-
|
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `foreground
|
|
305
|
-
| `foreground-fixed-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
|
313
|
-
|
|
|
314
|
-
| `
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
|
332
|
-
|
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
|
346
|
-
|
|
|
347
|
-
| `
|
|
348
|
-
| `
|
|
349
|
-
|
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
| Token
|
|
354
|
-
|
|
|
355
|
-
| `
|
|
356
|
-
| `
|
|
357
|
-
| `
|
|
358
|
-
| `
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
|
364
|
-
|
|
|
365
|
-
|
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
|
375
|
-
|
|
|
376
|
-
| `
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
|
381
|
-
|
|
382
|
-
|
|
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
|
-
|
|
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
|
-
|
|
416
|
+
### Decorative colors
|
|
387
417
|
|
|
388
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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-*`, `
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
2158
|
-
|
|
2159
|
-
| Add / New
|
|
2160
|
-
| Cancel
|
|
2161
|
-
| Collapse (window)
|
|
2162
|
-
| Copy
|
|
2163
|
-
| Delete
|
|
2164
|
-
| Download
|
|
2165
|
-
| Edit
|
|
2166
|
-
| Expand (window)
|
|
2167
|
-
| Filter
|
|
2168
|
-
| Hide
|
|
2169
|
-
| Link
|
|
2170
|
-
| More options (menu opens above or below) | `dots-vertical`
|
|
2171
|
-
| Notifications
|
|
2172
|
-
| Open external link
|
|
2173
|
-
| Publish
|
|
2174
|
-
| Redo
|
|
2175
|
-
| Refresh
|
|
2176
|
-
| Remove / Close
|
|
2177
|
-
| Save
|
|
2178
|
-
| Search
|
|
2179
|
-
| Settings
|
|
2180
|
-
| Share
|
|
2181
|
-
| Show
|
|
2182
|
-
| Sync
|
|
2183
|
-
| Undo
|
|
2184
|
-
| 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
|
|
2191
|
-
|
|
2192
|
-
| App switcher
|
|
2193
|
-
| Back
|
|
2194
|
-
| Home
|
|
2195
|
-
| Open
|
|
2196
|
-
| Close
|
|
2197
|
-
| Open, Next page
|
|
2198
|
-
| Last page, skip
|
|
2199
|
-
| Previous page
|
|
2200
|
-
| First page, skip | `chevrons-left`
|
|
2201
|
-
| Location
|
|
2202
|
-
| Sign in
|
|
2203
|
-
| 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
|
|
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
|
|
2247
|
-
| Sine
|
|
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
|
|
2257
|
-
|
|
|
2258
|
-
| Duration
|
|
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
|
|
2261
|
-
| Stagger
|
|
2262
|
-
| Respect reduced motion
|
|
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
|
|
2269
|
-
|
|
|
2270
|
-
| Position
|
|
2271
|
-
| Scale
|
|
2272
|
-
| Rotation
|
|
2273
|
-
| Opacity
|
|
2274
|
-
| Color
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
2311
|
-
|
|
|
2312
|
-
| Focus indicators
|
|
2313
|
-
| Keyboard activation
|
|
2314
|
-
| ARIA roles
|
|
2315
|
-
| Color contrast
|
|
2316
|
-
| Dark mode
|
|
2317
|
-
| Disabled states
|
|
2318
|
-
| Focus trapping
|
|
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
|
|
2400
|
-
|
|
|
2401
|
-
| Text input
|
|
2402
|
-
| Email input
|
|
2403
|
-
| Password
|
|
2404
|
-
| Number input
|
|
2405
|
-
| Date picker
|
|
2406
|
-
| Textarea
|
|
2407
|
-
| Select
|
|
2408
|
-
| Combobox
|
|
2409
|
-
| Checkbox
|
|
2410
|
-
| File upload
|
|
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
|
|
2464
|
-
| ------------------------ |
|
|
2465
|
-
| Informational image | Describe the content
|
|
2466
|
-
| Decorative image | Empty
|
|
2467
|
-
| Icon-only control | `aria-label` on the control
|
|
2468
|
-
| Icon paired with a label
|
|
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
|
|
2473
|
-
|
|
|
2474
|
-
| Search/list results update | `aria-live="polite"`
|
|
2475
|
-
| Form error
|
|
2476
|
-
| Toast
|
|
2477
|
-
| Dialog opens
|
|
2478
|
-
| Dialog closes
|
|
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
|
|
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.
|