@ids-group-ltd/ids-design-system 1.1.2 → 1.2.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 (221) hide show
  1. package/CHANGELOG.md +755 -0
  2. package/agent/INDEX.md +8 -7
  3. package/agent/charts/ds-scatter-chart.md +1 -1
  4. package/agent/feedback/ds-badge.md +2 -2
  5. package/agent/feedback/ds-chat-message.md +1 -1
  6. package/agent/feedback/ds-chat-step.md +2 -2
  7. package/agent/feedback/ds-chat-thread.md +1 -1
  8. package/agent/feedback/ds-stat.md +1 -1
  9. package/agent/feedback/ds-toast.md +2 -2
  10. package/agent/feedback/ds-tree.md +1 -1
  11. package/agent/forms/ds-button.md +3 -3
  12. package/agent/forms/ds-dropzone.md +1 -1
  13. package/agent/forms/ds-icon-button.md +3 -3
  14. package/agent/forms/ds-number-stepper.md +3 -3
  15. package/agent/forms/ds-search.md +1 -1
  16. package/agent/forms/ds-split-button.md +1 -1
  17. package/agent/foundations/tokens.md +4 -3
  18. package/agent/navigation/ds-app-layout.md +1 -1
  19. package/agent/navigation/ds-nav-divider.md +6 -0
  20. package/agent/navigation/{ds-sidenav-footer.md → ds-nav-footer.md} +3 -3
  21. package/agent/navigation/{ds-sidenav-group.md → ds-nav-group.md} +2 -2
  22. package/agent/navigation/{ds-sidenav-item.md → ds-nav-item.md} +6 -6
  23. package/agent/navigation/ds-nav.md +15 -0
  24. package/agent/overlays/ds-drawer.md +1 -1
  25. package/agent/platform/toast-service.md +1 -1
  26. package/components/README.md +24 -24
  27. package/components.md +51 -45
  28. package/design-system.md +8 -7
  29. package/eslint/deprecated-api.json +108 -7
  30. package/fesm2022/ids-group-ltd-ids-design-system-components-accordion.mjs +2 -2
  31. package/fesm2022/ids-group-ltd-ids-design-system-components-accordion.mjs.map +1 -1
  32. package/fesm2022/ids-group-ltd-ids-design-system-components-alert.mjs +2 -2
  33. package/fesm2022/ids-group-ltd-ids-design-system-components-alert.mjs.map +1 -1
  34. package/fesm2022/ids-group-ltd-ids-design-system-components-app-layout.mjs +4 -4
  35. package/fesm2022/ids-group-ltd-ids-design-system-components-app-layout.mjs.map +1 -1
  36. package/fesm2022/ids-group-ltd-ids-design-system-components-auth-layout.mjs +4 -4
  37. package/fesm2022/ids-group-ltd-ids-design-system-components-auth-layout.mjs.map +1 -1
  38. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs +2 -2
  39. package/fesm2022/ids-group-ltd-ids-design-system-components-autocomplete.mjs.map +1 -1
  40. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar.mjs +2 -2
  41. package/fesm2022/ids-group-ltd-ids-design-system-components-avatar.mjs.map +1 -1
  42. package/fesm2022/ids-group-ltd-ids-design-system-components-badge-badge-count-roll.component-BDNXADJZ.mjs +182 -0
  43. package/fesm2022/ids-group-ltd-ids-design-system-components-badge-badge-count-roll.component-BDNXADJZ.mjs.map +1 -0
  44. package/fesm2022/ids-group-ltd-ids-design-system-components-badge.mjs +37 -8
  45. package/fesm2022/ids-group-ltd-ids-design-system-components-badge.mjs.map +1 -1
  46. package/fesm2022/ids-group-ltd-ids-design-system-components-banner.mjs +2 -2
  47. package/fesm2022/ids-group-ltd-ids-design-system-components-banner.mjs.map +1 -1
  48. package/fesm2022/ids-group-ltd-ids-design-system-components-breadcrumbs.mjs +5 -2
  49. package/fesm2022/ids-group-ltd-ids-design-system-components-breadcrumbs.mjs.map +1 -1
  50. package/fesm2022/ids-group-ltd-ids-design-system-components-button-group.mjs +2 -2
  51. package/fesm2022/ids-group-ltd-ids-design-system-components-button-group.mjs.map +1 -1
  52. package/fesm2022/ids-group-ltd-ids-design-system-components-button.mjs +76 -5
  53. package/fesm2022/ids-group-ltd-ids-design-system-components-button.mjs.map +1 -1
  54. package/fesm2022/ids-group-ltd-ids-design-system-components-calendar-day.mjs +2 -2
  55. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs +2 -2
  56. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-legend.mjs.map +1 -1
  57. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs +2 -2
  58. package/fesm2022/ids-group-ltd-ids-design-system-components-chart-tooltip.mjs.map +1 -1
  59. package/fesm2022/ids-group-ltd-ids-design-system-components-chat.mjs +77 -18
  60. package/fesm2022/ids-group-ltd-ids-design-system-components-chat.mjs.map +1 -1
  61. package/fesm2022/ids-group-ltd-ids-design-system-components-checkbox.mjs +2 -2
  62. package/fesm2022/ids-group-ltd-ids-design-system-components-checkbox.mjs.map +1 -1
  63. package/fesm2022/ids-group-ltd-ids-design-system-components-color-picker.mjs +2 -2
  64. package/fesm2022/ids-group-ltd-ids-design-system-components-color-picker.mjs.map +1 -1
  65. package/fesm2022/ids-group-ltd-ids-design-system-components-date-picker.mjs +2 -2
  66. package/fesm2022/ids-group-ltd-ids-design-system-components-date-picker.mjs.map +1 -1
  67. package/fesm2022/ids-group-ltd-ids-design-system-components-definition-term.mjs +2 -2
  68. package/fesm2022/ids-group-ltd-ids-design-system-components-definition-term.mjs.map +1 -1
  69. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs +2 -2
  70. package/fesm2022/ids-group-ltd-ids-design-system-components-description-list.mjs.map +1 -1
  71. package/fesm2022/ids-group-ltd-ids-design-system-components-drawer.mjs +65 -4
  72. package/fesm2022/ids-group-ltd-ids-design-system-components-drawer.mjs.map +1 -1
  73. package/fesm2022/ids-group-ltd-ids-design-system-components-dropzone.mjs +76 -9
  74. package/fesm2022/ids-group-ltd-ids-design-system-components-dropzone.mjs.map +1 -1
  75. package/fesm2022/ids-group-ltd-ids-design-system-components-field-group.mjs +2 -2
  76. package/fesm2022/ids-group-ltd-ids-design-system-components-field-group.mjs.map +1 -1
  77. package/fesm2022/ids-group-ltd-ids-design-system-components-funnel-chart.mjs +2 -2
  78. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs +2 -2
  79. package/fesm2022/ids-group-ltd-ids-design-system-components-heatmap-chart.mjs.map +1 -1
  80. package/fesm2022/ids-group-ltd-ids-design-system-components-icon-button.mjs +6 -4
  81. package/fesm2022/ids-group-ltd-ids-design-system-components-icon-button.mjs.map +1 -1
  82. package/fesm2022/ids-group-ltd-ids-design-system-components-info-hint.mjs +2 -2
  83. package/fesm2022/ids-group-ltd-ids-design-system-components-info-hint.mjs.map +1 -1
  84. package/fesm2022/ids-group-ltd-ids-design-system-components-inline-edit.mjs +2 -2
  85. package/fesm2022/ids-group-ltd-ids-design-system-components-inline-edit.mjs.map +1 -1
  86. package/fesm2022/ids-group-ltd-ids-design-system-components-input.mjs +2 -2
  87. package/fesm2022/ids-group-ltd-ids-design-system-components-input.mjs.map +1 -1
  88. package/fesm2022/ids-group-ltd-ids-design-system-components-list.mjs +2 -2
  89. package/fesm2022/ids-group-ltd-ids-design-system-components-menu.mjs +4 -4
  90. package/fesm2022/ids-group-ltd-ids-design-system-components-menu.mjs.map +1 -1
  91. package/fesm2022/ids-group-ltd-ids-design-system-components-modal.mjs +2 -2
  92. package/fesm2022/ids-group-ltd-ids-design-system-components-modal.mjs.map +1 -1
  93. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs +2 -2
  94. package/fesm2022/ids-group-ltd-ids-design-system-components-multi-select.mjs.map +1 -1
  95. package/fesm2022/ids-group-ltd-ids-design-system-components-nav-footer.mjs +113 -0
  96. package/fesm2022/ids-group-ltd-ids-design-system-components-nav-footer.mjs.map +1 -0
  97. package/fesm2022/ids-group-ltd-ids-design-system-components-nav.mjs +228 -0
  98. package/fesm2022/ids-group-ltd-ids-design-system-components-nav.mjs.map +1 -0
  99. package/fesm2022/ids-group-ltd-ids-design-system-components-number-stepper.mjs +61 -10
  100. package/fesm2022/ids-group-ltd-ids-design-system-components-number-stepper.mjs.map +1 -1
  101. package/fesm2022/ids-group-ltd-ids-design-system-components-otp-input.mjs +2 -2
  102. package/fesm2022/ids-group-ltd-ids-design-system-components-otp-input.mjs.map +1 -1
  103. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs +36 -4
  104. package/fesm2022/ids-group-ltd-ids-design-system-components-pagination.mjs.map +1 -1
  105. package/fesm2022/ids-group-ltd-ids-design-system-components-pie-chart.mjs +2 -2
  106. package/fesm2022/ids-group-ltd-ids-design-system-components-radio-group.mjs +2 -2
  107. package/fesm2022/ids-group-ltd-ids-design-system-components-radio-group.mjs.map +1 -1
  108. package/fesm2022/ids-group-ltd-ids-design-system-components-reveal.mjs +56 -0
  109. package/fesm2022/ids-group-ltd-ids-design-system-components-reveal.mjs.map +1 -0
  110. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs +10 -39
  111. package/fesm2022/ids-group-ltd-ids-design-system-components-scatter-chart.mjs.map +1 -1
  112. package/fesm2022/ids-group-ltd-ids-design-system-components-search.mjs +7 -4
  113. package/fesm2022/ids-group-ltd-ids-design-system-components-search.mjs.map +1 -1
  114. package/fesm2022/ids-group-ltd-ids-design-system-components-segmented.mjs +33 -6
  115. package/fesm2022/ids-group-ltd-ids-design-system-components-segmented.mjs.map +1 -1
  116. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs +2 -2
  117. package/fesm2022/ids-group-ltd-ids-design-system-components-select.mjs.map +1 -1
  118. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav-footer.mjs +4 -98
  119. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav-footer.mjs.map +1 -1
  120. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav.mjs +11 -179
  121. package/fesm2022/ids-group-ltd-ids-design-system-components-sidenav.mjs.map +1 -1
  122. package/fesm2022/ids-group-ltd-ids-design-system-components-skeleton.mjs +2 -2
  123. package/fesm2022/ids-group-ltd-ids-design-system-components-skeleton.mjs.map +1 -1
  124. package/fesm2022/ids-group-ltd-ids-design-system-components-slider.mjs +2 -2
  125. package/fesm2022/ids-group-ltd-ids-design-system-components-slider.mjs.map +1 -1
  126. package/fesm2022/ids-group-ltd-ids-design-system-components-split-button.mjs +3 -2
  127. package/fesm2022/ids-group-ltd-ids-design-system-components-split-button.mjs.map +1 -1
  128. package/fesm2022/ids-group-ltd-ids-design-system-components-stat.mjs +68 -5
  129. package/fesm2022/ids-group-ltd-ids-design-system-components-stat.mjs.map +1 -1
  130. package/fesm2022/ids-group-ltd-ids-design-system-components-stepper.mjs +2 -2
  131. package/fesm2022/ids-group-ltd-ids-design-system-components-stepper.mjs.map +1 -1
  132. package/fesm2022/ids-group-ltd-ids-design-system-components-switch.mjs +2 -2
  133. package/fesm2022/ids-group-ltd-ids-design-system-components-switch.mjs.map +1 -1
  134. package/fesm2022/ids-group-ltd-ids-design-system-components-table-columns.mjs +2 -2
  135. package/fesm2022/ids-group-ltd-ids-design-system-components-table-columns.mjs.map +1 -1
  136. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs +2 -2
  137. package/fesm2022/ids-group-ltd-ids-design-system-components-table.mjs.map +1 -1
  138. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs +41 -3
  139. package/fesm2022/ids-group-ltd-ids-design-system-components-tabs.mjs.map +1 -1
  140. package/fesm2022/ids-group-ltd-ids-design-system-components-tag.mjs +2 -2
  141. package/fesm2022/ids-group-ltd-ids-design-system-components-tag.mjs.map +1 -1
  142. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs +6 -4
  143. package/fesm2022/ids-group-ltd-ids-design-system-components-textarea.mjs.map +1 -1
  144. package/fesm2022/ids-group-ltd-ids-design-system-components-time-picker.mjs +4 -4
  145. package/fesm2022/ids-group-ltd-ids-design-system-components-time-picker.mjs.map +1 -1
  146. package/fesm2022/ids-group-ltd-ids-design-system-components-timeline.mjs +27 -7
  147. package/fesm2022/ids-group-ltd-ids-design-system-components-timeline.mjs.map +1 -1
  148. package/fesm2022/ids-group-ltd-ids-design-system-components-toast.mjs +54 -19
  149. package/fesm2022/ids-group-ltd-ids-design-system-components-toast.mjs.map +1 -1
  150. package/fesm2022/ids-group-ltd-ids-design-system-components-toggle-button.mjs +2 -2
  151. package/fesm2022/ids-group-ltd-ids-design-system-components-toggle-button.mjs.map +1 -1
  152. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs +8 -7
  153. package/fesm2022/ids-group-ltd-ids-design-system-components-tooltip.mjs.map +1 -1
  154. package/fesm2022/ids-group-ltd-ids-design-system-components-tree.mjs +21 -11
  155. package/fesm2022/ids-group-ltd-ids-design-system-components-tree.mjs.map +1 -1
  156. package/fesm2022/ids-group-ltd-ids-design-system-components-w3w.mjs +2 -2
  157. package/fesm2022/ids-group-ltd-ids-design-system-components-w3w.mjs.map +1 -1
  158. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs +153 -1
  159. package/fesm2022/ids-group-ltd-ids-design-system-components.mjs.map +1 -1
  160. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs +11 -0
  161. package/fesm2022/ids-group-ltd-ids-design-system-core.mjs.map +1 -1
  162. package/fesm2022/ids-group-ltd-ids-design-system.mjs +4 -1
  163. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  164. package/migrations/1.1.1.json +14 -4
  165. package/migrations/1.1.2.json +11 -3
  166. package/migrations/1.2.0.json +1433 -0
  167. package/migrations/README.md +8 -1
  168. package/package.json +25 -1
  169. package/schematics/check-overrides/index.cjs +28 -3
  170. package/schematics/check-overrides/scan.cjs +151 -2
  171. package/schematics/check-overrides/schema.json +4 -0
  172. package/schematics/check-overrides/surface.json +389 -74
  173. package/schematics/collection.json +1 -1
  174. package/stylelint/deprecated-tokens.json +7 -0
  175. package/styles/_check-box.scss +4 -3
  176. package/styles/_dropdown-overlay.scss +6 -8
  177. package/styles/_ds-color.scss +7 -2
  178. package/styles/_field-state.scss +4 -2
  179. package/styles/_focus.scss +12 -5
  180. package/styles/_link.scss +4 -4
  181. package/styles/_optical-center.scss +29 -0
  182. package/styles/_reveal.scss +8 -0
  183. package/styles/_status.scss +17 -7
  184. package/styles/_step-marker.scss +192 -6
  185. package/styles/_surface-level.scss +16 -0
  186. package/styles/_text-shimmer.scss +21 -0
  187. package/styles/_theme-activation.scss +17 -4
  188. package/styles/_tokens.scss +26 -7
  189. package/styles/ds.scss +1 -0
  190. package/themes/README.md +16 -21
  191. package/themes/_semantic.scss +129 -64
  192. package/themes/dark/_theme.scss +17 -25
  193. package/types/ids-group-ltd-ids-design-system-components-app-layout.d.ts +3 -3
  194. package/types/ids-group-ltd-ids-design-system-components-auth-layout.d.ts +2 -2
  195. package/types/ids-group-ltd-ids-design-system-components-badge.d.ts +20 -1
  196. package/types/ids-group-ltd-ids-design-system-components-button.d.ts +14 -3
  197. package/types/ids-group-ltd-ids-design-system-components-chat.d.ts +49 -4
  198. package/types/ids-group-ltd-ids-design-system-components-drawer.d.ts +9 -1
  199. package/types/ids-group-ltd-ids-design-system-components-dropzone.d.ts +28 -2
  200. package/types/ids-group-ltd-ids-design-system-components-icon-button.d.ts +8 -5
  201. package/types/ids-group-ltd-ids-design-system-components-nav-footer.d.ts +88 -0
  202. package/types/ids-group-ltd-ids-design-system-components-nav.d.ts +152 -0
  203. package/types/ids-group-ltd-ids-design-system-components-number-stepper.d.ts +21 -3
  204. package/types/ids-group-ltd-ids-design-system-components-pagination.d.ts +1 -0
  205. package/types/ids-group-ltd-ids-design-system-components-reveal.d.ts +31 -0
  206. package/types/ids-group-ltd-ids-design-system-components-scatter-chart.d.ts +2 -8
  207. package/types/ids-group-ltd-ids-design-system-components-search.d.ts +4 -1
  208. package/types/ids-group-ltd-ids-design-system-components-segmented.d.ts +3 -0
  209. package/types/ids-group-ltd-ids-design-system-components-sidenav-footer.d.ts +12 -83
  210. package/types/ids-group-ltd-ids-design-system-components-sidenav.d.ts +21 -131
  211. package/types/ids-group-ltd-ids-design-system-components-split-button.d.ts +1 -1
  212. package/types/ids-group-ltd-ids-design-system-components-stat.d.ts +10 -1
  213. package/types/ids-group-ltd-ids-design-system-components-tabs.d.ts +1 -0
  214. package/types/ids-group-ltd-ids-design-system-components-textarea.d.ts +1 -1
  215. package/types/ids-group-ltd-ids-design-system-components-timeline.d.ts +3 -1
  216. package/types/ids-group-ltd-ids-design-system-components-toast.d.ts +27 -6
  217. package/types/ids-group-ltd-ids-design-system-components-tree.d.ts +9 -5
  218. package/types/ids-group-ltd-ids-design-system-components.d.ts +26 -1
  219. package/types/ids-group-ltd-ids-design-system-core.d.ts +19 -1
  220. package/types/ids-group-ltd-ids-design-system.d.ts +7 -4
  221. package/agent/navigation/ds-sidenav.md +0 -13
