tyrell-components 1.0.0-TC8 → 1.0.0-rc.21

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 (386) hide show
  1. package/AGENTS.md +122 -0
  2. package/CHANGELOG.md +1531 -0
  3. package/README.md +71 -53
  4. package/css/tyrell-colors-static.css +1 -0
  5. package/css/tyrell-theme.css +1 -0
  6. package/css/tyrell.css +1 -1783
  7. package/dist/tyrell-colors-static.css +1 -0
  8. package/dist/tyrell-theme.css +1 -0
  9. package/dist/tyrell.css +1 -1783
  10. package/dist/tyrell.js +1 -1
  11. package/guides/AGENT_INSTRUCTIONS.md +124 -0
  12. package/guides/AI_GUIDE.md +53 -0
  13. package/guides/CSS_GUIDE.md +1016 -0
  14. package/guides/DATASTAR_TY_GUIDE.md +657 -0
  15. package/guides/ICONS_GUIDE.md +212 -0
  16. package/guides/TY_GUIDE.md +935 -0
  17. package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
  18. package/guides/clj/CODE_SPLITTING.md +279 -0
  19. package/guides/clj/COMPONENT_GUIDE.md +391 -0
  20. package/guides/clj/HELIX_TY_GUIDE.md +428 -0
  21. package/guides/clj/I18N_GUIDE.md +478 -0
  22. package/guides/clj/LAYOUT_GUIDE.md +273 -0
  23. package/guides/clj/QUICKSTART.md +266 -0
  24. package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
  25. package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
  26. package/guides/clj/ROUTING_GUIDE.md +346 -0
  27. package/guides/clj/UIX_TY_GUIDE.md +319 -0
  28. package/guides/js/HTMX_TY_GUIDE.md +252 -0
  29. package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
  30. package/guides/js/REACT_TY_GUIDE.md +983 -0
  31. package/guides/js/SVELTE_TY_GUIDE.md +682 -0
  32. package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
  33. package/guides/js/VUE_TY_GUIDE.md +738 -0
  34. package/lib/base/ty-component.d.ts +57 -13
  35. package/lib/base/ty-component.js +266 -292
  36. package/lib/components/button.d.ts +42 -18
  37. package/lib/components/button.js +318 -235
  38. package/lib/components/calendar-month.d.ts +30 -47
  39. package/lib/components/calendar-month.js +455 -429
  40. package/lib/components/calendar-navigation.d.ts +41 -49
  41. package/lib/components/calendar-navigation.js +287 -346
  42. package/lib/components/calendar.d.ts +73 -83
  43. package/lib/components/calendar.js +837 -762
  44. package/lib/components/checkbox.d.ts +26 -75
  45. package/lib/components/checkbox.js +298 -391
  46. package/lib/components/copy.d.ts +20 -60
  47. package/lib/components/copy.js +276 -380
  48. package/lib/components/date-picker.d.ts +100 -183
  49. package/lib/components/date-picker.js +1155 -1570
  50. package/lib/components/file-upload.d.ts +122 -0
  51. package/lib/components/file-upload.js +451 -0
  52. package/lib/components/icon.d.ts +3 -24
  53. package/lib/components/icon.js +141 -230
  54. package/lib/components/input.d.ts +93 -108
  55. package/lib/components/input.js +734 -710
  56. package/lib/components/modal.d.ts +39 -29
  57. package/lib/components/modal.js +419 -438
  58. package/lib/components/option.d.ts +20 -35
  59. package/lib/components/option.js +184 -309
  60. package/lib/components/popup.d.ts +2 -17
  61. package/lib/components/popup.js +353 -347
  62. package/lib/components/radio.d.ts +33 -25
  63. package/lib/components/radio.js +433 -422
  64. package/lib/components/resize-observer.d.ts +3 -30
  65. package/lib/components/resize-observer.js +71 -103
  66. package/lib/components/scroll-container.d.ts +21 -14
  67. package/lib/components/scroll-container.js +292 -234
  68. package/lib/components/select.d.ts +446 -0
  69. package/lib/components/select.js +1381 -0
  70. package/lib/components/selected-tags.d.ts +60 -0
  71. package/lib/components/selected-tags.js +225 -0
  72. package/lib/components/sortable.d.ts +175 -0
  73. package/lib/components/sortable.js +1844 -0
  74. package/lib/components/step.d.ts +1 -6
  75. package/lib/components/step.js +62 -68
  76. package/lib/components/switch.d.ts +15 -15
  77. package/lib/components/switch.js +237 -231
  78. package/lib/components/tab.d.ts +50 -7
  79. package/lib/components/tab.js +203 -69
  80. package/lib/components/tabs.d.ts +19 -64
  81. package/lib/components/tabs.js +600 -618
  82. package/lib/components/tag.d.ts +17 -55
  83. package/lib/components/tag.js +235 -308
  84. package/lib/components/textarea.d.ts +58 -89
  85. package/lib/components/textarea.js +523 -573
  86. package/lib/components/tooltip.d.ts +8 -13
  87. package/lib/components/tooltip.js +322 -409
  88. package/lib/components/wizard.d.ts +7 -54
  89. package/lib/components/wizard.js +376 -606
  90. package/lib/icons/fontawesome/brands.d.ts +0 -1
  91. package/lib/icons/fontawesome/brands.js +0 -8
  92. package/lib/icons/fontawesome/regular.d.ts +0 -1
  93. package/lib/icons/fontawesome/regular.js +0 -8
  94. package/lib/icons/fontawesome/solid.d.ts +0 -1
  95. package/lib/icons/fontawesome/solid.js +0 -8
  96. package/lib/icons/heroicons/micro.d.ts +0 -1
  97. package/lib/icons/heroicons/micro.js +392 -400
  98. package/lib/icons/heroicons/mini.d.ts +0 -1
  99. package/lib/icons/heroicons/mini.js +382 -390
  100. package/lib/icons/heroicons/outline.d.ts +0 -1
  101. package/lib/icons/heroicons/outline.js +337 -345
  102. package/lib/icons/heroicons/solid.d.ts +0 -1
  103. package/lib/icons/heroicons/solid.js +407 -415
  104. package/lib/icons/lucide.d.ts +0 -1
  105. package/lib/icons/lucide.js +24479 -26351
  106. package/lib/icons/material/filled.d.ts +0 -1
  107. package/lib/icons/material/filled.js +9653 -9663
  108. package/lib/icons/material/outlined.d.ts +0 -1
  109. package/lib/icons/material/outlined.js +10271 -10281
  110. package/lib/icons/material/round.d.ts +0 -1
  111. package/lib/icons/material/round.js +10495 -10505
  112. package/lib/icons/material/sharp.d.ts +0 -1
  113. package/lib/icons/material/sharp.js +9905 -9915
  114. package/lib/icons/material/two-tone.d.ts +0 -1
  115. package/lib/icons/material/two-tone.js +12792 -12802
  116. package/lib/index.d.ts +15 -4
  117. package/lib/index.js +28 -38
  118. package/lib/styles/button.d.ts +24 -7
  119. package/lib/styles/button.js +298 -417
  120. package/lib/styles/calendar-month.d.ts +7 -6
  121. package/lib/styles/calendar-month.js +157 -179
  122. package/lib/styles/calendar-navigation.d.ts +2 -6
  123. package/lib/styles/calendar-navigation.js +108 -109
  124. package/lib/styles/calendar.d.ts +3 -3
  125. package/lib/styles/calendar.js +87 -23
  126. package/lib/styles/checkbox.d.ts +7 -6
  127. package/lib/styles/checkbox.js +101 -15
  128. package/lib/styles/copy.d.ts +3 -2
  129. package/lib/styles/copy.js +91 -71
  130. package/lib/styles/custom-scrollbar.d.ts +1 -2
  131. package/lib/styles/custom-scrollbar.js +80 -115
  132. package/lib/styles/date-picker.d.ts +4 -6
  133. package/lib/styles/date-picker.js +320 -352
  134. package/lib/styles/field-size.d.ts +6 -0
  135. package/lib/styles/field-size.js +91 -0
  136. package/lib/styles/file-upload.d.ts +1 -0
  137. package/lib/styles/file-upload.js +196 -0
  138. package/lib/styles/icon.d.ts +2 -6
  139. package/lib/styles/icon.js +92 -170
  140. package/lib/styles/input.d.ts +4 -7
  141. package/lib/styles/input.js +148 -643
  142. package/lib/styles/modal.d.ts +1 -2
  143. package/lib/styles/modal.js +127 -108
  144. package/lib/styles/option.d.ts +2 -6
  145. package/lib/styles/option.js +53 -96
  146. package/lib/styles/popup.d.ts +1 -2
  147. package/lib/styles/popup.js +47 -77
  148. package/lib/styles/radio.d.ts +3 -2
  149. package/lib/styles/radio.js +90 -116
  150. package/lib/styles/resize-observer.d.ts +1 -2
  151. package/lib/styles/resize-observer.js +2 -12
  152. package/lib/styles/scroll-container.d.ts +1 -2
  153. package/lib/styles/scroll-container.js +103 -146
  154. package/lib/styles/select-base.d.ts +8 -0
  155. package/lib/styles/select-base.js +747 -0
  156. package/lib/styles/select.d.ts +11 -0
  157. package/lib/styles/select.js +229 -0
  158. package/lib/styles/sortable.d.ts +16 -0
  159. package/lib/styles/sortable.js +85 -0
  160. package/lib/styles/step.d.ts +1 -2
  161. package/lib/styles/step.js +15 -34
  162. package/lib/styles/switch.d.ts +3 -2
  163. package/lib/styles/switch.js +52 -68
  164. package/lib/styles/tab.d.ts +1 -2
  165. package/lib/styles/tab.js +86 -34
  166. package/lib/styles/tabs.d.ts +3 -11
  167. package/lib/styles/tabs.js +204 -162
  168. package/lib/styles/tag.d.ts +2 -6
  169. package/lib/styles/tag.js +170 -359
  170. package/lib/styles/textarea.d.ts +1 -2
  171. package/lib/styles/textarea.js +238 -306
  172. package/lib/styles/tooltip.d.ts +4 -3
  173. package/lib/styles/tooltip.js +3 -131
  174. package/lib/styles/wizard.d.ts +8 -20
  175. package/lib/styles/wizard.js +306 -295
  176. package/lib/types/common.d.ts +9 -8
  177. package/lib/types/common.js +8 -5
  178. package/lib/utils/calendar-utils.d.ts +49 -65
  179. package/lib/utils/calendar-utils.js +158 -343
  180. package/lib/utils/custom-scrollbar.d.ts +6 -20
  181. package/lib/utils/custom-scrollbar.js +273 -317
  182. package/lib/utils/flavor-sheet.d.ts +31 -0
  183. package/lib/utils/flavor-sheet.js +17 -0
  184. package/lib/utils/icon-registry.d.ts +0 -15
  185. package/lib/utils/icon-registry.js +138 -279
  186. package/lib/utils/icons.d.ts +9 -0
  187. package/lib/utils/icons.js +1 -0
  188. package/lib/utils/loader-registry.d.ts +34 -0
  189. package/lib/utils/loader-registry.js +11 -0
  190. package/lib/utils/locale.d.ts +2 -80
  191. package/lib/utils/locale.js +30 -205
  192. package/lib/utils/mobile.d.ts +0 -1
  193. package/lib/utils/mobile.js +1 -18
  194. package/lib/utils/number-format.d.ts +6 -24
  195. package/lib/utils/number-format.js +53 -136
  196. package/lib/utils/positioning.d.ts +72 -22
  197. package/lib/utils/positioning.js +224 -298
  198. package/lib/utils/property-capture.d.ts +5 -27
  199. package/lib/utils/property-capture.js +36 -144
  200. package/lib/utils/property-manager.d.ts +6 -6
  201. package/lib/utils/property-manager.js +127 -196
  202. package/lib/utils/resize-observer.d.ts +0 -1
  203. package/lib/utils/resize-observer.js +23 -59
  204. package/lib/utils/scroll-lock.d.ts +10 -11
  205. package/lib/utils/scroll-lock.js +165 -173
  206. package/lib/utils/styles.d.ts +0 -6
  207. package/lib/utils/styles.js +17 -48
  208. package/lib/utils/upgrade-properties.d.ts +21 -0
  209. package/lib/utils/upgrade-properties.js +47 -0
  210. package/lib/utils/validity.d.ts +122 -0
  211. package/lib/utils/validity.js +289 -0
  212. package/lib/version.d.ts +1 -2
  213. package/lib/version.js +1 -11
  214. package/package.json +66 -18
  215. package/lib/base/ty-component.d.ts.map +0 -1
  216. package/lib/base/ty-component.js.map +0 -1
  217. package/lib/components/button.d.ts.map +0 -1
  218. package/lib/components/button.js.map +0 -1
  219. package/lib/components/calendar-month.d.ts.map +0 -1
  220. package/lib/components/calendar-month.js.map +0 -1
  221. package/lib/components/calendar-navigation.d.ts.map +0 -1
  222. package/lib/components/calendar-navigation.js.map +0 -1
  223. package/lib/components/calendar.d.ts.map +0 -1
  224. package/lib/components/calendar.js.map +0 -1
  225. package/lib/components/checkbox.d.ts.map +0 -1
  226. package/lib/components/checkbox.js.map +0 -1
  227. package/lib/components/copy.d.ts.map +0 -1
  228. package/lib/components/copy.js.map +0 -1
  229. package/lib/components/date-picker.d.ts.map +0 -1
  230. package/lib/components/date-picker.js.map +0 -1
  231. package/lib/components/dropdown.d.ts +0 -402
  232. package/lib/components/dropdown.d.ts.map +0 -1
  233. package/lib/components/dropdown.js +0 -1564
  234. package/lib/components/dropdown.js.map +0 -1
  235. package/lib/components/icon.d.ts.map +0 -1
  236. package/lib/components/icon.js.map +0 -1
  237. package/lib/components/input.d.ts.map +0 -1
  238. package/lib/components/input.js.map +0 -1
  239. package/lib/components/modal.d.ts.map +0 -1
  240. package/lib/components/modal.js.map +0 -1
  241. package/lib/components/multiselect.d.ts +0 -397
  242. package/lib/components/multiselect.d.ts.map +0 -1
  243. package/lib/components/multiselect.js +0 -1580
  244. package/lib/components/multiselect.js.map +0 -1
  245. package/lib/components/option.d.ts.map +0 -1
  246. package/lib/components/option.js.map +0 -1
  247. package/lib/components/popup.d.ts.map +0 -1
  248. package/lib/components/popup.js.map +0 -1
  249. package/lib/components/radio.d.ts.map +0 -1
  250. package/lib/components/radio.js.map +0 -1
  251. package/lib/components/resize-observer.d.ts.map +0 -1
  252. package/lib/components/resize-observer.js.map +0 -1
  253. package/lib/components/scroll-container.d.ts.map +0 -1
  254. package/lib/components/scroll-container.js.map +0 -1
  255. package/lib/components/step.d.ts.map +0 -1
  256. package/lib/components/step.js.map +0 -1
  257. package/lib/components/switch.d.ts.map +0 -1
  258. package/lib/components/switch.js.map +0 -1
  259. package/lib/components/tab.d.ts.map +0 -1
  260. package/lib/components/tab.js.map +0 -1
  261. package/lib/components/tabs.d.ts.map +0 -1
  262. package/lib/components/tabs.js.map +0 -1
  263. package/lib/components/tag.d.ts.map +0 -1
  264. package/lib/components/tag.js.map +0 -1
  265. package/lib/components/textarea.d.ts.map +0 -1
  266. package/lib/components/textarea.js.map +0 -1
  267. package/lib/components/tooltip.d.ts.map +0 -1
  268. package/lib/components/tooltip.js.map +0 -1
  269. package/lib/components/wizard.d.ts.map +0 -1
  270. package/lib/components/wizard.js.map +0 -1
  271. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  272. package/lib/icons/fontawesome/brands.js.map +0 -1
  273. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  274. package/lib/icons/fontawesome/regular.js.map +0 -1
  275. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  276. package/lib/icons/fontawesome/solid.js.map +0 -1
  277. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  278. package/lib/icons/heroicons/micro.js.map +0 -1
  279. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  280. package/lib/icons/heroicons/mini.js.map +0 -1
  281. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  282. package/lib/icons/heroicons/outline.js.map +0 -1
  283. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  284. package/lib/icons/heroicons/solid.js.map +0 -1
  285. package/lib/icons/lucide.d.ts.map +0 -1
  286. package/lib/icons/lucide.js.map +0 -1
  287. package/lib/icons/material/filled.d.ts.map +0 -1
  288. package/lib/icons/material/filled.js.map +0 -1
  289. package/lib/icons/material/outlined.d.ts.map +0 -1
  290. package/lib/icons/material/outlined.js.map +0 -1
  291. package/lib/icons/material/round.d.ts.map +0 -1
  292. package/lib/icons/material/round.js.map +0 -1
  293. package/lib/icons/material/sharp.d.ts.map +0 -1
  294. package/lib/icons/material/sharp.js.map +0 -1
  295. package/lib/icons/material/two-tone.d.ts.map +0 -1
  296. package/lib/icons/material/two-tone.js.map +0 -1
  297. package/lib/index.d.ts.map +0 -1
  298. package/lib/index.js.map +0 -1
  299. package/lib/styles/button.d.ts.map +0 -1
  300. package/lib/styles/button.js.map +0 -1
  301. package/lib/styles/calendar-month.d.ts.map +0 -1
  302. package/lib/styles/calendar-month.js.map +0 -1
  303. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  304. package/lib/styles/calendar-navigation.js.map +0 -1
  305. package/lib/styles/calendar.d.ts.map +0 -1
  306. package/lib/styles/calendar.js.map +0 -1
  307. package/lib/styles/checkbox.d.ts.map +0 -1
  308. package/lib/styles/checkbox.js.map +0 -1
  309. package/lib/styles/copy.d.ts.map +0 -1
  310. package/lib/styles/copy.js.map +0 -1
  311. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  312. package/lib/styles/custom-scrollbar.js.map +0 -1
  313. package/lib/styles/date-picker.d.ts.map +0 -1
  314. package/lib/styles/date-picker.js.map +0 -1
  315. package/lib/styles/dropdown.d.ts +0 -12
  316. package/lib/styles/dropdown.d.ts.map +0 -1
  317. package/lib/styles/dropdown.js +0 -983
  318. package/lib/styles/dropdown.js.map +0 -1
  319. package/lib/styles/icon.d.ts.map +0 -1
  320. package/lib/styles/icon.js.map +0 -1
  321. package/lib/styles/input.d.ts.map +0 -1
  322. package/lib/styles/input.js.map +0 -1
  323. package/lib/styles/modal.d.ts.map +0 -1
  324. package/lib/styles/modal.js.map +0 -1
  325. package/lib/styles/multiselect.d.ts +0 -6
  326. package/lib/styles/multiselect.d.ts.map +0 -1
  327. package/lib/styles/multiselect.js +0 -774
  328. package/lib/styles/multiselect.js.map +0 -1
  329. package/lib/styles/option.d.ts.map +0 -1
  330. package/lib/styles/option.js.map +0 -1
  331. package/lib/styles/popup.d.ts.map +0 -1
  332. package/lib/styles/popup.js.map +0 -1
  333. package/lib/styles/radio.d.ts.map +0 -1
  334. package/lib/styles/radio.js.map +0 -1
  335. package/lib/styles/resize-observer.d.ts.map +0 -1
  336. package/lib/styles/resize-observer.js.map +0 -1
  337. package/lib/styles/scroll-container.d.ts.map +0 -1
  338. package/lib/styles/scroll-container.js.map +0 -1
  339. package/lib/styles/step.d.ts.map +0 -1
  340. package/lib/styles/step.js.map +0 -1
  341. package/lib/styles/switch.d.ts.map +0 -1
  342. package/lib/styles/switch.js.map +0 -1
  343. package/lib/styles/tab.d.ts.map +0 -1
  344. package/lib/styles/tab.js.map +0 -1
  345. package/lib/styles/tabs.d.ts.map +0 -1
  346. package/lib/styles/tabs.js.map +0 -1
  347. package/lib/styles/tag.d.ts.map +0 -1
  348. package/lib/styles/tag.js.map +0 -1
  349. package/lib/styles/textarea.d.ts.map +0 -1
  350. package/lib/styles/textarea.js.map +0 -1
  351. package/lib/styles/tooltip.d.ts.map +0 -1
  352. package/lib/styles/tooltip.js.map +0 -1
  353. package/lib/styles/wizard.d.ts.map +0 -1
  354. package/lib/styles/wizard.js.map +0 -1
  355. package/lib/types/common.d.ts.map +0 -1
  356. package/lib/types/common.js.map +0 -1
  357. package/lib/utils/calendar-utils.d.ts.map +0 -1
  358. package/lib/utils/calendar-utils.js.map +0 -1
  359. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  360. package/lib/utils/custom-scrollbar.js.map +0 -1
  361. package/lib/utils/icon-registry.d.ts.map +0 -1
  362. package/lib/utils/icon-registry.js.map +0 -1
  363. package/lib/utils/locale.d.ts.map +0 -1
  364. package/lib/utils/locale.js.map +0 -1
  365. package/lib/utils/mobile.d.ts.map +0 -1
  366. package/lib/utils/mobile.js.map +0 -1
  367. package/lib/utils/number-format.d.ts.map +0 -1
  368. package/lib/utils/number-format.js.map +0 -1
  369. package/lib/utils/parse-boolean.d.ts +0 -39
  370. package/lib/utils/parse-boolean.d.ts.map +0 -1
  371. package/lib/utils/parse-boolean.js +0 -58
  372. package/lib/utils/parse-boolean.js.map +0 -1
  373. package/lib/utils/positioning.d.ts.map +0 -1
  374. package/lib/utils/positioning.js.map +0 -1
  375. package/lib/utils/property-capture.d.ts.map +0 -1
  376. package/lib/utils/property-capture.js.map +0 -1
  377. package/lib/utils/property-manager.d.ts.map +0 -1
  378. package/lib/utils/property-manager.js.map +0 -1
  379. package/lib/utils/resize-observer.d.ts.map +0 -1
  380. package/lib/utils/resize-observer.js.map +0 -1
  381. package/lib/utils/scroll-lock.d.ts.map +0 -1
  382. package/lib/utils/scroll-lock.js.map +0 -1
  383. package/lib/utils/styles.d.ts.map +0 -1
  384. package/lib/utils/styles.js.map +0 -1
  385. package/lib/version.d.ts.map +0 -1
  386. package/lib/version.js.map +0 -1
