@vokality/design-system 0.0.0-stage → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (350) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +134 -2
  3. package/dist/charts/chart.d.ts +52 -0
  4. package/dist/charts/chart.js +108 -0
  5. package/dist/components/Accordion/Accordion.d.ts +15 -0
  6. package/dist/components/Accordion/Accordion.js +16 -0
  7. package/dist/components/Alert/Alert.d.ts +14 -0
  8. package/dist/components/Alert/Alert.js +12 -0
  9. package/dist/components/AppShell/AppShell.d.ts +21 -0
  10. package/dist/components/AppShell/AppShell.js +48 -0
  11. package/dist/components/Avatar/Avatar.d.ts +11 -0
  12. package/dist/components/Avatar/Avatar.js +19 -0
  13. package/dist/components/AvatarGroup/AvatarGroup.d.ts +11 -0
  14. package/dist/components/AvatarGroup/AvatarGroup.js +13 -0
  15. package/dist/components/Badge/Badge.d.ts +9 -0
  16. package/dist/components/Badge/Badge.js +6 -0
  17. package/dist/components/BarChart/BarChart.d.ts +7 -0
  18. package/dist/components/BarChart/BarChart.js +45 -0
  19. package/dist/components/Breadcrumbs/Breadcrumbs.d.ts +11 -0
  20. package/dist/components/Breadcrumbs/Breadcrumbs.js +11 -0
  21. package/dist/components/Button/Button.d.ts +17 -0
  22. package/dist/components/Button/Button.js +23 -0
  23. package/dist/components/Calendar/Calendar.d.ts +21 -0
  24. package/dist/components/Calendar/Calendar.js +144 -0
  25. package/dist/components/Card/Card.d.ts +16 -0
  26. package/dist/components/Card/Card.js +11 -0
  27. package/dist/components/Checkbox/Checkbox.d.ts +12 -0
  28. package/dist/components/Checkbox/Checkbox.js +24 -0
  29. package/dist/components/Code/Code.d.ts +7 -0
  30. package/dist/components/Code/Code.js +6 -0
  31. package/dist/components/CodeBlock/CodeBlock.d.ts +10 -0
  32. package/dist/components/CodeBlock/CodeBlock.js +43 -0
  33. package/dist/components/Combobox/Combobox.d.ts +23 -0
  34. package/dist/components/Combobox/Combobox.js +188 -0
  35. package/dist/components/Combobox/ListPanel.d.ts +16 -0
  36. package/dist/components/Combobox/ListPanel.js +75 -0
  37. package/dist/components/CommandPalette/CommandPalette.d.ts +23 -0
  38. package/dist/components/CommandPalette/CommandPalette.js +86 -0
  39. package/dist/components/Container/Container.d.ts +10 -0
  40. package/dist/components/Container/Container.js +7 -0
  41. package/dist/components/ContextMenu/ContextMenu.d.ts +11 -0
  42. package/dist/components/ContextMenu/ContextMenu.js +56 -0
  43. package/dist/components/DatePicker/DatePicker.d.ts +25 -0
  44. package/dist/components/DatePicker/DatePicker.js +198 -0
  45. package/dist/components/DescriptionList/DescriptionList.d.ts +12 -0
  46. package/dist/components/DescriptionList/DescriptionList.js +6 -0
  47. package/dist/components/Dialog/Dialog.d.ts +23 -0
  48. package/dist/components/Dialog/Dialog.js +53 -0
  49. package/dist/components/Divider/Divider.d.ts +6 -0
  50. package/dist/components/Divider/Divider.js +10 -0
  51. package/dist/components/Drawer/Drawer.d.ts +6 -0
  52. package/dist/components/Drawer/Drawer.js +6 -0
  53. package/dist/components/EmptyState/EmptyState.d.ts +11 -0
  54. package/dist/components/EmptyState/EmptyState.js +10 -0
  55. package/dist/components/ErrorSummary/ErrorSummary.d.ts +10 -0
  56. package/dist/components/ErrorSummary/ErrorSummary.js +28 -0
  57. package/dist/components/FaqList/FaqList.d.ts +10 -0
  58. package/dist/components/FaqList/FaqList.js +6 -0
  59. package/dist/components/Field/Field.d.ts +12 -0
  60. package/dist/components/Field/Field.js +25 -0
  61. package/dist/components/Figure/Figure.d.ts +11 -0
  62. package/dist/components/Figure/Figure.js +6 -0
  63. package/dist/components/FileUpload/FileUpload.d.ts +25 -0
  64. package/dist/components/FileUpload/FileUpload.js +47 -0
  65. package/dist/components/Grid/Grid.d.ts +12 -0
  66. package/dist/components/Grid/Grid.js +10 -0
  67. package/dist/components/HatchDivider/HatchDivider.d.ts +2 -0
  68. package/dist/components/HatchDivider/HatchDivider.js +5 -0
  69. package/dist/components/Heading/Heading.d.ts +12 -0
  70. package/dist/components/Heading/Heading.js +11 -0
  71. package/dist/components/Icon/Icon.d.ts +8 -0
  72. package/dist/components/Icon/Icon.js +17 -0
  73. package/dist/components/IconButton/IconButton.d.ts +11 -0
  74. package/dist/components/IconButton/IconButton.js +16 -0
  75. package/dist/components/Inline/Inline.d.ts +13 -0
  76. package/dist/components/Inline/Inline.js +8 -0
  77. package/dist/components/Input/Input.d.ts +10 -0
  78. package/dist/components/Input/Input.js +25 -0
  79. package/dist/components/Kbd/Kbd.d.ts +7 -0
  80. package/dist/components/Kbd/Kbd.js +6 -0
  81. package/dist/components/LineChart/LineChart.d.ts +7 -0
  82. package/dist/components/LineChart/LineChart.js +53 -0
  83. package/dist/components/Link/Link.d.ts +7 -0
  84. package/dist/components/Link/Link.js +12 -0
  85. package/dist/components/LinkProvider/LinkProvider.d.ts +22 -0
  86. package/dist/components/LinkProvider/LinkProvider.js +21 -0
  87. package/dist/components/List/List.d.ts +24 -0
  88. package/dist/components/List/List.js +24 -0
  89. package/dist/components/MediaCard/MediaCard.d.ts +19 -0
  90. package/dist/components/MediaCard/MediaCard.js +25 -0
  91. package/dist/components/Menu/Menu.d.ts +14 -0
  92. package/dist/components/Menu/Menu.js +53 -0
  93. package/dist/components/Menu/entries.d.ts +40 -0
  94. package/dist/components/Menu/entries.js +146 -0
  95. package/dist/components/MultiSelect/MultiSelect.d.ts +24 -0
  96. package/dist/components/MultiSelect/MultiSelect.js +166 -0
  97. package/dist/components/NavList/NavList.d.ts +19 -0
  98. package/dist/components/NavList/NavList.js +10 -0
  99. package/dist/components/NumberInput/NumberInput.d.ts +13 -0
  100. package/dist/components/NumberInput/NumberInput.js +90 -0
  101. package/dist/components/OtpInput/OtpInput.d.ts +19 -0
  102. package/dist/components/OtpInput/OtpInput.js +75 -0
  103. package/dist/components/PageHeader/PageHeader.d.ts +18 -0
  104. package/dist/components/PageHeader/PageHeader.js +11 -0
  105. package/dist/components/Pagination/Pagination.d.ts +15 -0
  106. package/dist/components/Pagination/Pagination.js +22 -0
  107. package/dist/components/PasswordInput/PasswordInput.d.ts +7 -0
  108. package/dist/components/PasswordInput/PasswordInput.js +11 -0
  109. package/dist/components/Popover/Popover.d.ts +18 -0
  110. package/dist/components/Popover/Popover.js +26 -0
  111. package/dist/components/Progress/Progress.d.ts +13 -0
  112. package/dist/components/Progress/Progress.js +24 -0
  113. package/dist/components/Prose/Prose.d.ts +8 -0
  114. package/dist/components/Prose/Prose.js +7 -0
  115. package/dist/components/Quote/Quote.d.ts +10 -0
  116. package/dist/components/Quote/Quote.js +7 -0
  117. package/dist/components/Radio/Radio.d.ts +7 -0
  118. package/dist/components/Radio/Radio.js +9 -0
  119. package/dist/components/RadioGroup/RadioGroup.d.ts +21 -0
  120. package/dist/components/RadioGroup/RadioGroup.js +41 -0
  121. package/dist/components/SearchInput/SearchInput.d.ts +10 -0
  122. package/dist/components/SearchInput/SearchInput.js +39 -0
  123. package/dist/components/SectionHeader/SectionHeader.d.ts +10 -0
  124. package/dist/components/SectionHeader/SectionHeader.js +9 -0
  125. package/dist/components/SegmentedControl/SegmentedControl.d.ts +19 -0
  126. package/dist/components/SegmentedControl/SegmentedControl.js +21 -0
  127. package/dist/components/Select/Select.d.ts +26 -0
  128. package/dist/components/Select/Select.js +262 -0
  129. package/dist/components/Skeleton/Skeleton.d.ts +8 -0
  130. package/dist/components/Skeleton/Skeleton.js +13 -0
  131. package/dist/components/Slider/Slider.d.ts +21 -0
  132. package/dist/components/Slider/Slider.js +43 -0
  133. package/dist/components/Sparkline/Sparkline.d.ts +11 -0
  134. package/dist/components/Sparkline/Sparkline.js +15 -0
  135. package/dist/components/Spinner/Spinner.d.ts +8 -0
  136. package/dist/components/Spinner/Spinner.js +8 -0
  137. package/dist/components/SquareGlyph/SquareGlyph.d.ts +7 -0
  138. package/dist/components/SquareGlyph/SquareGlyph.js +6 -0
  139. package/dist/components/Stack/Stack.d.ts +11 -0
  140. package/dist/components/Stack/Stack.js +8 -0
  141. package/dist/components/Stat/Stat.d.ts +13 -0
  142. package/dist/components/Stat/Stat.js +22 -0
  143. package/dist/components/Steps/Steps.d.ts +13 -0
  144. package/dist/components/Steps/Steps.js +13 -0
  145. package/dist/components/Switch/Switch.d.ts +7 -0
  146. package/dist/components/Switch/Switch.js +16 -0
  147. package/dist/components/Table/Table.d.ts +48 -0
  148. package/dist/components/Table/Table.js +144 -0
  149. package/dist/components/Tabs/Tabs.d.ts +19 -0
  150. package/dist/components/Tabs/Tabs.js +29 -0
  151. package/dist/components/Tag/Tag.d.ts +12 -0
  152. package/dist/components/Tag/Tag.js +8 -0
  153. package/dist/components/Text/Text.d.ts +10 -0
  154. package/dist/components/Text/Text.js +7 -0
  155. package/dist/components/Textarea/Textarea.d.ts +6 -0
  156. package/dist/components/Textarea/Textarea.js +17 -0
  157. package/dist/components/ThemeScript/ThemeScript.d.ts +7 -0
  158. package/dist/components/ThemeScript/ThemeScript.js +9 -0
  159. package/dist/components/TileGrid/TileGrid.d.ts +13 -0
  160. package/dist/components/TileGrid/TileGrid.js +8 -0
  161. package/dist/components/TimePicker/TimePicker.d.ts +28 -0
  162. package/dist/components/TimePicker/TimePicker.js +192 -0
  163. package/dist/components/Timeline/Timeline.d.ts +16 -0
  164. package/dist/components/Timeline/Timeline.js +10 -0
  165. package/dist/components/Toaster/Toaster.d.ts +50 -0
  166. package/dist/components/Toaster/Toaster.js +63 -0
  167. package/dist/components/Tooltip/Tooltip.d.ts +11 -0
  168. package/dist/components/Tooltip/Tooltip.js +21 -0
  169. package/dist/components/TreeView/TreeView.d.ts +30 -0
  170. package/dist/components/TreeView/TreeView.js +127 -0
  171. package/dist/components.css +1798 -0
  172. package/dist/fonts/FONT-NOTICES.txt +20 -0
  173. package/dist/fonts/IBMPlexSans-Latin.woff2 +0 -0
  174. package/dist/fonts/IBMPlexSans-OFL.txt +93 -0
  175. package/dist/fonts/Manrope-Latin.woff2 +0 -0
  176. package/dist/fonts/Manrope-OFL.txt +93 -0
  177. package/dist/fonts/SpaceGrotesk-Latin.woff2 +0 -0
  178. package/dist/fonts/SpaceGrotesk-OFL.txt +93 -0
  179. package/dist/fonts.css +23 -0
  180. package/dist/hooks/useTheme.d.ts +16 -0
  181. package/dist/hooks/useTheme.js +82 -0
  182. package/dist/icons/arrow-down.svg +1 -0
  183. package/dist/icons/arrow-up-right.svg +1 -0
  184. package/dist/icons/arrow-up.svg +1 -0
  185. package/dist/icons/calendar.svg +1 -0
  186. package/dist/icons/chart.svg +1 -0
  187. package/dist/icons/check.svg +1 -0
  188. package/dist/icons/chevron-down.svg +1 -0
  189. package/dist/icons/chevron-left.svg +1 -0
  190. package/dist/icons/chevron-right.svg +1 -0
  191. package/dist/icons/chevrons-up-down.svg +1 -0
  192. package/dist/icons/circle-alert.svg +1 -0
  193. package/dist/icons/circle-check.svg +1 -0
  194. package/dist/icons/clock.svg +1 -0
  195. package/dist/icons/copy.svg +1 -0
  196. package/dist/icons/ellipsis.svg +1 -0
  197. package/dist/icons/file.svg +1 -0
  198. package/dist/icons/folder.svg +1 -0
  199. package/dist/icons/home.svg +1 -0
  200. package/dist/icons/info.svg +1 -0
  201. package/dist/icons/map-pin.svg +1 -0
  202. package/dist/icons/menu.svg +1 -0
  203. package/dist/icons/minus.svg +1 -0
  204. package/dist/icons/pencil.svg +1 -0
  205. package/dist/icons/phone.svg +1 -0
  206. package/dist/icons/plus.svg +1 -0
  207. package/dist/icons/quote.svg +1 -0
  208. package/dist/icons/search.svg +1 -0
  209. package/dist/icons/sidebar.svg +1 -0
  210. package/dist/icons/trash.svg +1 -0
  211. package/dist/icons/triangle-alert.svg +1 -0
  212. package/dist/icons/upload.svg +1 -0
  213. package/dist/icons/users.svg +1 -0
  214. package/dist/icons/x.svg +1 -0
  215. package/dist/index.d.ts +178 -0
  216. package/dist/index.js +93 -0
  217. package/dist/internal/CharCount.d.ts +17 -0
  218. package/dist/internal/CharCount.js +23 -0
  219. package/dist/internal/choice.d.ts +65 -0
  220. package/dist/internal/choice.js +111 -0
  221. package/dist/internal/focusables.d.ts +3 -0
  222. package/dist/internal/focusables.js +8 -0
  223. package/dist/internal/options.d.ts +15 -0
  224. package/dist/internal/options.js +30 -0
  225. package/dist/internal/status.d.ts +6 -0
  226. package/dist/internal/status.js +5 -0
  227. package/dist/internal/useIsoLayoutEffect.d.ts +3 -0
  228. package/dist/internal/useIsoLayoutEffect.js +4 -0
  229. package/dist/internal/useScrollActive.d.ts +3 -0
  230. package/dist/internal/useScrollActive.js +12 -0
  231. package/dist/internal/useUid.d.ts +2 -0
  232. package/dist/internal/useUid.js +6 -0
  233. package/dist/lib/cx.d.ts +2 -0
  234. package/dist/lib/cx.js +4 -0
  235. package/dist/lib/dates.d.ts +10 -0
  236. package/dist/lib/dates.js +107 -0
  237. package/dist/lib/format.d.ts +15 -0
  238. package/dist/lib/format.js +50 -0
  239. package/dist/lib/icons.d.ts +220 -0
  240. package/dist/lib/icons.js +54 -0
  241. package/dist/lib/intl.d.ts +4 -0
  242. package/dist/lib/intl.js +19 -0
  243. package/dist/lib/math.d.ts +5 -0
  244. package/dist/lib/math.js +36 -0
  245. package/dist/lib/omit.d.ts +2 -0
  246. package/dist/lib/omit.js +10 -0
  247. package/dist/lib/space.d.ts +4 -0
  248. package/dist/lib/space.js +9 -0
  249. package/dist/lib/text.d.ts +8 -0
  250. package/dist/lib/text.js +12 -0
  251. package/dist/lib/theme.d.ts +16 -0
  252. package/dist/lib/theme.js +14 -0
  253. package/dist/lib/utils.d.ts +17 -0
  254. package/dist/lib/utils.js +5 -0
  255. package/dist/tailwind.css +110 -0
  256. package/dist/tokens.css +316 -0
  257. package/dist/tokens.dtcg.json +1606 -0
  258. package/dist/tokens.json +1217 -0
  259. package/dist/types.d.ts +67 -0
  260. package/dist/types.js +1 -0
  261. package/dist/vokality.css +2139 -0
  262. package/dist/vokality.iife.js +19408 -0
  263. package/docs/brand.md +163 -0
  264. package/docs/components/Accordion/README.md +24 -0
  265. package/docs/components/Alert/README.md +31 -0
  266. package/docs/components/AppShell/README.md +20 -0
  267. package/docs/components/Avatar/README.md +17 -0
  268. package/docs/components/AvatarGroup/README.md +12 -0
  269. package/docs/components/Badge/README.md +24 -0
  270. package/docs/components/BarChart/README.md +30 -0
  271. package/docs/components/Breadcrumbs/README.md +16 -0
  272. package/docs/components/Button/README.md +43 -0
  273. package/docs/components/Calendar/README.md +43 -0
  274. package/docs/components/Card/README.md +16 -0
  275. package/docs/components/Checkbox/README.md +30 -0
  276. package/docs/components/Code/README.md +9 -0
  277. package/docs/components/CodeBlock/README.md +15 -0
  278. package/docs/components/Combobox/README.md +43 -0
  279. package/docs/components/CommandPalette/README.md +20 -0
  280. package/docs/components/Container/README.md +10 -0
  281. package/docs/components/ContextMenu/README.md +13 -0
  282. package/docs/components/Dashboard/README.md +12 -0
  283. package/docs/components/DatePicker/README.md +34 -0
  284. package/docs/components/DescriptionList/README.md +18 -0
  285. package/docs/components/Dialog/README.md +28 -0
  286. package/docs/components/Divider/README.md +15 -0
  287. package/docs/components/Drawer/README.md +16 -0
  288. package/docs/components/EmptyState/README.md +17 -0
  289. package/docs/components/ErrorPage/README.md +11 -0
  290. package/docs/components/ErrorSummary/README.md +16 -0
  291. package/docs/components/FaqList/README.md +11 -0
  292. package/docs/components/Field/README.md +27 -0
  293. package/docs/components/Figure/README.md +9 -0
  294. package/docs/components/FileUpload/README.md +20 -0
  295. package/docs/components/FormPage/README.md +11 -0
  296. package/docs/components/Grid/README.md +11 -0
  297. package/docs/components/HatchDivider/README.md +10 -0
  298. package/docs/components/Heading/README.md +10 -0
  299. package/docs/components/Icon/README.md +23 -0
  300. package/docs/components/IconButton/README.md +28 -0
  301. package/docs/components/Inline/README.md +9 -0
  302. package/docs/components/Input/README.md +31 -0
  303. package/docs/components/Kbd/README.md +13 -0
  304. package/docs/components/LineChart/README.md +27 -0
  305. package/docs/components/Link/README.md +31 -0
  306. package/docs/components/List/README.md +21 -0
  307. package/docs/components/ListDetail/README.md +11 -0
  308. package/docs/components/MediaCard/README.md +16 -0
  309. package/docs/components/Menu/README.md +45 -0
  310. package/docs/components/MultiSelect/README.md +41 -0
  311. package/docs/components/NavList/README.md +21 -0
  312. package/docs/components/NumberInput/README.md +19 -0
  313. package/docs/components/OtpInput/README.md +17 -0
  314. package/docs/components/PageHeader/README.md +17 -0
  315. package/docs/components/Pagination/README.md +22 -0
  316. package/docs/components/PasswordInput/README.md +13 -0
  317. package/docs/components/Popover/README.md +23 -0
  318. package/docs/components/Progress/README.md +19 -0
  319. package/docs/components/Prose/README.md +12 -0
  320. package/docs/components/Quote/README.md +13 -0
  321. package/docs/components/Radio/README.md +25 -0
  322. package/docs/components/RadioGroup/README.md +23 -0
  323. package/docs/components/SearchInput/README.md +23 -0
  324. package/docs/components/SectionHeader/README.md +14 -0
  325. package/docs/components/SegmentedControl/README.md +19 -0
  326. package/docs/components/Select/README.md +52 -0
  327. package/docs/components/SettingsPage/README.md +11 -0
  328. package/docs/components/SignIn/README.md +11 -0
  329. package/docs/components/Skeleton/README.md +16 -0
  330. package/docs/components/Slider/README.md +22 -0
  331. package/docs/components/Sparkline/README.md +13 -0
  332. package/docs/components/Spinner/README.md +16 -0
  333. package/docs/components/SquareGlyph/README.md +18 -0
  334. package/docs/components/Stack/README.md +11 -0
  335. package/docs/components/Stat/README.md +20 -0
  336. package/docs/components/Steps/README.md +22 -0
  337. package/docs/components/Switch/README.md +27 -0
  338. package/docs/components/Table/README.md +35 -0
  339. package/docs/components/Tabs/README.md +26 -0
  340. package/docs/components/Tag/README.md +21 -0
  341. package/docs/components/Text/README.md +11 -0
  342. package/docs/components/Textarea/README.md +20 -0
  343. package/docs/components/ThemeScript/README.md +47 -0
  344. package/docs/components/TileGrid/README.md +12 -0
  345. package/docs/components/TimePicker/README.md +19 -0
  346. package/docs/components/Timeline/README.md +12 -0
  347. package/docs/components/Toaster/README.md +34 -0
  348. package/docs/components/Tooltip/README.md +23 -0
  349. package/docs/components/TreeView/README.md +15 -0
  350. package/package.json +76 -4
