@maggioli-design-system/magma 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (267) hide show
  1. package/AGENTS.md +1 -1
  2. package/CHANGELOG.md +24 -0
  3. package/agents/assets.md +23 -9
  4. package/agents/conventions.md +2 -1
  5. package/agents/lint.md +37 -9
  6. package/agents/mcp.md +6 -2
  7. package/agents/reporting.md +53 -2
  8. package/dist/collection/components/mds-accordion/AGENTS.md +1 -1
  9. package/dist/collection/components/mds-accordion/documentation.json +1 -1
  10. package/dist/collection/components/mds-accordion-item/AGENTS.md +1 -1
  11. package/dist/collection/components/mds-accordion-item/documentation.json +1 -1
  12. package/dist/collection/components/mds-accordion-timer/AGENTS.md +1 -1
  13. package/dist/collection/components/mds-accordion-timer/documentation.json +1 -1
  14. package/dist/collection/components/mds-accordion-timer-item/AGENTS.md +1 -1
  15. package/dist/collection/components/mds-accordion-timer-item/documentation.json +1 -1
  16. package/dist/collection/components/mds-author/AGENTS.md +1 -1
  17. package/dist/collection/components/mds-author/documentation.json +1 -1
  18. package/dist/collection/components/mds-avatar/AGENTS.md +1 -1
  19. package/dist/collection/components/mds-avatar/documentation.json +1 -1
  20. package/dist/collection/components/mds-avatar-stack/AGENTS.md +1 -1
  21. package/dist/collection/components/mds-avatar-stack/documentation.json +1 -1
  22. package/dist/collection/components/mds-avatar-stack-item/AGENTS.md +1 -1
  23. package/dist/collection/components/mds-avatar-stack-item/documentation.json +1 -1
  24. package/dist/collection/components/mds-badge/AGENTS.md +1 -1
  25. package/dist/collection/components/mds-badge/documentation.json +1 -1
  26. package/dist/collection/components/mds-banner/AGENTS.md +1 -1
  27. package/dist/collection/components/mds-banner/documentation.json +1 -1
  28. package/dist/collection/components/mds-benchmark-bar/AGENTS.md +1 -1
  29. package/dist/collection/components/mds-benchmark-bar/documentation.json +1 -1
  30. package/dist/collection/components/mds-bibliography/AGENTS.md +1 -1
  31. package/dist/collection/components/mds-bibliography/documentation.json +1 -1
  32. package/dist/collection/components/mds-book/AGENTS.md +1 -1
  33. package/dist/collection/components/mds-book/documentation.json +1 -1
  34. package/dist/collection/components/mds-breadcrumb/AGENTS.md +1 -1
  35. package/dist/collection/components/mds-breadcrumb/documentation.json +1 -1
  36. package/dist/collection/components/mds-breadcrumb-item/AGENTS.md +1 -1
  37. package/dist/collection/components/mds-breadcrumb-item/documentation.json +1 -1
  38. package/dist/collection/components/mds-button/AGENTS.md +1 -1
  39. package/dist/collection/components/mds-button/documentation.json +1 -1
  40. package/dist/collection/components/mds-button-dropdown/AGENTS.md +1 -1
  41. package/dist/collection/components/mds-button-dropdown/documentation.json +1 -1
  42. package/dist/collection/components/mds-button-group/AGENTS.md +1 -1
  43. package/dist/collection/components/mds-button-group/documentation.json +1 -1
  44. package/dist/collection/components/mds-calendar/AGENTS.md +1 -1
  45. package/dist/collection/components/mds-calendar/documentation.json +1 -1
  46. package/dist/collection/components/mds-calendar-cell/AGENTS.md +1 -1
  47. package/dist/collection/components/mds-calendar-cell/documentation.json +1 -1
  48. package/dist/collection/components/mds-card/AGENTS.md +1 -1
  49. package/dist/collection/components/mds-card/documentation.json +1 -1
  50. package/dist/collection/components/mds-card-content/AGENTS.md +1 -1
  51. package/dist/collection/components/mds-card-content/documentation.json +1 -1
  52. package/dist/collection/components/mds-card-footer/AGENTS.md +1 -1
  53. package/dist/collection/components/mds-card-footer/documentation.json +1 -1
  54. package/dist/collection/components/mds-card-header/AGENTS.md +1 -1
  55. package/dist/collection/components/mds-card-header/documentation.json +1 -1
  56. package/dist/collection/components/mds-card-media/AGENTS.md +1 -1
  57. package/dist/collection/components/mds-card-media/documentation.json +1 -1
  58. package/dist/collection/components/mds-chip/AGENTS.md +1 -1
  59. package/dist/collection/components/mds-chip/documentation.json +1 -1
  60. package/dist/collection/components/mds-details/AGENTS.md +1 -1
  61. package/dist/collection/components/mds-details/documentation.json +1 -1
  62. package/dist/collection/components/mds-dropdown/AGENTS.md +1 -1
  63. package/dist/collection/components/mds-dropdown/documentation.json +1 -1
  64. package/dist/collection/components/mds-emoji/AGENTS.md +1 -1
  65. package/dist/collection/components/mds-emoji/documentation.json +1 -1
  66. package/dist/collection/components/mds-entity/AGENTS.md +1 -1
  67. package/dist/collection/components/mds-entity/documentation.json +1 -1
  68. package/dist/collection/components/mds-file/AGENTS.md +1 -1
  69. package/dist/collection/components/mds-file/documentation.json +1 -1
  70. package/dist/collection/components/mds-file-preview/AGENTS.md +1 -1
  71. package/dist/collection/components/mds-file-preview/documentation.json +1 -1
  72. package/dist/collection/components/mds-filter/AGENTS.md +1 -1
  73. package/dist/collection/components/mds-filter/documentation.json +1 -1
  74. package/dist/collection/components/mds-filter-item/AGENTS.md +1 -1
  75. package/dist/collection/components/mds-filter-item/documentation.json +1 -1
  76. package/dist/collection/components/mds-header/AGENTS.md +1 -1
  77. package/dist/collection/components/mds-header/documentation.json +1 -1
  78. package/dist/collection/components/mds-header-bar/AGENTS.md +1 -1
  79. package/dist/collection/components/mds-header-bar/documentation.json +1 -1
  80. package/dist/collection/components/mds-help/AGENTS.md +1 -1
  81. package/dist/collection/components/mds-help/documentation.json +1 -1
  82. package/dist/collection/components/mds-horizontal-scroll/AGENTS.md +1 -1
  83. package/dist/collection/components/mds-horizontal-scroll/documentation.json +1 -1
  84. package/dist/collection/components/mds-hr/AGENTS.md +1 -1
  85. package/dist/collection/components/mds-hr/documentation.json +1 -1
  86. package/dist/collection/components/mds-icon/AGENTS.md +1 -1
  87. package/dist/collection/components/mds-icon/documentation.json +1 -1
  88. package/dist/collection/components/mds-img/AGENTS.md +1 -1
  89. package/dist/collection/components/mds-img/documentation.json +1 -1
  90. package/dist/collection/components/mds-input/AGENTS.md +1 -1
  91. package/dist/collection/components/mds-input/documentation.json +1 -1
  92. package/dist/collection/components/mds-input-date/AGENTS.md +1 -1
  93. package/dist/collection/components/mds-input-date/documentation.json +1 -1
  94. package/dist/collection/components/mds-input-date-range/AGENTS.md +1 -1
  95. package/dist/collection/components/mds-input-date-range/documentation.json +1 -1
  96. package/dist/collection/components/mds-input-date-range-preselection/AGENTS.md +1 -1
  97. package/dist/collection/components/mds-input-date-range-preselection/documentation.json +1 -1
  98. package/dist/collection/components/mds-input-field/AGENTS.md +1 -1
  99. package/dist/collection/components/mds-input-field/documentation.json +1 -1
  100. package/dist/collection/components/mds-input-otp/AGENTS.md +1 -1
  101. package/dist/collection/components/mds-input-otp/documentation.json +1 -1
  102. package/dist/collection/components/mds-input-range/AGENTS.md +1 -1
  103. package/dist/collection/components/mds-input-range/documentation.json +1 -1
  104. package/dist/collection/components/mds-input-select/AGENTS.md +1 -1
  105. package/dist/collection/components/mds-input-select/documentation.json +1 -1
  106. package/dist/collection/components/mds-input-switch/AGENTS.md +1 -1
  107. package/dist/collection/components/mds-input-switch/documentation.json +1 -1
  108. package/dist/collection/components/mds-input-tip/AGENTS.md +1 -1
  109. package/dist/collection/components/mds-input-tip/documentation.json +1 -1
  110. package/dist/collection/components/mds-input-tip-item/AGENTS.md +1 -1
  111. package/dist/collection/components/mds-input-tip-item/documentation.json +1 -1
  112. package/dist/collection/components/mds-input-upload/AGENTS.md +1 -1
  113. package/dist/collection/components/mds-input-upload/documentation.json +1 -1
  114. package/dist/collection/components/mds-keyboard/AGENTS.md +1 -1
  115. package/dist/collection/components/mds-keyboard/documentation.json +1 -1
  116. package/dist/collection/components/mds-keyboard-key/AGENTS.md +1 -1
  117. package/dist/collection/components/mds-keyboard-key/documentation.json +1 -1
  118. package/dist/collection/components/mds-kpi/AGENTS.md +1 -1
  119. package/dist/collection/components/mds-kpi/documentation.json +1 -1
  120. package/dist/collection/components/mds-kpi-item/AGENTS.md +1 -1
  121. package/dist/collection/components/mds-kpi-item/documentation.json +1 -1
  122. package/dist/collection/components/mds-label/AGENTS.md +1 -1
  123. package/dist/collection/components/mds-label/documentation.json +1 -1
  124. package/dist/collection/components/mds-link/AGENTS.md +1 -1
  125. package/dist/collection/components/mds-link/documentation.json +1 -1
  126. package/dist/collection/components/mds-list/AGENTS.md +1 -1
  127. package/dist/collection/components/mds-list/documentation.json +1 -1
  128. package/dist/collection/components/mds-list-item/AGENTS.md +1 -1
  129. package/dist/collection/components/mds-list-item/documentation.json +1 -1
  130. package/dist/collection/components/mds-mention/AGENTS.md +1 -1
  131. package/dist/collection/components/mds-mention/documentation.json +1 -1
  132. package/dist/collection/components/mds-modal/AGENTS.md +1 -1
  133. package/dist/collection/components/mds-modal/documentation.json +1 -1
  134. package/dist/collection/components/mds-note/AGENTS.md +1 -1
  135. package/dist/collection/components/mds-note/documentation.json +1 -1
  136. package/dist/collection/components/mds-notification/AGENTS.md +1 -1
  137. package/dist/collection/components/mds-notification/documentation.json +1 -1
  138. package/dist/collection/components/mds-paginator/AGENTS.md +1 -1
  139. package/dist/collection/components/mds-paginator/documentation.json +1 -1
  140. package/dist/collection/components/mds-paginator-item/AGENTS.md +1 -1
  141. package/dist/collection/components/mds-paginator-item/documentation.json +1 -1
  142. package/dist/collection/components/mds-policy-ai/AGENTS.md +1 -1
  143. package/dist/collection/components/mds-policy-ai/documentation.json +1 -1
  144. package/dist/collection/components/mds-pref/AGENTS.md +1 -1
  145. package/dist/collection/components/mds-pref/documentation.json +1 -1
  146. package/dist/collection/components/mds-pref-animation/AGENTS.md +1 -1
  147. package/dist/collection/components/mds-pref-animation/documentation.json +1 -1
  148. package/dist/collection/components/mds-pref-consumption/AGENTS.md +1 -1
  149. package/dist/collection/components/mds-pref-consumption/documentation.json +1 -1
  150. package/dist/collection/components/mds-pref-contrast/AGENTS.md +1 -1
  151. package/dist/collection/components/mds-pref-contrast/documentation.json +1 -1
  152. package/dist/collection/components/mds-pref-language/AGENTS.md +1 -1
  153. package/dist/collection/components/mds-pref-language/documentation.json +1 -1
  154. package/dist/collection/components/mds-pref-language-item/AGENTS.md +1 -1
  155. package/dist/collection/components/mds-pref-language-item/documentation.json +1 -1
  156. package/dist/collection/components/mds-pref-mode/AGENTS.md +1 -1
  157. package/dist/collection/components/mds-pref-mode/documentation.json +1 -1
  158. package/dist/collection/components/mds-pref-theme/AGENTS.md +1 -1
  159. package/dist/collection/components/mds-pref-theme/documentation.json +1 -1
  160. package/dist/collection/components/mds-pref-theme-item/AGENTS.md +1 -1
  161. package/dist/collection/components/mds-pref-theme-item/documentation.json +1 -1
  162. package/dist/collection/components/mds-price-table/AGENTS.md +1 -1
  163. package/dist/collection/components/mds-price-table/documentation.json +1 -1
  164. package/dist/collection/components/mds-price-table-features/AGENTS.md +1 -1
  165. package/dist/collection/components/mds-price-table-features/documentation.json +1 -1
  166. package/dist/collection/components/mds-price-table-features-cell/AGENTS.md +1 -1
  167. package/dist/collection/components/mds-price-table-features-cell/documentation.json +1 -1
  168. package/dist/collection/components/mds-price-table-features-row/AGENTS.md +1 -1
  169. package/dist/collection/components/mds-price-table-features-row/documentation.json +1 -1
  170. package/dist/collection/components/mds-price-table-header/AGENTS.md +1 -1
  171. package/dist/collection/components/mds-price-table-header/documentation.json +1 -1
  172. package/dist/collection/components/mds-price-table-list/AGENTS.md +1 -1
  173. package/dist/collection/components/mds-price-table-list/documentation.json +1 -1
  174. package/dist/collection/components/mds-price-table-list-item/AGENTS.md +1 -1
  175. package/dist/collection/components/mds-price-table-list-item/documentation.json +1 -1
  176. package/dist/collection/components/mds-progress/AGENTS.md +1 -1
  177. package/dist/collection/components/mds-progress/documentation.json +1 -1
  178. package/dist/collection/components/mds-push-notification/AGENTS.md +1 -1
  179. package/dist/collection/components/mds-push-notification/documentation.json +1 -1
  180. package/dist/collection/components/mds-push-notification-item/AGENTS.md +1 -1
  181. package/dist/collection/components/mds-push-notification-item/documentation.json +1 -1
  182. package/dist/collection/components/mds-quote/AGENTS.md +1 -1
  183. package/dist/collection/components/mds-quote/documentation.json +1 -1
  184. package/dist/collection/components/mds-radial-menu/AGENTS.md +1 -1
  185. package/dist/collection/components/mds-radial-menu/documentation.json +1 -1
  186. package/dist/collection/components/mds-radial-menu-item/AGENTS.md +1 -1
  187. package/dist/collection/components/mds-radial-menu-item/documentation.json +1 -1
  188. package/dist/collection/components/mds-radial-progress/AGENTS.md +1 -1
  189. package/dist/collection/components/mds-radial-progress/documentation.json +1 -1
  190. package/dist/collection/components/mds-separator/AGENTS.md +1 -1
  191. package/dist/collection/components/mds-separator/documentation.json +1 -1
  192. package/dist/collection/components/mds-spinner/AGENTS.md +1 -1
  193. package/dist/collection/components/mds-spinner/documentation.json +1 -1
  194. package/dist/collection/components/mds-status-bar/AGENTS.md +1 -1
  195. package/dist/collection/components/mds-status-bar/documentation.json +1 -1
  196. package/dist/collection/components/mds-stepper-bar/AGENTS.md +1 -1
  197. package/dist/collection/components/mds-stepper-bar/documentation.json +1 -1
  198. package/dist/collection/components/mds-stepper-bar-item/AGENTS.md +1 -1
  199. package/dist/collection/components/mds-stepper-bar-item/documentation.json +1 -1
  200. package/dist/collection/components/mds-tab/AGENTS.md +1 -1
  201. package/dist/collection/components/mds-tab/documentation.json +1 -1
  202. package/dist/collection/components/mds-tab-bar/AGENTS.md +1 -1
  203. package/dist/collection/components/mds-tab-bar/documentation.json +1 -1
  204. package/dist/collection/components/mds-tab-bar-item/AGENTS.md +1 -1
  205. package/dist/collection/components/mds-tab-bar-item/documentation.json +1 -1
  206. package/dist/collection/components/mds-tab-item/AGENTS.md +1 -1
  207. package/dist/collection/components/mds-tab-item/documentation.json +1 -1
  208. package/dist/collection/components/mds-table/AGENTS.md +1 -1
  209. package/dist/collection/components/mds-table/documentation.json +1 -1
  210. package/dist/collection/components/mds-table-body/AGENTS.md +1 -1
  211. package/dist/collection/components/mds-table-body/documentation.json +1 -1
  212. package/dist/collection/components/mds-table-cell/AGENTS.md +1 -1
  213. package/dist/collection/components/mds-table-cell/documentation.json +1 -1
  214. package/dist/collection/components/mds-table-footer/AGENTS.md +1 -1
  215. package/dist/collection/components/mds-table-footer/documentation.json +1 -1
  216. package/dist/collection/components/mds-table-header/AGENTS.md +1 -1
  217. package/dist/collection/components/mds-table-header/documentation.json +1 -1
  218. package/dist/collection/components/mds-table-header-cell/AGENTS.md +1 -1
  219. package/dist/collection/components/mds-table-header-cell/documentation.json +1 -1
  220. package/dist/collection/components/mds-table-row/AGENTS.md +1 -1
  221. package/dist/collection/components/mds-table-row/documentation.json +1 -1
  222. package/dist/collection/components/mds-text/AGENTS.md +1 -1
  223. package/dist/collection/components/mds-text/documentation.json +1 -1
  224. package/dist/collection/components/mds-toast/AGENTS.md +1 -1
  225. package/dist/collection/components/mds-toast/documentation.json +1 -1
  226. package/dist/collection/components/mds-toast-region/AGENTS.md +1 -1
  227. package/dist/collection/components/mds-toast-region/documentation.json +1 -1
  228. package/dist/collection/components/mds-tooltip/AGENTS.md +1 -1
  229. package/dist/collection/components/mds-tooltip/documentation.json +1 -1
  230. package/dist/collection/components/mds-tree/AGENTS.md +1 -1
  231. package/dist/collection/components/mds-tree/documentation.json +1 -1
  232. package/dist/collection/components/mds-tree-item/AGENTS.md +1 -1
  233. package/dist/collection/components/mds-tree-item/documentation.json +1 -1
  234. package/dist/collection/components/mds-url-view/AGENTS.md +1 -1
  235. package/dist/collection/components/mds-url-view/documentation.json +1 -1
  236. package/dist/collection/components/mds-usage/AGENTS.md +1 -1
  237. package/dist/collection/components/mds-usage/documentation.json +1 -1
  238. package/dist/collection/components/mds-video-wall/AGENTS.md +1 -1
  239. package/dist/collection/components/mds-video-wall/documentation.json +1 -1
  240. package/dist/collection/components/mds-zero/AGENTS.md +1 -1
  241. package/dist/collection/components/mds-zero/documentation.json +1 -1
  242. package/dist/documentation.json +1 -1
  243. package/dist/lint/core/checks.d.ts +16 -2
  244. package/dist/lint/core/checks.js +32 -24
  245. package/dist/lint/core/data.d.ts +8 -0
  246. package/dist/lint/core/data.js +15 -0
  247. package/dist/lint/core/element.d.ts +1 -1
  248. package/dist/lint/eslint/adapters.d.ts +2 -0
  249. package/dist/lint/eslint/adapters.js +50 -13
  250. package/dist/lint/eslint/index.js +5 -4
  251. package/dist/lint/mcp/checks.js +60 -24
  252. package/dist/lint/mcp/components.js +7 -7
  253. package/dist/lint/mcp/context.d.ts +11 -0
  254. package/dist/lint/mcp/context.js +11 -0
  255. package/dist/lint/mcp/icons.js +46 -20
  256. package/dist/lint/mcp/protocol.d.ts +17 -0
  257. package/dist/lint/mcp/protocol.js +15 -10
  258. package/dist/lint/mcp/server.d.ts +17 -0
  259. package/dist/lint/mcp/server.js +7 -1
  260. package/dist/lint/mcp/tokens.d.ts +15 -0
  261. package/dist/lint/mcp/tokens.js +170 -48
  262. package/dist/lint/mcp/tools.json +962 -0
  263. package/dist/lint/stylelint/index.js +80 -14
  264. package/dist/lint/stylelint/recommended.js +1 -0
  265. package/dist/lint/stylelint/strict.js +1 -0
  266. package/dist/stats.json +1 -1
  267. package/package.json +2 -1