@@ -0,0 +1,1016 @@
1
+ # Tyrell CSS System
2
+
3
+ Tyrell classes handle colors. Use Tailwind for everything else (spacing, layout, typography, sizing).
4
+
5
+ ## Surfaces vs Backgrounds
6
+
7
+ **Surfaces** are for layout areas — cards, panels, sidebars, modals, page background, form fields:
8
+
9
+ ```html
10
+ <div class="ty-canvas"> <!-- App background -->
11
+ <div class="ty-content"> <!-- Main content area -->
12
+ <div class="ty-elevated"> <!-- Cards, panels (with shadow) -->
13
+ <div class="ty-floating"> <!-- Modals, dropdowns (with shadow) -->
14
+ <div class="ty-input"> <!-- Form controls background -->
15
+ ```
16
+
17
+ **Backgrounds** are for small accents inside a surface — alert and callout boxes, a highlighted row, a status dot. Buttons, tags and badges are components (`ty-button`, `ty-tag`), never `div`s with a background class:
18
+
19
+ ```html
20
+ <div class="ty-bg-warning-"> <!-- Callout -->
21
+ <div class="ty-bg-success-"> <!-- Success alert -->
22
+ <div class="ty-bg-danger"> <!-- Error indicator -->
23
+ ```
24
+
25
+ Do not use `ty-bg-*` for cards or panels, or to fake a button or a badge. Do not use `ty-elevated` for a badge.
26
+
27
+ ### Surface Borders & Dividers
28
+
29
+ Each surface exposes three border knobs (color, width, style) via CSS vars. Defaults are `transparent` color, `var(--ty-border-width)` (1px) width, `solid` style — so surfaces ship with no visible border until you opt in.
30
+
31
+ ```css
32
+ :root {
33
+ --ty-elevated-border: var(--ty-border); /* show a 1px ty-border on cards */
34
+ --ty-floating-border: var(--ty-border-bold);
35
+ /* Width and style use --ty-border-width and `solid` unless overridden */
36
+ }
37
+ ```
38
+
39
+ Pattern: `--ty-{surface}-border` (color), `--ty-{surface}-border-width`, `--ty-{surface}-border-style`. Surfaces: `elevated`, `floating`, `canvas`, `content`, `input`.
40
+
41
+ For dividers between siblings inside a surface, use `ty-divide-y` / `ty-divide-x`:
42
+
43
+ ```html
44
+ <div class="ty-elevated">
45
+ <ul class="ty-divide-y">
46
+ <li>row 1</li>
47
+ <li>row 2</li>
48
+ <li>row 3</li>
49
+ </ul>
50
+ </div>
51
+ ```
52
+
53
+ The divider color is **contextual** — each surface points `--ty-divide-color` at its own `--ty-{surface}-border` token. So tuning a surface's border once also changes any dividers placed inside it.
54
+
55
+ ```html
56
+ <!-- Per-instance override -->
57
+ <ul class="ty-divide-y" style="--ty-divide-color: var(--ty-border-strong);">
58
+ ```
59
+
60
+ **Prefer `ty-divide-y`/`ty-divide-x` over Tailwind's `divide-y`/`divide-x` when working with Tyrell surfaces** — Tailwind's defaults are baked at build time and don't follow your theme in dark mode. The Tyrell utilities use CSS vars that auto-switch.
61
+
62
+ ## Background Colors (Semantic)
63
+
64
+ 3 variants per color: stronger (+), base, softer (-).
65
+
66
+ ```html
67
+ <div class="ty-bg-primary+"> <!-- Stronger -->
68
+ <div class="ty-bg-primary"> <!-- Base -->
69
+ <div class="ty-bg-primary-"> <!-- Softer -->
70
+ ```
71
+
72
+ Available colors: `primary`, `success`, `danger`, `warning`, `neutral`.
73
+
74
+ ## Text Colors (5-Variant System)
75
+
76
+ Base text hierarchy (no color, just emphasis):
77
+
78
+ ```html
79
+ <p class="ty-text++"> <!-- Maximum emphasis -->
80
+ <p class="ty-text+"> <!-- High emphasis -->
81
+ <p class="ty-text"> <!-- Normal text -->
82
+ <p class="ty-text-"> <!-- Reduced emphasis -->
83
+ <p class="ty-text--"> <!-- Minimal emphasis -->
84
+ ```
85
+
86
+ Semantic text colors — same 5 variants per color:
87
+
88
+ ```html
89
+ <p class="ty-text-primary++"> <!-- Maximum emphasis primary -->
90
+ <p class="ty-text-primary+"> <!-- High emphasis primary -->
91
+ <p class="ty-text-primary"> <!-- Normal primary -->
92
+ <p class="ty-text-primary-"> <!-- Reduced primary -->
93
+ <p class="ty-text-primary--"> <!-- Minimal primary -->
94
+ ```
95
+
96
+ Available colors: `primary`, `success`, `danger`, `warning`, `neutral`.
97
+
98
+ ## Border Colors
99
+
100
+ Base borders (no color, just emphasis) — 5 variants:
101
+
102
+ ```html
103
+ <div class="ty-border++"> <!-- Maximum -->
104
+ <div class="ty-border+"> <!-- Strong -->
105
+ <div class="ty-border"> <!-- Normal -->
106
+ <div class="ty-border-"> <!-- Soft -->
107
+ <div class="ty-border--"> <!-- Minimal -->
108
+ ```
109
+
110
+ Semantic borders — base only:
111
+
112
+ ```html
113
+ <div class="ty-border-primary">
114
+ <div class="ty-border-success">
115
+ <div class="ty-border-danger">
116
+ <div class="ty-border-warning">
117
+ <div class="ty-border-neutral">
118
+ ```
119
+
120
+ ## Hover / Focus States
121
+
122
+ ```html
123
+ <div class="hover:ty-bg-primary">
124
+ <input class="focus:ty-border-primary">
125
+ ```
126
+
127
+ ## Dark Mode
128
+
129
+ Tyrell uses the `dark` class on `<html>` to switch themes. All Tyrell color variables respond automatically.
130
+
131
+ ### Requirements
132
+
133
+ Add a `dark` class to `<html>` for dark mode:
134
+
135
+ ```html
136
+ <!-- Light mode (default) -->
137
+ <html>
138
+
139
+ <!-- Dark mode -->
140
+ <html class="dark">
141
+ ```
142
+
143
+ ### Toggling Theme (JavaScript)
144
+
145
+ ```javascript
146
+ function toggleTheme() {
147
+ const html = document.documentElement;
148
+ const isDark = html.classList.toggle('dark');
149
+ localStorage.setItem('theme', isDark ? 'dark' : 'light');
150
+ }
151
+ ```
152
+
153
+ ### Toggling Theme (ClojureScript)
154
+
155
+ ```clojure
156
+ (defn toggle-theme! []
157
+ (let [cl (.-classList js/document.documentElement)
158
+ dark? (.toggle cl "dark")]
159
+ (.setItem js/localStorage "theme" (if dark? "dark" "light"))))
160
+ ```
161
+
162
+ ### Initializing from Stored Preference
163
+
164
+ ```javascript
165
+ // Run before page renders (e.g. in <head>) to prevent flash
166
+ const theme = localStorage.getItem('theme')
167
+ || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
168
+ if (theme === 'dark') document.documentElement.classList.add('dark');
169
+ ```
170
+
171
+ ## Color Customization
172
+
173
+ `tyrell.css` on its own has **no color tokens** — spacing, radius, typography, shadows, z-index and component structure only. Pair it with exactly one color layer:
174
+
175
+ - **`tyrell-theme.css`** — OKLCH theme engine, dynamic, retintable, recommended (Option 1 below).
176
+ - **`tyrell-colors-static.css`** — the plain hardcoded hex fallback (light + dark), for consumers who don't want the theme engine at all.
177
+
178
+ Loading both is harmless (`tyrell-theme.css` always wins the cascade) but redundant — pick one.
179
+
180
+ ### Option 1 — OKLCH theme engine (recommended)
181
+
182
+ Load `tyrell-theme.css` after `tyrell.css`, then rebrand with one variable:
183
+
184
+ ```html
185
+ <link rel="stylesheet" href=".../tyrell.css">
186
+ <link rel="stylesheet" href=".../tyrell-theme.css">
187
+ ```
188
+
189
+ ```css
190
+ :root {
191
+ --ty-primary-hue: 200; /* teal. Try 260 indigo, 30 orange, 145 emerald. */
192
+ }
193
+ ```
194
+
195
+ That's it. Primary, surfaces, inputs, solid buttons, focus rings — everything retints coherently in both light and dark mode. Greys stay pure by design (see the neutral row below) — set `--ty-neutral-hue`/`--ty-neutral-chroma` to warm them toward primary.
196
+
197
+ #### How it builds colors
198
+
199
+ Every color in the library is one formula on five axes:
200
+
201
+ ```
202
+ oklch(
203
+ L = L-curve[shade] × flavor-l-factor ← Tier 2 × Tier 4
204
+ C = flavor-chroma × saturation-curve[shade] ← Tier 1 × Tier 3
205
+ H = flavor-hue ← Tier 1
206
+ )
207
+ ```
208
+
209
+ Pick a flavor (primary / success / warning / danger / neutral) and a shade (strong / bold / base / soft / faint). The formula gives you that cell's color. Five axes:
210
+
211
+ - **FLAVOR** — which semantic role. Each flavor carries its own hue, chroma, and l-factor seeds.
212
+ - **SHADE** — 5 emphasis stops shared across flavors. Same shade across flavors = same perceptual weight.
213
+ - **HUE** — what color family (0°–360°).
214
+ - **CHROMA** — how saturated (0 grey → ~0.4 max vivid).
215
+ - **L** — how dark or light. Light mode: low L = more emphasis. Dark mode flips the curve so high L = more emphasis.
216
+
217
+ Worked example — `--ty-color-warning-bold` in light mode:
218
+
219
+ ```
220
+ L = 0.46 × 1 = 0.46 ← l-bold × warning-l-factor (default)
221
+ C = 0.26 × 1.00 = 0.26 ← warning-chroma × c-bold-mult
222
+ H = 75° ← warning-hue
223
+ → oklch(0.46 0.26 75) a punchy amber
224
+ ```
225
+
226
+ Set `--ty-warning-l-factor: 0.85` and the new L becomes `0.46 × 0.85 = 0.39` — every warning shade shifts in step; primary / success / danger untouched.
227
+
228
+ The customisation surface has **five tiers**, each independent. Set just the seeds for the 90% case; reach further when needed.
229
+
230
+ ---
231
+
232
+ #### Tier 1 — flavor seeds
233
+
234
+ Every flavor — including primary — is one hue + one chroma. No flavor derives from another; each is a standalone dial:
235
+
236
+ ```css
237
+ :root {
238
+ --ty-primary-hue: 200; /* the color (0–360°) */
239
+ --ty-primary-chroma: 0.15; /* saturation (0–0.30) */
240
+ }
241
+ ```
242
+
243
+ Rebrand by overriding `--ty-primary-hue`/`-chroma` alone; touch the others only when a specific flavor needs its own tuning:
244
+
245
+ > **These dials are per-mode.** Dark mode re-declares every Tier-1 flavor seed
246
+ > at `html.dark` (`--ty-primary-hue: 226`, `--ty-primary-chroma: 0.065`, and the
247
+ > same for success/warning/danger), and `html.dark` (0,1,1) outranks `:root`
248
+ > (0,1,0). So the block below rebrands **light mode only** — dark silently keeps
249
+ > the stock palette. Either repeat the declarations inside `html.dark`
250
+ > (see [Per-mode overrides](#per-mode-overrides)), or set
251
+ > `--ty-{flavor}-seed` instead, which nothing re-declares and which therefore
252
+ > covers both modes in one line:
253
+ >
254
+ > ```css
255
+ > :root { --ty-primary-seed: oklch(0.5 0.13 200); } /* light + dark */
256
+ > ```
257
+
258
+ ```css
259
+ :root {
260
+ --ty-primary-hue: 200;
261
+
262
+ /* Every flavor is independent. Override hue and/or chroma. */
263
+ --ty-success-hue: 165;
264
+ --ty-danger-chroma: 0.20; /* louder errors */
265
+
266
+ /* Neutral is ACHROMATIC by default — greys do NOT follow primary.
267
+ Opt in to primary-warmed greys: */
268
+ --ty-neutral-hue: var(--ty-primary-hue);
269
+ --ty-neutral-chroma: 0.003;
270
+ }
271
+ ```
272
+
273
+ | Flavor | Hue var | Chroma var | Default (light) |
274
+ |----------|-------------------------|---------------------------|------------------|
275
+ | primary | `--ty-primary-hue` | `--ty-primary-chroma` | `243°` / `0.105` |
276
+ | success | `--ty-success-hue` | `--ty-success-chroma` | `145°` / `0.086` |
277
+ | danger | `--ty-danger-hue` | `--ty-danger-chroma` | `31°` / `0.134` |
278
+ | warning | `--ty-warning-hue` | `--ty-warning-chroma` | `76°` / `0.178` |
279
+ | neutral | `--ty-neutral-hue` | `--ty-neutral-chroma` | `0` / `0` — pure grey, primary-independent |
280
+
281
+ **Or skip the numbers entirely — seed any flavor with a color.** Every flavor also accepts `--ty-{flavor}-seed: <any color>`; its hue + chroma are read via relative color syntax and the number dials are bypassed. The seed's *lightness is discarded by design* — shade placement per mode is the L-curve's job, which is what keeps dark mode, tones and contrast correct for any seed:
282
+
283
+ ```css
284
+ :root {
285
+ --ty-primary-seed: #76467c; /* your color from one hex — done */
286
+ --ty-danger-seed: crimson;
287
+ }
288
+ ```
289
+
290
+
291
+ ---
292
+
293
+ #### Tier 2 — L-curve (emphasis ladder)
294
+
295
+ The 5-shade text ramp (`strong / bold / base / soft / faint`) is computed from shared lightness stops. Reshape the ladder by overriding any:
296
+
297
+ ```css
298
+ :root {
299
+ /* Light mode — lower L = more emphasis. */
300
+ --ty-l-strong: 0.34; /* darker ++ shade */
301
+ --ty-l-bold: 0.46;
302
+ --ty-l-base: 0.54;
303
+ --ty-l-soft: 0.72;
304
+ --ty-l-faint: 0.82; /* less faded -- shade */
305
+
306
+ /* 3-shade bg ramp uses its own L-stops. */
307
+ --ty-l-bg-base: 0.96;
308
+ --ty-l-bg-bold: 0.92;
309
+ --ty-l-bg-soft: 0.98;
310
+
311
+ /* Text ladder (--ty-text-*) and generic borders (--ty-border-*) are
312
+ separate families with their own L dials — tuning the emphasis
313
+ curve above does NOT move them. */
314
+ --ty-l-text-base: 0.21; /* body text */
315
+ --ty-l-border: 0.72; /* default border */
316
+ --ty-l-border-elevated: 0.93; /* card/panel border */
317
+ }
318
+ ```
319
+
320
+ Use cases: compress the ladder for an "all-soft" muted palette; expand it for higher-contrast accessibility-first themes. Full dial list: `--ty-l-text-{strong,bold,base,soft,faint}`, `--ty-l-border{,-strong,-bold,-soft,-faint}`, `--ty-l-border-{content,elevated,floating}` — each with independent dark-mode values (override inside `html.dark`).
321
+
322
+ ---
323
+
324
+ #### Tier 3 — saturation curve (per-shade chroma multipliers)
325
+
326
+ Each shade's chroma = `flavor-chroma × multiplier`. Override to make any shade more or less saturated than the curve's default:
327
+
328
+ ```css
329
+ :root {
330
+ --ty-c-strong-mult: 0.77; /* slightly desaturated strong */
331
+ --ty-c-bold-mult: 1.20; /* punchier bold */
332
+ --ty-c-base-mult: 0.92;
333
+ --ty-c-soft-mult: 0.77;
334
+ --ty-c-faint-mult: 0.20; /* whisper-quiet placeholders */
335
+ }
336
+ ```
337
+
338
+ Same idea for bg multipliers: `--ty-c-bg-base-mult`, `--ty-c-bg-bold-mult`, `--ty-c-bg-soft-mult`.
339
+
340
+ ---
341
+
342
+ #### Tier 4 — per-flavor L-factor
343
+
344
+ A single multiplier per flavor that scales every L-curve value *only for that flavor*. Default `1` = no change. Useful when one flavor's hue sits too close to primary's on the wheel and the buttons blend.
345
+
346
+ ```css
347
+ :root {
348
+ --ty-primary-hue: 47; /* gold primary */
349
+ --ty-warning-l-factor: 0.85; /* nudge warning darker so it stands apart */
350
+ }
351
+ ```
352
+
353
+ The full set:
354
+
355
+ ```css
356
+ --ty-primary-l-factor: 1;
357
+ --ty-success-l-factor: 1;
358
+ --ty-warning-l-factor: 1;
359
+ --ty-danger-l-factor: 1;
360
+ --ty-neutral-l-factor: 1;
361
+ ```
362
+
363
+ Effect on the formula: `L = L-curve[shade] × flavor-l-factor`. Set warning's factor to `0.85` and every warning shade (strong/bold/base/soft/faint) shifts by ×0.85; primary/success/danger untouched.
364
+
365
+ > **Note about dark mode.** The L-curve flips between modes (light: low L = emphatic; dark: high L = emphatic). A factor `< 1` darkens warning in light mode but **dims** it in dark mode. If you want symmetric "more emphatic" in both modes, set the factor in `:root` for light AND set its inverse (roughly `1 / factor`) in `html.dark`. See "Per-mode overrides" below.
366
+
367
+ **Per-flavor solid anchor lift** (`--ty-{flavor}-solid-l`, default `0`) — a companion set for the *solid button* ladder specifically: an additive L shift applied to the flavor's base fill before tones and hover/active derive from it. Exists because "darker = stronger" is false for the yellow family — darkened hue-75 is brown — so warning ships with `+0.1` in light mode (`0` in dark), lifting its whole solid ladder into the orange zone with black text throughout. Use it for any flavor whose solid fills land in a bad lightness zone:
368
+
369
+ ```css
370
+ :root { --ty-warning-solid-l: 0.1; } /* shipped default */
371
+ html.dark { --ty-warning-solid-l: 0; } /* dim fills don't brown out */
372
+ ```
373
+
374
+ ---
375
+
376
+ #### Auto-contrast foregrounds (solid buttons)
377
+
378
+ Solid button text is **not** a fixed color — each fill derives its own foreground from its lightness, so rebranding can't strand white text on a pale fill:
379
+
380
+ ```css
381
+ --ty-solid-primary-soft-fg: oklch(from var(--ty-solid-primary-soft)
382
+ clamp(0, (var(--ty-solid-fg-threshold) - l) * 1000, 1) 0 0);
383
+ ```
384
+
385
+ Fills darker than the threshold get white, lighter get black. One token per *fill* — `-fg`, `-soft-fg` (tone `-`), `-strong-fg` (tone `+`) — because each tone sits at a different lightness.
386
+
387
+ ```css
388
+ :root {
389
+ --ty-solid-fg-threshold: 0.57; /* crossover. Higher = prefers white, lower = prefers black. */
390
+ }
391
+ ```
392
+
393
+ Opt out per flavor by pinning the token (`--ty-solid-primary-fg: white`), or globally with `--ty-solid-fg-threshold: 1` to force white everywhere.
394
+
395
+ ---
396
+
397
+ #### Typography weight dials (mode-flipped)
398
+
399
+ Button and tag text weight is a themable dial, not a hardcode — and it flips with the mode, because light text on dark surfaces optically blooms (halation) and reads heavier than the same weight on white:
400
+
401
+ ```css
402
+ :root {
403
+ --ty-weight-action: 510; /* buttons, interactive chrome (light mode) */
404
+ --ty-weight-label: 440; /* tags, chips, badges (light mode) */
405
+ }
406
+ html.dark {
407
+ --ty-weight-action: 400; /* bloom compensation */
408
+ --ty-weight-label: 400;
409
+ }
410
+ ```
411
+
412
+ Override at any scope — `:root`, a theme pack, one element. Old semibold look back in one line: `--ty-weight-action: var(--ty-font-semibold)`. Both dials are `@property`-registered numbers, so with a variable font, weight **crossfades during theme transitions** along with the colors.
413
+
414
+ ---
415
+
416
+ #### Solid-button depth (`--ty-button-depth`)
417
+
418
+ Solid buttons derive a 1px border and a soft drop shadow from their **own current fill** via relative color, scaled by one dial:
419
+
420
+ ```css
421
+ :root { --ty-button-depth: 0.35; } /* default: subtle */
422
+ html.love { --ty-button-depth: 1; } /* stronger border + shadow for one theme */
423
+ ty-button.flat { --ty-button-depth: 0; } /* pixel-flat — border color matches the fill exactly */
424
+ ```
425
+
426
+ Border color is `oklch(from <resting fill> calc(l + border-l × depth) c h)` — the fill with only its lightness shifted, chroma/hue kept. **Resting** fill, not current: on hover/active only the fill steps up (via `--ty-solid-hover-l`/`-active-l`) while the border stays put, so the fill visibly rises *toward* the border instead of dragging it along.
427
+
428
+ `--ty-button-border-l` sets the offset direction/magnitude and is mode-flipped — colored solids get no border at all in dark mode (`0`; the fill's own hue/saturation already separates it from the page) and a subtle darkening in light (`-0.08`). Neutral is different — no hue to lean on, so it needs a real lit edge to read as a shape against a near-black canvas — and gets its own stronger dial, `--ty-button-border-l-neutral` (`-0.25` light / `0.5` dark).
429
+
430
+ Direct escape hatches outrank the derivation entirely:
431
+
432
+ ```css
433
+ ty-button.custom {
434
+ --ty-solid-border-color: oklch(0.7 0.1 300); /* pin ANY color — dials stop mattering */
435
+ --ty-solid-border-width: 2px; /* thickness (≠1px shifts geometry) */
436
+ }
437
+ ```
438
+
439
+ ---
440
+
441
+ #### Neutral+ — full-contrast ink, in every appearance
442
+
443
+ `flavor="neutral+"` is the monochrome max-emphasis CTA: near-black ink in light mode, **inverted white ink with black text in dark mode** — the Geist/shadcn primary-button pattern. Unlike other tones it's an absolute, not "anchor + offset", and unlike every other flavor's `-strong` it's the same dial across all three appearances (solid/outlined/ghost) rather than each reading its own token:
444
+
445
+ ```css
446
+ --ty-l-solid-neutral-strong: 0.15; /* light */
447
+ html.dark { --ty-l-solid-neutral-strong: 0.88; } /* inverted ink */
448
+ ```
449
+
450
+ Base and soft neutral (all appearances) stay on the regular per-flavor text ladder — bare text needs page contrast, which is what that ladder is for; the ink ramp doesn't invert for readability the way it does, so pointing weaker tones at it would make them illegible. `+` alone reads the ink dial, giving outlined/ghost `neutral+` the same loud identity as the solid button next to it. `button.muted` follows the same split. Hover/active on `neutral+` move *toward mid-lightness* (fill-relative, not mode-directional) — at an L extreme the normal interaction dials would clip and vanish.
451
+
452
+ ---
453
+
454
+ #### Outlined/ghost hover — always escalates to peak
455
+
456
+ Whatever tone you set (`-`/base/`+`), outlined and ghost buttons resolve their text (and outlined's border) to the `-strong` tier on `:hover`/`:active`/`:focus-visible` — soft and base both rise to the same peak color on interaction; `+` is already there at rest. `muted` composes with this correctly: hover keeps muted's own contract (reveal the plain button's resting color), while press/focus lands muted on the same escalated color as a pressed plain button.
457
+
458
+ ---
459
+
460
+ #### Named + scoped themes
461
+
462
+ A theme is nothing more than a class that overrides Section 1 dials — `html.dark` is just the built-in reference theme, not a special case. Any name works the same way:
463
+
464
+ ```css
465
+ html.love {
466
+ --ty-primary-hue: 340;
467
+ --ty-primary-chroma: 0.18;
468
+ --ty-l-base: 0.5;
469
+ /* any Section 1 dial */
470
+ }
471
+ ```
472
+
473
+ ```html
474
+ <html class="love">
475
+ ```
476
+
477
+ That's a complete named theme — every derived token recomputes because the formulas read these dials, not literal colors.
478
+
479
+ **Scope one to a subtree** with `[data-ty-theme]`, which the theme engine's formulas already match alongside `html:root`:
480
+
481
+ ```html
482
+ <section data-ty-theme class="love">
483
+ <!-- everything in here re-themes, independent of the page around it -->
484
+ </section>
485
+
486
+ <!-- dark card inside a light page, or vice versa -->
487
+ <aside data-ty-theme class="dark">…</aside>
488
+ ```
489
+
490
+ Combine with a flavor pack (below) for a theme that also carries its own custom flavors — the Theming page's playground has a "named theme" export mode that generates this shape from the live sliders.
491
+
492
+ ---
493
+
494
+ #### Animated theme transitions
495
+
496
+ Every dial in the theme engine is a typed, `@property`-registered number — and every color is a pure function of the dials. So theme and mode switches don't snap: the dials interpolate, and the whole page crossfades through OKLCH space. This applies to `html.dark`, named theme packs, `[data-ty-theme]` subtree switches, and even live seed changes.
497
+
498
+ ```css
499
+ :root { --ty-theme-transition: 0s; } /* opt out */
500
+ :root { --ty-theme-transition: 1.2s; } /* slower crossfade */
501
+ ```
502
+
503
+ Reduced-motion users never get the animation. Browsers without `@property` fall back to instant switching.
504
+
505
+ **Jittery instead of smooth?** Interactive components (`ty-button`, `ty-input`, `ty-switch`, …) each carry their own short hover/focus transition (~0.15–0.2s on `background-color`/`border-color`/`color`). CSS transitions fire on any computed-value change, not just interaction, so a theme switch also retriggers every one of those at once — hundreds of elements racing the coordinated dial crossfade at a different speed, which reads as jitter rather than one smooth wash. Add the `ty-theme-switching` class to whatever you toggle (`<html>`, or a scoped `[data-ty-theme]` root) for the duration of the switch to silence those local transitions:
506
+
507
+ ```js
508
+ root.classList.add('ty-theme-switching')
509
+ root.classList.toggle('dark') // or swap in a theme pack
510
+ setTimeout(() => root.classList.remove('ty-theme-switching'),
511
+ parseFloat(getComputedStyle(root).getPropertyValue('--ty-theme-transition')) * 1000 || 450)
512
+ ```
513
+
514
+ Purely additive — nothing changes unless you add the class yourself. Works through Shadow DOM too: every `ty-*` component's own local transition is wired to an inheriting custom property that `.ty-theme-switching` sets, not to a selector that Shadow DOM encapsulation would block.
515
+
516
+ ---
517
+
518
+ #### Per-mode overrides
519
+
520
+ Any tier can be overridden separately for dark mode by repeating the declaration inside `html.dark`.
521
+
522
+ For most tiers this is optional. For the **Tier 1 flavor dials**
523
+ (`--ty-{primary,success,warning,danger}-{hue,chroma}`) it is **required** —
524
+ dark ships its own values for those at `html.dark`, so a `:root`-only override
525
+ never reaches dark mode. Repeat them here, or use `--ty-{flavor}-seed` on
526
+ `:root` instead and skip the duplication entirely.
527
+
528
+ ```css
529
+ :root {
530
+ --ty-primary-hue: 200; /* light mode teal */
531
+ --ty-warning-l-factor: 0.85; /* darker warning in light mode */
532
+ }
533
+ html.dark, html[data-theme="dark"] {
534
+ --ty-primary-hue: 210; /* slightly cooler teal in dark mode */
535
+ --ty-warning-l-factor: 1.15; /* brighter warning in dark mode */
536
+ --ty-c-faint-mult: 0.60; /* dark mode needs more chroma at faint */
537
+ }
538
+ ```
539
+
540
+ The theme engine's `html.dark` block already redefines the L-curve with inverted defaults (`0.86 / 0.74 / 0.62 / 0.46 / 0.30`) and bumps `--ty-c-faint-mult` so dim shades don't collapse to grey. Override either to fine-tune.
541
+
542
+ ---
543
+
544
+ ### Option 2 — direct token override (legacy / fine-grained)
545
+
546
+ If you don't load the theme engine, load `tyrell-colors-static.css` alongside `tyrell.css` for the base tokens, then override individual shades on top — or, if you're already on the theme engine and just want to override individual derived tokens, write hex values directly; the theme engine doesn't block this, the cascade resolves consumer overrides past the formula's output.
547
+
548
+ ```html
549
+ <link rel="stylesheet" href=".../tyrell.css">
550
+ <link rel="stylesheet" href=".../tyrell-colors-static.css">
551
+ ```
552
+
553
+ ```css
554
+ :root {
555
+ --ty-color-primary-strong: #0034c7;
556
+ --ty-color-primary-bold: #1c40a8;
557
+ --ty-color-primary: #4367cd;
558
+ --ty-color-primary-soft: #60a5fa;
559
+ --ty-color-primary-faint: #93c5fd;
560
+ --ty-bg-primary-bold: #bfdbfe;
561
+ --ty-bg-primary: #dbeafe;
562
+ --ty-bg-primary-soft: #eff6ff;
563
+ }
564
+
565
+ html.dark {
566
+ --ty-color-primary-strong: #93c5fd;
567
+ /* …etc */
568
+ }
569
+ ```
570
+
571
+ **Pattern:** `--ty-color-{flavor}-{strong | bold | soft | faint}`, `--ty-bg-{flavor}-{bold | soft}`, `--ty-border-{flavor}`. Flavors are `primary`, `success`, `danger`, `warning`, `neutral`.
572
+
573
+ Use this when:
574
+ - You have a fixed color palette and don't need the OKLCH math
575
+ - You want to override one specific shade without abandoning the formula (set the seed AND the one token)
576
+ - You're integrating with an existing design-token system
577
+
578
+ The theme engine (Option 1) is strictly more powerful — anything you can do with Option 2 you can also do on top of Option 1. Most apps shouldn't need Option 2 at all.
579
+
580
+ ---
581
+
582
+ ## Custom Flavors (add your own)
583
+
584
+ The built-in flavors (`primary` / `success` / `danger` / `warning` / `neutral`) are not a closed set. Pass any name as `flavor` and the component themes itself from that name's design tokens, `+`/`-` tones included. Supported by **every flavored component**: `ty-button`, `ty-tag`, `ty-switch`, `ty-radio-group` (and its `ty-radio` children), `ty-checkbox`, `ty-input`, `ty-select`, `ty-date-picker`, `ty-copy`, `ty-tooltip`, `ty-calendar` (and its `ty-calendar-month`).
585
+
586
+ ```html
587
+ <ty-button flavor="mr-hanky">Save</ty-button>
588
+ <ty-button flavor="mr-hanky-" appearance="outlined">Softer</ty-button>
589
+ <ty-tag flavor="mr-hanky+">stronger chip</ty-tag>
590
+ ```
591
+
592
+ ### The flavor pack: one color, everything a built-in gets
593
+
594
+ A pack has two parts. Generate it with the **Custom flavors** builder on the docs site's Theming page (name + one color → copy); the block below is its output for `mr-hanky`, and if the two ever differ, the builder wins.
595
+
596
+ **1 · Yours** (the only lines you edit):
597
+
598
+ ```css
599
+ :root {
600
+ --ty-mr-hanky-seed: #784011; /* any CSS color: hex, name, rgb(), oklch() */
601
+ --ty-mr-hanky-l-factor: 0.86; /* optional: all five shades lighter (>1) or darker (<1) */
602
+ }
603
+ ```
604
+
605
+ **2 · Engine** (paste once per flavor name, never edit):
606
+
607
+ ```css
608
+ html:root,
609
+ [data-ty-theme] {
610
+ --ty-color-mr-hanky-strong: oklch(from var(--ty-mr-hanky-seed) calc(var(--ty-l-strong) * var(--ty-mr-hanky-l-factor, 1)) calc(c * var(--ty-c-strong-mult)) h);
611
+ --ty-color-mr-hanky-bold: oklch(from var(--ty-mr-hanky-seed) calc(var(--ty-l-bold) * var(--ty-mr-hanky-l-factor, 1)) calc(c * var(--ty-c-bold-mult)) h);
612
+ --ty-color-mr-hanky: oklch(from var(--ty-mr-hanky-seed) calc(var(--ty-l-base) * var(--ty-mr-hanky-l-factor, 1)) calc(c * var(--ty-c-base-mult)) h);
613
+ --ty-color-mr-hanky-soft: oklch(from var(--ty-mr-hanky-seed) calc(var(--ty-l-soft) * var(--ty-mr-hanky-l-factor, 1)) calc(c * var(--ty-c-soft-mult)) h);
614
+ --ty-color-mr-hanky-faint: oklch(from var(--ty-mr-hanky-seed) calc(var(--ty-l-faint) * var(--ty-mr-hanky-l-factor, 1)) calc(c * var(--ty-c-faint-mult)) h);
615
+ --ty-bg-mr-hanky: oklch(from var(--ty-color-mr-hanky) l c h / var(--ty-a-bg-base));
616
+ --ty-bg-mr-hanky-bold: oklch(from var(--ty-color-mr-hanky) l c h / var(--ty-a-bg-bold));
617
+ --ty-bg-mr-hanky-soft: oklch(from var(--ty-color-mr-hanky) l c h / var(--ty-a-bg-soft));
618
+ --ty-border-mr-hanky: var(--ty-color-mr-hanky-soft);
619
+ --ty-solid-mr-hanky: oklch(from var(--ty-color-mr-hanky) calc(l + var(--ty-solid-l)) calc(c * var(--ty-solid-c)) calc(h + var(--ty-solid-h)));
620
+ --ty-solid-mr-hanky-hover: oklch(from var(--ty-solid-mr-hanky) calc(l + var(--ty-solid-hover-l)) c h);
621
+ --ty-solid-mr-hanky-active: oklch(from var(--ty-solid-mr-hanky) calc(l + var(--ty-solid-active-l)) c h);
622
+ --ty-solid-mr-hanky-strong: oklch(from var(--ty-solid-mr-hanky) calc(l + var(--ty-solid-strong-l)) c h);
623
+ --ty-solid-mr-hanky-soft: oklch(from var(--ty-solid-mr-hanky) calc(l + var(--ty-solid-soft-l)) c h);
624
+ --ty-solid-mr-hanky-fg: oklch(from var(--ty-solid-mr-hanky) clamp(0, (var(--ty-solid-fg-threshold) - l) * 1000, 1) 0 0);
625
+ --ty-solid-mr-hanky-soft-fg: oklch(from var(--ty-solid-mr-hanky-soft) clamp(0, (var(--ty-solid-fg-threshold) - l) * 1000, 1) 0 0);
626
+ --ty-solid-mr-hanky-strong-fg: oklch(from var(--ty-solid-mr-hanky-strong) clamp(0, (var(--ty-solid-fg-threshold) - l) * 1000, 1) 0 0);
627
+ }
628
+ ```
629
+
630
+ **Do I copy the whole theme CSS?** No. Keep loading `tyrell.css` and `tyrell-theme.css` as they are. Each custom flavor adds just the block above.
631
+
632
+ **Do the lightness and chroma dials affect it?** Yes, live. The engine points at the shared dials (`--ty-l-*` curve, `--ty-c-*-mult` chroma scales, `--ty-a-bg-*` tint amounts, `--ty-solid-*` offsets, `--ty-solid-fg-threshold`) instead of copying their values. Retune any of them, or switch to dark mode, and your flavor recolors exactly like the built-ins; nothing to re-copy and **no `html.dark` block of your own**. Only the seed's hue and chroma are used: its lightness is ignored because the curve decides it, which is what `l-factor` is for.
633
+
634
+ **What it needs:**
635
+
636
+ - `tyrell-theme.css` loaded. The static palette (`tyrell-colors-static.css`) has no dials, so the engine resolves to nothing without it.
637
+ - A name that starts with a letter (letters, digits, `-`, `_`) and isn't one of the five built-ins. A trailing `+`/`-` is read as a tone, so `mr-hanky-` is the soft tone of `mr-hanky`.
638
+ - The selector exactly as given: `html:root, [data-ty-theme]`. The second half makes themed subtrees (`[data-ty-theme]` with their own dials) recompute your flavor; without it they inherit the page's values.
639
+ - A browser with relative color syntax (`oklch(from …)`), the same requirement as the theme engine itself.
640
+
641
+ **What comes free:** `+`/`-` tones on every component, hover and pressed states, tinted backgrounds, borders, focus rings, and black-or-white text on solid fills picked from each fill's own lightness.
642
+
643
+ ### Hand-picked tokens instead
644
+
645
+ For exact brand values, skip the engine and define the tokens components read yourself. This is the complete list, shown for `flavor="brand"`:
646
+
647
+ ```css
648
+ :root {
649
+ /* text & icons */
650
+ --ty-color-brand-strong: #115e59;
651
+ --ty-color-brand: #0d9488;
652
+ --ty-color-brand-soft: #2dd4bf;
653
+ --ty-color-brand-faint: #99f6e4; /* focus ring */
654
+ /* tinted backgrounds */
655
+ --ty-bg-brand-bold: #99f6e4;
656
+ --ty-bg-brand: #ccfbf1;
657
+ --ty-bg-brand-soft: #f0fdfa;
658
+ /* border */
659
+ --ty-border-brand: #0d9488;
660
+ /* solid fills: base, tone+, tone-, states */
661
+ --ty-solid-brand: #0d9488;
662
+ --ty-solid-brand-strong: #0f766e;
663
+ --ty-solid-brand-soft: #5eead4;
664
+ --ty-solid-brand-hover: #0f766e;
665
+ --ty-solid-brand-active: #134e4a;
666
+ /* text on each solid fill */
667
+ --ty-solid-brand-fg: white;
668
+ --ty-solid-brand-strong-fg: white;
669
+ --ty-solid-brand-soft-fg: #134e4a;
670
+ }
671
+ ```
672
+
673
+ The trade-off: these are fixed values, so they don't follow the dials or dark mode. Repeat the block under `html.dark` with dark-mode values.
674
+
675
+ Notes:
676
+
677
+ - **Missing tokens degrade to neutral.** Any token you don't define falls back to the `neutral` equivalent, so you can start with `--ty-solid-X` + `--ty-solid-X-fg` and fill in the rest later.
678
+ - **Field emphasis ladders need the shade tokens.** Flavored fields (`ty-input`, `ty-select`, `ty-date-picker`) rest on `--ty-color-X-soft` and escalate to `--ty-color-X` on hover/focus. Define only the base token and rest and focus look the same.
679
+ - **Scoping works like any CSS variable:** define on `:root` for the whole app, or on a container for one section.
680
+ - **Per-instance overrides still win.** Each component's local flavor vars (table below) take precedence over the token wiring, e.g. `ty-tag[flavor="X"] { --tag-bg: … }`. On `ty-input`, `ty-select` and `ty-date-picker` such a rule also beats the danger look an `error` gives. To let the error show, skip the error state: `ty-input[flavor="X"]:not([error]:not([error=""])) { --input-accent: … }`.
681
+
682
+ Each flavored component funnels its colors through a few local vars, which double as the per-instance override API (set them on the host from any page-level rule):
683
+
684
+ | Component | Local vars |
685
+ |---|---|
686
+ | `ty-tag` | `--tag-bg`, `--tag-color`, `--tag-border-color` |
687
+ | `ty-switch` | `--switch-track` (checked track) |
688
+ | `ty-radio` | `--radio-color` (checked border + dot) |
689
+ | `ty-checkbox` | `--checkbox-color` (checked), `--checkbox-color-off`, `--checkbox-ring` (focus ring) |
690
+ | `ty-input` | `--input-accent` (border), `--input-accent-bold` (hover/focus), `--input-ring` |
691
+ | `ty-select` | `--select-accent` (border), `--select-accent-bold` (hover/open border), `--select-ring` (open focus ring) |
692
+ | `ty-date-picker` | `--date-picker-accent`, `--date-picker-accent-bold`, `--date-picker-ring` |
693
+ | `ty-copy` | `--copy-color`, `--copy-color-hover`, `--copy-bg-hover` |
694
+ | `ty-tooltip` (default `dark` flavor only) | `--ty-tooltip-bg`, `--ty-tooltip-color`, `--ty-tooltip-border` — defined once on `:root`, deliberately NOT redeclared per theme (a tooltip should always pop, light page or dark) |
695
+ | `ty-calendar-month` | `--calendar-month-accent` (today + selected border), `--calendar-month-selected-bg`, `--calendar-month-selected-color`, `--calendar-month-selected-hover-bg` — also reachable via the pre-existing `--ty-calendar-*` overrides, which still win. `--ty-calendar-other-month-color` (prev/next-month day text — its `:root` / `html.dark` defaults are pre-calibrated to pass WCAG AA contrast; if you override it, check contrast against your own surface color) |
696
+
697
+ ---
698
+
699
+ ## Component Sizing
700
+
701
+ ### The field ladder
702
+
703
+ **Fields** (`ty-input`, `ty-select`, `ty-date-picker`, `ty-copy`) come in **five sizes** — `xs` / `sm` / `md` / `lg` / `xl` — and **`sm` is the default**. The same `size` value gives the same height, the same text size and the same label scale on every field, so a form row lines up without per-component tuning.
704
+
705
+ | size | height | field text | label | padding-x |
706
+ |---|---|---|---|---|
707
+ | `xs` | 28px | 12px | 12px | 8px |
708
+ | **`sm`** (default) | **32px** | 14px | 12px | 10px |
709
+ | `md` | 36px | 14px | 14px | 12px |
710
+ | `lg` | 40px | 16px | 14px | 14px |
711
+ | `xl` | 44px | 18px | 16px | 16px |
712
+
713
+ All of it comes from **one file** — `src/styles/field-size.ts` — which emits a block of `--ty-field-*` custom properties per `:host([size])`. Every field stylesheet interpolates that block and consumes the vars; **no component hardcodes a size**:
714
+
715
+ ```css
716
+ :host([size="md"]) {
717
+ --ty-field-height: var(--ty-size-md, 2.25rem);
718
+ --ty-field-pad-x: 12px;
719
+ --ty-field-font: var(--ty-font-sm);
720
+ --ty-field-leading: 20px;
721
+ --ty-field-label-font: var(--ty-font-sm);
722
+ --ty-field-label-gap: 6px;
723
+ --ty-field-control: 28px; /* inline buttons, e.g. ty-copy's */
724
+ --ty-field-icon: 18px;
725
+ }
726
+ ```
727
+
728
+ Two consequences worth knowing:
729
+
730
+ - The **base `:host` block is the `sm` rung**, not a neutral default. A component left at its default never receives a `size` attribute (property sets reflect to attributes, defaults don't), so there is nothing for `:host([size="sm"])` to match. Change `DEFAULT_SIZE` and you must move that base block with it.
731
+ - Narrow viewports drop `lg` and `xl` one rung, in the ladder itself rather than per component.
732
+
733
+ To retheme the ladder, override `--ty-size-*` on `:root`; to change the default size for every field, button and tag at once, change `DEFAULT_SIZE` in `src/types/common.ts`.
734
+
735
+ ### Why `--ty-field-leading` is a plain pixel value
736
+
737
+ It is deliberately **an even number of pixels**, not the matching `--ty-leading-*` token.
738
+
739
+ A single-line field centres its *line box* inside the field height. When the line box is an odd height — `--ty-leading-sm` is 21px — the leftover space in a 32px or 36px field splits into a half pixel, which the browser rounds down, and the text renders 1px off centre. An even line box divides cleanly at every rung. Multi-line text (`ty-textarea`, `ty-copy` in multiline mode) keeps the real leading tokens, where paragraph rhythm matters more than pixel centring.
740
+
741
+ Beyond that, **no optical correction is applied, and none is needed**. Inter is a cap-centred typeface — `ascent − descent − capHeight = 0` — so once the line box centres cleanly, the cap-height-to-baseline band lands exactly in the middle of the field. Measured cap-band offset from the field centre is `0.0px` at `sm`/`md`/`lg` and `±0.5px` at `xs`/`xl` (irreducible sub-pixel rasterisation).
742
+
743
+ > If the font is ever changed, check this assumption first. For a typeface where `ascent − descent ≠ capHeight`, symmetric centring will look wrong and the fix is [Capsize](https://seek-oss.github.io/capsize/)-style leading trim or the native `text-box-trim` / `text-box-edge` properties — not a nudge. Note that `text-box-trim: trim-both` with `text-box-edge: cap alphabetic` clips descenders inside an `<input>`, which clips overflow.
744
+
745
+ ### Text arriving from the light DOM
746
+
747
+ A closed single `ty-select` shows the chosen `ty-option` itself in its trigger (the select assigns it to its `selected` slot and sets the option's `inTrigger`). The option is **light DOM**, so it does not inherit the stub's shadow styles — it picks up the ladder explicitly:
748
+
749
+ ```css
750
+ .option-content.in-trigger {
751
+ font-size: var(--ty-field-font, var(--ty-font-sm));
752
+ line-height: var(--ty-field-leading, var(--ty-leading-sm));
753
+ letter-spacing: var(--ty-field-tracking, var(--ty-tracking-sm));
754
+ }
755
+ ```
756
+
757
+ The custom properties reach it by inheriting from `ty-select` down the light-DOM tree. The fallbacks cover a `ty-option` used outside a select. Options *inside* the dropdown panel keep the panel's own type scale — the panel is not a field and does not follow the field ladder.
758
+
759
+ ### Buttons and tags
760
+
761
+ **Buttons** run a 4px ladder — `xs` 24 / `sm` 28 / `md` 32 / `lg` 36 / `xl` 40 — deliberately one rung below the field ladder, sharing its top three steps. `ty-button` and `ty-tag` also default to `sm`, so the pairing below is unchanged by the default.
762
+
763
+ **Tags** run one rung below the buttons — `xs` 20 / `sm` 24 / `md` 28 / `lg` 32 / `xl` 36 — so a tag beside a button or field matches by height: tag `lg` = button `md` = field `sm` (32), tag `xl` = button `lg` = field `md` (36).
764
+
765
+ | Placement | Rule | Example |
766
+ |---|---|---|
767
+ | **Alongside** a field (separate elements in a row) | field `sm` = button `md` (32); field `md` = button `lg` (36); field `lg` = button `xl` (40) — exact height match, flush in the row | input `size="md"` + button `size="lg"` → both 36px |
768
+ | **Embedded** in a field's `end` slot | Same size name — nests with a consistent ~4px margin | input `size="md"` + slotted button `size="md"` (36 vs 32) |
769
+ | Button `xs`/`sm` | Below the field ladder — compact toolbars, icon actions | — |
770
+
771
+ ```html
772
+ <!-- Alongside: button lg matches field md exactly -->
773
+ <div style="display:flex; gap:0.5rem;">
774
+ <ty-input size="md" placeholder="Search…"></ty-input>
775
+ <ty-button size="lg">Search</ty-button>
776
+ </div>
777
+
778
+ <!-- Embedded: same size name nests with a ~4px margin -->
779
+ <ty-input size="md" placeholder="Search…">
780
+ <ty-button slot="end" size="md" appearance="ghost">Go</ty-button>
781
+ </ty-input>
782
+ ```
783
+
784
+ `ty-checkbox`, `ty-switch` and `ty-radio` scale on their own ladders and are not held to the field height.
785
+
786
+ ### Checking it
787
+
788
+ `/internal/sizing` renders every size-aware component, one row per rung, inside dashed rules marking that rung's expected field height — anything off the ladder breaks out of them visually. `e2e/field-size-ladder.spec.ts` asserts the same thing in CI.
789
+
790
+ ---
791
+
792
+ ## Per-Component Color Overrides
793
+
794
+ The customization above retunes the *whole palette*. To recolor a single instance instead — a one-off brand button, a highlighted input, a green dropdown — set the component's CSS variables on the host element. Custom properties inherit through the shadow DOM, so a value on the host wins over the global default inside that component only.
795
+
796
+ Three places you can set them:
797
+
798
+ ```html
799
+ <!-- inline on one element -->
800
+ <ty-button style="--ty-button-bg: #ff6600;">…</ty-button>
801
+
802
+ <!-- in a stylesheet, scoped by attribute -->
803
+ <style>
804
+ ty-button[flavor="brand"] {
805
+ --ty-button-bg: #7c3aed;
806
+ --ty-button-color: white;
807
+ }
808
+ </style>
809
+
810
+ <!-- on a wrapping container — inherits down to all descendants -->
811
+ <div style="--ty-input-border: #16a34a;">
812
+ <ty-input></ty-input>
813
+ <ty-select>…</ty-select>
814
+ </div>
815
+ ```
816
+
817
+ ### `<ty-button>`
818
+
819
+ Four hooks. The button reads `var(--ty-button-X, …flavor default…)`, so unset values fall back to the chosen flavor.
820
+
821
+ | Variable | Purpose |
822
+ |---|---|
823
+ | `--ty-button-bg` | Background color (used by `solid`) |
824
+ | `--ty-button-bg-hover` | Hover background (optional — flavor's hover shade is used otherwise) |
825
+ | `--ty-button-color` | Text color |
826
+ | `--ty-button-border` | Border color (used by `outlined`) |
827
+
828
+ ```html
829
+ <!-- One-off brand button (solid is default, no border) -->
830
+ <ty-button style="--ty-button-bg: #ff6600;
831
+ --ty-button-color: white;
832
+ --ty-button-bg-hover: #e65c00;">
833
+ Brand orange
834
+ </ty-button>
835
+
836
+ <!-- Gradients work too — solid has no border to interfere -->
837
+ <ty-button style="--ty-button-bg: linear-gradient(135deg, #667eea, #764ba2);">
838
+ Gradient
839
+ </ty-button>
840
+
841
+ <!-- Quick reusable flavor via override variables. For a full flavor with
842
+ shade ramp, tones and tag support, prefer the token-based approach in
843
+ "Custom Flavors" above — these per-instance variables override it. -->
844
+ <style>
845
+ ty-button[flavor="brand"] {
846
+ --ty-button-bg: #7c3aed;
847
+ --ty-button-color: white;
848
+ --ty-button-bg-hover: #6d28d9;
849
+ --ty-button-border: #5b21b6;
850
+ }
851
+ </style>
852
+ <ty-button flavor="brand">Brand</ty-button>
853
+ <ty-button flavor="brand" appearance="outlined">Brand outlined</ty-button>
854
+ ```
855
+
856
+ ### `<ty-input>`, `<ty-select>`
857
+
858
+ All form controls read the same `--ty-input-*` tokens. They're defined globally in `:root` but inherit into each component's shadow DOM, so setting one on a host overrides only that element.
859
+
860
+ | Variable | Purpose |
861
+ |---|---|
862
+ | `--ty-input-bg` | Background |
863
+ | `--ty-input-color` | Text color |
864
+ | `--ty-input-border` | Border (default state) |
865
+ | `--ty-input-border-hover` | Border on hover |
866
+ | `--ty-input-border-focus` | Border when focused |
867
+ | `--ty-input-shadow-focus` | Focus ring color (3px outer glow) |
868
+ | `--ty-input-placeholder` | Placeholder text color |
869
+ | `--ty-input-disabled-bg` | Disabled background |
870
+ | `--ty-input-disabled-border` | Disabled border |
871
+ | `--ty-input-disabled-color` | Disabled text |
872
+
873
+ Per-flavor border overrides (apply when the `flavor` attribute is set):
874
+
875
+ | Variable | Used by |
876
+ |---|---|
877
+ | `--ty-input-primary-border` | `flavor="primary"` |
878
+ | `--ty-input-success-border` | `flavor="success"` |
879
+ | `--ty-input-danger-border` | `flavor="danger"`, and any field with an `error` |
880
+ | `--ty-input-warning-border` | `flavor="warning"` |
881
+
882
+ ```html
883
+ <!-- Highlighted input -->
884
+ <ty-input style="--ty-input-bg: #fffbeb;
885
+ --ty-input-border: #f59e0b;
886
+ --ty-input-border-focus: #d97706;
887
+ --ty-input-shadow-focus: rgba(245, 158, 11, 0.15);"
888
+ placeholder="Highlighted field"></ty-input>
889
+
890
+ <!-- Green-tinted dropdown -->
891
+ <ty-select style="--ty-input-bg: #f0fdf4;
892
+ --ty-input-border: #16a34a;
893
+ --ty-input-border-focus: #15803d;">
894
+ <ty-option value="a">Apple</ty-option>
895
+ <ty-option value="b">Banana</ty-option>
896
+ </ty-select>
897
+
898
+ <!-- Multiselect with a brand tone -->
899
+ <ty-select multiple style="--ty-input-border-focus: #7c3aed;
900
+ --ty-input-shadow-focus: rgba(124, 58, 237, 0.2);">
901
+ <ty-option value="x">X</ty-option>
902
+ <ty-option value="y">Y</ty-option>
903
+ </ty-select>
904
+ ```
905
+
906
+ ### `<ty-calendar>`, `<ty-calendar-month>`, `<ty-date-picker>`
907
+
908
+ These three share a `--ty-calendar-*` token family for the day grid, the popup surface, navigation, and the optional time section. The date-picker stub (the input-like trigger) has its own thin `--ty-date-picker-*` shim that sits on top of `--ty-input-*` — override it to style only the date-picker trigger without affecting other form fields.
909
+
910
+ #### Quick retheming via accent aliases
911
+
912
+ Three aliases drive the most-visible colors. Override any of these and selected/today/focus shift together:
913
+
914
+ | Variable | Drives |
915
+ |---|---|
916
+ | `--ty-calendar-accent` | Selected day border + nav focus outline (default: `--ty-color-primary`) |
917
+ | `--ty-calendar-today-accent` | Today's border (default: `--ty-color-primary`) |
918
+ | `--ty-calendar-muted` | Default day text (default: `--ty-color-neutral`) |
919
+
920
+ ```html
921
+ <ty-calendar style="--ty-calendar-accent: hotpink;
922
+ --ty-calendar-today-accent: gold;"></ty-calendar>
923
+ ```
924
+
925
+ #### Day cell — fine-grained control
926
+
927
+ | Variable | Purpose |
928
+ |---|---|
929
+ | `--ty-calendar-day-color` | Default day text |
930
+ | `--ty-calendar-day-bg` | Default day background |
931
+ | `--ty-calendar-day-border` | Default day border |
932
+ | `--ty-calendar-day-radius` | Day cell border-radius |
933
+ | `--ty-calendar-day-hover-color` | Hover text |
934
+ | `--ty-calendar-day-hover-bg` | Hover background |
935
+ | `--ty-calendar-day-hover-border` | Hover border |
936
+ | `--ty-calendar-today-color` | Today text |
937
+ | `--ty-calendar-today-bg` | Today background |
938
+ | `--ty-calendar-today-border` | Today border |
939
+ | `--ty-calendar-selected-color` | Selected text |
940
+ | `--ty-calendar-selected-bg` | Selected background |
941
+ | `--ty-calendar-selected-border` | Selected border |
942
+ | `--ty-calendar-selected-hover-bg` | Selected + hover background |
943
+ | `--ty-calendar-selected-hover-border` | Selected + hover border |
944
+ | `--ty-calendar-weekend-color` | Saturday/Sunday text |
945
+ | `--ty-calendar-other-month-color` | Days from prev/next month |
946
+ | `--ty-calendar-other-month-opacity` | Other-month dimming (default `0.5`) |
947
+ | `--ty-calendar-header-color` | Weekday name row |
948
+
949
+ #### Navigation bar
950
+
951
+ | Variable | Purpose |
952
+ |---|---|
953
+ | `--ty-calendar-nav-color` | Prev/next chevron color |
954
+ | `--ty-calendar-nav-hover-color` | Chevron on hover |
955
+ | `--ty-calendar-nav-hover-bg` | Chevron button hover background |
956
+ | `--ty-calendar-nav-active-bg` | Chevron button pressed background |
957
+ | `--ty-calendar-nav-focus-outline` | Focus-visible outline (defaults to `--ty-calendar-accent`) |
958
+ | `--ty-calendar-nav-title-color` | Month/year display |
959
+
960
+ #### Popup surface (date-picker dialog)
961
+
962
+ | Variable | Purpose |
963
+ |---|---|
964
+ | `--ty-calendar-surface-bg` | Popup background |
965
+ | `--ty-calendar-surface-border` | Popup border |
966
+ | `--ty-calendar-surface-shadow` | Popup drop-shadow |
967
+ | `--ty-calendar-surface-radius` | Popup border-radius |
968
+
969
+ #### Time section (date-picker only)
970
+
971
+ | Variable | Purpose |
972
+ |---|---|
973
+ | `--ty-calendar-time-bg` | Time row background |
974
+ | `--ty-calendar-time-border` | Divider above time row |
975
+ | `--ty-calendar-time-label-color` | "Time" label color |
976
+ | `--ty-calendar-time-input-color` | HH/MM input text |
977
+ | `--ty-calendar-time-placeholder-color` | HH/MM placeholder |
978
+ | `--ty-calendar-time-icon-color` | Clock icon |
979
+
980
+ #### Date-picker stub (input-like trigger)
981
+
982
+ A thin shim over `--ty-input-*`. By default the stub looks identical to other inputs; override these to make it look distinct without affecting `<ty-input>`, `<ty-select>`, etc.
983
+
984
+ | Variable | Defaults to |
985
+ |---|---|
986
+ | `--ty-date-picker-bg` | `--ty-input-bg` |
987
+ | `--ty-date-picker-color` | `--ty-input-color` |
988
+ | `--ty-date-picker-placeholder` | `--ty-input-placeholder` |
989
+ | `--ty-date-picker-border` | `--ty-input-border` |
990
+ | `--ty-date-picker-border-hover` | `--ty-input-border-hover` |
991
+ | `--ty-date-picker-border-focus` | `--ty-input-border-focus` |
992
+ | `--ty-date-picker-shadow-focus` | `--ty-input-shadow-focus` |
993
+ | `--ty-date-picker-disabled-bg` | `--ty-input-disabled-bg` |
994
+ | `--ty-date-picker-disabled-color` | `--ty-input-disabled-color` |
995
+ | `--ty-date-picker-radius` | `--ty-radius-md` |
996
+
997
+ ```html
998
+ <!-- Make the date-picker trigger look like a "button" without affecting inputs -->
999
+ <ty-date-picker style="--ty-date-picker-bg: #f0fdf4;
1000
+ --ty-date-picker-border: #16a34a;
1001
+ --ty-date-picker-border-hover: #15803d;
1002
+ --ty-date-picker-border-focus: #15803d;
1003
+ --ty-date-picker-shadow-focus: rgba(22, 163, 74, 0.15);"></ty-date-picker>
1004
+
1005
+ <!-- Theme the popup body separately from the trigger -->
1006
+ <ty-date-picker style="--ty-calendar-surface-bg: #1a1a2e;
1007
+ --ty-calendar-surface-border: #2d2d44;
1008
+ --ty-calendar-selected-bg: #f72585;
1009
+ --ty-calendar-selected-color: white;"></ty-date-picker>
1010
+ ```
1011
+
1012
+ ### How it works
1013
+
1014
+ CSS custom properties inherit through shadow DOM boundaries. When you set `--ty-button-bg` on a `<ty-button>` host, the inner `<button>` inside the shadow root resolves `var(--ty-button-bg, …flavor default…)` — finds the host's value, uses it. Unset → falls back to the flavor's design token. The same mechanism applies to inputs/dropdowns/multiselects, just via the shared `--ty-input-*` token family.
1015
+
1016
+ **Tip — scoping by container**: setting an override on a wrapping `<div>` cascades to every descendant component, so you can theme a whole section (e.g. a settings panel) without touching individual elements.