package/components.md CHANGED
@@ -32,12 +32,13 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
32
32
 
33
33
  **Colour roles:**
34
34
  - Surfaces: `--surface-canvas`, `--surface-default`, `--surface-secondary`, `--surface-overlay`, `--surface-overlay-secondary`, `--surface-overlay-muted`, `--surface-overlay-raised`, `--surface-overlay-raised-secondary`, `--surface-overlay-raised-muted`, `--surface-overlay-tint`, `--surface-overlay-raised-tint`, `--surface-tint`, `--surface-disabled`, `--surface-muted`, `--surface-inverted`, `--surface-inverted-hover`, `--surface-scrim`
35
- - Borders: `--border-default`, `--border-strong`, `--border-field`, `--border-field-hover`, `--border-overlay`, `--border-subtle`, `--border-divider`, `--border-disabled`, `--border-inverted`
35
+ - Borders: `--border-default`, `--border-strong`, `--border-field`, `--border-field-hover`, `--border-readonly`, `--border-overlay`, `--border-subtle`, `--border-divider`, `--border-disabled`, `--border-inverted`
36
36
  - Text: `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-tertiary-overlay`, `--text-muted`, `--text-disabled`, `--text-inverted`, `--text-link`, `--text-link-visited`, `--text-on-primary`, `--text-on-success`, `--text-on-error`
37
37
  - Icons: `--icon-default`, `--icon-strong`, `--icon-muted`, `--icon-on-primary`
38
- - Primary (main brand fill): `--primary`, `--primary-hover`, `--primary-pressed`, `--primary-selected-hover`, `--primary-strong`, `--primary-subtle`, `--primary-muted`, `--primary-muted-strong`, `--primary-on` + HSL channels `--primary-h/s/l`
38
+ - Primary (main brand fill): `--primary`, `--primary-hover`, `--primary-pressed`, `--primary-selected-hover`, `--primary-strong`, `--primary-subtle`, `--primary-muted`, `--primary-muted-strong`, `--primary-muted-pressed`, `--primary-on` + HSL channels `--primary-h/s/l`
39
39
  - Secondary (paired CTAs, accent rails, opt-in variants): `--secondary`, `--secondary-hover`, `--secondary-pressed`, `--secondary-strong`, `--secondary-subtle`, `--secondary-muted`, `--secondary-on` + HSL channels `--secondary-h/s/l`