@@ -3,16 +3,28 @@
3
3
  set and each set lives in its own package (agents/assets.md, "Icons"): mi/<variant>/<name>
4
4
  from @material-icons/svg (searched with the tags of its data.json), mdi/<name> from @mdi/svg
5
5
  (with the aliases and tags of its meta.json), mgg/<name> from svg-icons (by name).
6
+
7
+ The slug is what the active iconsauce plugin writes (mds-icon, "2. Pattern.md"), not the name
8
+ of the file in the package: @iconsauce/material-icons spells a Material name with hyphens
9
+ (check_circle/baseline.svg is mi/baseline/check-circle) and serves the variants baseline,
10
+ outline, round and sharp only, so a twotone slug is a 404 there. No Material folder has a
11
+ hyphen, so the two spellings convert one into the other.
6
12
  */
7
13
  import { existsSync, readdirSync } from 'node:fs';
8
14
  import path from 'node:path';
9
- import { packageDir, readJsonFile, wordsOf } from './context.js';
15
+ import { GAP, GAP_SCHEMA, packageDir, readJsonFile, wordsOf } from './context.js';
10
16
  import { ToolError } from './protocol.js';
11
17
  const PACKAGES = {
12
18
  mi: { name: '@material-icons/svg', svg: 'svg' },
13
19
  mdi: { name: '@mdi/svg', svg: 'svg' },
14
20
  mgg: { name: '@maggioli-design-system/svg-icons', svg: 'dist/svg' },
15
21
  };
