feat(dialtone-vue): DLT-3225 migrate component size props to numeric ordinal scale (#1157)

Author: francisrupert

.claude/rules/vue-components.md

@@ -30,9 +30,14 @@ paths:
 
 ## Sizes
 
-- Interactive components: `xs`, `sm`, `md`, `lg`, `xl` (string).
-- Icons: numeric scale `100`–`800`.
-- Export from `*_constants.js`: `COMPONENT_SIZES` object + `COMPONENT_SIZE_DEFAULT`.
+- All component size props use a numeric ordinal scale: `100` (xs), `200` (sm), `300` (md), `400` (lg), `500` (xl).
+- Prop type: `[String, Number]`. Default: numeric (e.g., `default: 300`).
+- T-shirt aliases (`xs`, `sm`, `md`, `lg`, `xl`) remain in constants for backward compat but are deprecated.
+- `@values` JSDoc: list numeric only (e.g., `@values 100, 200, 300, 400, 500`). Do not list t-shirt aliases.
+- Text headline extends the scale: `500` (xl), `600` (2xl), `700` (3xl).
+- Icons: separate numeric scale `100`–`800` (unchanged, do not modify).
+- Shared scale definition: `packages/dialtone-vue/common/constants/sizes.js`.
+- Export from `*_constants.js`: `COMPONENT_SIZE_MODIFIERS` object with both numeric and t-shirt keys.
 
 ## Separation of Concerns
 

packages/dialtone-cli/package.json

@@ -23,7 +23,7 @@
     "@dialpad/dialtone-css": "workspace:*",
     "@dialpad/dialtone-icons": "workspace:*",
     "@dialpad/dialtone-query-core": "workspace:*",
-    "@dialpad/dialtone-vue": "workspace:^3",
+    "@dialpad/dialtone-vue": "workspace:*",
     "@rollup/plugin-commonjs": "^28.0.0",
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^15.2.0",

packages/dialtone-query-core/package.json

@@ -14,7 +14,7 @@
   "devDependencies": {
     "@dialpad/dialtone-css": "workspace:*",
     "@dialpad/dialtone-icons": "workspace:*",
-    "@dialpad/dialtone-vue": "workspace:^3",
+    "@dialpad/dialtone-vue": "workspace:*",
     "@types/node": "24.3.1",
     "typescript": "^5.2"
   },

packages/dialtone-vue/common/constants/index.js

@@ -22,6 +22,13 @@ export const DESCRIPTION_SIZE_TYPES = {
 
 // Description size variants
 export const DESCRIPTION_SIZE_MODIFIERS = {
+  // Numeric (preferred)
+  100: 'd-description--xs',
+  200: 'd-description--sm',
+  300: '',
+  400: 'd-description--lg',
+  500: 'd-description--xl',
+  // T-shirt aliases (deprecated)
   xs: 'd-description--xs',
   sm: 'd-description--sm',
   md: '',
@@ -31,6 +38,13 @@ export const DESCRIPTION_SIZE_MODIFIERS = {
 
 // Label size variants
 export const LABEL_SIZE_MODIFIERS = {
+  // Numeric (preferred)
+  100: 'd-label--xs',
+  200: 'd-label--sm',
+  300: '',
+  400: 'd-label--lg',
+  500: 'd-label--xl',
+  // T-shirt aliases (deprecated)
   xs: 'd-label--xs',
   sm: 'd-label--sm',
   md: '',
@@ -66,6 +80,9 @@ export const DEFAULT_VALIDATION_MESSAGE_TYPE = VALIDATION_MESSAGE_TYPES.ERROR;
 // Default prefix used for ids
 export const DEFAULT_PREFIX = 'dt';
 
+// Component size scale
+export { COMPONENT_SIZES, TEXT_HEADLINE_SIZES } from './sizes.js';
+
 export default {
   VALIDATION_MESSAGE_TYPES,
   DESCRIPTION_SIZE_TYPES,

packages/dialtone-vue/common/constants/sizes.js

@@ -0,0 +1,31 @@
+/**
+ * Canonical numeric-to-t-shirt size mapping for component size props.
+ *
+ * Scale: 100-unit ordinal steps with 50-unit half-steps reserved for future sizes.
+ * Convention matches Dialtone's existing token scales (dt-size-*, dt-icon-size-*, colors).
+ *
+ * @example
+ *   <DtButton :size="200" />   <!-- equivalent to size="sm" -->
+ *   <DtButton :size="250" />   <!-- future "smedium" -->
+ */
+
+// Numeric → t-shirt label mapping
+export const COMPONENT_SIZES = {
+  100: 'xs',
+  200: 'sm',
+  300: 'md',
+  400: 'lg',
+  500: 'xl',
+};
+
+// Extended sizes for Text headline kind
+export const TEXT_HEADLINE_SIZES = {
+  ...COMPONENT_SIZES,
+  600: '2xl',
+  700: '3xl',
+};
+
+export default {
+  COMPONENT_SIZES,
+  TEXT_HEADLINE_SIZES,
+};

packages/dialtone-vue/components/avatar/avatar.stories.js

@@ -11,7 +11,7 @@ const ICONS_LIST = getIconNames();
 
 export const argsData = {
   onClick: action('click'),
-  size: 'md',
+  size: 300,
   presence: null,
   fullName: 'Jaqueline Nackos',
   imageAlt: 'profile image',

packages/dialtone-vue/components/avatar/avatar.vue

@@ -171,7 +171,7 @@ export default {
      * The size of the avatar.
      * T-shirt sizes (xs, sm, md, lg, xl) are deprecated and will be removed in the next major version.
      * Please use the numeric scale instead.
-     * @values 100, 150, 200, 250, 300, 400, 500, 600, 700, 800, 900, xs, sm, md, lg, xl
+     * @values 100, 150, 200, 250, 300, 400, 500, 600, 700, 800, 900
      */
     size: {
       type: [String, Number],

packages/dialtone-vue/components/button/button.stories.js

@@ -17,7 +17,7 @@ export const argsData = {
   onClick: action('click'),
   onFocusIn: action('focusin'),
   onFocusOut: action('focusout'),
-  size: 'md',
+  size: 300,
   link: false,
 };
 

packages/dialtone-vue/components/button/button.test.js

@@ -227,6 +227,18 @@ describe('DtButton Tests', () => {
         });
       });
 
+      describe('When size is numeric', () => {
+        it('should apply the correct size class for numeric size 200', async () => {
+          await wrapper.setProps({
+            size: 200,
+          });
+
+          button = wrapper.find('.base-button__button');
+
+          expect(button.classes().includes('d-btn--sm')).toBe(true);
+        });
+      });
+
       describe('When button has an invalid size prop', () => {
         it('should not have a size class', async () => {
           await wrapper.setProps({

packages/dialtone-vue/components/button/button.vue

@@ -281,12 +281,12 @@ export default {
 
     /**
      * The size of the button.
-     * @values xs, sm, md, lg, xl
+     * @values 100, 200, 300, 400, 500
      */
     size: {
-      type: String,
-      default: 'md',
-      validator: (s) => Object.keys(BUTTON_SIZE_MODIFIERS).includes(s),
+      type: [String, Number],
+      default: 300,
+      validator: (s) => Object.keys(BUTTON_SIZE_MODIFIERS).includes(String(s)),
     },
 
     /**
@@ -508,11 +508,11 @@ export default {
     },
 
     iconSize () {
-      return BUTTON_ICON_SIZES[this.size];
+      return BUTTON_ICON_SIZES[String(this.size)];
     },
 
     loaderSize () {
-      return BUTTON_ICON_SIZES[this.size];
+      return BUTTON_ICON_SIZES[String(this.size)];
     },
   },
 
@@ -547,7 +547,7 @@ export default {
         return [
           'd-link',
           getLinkKindModifier(this.linkKind, this.linkInverted),
-          BUTTON_SIZE_MODIFIERS[this.size],
+          BUTTON_SIZE_MODIFIERS[String(this.size)],
           { 'd-link--no-underline': !this.resolvedUnderline },
         ];
       }
@@ -558,7 +558,7 @@ export default {
         'd-btn',
         BUTTON_IMPORTANCE_MODIFIERS[this.importance],
         BUTTON_KIND_MODIFIERS[this.kind],
-        BUTTON_SIZE_MODIFIERS[this.size],
+        BUTTON_SIZE_MODIFIERS[String(this.size)],
         {
           'd-btn--circle': this.circle,
           'd-btn--loading': this.loading,