@askrjs/themes 0.0.1

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 (423) hide show
  1. package/LICENSE +201 -0
  2. package/THEMING.md +930 -0
  3. package/dist/_internal/box-layout.js +115 -0
  4. package/dist/_internal/box-layout.js.map +1 -0
  5. package/dist/_internal/classes.js +8 -0
  6. package/dist/_internal/classes.js.map +1 -0
  7. package/dist/_internal/jsx.js +12 -0
  8. package/dist/_internal/jsx.js.map +1 -0
  9. package/dist/_internal/layout.d.ts +9 -0
  10. package/dist/_internal/layout.js +156 -0
  11. package/dist/_internal/layout.js.map +1 -0
  12. package/dist/_internal/merge-props.js +50 -0
  13. package/dist/_internal/merge-props.js.map +1 -0
  14. package/dist/accessible-icon/accessible-icon.d.ts +7 -0
  15. package/dist/accessible-icon/accessible-icon.js +20 -0
  16. package/dist/accessible-icon/accessible-icon.js.map +1 -0
  17. package/dist/accessible-icon/accessible-icon.types.d.ts +9 -0
  18. package/dist/askr/dist/common/jsx.d.ts +16 -0
  19. package/dist/askr/dist/common/props.d.ts +22 -0
  20. package/dist/askr-themes/src/themes/default/index.css +3736 -0
  21. package/dist/aspect-ratio/aspect-ratio.d.ts +8 -0
  22. package/dist/aspect-ratio/aspect-ratio.js +36 -0
  23. package/dist/aspect-ratio/aspect-ratio.js.map +1 -0
  24. package/dist/aspect-ratio/aspect-ratio.types.d.ts +20 -0
  25. package/dist/aspect-ratio/index.d.ts +2 -0
  26. package/dist/badge/badge.d.ts +8 -0
  27. package/dist/badge/badge.js +26 -0
  28. package/dist/badge/badge.js.map +1 -0
  29. package/dist/badge/badge.types.d.ts +20 -0
  30. package/dist/badge/index.d.ts +2 -0
  31. package/dist/box/box.d.ts +9 -0
  32. package/dist/box/box.js +35 -0
  33. package/dist/box/box.js.map +1 -0
  34. package/dist/box/box.types.d.ts +71 -0
  35. package/dist/box/index.d.ts +2 -0
  36. package/dist/breadcrumb/breadcrumb.d.ts +18 -0
  37. package/dist/breadcrumb/breadcrumb.js +113 -0
  38. package/dist/breadcrumb/breadcrumb.js.map +1 -0
  39. package/dist/breadcrumb/breadcrumb.types.d.ts +64 -0
  40. package/dist/breadcrumb/index.d.ts +2 -0
  41. package/dist/card/card.d.ts +12 -0
  42. package/dist/card/card.js +68 -0
  43. package/dist/card/card.js.map +1 -0
  44. package/dist/card/card.types.d.ts +37 -0
  45. package/dist/card/index.d.ts +2 -0
  46. package/dist/components/_internal/box-layout.d.ts +7 -0
  47. package/dist/components/_internal/classes.d.ts +1 -0
  48. package/dist/components/_internal/jsx.d.ts +8 -0
  49. package/dist/components/_internal/layout.d.ts +31 -0
  50. package/dist/components/_internal/merge-props.d.ts +1 -0
  51. package/dist/components/_internal/style.d.ts +1 -0
  52. package/dist/components/accessible-icon/accessible-icon.d.ts +2 -0
  53. package/dist/components/accessible-icon/accessible-icon.types.d.ts +5 -0
  54. package/dist/components/accessible-icon/index.d.ts +2 -0
  55. package/dist/components/aspect-ratio/aspect-ratio.d.ts +3 -0
  56. package/dist/components/aspect-ratio/aspect-ratio.types.d.ts +15 -0
  57. package/dist/components/aspect-ratio/index.d.ts +2 -0
  58. package/dist/components/badge/badge.a11y.d.ts +13 -0
  59. package/dist/components/badge/badge.d.ts +3 -0
  60. package/dist/components/badge/badge.types.d.ts +15 -0
  61. package/dist/components/badge/index.d.ts +3 -0
  62. package/dist/components/box/box.a11y.d.ts +10 -0
  63. package/dist/components/box/box.d.ts +4 -0
  64. package/dist/components/box/box.types.d.ts +66 -0
  65. package/dist/components/box/index.d.ts +3 -0
  66. package/dist/components/breadcrumb/breadcrumb.a11y.d.ts +13 -0
  67. package/dist/components/breadcrumb/breadcrumb.d.ts +13 -0
  68. package/dist/components/breadcrumb/breadcrumb.types.d.ts +59 -0
  69. package/dist/components/breadcrumb/index.d.ts +3 -0
  70. package/dist/components/card/card.d.ts +7 -0
  71. package/dist/components/card/card.types.d.ts +33 -0
  72. package/dist/components/card/index.d.ts +2 -0
  73. package/dist/components/container/container.a11y.d.ts +16 -0
  74. package/dist/components/container/container.d.ts +3 -0
  75. package/dist/components/container/container.types.d.ts +29 -0
  76. package/dist/components/container/index.d.ts +3 -0
  77. package/dist/components/empty-state/empty-state.d.ts +2 -0
  78. package/dist/components/empty-state/empty-state.types.d.ts +9 -0
  79. package/dist/components/empty-state/index.d.ts +2 -0
  80. package/dist/components/flex/flex.a11y.d.ts +18 -0
  81. package/dist/components/flex/flex.d.ts +4 -0
  82. package/dist/components/flex/flex.types.d.ts +41 -0
  83. package/dist/components/flex/index.d.ts +3 -0
  84. package/dist/components/grid/grid.a11y.d.ts +21 -0
  85. package/dist/components/grid/grid.d.ts +4 -0
  86. package/dist/components/grid/grid.types.d.ts +37 -0
  87. package/dist/components/grid/index.d.ts +3 -0
  88. package/dist/components/header/header.a11y.d.ts +10 -0
  89. package/dist/components/header/header.d.ts +2 -0
  90. package/dist/components/header/header.types.d.ts +5 -0
  91. package/dist/components/header/index.d.ts +3 -0
  92. package/dist/components/index.d.ts +49 -0
  93. package/dist/components/index.js +28 -0
  94. package/dist/components/inline/index.d.ts +6 -0
  95. package/dist/components/logos/create-logo.d.ts +5 -0
  96. package/dist/components/logos/github-logo.d.ts +4 -0
  97. package/dist/components/logos/google-logo.d.ts +4 -0
  98. package/dist/components/logos/index.d.ts +5 -0
  99. package/dist/components/logos/microsoft-logo.d.ts +4 -0
  100. package/dist/components/logos/types.d.ts +14 -0
  101. package/dist/components/navbar/index.d.ts +2 -0
  102. package/dist/components/navbar/navbar.d.ts +6 -0
  103. package/dist/components/navbar/navbar.types.d.ts +24 -0
  104. package/dist/components/section/index.d.ts +3 -0
  105. package/dist/components/section/section.a11y.d.ts +11 -0
  106. package/dist/components/section/section.d.ts +3 -0
  107. package/dist/components/section/section.types.d.ts +17 -0
  108. package/dist/components/separator/index.d.ts +3 -0
  109. package/dist/components/separator/separator.a11y.d.ts +13 -0
  110. package/dist/components/separator/separator.d.ts +3 -0
  111. package/dist/components/separator/separator.types.d.ts +16 -0
  112. package/dist/components/sidebar-layout/index.d.ts +3 -0
  113. package/dist/components/sidebar-layout/sidebar-layout.a11y.d.ts +15 -0
  114. package/dist/components/sidebar-layout/sidebar-layout.d.ts +2 -0
  115. package/dist/components/sidebar-layout/sidebar-layout.types.d.ts +20 -0
  116. package/dist/components/skeleton/index.d.ts +3 -0
  117. package/dist/components/skeleton/skeleton.a11y.d.ts +12 -0
  118. package/dist/components/skeleton/skeleton.d.ts +3 -0
  119. package/dist/components/skeleton/skeleton.types.d.ts +13 -0
  120. package/dist/components/spacer/index.d.ts +3 -0
  121. package/dist/components/spacer/spacer.a11y.d.ts +13 -0
  122. package/dist/components/spacer/spacer.d.ts +3 -0
  123. package/dist/components/spacer/spacer.types.d.ts +24 -0
  124. package/dist/components/spinner/index.d.ts +2 -0
  125. package/dist/components/spinner/spinner.d.ts +2 -0
  126. package/dist/components/spinner/spinner.types.d.ts +5 -0
  127. package/dist/components/stack/index.d.ts +3 -0
  128. package/dist/components/stack/stack.a11y.d.ts +14 -0
  129. package/dist/components/stack/stack.d.ts +3 -0
  130. package/dist/components/stack/stack.types.d.ts +16 -0
  131. package/dist/components/theme/index.d.ts +2 -0
  132. package/dist/components/theme/theme.d.ts +40 -0
  133. package/dist/components/topbar-layout/index.d.ts +3 -0
  134. package/dist/components/topbar-layout/topbar-layout.a11y.d.ts +13 -0
  135. package/dist/components/topbar-layout/topbar-layout.d.ts +2 -0
  136. package/dist/components/topbar-layout/topbar-layout.types.d.ts +12 -0
  137. package/dist/container/container.d.ts +8 -0
  138. package/dist/container/container.js +82 -0
  139. package/dist/container/container.js.map +1 -0
  140. package/dist/container/container.types.d.ts +28 -0
  141. package/dist/container/index.d.ts +2 -0
  142. package/dist/empty-state/empty-state.d.ts +7 -0
  143. package/dist/empty-state/empty-state.js +39 -0
  144. package/dist/empty-state/empty-state.js.map +1 -0
  145. package/dist/empty-state/empty-state.types.d.ts +13 -0
  146. package/dist/flex/flex.d.ts +9 -0
  147. package/dist/flex/flex.js +114 -0
  148. package/dist/flex/flex.js.map +1 -0
  149. package/dist/flex/flex.types.d.ts +41 -0
  150. package/dist/flex/index.d.ts +2 -0
  151. package/dist/grid/grid.d.ts +9 -0
  152. package/dist/grid/grid.js +115 -0
  153. package/dist/grid/grid.js.map +1 -0
  154. package/dist/grid/grid.types.d.ts +40 -0
  155. package/dist/grid/index.d.ts +2 -0
  156. package/dist/header/header.d.ts +7 -0
  157. package/dist/header/header.js +18 -0
  158. package/dist/header/header.js.map +1 -0
  159. package/dist/header/header.types.d.ts +9 -0
  160. package/dist/inline/index.d.ts +7 -0
  161. package/dist/inline/index.js +13 -0
  162. package/dist/inline/index.js.map +1 -0
  163. package/dist/logos/create-logo.js +75 -0
  164. package/dist/logos/create-logo.js.map +1 -0
  165. package/dist/logos/github-logo.d.ts +18 -0
  166. package/dist/logos/github-logo.js +9 -0
  167. package/dist/logos/github-logo.js.map +1 -0
  168. package/dist/logos/google-logo.d.ts +18 -0
  169. package/dist/logos/google-logo.js +23 -0
  170. package/dist/logos/google-logo.js.map +1 -0
  171. package/dist/logos/microsoft-logo.d.ts +18 -0
  172. package/dist/logos/microsoft-logo.js +35 -0
  173. package/dist/logos/microsoft-logo.js.map +1 -0
  174. package/dist/logos/types.d.ts +16 -0
  175. package/dist/navbar/index.d.ts +2 -0
  176. package/dist/navbar/navbar.d.ts +11 -0
  177. package/dist/navbar/navbar.js +57 -0
  178. package/dist/navbar/navbar.js.map +1 -0
  179. package/dist/navbar/navbar.types.d.ts +29 -0
  180. package/dist/section/index.d.ts +2 -0
  181. package/dist/section/section.d.ts +8 -0
  182. package/dist/section/section.js +40 -0
  183. package/dist/section/section.js.map +1 -0
  184. package/dist/section/section.types.d.ts +22 -0
  185. package/dist/separator/index.d.ts +2 -0
  186. package/dist/separator/separator.d.ts +8 -0
  187. package/dist/separator/separator.js +27 -0
  188. package/dist/separator/separator.js.map +1 -0
  189. package/dist/separator/separator.types.d.ts +21 -0
  190. package/dist/sidebar-layout/index.d.ts +2 -0
  191. package/dist/sidebar-layout/sidebar-layout.d.ts +7 -0
  192. package/dist/sidebar-layout/sidebar-layout.js +51 -0
  193. package/dist/sidebar-layout/sidebar-layout.js.map +1 -0
  194. package/dist/sidebar-layout/sidebar-layout.types.d.ts +20 -0
  195. package/dist/skeleton/index.d.ts +2 -0
  196. package/dist/skeleton/skeleton.d.ts +8 -0
  197. package/dist/skeleton/skeleton.js +26 -0
  198. package/dist/skeleton/skeleton.js.map +1 -0
  199. package/dist/skeleton/skeleton.types.d.ts +18 -0
  200. package/dist/spacer/index.d.ts +2 -0
  201. package/dist/spacer/spacer.d.ts +8 -0
  202. package/dist/spacer/spacer.js +47 -0
  203. package/dist/spacer/spacer.js.map +1 -0
  204. package/dist/spacer/spacer.types.d.ts +25 -0
  205. package/dist/spinner/index.d.ts +2 -0
  206. package/dist/spinner/spinner.d.ts +7 -0
  207. package/dist/spinner/spinner.js +16 -0
  208. package/dist/spinner/spinner.js.map +1 -0
  209. package/dist/spinner/spinner.types.d.ts +10 -0
  210. package/dist/stack/index.d.ts +2 -0
  211. package/dist/stack/stack.d.ts +8 -0
  212. package/dist/stack/stack.js +16 -0
  213. package/dist/stack/stack.js.map +1 -0
  214. package/dist/stack/stack.types.d.ts +21 -0
  215. package/dist/theme/index.d.ts +1 -0
  216. package/dist/theme/theme.d.ts +44 -0
  217. package/dist/theme/theme.js +159 -0
  218. package/dist/theme/theme.js.map +1 -0
  219. package/dist/topbar-layout/index.d.ts +2 -0
  220. package/dist/topbar-layout/topbar-layout.d.ts +7 -0
  221. package/dist/topbar-layout/topbar-layout.js +37 -0
  222. package/dist/topbar-layout/topbar-layout.js.map +1 -0
  223. package/dist/topbar-layout/topbar-layout.types.d.ts +13 -0
  224. package/package.json +122 -0
  225. package/scripts/new-theme.js +87 -0
  226. package/src/askr-compat.d.ts +110 -0
  227. package/src/components/_internal/box-layout.ts +156 -0
  228. package/src/components/_internal/classes.ts +5 -0
  229. package/src/components/_internal/jsx.ts +141 -0
  230. package/src/components/_internal/layout.ts +223 -0
  231. package/src/components/_internal/merge-props.ts +89 -0
  232. package/src/components/_internal/style.ts +18 -0
  233. package/src/components/accessible-icon/accessible-icon.tsx +18 -0
  234. package/src/components/accessible-icon/accessible-icon.types.ts +5 -0
  235. package/src/components/accessible-icon/index.ts +2 -0
  236. package/src/components/aspect-ratio/aspect-ratio.tsx +48 -0
  237. package/src/components/aspect-ratio/aspect-ratio.types.ts +19 -0
  238. package/src/components/aspect-ratio/index.ts +2 -0
  239. package/src/components/badge/badge.a11y.ts +15 -0
  240. package/src/components/badge/badge.tsx +21 -0
  241. package/src/components/badge/badge.types.ts +27 -0
  242. package/src/components/badge/index.ts +3 -0
  243. package/src/components/box/box.a11y.ts +11 -0
  244. package/src/components/box/box.tsx +37 -0
  245. package/src/components/box/box.types.ts +75 -0
  246. package/src/components/box/index.ts +11 -0
  247. package/src/components/breadcrumb/breadcrumb.a11y.ts +15 -0
  248. package/src/components/breadcrumb/breadcrumb.tsx +123 -0
  249. package/src/components/breadcrumb/breadcrumb.types.ts +73 -0
  250. package/src/components/breadcrumb/index.ts +24 -0
  251. package/src/components/card/card.tsx +79 -0
  252. package/src/components/card/card.types.ts +40 -0
  253. package/src/components/card/index.ts +12 -0
  254. package/src/components/container/container.a11y.ts +17 -0
  255. package/src/components/container/container.tsx +139 -0
  256. package/src/components/container/container.types.ts +35 -0
  257. package/src/components/container/index.ts +9 -0
  258. package/src/components/empty-state/empty-state.tsx +42 -0
  259. package/src/components/empty-state/empty-state.types.ts +10 -0
  260. package/src/components/empty-state/index.ts +2 -0
  261. package/src/components/flex/flex.a11y.ts +19 -0
  262. package/src/components/flex/flex.tsx +160 -0
  263. package/src/components/flex/flex.types.ts +50 -0
  264. package/src/components/flex/index.ts +16 -0
  265. package/src/components/grid/grid.a11y.ts +22 -0
  266. package/src/components/grid/grid.tsx +172 -0
  267. package/src/components/grid/grid.types.ts +45 -0
  268. package/src/components/grid/index.ts +10 -0
  269. package/src/components/header/header.a11y.ts +11 -0
  270. package/src/components/header/header.tsx +18 -0
  271. package/src/components/header/header.types.ts +6 -0
  272. package/src/components/header/index.ts +3 -0
  273. package/src/components/index.ts +107 -0
  274. package/src/components/inline/index.tsx +28 -0
  275. package/src/components/logos/create-logo.tsx +103 -0
  276. package/src/components/logos/github-logo.tsx +13 -0
  277. package/src/components/logos/google-logo.tsx +34 -0
  278. package/src/components/logos/index.ts +5 -0
  279. package/src/components/logos/microsoft-logo.tsx +10 -0
  280. package/src/components/logos/types.ts +24 -0
  281. package/src/components/navbar/index.ts +9 -0
  282. package/src/components/navbar/navbar.tsx +59 -0
  283. package/src/components/navbar/navbar.types.ts +33 -0
  284. package/src/components/section/index.ts +8 -0
  285. package/src/components/section/section.a11y.ts +12 -0
  286. package/src/components/section/section.tsx +37 -0
  287. package/src/components/section/section.types.ts +22 -0
  288. package/src/components/separator/index.ts +12 -0
  289. package/src/components/separator/separator.a11y.ts +15 -0
  290. package/src/components/separator/separator.tsx +23 -0
  291. package/src/components/separator/separator.types.ts +21 -0
  292. package/src/components/sidebar-layout/index.ts +6 -0
  293. package/src/components/sidebar-layout/sidebar-layout.a11y.ts +16 -0
  294. package/src/components/sidebar-layout/sidebar-layout.tsx +59 -0
  295. package/src/components/sidebar-layout/sidebar-layout.types.ts +22 -0
  296. package/src/components/skeleton/index.ts +3 -0
  297. package/src/components/skeleton/skeleton.a11y.ts +14 -0
  298. package/src/components/skeleton/skeleton.tsx +21 -0
  299. package/src/components/skeleton/skeleton.types.ts +17 -0
  300. package/src/components/spacer/index.ts +9 -0
  301. package/src/components/spacer/spacer.a11y.ts +14 -0
  302. package/src/components/spacer/spacer.tsx +58 -0
  303. package/src/components/spacer/spacer.types.ts +30 -0
  304. package/src/components/spinner/index.ts +2 -0
  305. package/src/components/spinner/spinner.tsx +21 -0
  306. package/src/components/spinner/spinner.types.ts +7 -0
  307. package/src/components/stack/index.ts +3 -0
  308. package/src/components/stack/stack.a11y.ts +15 -0
  309. package/src/components/stack/stack.tsx +13 -0
  310. package/src/components/stack/stack.types.ts +21 -0
  311. package/src/components/theme/index.ts +10 -0
  312. package/src/components/theme/theme.tsx +260 -0
  313. package/src/components/topbar-layout/index.ts +3 -0
  314. package/src/components/topbar-layout/topbar-layout.a11y.ts +14 -0
  315. package/src/components/topbar-layout/topbar-layout.tsx +39 -0
  316. package/src/components/topbar-layout/topbar-layout.types.ts +13 -0
  317. package/src/css.d.ts +1 -0
  318. package/src/index.css +1 -0
  319. package/src/jsx.d.ts +23 -0
  320. package/src/themes/default/index.css +48 -0
  321. package/src/themes/default/styles/actions/button.css +196 -0
  322. package/src/themes/default/styles/actions/toggle-group.css +52 -0
  323. package/src/themes/default/styles/actions/toggle.css +44 -0
  324. package/src/themes/default/styles/base/icon.css +10 -0
  325. package/src/themes/default/styles/base/typography.css +208 -0
  326. package/src/themes/default/styles/base/utilities.css +223 -0
  327. package/src/themes/default/styles/disclosure/accordion.css +62 -0
  328. package/src/themes/default/styles/disclosure/collapsible.css +47 -0
  329. package/src/themes/default/styles/display/avatar.css +25 -0
  330. package/src/themes/default/styles/display/badge.css +51 -0
  331. package/src/themes/default/styles/display/card.css +53 -0
  332. package/src/themes/default/styles/display/coverage.css +248 -0
  333. package/src/themes/default/styles/display/progress-circle.css +18 -0
  334. package/src/themes/default/styles/display/progress.css +18 -0
  335. package/src/themes/default/styles/display/scroll-area.css +34 -0
  336. package/src/themes/default/styles/display/separator.css +15 -0
  337. package/src/themes/default/styles/display/skeleton.css +6 -0
  338. package/src/themes/default/styles/display/spinner.css +9 -0
  339. package/src/themes/default/styles/display/table.css +63 -0
  340. package/src/themes/default/styles/forms/checkbox.css +64 -0
  341. package/src/themes/default/styles/forms/form.css +5 -0
  342. package/src/themes/default/styles/forms/input.css +49 -0
  343. package/src/themes/default/styles/forms/label.css +6 -0
  344. package/src/themes/default/styles/forms/radio-group.css +53 -0
  345. package/src/themes/default/styles/forms/select.css +143 -0
  346. package/src/themes/default/styles/forms/slider.css +75 -0
  347. package/src/themes/default/styles/forms/switch.css +70 -0
  348. package/src/themes/default/styles/forms/textarea.css +37 -0
  349. package/src/themes/default/styles/layout/aspect-ratio.css +5 -0
  350. package/src/themes/default/styles/layout/dashboard-layout.css +15 -0
  351. package/src/themes/default/styles/layout/docs-layout.css +10 -0
  352. package/src/themes/default/styles/layout/layout.css +946 -0
  353. package/src/themes/default/styles/layout/patterns.css +43 -0
  354. package/src/themes/default/styles/layout/responsive-layout.css +209 -0
  355. package/src/themes/default/styles/layout/sidebar.css +10 -0
  356. package/src/themes/default/styles/navigation/breadcrumb.css +39 -0
  357. package/src/themes/default/styles/navigation/menu.css +60 -0
  358. package/src/themes/default/styles/navigation/menubar.css +89 -0
  359. package/src/themes/default/styles/navigation/navigation-menu.css +90 -0
  360. package/src/themes/default/styles/navigation/tabs.css +61 -0
  361. package/src/themes/default/styles/overlays/alert-dialog.css +9 -0
  362. package/src/themes/default/styles/overlays/dialog.css +116 -0
  363. package/src/themes/default/styles/overlays/dropdown-menu.css +109 -0
  364. package/src/themes/default/styles/overlays/hover-card.css +46 -0
  365. package/src/themes/default/styles/overlays/popover.css +72 -0
  366. package/src/themes/default/styles/overlays/toast.css +123 -0
  367. package/src/themes/default/styles/overlays/tooltip.css +83 -0
  368. package/src/themes/default/styles/shell/header.css +36 -0
  369. package/src/themes/default/styles/shell/navbar.css +158 -0
  370. package/src/themes/default/styles/shell/theme.css +35 -0
  371. package/src/themes/default/tokens.css +316 -0
  372. package/templates/theme/index.css +48 -0
  373. package/templates/theme/styles/actions/button.css +196 -0
  374. package/templates/theme/styles/actions/toggle-group.css +52 -0
  375. package/templates/theme/styles/actions/toggle.css +44 -0
  376. package/templates/theme/styles/base/icon.css +10 -0
  377. package/templates/theme/styles/base/typography.css +208 -0
  378. package/templates/theme/styles/base/utilities.css +19 -0
  379. package/templates/theme/styles/disclosure/accordion.css +62 -0
  380. package/templates/theme/styles/disclosure/collapsible.css +47 -0
  381. package/templates/theme/styles/display/avatar.css +25 -0
  382. package/templates/theme/styles/display/badge.css +51 -0
  383. package/templates/theme/styles/display/card.css +53 -0
  384. package/templates/theme/styles/display/coverage.css +146 -0
  385. package/templates/theme/styles/display/progress-circle.css +18 -0
  386. package/templates/theme/styles/display/progress.css +18 -0
  387. package/templates/theme/styles/display/scroll-area.css +34 -0
  388. package/templates/theme/styles/display/separator.css +15 -0
  389. package/templates/theme/styles/display/skeleton.css +6 -0
  390. package/templates/theme/styles/display/spinner.css +9 -0
  391. package/templates/theme/styles/display/table.css +63 -0
  392. package/templates/theme/styles/forms/checkbox.css +64 -0
  393. package/templates/theme/styles/forms/form.css +5 -0
  394. package/templates/theme/styles/forms/input.css +49 -0
  395. package/templates/theme/styles/forms/label.css +6 -0
  396. package/templates/theme/styles/forms/radio-group.css +53 -0
  397. package/templates/theme/styles/forms/select.css +143 -0
  398. package/templates/theme/styles/forms/slider.css +75 -0
  399. package/templates/theme/styles/forms/switch.css +70 -0
  400. package/templates/theme/styles/forms/textarea.css +37 -0
  401. package/templates/theme/styles/layout/aspect-ratio.css +5 -0
  402. package/templates/theme/styles/layout/dashboard-layout.css +16 -0
  403. package/templates/theme/styles/layout/docs-layout.css +11 -0
  404. package/templates/theme/styles/layout/layout.css +1 -0
  405. package/templates/theme/styles/layout/patterns.css +43 -0
  406. package/templates/theme/styles/layout/responsive-layout.css +209 -0
  407. package/templates/theme/styles/layout/sidebar.css +11 -0
  408. package/templates/theme/styles/navigation/breadcrumb.css +31 -0
  409. package/templates/theme/styles/navigation/menu.css +60 -0
  410. package/templates/theme/styles/navigation/menubar.css +89 -0
  411. package/templates/theme/styles/navigation/navigation-menu.css +90 -0
  412. package/templates/theme/styles/navigation/tabs.css +61 -0
  413. package/templates/theme/styles/overlays/alert-dialog.css +9 -0
  414. package/templates/theme/styles/overlays/dialog.css +116 -0
  415. package/templates/theme/styles/overlays/dropdown-menu.css +109 -0
  416. package/templates/theme/styles/overlays/hover-card.css +46 -0
  417. package/templates/theme/styles/overlays/popover.css +72 -0
  418. package/templates/theme/styles/overlays/toast.css +123 -0
  419. package/templates/theme/styles/overlays/tooltip.css +83 -0
  420. package/templates/theme/styles/shell/header.css +36 -0
  421. package/templates/theme/styles/shell/navbar.css +158 -0
  422. package/templates/theme/styles/shell/theme.css +35 -0
  423. package/templates/theme/tokens.css +316 -0