22
+ /** The Material variants a slug can name: the ones @iconsauce/material-icons serves. */
23
+ const MI_VARIANTS = ['baseline', 'outline', 'round', 'sharp'];
24
+ /** `check_circle` (the folder of @material-icons/svg) -> `check-circle` (the slug). */
25
+ const miSlugName = (folder) => folder.replace(/_/g, '-');
26
+ /** `check-circle` (the slug) -> `check_circle` (the folder). */
27
+ const miFolder = (name) => name.replace(/-/g, '_');
16
28
  /** The svg folder of a set: the setting of the tests, else the installed package. */
17
29
  const folderOf = (context, set) => {
18
30
  if (context.icons?.[set])
@@ -27,10 +39,10 @@ const iconsOf = (context, set, folder) => {
27
39
  if (data)
28
40
  return data.icons.map(({ name, tags = [] }) => ({
29
41
  set,
30
- name,
42
+ name: miSlugName(name),
31
43
  words: tags.map((tag) => tag.toLowerCase()),
32
44
  }));
33
- return readdirSync(folder).map((name) => ({ set, name, words: [] }));
45
+ return readdirSync(folder).map((name) => ({ set, name: miSlugName(name), words: [] }));
34
46
  }
35
47
  if (set === 'mdi') {
36
48
  const meta = readJsonFile(path.join(folder, '../meta.json'));
@@ -50,8 +62,11 @@ const iconsOf = (context, set, folder) => {
50
62
  /** The file a slug is served from, in its package. */
51
63
  const fileOf = (folder, slug) => {
52
64
  const [set, ...rest] = slug.split('/');
65
+ // an underscore is the folder's spelling, which no slug served by iconsauce has
53
66
  if (set === 'mi' && rest.length === 2)
54
- return path.join(folder, rest[1], `${rest[0]}.svg`);
67
+ return MI_VARIANTS.includes(rest[0]) && !rest[1].includes('_')
68
+ ? path.join(folder, miFolder(rest[1]), `${rest[0]}.svg`)
69
+ : undefined;
55
70
  if ((set === 'mdi' || set === 'mgg') && rest.length === 1)
56
71
  return path.join(folder, `${rest[0]}.svg`);
57
72
  return undefined;
@@ -68,7 +83,8 @@ export const findIcon = (context) => ({
68
83
  set: { type: 'string', enum: ['mi', 'mdi', 'mgg'], description: 'Search one set only.' },
69
84
  variant: {
70
85
  type: 'string',
71
- description: 'The Material Icons variant of the slugs found: baseline (default), outline, round, sharp, twotone.',
86
+ enum: MI_VARIANTS,
87
+ description: 'The Material Icons variant of the slugs found: baseline (default), outline, round, sharp.',
72
88
  },
73
89
  limit: { type: 'number', description: 'How many to return, 12 by default.' },
74
90
  },
@@ -101,6 +117,7 @@ export const findIcon = (context) => ({
101
117
  required: ['slug', 'set', 'name'],
102
118
  },
103
119
  },
120
+ gap: GAP_SCHEMA,
104
121
  },
105
122
  required: ['sets', 'icons'],
106
123
  },
@@ -113,28 +130,37 @@ export const findIcon = (context) => ({
113
130
  installed: Boolean(folders.get(one)),
114
131
  }));
115
132
  const miVariant = typeof variant === 'string' && variant ? variant : 'baseline';
133
+ if (!MI_VARIANTS.includes(miVariant))
134
+ throw new ToolError(`"${miVariant}" is not a Material Icons variant a slug can name: ${MI_VARIANTS.join(', ')}.`);
116
135
  const slugOf = (icon) => icon.set === 'mi' ? `mi/${miVariant}/${icon.name}` : `${icon.set}/${icon.name}`;
117
136
  if (typeof slug === 'string' && slug) {
118
137
  const own = slug.split('/')[0];
119
138
  const folder = PACKAGES[own] ? (folders.get(own) ?? folderOf(context, own)) : undefined;
120
139
  const file = folder && fileOf(folder, slug);
121
140
  const exists = Boolean(file && existsSync(file));
122
- // when it does not exist, the icons of the same name in the installed sets
123
- const name = slug.split('/').pop();
141
+ // when it does not exist, the icons of the same name in the installed sets, in the
142
+ // variant the slug asked for; an underscore (the folder's spelling) reads as a hyphen
143
+ const parts = slug.split('/');
144
+ const name = miSlugName(parts.pop());
145
+ const asked = own === 'mi' && MI_VARIANTS.includes(parts[1]) ? parts[1] : miVariant;
124
146
  const near = exists
125
147
  ? []
126
- : sets.flatMap((one) => {
148
+ : sets
149
+ .flatMap((one) => {
127
150
  const dir = folders.get(one);
128
151
  return dir
129
152
  ? iconsOf(context, one, dir).filter((icon) => icon.name.includes(name) || name.includes(icon.name))
130
153
  : [];
131
- });
154
+ })
155
+ .sort((a, b) => Number(b.name === name) - Number(a.name === name));
132
156
  return {
133
157
  sets: status,
134
158
  exists,
135
- icons: near
136
- .slice(0, 12)
137
- .map((icon) => ({ slug: slugOf(icon), set: icon.set, name: icon.name })),
159
+ icons: near.slice(0, 12).map((icon) => ({
160
+ slug: icon.set === 'mi' ? `mi/${asked}/${icon.name}` : slugOf(icon),
161
+ set: icon.set,
162
+ name: icon.name,
163
+ })),
138
164
  };
139
165
  }
140
166
  const words = wordsOf(String(query ?? ''));
@@ -158,13 +184,13 @@ export const findIcon = (context) => ({
158
184
  return { icon, score };
159
185
  });
160
186
  });