40
40
  - Tertiary (third brand hue — tertiary button, tonal chips, indicators): `--tertiary`, `--tertiary-hover`, `--tertiary-pressed`, `--tertiary-strong`, `--tertiary-subtle`, `--tertiary-muted`, `--tertiary-on` + HSL channels `--tertiary-h/s/l`
41
+ - Neutral fill (`ds-button` `color="neutral"`): `--neutral-fill`, `--neutral-fill-on`, `--neutral-fill-hover`, `--neutral-fill-pressed`, `--neutral-fill-muted`, `--neutral-fill-muted-strong`, `--neutral-fill-muted-pressed`
41
42
  - Error (destructive, was --danger): `--error`, `--error-hover`, `--error-pressed`, `--error-subtle`, `--error-muted`, `--error-highlight`, `--error-border`, `--error-text` + HSL channels `--error-h/s/l`
42
43
  - Status: `--success`, `--success-hover`, `--success-subtle`, `--success-muted`, `--success-border`, `--success-text`
43
44
  - Status (warning/info): same shape with prefix swapped
@@ -45,7 +46,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
45
46
 
46
47
  **Geometry:**
47
48
  - Spacing: `--space-0`, `--space-px`, `--space-0-5` (2px), `--space-1` (4px), `--space-1-5` (6px), `--space-2` (8px), `--space-2-5` (10px), `--space-3` (12px), `--space-4` (16px), `--space-5` (20px), `--space-6` (24px), `--space-8` (32px), `--space-10` (40px), `--space-12` (48px), `--space-14` (56px), `--space-16` (64px), `--space-20` (80px), `--space-24` (96px), `--space-32` (128px)
48
- - Radius: `--radius-0`, `--radius-sm` (4px), `--radius-md` (8px), `--radius-lg` (12px), `--radius-2xl` (24px), `--radius-pill` (999px), `--radius-pill-value`, `--radius-flat`
49
+ - Radius: `--radius-0`, `--radius-sm` (4px), `--radius-sm-md` (6px), `--radius-md` (8px), `--radius-lg` (12px), `--radius-2xl` (24px), `--radius-pill` (999px), `--radius-pill-value`, `--radius-flat`
49
50
  - Border widths: `--border-width-default` (1px), `--border-width-strong` (2px)
50
51
  - Hit targets: `--hit-xs` (24), `--hit-sm` (28), `--hit-md` (36), `--hit-min` (32), `--hit-cozy` (40), `--hit-comfy` (44), `--hit-touch` (48)
51
52
  - Icon sizes: `--icon-2xs` (10), `--icon-xs` (12), `--icon-sm` (14), `--icon-md` (16), `--icon-lg` (20)
@@ -158,8 +159,8 @@ is not a validated field; where a search needs a label or an error line, use `ds
158
159
  **Shared box tokens.** `--ds-field-border-color`, `--ds-field-border-color-hover`, `--ds-field-border-color-focus`, `--ds-field-text-color`, `--ds-field-placeholder-color` and `--ds-field-font-size` sit UNDER each field's own token the way `--ds-field-height` and `--ds-field-label-*` do: `--ds-input-border`, `--ds-select-border-color-focus` or `--ds-autocomplete-text-color` still wins where set, and the family value fills in everywhere it is not. They reach input, textarea, select, multi-select, autocomplete and search. The date, time and colour pickers, the number stepper and the OTP cells keep their own `--ds-<component>-*` tokens and do not read the family.
159
160
 
160
161
  #### `<ds-button>` — `ButtonComponent`
161
- Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `align: ButtonAlign = 'center'` (`'center' | 'between'`; `'between'` pushes the label and a trailing icon to opposite edges, and only shows once something widens the button past its contents), `disabled`, `loading`, `loadingMode: ButtonLoadingMode = 'auto'` (`'auto' | 'icon' | 'replace'`; `'icon'` draws the spinner in the leading icon's box, or the trailing one's when there is no leading icon, and keeps the label; `'replace'` hides the contents behind one centred spinner; `'auto'` is `'icon'` when `icon` is set; neither moves the label or resizes the button), `fullWidth`, `icon: IconName | null`, and the destination pair `routerLink: DsRouterLink = null` (a path, a command array or a `UrlTree`) / `href: string = ''`, with the modifiers `fragment` / `queryParams` / `queryParamsHandling` (routerLink-only) and `target` / `rel` (either link), plus `routerLinkActiveOptions` and `ariaCurrent`. Plus the refusal pair below: `disabledReason`, and the field message inputs `hint` / `warning` / `error` / `messageIcon` / `reserveMessage` / `ariaDescribedBy`.
162
- Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn with the reason. Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled splits by whether the fill can carry the state: `solid` and `tonal` keep `oklch(from accent 70% 0.035 h)`, while `outline`, `ghost` and `text` — the three with no fill of their own — mix the label toward the surface, `color-mix(in srgb, <label> 40%, var(--surface-default))`, because a fixed lightness cannot serve both themes. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
162
+ Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'surface' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `align: ButtonAlign = 'center'` (`'center' | 'between'`; `'between'` pushes the label and a trailing icon to opposite edges, and only shows once something widens the button past its contents), `disabled`, `loading`, `loadingMode: ButtonLoadingMode = 'auto'` (`'auto' | 'icon' | 'replace'`; `'icon'` draws the spinner in the leading icon's box, or the trailing one's when there is no leading icon, and keeps the label; `'replace'` hides the contents behind one centred spinner; `'auto'` is `'icon'` when `icon` is set; neither moves the label or resizes the button), `fullWidth`, `icon: IconName | null`, and the destination pair `routerLink: DsRouterLink = null` (a path, a command array or a `UrlTree`) / `href: string = ''`, with the modifiers `fragment` / `queryParams` / `queryParamsHandling` (routerLink-only) and `target` / `rel` (either link), plus `routerLinkActiveOptions` and `ariaCurrent`. Plus the refusal pair below: `disabledReason`, and the field message inputs `hint` / `warning` / `error` / `messageIcon` / `reserveMessage` / `ariaDescribedBy`.
163
+ Axis meaning: **variant is loudness** (solid > tonal > outline/surface/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn with the reason. Solid and tonal paint the accent; `surface` is `outline` on the field fill, `--surface-default`, so it stays a plate on a grey surface; outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled splits by whether the fill can carry the state: `solid` and `tonal` keep `oklch(from accent 70% 0.035 h)`, while `outline`, `surface`, `ghost` and `text` — the four with no accent fill — mix the label toward the surface, `color-mix(in srgb, <label> 40%, var(--surface-default))`, because a fixed lightness cannot serve both themes. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
163
164
  Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
164
165
  **`loading` keeps the button in the focus order.** It sets `aria-busy` and `aria-disabled`, never the native `disabled`, so a button pressed from the keyboard keeps focus while the work runs; the click is swallowed in the handler, so `(pressed)` does not fire and a `type="submit"` does not submit. For an action in flight bind `loading`, not `disabled`: a natively disabled button under focus drops it to the page.
165
166
  **Three elements, decided by destination.** `routerLink` → an `<a [routerLink]>` with `routerLinkActive`; `href` → a plain `<a href>`; **neither → a `<button type="button">`** — the same rule `ds-sidenav-item` follows, and for the same reason: a control that navigates has to BE a link, or middle-click, open-in-new-tab, copy-link-address and the `link` role a screen reader announces are all gone. Styling is identical across all three (class-based on `.button`, and the anchor's UA underline is reset), so target the class, never the tag — measured at zero differences across eleven computed properties, focus ring included. `type` and `loading` are button-only and dev-warn if set on a link: an anchor has no form to submit, and a navigation cannot be in flight before it starts. A disabled link takes `aria-disabled` plus `tabindex="-1"` — an anchor has no native disabled state — and its click is swallowed, which is what stops an `href` from navigating anyway. **`controlRef`** (was `buttonRef` before 0.12.3) is typed `ElementRef<HTMLElement>` for that reason: it resolves whichever element rendered.
@@ -174,18 +175,18 @@ Layout: a message-bearing button becomes a column (host class `with-message`), a
174
175
  Tokens: `--ds-button-bg-color`, `--ds-button-bg-color-hover`, `--ds-button-bg-color-active`, `--ds-button-bg-color-disabled`, `--ds-button-label-color`, `--ds-button-label-color-disabled`, `--ds-button-border-color`, `--ds-button-border-color-hover`, `--ds-button-border-color-active`, `--ds-button-border-color-disabled`, `--ds-button-border-width`, `--ds-button-radius`, `--ds-button-pressed-shadow`, `--ds-button-shadow`, `--ds-button-shadow-hover`. The focus ring is not a button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on the button's own scope. The last two are the REST and hover shadow, both `none` by default — before them the only way to give a button a resting shadow was a deep selector into its inner `<button>`. `-shadow-hover` falls back to `-shadow`, so setting the resting one alone keeps the button steady under the pointer; focus and pressed keep their own hooks and still win while those states are on. `-border-color-hover` falls back to the rest border and `-border-color-active` to the hover one, so an outline button's edge stays put until one of them is set. For `variant="solid"`, `-bg-color-hover` / `-bg-color-active` / `-pressed-shadow` default to a `color-mix()` derivation of the resolved fill (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the fill alone retints the whole state set; tonal, outline, ghost and text keep explicit ramp defaults, so a full retint there means setting the state tokens too.
175
176
 
176
177
  <!-- inputs:ds-button -->
177
- All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `color: ButtonColor = 'primary'`, `variant: 'solid' | 'tonal' | 'ghost' | 'outline' | 'text' = 'solid'`, `align: 'center' | 'between' = 'center'`, `size: 'sm' | 'md' | 'lg' = null`, `routerLink: DsRouterLink = null`, `href: string = ''`, `fragment: string | undefined`, `queryParams: Params | null | undefined`, `queryParamsHandling: QueryParamsHandling | null | undefined`, `target: string | undefined`, `rel: string | undefined`, `routerLinkActiveOptions: { exact: boolean } | IsActiveMatchOptions`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `loading: boolean = false`, `loadingMode: 'auto' | 'icon' | 'replace' = 'auto'`, `fullWidth: boolean = false`, `ariaLabel: string | null = null`, `icon: IconName | null = null`, `trailingIcon: IconName | null = null`, `ariaHasPopup: 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' = null`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`, `disabledReason: string = ''`, `ariaDescribedBy: string | null = null`
178
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `color: ButtonColor = 'primary'`, `variant: 'solid' | 'tonal' | 'ghost' | 'outline' | 'surface' | 'text' = 'solid'`, `align: 'center' | 'between' = 'center'`, `size: 'sm' | 'md' | 'lg' = null`, `routerLink: DsRouterLink = null`, `href: string = ''`, `fragment: string | undefined`, `queryParams: Params | null | undefined`, `queryParamsHandling: QueryParamsHandling | null | undefined`, `target: string | undefined`, `rel: string | undefined`, `routerLinkActiveOptions: { exact: boolean } | IsActiveMatchOptions`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `loading: boolean = false`, `loadingMode: 'auto' | 'icon' | 'replace' = 'auto'`, `fullWidth: boolean = false`, `ariaLabel: string | null = null`, `icon: IconName | null = null`, `trailingIcon: IconName | null = null`, `ariaHasPopup: 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' = null`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`, `disabledReason: string = ''`, `ariaDescribedBy: string | null = null`
178
179
  <!-- /inputs -->
179
180
 
180
181
  #### `<ds-icon-button>` — `IconButtonComponent`
181
182
  Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` is required (icon-only must be labelled for a11y).