package/THEMING.md ADDED
@@ -0,0 +1,930 @@
1
+ # Theming
2
+
3
+ Import a theme:
4
+
5
+ ```css
6
+ @import "@askrjs/themes/default";
7
+ ```
8
+
9
+ Pick a mode on an ancestor:
10
+
11
+ ```html
12
+ <html data-theme="light"></html>
13
+ <html data-theme="dark"></html>
14
+ ```
15
+
16
+ Token override:
17
+
18
+ ```css
19
+ :root {
20
+ --ak-color-primary: purple;
21
+ --ak-radius-md: 12px;
22
+ }
23
+ ```
24
+
25
+ Style override:
26
+
27
+ ```css
28
+ :where(.btn-primary, [data-slot="button"][data-variant="primary"]) {
29
+ background: black;
30
+ }
31
+ ```
32
+
33
+ Icon override:
34
+
35
+ ```css
36
+ [data-slot="icon"][data-size="sm"] {
37
+ --ak-icon-size-sm: 0.875rem;
38
+ --ak-icon-stroke-width-sm: 1.5;
39
+ }
40
+ ```
41
+
42
+ Rules: style only public data-\* hooks, never internal DOM, no deep selectors, no !important.
43
+
44
+ Selector contract:
45
+
46
+ - Tokens keep the `--ak-*` prefix because they are global.
47
+ - `askr-ui` public hooks are canonical: `data-slot`, `data-state`, `data-disabled`, `data-orientation`, `data-variant`, and `data-size`.
48
+ - `askr-themes` may expose simple kebab-case class aliases for high-value authoring shortcuts such as `.btn`, `.btn-primary`, `.card`, `.input`, and `.badge-success`.
49
+ - Alias selectors must be grouped with canonical selectors in the same low-specificity rule. Classes are convenience API, not a replacement source of truth.
50
+ - Theme-owned pattern components use plain kebab-case classes such as `.page-header`, and public pattern parts should emit matching `data-slot` hooks so the same grouped selector pattern applies there as well.
51
+ - Semantic `askr-ui` table primitives are styled from `styles/display/table.css` using their `data-slot` hooks only; keep the surface semantic and avoid restoring data-grid behavior in themes.
52
+
53
+ Example:
54
+
55
+ ```css
56
+ :where(.page-header, [data-slot="page-header"]) {
57
+ display: flex;
58
+ }
59
+
60
+ :where(.page-header-title, [data-slot="page-header-title"]) {
61
+ font-size: var(--ak-type-7-size);
62
+ }
63
+ ```
64
+
65
+ Package boundaries:
66
+
67
+ - `@askrjs/askr` owns what exists and when.
68
+ - `@askrjs/ui` owns behavior, state, focus, and ARIA coordination.
69
+ - `@askrjs/themes` owns visual-only components, layout composition, and
70
+ default styling.
71
+
72
+ Use `@askrjs/themes/components` for styled components such as Button, Box,
73
+ Stack, Inline, Flex, Grid, Container, Section, Spacer, Badge, Skeleton,
74
+ Separator/Divider, SidebarLayout, TopbarLayout, and EmptyState.
75
+
76
+ Theme state helpers also live there: `ThemeProvider`, `ThemePicker`,
77
+ `ThemeToggle`, and `useTheme`. `ThemeToggle` intentionally has no built-in
78
+ icons; applications pass their own icon/content props.
79
+
80
+ Responsive rules:
81
+
82
+ - Build mobile first. Base selectors must work on narrow screens; larger layouts are additive via `min-width` media queries.
83
+ - The default theme uses semantic breakpoints `sm`, `md`, `lg`, and `xl` for `data-collapse-below`.
84
+ - Keep breakpoint values centralized in theme tokens so the default theme and generated themes stay aligned.
85
+ - Responsive behavior must target only public hooks such as `data-collapse-below`, `data-columns`, `data-min-item-width`, `data-gap`, `data-sidebar-position`, and `data-sidebar-width`.
86
+ - Prefer token overrides first. Reach for component CSS overrides only when tokens are insufficient.
87
+ - Keep selectors low-specificity so a custom theme can override a rule with one equally specific selector. `:where(...)` is preferred for the default theme baseline.
88
+ - Broad layout slots like `main`, `sidebar`, and `navbar` must always be anchored to a public layout root such as `topbar-layout` or `sidebar-layout`.
89
+ - Named layout hooks such as `data-size`, `data-max-width`, `data-padding`, `data-gap`, and `data-sidebar-width` are part of the public theme contract and should resolve through theme tokens rather than hard-coded values.
90
+ - Icons are part of the public theme contract. `@askrjs/ui` owns the canonical icon hooks, and official icon wrappers should implement that contract by emitting `data-slot="icon"`, `data-icon`, semantic `data-size`, and `data-decorative` so themes can style them uniformly across icon sets.
91
+ - Icon size and stroke defaults should resolve through the shared icon tokens: `--ak-icon-size-sm|md|lg|xl` and `--ak-icon-stroke-width-sm|md|lg|xl`.
92
+ - Product SaaS scaffolds should compose broad visual primitives first. Keep first-class pattern exports general; put narrow dashboard, auth, or table-page recipes in docs/examples unless they prove reusable across apps. Recipe shells such as product-style or marketing-style page wrappers belong in userland composition, not the shipped theme package.
93
+ - Comfortable density is tokenized through `--ak-density-control-height-*` and `--ak-density-control-padding-x-*`; apps should tune those before overriding component CSS.
94
+ - Future class aliases must be added selectively with contract tests; do not mirror every internal slot as a class by default.
95
+
96
+ ## Token Contract
97
+
98
+ Version: 1.0 draft
99
+
100
+ This document defines the default theme token contract for `askr-themes`.
101
+
102
+ The purpose of this token set is to provide a stable, reusable semantic theming layer for:
103
+
104
+ - `askr-ui` headless components
105
+ - application shell layouts
106
+ - docs layouts
107
+ - admin dashboards
108
+ - forms
109
+ - tables
110
+ - navigation
111
+ - overlays and interactive surfaces
112
+
113
+ This contract is intentionally semantic, not component-specific.
114
+
115
+ ---
116
+
117
+ ## Goals
118
+
119
+ The token system must:
120
+
121
+ - support both light and dark themes
122
+ - theme headless UI primitives consistently
123
+ - optimize for admin and internal tools by default
124
+ - avoid hardcoded component styling
125
+ - provide enough semantic coverage for real apps
126
+ - remain small enough to be maintainable
127
+ - separate visual tokens from component implementation
128
+
129
+ ---
130
+
131
+ ## Non-Goals
132
+
133
+ This spec does not:
134
+
135
+ - define component-specific tokens for every widget
136
+ - mandate one visual style
137
+ - require every theme to look the same
138
+ - require all apps to use every token directly
139
+ - optimize the default theme for highly branded marketing sites
140
+
141
+ ---
142
+
143
+ ## Design Principles
144
+
145
+ 1. Prefer semantic tokens over raw visual tokens.
146
+ 2. Prefer a restrained, reusable token set over many one-off tokens.
147
+ 3. The default theme should favor admin UI, docs UI, dashboards, CRUD flows, and settings surfaces.
148
+ 4. `askr-ui` components should consume semantic tokens, not hardcoded values.
149
+ 5. Theme blocks should only override theme-dependent values.
150
+ 6. Layout, spacing, typography scale, icon scale, and breakpoints belong in the global root unless intentionally themed.
151
+ 7. Default visual choices should reduce end-user design decisions: one accent, subtle borders, compact density, restrained radius, and minimal decorative styling.
152
+ 8. The default theme should stay crisp and low-noise, closer to a shadcn-style baseline than a glossy decorative system.
153
+
154
+ ---
155
+
156
+ ## Token Layers
157
+
158
+ The token contract is split into these layers:
159
+
160
+ 1. Color semantics
161
+ 2. Typography
162
+ 3. Spacing
163
+ 4. Radius
164
+ 5. Borders
165
+ 6. Shadows
166
+ 7. Focus
167
+ 8. Motion
168
+ 9. Icons
169
+ 10. Layout
170
+ 11. Z-index
171
+
172
+ ---
173
+
174
+ ## Naming Rules
175
+
176
+ All official tokens use the `--ak-` prefix.
177
+
178
+ Categories:
179
+
180
+ - `--ak-color-*`
181
+ - `--ak-font-*`
182
+ - `--ak-space-*`
183
+ - `--ak-radius-*`
184
+ - `--ak-border-*`
185
+ - `--ak-shadow-*`
186
+ - `--ak-focus-*`
187
+ - `--ak-duration-*`
188
+ - `--ak-ease-*`
189
+ - `--ak-icon-*`
190
+ - `--ak-breakpoint-*`
191
+ - `--ak-layout-*`
192
+ - `--ak-z-*`
193
+
194
+ Rules:
195
+
196
+ - Use `text` instead of `fg`
197
+ - Use `text-muted` instead of generic `muted`
198
+ - Use `surface` for UI surfaces
199
+ - Use `bg` only for the global app background
200
+ - Use `soft` for low-emphasis tinted backgrounds
201
+ - Use `ink` for readable foreground color placed on a soft/status background
202
+ - Use `subtle`, `default`, and `strong` when a three-step ladder is needed
203
+ - Use `hover`, `active`, `selected`, and `disabled` for interaction semantics
204
+
205
+ ---
206
+
207
+ ## Required Tokens
208
+
209
+ ### 1. Color Tokens
210
+
211
+ These are required for the default theme and any future theme reintroduced to the package.
212
+
213
+ #### Brand / Accent
214
+
215
+ - `--ak-color-primary`
216
+ - `--ak-color-primary-hover`
217
+ - `--ak-color-primary-active`
218
+ - `--ak-color-primary-soft`
219
+ - `--ak-color-primary-ink`
220
+
221
+ #### Text
222
+
223
+ - `--ak-color-text`
224
+ - `--ak-color-text-muted`
225
+ - `--ak-color-text-subtle`
226
+ - `--ak-color-text-inverse`
227
+
228
+ #### Background / Surface
229
+
230
+ - `--ak-color-bg`
231
+ - `--ak-color-surface`
232
+ - `--ak-color-surface-muted`
233
+ - `--ak-color-surface-raised`
234
+ - `--ak-color-surface-overlay`
235
+
236
+ #### Borders
237
+
238
+ - `--ak-color-border-subtle`
239
+ - `--ak-color-border`
240
+ - `--ak-color-border-strong`
241
+
242
+ #### Status
243
+
244
+ - `--ak-color-success`
245
+ - `--ak-color-success-soft`
246
+ - `--ak-color-success-ink`
247
+ - `--ak-color-warning`
248
+ - `--ak-color-warning-soft`
249
+ - `--ak-color-warning-ink`
250
+ - `--ak-color-danger`
251
+ - `--ak-color-danger-soft`
252
+ - `--ak-color-danger-ink`
253
+ - `--ak-color-info`
254
+ - `--ak-color-info-soft`
255
+ - `--ak-color-info-ink`
256
+
257
+ #### Links / Focus / Selection / Disabled / Overlay
258
+
259
+ - `--ak-color-link`
260
+ - `--ak-color-link-hover`
261
+ - `--ak-color-focus-ring`
262
+ - `--ak-color-disabled-bg`
263
+ - `--ak-color-disabled-surface`
264
+ - `--ak-color-disabled-border`
265
+ - `--ak-color-disabled-text`
266
+ - `--ak-color-selected`
267
+ - `--ak-color-selected-border`
268
+ - `--ak-color-hover`
269
+ - `--ak-color-active`
270
+ - `--ak-color-backdrop`
271
+
272
+ ---
273
+
274
+ ### 2. Typography Tokens
275
+
276
+ Required:
277
+
278
+ - `--ak-font-family-body`
279
+ - `--ak-font-family-mono`
280
+ - `--ak-font-size-xs`
281
+ - `--ak-font-size-sm`
282
+ - `--ak-font-size-md`
283
+ - `--ak-font-size-lg`
284
+ - `--ak-font-size-xl`
285
+ - `--ak-font-size-2xl`
286
+ - `--ak-font-size-heading`
287
+ - `--ak-font-size-display`
288
+ - `--ak-font-weight-regular`
289
+ - `--ak-font-weight-medium`
290
+ - `--ak-font-weight-semibold`
291
+ - `--ak-font-weight-bold`
292
+ - `--ak-line-height-tight`
293
+ - `--ak-line-height-normal`
294
+ - `--ak-line-height-relaxed`
295
+
296
+ ---
297
+
298
+ ### 3. Spacing Tokens
299
+
300
+ Required:
301
+
302
+ - `--ak-space-xs`
303
+ - `--ak-space-sm`
304
+ - `--ak-space-md`
305
+ - `--ak-space-lg`
306
+ - `--ak-space-xl`
307
+ - `--ak-space-2xl`
308
+ - `--ak-space-3xl`
309
+
310
+ ---
311
+
312
+ ### 4. Radius Tokens
313
+
314
+ Required:
315
+
316
+ - `--ak-radius-sm`
317
+ - `--ak-radius-md`
318
+ - `--ak-radius-lg`
319
+ - `--ak-radius-xl`
320
+ - `--ak-radius-round`
321
+
322
+ ---
323
+
324
+ ### 5. Border Tokens
325
+
326
+ Required:
327
+
328
+ - `--ak-border-width-sm`
329
+ - `--ak-border-width-md`
330
+
331
+ ---
332
+
333
+ ### 6. Shadow Tokens
334
+
335
+ Required:
336
+
337
+ - `--ak-shadow-sm`
338
+ - `--ak-shadow-md`
339
+ - `--ak-shadow-lg`
340
+
341
+ Themes may keep shadows extremely subtle, but they must still provide these tokens.
342
+
343
+ ---
344
+
345
+ ### 7. Focus Tokens
346
+
347
+ Required:
348
+
349
+ - `--ak-focus-ring-width`
350
+ - `--ak-focus-ring-offset`
351
+
352
+ ---
353
+
354
+ ### 8. Motion Tokens
355
+
356
+ Required:
357
+
358
+ - `--ak-duration-fast`
359
+ - `--ak-duration-normal`
360
+ - `--ak-duration-slow`
361
+ - `--ak-ease-standard`
362
+
363
+ ---
364
+
365
+ ### 9. Icon Tokens
366
+
367
+ Required:
368
+
369
+ - `--ak-icon-size-sm`
370
+ - `--ak-icon-size-md`
371
+ - `--ak-icon-size-lg`
372
+ - `--ak-icon-size-xl`
373
+ - `--ak-icon-stroke-width-sm`
374
+ - `--ak-icon-stroke-width-md`
375
+ - `--ak-icon-stroke-width-lg`
376
+ - `--ak-icon-stroke-width-xl`
377
+
378
+ ---
379
+
380
+ ### 10. Layout Tokens
381
+
382
+ Required:
383
+
384
+ - `--ak-breakpoint-sm`
385
+ - `--ak-breakpoint-md`
386
+ - `--ak-breakpoint-lg`
387
+ - `--ak-breakpoint-xl`
388
+ - `--ak-layout-navbar-height`
389
+ - `--ak-layout-sidebar-width-sm`
390
+ - `--ak-layout-sidebar-width-md`
391
+ - `--ak-layout-sidebar-width-lg`
392
+ - `--ak-layout-sidebar-width-xl`
393
+ - `--ak-layout-sidebar-width`
394
+ - `--ak-layout-content-max-width`
395
+ - `--ak-layout-page-gutter`
396
+ - `--ak-layout-panel-padding`
397
+
398
+ ---
399
+
400
+ ### 11. Z-Index Tokens
401
+
402
+ Required:
403
+
404
+ - `--ak-z-dropdown`
405
+ - `--ak-z-sticky`
406
+ - `--ak-z-fixed`
407
+ - `--ak-z-modal-backdrop`
408
+ - `--ak-z-modal`
409
+ - `--ak-z-popover`
410
+ - `--ak-z-toast`
411
+ - `--ak-z-tooltip`
412
+
413
+ ---
414
+
415
+ ## Optional Tokens
416
+
417
+ These may be added later if justified by real usage, but are not part of the minimum required contract:
418
+
419
+ - `--ak-color-link-visited`
420
+ - `--ak-color-selection`
421
+ - `--ak-color-selection-text`
422
+ - `--ak-shadow-xl`
423
+ - `--ak-duration-instant`
424
+ - `--ak-ease-emphasized`
425
+ - `--ak-layout-header-blur`
426
+ - `--ak-border-width-lg`
427
+
428
+ Do not add optional tokens until there is a clear cross-component need.
429
+
430
+ ---
431
+
432
+ ## Global vs Theme-Scoped Tokens
433
+
434
+ ### Global root tokens
435
+
436
+ These should normally be defined once in `:root`:
437
+
438
+ - typography scale
439
+ - spacing scale
440
+ - radius scale
441
+ - border widths
442
+ - shadow scale
443
+ - focus ring dimensions
444
+ - motion values
445
+ - icon scale
446
+ - breakpoints
447
+ - layout sizes
448
+ - z-index layers
449
+
450
+ ### Theme-scoped tokens
451
+
452
+ These should normally be defined per theme:
453
+
454
+ - all color tokens
455
+ - `color-scheme`
456
+
457
+ A theme may override non-color tokens only when the design intentionally changes them.
458
+
459
+ ---
460
+
461
+ ## Required Consumption Rules for askr-ui
462
+
463
+ `askr-ui` must consume semantic tokens, not raw colors or app-specific styling.
464
+
465
+ ### Correct usage examples
466
+
467
+ Button:
468
+
469
+ - background uses `--ak-color-primary`
470
+ - hover uses `--ak-color-primary-hover`
471
+ - active uses `--ak-color-primary-active`
472
+ - focus uses `--ak-color-focus-ring`
473
+ - disabled styles use disabled tokens
474
+
475
+ Card:
476
+
477
+ - background uses `--ak-color-surface`
478
+ - border uses `--ak-color-border`
479
+ - raised card may use `--ak-color-surface-raised`
480
+
481
+ Muted text:
482
+
483
+ - use `--ak-color-text-muted`
484
+
485
+ Selected nav item:
486
+
487
+ - background uses `--ak-color-selected`
488
+ - border or indicator uses `--ak-color-selected-border`
489
+
490
+ Status badge:
491
+
492
+ - success badge uses `success`, `success-soft`, `success-ink`
493
+ - warning badge uses `warning`, `warning-soft`, `warning-ink`
494
+ - danger badge uses `danger`, `danger-soft`, `danger-ink`
495
+ - info badge uses `info`, `info-soft`, `info-ink`
496
+
497
+ Dialog backdrop:
498
+
499
+ - use `--ak-color-backdrop`
500
+
501
+ ### Incorrect usage examples
502
+
503
+ Do not:
504
+
505
+ - hardcode hex values inside components
506
+ - use `primary` for warning/danger semantics
507
+ - use border colors as text colors
508
+ - derive component styling from unrelated tokens
509
+ - invent one-off component colors inside `askr-ui`
510
+
511
+ ---
512
+
513
+ ## Semantic Meaning of Key Tokens
514
+
515
+ ### Primary
516
+
517
+ The main brand/accent color used for primary actions, active highlights, selected emphasis, and interactive accenting.
518
+
519
+ ### Soft
520
+
521
+ A low-emphasis tinted background, typically used for selected items, badges, soft alerts, and subtle emphasis.
522
+
523
+ ### Ink
524
+
525
+ Readable foreground color intended to sit on a soft or tinted background.
526
+
527
+ ### Surface
528
+
529
+ The default UI container surface.
530
+
531
+ ### Surface Muted
532
+
533
+ A lower-emphasis surface used to distinguish nested or grouped regions.
534
+
535
+ ### Surface Raised
536
+
537
+ A slightly elevated surface used for cards, dropdowns, or overlays that need more separation than default surface.
538
+
539
+ ### Surface Overlay
540
+
541
+ The surface color for overlay UI such as popovers, menus, and dialog panels when composited over the app.
542
+
543
+ ### Border Subtle / Border / Border Strong
544
+
545
+ - subtle: low-emphasis separators
546
+ - border: standard control and card border
547
+ - strong: emphasized dividers, active frames, or stronger chrome
548
+
549
+ ### Text / Text Muted / Text Subtle / Text Inverse
550
+
551
+ - text: default readable foreground
552
+ - text-muted: secondary information
553
+ - text-subtle: tertiary or very quiet metadata
554
+ - text-inverse: text placed on strong/dark/accent backgrounds
555
+
556
+ ### Hover / Active
557
+
558
+ Generic interaction overlays for neutral interactive surfaces.
559
+
560
+ ### Selected
561
+
562
+ Selection state for tabs, nav items, rows, or toggles.
563
+
564
+ ### Disabled
565
+
566
+ Disabled semantic ladder for background, surface, border, and text.
567
+
568
+ ---
569
+
570
+ ## Invariants
571
+
572
+ The default theme and any future reintroduced themes must satisfy these invariants:
573
+
574
+ 1. `--ak-color-text` must be readable on `--ak-color-bg`
575
+ 2. `--ak-color-text` must be readable on `--ak-color-surface`
576
+ 3. `--ak-color-text-muted` must remain readable for secondary content
577
+ 4. `--ak-color-text-inverse` must be readable on `--ak-color-primary`
578
+ 5. `--ak-color-primary-ink` must be readable on `--ak-color-primary-soft`
579
+ 6. each status `*-ink` must be readable on its corresponding `*-soft`
580
+ 7. borders must remain visible against adjacent surfaces
581
+ 8. focus ring must remain visible on both bg and surface contexts
582
+ 9. disabled text must appear visually disabled without becoming unreadable
583
+ 10. backdrop must provide sufficient separation for modal surfaces
584
+ 11. hover and active states must remain perceptible but restrained
585
+ 12. selected state must be visually distinct from hover state
586
+
587
+ ---
588
+
589
+ ## Recommended Defaults
590
+
591
+ These are recommended implementation defaults for component authors:
592
+
593
+ - default body text: `--ak-color-text`
594
+ - secondary text: `--ak-color-text-muted`
595
+ - tertiary text: `--ak-color-text-subtle`
596
+ - page background: `--ak-color-bg`
597
+ - panel/card background: `--ak-color-surface`
598
+ - subdued section background: `--ak-color-surface-muted`
599
+ - stronger card/popover background: `--ak-color-surface-raised`
600
+ - overlay panel background: `--ak-color-surface-overlay`
601
+ - standard border: `--ak-color-border`
602
+ - subtle divider: `--ak-color-border-subtle`
603
+ - strong emphasis border: `--ak-color-border-strong`
604
+
605
+ ---
606
+
607
+ ## Reference Theme Template
608
+
609
+ ```css
610
+ /* __THEME_NAME__ theme */
611
+
612
+ :root {
613
+ /* typography */
614
+ --ak-font-family-body: system-ui, sans-serif;
615
+ --ak-font-family-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
616
+
617
+ --ak-font-size-xs: 0.75rem;
618
+ --ak-font-size-sm: 0.875rem;
619
+ --ak-font-size-md: 1rem;
620
+ --ak-font-size-lg: 1.125rem;
621
+ --ak-font-size-xl: 1.25rem;
622
+ --ak-font-size-2xl: 1.5rem;
623
+
624
+ --ak-font-weight-regular: 400;
625
+ --ak-font-weight-medium: 500;
626
+ --ak-font-weight-semibold: 600;
627
+ --ak-font-weight-bold: 700;
628
+
629
+ --ak-line-height-tight: 1.2;
630
+ --ak-line-height-normal: 1.5;
631
+ --ak-line-height-relaxed: 1.7;
632
+
633
+ /* spacing */
634
+ --ak-space-xs: 0.25rem;
635
+ --ak-space-sm: 0.5rem;
636
+ --ak-space-md: 0.75rem;
637
+ --ak-space-lg: 1rem;
638
+ --ak-space-xl: 1.5rem;
639
+ --ak-space-2xl: 2rem;
640
+ --ak-space-3xl: 3rem;
641
+
642
+ /* radius */
643
+ --ak-radius-sm: 6px;
644
+ --ak-radius-md: 10px;
645
+ --ak-radius-lg: 14px;
646
+ --ak-radius-xl: 22px;
647
+ --ak-radius-round: 9999px;
648
+
649
+ /* borders */
650
+ --ak-border-width-sm: 1px;
651
+ --ak-border-width-md: 2px;
652
+
653
+ /* shadows */
654
+ --ak-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
655
+ --ak-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
656
+ --ak-shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.16);
657
+
658
+ /* focus */
659
+ --ak-focus-ring-width: 3px;
660
+ --ak-focus-ring-offset: 2px;
661
+
662
+ /* motion */
663
+ --ak-duration-fast: 120ms;
664
+ --ak-duration-normal: 180ms;
665
+ --ak-duration-slow: 280ms;
666
+ --ak-ease-standard: ease;
667
+
668
+ /* icons */
669
+ --ak-icon-size-sm: 1rem;
670
+ --ak-icon-size-md: 1.25rem;
671
+ --ak-icon-size-lg: 1.5rem;
672
+ --ak-icon-size-xl: 1.75rem;
673
+ --ak-icon-stroke-width-sm: 1.75;
674
+ --ak-icon-stroke-width-md: 2;
675
+ --ak-icon-stroke-width-lg: 2;
676
+ --ak-icon-stroke-width-xl: 2.25;
677
+
678
+ /* layout */
679
+ --ak-breakpoint-sm: 40rem;
680
+ --ak-breakpoint-md: 48rem;
681
+ --ak-breakpoint-lg: 64rem;
682
+ --ak-breakpoint-xl: 80rem;
683
+ --ak-layout-navbar-height: 56px;
684
+ --ak-layout-sidebar-width-sm: 14rem;
685
+ --ak-layout-sidebar-width-md: 16rem;
686
+ --ak-layout-sidebar-width-lg: 20rem;
687
+ --ak-layout-sidebar-width-xl: 24rem;
688
+ --ak-layout-sidebar-width: 16.25rem;
689
+ --ak-layout-content-max-width: 75rem;
690
+
691
+ /* stacking */
692
+ --ak-z-dropdown: 1000;
693
+ --ak-z-sticky: 1100;
694
+ --ak-z-fixed: 1200;
695
+ --ak-z-modal-backdrop: 1300;
696
+ --ak-z-modal: 1400;
697
+ --ak-z-popover: 1500;
698
+ --ak-z-toast: 1550;
699
+ --ak-z-tooltip: 1600;
700
+ }
701
+
702
+ :root,
703
+ [data-theme="light"] {
704
+ --ak-color-primary: #79b53f;
705
+ --ak-color-primary-hover: #5f9132;
706
+ --ak-color-primary-active: #4f792b;
707
+ --ak-color-primary-soft: #e5efd5;
708
+ --ak-color-primary-ink: #29411a;
709
+
710
+ --ak-color-text: #2f2b2a;
711
+ --ak-color-text-muted: #716660;
712
+ --ak-color-text-subtle: #8b8178;
713
+ --ak-color-text-inverse: #fffdfa;
714
+
715
+ --ak-color-bg: #f5f1ea;
716
+ --ak-color-surface: #fffdfa;
717
+ --ak-color-surface-muted: #ece5da;
718
+ --ak-color-surface-raised: #ffffff;
719
+ --ak-color-surface-overlay: rgba(255, 253, 250, 0.92);
720
+
721
+ --ak-color-border-subtle: #ddd4c7;
722
+ --ak-color-border: #cbbfb0;
723
+ --ak-color-border-strong: #a99987;
724
+
725
+ --ak-color-success: #3b8f57;
726
+ --ak-color-success-soft: rgba(59, 143, 87, 0.16);
727
+ --ak-color-success-ink: #163b22;
728
+ --ak-color-warning: #b7791f;
729
+ --ak-color-warning-soft: rgba(183, 121, 31, 0.16);
730
+ --ak-color-warning-ink: #4c320c;
731
+ --ak-color-danger: #b45a5a;
732
+ --ak-color-danger-soft: rgba(180, 90, 90, 0.18);
733
+ --ak-color-danger-ink: #4a1f1f;
734
+ --ak-color-info: #3a78b8;
735
+ --ak-color-info-soft: rgba(58, 120, 184, 0.16);
736
+ --ak-color-info-ink: #18324d;
737
+
738
+ --ak-color-link: var(--ak-color-primary);
739
+ --ak-color-link-hover: var(--ak-color-primary-hover);
740
+ --ak-color-focus-ring: rgba(121, 181, 63, 0.28);
741
+ --ak-color-disabled-bg: #e7dfd3;
742
+ --ak-color-disabled-surface: #f1ebe3;
743
+ --ak-color-disabled-border: #d7ccbe;
744
+ --ak-color-disabled-text: #9c9187;
745
+ --ak-color-selected: #e5efd5;
746
+ --ak-color-selected-border: #b8d38f;
747
+ --ak-color-hover: rgba(47, 43, 42, 0.04);
748
+ --ak-color-active: rgba(47, 43, 42, 0.08);
749
+ --ak-color-backdrop: rgba(25, 20, 18, 0.45);
750
+
751
+ color-scheme: light;
752
+ }
753
+
754
+ [data-theme="dark"] {
755
+ --ak-color-primary: #9bd45f;
756
+ --ak-color-primary-hover: #7eb448;
757
+ --ak-color-primary-active: #6a983d;
758
+ --ak-color-primary-soft: rgba(155, 212, 95, 0.18);
759
+ --ak-color-primary-ink: #d9efbf;
760
+
761
+ --ak-color-text: #e8e1d8;
762
+ --ak-color-text-muted: #b8aea2;
763
+ --ak-color-text-subtle: #94897d;
764
+ --ak-color-text-inverse: #1f2225;
765
+
766
+ --ak-color-bg: #1f2225;
767
+ --ak-color-surface: #2a2e31;
768
+ --ak-color-surface-muted: #34393d;
769
+ --ak-color-surface-raised: #3a4044;
770
+ --ak-color-surface-overlay: rgba(42, 46, 49, 0.92);
771
+
772
+ --ak-color-border-subtle: #49443d;
773
+ --ak-color-border: #565048;
774
+ --ak-color-border-strong: #746b61;
775
+
776
+ --ak-color-success: #6fca88;
777
+ --ak-color-success-soft: rgba(111, 202, 136, 0.18);
778
+ --ak-color-success-ink: #d6f3de;
779
+ --ak-color-warning: #e0ad52;
780
+ --ak-color-warning-soft: rgba(224, 173, 82, 0.18);
781
+ --ak-color-warning-ink: #fff0cf;
782
+ --ak-color-danger: #df8d8d;
783
+ --ak-color-danger-soft: rgba(223, 141, 141, 0.18);
784
+ --ak-color-danger-ink: #ffe2e2;
785
+ --ak-color-info: #7eb2eb;
786
+ --ak-color-info-soft: rgba(126, 178, 235, 0.18);
787
+ --ak-color-info-ink: #e2f0ff;
788
+
789
+ --ak-color-link: var(--ak-color-primary);
790
+ --ak-color-link-hover: var(--ak-color-primary-hover);
791
+ --ak-color-focus-ring: rgba(155, 212, 95, 0.3);
792
+ --ak-color-disabled-bg: #303438;
793
+ --ak-color-disabled-surface: #2b2f33;
794
+ --ak-color-disabled-border: #444a4f;
795
+ --ak-color-disabled-text: #7f776e;
796
+ --ak-color-selected: rgba(155, 212, 95, 0.18);
797
+ --ak-color-selected-border: #7eb448;
798
+ --ak-color-hover: rgba(232, 225, 216, 0.05);
799
+ --ak-color-active: rgba(232, 225, 216, 0.1);
800
+ --ak-color-backdrop: rgba(0, 0, 0, 0.55);
801
+
802
+ color-scheme: dark;
803
+ }
804
+ ```
805
+
806
+ ## Component Variants
807
+
808
+ Components support variant styling through `data-variant` and `data-size` attributes.
809
+
810
+ ### Button Variants
811
+
812
+ ```html
813
+ <button data-slot="button" data-variant="primary">Primary</button>
814
+ <button data-slot="button" data-variant="secondary">Secondary</button>
815
+ <button data-slot="button" data-variant="outline">Outline</button>
816
+ <button data-slot="button" data-variant="ghost">Ghost</button>
817
+ <button data-slot="button" data-variant="destructive">Destructive</button>
818
+ <button data-slot="button" data-variant="link">Link</button>
819
+ ```
820
+
821
+ ### Button Sizes
822
+
823
+ ```html
824
+ <button data-slot="button" data-size="sm">Small</button>
825
+ <button data-slot="button">Default (md)</button>
826
+ <button data-slot="button" data-size="lg">Large</button>
827
+ <button data-slot="button" data-size="icon">Icon</button>
828
+ ```
829
+
830
+ ### Badge Variants
831
+
832
+ ```html
833
+ <span data-slot="badge">Default</span>
834
+ <span data-slot="badge" data-variant="secondary">Secondary</span>
835
+ <span data-slot="badge" data-variant="outline">Outline</span>
836
+ <span data-slot="badge" data-variant="success">Success</span>
837
+ <span data-slot="badge" data-variant="warning">Warning</span>
838
+ <span data-slot="badge" data-variant="danger">Danger</span>
839
+ <span data-slot="badge" data-variant="info">Info</span>
840
+ ```
841
+
842
+ ### Toast Variants
843
+
844
+ ```html
845
+ <div data-slot="toast" data-variant="success">Success toast</div>
846
+ <div data-slot="toast" data-variant="warning">Warning toast</div>
847
+ <div data-slot="toast" data-variant="danger">Danger toast</div>
848
+ <div data-slot="toast" data-variant="info">Info toast</div>
849
+ ```
850
+
851
+ ### Customizing Variants
852
+
853
+ Override variant styles using the same selector pattern:
854
+
855
+ ```css
856
+ [data-slot="button"][data-variant="primary"] {
857
+ background: linear-gradient(135deg, var(--ak-color-primary), var(--ak-color-primary-hover));
858
+ }
859
+ ```
860
+
861
+ ---
862
+
863
+ ## Animations
864
+
865
+ Overlay components include enter/exit animations using `@keyframes` and motion tokens:
866
+
867
+ - **Dialog**: fade-in overlay + scale-in content
868
+ - **Popover/Dropdown/Select**: slide-up with fade
869
+ - **Tooltip**: subtle slide-up
870
+ - **Toast**: slide-in from right
871
+
872
+ All animations use `--ak-duration-fast` and `--ak-duration-normal` tokens. To customize:
873
+
874
+ ```css
875
+ :root {
876
+ --ak-duration-fast: 80ms; /* snappier */
877
+ --ak-duration-normal: 150ms;
878
+ }
879
+ ```
880
+
881
+ Exit animations are triggered via `[data-state='closed']` selectors.
882
+
883
+ ---
884
+
885
+ ## Accessibility
886
+
887
+ ### Reduced Motion
888
+
889
+ All themes respect `prefers-reduced-motion`. When enabled, all duration tokens are set to `0s`:
890
+
891
+ ```css
892
+ @media (prefers-reduced-motion: reduce) {
893
+ :root {
894
+ --ak-duration-fast: 0s;
895
+ --ak-duration-normal: 0s;
896
+ --ak-duration-slow: 0s;
897
+ }
898
+ }
899
+ ```
900
+
901
+ ### Automatic Dark Mode
902
+
903
+ When no `data-theme` attribute is set, themes auto-detect OS preference:
904
+
905
+ ```css
906
+ @media (prefers-color-scheme: dark) {
907
+ :root:not([data-theme]) {
908
+ /* dark color tokens applied automatically */
909
+ }
910
+ }
911
+ ```
912
+
913
+ Explicit `data-theme="light"` or `data-theme="dark"` always takes precedence.
914
+
915
+ ### WCAG Contrast
916
+
917
+ All official themes are tested for WCAG AA compliance:
918
+
919
+ - Text on backgrounds: 4.5:1 minimum
920
+ - UI components and large text: 3:1 minimum
921
+ - Status ink on soft backgrounds: 3:1 minimum
922
+ - Inverse text on primary: 4.5:1 minimum
923
+
924
+ The automated test suite (`tests/contrast.test.ts`) validates these pairs across all themes in both light and dark modes.
925
+
926
+ ---
927
+
928
+ ## Implementation Note
929
+
930
+ The v1.0 contract above is the current semantic surface. Default theme component CSS now consumes the semantic token names directly. Shipped CSS still publishes temporary compatibility aliases such as `--ak-color-fg`, `--ak-color-muted`, and `--ak-font-family` for downstream compatibility, but those aliases are not part of the required contract and should not be used for new work.