161
- return {
162
- sets: status,
163
- icons: scored
164
- .filter(({ score }) => score > 0)
165
- .sort((a, b) => b.score - a.score || a.icon.name.length - b.icon.name.length)
166
- .slice(0, typeof limit === 'number' && limit > 0 ? limit : 12)
167
- .map(({ icon }) => ({ slug: slugOf(icon), set: icon.set, name: icon.name })),
168
- };
187
+ const icons = scored
188
+ .filter(({ score }) => score > 0)
189
+ .sort((a, b) => b.score - a.score || a.icon.name.length - b.icon.name.length)
190
+ .slice(0, typeof limit === 'number' && limit > 0 ? limit : 12)
191
+ .map(({ icon }) => ({ slug: slugOf(icon), set: icon.set, name: icon.name }));
192
+ // with no set installed the gap is the project's, which `sets` already says
193
+ const searched = status.some((one) => one.installed);
194
+ return { sets: status, icons, ...(searched && !icons.length ? { gap: GAP } : {}) };
169
195
  },
170
196
  });
@@ -12,6 +12,23 @@ export interface Tool {
12
12
  /** Read-only: no tool of this server changes the project or the world. */
13
13
  run: (args: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
14
14
  }
15
+ /**
16
+ * The answer of `tools/list`: what a client learns of each tool. The stencil build writes the
17
+ * same object into dist/lint/mcp/tools.json, for the documentation.
18
+ */
19
+ export declare const toolList: (tools: Tool[]) => {
20
+ tools: {
21
+ name: string;
22
+ title: string;
23
+ description: string;
24
+ inputSchema: JsonSchema;
25
+ outputSchema: JsonSchema;
26
+ annotations: {
27
+ readOnlyHint: boolean;
28
+ openWorldHint: boolean;
29
+ };
30
+ }[];
31
+ };
15
32
  /** A failure the tool explains to the agent: returned as a tool error, not a protocol one. */
16
33
  export declare class ToolError extends Error {
17
34
  }
@@ -9,6 +9,20 @@
9
9
  */
10
10
  /** The protocol versions this server can speak, newest first. */
11
11
  export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
12
+ /**
13
+ * The answer of `tools/list`: what a client learns of each tool. The stencil build writes the
14
+ * same object into dist/lint/mcp/tools.json, for the documentation.
15
+ */
16
+ export const toolList = (tools) => ({
17
+ tools: tools.map(({ name, title, description, inputSchema, outputSchema }) => ({
18
+ name,
19
+ title,
20
+ description,
21
+ inputSchema,
22
+ outputSchema,
23
+ annotations: { readOnlyHint: true, openWorldHint: false },
24
+ })),
25
+ });
12
26
  /** A failure the tool explains to the agent: returned as a tool error, not a protocol one. */
13
27
  export class ToolError extends Error {
14
28
  }
@@ -48,16 +62,7 @@ export const createHandler = (tools, info, instructions) => async (message) => {
48
62
  case 'ping':
49
63
  return ok({});
50
64
  case 'tools/list':
51
- return ok({
52
- tools: tools.map(({ name, title, description, inputSchema, outputSchema }) => ({
53
- name,
54
- title,
55
- description,
56
- inputSchema,
57
- outputSchema,
58
- annotations: { readOnlyHint: true, openWorldHint: false },
59
- })),
60
- });
65
+ return ok(toolList(tools));
61
66
  case 'tools/call': {
62
67
  const tool = tools.find((one) => one.name === params.name);
63
68
  if (!tool)
@@ -3,6 +3,23 @@ import { type Tool } from './protocol.js';
3
3
  /** What the agent reads when it connects: when to reach for the server. */
4
4
  export declare const INSTRUCTIONS: string;
5
5
  export declare const toolsOf: (context: ToolContext) => Tool[];
6
+ /**
7
+ * The tools as data, the answer of `tools/list`: a definition reads nothing of the project, so
8
+ * any context gives the same. The stencil build writes it into dist/lint/mcp/tools.json.
9
+ */
10
+ export declare const toolsList: (context: ToolContext) => {
11
+ tools: {
12
+ name: string;
13
+ title: string;
14
+ description: string;
15
+ inputSchema: import("./protocol.js").JsonSchema;
16
+ outputSchema: import("./protocol.js").JsonSchema;
17
+ annotations: {
18
+ readOnlyHint: boolean;
19
+ openWorldHint: boolean;
20
+ };
21
+ }[];
22
+ };
6
23
  export declare const createServer: (context: ToolContext) => {
7
24
  tools: Tool[];
8
25
  handle: (message: unknown) => Promise<({
@@ -12,13 +12,14 @@ import { checkMarkup, checkSetup } from './checks.js';
12
12
  import { findComponent, getComponent, getUsage } from './components.js';
13
13
  import { getGuide } from './guides.js';
14
14
  import { findIcon } from './icons.js';
15
- import { createHandler } from './protocol.js';
15
+ import { createHandler, toolList } from './protocol.js';
16
16
  import { explainClass, listTokens, suggestRole } from './tokens.js';
17
17
  /** What the agent reads when it connects: when to reach for the server. */
18
18
  export const INSTRUCTIONS = [
19
19
  'Magma is the design system of this project: web components (mds-*), tokens and Tailwind classes. The tools answer from the version installed here.',
20
20
  'Before writing a component, find it (find_component), read its API (get_component) and how your framework writes it (get_usage). Before a colour, a spacing or a class, ask list_tokens, suggest_role or explain_class: Magma spacing steps are hundredths of a rem (p-4 is 0.01rem, p-400 is 1rem).',
21
21
  'Before an icon slug, check it with find_icon. After writing, check the snippet with check_markup. When the integration itself may be incomplete, run check_setup. For a rule or a setup step, read the section you need with get_guide.',
22
+ 'When you need something these tools do not answer (you had to read Magma files by hand or guess, or an answer carries gap), tell the user, and at the end of the task propose an issue on Magma, one per missing capability, as get_guide reporting describes (section "A tool or an answer the MCP server is missing"); open it only once the user agrees.',
22
23
  ].join(' ');
23
24
  export const toolsOf = (context) => [
24
25
  findComponent,
@@ -32,6 +33,11 @@ export const toolsOf = (context) => [
32
33
  checkMarkup,
33
34
  checkSetup,
34
35
  ].map((tool) => tool(context));
36
+ /**
37
+ * The tools as data, the answer of `tools/list`: a definition reads nothing of the project, so
38
+ * any context gives the same. The stencil build writes it into dist/lint/mcp/tools.json.
39
+ */
40
+ export const toolsList = (context) => toolList(toolsOf(context));
35
41
  /**
36
42
  * The Magma mark, the icon a client may show next to the server: the stencil build copies it
37
43
  * from the build of identity beside this module (dist/lint/mcp/icon.svg). None from the sources.
@@ -15,8 +15,23 @@ export interface TokenEntry {
15
15
  /** The light colour, for a colour token. */
16
16
  rgb?: Rgb;
17
17
  }
18
+ export declare const cssValueOf: (type: string, value: unknown) => string | undefined;
18
19
  /** Every token of the base sets of design-tokens and styles, with its light value. */
19
20
  export declare const tokensOf: (context: ToolContext) => TokenEntry[];
21
+ /**
22
+ * What a colour paints, the family of roles that fits it: text (glyphs, lines and icons, whose
23
+ * fill follows the text), a border, a background (an area: a fill, a gradient stop) or a shadow
24
+ * (a projected shadow, `--magma-shadow-ink`, or a glow tinted with a fill role).
25
+ */
26
+ type Use = 'text' | 'border' | 'background' | 'shadow';
27
+ /**
28
+ * What each colour utility paints, from the CSS property Tailwind writes for it: every root of
29
+ * the `--color` namespace of the consumption map is here (a test holds the table to it), so a
30
+ * root Tailwind adds is a failing test, not a background by default. The mask utilities read
31
+ * only the alpha of a colour: no role fits them.
32
+ */
33
+ export declare const USE_OF_UTILITY: Record<string, Use | 'none'>;
20
34
  export declare const listTokens: (context: ToolContext) => Tool;
21
35
  export declare const suggestRole: (context: ToolContext) => Tool;
22
36
  export declare const explainClass: (context: ToolContext) => Tool;
37
+ export {};
@@ -8,26 +8,81 @@ import { loadPalette, readData } from '../core/data.js';
8
8
  import { utilityOf } from '../core/checks.js';
9
9
  import { readFileSync } from 'node:fs';
10
10
  import { distance, parseColor, toHex } from './color.js';
11
- import { resolvePackage, wordsOf } from './context.js';
11
+ import { GAP, GAP_SCHEMA, resolvePackage, wordsOf } from './context.js';
12
12
  import { ToolError } from './protocol.js';
13
13
  const NAMESPACE = 'it.maggioli.magma';
14
14
  const isToken = (node) => typeof node === 'object' && node !== null && '$value' in node;
15
- const cssValue = (value) => {
16
- if (typeof value === 'string' || typeof value === 'number')
17
- return String(value);
18
- if (Array.isArray(value))
19
- return value.every((one) => typeof one === 'number')
20
- ? `cubic-bezier(${value.join(', ')})`
21
- : value.join(', ');
22
- if (value && typeof value === 'object') {
23
- const object = value;
24
- if (typeof object.hex === 'string')
25
- return object.hex;
26
- if ('value' in object && 'unit' in object)
27
- return `${object.value}${object.unit}`;
28
- }
29
- return undefined;
15
+ const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
16
+ ? value
17
+ : undefined;
18
+ const plain = (value) => typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
19
+ const dimension = (value) => {
20
+ const object = record(value);
21
+ if (object && typeof object.value === 'number' && typeof object.unit === 'string')
22
+ return `${object.value}${object.unit}`;
23
+ return plain(value);
24
+ };
25
+ /** Opaque: the hex; with an alpha: rgb() with it, from the sRGB components. */
26
+ const color = (value) => {
27
+ const object = record(value);
28
+ if (!object)
29
+ return plain(value);
30
+ const { hex, alpha, components, colorSpace } = object;
31
+ if (alpha === undefined || alpha === 1)
32
+ return hex;
33
+ if (colorSpace === 'srgb' && components?.length === 3)
34
+ return `rgb(${components.map((one) => Math.round(one * 255)).join(' ')} / ${alpha})`;
35
+ return hex
36
+ ? `${hex}${Math.round(alpha * 255)
37
+ .toString(16)
38
+ .padStart(2, '0')}`
39
+ : undefined;
40
+ };
41
+ /** A name that is not one identifier is quoted, as the CSS of design-tokens writes it. */
42
+ const fontFamily = (value) => {
43
+ const names = Array.isArray(value) ? value : [value];
44
+ if (!names.every((name) => typeof name === 'string'))
45
+ return undefined;
46
+ return names
47
+ .map((name) => (/^-?[\w-]+$/.test(name) ? name : `'${name}'`))
48
+ .join(', ');
49
+ };
50
+ const cubicBezier = (value) => Array.isArray(value) && value.length === 4 && value.every((one) => typeof one === 'number')
51
+ ? `cubic-bezier(${value.join(', ')})`
52
+ : plain(value);
53
+ /** The parts of a composite, each by its serializer, or undefined when one has none. */
54
+ const parts = (...values) => values.every((one) => one !== undefined) ? values : undefined;
55
+ const shadowLayer = (value) => {
56
+ const layer = record(value);
57
+ const geometry = layer &&
58
+ parts(dimension(layer.offsetX), dimension(layer.offsetY), dimension(layer.blur), dimension(layer.spread), color(layer.color));
59
+ return geometry && [...(layer.inset === true ? ['inset'] : []), ...geometry].join(' ');
60
+ };
61
+ const SERIALIZERS = {
62
+ color,
63
+ dimension,
64
+ duration: dimension,
65
+ fontFamily,
66
+ fontWeight: plain,
67
+ number: plain,
68
+ cubicBezier,
69
+ // a dash array has no border-style keyword
70
+ strokeStyle: plain,
71
+ shadow: (value) => {
72
+ const layers = (Array.isArray(value) ? value : [value]).map(shadowLayer);
73
+ return parts(...layers)?.join(', ');
74
+ },
75
+ border: (value) => {
76
+ const object = record(value);
77
+ return (object && parts(dimension(object.width), plain(object.style), color(object.color))?.join(' '));
78
+ },
79
+ transition: (value) => {
80
+ const object = record(value);
81
+ return (object &&
82
+ parts(dimension(object.duration), cubicBezier(object.timingFunction), dimension(object.delay))?.join(' '));
83
+ },
30
84
  };
85
+ export const cssValueOf = (type, value) => SERIALIZERS[type]?.(value);
31
86
  const indexCache = new WeakMap();
32
87
  /** Every token of the base sets of design-tokens and styles, with its light value. */
33
88
  export const tokensOf = (context) => {
@@ -70,15 +125,23 @@ export const tokensOf = (context) => {
70
125
  };
71
126
  walk(base, []);
72
127
  walk(globals, []);
73
- // the light value of each token: follow its aliases to the end
128
+ // the light value of each token: follow its aliases to the end, also inside a composite
74
129
  const resolve = (value, depth = 0) => {
75
- if (depth > 12 || typeof value !== 'string' || !/^\{.+\}$/.test(value))
76
- return value;
77
- return resolve(byPath.get(value.slice(1, -1))?.$value, depth + 1);
130
+ if (depth > 12)
131
+ return undefined;
132
+ if (typeof value === 'string' && /^\{.+\}$/.test(value))
133
+ return resolve(byPath.get(value.slice(1, -1))?.$value, depth + 1);
134
+ if (Array.isArray(value))
135
+ return value.map((one) => resolve(one, depth));
136
+ const object = record(value);
137
+ return object
138
+ ? Object.fromEntries(Object.entries(object).map(([key, one]) => [key, resolve(one, depth)]))
139
+ : value;
78
140
  };
79
141
  for (const entry of entries) {
80
- const value = resolve(byPath.get(entry.path).$value);
81
- const text = cssValue(value);
142
+ const token = byPath.get(entry.path);
143
+ const value = resolve(token.$value);
144
+ const text = token.$extensions?.[NAMESPACE]?.cssValue ?? cssValueOf(entry.type, value);
82
145
  if (text)
83
146
  entry.value = text;
84
147
  const components = value?.components;
@@ -89,17 +152,64 @@ export const tokensOf = (context) => {
89
152
  return entries;
90
153
  };
91
154
  const consumptionOf = (context) => readData('consumption', context.settings);
155
+ const USES = ['text', 'border', 'background', 'shadow'];
156
+ /** What a colour role paints, from its name. */
92
157
  const useOfRole = (css) => /-(text|fg|on)(-|$)|on-emphasis|-on-/.test(css)
93
158
  ? 'text'
94
159
  : /border|outline/.test(css)
95
160
  ? 'border'
96
- : 'background';
97
- /** What a colour utility paints, from its root. */
98
- const useOfUtility = (root) => /^(text|decoration|placeholder|caret|fill|stroke)$/.test(root)
99
- ? 'text'
100
- : /^(border|outline|ring|divide)/.test(root)
101
- ? 'border'
102
- : 'background';
161
+ : /^--magma-shadow-/.test(css)
162
+ ? 'shadow'
163
+ : 'background';
164
+ /**
165
+ * What each colour utility paints, from the CSS property Tailwind writes for it: every root of
166
+ * the `--color` namespace of the consumption map is here (a test holds the table to it), so a
167
+ * root Tailwind adds is a failing test, not a background by default. The mask utilities read
168
+ * only the alpha of a colour: no role fits them.
169
+ */
170
+ export const USE_OF_UTILITY = {
171
+ text: 'text', // color
172
+ decoration: 'text', // text-decoration-color
173
+ placeholder: 'text', // the color of ::placeholder
174
+ caret: 'text', // caret-color
175
+ fill: 'text', // fill: an icon follows the text
176
+ stroke: 'text', // stroke
177
+ border: 'border', // border-color, and each side below
178
+ 'border-x': 'border',
179
+ 'border-y': 'border',
180
+ 'border-s': 'border',
181
+ 'border-e': 'border',
182
+ 'border-bs': 'border',
183
+ 'border-be': 'border',
184
+ 'border-t': 'border',
185
+ 'border-r': 'border',
186
+ 'border-b': 'border',
187
+ 'border-l': 'border',
188
+ divide: 'border', // border-color of the children
189
+ outline: 'border', // outline-color
190
+ ring: 'border', // the colour of a box-shadow drawn as a line
191
+ 'inset-ring': 'border',
192
+ bg: 'background', // background-color
193
+ accent: 'background', // accent-color, the fill of a checked control
194
+ 'ring-offset': 'background', // the gap between the ring and the box: the surface behind it
195
+ from: 'background', // the stops of a gradient
196
+ via: 'background',
197
+ to: 'background',
198
+ 'scrollbar-thumb': 'background', // scrollbar-color
199
+ 'scrollbar-track': 'background',
200
+ shadow: 'shadow', // the colour of box-shadow
201
+ 'inset-shadow': 'shadow',
202
+ 'drop-shadow': 'shadow', // filter: drop-shadow()
203
+ 'text-shadow': 'shadow',
204
+ };
205
+ const useOfUtility = (root) => USE_OF_UTILITY[root] ?? (root.startsWith('mask-') ? 'none' : undefined);
206
+ /** The utility a role is written with when the input names none. */
207
+ const ROOT_OF_USE = {
208
+ text: 'text',
209
+ border: 'border',
210
+ background: 'bg',
211
+ shadow: 'shadow',
212
+ };
103
213
  /** A few classes that read a token, for the agent to write. */
104
214
  const classesOf = (context, entry) => {
105
215
  const consumption = consumptionOf(context);
@@ -107,10 +217,8 @@ const classesOf = (context, entry) => {
107
217
  if (!published?.namespace || !published.key)
108
218
  return [];
109
219
  const namespace = consumption.namespaces[published.namespace];
110
- if (published.namespace === '--color') {
111
- const root = { text: 'text', border: 'border', background: 'bg' }[useOfRole(entry.css)];
112
- return [`${root}-${published.key}`];
113
- }
220
+ if (published.namespace === '--color')
221
+ return [`${ROOT_OF_USE[useOfRole(entry.css)]}-${published.key}`];
114
222
  const PREFERRED = [
115
223
  'rounded',
116
224
  'shadow',
@@ -167,6 +275,7 @@ export const listTokens = (context) => ({
167
275
  },
168
276
  },
169
277
  total: { type: 'number' },
278
+ gap: GAP_SCHEMA,
170
279
  },
171
280
  required: ['tokens', 'total'],
172
281
  },
@@ -192,6 +301,7 @@ export const listTokens = (context) => ({
192
301
  const max = typeof limit === 'number' && limit > 0 ? limit : 30;
193
302
  return {
194
303
  total: found.length,
304
+ ...(found.length ? {} : { gap: GAP }),
195
305
  tokens: found.slice(0, max).map(({ entry }) => ({
196
306
  ...(entry.css ? { css: entry.css } : {}),
197
307
  path: entry.path,
@@ -217,14 +327,14 @@ const tailwindColor = (context, key) => {
217
327
  export const suggestRole = (context) => ({
218
328
  name: 'suggest_role',
219
329
  title: 'Find the Magma role for a colour',
220
- description: 'The semantic role to use instead of a raw colour: a literal (#f5f5f5, rgb(...), oklch(...)), a Tailwind class (bg-gray-100, text-tone-neutral-03) or a palette step (--tone-neutral-09). Returns the nearest roles by their light value, for the use the class or the hint says (text, border, background).',
330
+ description: 'The semantic role to use instead of a raw colour: a literal (#f5f5f5, rgb(...), oklch(...)), a Tailwind class (bg-gray-100, text-tone-neutral-03, shadow-gray-900/20) or a palette step (--tone-neutral-09). Returns the nearest roles by their light value, for the use the class or the hint says (text, border, background, shadow; background when neither says), each with the class to write: the utility and the opacity of the class given, else the utility of the use.',
221
331
  inputSchema: {
222
332
  type: 'object',
223
333
  properties: {
224
334
  color: { type: 'string', description: 'The colour, class or custom property to replace.' },
225
335
  use: {
226
336
  type: 'string',
227
- enum: ['text', 'border', 'background'],
337
+ enum: USES,
228
338
  description: 'What it paints; read from the class when there is one.',
229
339
  },
230
340
  },
@@ -261,9 +371,10 @@ export const suggestRole = (context) => ({
261
371
  const byCss = new Map(tokens.filter((entry) => entry.css).map((entry) => [entry.css, entry]));
262
372
  const consumption = consumptionOf(context);
263
373
  let rgb;
264
- let kind = ['text', 'border', 'background'].includes(String(use))
265
- ? use
266
- : undefined;
374
+ let kind = USES.includes(use) ? use : undefined;
375
+ // the class to write keeps the utility and the opacity of a class given
376
+ let root;
377
+ let opacity = '';
267
378
  const variable = /--[a-z0-9-]+/.exec(input)?.[0];
268
379
  if (variable)
269
380
  rgb = byCss.get(variable)?.rgb;
@@ -273,9 +384,15 @@ export const suggestRole = (context) => ({
273
384
  // a class: its root says the use, its key the colour
274
385
  const utility = utilityOf(input);
275
386
  const { colorUtilities } = loadPalette(context.settings);
276
- const root = colorUtilities.find((one) => utility.startsWith(`${one}-`));
387
+ root = colorUtilities.find((one) => utility.startsWith(`${one}-`));
277
388
  if (root) {
278
- kind ??= useOfUtility(root);
389
+ const paints = useOfUtility(root);
390
+ if (paints === 'none')
391
+ throw new ToolError(`${root}-* reads only the alpha of a colour, so no colour role fits it: write black or transparent, or a percentage.`);
392
+ if (!paints && !kind)
393
+ throw new ToolError(`suggest_role does not know what ${root}-* paints: pass use (${USES.join(', ')}). ${GAP}`);
394
+ kind ??= paints;
395
+ opacity = /\/[\w.[\]()%-]+$/.exec(input.replace(/!$/, ''))?.[0] ?? '';
279
396
  const key = utility.slice(root.length + 1);
280
397
  const css = Object.entries(consumption.tokens).find(([, token]) => token.namespace === '--color' && token.key === key)?.[0];
281
398
  rgb = (css && byCss.get(css)?.rgb) || tailwindColor(context, key);
@@ -284,23 +401,28 @@ export const suggestRole = (context) => ({
284
401
  if (!rgb)
285
402
  throw new ToolError(`Cannot read a colour from "${input}": give a literal (#f5f5f5), a colour class (bg-gray-100) or a custom property (--tone-neutral-09).`);
286
403
  const target = kind ?? 'background';
404
+ // a shadow takes the shadow ink or, for a glow, a fill
405
+ const family = target === 'shadow' ? ['shadow', 'background'] : [target];
287
406
  const roles = tokens
288
407
  .filter((entry) => entry.tier === 'semantic' &&
289
408
  entry.type === 'color' &&
290
409
  entry.rgb &&
291
410
  entry.css &&
292
411
  !entry.deprecated)
293
- .filter((entry) => !/shadow-ink|outline|focus/.test(entry.css) && useOfRole(entry.css) === target)
412
+ .filter((entry) => !/outline|focus/.test(entry.css) && family.includes(useOfRole(entry.css)))
294
413
  .map((entry) => ({ entry, gap: distance(rgb, entry.rgb) }))
295
414
  .sort((a, b) => a.gap - b.gap)
296
415
  .slice(0, 3)
297
- .map(({ entry, gap }) => ({
298
- css: entry.css,
299
- class: classesOf(context, entry)[0] ?? '',
300
- ...(entry.description ? { description: entry.description } : {}),
301
- value: entry.value ?? toHex(entry.rgb),
302
- distance: Math.round(gap * 1000) / 1000,
303
- }));
416
+ .map(({ entry, gap }) => {
417
+ const key = consumption.tokens[entry.css]?.key;
418
+ return {
419
+ css: entry.css,
420
+ class: key ? `${root ?? ROOT_OF_USE[target]}-${key}${opacity}` : '',
421
+ ...(entry.description ? { description: entry.description } : {}),
422
+ value: entry.value ?? toHex(entry.rgb),
423
+ distance: Math.round(gap * 1000) / 1000,
424
+ };
425
+ });
304
426
  return { input, use: target, value: toHex(rgb), roles };
305
427
  },
306
428
  });