182
- Inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null` (point at text the page already shows — e.g. why the action is refused; icon-only leaves no room for a second line, which is why there is deliberately no `disabledReason` here), `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
183
+ Inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null` (point at text the page already shows — e.g. why the action is refused; icon-only leaves no room for a second line, which is why there is deliberately no `disabledReason` here), `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined' | 'surface'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
183
184
  Output: `(pressed): MouseEvent` — fires when not disabled
184
- Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered. `selected` renders the pressed/active fill.
185
+ Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered · `surface` bordered on the field fill, `--surface-default`. `selected` renders the pressed/active fill. `color="inherit"` draws a `standard` button in the surrounding text colour, hover, press and focus ring included, for a close or action button on a chip, banner or header filled with a colour.
185
186
  Tokens: `--ds-icon-button-bg-color`, `--ds-icon-button-icon-color`, `--ds-icon-button-border`, `--ds-icon-button-border-hover`, `--ds-icon-button-border-active`, `--ds-icon-button-bg-color-hover`, `--ds-icon-button-bg-color-active`, `--ds-icon-button-icon-color-hover`, `--ds-icon-button-radius`. The focus ring is not an icon-button token — set `--focus-ring-color`, `--focus-ring-width` or `--focus-ring-offset` on its own scope. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults. `-border-hover` falls back to `-border` and `-border-active` to `-border-hover`, so the border stays put until one of them is set.
186
187
 
187
188
  <!-- inputs:ds-icon-button -->
188
- All inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null`, `variant: 'standard' | 'filled' | 'tonal' | 'outlined' = 'standard'`, `color: ButtonColor = 'primary'`, `size: 'sm' | 'md' | 'lg' = null`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean | null = null`, `ariaHasPopup: 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' = null`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`
189
+ All inputs: `icon: required IconName`, `ariaLabel: required string`, `ariaDescribedBy: string | null = null`, `variant: 'standard' | 'filled' | 'tonal' | 'outlined' | 'surface' = 'standard'`, `color: IconButtonColor = 'primary'`, `size: 'sm' | 'md' | 'lg' = null`, `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean | null = null`, `ariaHasPopup: 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' = null`, `ariaExpanded: boolean | null = null`, `ariaControls: string | null = null`
189
190
  <!-- /inputs -->
190
191
 
191
192
  #### `<ds-inline-edit>` — `InlineEditComponent`