@@ -0,0 +1,34 @@
1
+ # DatePicker
2
+
3
+ A field that opens a `Calendar` in a popover to choose a date or a date range. The popover is built on Radix Popover.
4
+
5
+ ## Anatomy
6
+ 1. **Trigger**: in single mode, a text input with a calendar button inside its right edge (Alt+↓ opens the calendar); in range mode, the `Input` box as a button, with a `calendar` icon (16px, `muted-foreground`) and the formatted date ("Oct 17, 2026", or "Sep 10 – Oct 10, 2026" for a range), or the placeholder in `muted-subtle`.
7
+ 2. **Popover**: a dialog rendered at the end of the page (so scrolling containers, dialogs and drawers never clip it), 4px below the trigger and start-aligned with it (the whole field in typing mode), flipping above when there's no room and kept 8px inside the viewport: `surface-elevated`, 1px `border`, square, 0.75rem padding, at most the room on its side tall (it scrolls). It fades and rises 0.5rem over `motion-normal`; no motion under reduced motion.
8
+ 3. **Calendar**: see `Calendar`.
9
+ 4. **Footer**: above a `border-subtle` rule, a ghost `Clear` button and, in single mode, an outline `Today` button, both `sm`.
10
+
11
+ ## States
12
+ | Part | State | Treatment |
13
+ | --- | --- | --- |
14
+ | Trigger | Focus | `primary` edge, 2px `ring` |
15
+ | Trigger | Open (`data-state="open"`) | `primary` edge |
16
+ | Trigger | Invalid / disabled | As `Input` |
17
+
18
+ ## Behaviour and keyboard
19
+ - Click, Enter, Space or ↓ on the trigger opens the popover and moves focus to the selected day (or today).
20
+ - In the grid, use the `Calendar` keys. Choosing a date closes the popover and returns focus to the trigger. In range mode it closes after the end date.
21
+ - Esc closes and returns focus to the trigger (the input in typing mode); inside a `Dialog` or `Drawer` it closes only the calendar. Clicking outside also closes, leaving focus where it was put. Tab and Shift+Tab off the ends of the popover close it and move on in page order (back to the trigger, or to the next field).
22
+ - In typing mode the calendar button toggles the popover; pressing the input while it's open keeps it open.
23
+ - The popover is a `role="dialog"` labelled "Choose a date" (or "Choose dates", or `dialogLabel`). The trigger (the calendar button in typing mode) has `aria-haspopup="dialog"`, `aria-expanded` and, while open, `aria-controls`.
24
+
25
+ ## Props
26
+ - `mode` (`single` or `range`), `value` / `defaultValue` / `onChange` as in `Calendar`.
27
+ - `placeholder`, `min`, `max`, `isDateDisabled`, `weekStartsOn`, `locale`, `disabled`, `defaultOpen`, `dialogLabel`.
28
+ - `name`: posts `name=YYYY-MM-DD`, or `name_start` and `name_end` for a range.
29
+ - `invalidMessage`: replaces "Enter a date like …".
30
+ - `ref`: the text input, or the trigger button with `allowTyping={false}` or in range mode.
31
+
32
+ ## Rules
33
+ - Display format follows `locale` (`Intl.DateTimeFormat`, medium date). Never show raw ISO strings to people.
34
+ - In single mode, people can type the date. The field accepts ISO (`2026-10-11`), the locale's numeric order (`10/11/2026` in en-US, `11-10-2026` in Dutch) and month names in the locale or English (`Oct 11 2026`, `11 okt 2026`). On Enter or leaving the field, a valid date is reformatted; anything else (or a date outside `min`/`max`) shows "Enter a date like Oct 11, 2026." Set `allowTyping={false}` for a button-only trigger. Range mode is calendar-only.
@@ -0,0 +1,18 @@
1
+ # DescriptionList
2
+
3
+ Label and value pairs for a record's details: client info, settings summaries, metadata.
4
+
5
+ ## Layouts
6
+ - **Inline** (default): the term in `muted-foreground` on the left (8–12rem column), the value in `foreground` on the right, rows separated by 1px `border-subtle`. It stacks under 40rem.
7
+ - **Stacked** (`layout="stacked"`): the term as a 12px uppercase label above the value, for narrow panels such as a `Drawer`.
8
+ - `columns={2}` splits into two columns from 40rem.
9
+
10
+ ## Props
11
+ - `items`: `{ term, description }[]`, where description can be any content (a `Badge`, a `Link`). `layout`, `columns`.
12
+
13
+ ## Accessibility
14
+ A real `dl` with `dt` and `dd` pairs.
15
+
16
+ ## Rules
17
+ - Use Space Grotesk for IDs and figures inside values.
18
+ - Write "Not set" (in `muted-subtle`) for empty values rather than leaving a blank.
@@ -0,0 +1,28 @@
1
+ # Dialog
2
+
3
+ A modal window that takes focus for a task or decision before people return to the page: a short form, a confirmation, details that need attention. Built on Radix Dialog (Radix AlertDialog for `role="alertdialog"`).
4
+
5
+ ## Anatomy
6
+ 1. **Backdrop**: `overlay` over the whole viewport.
7
+ 2. **Panel**: `surface-elevated`, 1px `border`, square, centered, with a max width by `size`: `sm` 26rem, `md` 34rem, `lg` 46rem. It is never taller than the viewport minus 2rem; the body scrolls.
8
+ 3. **Header**: title in Manrope 700 at 20px, an optional description in `muted-foreground`, and a close `IconButton`.
9
+ 4. **Body**: any content, `small` text by default.
10
+ 5. **Footer**: right-aligned buttons above a `border-subtle` rule: the confirming action last, as `primary` (or `danger` for destructive ones).
11
+
12
+ ## Behaviour
13
+ - Opening moves focus to the first field in the body (or the element marked `data-autofocus`), else the first footer button.
14
+ - Tab and Shift+Tab stay inside the dialog. The page behind can't scroll and is hidden from assistive technology and pointer input while it is open.
15
+ - Esc, the close button and a backdrop click call `onClose`. Closing returns focus to whatever opened the dialog.
16
+ - `role="alertdialog"` is for destructive confirmations: no close button, and Esc and the backdrop do nothing, so people must choose.
17
+ - The panel rises 0.5rem as it fades in (none under reduced motion); it closes at once.
18
+ - Selects, menus, date pickers and popovers inside the body float above the dialog, so a field near the bottom can open its list without being clipped.
19
+
20
+ ## Props
21
+ - `open`, `onClose`, `title`, `description`, `children`, `footer`, `size`, `role`, `dismissible`, `closeOnBackdrop`, `closeLabel`.
22
+
23
+ ## Accessibility
24
+ `role="dialog"` (or `alertdialog`), `aria-modal="true"`, labelled by the title (`aria-labelledby`) and described by the description (`aria-describedby`, only when there is one); rendered in a portal on `document.body`. Open state is exposed as `data-state="open"` on the overlay and the panel.
25
+
26
+ ## Rules
27
+ - The title states the task or question ("Delete INV-1043?"). Buttons repeat the verb ("Delete invoice"), never "OK" or "Yes".
28
+ - One dialog at a time. For side detail that people compare against the page, use a `Drawer`.
@@ -0,0 +1,15 @@
1
+ # Divider
2
+
3
+ A horizontal rule that separates content.
4
+
5
+ ## Variants
6
+ | Variant | Line | Use |
7
+ | --- | --- | --- |
8
+ | `solid` (default) | 1px `border-subtle` | Between sections, list rows, card footers |
9
+ | `strong` | 1px `border` | Edges that must read clearly, such as under a table header |
10
+ | `dashed` | 1px dashed `dash-line` | Inside a `surface-sunken` band |
11
+ | `hatch` | `HatchDivider` | At most two major breaks per page |
12
+
13
+ ## Rules
14
+ - Prefer spacing to a rule when the groups are already clear.
15
+ - Rules run the full width of their container; don't inset them.
@@ -0,0 +1,16 @@
1
+ # Drawer
2
+
3
+ A modal panel that slides in from the side, for detail views and longer forms that relate to the page behind it.
4
+
5
+ ## Anatomy
6
+ Same parts as `Dialog` (header, body, footer) in a full-height panel up to 28rem wide (the full width on phones), with a 1px `border` on its inner edge. It slides in 1.5rem from its side (from the left for `side="left"`).
7
+
8
+ ## Behaviour
9
+ Identical to `Dialog` (Radix Dialog): focus moves in and is trapped, Esc and a backdrop click close it, focus returns to the opener, and the page can't scroll.
10
+
11
+ ## Props
12
+ - All `Dialog` props, plus `side`: `right` (default) or `left`.
13
+
14
+ ## Rules
15
+ - Use a drawer for a record's details, edit forms and filters that need more than a popover.
16
+ - Keep the primary action in the footer so it stays visible while the body scrolls.
@@ -0,0 +1,17 @@
1
+ # EmptyState
2
+
3
+ What a list, table or page shows when it has nothing in it yet: what will appear here, and how to add the first item.
4
+
5
+ ## Anatomy
6
+ 1. **Box**: 1px dashed `dash-line` border, 2rem 1.75rem padding, left-aligned.
7
+ 2. **Glyphs**: a `SquareGlyph` with two empty boxes beside it, the system's signature cluster.
8
+ 3. **Title**: Manrope 700, 18px.
9
+ 4. **Text**: `small`, `muted-foreground`, up to 36rem.
10
+ 5. **Actions**: a primary `Button` for the main way to start, plus ghost or outline buttons for the alternatives.
11
+
12
+ ## Props
13
+ - `title`, `children` (text), `actions` (an array of buttons), `glyph`, `headingAs`.
14
+
15
+ ## Rules
16
+ - Name what will appear ("Invoices you create or import show up here"), not just "No data".
17
+ - For a search or filter with no results, say so and offer to clear the filter; don't show the first-run actions.
@@ -0,0 +1,11 @@
1
+ # Error page template
2
+
3
+ What people see when a page can't be shown: not found (404), no access (403) or a server error (500). It says what happened in plain words and gives a way forward.
4
+
5
+ ## Built from
6
+ `Container`, `Stack`, `Inline`, `Button`, `Code`, `Text`, and the display type styles.
7
+
8
+ ## Rules
9
+ - The headline uses the two-beat pattern ("This page is / out of range."); the oversized numeral is the status code in Space Grotesk.
10
+ - Offer the obvious next step as the primary button (Go to dashboard) and a secondary way out (Contact support).
11
+ - For server errors, show a short reference people can quote to support, in `Code`. Never show a stack trace.
@@ -0,0 +1,16 @@
1
+ # ErrorSummary
2
+
3
+ A list of a form's problems, shown at the top of the form after a failed submit. Each item links to its field.
4
+
5
+ ## Anatomy
6
+ A `danger` `Alert` with the title "Fix 2 problems to continue" and a bulleted list of the field messages as links.
7
+
8
+ ## Behaviour
9
+ - It takes focus when it appears, so keyboard and screen-reader users land on it. Clicking an item focuses that field and scrolls it into view.
10
+ - Renders nothing when `errors` is empty.
11
+
12
+ ## Props
13
+ - `errors`: `{ field, message }[]`, where `field` is the input's `id` (the same message shown in that field's `Field` error). `title`, `autoFocus` (true).
14
+
15
+ ## Rules
16
+ - Use it on forms longer than one screen, alongside the inline field errors, not instead of them.
@@ -0,0 +1,11 @@
1
+ # FaqList
2
+
3
+ Question-and-answer pairs in outlined panels, rendered as a description list. Use it for help pages, pricing questions and onboarding notes.
4
+
5
+ ## What you provide
6
+ - `items`: `{ question, answer }[]`. Write questions the way a user asks them.
7
+ - `columns`: `2` splits the list into two columns from 60rem; an odd last item spans both. One column holds to 52rem.
8
+
9
+ ## Rules
10
+ - Question in `question` style (Manrope 600); answer in `body-sm`, `muted-foreground`.
11
+ - Open an answer with "Yes." or "No." when the question allows it.
@@ -0,0 +1,27 @@
1
+ # Field
2
+
3
+ The wrapper that gives any form control its label, hint and error, and wires them together for assistive technology.
4
+
5
+ ## Anatomy
6
+ 1. **Label**: a Radix Label, `card-eyebrow` style in `muted-foreground`, uppercase; clicking it focuses the control. An optional marker ("Optional") sits after it in `muted-subtle`, sentence case.
7
+ 2. **Control**: one `Input`, `Textarea`, `SearchInput`, `Select`, `Combobox`, `MultiSelect` or `DatePicker` passed as the child.
8
+ 3. **Hint** (optional): `small` text in `muted-subtle` under the control.
9
+ 4. **Error** (optional): `small` text in `primary-hover`, below the hint.
10
+
11
+ ## Spacing
12
+ 0.4rem between parts. Stack fields with a 1rem gap; pair two short fields side by side from 36rem.
13
+
14
+ ## States
15
+ | State | Treatment |
16
+ | --- | --- |
17
+ | Default | Label, control, optional hint |
18
+ | Error | The control gets `aria-invalid` and a `primary` border; the message says how to fix it |
19
+
20
+ ## Props
21
+ - `label` (required), `children` (one control), `hint`, `error`, `optional` (the marker text), `id` (generated if omitted).
22
+ - Field sets the child's `id`, `aria-describedby` and `aria-invalid`; don't set them yourself.
23
+
24
+ ## Rules
25
+ - Mark the optional fields, not the required ones.
26
+ - Show errors after submit or blur, not while someone is still typing.
27
+ - Checkboxes and switches carry their own label; group radios with `RadioGroup`.
@@ -0,0 +1,9 @@
1
+ # Figure
2
+
3
+ An image (or any media) with a caption: screenshots in docs, product shots in articles.
4
+
5
+ ## Anatomy
6
+ The media in a 1px `border-subtle` frame on `media-placeholder`, cropped to `ratio`, square; the caption in 13px `muted-foreground`, 0.5rem below.
7
+
8
+ ## Props
9
+ - `src`, `alt` (required when the image carries information), `ratio` ("16 / 10"), `caption`, or `children` in place of `src`.
@@ -0,0 +1,20 @@
1
+ # FileUpload
2
+
3
+ A drop zone with a browse button for attaching files, and a list of the chosen files with sizes and errors.
4
+
5
+ ## Anatomy
6
+ 1. **Drop zone**: 1px dashed `muted-subtle` border on `card-fill`, with an `upload` icon, "Drop files here or browse", and a hint (types and size limit) in `muted-subtle`.
7
+ 2. **Drag-over state**: a solid `primary` border, `primary-tint` fill and a `primary` icon.
8
+ 3. **File list**: rows in a 1px `border-subtle` frame: `file` icon, name (truncated), size in Space Grotesk, and a remove `IconButton`.
9
+ 4. **Error row**: `circle-alert` icon and the message in `danger` ("Larger than 10.0 MB.").
10
+
11
+ ## Props
12
+ - `accept`, `multiple`, `maxSize` (bytes), `name`, `disabled`, `title`, `hint`, `defaultFiles`.
13
+ - `onChange(validFiles, allEntries)`: the `File` objects that passed, plus every entry with its error.
14
+
15
+ ## Accessibility
16
+ The browse control is a real button; the file input behind it is labelled by the surrounding `Field`. Every remove button is named "Remove file-name". Errors are written out, not only colored.
17
+
18
+ ## Rules
19
+ - State the accepted types and size limit in the hint before people try.
20
+ - Uploading progress belongs in each row; use `Progress` there when you upload immediately.
@@ -0,0 +1,11 @@
1
+ # Form page template
2
+
3
+ A long form inside the app: grouped sections with a clear heading each, inline validation, an error summary after a failed submit, and the actions at the end.
4
+
5
+ ## Built from
6
+ `AppShell`, `PageHeader`, `ErrorSummary`, `Field`, `Input` (prefix), `NumberInput`, `Select`, `Combobox`, `DatePicker`, `Textarea` (character count), `RadioGroup`, `FileUpload`, `Divider`, `Button` (loading), `toast()`.
7
+
8
+ ## Rules
9
+ - One column of fields at up to 40rem; pair short fields from 36rem.
10
+ - Validate when a field loses focus and again on submit. On a failed submit, show the `ErrorSummary` at the top and keep each field's message beside it.
11
+ - The primary action states what happens ("Create invoice"). It shows a spinner while saving, and a toast confirms the result.
@@ -0,0 +1,11 @@
1
+ # Grid
2
+
3
+ A responsive grid. With `columns` it is a fixed count (one column under 40rem); without, it fits as many columns of at least `min` width as the space allows.
4
+
5
+ ## Props
6
+ - `columns`: a number of equal columns. Or `min`: the smallest column width for an auto-fitting grid (`16rem` default).
7
+ - `gap` (`lg` default), `as`.
8
+
9
+ ## Rules
10
+ - Card grids: `min="16rem"`. Stat rows: `min="10rem"`. Form columns: `columns={2}`.
11
+ - For the website-style grids with fixed breakpoints, `Card` documents `.vk-card-grid-2/3/4`.
@@ -0,0 +1,10 @@
1
+ # HatchDivider
2
+
3
+ A full-width black band of 1px diagonal stripes that marks a major break in a page. It is also available as `Divider variant="hatch"`.
4
+
5
+ ## Anatomy
6
+ 0.85–1.2rem tall; `hatch-ground` fill, `hatch-edge` top and bottom rules, `hatch-line` stripes at -45° every 9px.
7
+
8
+ ## Rules
9
+ - Edge to edge across its container, with no side padding.
10
+ - At most twice per page. Decorative (`aria-hidden`).
@@ -0,0 +1,10 @@
1
+ # Heading
2
+
3
+ A heading at the right level with the right type style, so document structure and visual size can differ when they need to.
4
+
5
+ ## Props
6
+ - `level` (1–4, default 2) sets the element. `size` picks any type style (`display-xl`, `heading-1`, `heading-2`, `title`, `title-sm` …); by default level 1 is `heading-1`, 2 `heading-2`, 3 `title`, 4 `title-sm`.
7
+ - `id`, `children`, `className`.
8
+
9
+ ## Rules
10
+ - One `h1` per page (usually in `PageHeader`). Don't skip levels; change `size` instead.
@@ -0,0 +1,23 @@
1
+ # Icon
2
+
3
+ An outline icon from the Vokality set (Lucide), drawn inline with `currentColor`.
4
+
5
+ ## Anatomy
6
+ 24×24 viewBox, no fill, round caps and joins; stroke 1.5 for `arrow-up-right`, `phone` and `map-pin`, 1.75 for the rest.
7
+
8
+ ## The set
9
+ | Group | Icons | Default size |
10
+ | --- | --- | --- |
11
+ | Actions | `arrow-up-right`, `pencil`, `copy`, `trash`, `plus`, `minus`, `upload`, `ellipsis` | 16–20px (arrow 17px) |
12
+ | Status | `info`, `circle-check`, `triangle-alert`, `circle-alert`, `check` | 18px (check 16px) |
13
+ | Navigation | `chevron-left`, `chevron-right`, `chevron-down`, `menu`, `x`, `home`, `folder`, `users`, `chart`, `search`, `calendar` | 16px (menu and x 22px) |
14
+ | Data | `arrow-up`, `arrow-down`, `chevrons-up-down`, `file` | 14–16px |
15
+ | Contact | `phone`, `map-pin`, `quote` | 14px (quote 18px) |
16
+
17
+ ## Props
18
+ - `name` (any icon above), `size` (px), `className`.
19
+
20
+ ## Rules
21
+ - Icons are `aria-hidden`; a visible label or an `IconButton` label carries the meaning.
22
+ - Color them with text tokens. Never fill them and never use emoji in their place.
23
+ - To add an icon, take it from Lucide at the same stroke.
@@ -0,0 +1,28 @@
1
+ # IconButton
2
+
3
+ A square button that shows only an icon, for compact controls: close, menu, previous and next, more actions.
4
+
5
+ ## Anatomy
6
+ 1. **Container**: 40×40px square, 1px border (transparent for `ghost`).
7
+ 2. **Icon**: one `Icon` at its default size, `currentColor` (`foreground`).
8
+
9
+ ## Variants
10
+ | Variant | Border at rest | Use |
11
+ | --- | --- | --- |
12
+ | `ghost` (default) | none | Toolbars, headers, dismiss buttons |
13
+ | `outline` | `muted-subtle` | Controls that must read as buttons on their own, such as carousel arrows |
14
+
15
+ ## States
16
+ | State | Treatment |
17
+ | --- | --- |
18
+ | Hover | `primary-tint` fill; outline border turns `primary-hover` |
19
+ | Focus | 2px `ring` outline, 2px offset |
20
+ | Disabled | 50% opacity, `not-allowed` cursor |
21
+
22
+ ## Props
23
+ - `icon` (required): an `Icon` name. `label` (required): the action in words; it becomes `aria-label` and the tooltip.
24
+ - `variant`, `size` (icon px), `href`, plus any button attribute.
25
+
26
+ ## Rules
27
+ - Always pass `label`. If the action isn't obvious from the icon alone, use a `Button` with text instead.
28
+ - Keep the 40px target even when the icon is small.
@@ -0,0 +1,9 @@
1
+ # Inline
2
+
3
+ Lays children out in a row that wraps, with one gap. For button groups, tag lists, metadata rows and toolbars.
4
+
5
+ ## Props
6
+ - `gap` (`sm` default), `align` (`center` default), `justify` (`flex-start`, `space-between`, `flex-end`), `wrap` (`true` default), `as`.
7
+
8
+ ## Rules
9
+ - Buttons in a row: `gap="sm"` (0.5rem) or the 0.75rem button default. Toolbars that push actions to the end: `justify="space-between"`.
@@ -0,0 +1,31 @@
1
+ # Input
2
+
3
+ A single-line text control for names, emails, numbers, search and other short values.
4
+
5
+ ## Anatomy
6
+ 1. **Box**: `card` fill, 1px `input-border` edge (3:1 or more on every surface), square, 44px minimum height, 0.6rem 0.75rem padding.
7
+ 2. **Value**: IBM Plex Sans 16px (`text-base`) in `foreground`.
8
+ 3. **Placeholder**: `muted-subtle`.
9
+
10
+ ## States
11
+ | State | Fill | Border | Text |
12
+ | --- | --- | --- | --- |
13
+ | Rest | `card` | `input-border` | `foreground` |
14
+ | Focus | `card` | `primary`, plus 2px `ring` outline at 1px offset | `foreground` |
15
+ | Invalid (`aria-invalid`) | `card` | `primary` | `foreground` |
16
+ | Read-only | transparent | `input-border` | `foreground` |
17
+ | Disabled | transparent | `input-border`, dashed | `muted-subtle` |
18
+
19
+ ## Add-ons and counter
20
+ - `prefix` and `suffix` put text or an element inside the field, divided by a 1px `border-subtle` rule: a currency ("$"), a unit, a domain (".vokality.com"). The whole box takes the focus ring.
21
+ - `showCount` with `maxLength` shows "12 / 80" under the field in Space Grotesk; it turns `danger` past the limit and is announced near it. The limit is soft, so people can paste and then trim.
22
+
23
+ ## Props
24
+ - `prefix`, `suffix`, `showCount`, and any `<input>` attribute: `type`, `name`, `value` or `defaultValue`, `placeholder`, `autoComplete`, `inputMode`, `required`, `disabled`.
25
+ - The ref is the `<input>` (also with add-ons), so it can anchor a `Tooltip` or `Popover`.
26
+
27
+ ## Rules
28
+ - Always render inside a `Field` (or give it an `aria-label`).
29
+ - Placeholders show an example of the format ("name@company.com"), never the label.
30
+ - Set `type` and `autoComplete` so phones show the right keyboard and autofill works.
31
+ - Use Space Grotesk with `tabular-nums` (`font-family: var(--font-numeric)`) for amounts and codes.
@@ -0,0 +1,13 @@
1
+ # Kbd
2
+
3
+ A keyboard key, for shortcuts in help text, menus and tooltips.
4
+
5
+ ## Anatomy
6
+ Space Grotesk 11px in `foreground` on `card`, 1px `border` with a 2px bottom edge, square, at least 1.4rem wide.
7
+
8
+ ## Props
9
+ - `children`: the key ("⌘", "K", "Esc").
10
+
11
+ ## Rules
12
+ - One `Kbd` per key, with combinations side by side: ⌘ K.
13
+ - Use the platform's symbols (⌘ on Apple, Ctrl elsewhere) when you know the platform.
@@ -0,0 +1,27 @@
1
+ # LineChart
2
+
3
+ Lines for change over time: one to four series, each labeled directly at its end.
4
+
5
+ ## Anatomy
6
+ 1. **Header and legend**: as in `BarChart`.
7
+ 2. **Plot**: 2px lines with round joins, a 4px point at the latest value (or at the hovered one), direct labels at the right end for up to four series.
8
+ 3. **Crosshair**: a dashed `muted-subtle` rule and a tooltip with every series' value at the hovered point.
9
+
10
+ ## Props
11
+ - `data`, `xKey`, `series`, `height`, `valueFormat`, `tickFormat`, `directLabels` (true for up to four series), `title`, `description`, `allowTable`, `locale`.
12
+
13
+ ## Color
14
+ - Series take `chart-1` … `chart-8` in order and never cycle; slot 1 is Vokality orange. A ninth series folds into "Other".
15
+ - Slots 1–3 stay distinct for color-blind readers even in scatter-type charts where any two marks can meet; past three series there, use small multiples.
16
+ - The order was validated with the data-visualization checks (OKLab ΔE ×100 under protanopia and deuteranopia): worst neighboring pair 9.2 light and 9.4 dark against a target of 8, and 19.6 / 19.3 for full color vision against a floor of 15.
17
+ - In light, slots 1, 2, 4 and 5 sit under 3:1 on the page, so light-theme charts keep their legend, direct labels and table view on.
18
+ - Status colors are never series colors. Magnitude uses `seq-1`…`seq-7`; above or below a baseline uses `div-1`…`div-7` (blue, gray midpoint, orange).
19
+
20
+ ## Accessibility
21
+ - Every chart carries a visually hidden data table, so screen readers get the numbers. "Show table" swaps the chart for the same table on screen.
22
+ - The plot is focusable: ← → move through the points and show the tooltip, Home and End jump to the ends, Esc hides it.
23
+ - Two or more series always get a legend; text uses text tokens, never the series color.
24
+
25
+ ## Rules
26
+ - One y-axis per chart. Two measures of different scale get two charts.
27
+ - Gridlines are faint (`border-subtle`), the baseline is `border`, tick labels are Space Grotesk in `muted-subtle`.
@@ -0,0 +1,31 @@
1
+ # Link
2
+
3
+ An inline text link for navigation inside or beside running text.
4
+
5
+ ## Anatomy
6
+ 1. **Text**: inherits the surrounding size and family.
7
+ 2. **Underline**: 1px, 0.2em offset.
8
+ 3. **External glyph** (optional): `arrow-up-right` at 13px after the text.
9
+
10
+ ## Tones
11
+ | Tone | Text | Underline | Use |
12
+ | --- | --- | --- | --- |
13
+ | default | `foreground` | `primary-line` | Links in body copy |
14
+ | `muted` | `muted-foreground` | current color | Footers, metadata, secondary navigation |
15
+
16
+ ## States
17
+ | State | Treatment |
18
+ | --- | --- |
19
+ | Hover | Text and underline turn `primary-hover` |
20
+ | Focus | 2px `ring` outline, 2px offset |
21
+ | Visited | Same as rest |
22
+
23
+ ## Props
24
+ - `href`, `children`. `tone`: `muted`. `external`: adds the glyph and opens in a new tab.
25
+
26
+ ## Rules
27
+ - Link text names the destination ("Billing settings"), never "click here".
28
+ - Keep the underline in running text; a link without one has to sit in navigation where its role is obvious.
29
+
30
+ ## Client-side navigation
31
+ Wrap the app in `LinkProvider` with your router's link component (for example `next/link`) and internal links in `Link`, `Button`, `IconButton`, `Card`, `MediaCard`, `NavList`, `Breadcrumbs` and `ListItem` render with it. Hash, external, `mailto:` and `tel:` links, and links with `target` or `download`, stay plain `<a>`.
@@ -0,0 +1,21 @@
1
+ # List
2
+
3
+ Rows of records: people, files, notifications, recent items. Each `ListItem` has a leading element, a title and description, metadata and trailing actions.
4
+
5
+ ## Anatomy
6
+ 1. **Leading** (optional): an `Avatar`, `Icon` or small image.
7
+ 2. **Text**: title in `small` 500 `foreground` (truncates), description in 13px `muted-foreground`.
8
+ 3. **Meta** (optional): Space Grotesk 12px `muted-subtle`, such as a time or size.
9
+ 4. **Trailing** (optional): a `Badge`, a `Menu` or icon buttons.
10
+
11
+ ## Variants
12
+ - `divided` (default): 1px `border-subtle` rules between rows. `bordered`: an outline around the list.
13
+ - Interactive rows (`href` or `onClick`) get a `card-fill` hover and the inset focus ring; `selected` adds `primary-tint`.
14
+
15
+ ## Props
16
+ - `List`: `children`, `divided`, `bordered`, `label`, `as`.
17
+ - `ListItem`: `title`, `description`, `meta`, `leading`, `trailing`, `href`, `onClick`, `selected`.
18
+
19
+ ## Rules
20
+ - Keep the trailing slot to one or two controls; more goes in a `Menu`.
21
+ - For records people compare column by column, use `Table`.
@@ -0,0 +1,11 @@
1
+ # List and detail template
2
+
3
+ A record list with a toolbar and a table; choosing a record opens its details in a drawer, so people keep their place in the list.
4
+
5
+ ## Built from
6
+ `AppShell`, `PageHeader`, `SearchInput`, `SegmentedControl`, `Table` (selection, sorting, pagination), `Drawer`, `DescriptionList`, `Timeline`, `Badge`, `Menu`.
7
+
8
+ ## Rules
9
+ - One toolbar above the table: search on the left, view switches and filters on the right.
10
+ - Clicking a record's ID opens the drawer; row actions live in the row's `Menu`. Bulk actions appear in the toolbar once rows are selected.
11
+ - Paginate below the table with a summary ("1–5 of 12"). A filter with no results says so and offers to clear it.
@@ -0,0 +1,16 @@
1
+ # MediaCard
2
+
3
+ A card led by an image: a screenshot, a template, a document preview. It comes in two variants. `plain` sets the text directly under the image; `outlined` puts image and text in one bordered panel.
4
+
5
+ ## What you provide
6
+ - `title`, `image` (a real screenshot or render), `imageAlt` when the image carries information.
7
+ - `ratio`: the image box, `16 / 9` by default; screenshots of full apps often suit `16 / 10`.
8
+ - `eyebrow`, `meta` (a `·`-joined line such as "Updated 2h ago · 12 items"), `description`, `badge` (a status word).
9
+ - `href` makes the whole card a link; `linkLabel` adds a "label ↗" row. Links to other sites open in a new tab.
10
+ - `variant`: `plain` (default) or `outlined`. `as`: `li` inside a list.
11
+
12
+ ## Rules
13
+ - Lay out with `.vk-media-grid`: one column on phones, two from 40rem, three from 60rem.
14
+ - `meta` is `muted-subtle` uppercase; `description` is `muted-foreground`.
15
+ - On hover, a plain card scales its image to 1.04 and turns the link row `primary`; an outlined card warms its border to `primary-line`.
16
+ - Use real captures only. With no image the slot shows `media-placeholder`.
@@ -0,0 +1,45 @@
1
+ # Menu
2
+
3
+ A button that opens a list of actions: row actions in a table, "More" in a toolbar, a sort menu. Built on Radix DropdownMenu (non-modal: the page keeps scrolling and a click outside closes it and lands where it was aimed).
4
+
5
+ ## Anatomy
6
+ 1. **Trigger**: an outline `Button` with a chevron glyph cell (`label`), or an `IconButton` (`icon` with `triggerLabel`), usually `ellipsis`.
7
+ 2. **Panel**: `surface-elevated`, 1px `border`, square, at least 13rem wide, rendered in a portal at `z-popover` (so a scrolling table, dialog or drawer never clips it), 0.25rem below the trigger (above when there's no room), left- or right-aligned (`align="end"`), and scrolling when taller than the room it has. It fades and rises 0.5rem in over `motion-normal`; it closes at once.
8
+ 3. **Item**: 36px tall, an optional 16px icon in `muted-foreground`, label in `small`, an optional shortcut in Space Grotesk `muted-subtle`.
9
+ 4. **Separator**: 1px `border-subtle`. **Group label**: 11px uppercase `muted-subtle`.
10
+
11
+ ## Item states
12
+ | State | Treatment |
13
+ | --- | --- |
14
+ | Focused / hovered (`[data-highlighted]`) | `primary-tint` fill (keyboard focus also gets the `ring`) |
15
+ | Danger | text and icon `danger`; focus fill `danger-tint` |
16
+ | Disabled (`[data-disabled]`) | `muted-subtle`, skipped by arrow keys and typeahead |
17
+ | Submenu open (`[data-state="open"]`) | `primary-tint` fill on its item |
18
+
19
+ ## Keyboard
20
+ | Key | Action |
21
+ | --- | --- |
22
+ | Enter, Space, ↓ on the trigger | Opens on the first item |
23
+ | ↑ on the trigger | Opens on the last item |
24
+ | ↓ / ↑ | Next or previous item, wrapping |
25
+ | Home / End | First or last item |
26
+ | Letters | Jump to the next item starting with them; letters typed within a second build a prefix |
27
+ | Enter / Space | Run the item and close; `onSelect` runs once focus is back on the trigger |
28
+ | Esc | Close and return focus to the trigger |
29
+ | Tab | Close and move on |
30
+
31
+ ## Checkable items and submenus
32
+ - `{ type: 'checkbox', label, checked, onCheckedChange }`: a `menuitemcheckbox` with a check; choosing it calls `onCheckedChange(!checked)`, then `onSelect`, and keeps the menu open.
33
+ - `{ type: 'radio', label, checked, onSelect }`: a `menuitemradio` with a dot, for one choice from a group (sort order, density). Consecutive radio items form one `group`, named by a label entry right before them; choosing one keeps the menu open.
34
+ - `{ label, items: [...] }`: a submenu with a chevron; it opens to the right on hover, → or Enter, and ← or Esc goes back.
35
+
36
+ ## Accessibility
37
+ WAI-ARIA menu button: the trigger has `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`; the panel is `role="menu"`, labelled by the trigger, with `menuitem`s (`menuitemcheckbox` / `menuitemradio` with `aria-checked`) and a roving focus. Checkable items carry `data-state="checked"` or `"unchecked"`.
38
+
39
+ ## Props
40
+ - `items`: `{ label, onSelect, icon, shortcut, danger, disabled }`, checkable and submenu items as above, `{ type: 'separator' }` or `{ type: 'label', label }`.
41
+ - `label` or `icon` + `triggerLabel`, `variant`, `size`, `align`, `disabled`.
42
+
43
+ ## Rules
44
+ - Menus hold actions. To pick a value, use `Select`; to navigate, use links.
45
+ - Put destructive items last, after a separator, and confirm them with a `Dialog`.
@@ -0,0 +1,41 @@
1
+ # MultiSelect
2
+
3
+ Picks several options from a list. Choices show as removable `Tag`s inside the field, and typing filters the list. Its list is positioned by Radix Popover.
4
+
5
+ ## Anatomy
6
+ 1. **Field**: the `Input` box, growing to wrap its tags; 0.35rem between tags.
7
+ 2. **Tags**: one `Tag` per chosen option, each with a remove button.
8
+ 3. **Filter input**: after the tags, borderless, showing the placeholder only while nothing is chosen.
9
+ 4. **Chevron**: `chevron-down`, flipped while open.
10
+ 5. **List**: the `Select` panel with `aria-multiselectable`, placed like the `Combobox` list (Radix Popover, portalled; 4px under the field, at least as wide, flips above, shrinks to the room it has; `data-state`, `data-side`). Each option has a square check box like `Checkbox`, filled `primary` when chosen. Typed text is marked as in `Combobox`.
11
+
12
+ ## States
13
+ | Part | State | Treatment |
14
+ | --- | --- | --- |
15
+ | Field | Focus | `primary` edge and 2px `ring` around the whole field |
16
+ | Field | Invalid | `primary` edge |
17
+ | Field | Disabled | transparent, dashed edge; tags have no remove buttons |
18
+ | Option | Active | `primary-tint` fill |
19
+ | Option | Chosen | check box filled `primary` |
20
+ | Option | Disabled or over `max` | dashed box, `muted-subtle` text |
21
+
22
+ ## Keyboard
23
+ | Key | Action |
24
+ | --- | --- |
25
+ | Typing | Filters and opens the list |
26
+ | ↓ / ↑ | Opens, then moves through options |
27
+ | Enter (or Space with no text typed) | Toggles the active option; the list stays open |
28
+ | Backspace with no text | Removes the last tag |
29
+ | Esc | Closes the list; a second Esc clears the typed text |
30
+ | Tab | Closes and moves on |
31
+
32
+ Mouse: click anywhere in the field to open; click options to toggle; click a tag's `x` to remove it. The list stays open for clicks in the field, closes on a click outside, and focus stays in the input throughout.
33
+
34
+ ## Props
35
+ - `options`: strings or `{ value, label, description, disabled }`. `value` (array) + `onChange(values)`, or `defaultValue`.
36
+ - `max`: the most that can be chosen; further options are disabled. Say the limit in the `Field` hint.
37
+ - `placeholder`, `name` (one hidden input per value, all with that name), `emptyText`, `disabled`, `required`, `defaultOpen`.
38
+
39
+ ## Rules
40
+ - With fewer than about six options, a group of `Checkbox`es is clearer.
41
+ - Keep option labels short; they become tags.
@@ -0,0 +1,21 @@
1
+ # NavList
2
+
3
+ The vertical navigation for an app's sidebar: sections of links with icons, counts and the current page marked.
4
+
5
+ ## Anatomy
6
+ 1. **Section heading** (optional): 11px uppercase `muted-subtle`.
7
+ 2. **Item**: 36px tall, a 16px icon, label in `small` 500 in `muted-foreground`, an optional count in Space Grotesk `muted-subtle` on the right.
8
+ 3. **Current item**: `primary-tint` fill, `foreground` label, `primary` icon.
9
+
10
+ ## States
11
+ Hover: `card-fill` and `foreground`. Focus: the 2px `ring`, inset.
12
+
13
+ ## Props
14
+ - `items`: `{ label, href, icon, active, count }`, or `sections`: `{ heading, items }[]`. `label` (the nav's accessible name).
15
+
16
+ ## Accessibility
17
+ A `nav` landmark; the current page has `aria-current="page"`.
18
+
19
+ ## Rules
20
+ - Five to nine items per section; group the rest under headings.
21
+ - Every item has an icon or none do. Counts show only what needs attention (unread, open), not totals.