@@ -255,13 +256,13 @@ All inputs: `value: string = ''`, `placeholder: string = ''`, `ariaLabel: string
255
256
  <!-- /inputs -->
256
257
 
257
258
  #### `<ds-number-stepper>` — `NumberStepperComponent`
258
- Spinbox for bounded quantities — −/+ buttons around a numeric value.
259
+ Spinbox for bounded quantities — −/+ buttons on tinted pads inside the box, around a numeric value. While `pending` a spinner, and under `showDirty` the changed dot, sit in the top corner beside the + pad, over the box: the value never moves.
259
260
  Inputs: `value: model<number> = 0`, `min: number = 0`, `max: number | null = null`, `step: number = 1`, `size: 'sm' | 'md' | 'lg' = 'md'`, `disabled: boolean = false`
260
261
  Methods: `inc()`, `dec()` (clamp to min/max). Buttons disable at the bounds.
261
- Tokens: `--ds-number-stepper-field-width` sizes the number itself and is derived from the box height by default — a value with more digits than that width holds is clipped rather than wrapped, so widen it for large quantities. Also `--ds-number-stepper-bg-color`, `--ds-number-stepper-border-color`, `--ds-number-stepper-step-bg-color-active`, `--ds-number-stepper-focus-shadow`.
262
+ Tokens: `--ds-number-stepper-field-width` sizes the number itself and is derived from the box height by default — a value with more digits than that width holds is clipped rather than wrapped, so widen it for large quantities. Also `--ds-number-stepper-bg-color`, `--ds-number-stepper-border-color`, `--ds-number-stepper-border-color-hover`, `--ds-number-stepper-step-bg-color`, `--ds-number-stepper-step-bg-color-hover`, `--ds-number-stepper-step-bg-color-active`, `--ds-number-stepper-step-text-color-hover`, `--ds-number-stepper-focus-shadow`.
262
263
 
263
264
  <!-- inputs:ds-number-stepper -->
264
- All inputs: `value: number = 0`, `min: number = 0`, `max: number | null = null`, `step: number = 1`, `size: 'sm' | 'md' | 'lg' = null`, `disabled: boolean = false`, `ariaLabel: string | null = null`
265
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `pending: boolean = false`, `dirty: boolean = false`, `showDirty: boolean | null = null`, `hidden: boolean = false`, `value: number = 0`, `min: number = 0`, `max: number | null = null`, `step: number = 1`, `size: 'sm' | 'md' | 'lg' = null`, `disabled: boolean = false`, `label: string = ''`, `required: boolean = false`, `ariaLabel: string | null = null`
265
266
  <!-- /inputs -->
266
267
 
267
268
  #### `<ds-checkbox>` — `CheckboxComponent`
@@ -342,7 +343,7 @@ Methods: `clear()` — empties the field, drops an armed keystroke and publishes
342
343
  Binds through `NG_VALUE_ACCESSOR`, taking the value plumbing without the field-message layer — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
343
344
 
344
345
  <!-- inputs:ds-search -->
345
- All inputs: `hidden: boolean = false`, `value: string = ''`, `placeholder: string | null = null`, `shortcut: string = ''`, `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `size: 'sm' | 'md' | 'lg' = null`, `debounce: number = 0`
346
+ All inputs: `hidden: boolean = false`, `value: string = ''`, `placeholder: string | null = null`, `shortcut: string = ''`, `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `size: 'sm' | 'md' | 'lg' = null`, `loading: boolean = false`, `debounce: number = 0`
346
347
  <!-- /inputs -->
347
348
 
348
349
  #### `<ds-date-picker>` — `DatePickerComponent`
@@ -360,7 +361,7 @@ Inputs: `accept: string = ''`, `multiple: boolean = false`, `files: model<Dropzo
360
361
  Outputs: `(filesAdded): File[]` (raw browser File list from drop or picker), `(fileRemoved): DropzoneFile` (a chip's remove button)
361
362
 
362
363
  <!-- inputs:ds-dropzone -->
363
- All inputs: `accept: string = ''`, `multiple: boolean = false`, `files: DropzoneFile[] = []`, `disabled: boolean = false`
364
+ All inputs: `hint: string = ''`, `error: string = ''`, `warning: string = ''`, `reserveMessage: boolean | null = null`, `messageIcon: IconName | false | null = null`, `errors: readonly DsFieldError[] = []`, `invalid: boolean = false`, `touched: boolean = false`, `pending: boolean = false`, `dirty: boolean = false`, `showDirty: boolean | null = null`, `accept: string = ''`, `multiple: boolean = false`, `files: DropzoneFile[] = []`, `disabled: boolean = false`, `label: string = ''`, `required: boolean = false`
364
365
  <!-- /inputs -->
365
366
 
366
367
  ---
@@ -374,7 +375,7 @@ All inputs: `ariaLabel: string | null = null`
374
375
  #### `<ds-split-button>` — `SplitButtonComponent`
375
376
 
376
377
  <!-- inputs:ds-split-button -->
377
- All inputs: `label: string = ''`, `variant: 'primary' | 'outline' = 'primary'`, `icon: IconName | null = null`, `disabled: boolean = false`, `menuItems: readonly SplitButtonItem[] = []`, `menuLabel: string | null = null`
378
+ All inputs: `label: string = ''`, `variant: 'primary' | 'outline' | 'surface' = 'primary'`, `icon: IconName | null = null`, `disabled: boolean = false`, `menuItems: readonly SplitButtonItem[] = []`, `menuLabel: string | null = null`
378
379
  <!-- /inputs -->
379
380
 
380
381
  #### `<ds-toggle-button>` — `ToggleButtonComponent`
@@ -447,10 +448,10 @@ All inputs: `dsFilterItem: unknown`
447
448
 
448
449
  #### `<ds-badge>` — `BadgeComponent`
449
450
  Inputs: `status: DsStatusKey` (consumer-registered status key; colours wired via `styles/status`, unset → neutral), `withDot: boolean = false`, `solid: boolean = false`, `count: number | null = null`, `max: number = 99`
450
- Content: label text. Use for status pills, counts, lifecycle markers.
451
+ Content: label text. Use for status labels, counts, lifecycle markers.
451
452
 
452
453
  <!-- inputs:ds-badge -->
453
- All inputs: `status: DsStatusKey`, `withDot: boolean | null = null`, `solid: boolean = false`, `count: number | null = null`, `max: number = 99`, `countLabel: string | null = null`
454
+ All inputs: `status: DsStatusKey`, `withDot: boolean | null = null`, `solid: boolean = false`, `appearance: 'default' | 'lozenge' = 'default'`, `icon: IconName | null = null`, `count: number | null = null`, `max: number = 99`, `countLabel: string | null = null`, `animateCount: boolean | null = null`
454
455
  <!-- /inputs -->
455
456
 
456
457
  #### `<ds-status-dot>` — `StatusDotComponent`
@@ -526,7 +527,7 @@ Inputs: `label: required string`, `value: required string | number`, `delta: num
526
527
  Delta direction is derived from the sign of `delta`: positive → up (arrow + green), negative → down (arrow + red), zero/null → neutral.
527
528
 
528
529
  <!-- inputs:ds-stat -->
529
- All inputs: `label: required string`, `value: string | number | null = ''`, `delta: number | null = null`, `deltaLabel: string = ''`, `deltaTone: 'neutral' | 'secondary' = null`, `caption: string = ''`, `unit: string = ''`, `variant: 'default' | 'error' = 'default'`, `size: 'sm' | 'md' | 'lg' = 'md'`
530
+ All inputs: `label: required string`, `value: string | number | null = ''`, `delta: number | null = null`, `deltaLabel: string = ''`, `deltaTone: 'neutral' | 'secondary' = null`, `caption: string = ''`, `unit: string = ''`, `variant: 'default' | 'error' = 'default'`, `animateValue: boolean | null = null`, `size: 'sm' | 'md' | 'lg' = 'md'`
530
531
  <!-- /inputs -->
531
532
 
532
533
  #### `<ds-empty-state>` — `EmptyStateComponent`
@@ -565,7 +566,7 @@ All inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'in
565
566
  <!-- /inputs -->
566
567
 
567
568
  #### `<ds-toast>` — `ToastComponent`
568
- Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `action: ToastAction | null = null` (`{ label, handler }` — renders a trailing button)
569
+ Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `action: ToastAction | null = null` (`{ label, handler }` — renders a trailing button), `iconAction: ToastIconAction | null = null` (`{ icon, label, handler, keepOpen?, successLabel? }` — an 18×18 icon button with a 14 px icon between the action and the close button; `label` is its accessible name and its tooltip; it closes the toast after `handler` unless `keepOpen` or `successLabel` is set; with `successLabel` the icon turns into a check for 1.2 s once `handler` (or the promise it returns) succeeds, and the label is announced). Tab order: action, icon action, close
569
570
  Output: `(closed): void`
570
571
  Content slots: default (body text, an alternative to `message`), `[actions]` (trailing CTAs). Neither is reachable through `ToastService`, which renders from `ToastOptions` — they are for a `<ds-toast>` you place yourself.
571
572
 
@@ -574,7 +575,7 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
574
575
  A toast leaving with focus inside it (its action, its close button, or `ToastRef.dismiss()`) hands focus to the next toast in the region, else back to the element focused before focus entered the region, as a dialog returns it.
575
576
 
576
577
  <!-- inputs:ds-toast -->
577
- All inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `body: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null`, `action: ToastAction | null = null`, `occurrences: readonly ToastOccurrence[] = []`
578
+ All inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `body: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null`, `action: ToastAction | null = null`, `iconAction: ToastIconAction | null = null`, `occurrences: readonly ToastOccurrence[] = []`
578
579
  <!-- /inputs -->
579
580
 
580
581
  ---
@@ -616,7 +617,7 @@ All inputs: `heading: string = ''`, `time: string = ''`, `icon: IconName | null
616
617
 
617
618
  #### `<ds-chat-message>` — `ChatMessageComponent`
618
619
 
619
- One message of a chat: `role: ChatMessageRole = 'assistant'` puts a filled bubble on the right (`'user'`), a subtle one on the left (`'assistant'`), or a centred notice from the app (`'system'`, spoken as `DS_INTL.chat.system`, `'Notice'`). A notice's `tone: ChatMessageTone = 'neutral'` follows its meaning: `'neutral'` is a quiet one-line plaque for a routine note (saved, switched, started), `'info'` / `'success'` / `'warning'` / `'error'` a card in that status colour with its icon for a note the reader should not miss; `title` adds a bold first line for a note with a detail under it; `icon` sets the icon (a neutral plaque shows one only when given). `author` shows above the bubble; `time` (already formatted) under it, in a thread only under the last message of a run, and not while `streaming`; `sentAt: Date | string | number | null` lets a thread split runs by time; without `author` the role is spoken (`DS_INTL.chat.user` / `assistant`). Slots: default (the text, or the markdown your app renders; a user message keeps its line breaks), `[steps]` above the bubble, on the thread's surface (a `ds-chat-steps` of the agent's steps; a message with only steps draws no bubble), `[attachments]` under the text (`ds-chat-attachment` for something to open, `ds-tag` for a plain file), `[actions]` under the bubble (copy, retry), shown on hover or focus and always without hover. Text is selectable and long words and URLs wrap. The window, tabs, composer and question cards around it stay in the app. `streaming` marks a reply still arriving (caret after the text, `aria-busy`, `[actions]` hidden; the thread reads it when it completes). `status: ChatMessageStatus | null` is the delivery of a sent message, under it in place of the time: `'sending'` (dimmed), `'failed'` with a Retry button emitting `(retry)`; `'sent'` shows nothing and is only spoken; the app resends and sets `status` back. `stepsFolded` (two-way) folds the `[steps]` into a chip at the top of the bubble with the step count and the failed count; the chip toggles them (`aria-expanded`), and stays once shown. Steps are counted from their `ds-chat-step`s; a step that fails while folded opens the steps again.
620
+ One message of a chat: `role: ChatMessageRole = 'assistant'` puts a filled bubble on the right (`'user'`), a subtle one on the left (`'assistant'`), or a centred notice from the app (`'system'`, spoken as `DS_INTL.chat.system`, `'Notice'`). A notice's `tone: ChatMessageTone = 'neutral'` follows its meaning: `'neutral'` is a quiet one-line plaque for a routine note (saved, switched, started), `'info'` / `'success'` / `'warning'` / `'error'` a card in that status colour with its icon for a note the reader should not miss; `title` adds a bold first line for a note with a detail under it; `icon` sets the icon (a neutral plaque shows one only when given). `author` shows above the bubble; `time` (already formatted) under it, in a thread only under the last message of a run, and not while `streaming`; `sentAt: Date | string | number | null` lets a thread split runs by time; without `author` the role is spoken (`DS_INTL.chat.user` / `assistant`). Slots: default (the text, or the markdown your app renders; a user message keeps its line breaks), `[steps]` above the bubble, on the thread's surface and the whole row wide (a `ds-chat-steps` of the agent's steps; a message with only steps draws no bubble), `[attachments]` under the text (`ds-chat-attachment` for something to open, `ds-tag` for a plain file), `[actions]` under the bubble (copy, retry), shown on hover or focus and always without hover. Text is selectable and long words and URLs wrap. The window, tabs, composer and question cards around it stay in the app. `streaming` marks a reply still arriving (caret after the text, `aria-busy`, `[actions]` hidden; the thread reads it when it completes). `status: ChatMessageStatus | null` is the delivery of a sent message, under it in place of the time: `'sending'` (dimmed), `'failed'` with a Retry button emitting `(retry)`; `'sent'` shows nothing and is only spoken; the app resends and sets `status` back. `stepsFolded` (two-way) folds the `[steps]` into a chip at the top of the bubble with the step count and the failed count; the chip toggles them (`aria-expanded`), and stays once shown. Steps are counted from their `ds-chat-step`s; a step that fails while folded opens the steps again.
620
621
  Tokens: `--ds-chat-message-max-width` (default `85%`), `--ds-chat-message-radius`, `--ds-chat-message-padding`, `--ds-chat-message-user-bg-color` / `-user-color`, `--ds-chat-message-assistant-bg-color` / `-assistant-color`, `--ds-chat-message-system-color` (default `--text-secondary`) / `-system-bg-color` (`--surface-secondary`) / `-system-border-color` (`--border-default`) for the neutral plaque.
621
622
 
622
623
  <!-- inputs:ds-chat-message -->
@@ -625,7 +626,7 @@ All inputs: `role: 'user' | 'assistant' | 'system' = 'assistant'`, `tone: 'neutr
625
626
 
626
627
  #### `<ds-chat-thread>` — `ChatThreadComponent`
627
628
 
628
- Scrollable list of `ds-chat-message`s; give it a height (or `flex: 1` in a column). Stays at the newest message as messages arrive or grow; once the reader scrolls up it stays put and shows a jump button with the count of messages that arrived below (`DS_INTL.chat.newMessages(count)`, `latest` when none). A message with `role="user"` arriving scrolls back down. Consecutive messages of one role sit at `--ds-chat-thread-group-gap`, speakers apart at `--ds-chat-thread-gap`; only the last message of a run takes the tight bottom corner on the speaker's side (`--ds-radius-inner`), the messages above it stay round. With `sentAt` on the messages, a gap of `timeBreakMinutes` (default `15`) or more starts a new run under a centred divider (`DS_INTL.chat.today` / `yesterday` or the date, then the time, in `DsConfig.locale`); the first dated message gets one too. `working` shows a spinner row with `workingLabel` (else `DS_INTL.chat.working`) at the end; never put a time estimate in it. Screen readers: the list is not a live region; the thread announces a finished assistant reply once (when it arrives while not `working`, or when `working` clears) and the working label, and never the messages present at first render. Older messages: set `hasOlder` and scrolling near the start emits `(loadOlder)` once until the list changes; prepend them and the thread keeps the message in view in place; `loadingOlder` shows a spinner over the top. A user message that arrives folds the steps of the replies before it, except a reply with a failed step the reader has not opened (`foldStepsOnSend`, default `true`); messages and steps that arrive later grow in while a pinned thread keeps its bottom still. Something laid over the bottom of the thread, such as attachments floating above the composer, sets `--ds-chat-thread-inset-bottom` to its height (default `0px`): the last message scrolls clear of it and the jump button sits above it. Method: `scrollToEnd()`.
629
+ Scrollable list of `ds-chat-message`s; give it a height (or `flex: 1` in a column). Stays at the newest message as messages arrive or grow; once the reader scrolls up it stays put and shows a jump button with the count of messages that arrived below (`DS_INTL.chat.newMessages(count)`, `latest` when none). A message with `role="user"` arriving scrolls back down. Consecutive messages of one role sit at `--ds-chat-thread-group-gap`, speakers apart at `--ds-chat-thread-gap`; only the last message of a run takes the tight bottom corner on the speaker's side (`--ds-radius-inner`), the messages above it stay round. With `sentAt` on the messages, a gap of `timeBreakMinutes` (default `15`) or more starts a new run under a centred divider (`DS_INTL.chat.today` / `yesterday` or the date, then the time, in `DsConfig.locale`); the first dated message gets one too. `working` shows a spinner row with `workingLabel` (else `DS_INTL.chat.working`) at the end, its label swept by a moving highlight (still under `prefers-reduced-motion: reduce`); never put a time estimate in it. Screen readers: the list is not a live region; the thread announces a finished assistant reply once (when it arrives while not `working`, or when `working` clears) and the working label, and never the messages present at first render. Older messages: set `hasOlder` and scrolling near the start emits `(loadOlder)` once until the list changes; prepend them and the thread keeps the message in view in place; `loadingOlder` shows a spinner over the top. A user message that arrives folds the steps of the replies before it, except a reply with a failed step the reader has not opened (`foldStepsOnSend`, default `true`); messages and steps that arrive later grow in while a pinned thread keeps its bottom still. Something laid over the bottom of the thread, such as attachments floating above the composer, sets `--ds-chat-thread-inset-bottom` to its height (default `0px`): the last message scrolls clear of it and the jump button sits above it. Method: `scrollToEnd()`.
629
630
  Tokens: `--ds-chat-thread-gap`, `--ds-chat-thread-group-gap`, `--ds-chat-thread-padding`, `--ds-chat-thread-inset-bottom`.
630
631
 
631
632
  <!-- inputs:ds-chat-thread -->
@@ -650,10 +651,10 @@ All inputs: `enter: 'together' | 'stagger' = 'together'`, `minRunningMs: number
650
651
 
651
652
  #### `<ds-chat-step>` — `ChatStepComponent`
652
653
 
653
- One step: `heading`, optional `time`, and `status: ChatStepStatus | null` (`'done' | 'running' | 'pending' | 'waiting' | 'error'`), which draws the marker (a check, a spinner, a dashed ring with muted text, a grey disc with a pause glyph, a cross) and is spoken before the heading (`DS_INTL.chat.stepDone`, `stepRunning`, `stepPending`, `stepWaiting` "Waiting for your approval", `stepFailed`). Slots: default content under the heading (the reader's answer buttons on a `waiting` step), with the marker beside the heading's first line; `[trailing]` at the end of the heading row (Stop, Retry); `[details]` behind a chevron toggle (`DS_INTL.chat.stepDetails(heading)`), closed by default, open state two-way as `expanded`; it opens with a height transition on a tinted card. A failed step the reader has not opened keeps its message's steps unfolded.
654
+ One step: `heading`, optional `time`, and `status: ChatStepStatus | null` (`'done' | 'running' | 'pending' | 'waiting' | 'error'`), which draws the marker (a check, a spinner, a dashed ring with muted text, a grey disc with a pause glyph, a cross) and is spoken before the heading (`DS_INTL.chat.stepDone`, `stepRunning`, `stepPending`, `stepWaiting` "Waiting for your approval", `stepFailed`); a `running` heading is swept by a moving highlight, still under `prefers-reduced-motion: reduce`. `startedAt` and `endedAt` (`Date | string | number | null`) end the heading row in the step's duration, right-aligned before `[trailing]` (`DS_INTL.chat.stepElapsed(seconds)`, `'4s'`, `'1m 13s'`, `'1h 2m'`); with `startedAt` alone a `running` step counts up each second. Slots: default content under the heading (the reader's answer buttons on a `waiting` step), with the marker beside the heading's first line; `[trailing]` at the end of the heading row (Stop, Retry); `[details]` behind a chevron toggle (`DS_INTL.chat.stepDetails(heading)`), closed by default, open state two-way as `expanded`; it opens with a height transition on a tinted card; `[actions]` in a row of buttons under the details, inside the open card with `--space-3` to its bottom edge (the way out of a failed step, such as Fix connection). `retryable` ends that row of an `error` step in an outline Retry button (`DS_INTL.chat.stepRetry`) that emits `retry`. A failed step the reader has not opened keeps its message's steps unfolded.
654
655
 
655
656
  <!-- inputs:ds-chat-step -->
656
- All inputs: `heading: string = ''`, `time: string = ''`, `status: 'done' | 'running' | 'pending' | 'waiting' | 'error' = null`, `expanded: boolean = false`
657
+ All inputs: `heading: string = ''`, `time: string = ''`, `status: 'done' | 'running' | 'pending' | 'waiting' | 'error' = null`, `startedAt: Date | string | number | null = null`, `endedAt: Date | string | number | null = null`, `expanded: boolean = false`, `retryable: boolean = false`
657
658
  <!-- /inputs -->
658
659
 
659
660
  #### `<ds-toast-region>` — `ToastRegionComponent`
@@ -664,7 +665,7 @@ All inputs: `maxVisible: number`, `showQueueCount: boolean = true`
664
665
 
665
666
  #### `<ds-tree>` — `TreeComponent`
666
667
 
667
- Nested rows with one tab stop and arrow-key navigation. `(nodeSelected)` emits the node selected; `(nodeHover)` emits the node under the pointer or newly focused, `null` when the pointer leaves the tree. `<ng-template dsTreeTrailing let-node>` draws at the end of every row (a badge, a count, a small icon button); a click inside it neither selects nor toggles the row, and its controls are tab stops on the focused row only. `<ng-template dsTreeLabel let-node>` replaces the row's label (context `node`, `level`, `selected`, `disabled`): the row grows to its height and it takes the width up to the trailing content, so its lines can cut with an ellipsis; its text is the row's accessible name, so a template that draws no text needs a visually hidden name. `selection="multiple"` binds `[(selectedIds)]`: Shift-click, Ctrl-click, Shift+Space or Ctrl+Space adds or removes a row, a plain click or Enter selects it alone, and the host carries `aria-multiselectable`.
668
+ Nested rows with one tab stop and arrow-key navigation. `(nodeSelected)` emits the node selected; `(nodeHover)` emits the node under the pointer or newly focused, `null` when the pointer leaves the tree. `<ng-template dsTreeTrailing let-node>` draws at the end of every row (a badge, a count, a small icon button), handed the row's `node` and `expanded` (`false` for a row without children), so a folder can show a count while collapsed (`let-expanded="expanded"`); a click inside it neither selects nor toggles the row, and its controls are tab stops on the focused row only. `<ng-template dsTreeLabel let-node>` replaces the row's label (context `node`, `level`, `selected`, `disabled`): the row grows to its height and it takes the width up to the trailing content, so its lines can cut with an ellipsis; its text is the row's accessible name, so a template that draws no text needs a visually hidden name. `selection="multiple"` binds `[(selectedIds)]`: Shift-click, Ctrl-click, Shift+Space or Ctrl+Space adds or removes a row, a plain click or Enter selects it alone, and the host carries `aria-multiselectable`.
668
669
  `toggleOn` says what expands and collapses a parent: `'row'` (default), where a click, Enter or Space selects the row and toggles it; `'caret'`, where the row only selects and the chevron is a button of its own that toggles (named by the `DsIntl` keys `tree.expand` / `tree.collapse`, `` `Expand ${label}` `` / `` `Collapse ${label}` ``, and outside the tab order); `'doubleClick'`, where a click selects and a double click toggles. ArrowRight and ArrowLeft expand and collapse in every mode, and a modified click in multiple selection only adds or removes the row.
669
670
  Expanding and collapsing animate: the revealed rows slide open and shut and the chevron turns, on `--duration-base` / `--ease-standard`; the first render does not animate, nothing moves under `prefers-reduced-motion: reduce`, and `[animate]="false"` toggles instantly.
670
671
 
@@ -688,34 +689,39 @@ All inputs: `term: string = ''`, `copyValue: string | null = null`
688
689
 
689
690
  ### Layout & navigation
690
691
 
691
- #### `<ds-sidenav>` — `SidenavComponent`
692
- Inputs: `collapsed: boolean = false`, `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = true` (whether an active item draws its edge marker — turn it off here rather than painting `--ds-sidenav-item-rail` transparent), `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
692
+ #### `<ds-nav>` — `NavComponent`
693
+ Renamed from `ds-sidenav`. `ds-sidenav`, `ds-sidenav-group`, `ds-sidenav-item`, `ds-sidenav-footer`, the `Sidenav*` exports, `SIDENAV`, the `--ds-sidenav-*` hooks and the `[sidenav]` slot of `ds-app-layout` still work and warn once in the console in development; they are removed 10 releases after 1.2.0.
694
+ **Tabs or nav.** Use `ds-tabs` for panels of one object on one page: up to 5-7, no groups, no nesting, only `?tab=` changes. Use `ds-nav` as soon as one holds: an item has its own page, more than 7 items, groups, dividers or nesting, or a second menu on the page. A vertical `ds-tabs` with more than 7 tabs warns in the console.
695
+ Inputs: `collapsed: boolean = false`, `label: string = ''` (names the menu as a navigation landmark, `role="navigation"` with this `aria-label`; set it on each menu when a page has more than one), `brand: string | null = null` (renders a letter mark + name; omit to project custom content, or set `DS_CONFIG.brand.name`), `logoLetter: string | null = null` (the mark's glyph; derived from `brand` when unset), `rail: boolean = false` (whether an active item draws its edge marker; `[rail]="true"` turns it on for the whole sidenav), `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
693
696
  Content: default slot for groups/items + custom brand/footer rows
694
697
  **The brand row leads home only if you say so.** `brandRoute` turns the mark + wordmark into one link; unset, the row stays a plain block. A logo that goes nowhere should not be a link, and whether a mark is a way home is an app's decision, not the DS's — so this is opt-in, like every other new capability here. The link announces itself as `"<brand>, home"` because a wordmark alone does not say where it goes; `brandLinkLabel` overrides that. Router targets only, and `RouterLink` is instantiated only inside the `@if`, so an app with no router provided still renders the sidenav. A collapse toggle projected into the row stays OUTSIDE the link — one control never nests inside another.
695
- Tokens: `--ds-sidenav-bg-color`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg-color`, `--ds-sidenav-mark-label-color`
698
+ Tokens: `--ds-nav-bg-color`, `--ds-nav-border`, `--ds-nav-width`, `--ds-nav-width-collapsed`, `--ds-nav-mark-bg-color`, `--ds-nav-mark-label-color`
696
699
 
697
- <!-- inputs:ds-sidenav -->
698
- All inputs: `collapsed: boolean = false`, `rail: boolean = true`, `brand: string | null = null`, `logoLetter: string | null = null`, `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
700
+ <!-- inputs:ds-nav -->
701
+ All inputs: `collapsed: boolean = false`, `label: string = ''`, `rail: boolean = false`, `variant: 'app' | 'page' = 'app'`, `brand: string | null = null`, `logoLetter: string | null = null`, `brandRoute: string | readonly unknown[] | null = null`, `brandLinkLabel: string | null = null`
699
702
  <!-- /inputs -->
700
703
 
701
- #### `<ds-sidenav-group>` — `SidenavGroupComponent`
704
+ #### `<ds-nav-group>` — `NavGroupComponent`
702
705
  Inputs: `label: string = ''`, `icon: IconName | null = null`, `expandable: boolean = false`, `expanded: model<boolean> = true`
703
706
  Content slots: default (items); `[ds-group-icon]` (custom group icon when not using a DS IconName)
704
707
  When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
705
708
 
706
- <!-- inputs:ds-sidenav-group -->
709
+ <!-- inputs:ds-nav-group -->
707
710
  All inputs: `label: string = ''`, `icon: IconName | null = null`, `expandable: boolean = false`, `routerLink: DsRouterLink = null`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `expanded: boolean = true`
708
711
  <!-- /inputs -->
709
712
 
710
- #### `<ds-sidenav-item>` — `SidenavItemComponent`
711
- Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-sidenav`)
713
+ #### `<ds-nav-divider>` — `NavDividerComponent`
714
+ No inputs. A line between items or groups, `role="separator"`. Token: `--ds-nav-divider-color`.
715
+
716
+ #### `<ds-nav-item>` — `NavItemComponent`
717
+ Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `trailingText: string = ''` (a short word at the end, such as a status or a shortcut; `badge` stays for numbers), `hasAlert: boolean = false`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-nav`, which is off by default)
712
718
  Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
713
- **What an active item announces.** An EXACT match on the item's destination announces `aria-current="page"`; a PREFIX match announces `true`, which in a sidenav is the useful case — "you are in this section". `ariaCurrent` overrides it, `null` silences it, and the `active` class is a separate question decided by `routerLinkActive`. `ds-sidenav-group` follows the same rule on a header that is itself a destination, and `routerLink` on both accepts a `UrlTree`. The value must go through `ariaCurrentWhenActive`, never `[attr.aria-current]`, and a relative destination must be resolved against the control's own route — see the two traps under `ds-button`.
719
+ **What an active item announces.** An EXACT match on the item's destination announces `aria-current="page"`; a PREFIX match announces `true`, which in a sidenav is the useful case — "you are in this section". `ariaCurrent` overrides it, `null` silences it, and the `active` class is a separate question decided by `routerLinkActive`. `ds-nav-group` follows the same rule on a header that is itself a destination, and `routerLink` on both accepts a `UrlTree`. The value must go through `ariaCurrentWhenActive`, never `[attr.aria-current]`, and a relative destination must be resolved against the control's own route — see the two traps under `ds-button`.
714
720
  **Three elements, decided by destination.** `routerLink` → an `<a [routerLink]>` with `routerLinkActive`; `href` → a plain `<a href>`; **neither → a `<button type="button">`**. Until 0.11.0 the last case fell back to `href="#"`, which navigates: it rewrites the URL and discards the scroll position on every click. An item that only emits `activate` is a button. Styling is identical across all three — the rules are class-based (`.item`) and the button's UA chrome is reset — so target the class, never the tag.
715
- Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--accent-subtitle` — a wash, not a solid pill), `--ds-sidenav-item-label-color-active` (default: `--accent-strong`), `--ds-sidenav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-sidenav-item-rail` (left rail, default: `--accent-strong`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
721
+ Tokens (on `:host`): `--ds-nav-item-label-color`, `--ds-nav-item-label-color-hover`, `--ds-nav-item-bg-color-hover`, `--ds-nav-item-bg-color-active` (default: `--accent-subtitle` — a wash, not a solid pill), `--ds-nav-item-label-color-active` (default: `--accent-strong`), `--ds-nav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-nav-item-rail` (left rail, default: `--accent-strong`), `--ds-nav-item-radius`, `--ds-nav-alert-color`
716
722
 
717
- <!-- inputs:ds-sidenav-item -->
718
- All inputs: `icon: IconName | null = null`, `label: required string`, `href: string = ''`, `routerLink: DsRouterLink = null`, `active: boolean = false`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `badge: number | null = null`, `hasAlert: boolean = false`, `disabled: boolean = false`, `rail: boolean | null = null`
723
+ <!-- inputs:ds-nav-item -->
724
+ All inputs: `icon: IconName | null = null`, `label: required string`, `href: string = ''`, `routerLink: DsRouterLink = null`, `active: boolean = false`, `ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true'`, `badge: number | null = null`, `trailingText: string = ''`, `hasAlert: boolean = false`, `disabled: boolean = false`, `rail: boolean | null = null`
719
725
  <!-- /inputs -->
720
726
 
721
727
  #### `<ds-topbar>` — `TopBarComponent`
@@ -725,7 +731,7 @@ Tokens (on `:host`): `--ds-topbar-height`, `--ds-topbar-bg-color`, `--ds-topbar-
725
731
 
726
732
  #### `<ds-app-layout>` — `AppLayoutComponent`
727
733
  Inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: model<boolean> = false` (the overlay rail below `--bp-lg`), `railLabel: string | null = null` (unset: `DS_INTL.appLayout.railLabel`), `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000` (ms), `scrollReset: 'path' | 'always' | 'never' = 'path'`
728
- Content slots: `[sidenav]`, `[topbar]`, default (the page)
734
+ Content slots: `[nav]` (`[sidenav]` is the deprecated name, removed 10 releases after 1.2.0), `[topbar]`, default (the page)
729
735
  Reads: `railId` and the read-only `railOverlay` signal, for a consumer-built burger; `dsRailTrigger` wires one for you.
730
736
  Tokens: `--ds-app-layout-padding-x`, `--ds-app-layout-padding-y`, `--ds-app-layout-content-max-width`, `--ds-app-layout-height`, `--ds-app-layout-rail-bg-color`, `--ds-app-layout-rail-shadow`, `--ds-app-layout-scrim-color`
731
737
  It owns the app's scroll CONTAINER, so a screen that needs to move the scroll calls `AppLayoutScrollService` rather than touching `window`.
@@ -835,10 +841,10 @@ Tokens: `--ds-splitter-gap`, `--ds-splitter-line-color`, `--ds-splitter-drag-col
835
841
  All inputs: `orientation: 'horizontal' | 'vertical' = 'horizontal'`, `pane: 'start' | 'end' = 'start'`, `size: number | null = null`, `defaultSize: number = 320`, `min: number = 160`, `max: number = 640`, `persistKey: string = ''`, `ariaLabel: string | null = null`, `overdrag: 'elastic' | 'none' = 'elastic'`, `dragFog: boolean = false`
836
842
  <!-- /inputs -->
837
843
 
838
- #### `<ds-sidenav-footer>` — `SidenavFooterComponent`
844
+ #### `<ds-nav-footer>` — `NavFooterComponent`
839
845
 
840
- <!-- inputs:ds-sidenav-footer -->
841
- All inputs: `userName: string = ''`, `userRole: string = ''`, `alerts: boolean = false`, `collapsed: boolean = false`, `searchProvider: SidenavSearchProvider | null = null`, `alertItems: readonly SidenavAlertItem[] | null = null`, `profileRoute: string = ''`
846
+ <!-- inputs:ds-nav-footer -->
847
+ All inputs: `userName: string = ''`, `userRole: string = ''`, `alerts: boolean = false`, `collapsed: boolean = false`, `searchProvider: NavSearchProvider | null = null`, `alertItems: readonly NavAlertItem[] | null = null`, `profileRoute: string = ''`
842
848
  <!-- /inputs -->
843
849
 
844
850
  #### `<ds-tab>` — `TabComponent`
@@ -918,7 +924,7 @@ Output: `(closed): void`
918
924
  Content slots: `[drawer-body]` (or `[body]`), `[drawer-footer]` (or `[actions]`). Content with no slot attribute, or with an attribute that names no slot, renders in the body. `actions` (or `drawer-footer`) goes on each button or on one `<div actions>` around them; both lay out the same.
919
925
 
920
926
  <!-- inputs:ds-drawer -->
921
- All inputs: `open: boolean = false`, `size: 'sm' | 'md' | 'lg' = 'md'`, `placement: 'right' | 'left' | 'top' | 'bottom' = 'right'`, `title: required string`, `staticPreview: boolean = false`
927
+ All inputs: `open: boolean = false`, `size: 'sm' | 'md' | 'lg' = 'md'`, `placement: 'right' | 'left' | 'top' | 'bottom' = 'right'`, `title: required string`, `scrimCutout: HTMLElement | DOMRect | null = null`, `staticPreview: boolean = false`
922
928
  <!-- /inputs -->
923
929
 
924
930
  #### `<ds-bottom-sheet>` — `BottomSheetComponent`
@@ -1150,7 +1156,7 @@ Series: `ScatterChartSeries = { id: string; label: string; data: readonly { x: n
1150
1156
  It thins its own data, and it says so. SVG degrades by the number of NODES, not readings — the same data as a line is one `<path>`, as a scatter it is one node per point, and Lighthouse warns at ~800 nodes and errors at ~1400 on a page that may hold four more charts. Past FOUR times the plot's width in marks the series is decimated, a line under the plot says how many readings were thinned, and the annex table still lists every one.
1151
1157
  `decimator`: `'minMax'` is the default because it is the only one that promises anything — each bucket's highest and lowest reading survive by construction, so the spike a reader is looking for cannot be the point that was dropped, and a bucket's answer does not depend on its neighbours. `'lttb'` draws a truer silhouette at the same budget with no such promise. `'none'` is the caller taking the node budget on themselves.
1152
1158
  The annex table is built when it is OPENED: `<details>` keeps its children in the DOM while shut, so 12 000 readings parked 48 000 nodes on the page - three times what decimating the plot had just saved. Closed the chart is 615 nodes; opened, every reading is there.
1153
- Hover answers with the point nearest the pointer anywhere over the plot: a ring glides to it and a dashed tether runs from the pointer to it. `nearestRadius: number | null = null` caps that reach in CSS pixels from a point's centre, inclusive. `showNearestPoint: false` answers only within 16px of a point's centre, without the ring and tether. Points enter left to right within 260ms (`staggerMs`).
1159
+ Hover answers with the point nearest the pointer anywhere over the plot: a ring glides to it. `nearestRadius: number | null = null` caps that reach in CSS pixels from a point's centre, inclusive. `showNearestPoint: false` answers only within 16px of a point's centre, without the ring. Points enter left to right within 260ms (`staggerMs`).
1154
1160
  Marks are semi-transparent by default, because the interesting thing is where they pile up: at full opacity a cluster of forty and a cluster of four are the same solid disc.
1155
1161
  The budget is a gate, not a paragraph: the decimator is fed 100 000 readings and the output is asserted to fit the plot, with a control that the same data undecimated does not.
1156
1162
  Tokens: `--ds-scatter-chart-grid-line-color`, `--ds-scatter-chart-axis-line-color`, `--ds-scatter-chart-axis-label-color`, `--ds-scatter-chart-axis-font-size`, `--ds-scatter-chart-dot-radius`, `--ds-scatter-chart-dot-opacity`, `--ds-scatter-chart-focus-color`, `--ds-scatter-chart-focus-width`.
@@ -1433,7 +1439,7 @@ this.crumbs.clear();
1433
1439
 
1434
1440
  #### `ToastService`
1435
1441
  `@Injectable({ providedIn: 'root' })`. Inject and call:
1436
- - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error' | 'loading', dismissible?, icon?, action?: ToastAction, durationMs? = 5000, groupKey? }`. Returns `{ id, dismiss(), update(patch) }`: `update` takes a `ToastUpdate` (`title`, `body`, `variant`, `durationMs`, `dismissible`) and changes the toast in place while it is on screen or queued, and does nothing once it is gone; it is announced only when `variant` turns `success` or `error`, `durationMs` restarts the countdown, and a toast leaving `loading` without one counts down 5000 ms. `durationMs: 0` (and any negative) means it never auto-dismisses, and it is counted from the moment the toast becomes VISIBLE, not from the call — a toast queued behind `maxVisible` keeps its full time on screen. A `loading` toast is forced to 0 and discards a supplied `durationMs`.
1442
+ - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error' | 'loading', dismissible?, icon?, action?: ToastAction, iconAction?: ToastIconAction, durationMs? = 5000, groupKey? }`. A toast with an `action` or an `iconAction` never auto-dismisses and is always dismissible. Returns `{ id, dismiss(), update(patch) }`: `update` takes a `ToastUpdate` (`title`, `body`, `variant`, `durationMs`, `dismissible`) and changes the toast in place while it is on screen or queued, and does nothing once it is gone; it is announced only when `variant` turns `success` or `error`, `durationMs` restarts the countdown, and a toast leaving `loading` without one counts down 5000 ms. `durationMs: 0` (and any negative) means it never auto-dismisses, and it is counted from the moment the toast becomes VISIBLE, not from the call — a toast queued behind `maxVisible` keeps its full time on screen. A `loading` toast is forced to 0 and discards a supplied `durationMs`.
1437
1443
  - `promise<T>(source: Promise<T>, messages: ToastPromiseMessages): Promise<T>` — shows a `loading` toast, then patches it in place to `success` or `error` when `source` settles. Returns `source` itself, so an un-`catch`ed call still produces an unhandled rejection. The settled toast dismisses after a hard-coded 4s (success) or 6s (error), counted from the moment it becomes visible and not overridable; `dismissAll()` cancels it like any other. A toast closed before `source` settles stays closed and its outcome is not announced.
1438
1444
  - `dismissAll(): void`
1439
1445
 
package/design-system.md CHANGED
@@ -129,6 +129,7 @@ usage across the library:
129
129
  | `--text-tertiary` | 69 | Meta that must not compete: eyebrows, placeholders, counters, timestamps. |
130
130
  | `--text-secondary` | 46 | Supporting copy that still has to be read — hints, subtitles, descriptions. |
131
131
  | `--text-disabled` | 33 | Only for a disabled control. Never as "quiet text". |
132
+ | `--text-muted` | 4 | Decoration only: a grip, the days of a neighbouring month. Never text that must be read. |
132
133
  | `--surface-default` | 50 | The page and the inside of a control. |
133
134
  | `--surface-secondary` | 52 | A tier up from the page: table heads, sandboxes, code blocks. |
134
135
  | `--surface-muted` | 16 | Hover and pressed fills on a neutral row. |
@@ -354,21 +355,21 @@ components (measured 2026-09-01) show which one a given surface actually takes:
354
355
 
355
356
  | Role | Resolves to | Uses | What it is for |
356
357
  | --- | --- | --- | --- |
357
- | `--ds-radius-inner` | `--radius-sm` (4px) | 37 | Something nested INSIDE a control — a tick, a kbd cap, a focus halo, a segment |
358
- | `--ds-radius-control` | `--radius-md` (8px) | 26 | The control itself — button, field, tag, tooltip, segmented, search |
358
+ | `--ds-radius-inner` | `--radius-sm` (4px) | 37 | Something nested INSIDE a control or a row — a tick, a kbd cap, a focus halo, a status badge |
359
+ | `--ds-radius-control` | `--radius-sm-md` (6px) | 26 | The control itself — button, field, tag, tooltip, segmented, search, menu |
359
360
  | `--ds-radius-panel` | `--radius-lg` (12px) | 13 | A surface that CONTAINS controls — card, modal, bottom sheet, popover, the picker panels, page footer |
360
- | `--ds-radius-pill` | `--radius-pill` (999px) | 4 | Fully round by meaning, not by size — avatar, badge, radio, progress track |
361
+ | `--ds-radius-pill` | `--radius-pill` (999px) | 4 | Fully round by meaning, not by size — avatar, count badge, radio, progress track |
361
362
 
362
363
  The raw steps (`--radius-sm` … `--radius-2xl`) are the scale the roles map onto. Using one
363
- directly says "this corner belongs to no role", which is almost never true. `--radius-xl` (16px)
364
- and `--radius-2xl` (24px) have no consumer in the library at all — their comments in
364
+ directly says "this corner belongs to no role", which is almost never true. `--radius-md` (8px),
365
+ `--radius-xl` (16px) and `--radius-2xl` (24px) have no consumer in the library at all — their comments in
365
366
  the token file describe an intent, not a usage.
366
367
 
367
368
  ### Nesting: inner < control < panel, and never equal
368
369
 
369
370
  A rounded thing inside a rounded thing needs a SMALLER radius, or the inner corner appears
370
371
  to bulge out of the outer one. The three roles are ordered for exactly this: a field
371
- (`control`, 8px) inside a card (`panel`, 12px); a tick (`inner`, 4px) inside a checkbox
372
+ (`control`, 6px) inside a card (`panel`, 12px); a tick (`inner`, 4px) inside a checkbox
372
373
  (`control`). If two nested surfaces share a radius, one of them is wrong.
373
374
 
374
375
  The optical rule when you need a value the roles do not cover: inner radius = outer radius
@@ -401,7 +402,7 @@ above it: which region holds what, and in which order.
401
402
 
402
403
  ```
403
404
  ds-app-layout
404
- ├── [sidenav] ds-sidenav — reserve the rail, OUTSIDE the page grid
405
+ ├── [nav] ds-nav — reserve the rail, OUTSIDE the page grid
405
406
  ├── [topbar] ds-topbar — global, not per-page
406
407
  └── (default) the page itself
407
408
  ├── ds-page-header — breadcrumbs · title · meta · actions · tabs
@@ -7,6 +7,13 @@
7
7
  "since": "0.14.1",
8
8
  "itemId": "0.14.1#chart-tooltip-prefer-below-removed"
9
9
  },
10
+ {
11
+ "element": "*",
12
+ "name": "dsTooltipClippedLead",
13
+ "replacement": null,
14
+ "since": "0.15.0",
15
+ "itemId": "0.15.0#tooltip-clipped-lead-removed"
16
+ },
10
17
  {
11
18
  "element": "*",
12
19
  "name": "dsTooltipTextSelector",
@@ -14,6 +21,13 @@
14
21
  "since": "0.15.0",
15
22
  "itemId": "0.15.0#tooltip-text-selector-merged-into-when-clipped"
16
23
  },
24
+ {
25
+ "element": "*",
26
+ "name": "sidenav",
27
+ "replacement": null,
28
+ "since": "1.2.0",
29
+ "itemId": "1.2.0#app-layout-sidenav-slot-renamed-to-nav"
30
+ },
17
31
  {
18
32
  "element": "ds-accordion",
19
33
  "name": "multi",
@@ -453,6 +467,30 @@
453
467
  "replacement": "ds-bar",
454
468
  "since": "0.13.3",
455
469
  "itemId": "0.13.3#progress-renamed-to-bar"
470
+ },
471
+ {
472
+ "name": "ds-sidenav",
473
+ "replacement": "ds-nav",
474
+ "since": "1.2.0",
475
+ "itemId": "1.2.0#sidenav-renamed-to-nav"
476
+ },
477
+ {
478
+ "name": "ds-sidenav-footer",
479
+ "replacement": "ds-nav-footer",
480
+ "since": "1.2.0",
481
+ "itemId": "1.2.0#sidenav-footer-renamed-to-nav-footer"
482
+ },
483
+ {
484
+ "name": "ds-sidenav-group",
485
+ "replacement": "ds-nav-group",
486
+ "since": "1.2.0",
487
+ "itemId": "1.2.0#sidenav-group-renamed-to-nav-group"
488
+ },
489
+ {
490
+ "name": "ds-sidenav-item",
491
+ "replacement": "ds-nav-item",
492
+ "since": "1.2.0",
493
+ "itemId": "1.2.0#sidenav-item-renamed-to-nav-item"
456
494
  }
457
495
  ],
458
496
  "symbols": [
@@ -673,6 +711,76 @@
673
711
  "since": "0.7.0",
674
712
  "itemId": "0.7.0#shell-scroll-service-to-layout-scroll-service"
675
713
  },
714
+ {
715
+ "name": "SIDENAV",
716
+ "replacement": "NAV",
717
+ "renamed": true,
718
+ "since": "1.2.0",
719
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
720
+ },
721
+ {
722
+ "name": "SidenavAlertItem",
723
+ "replacement": "NavAlertItem",
724
+ "renamed": true,
725
+ "since": "1.2.0",
726
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
727
+ },
728
+ {
729
+ "name": "SidenavComponent",
730
+ "replacement": "NavComponent",
731
+ "renamed": true,
732
+ "since": "1.2.0",
733
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
734
+ },
735
+ {
736
+ "name": "SidenavContract",
737
+ "replacement": "NavContract",
738
+ "renamed": true,
739
+ "since": "1.2.0",
740
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
741
+ },
742
+ {
743
+ "name": "SidenavFooterComponent",
744
+ "replacement": "NavFooterComponent",
745
+ "renamed": true,
746
+ "since": "1.2.0",
747
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
748
+ },
749
+ {
750
+ "name": "SidenavGroupComponent",
751
+ "replacement": "NavGroupComponent",
752
+ "renamed": true,
753
+ "since": "1.2.0",
754
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
755
+ },
756
+ {
757
+ "name": "SidenavItemComponent",
758
+ "replacement": "NavItemComponent",
759
+ "renamed": true,
760
+ "since": "1.2.0",
761
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
762
+ },
763
+ {
764
+ "name": "SidenavItemModel",
765
+ "replacement": "NavItemModel",
766
+ "renamed": true,
767
+ "since": "1.2.0",
768
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
769
+ },
770
+ {
771
+ "name": "SidenavSearchProvider",
772
+ "replacement": "NavSearchProvider",
773
+ "renamed": true,
774
+ "since": "1.2.0",
775
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
776
+ },
777
+ {
778
+ "name": "SidenavSearchResult",
779
+ "replacement": "NavSearchResult",
780
+ "renamed": true,
781
+ "since": "1.2.0",
782
+ "itemId": "1.2.0#sidenav-types-renamed-to-nav"
783
+ },
676
784
  {
677
785
  "name": "SortDir",
678
786
  "replacement": "SortDirection",
@@ -885,13 +993,6 @@
885
993
  "since": "0.5.1",
886
994
  "itemId": "0.5.1#tabs-tabclose-output-rename"
887
995
  },
888
- {
889
- "owner": "TimePickerComponent",
890
- "name": "valueChange",
891
- "replacement": null,
892
- "since": "1.0.0",
893
- "itemId": "1.0.0#time-picker-value-changes-while-scrolling"
894
- },
895
996
  {
896
997
  "owner": "ToastComponent",
897
998
  "name": "dismissed",