@hirobius/design-system 0.16.0 → 0.17.0

package/dist/variables.css

@@ -108,16 +108,16 @@
   --primitive-typography-family-primary: Satoshi, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --primitive-typography-family-display: Satoshi, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --primitive-typography-family-mono: "Geist Mono", "Courier New", monospace;
-  --primitive-typography-size-xs: 13px;
-  --primitive-typography-size-sm: 15px;
-  --primitive-typography-size-base: 17px;
-  --primitive-typography-size-lg: 20px;
-  --primitive-typography-size-xl: 24px;
-  --primitive-typography-size-2xl: 30px;
-  --primitive-typography-size-3xl: 36px;
-  --primitive-typography-size-4xl: 48px;
-  --primitive-typography-size-5xl: 72px;
-  --primitive-typography-size-6xl: 80px;
+  --primitive-typography-size-xs: 12px;
+  --primitive-typography-size-sm: 14px;
+  --primitive-typography-size-base: 16px;
+  --primitive-typography-size-lg: 18px;
+  --primitive-typography-size-xl: 20px;
+  --primitive-typography-size-2xl: 24px;
+  --primitive-typography-size-3xl: 30px;
+  --primitive-typography-size-4xl: 36px;
+  --primitive-typography-size-5xl: 48px;
+  --primitive-typography-size-6xl: 60px;
   --primitive-typography-weight-regular: 400;
   --primitive-typography-weight-medium: 500;
   --primitive-typography-weight-bold: 700;
@@ -187,6 +187,7 @@
   /* semantic.motion.exit */
   --hds-motion-exit-duration: var(--primitive-duration-instant);
   --hds-motion-exit-easing: var(--primitive-easing-accelerate);
+  --semantic-motion-distance: var(--primitive-space-6);
   --semantic-color-surface-page: var(--primitive-color-neutral-white);
   --semantic-color-surface-raised: var(--primitive-color-neutral-50);
   --semantic-color-surface-overlay: var(--primitive-color-neutral-100);
@@ -225,15 +226,22 @@
   --semantic-color-feedback-bg-warning: var(--primitive-color-amber-50);
   --semantic-color-feedback-bg-info: var(--primitive-color-blue-50);
   --semantic-color-feedback-bg-inProgress: var(--primitive-color-violet-50);
+  --semantic-space-scale-xs: var(--primitive-space-2);
+  --semantic-space-scale-sm: var(--primitive-space-4);
+  --semantic-space-scale-md: var(--primitive-space-6);
+  --semantic-space-scale-lg: var(--primitive-space-8);
+  --semantic-space-scale-xl: var(--primitive-space-12);
+  --semantic-space-surface-padding: var(--semantic-space-scale-md);
+  --semantic-space-region-gutter: var(--semantic-space-scale-md);
   --semantic-space-subgrid-hairline: var(--primitive-space-px1);
   --semantic-space-subgrid-xs: var(--primitive-space-px2);
   --semantic-space-subgrid-gap: var(--primitive-space-1);
   --semantic-space-component-gap: var(--primitive-space-2);
   --semantic-space-component-medium: var(--primitive-space-3);
-  --semantic-space-component-padding: var(--primitive-space-6);
+  --semantic-space-component-padding: var(--semantic-space-surface-padding);
   --semantic-space-layout-tight: var(--primitive-space-4);
   --semantic-space-layout-normal: var(--primitive-space-6);
-  --semantic-space-layout-gutter: var(--primitive-space-6);
+  --semantic-space-layout-gutter: var(--semantic-space-region-gutter);
   --semantic-space-layout-inset: var(--primitive-space-8);
   --semantic-space-layout-spacious: var(--primitive-space-12);
   --semantic-space-section-stack: var(--primitive-space-20);
@@ -256,25 +264,25 @@
   --semantic-layout-grid-columns-desktop: var(--primitive-grid-columns-3);
   /* semantic.typography.display */
   --semantic-typography-display-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-display-font-size: var(--primitive-typography-size-5xl);
+  --semantic-typography-display-font-size: var(--primitive-typography-size-6xl);
   --semantic-typography-display-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-display-letter-spacing: var(--primitive-typography-letterSpacing-tight);
   --semantic-typography-display-line-height: var(--primitive-typography-lineHeight-none);
   /* semantic.typography.h1 */
   --semantic-typography-h1-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h1-font-size: var(--primitive-typography-size-4xl);
+  --semantic-typography-h1-font-size: var(--primitive-typography-size-5xl);
   --semantic-typography-h1-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h1-letter-spacing: var(--primitive-typography-letterSpacing-tight);
   --semantic-typography-h1-line-height: var(--primitive-typography-lineHeight-tight);
   /* semantic.typography.h2 */
   --semantic-typography-h2-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h2-font-size: var(--primitive-typography-size-2xl);
+  --semantic-typography-h2-font-size: var(--primitive-typography-size-3xl);
   --semantic-typography-h2-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h2-letter-spacing: var(--primitive-typography-letterSpacing-tight);
-  --semantic-typography-h2-line-height: 42px;
+  --semantic-typography-h2-line-height: 40px;
   /* semantic.typography.h3 */
   --semantic-typography-h3-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h3-font-size: var(--primitive-typography-size-lg);
+  --semantic-typography-h3-font-size: var(--primitive-typography-size-xl);
   --semantic-typography-h3-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h3-letter-spacing: var(--primitive-typography-letterSpacing-normal);
   --semantic-typography-h3-line-height: 28px;
@@ -283,18 +291,18 @@
   --semantic-typography-body-font-size: var(--primitive-typography-size-base);
   --semantic-typography-body-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-body-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-body-line-height: 28px;
+  --semantic-typography-body-line-height: 24px;
   --semantic-typography-body-max-width: 60ch;
   /* semantic.typography.ui */
   --semantic-typography-ui-font-family: var(--primitive-typography-family-primary);
   --semantic-typography-ui-font-size: var(--primitive-typography-size-sm);
   --semantic-typography-ui-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-ui-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-ui-line-height: 24px;
+  --semantic-typography-ui-line-height: 20px;
   --semantic-typography-ui-max-width: 60ch;
   /* semantic.typography.caption */
   --semantic-typography-caption-font-family: var(--primitive-typography-family-primary);
-  --semantic-typography-caption-font-size: 12px;
+  --semantic-typography-caption-font-size: var(--primitive-typography-size-xs);
   --semantic-typography-caption-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-caption-letter-spacing: var(--primitive-typography-letterSpacing-normal);
   --semantic-typography-caption-line-height: 16px;
@@ -303,11 +311,11 @@
   --semantic-typography-eyebrow-font-size: var(--primitive-typography-size-xs);
   --semantic-typography-eyebrow-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-eyebrow-letter-spacing: var(--primitive-typography-letterSpacing-caps);
-  --semantic-typography-eyebrow-line-height: 20px;
+  --semantic-typography-eyebrow-line-height: 16px;
   --semantic-typography-eyebrow-text-transform: uppercase;
   /* semantic.typography.mono */
   --semantic-typography-mono-font-family: var(--primitive-typography-family-mono);
-  --semantic-typography-mono-font-size: var(--primitive-typography-size-xs);
+  --semantic-typography-mono-font-size: var(--primitive-typography-size-sm);
   --semantic-typography-mono-font-weight: var(--primitive-typography-weight-regular);
   --semantic-typography-mono-letter-spacing: var(--primitive-typography-letterSpacing-normal);
   --semantic-typography-mono-line-height: 20px;
@@ -325,6 +333,7 @@
   --semantic-accent-contentHover: var(--primitive-color-neutral-700);
   --semantic-accent-subtle: var(--primitive-color-neutral-100);
   --semantic-radius-action: var(--primitive-radius-8);
+  --semantic-radius-control: var(--primitive-radius-4);
   --semantic-borderWidth-default: var(--primitive-borderWidth-xs);
   --semantic-borderWidth-emphasis: var(--primitive-borderWidth-sm);
   --semantic-shadow-subtle: 0 1px 2px hsl(var(--primitive-shadow-color) / 0.04), 0 1px 1px hsl(var(--primitive-shadow-color) / 0.06);
@@ -346,6 +355,17 @@
   --semantic-elevation-overlay-surface: var(--semantic-color-surface-overlay);
   --semantic-elevation-overlay-shadow: var(--semantic-shadow-overlay);
   --semantic-elevation-overlay-border: transparent;
+  --semantic-size-control-sm: var(--primitive-size-8);
+  --semantic-size-control-md: var(--primitive-size-20);
+  --semantic-size-control-lg: var(--primitive-size-32);
+  --semantic-size-icon-sm: var(--primitive-size-16);
+  --semantic-size-icon-md: var(--primitive-size-20);
+  --semantic-size-icon-lg: var(--primitive-size-24);
+  --semantic-size-avatar: var(--primitive-size-40);
+  --semantic-size-row-compact: var(--primitive-size-40);
+  --semantic-size-row-comfortable: var(--primitive-size-48);
+  --semantic-zIndex-control: var(--primitive-zIndex-10);
+  --semantic-zIndex-sticky: var(--primitive-zIndex-100);
 
   /* ── Component ─────────────────────────────────────────────────────────── */
   --component-nav-bg: var(--semantic-color-surface-page);

package/hirobius.tokens.json

@@ -497,64 +497,73 @@
         "$type": "dimension",
         "xs": {
           "$value": {
-            "value": 13,
+            "value": 12,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-xs (hds#283 ramp)."
         },
         "sm": {
           "$value": {
-            "value": 15,
+            "value": 14,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-sm (hds#283 ramp)."
         },
         "base": {
           "$value": {
-            "value": 17,
+            "value": 16,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-base (hds#283 ramp)."
         },
         "lg": {
           "$value": {
-            "value": 20,
+            "value": 18,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-lg (hds#283 ramp)."
         },
         "xl": {
           "$value": {
-            "value": 24,
+            "value": 20,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-xl (hds#283 ramp)."
         },
         "2xl": {
           "$value": {
-            "value": 30,
+            "value": 24,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-2xl (hds#283 ramp)."
         },
         "3xl": {
           "$value": {
-            "value": 36,
+            "value": 30,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-3xl (hds#283 ramp)."
         },
         "4xl": {
           "$value": {
-            "value": 48,
+            "value": 36,
             "unit": "px"
-          }
+          },
+          "$description": "Tailwind 4 default text-4xl (hds#283 ramp)."
         },
         "5xl": {
           "$value": {
-            "value": 72,
+            "value": 48,
             "unit": "px"
           },
-          "$description": "Swiss-canon display size. Static desktop value; fluid in theme.css."
+          "$description": "Tailwind 4 default text-5xl (hds#283 ramp)."
         },
         "6xl": {
           "$value": {
-            "value": 80,
+            "value": 60,
             "unit": "px"
-          }
+          },
+          "$description": "Swiss-canon display size (hds#283 ramp). Static desktop value; fluid in theme.css. Tailwind 4 default text-6xl."
         }
       },
       "weight": {
@@ -968,6 +977,11 @@
           "easing": "{primitive.easing.accelerate}"
         },
         "$description": "For elements being removed from the DOM."
+      },
+      "distance": {
+        "$type": "dimension",
+        "$value": "{primitive.space.6}",
+        "$description": "Travel distance for a scroll-reveal translateY offset. Coincides in value with semantic.space.scale.md today, but names a motion travel distance rather than a spacing tier (hds#242)."
       }
     },
     "color": {
@@ -1434,7 +1448,44 @@
     },
     "space": {
       "$type": "dimension",
-      "$description": "Semantic spacing tiers: subgrid, component, layout, section.",
+      "$description": "Semantic spacing tiers: subgrid, component, layout, section, scale.",
+      "scale": {
+        "$description": "hds#206 — the canonical spacing vocabulary. One monotonic, single-family t-shirt scale (xs < sm < md < lg < xl) for the `p`/`m`/`gap` family of props on Box/Stack. Supersedes the four un-ordered gap families below (subgrid/component/layout/section) and the 24px alias triplet (layout.normal / layout.gutter / component.padding) for NEW usage; those remain live, deprecated aliases until the consumer codemod (hds#206 remaining work) migrates callers and removes them — not a breaking change yet.",
+        "xs": {
+          "$value": "{primitive.space.2}",
+          "$description": "8px — smallest step. Same value as component.gap (deprecated alias)."
+        },
+        "sm": {
+          "$value": "{primitive.space.4}",
+          "$description": "16px — same value as layout.tight (deprecated alias)."
+        },
+        "md": {
+          "$value": "{primitive.space.6}",
+          "$description": "24px — same value as layout.normal (deprecated alias). Default of the overridable roles surface.padding and region.gutter, which replace the deprecated component.padding / layout.gutter."
+        },
+        "lg": {
+          "$value": "{primitive.space.8}",
+          "$description": "32px — same value as layout.inset (deprecated alias)."
+        },
+        "xl": {
+          "$value": "{primitive.space.12}",
+          "$description": "48px — same value as layout.spacious (deprecated alias)."
+        }
+      },
+      "surface": {
+        "$description": "hds#206 — the overridable surface inset. A named role on the t-shirt scale rather than a scale step, because tenants (per brand and density) override it at runtime; its value is always a scale step.",
+        "padding": {
+          "$value": "{semantic.space.scale.md}",
+          "$description": "24px (scale.md) default inset for cards, forms, panels, and grouped surfaces. Tenants override it with another scale step (tenants/*/tokens.json, incl. a Compact density mode). Replaces the deprecated semantic.space.component.padding."
+        }
+      },
+      "region": {
+        "$description": "hds#206 — the overridable region gutter. A named role on the t-shirt scale rather than a scale step, because theme.css retunes it per viewport; its value is always a scale step.",
+        "gutter": {
+          "$value": "{semantic.space.scale.md}",
+          "$description": "24px (scale.md) column and region gutters. theme.css sets it responsively to scale.lg (32px) and, below 640px, scale.sm (16px). Replaces the deprecated semantic.space.layout.gutter."
+        }
+      },
       "subgrid": {
         "hairline": {
           "$value": "{primitive.space.px1}",
@@ -1452,37 +1503,44 @@
       "component": {
         "gap": {
           "$value": "{primitive.space.2}",
-          "$description": "8px label↔input rhythm and closely coupled control spacing."
+          "$description": "8px label↔input rhythm and closely coupled control spacing. DEPRECATED alias (hds#206) — use semantic.space.scale.xs; kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.scale.xs"
         },
         "medium": {
           "$value": "{primitive.space.3}",
           "$description": "12px adjacent form fields and medium intra-component gaps."
         },
         "padding": {
-          "$value": "{primitive.space.6}",
-          "$description": "24px default inset for cards, forms, panels, and grouped surfaces."
+          "$value": "{semantic.space.surface.padding}",
+          "$description": "24px default inset for cards, forms, panels, and grouped surfaces. DEPRECATED alias (hds#206) — use semantic.space.surface.padding (tenant/density-overridable); kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.surface.padding"
         }
       },
       "layout": {
         "tight": {
           "$value": "{primitive.space.4}",
-          "$description": "16px default HdsStack gap and inter-component spacing."
+          "$description": "16px default HdsStack gap and inter-component spacing. DEPRECATED alias (hds#206) — use semantic.space.scale.sm; kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.scale.sm"
         },
         "normal": {
           "$value": "{primitive.space.6}",
-          "$description": "24px column gutters and sidebar gutter spacing."
+          "$description": "24px column gutters and sidebar gutter spacing. DEPRECATED alias (hds#206) — use semantic.space.scale.md; kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.scale.md"
         },
         "gutter": {
-          "$value": "{primitive.space.6}",
-          "$description": "24px column and region gutters (alias for layout.normal)."
+          "$value": "{semantic.space.region.gutter}",
+          "$description": "24px column and region gutters. DEPRECATED alias (hds#206) — use semantic.space.region.gutter (responsive in theme.css); kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.region.gutter"
         },
         "inset": {
           "$value": "{primitive.space.8}",
-          "$description": "32px major block separation and inset inter-component gaps."
+          "$description": "32px major block separation and inset inter-component gaps. DEPRECATED alias (hds#206) — use semantic.space.scale.lg; kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.scale.lg"
         },
         "spacious": {
           "$value": "{primitive.space.12}",
-          "$description": "48px section break and whitespace separator between major content blocks."
+          "$description": "48px section break and whitespace separator between major content blocks. DEPRECATED alias (hds#206) — use semantic.space.scale.xl; kept live, no removal yet.",
+          "$deprecated": "hds#206 — use semantic.space.scale.xl"
         }
       },
       "section": {
@@ -1587,28 +1645,28 @@
       "display": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.5xl}",
+          "fontSize": "{primitive.typography.size.6xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
           "lineHeight": "{primitive.typography.lineHeight.none}"
         },
-        "$description": "Display headline. 72px / Satoshi bold 700 / leading-none.",
+        "$description": "Display headline. 60px / Satoshi bold 700 / leading-none (hds#283: was 72px/5xl).",
         "$extensions": {
           "com.figma.variables": {
-            "fontSize": "clamp(40px, 8vw, 72px)",
-            "note": "Figma stores the 72px desktop-max static value. Browser CSS overrides with fluid scaling (40px min → 72px max). See src/styles/theme.css."
+            "fontSize": "clamp(40px, 8vw, 60px)",
+            "note": "Figma stores the 60px desktop-max static value. Browser CSS overrides with fluid scaling (40px min → 60px max). See src/styles/theme.css."
           }
         }
       },
       "h1": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.4xl}",
+          "fontSize": "{primitive.typography.size.5xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
           "lineHeight": "{primitive.typography.lineHeight.tight}"
         },
-        "$description": "Primary section headings (h1). 48px / Satoshi bold 700 / leading-tight.",
+        "$description": "Primary section headings (h1). 48px / Satoshi bold 700 / leading-tight (hds#283: rung renamed 4xl→5xl, px unchanged).",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(32px, 6vw, 48px)",
@@ -1619,12 +1677,12 @@
       "h2": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.2xl}",
+          "fontSize": "{primitive.typography.size.3xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
-          "lineHeight": "42px"
+          "lineHeight": "40px"
         },
-        "$description": "Secondary section headings (h2). Satoshi bold 700, 30px, line-height 42px.",
+        "$description": "Secondary section headings (h2). Satoshi bold 700, 30px, line-height 40px (hds#283: rung renamed, was 42px).",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(24px, 3.5vw, 30px)",
@@ -1635,12 +1693,12 @@
       "h3": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.lg}",
+          "fontSize": "{primitive.typography.size.xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
           "lineHeight": "28px"
         },
-        "$description": "Component and card headers (h3). 20px / Satoshi bold 700 500 / leading-snug.",
+        "$description": "Component and card headers (h3). 20px / Satoshi bold 700 500 / leading-snug (hds#283: rung renamed lg→xl, px unchanged).",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(18px, 2vw, 20px)",
@@ -1654,13 +1712,13 @@
           "fontSize": "{primitive.typography.size.base}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "28px",
+          "lineHeight": "24px",
           "maxWidth": {
             "value": 60,
             "unit": "ch"
           }
         },
-        "$description": "Body prose. Satoshi medium, 17px, line-height 28px, max 60ch measure."
+        "$description": "Body prose. Satoshi medium, 16px, line-height 24px, max 60ch measure (hds#283: was 17px/28px)."
       },
       "ui": {
         "$value": {
@@ -1668,26 +1726,23 @@
           "fontSize": "{primitive.typography.size.sm}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "24px",
+          "lineHeight": "20px",
           "maxWidth": {
             "value": 60,
             "unit": "ch"
           }
         },
-        "$description": "UI text for nav, labels, captions. Satoshi medium, 15px, line-height 24px."
+        "$description": "UI text for nav, labels, captions. Satoshi medium, 14px, line-height 20px (hds#283: was 15px/24px)."
       },
       "caption": {
         "$value": {
           "fontFamily": "{primitive.typography.family.primary}",
-          "fontSize": {
-            "value": 12,
-            "unit": "px"
-          },
+          "fontSize": "{primitive.typography.size.xs}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
           "lineHeight": "16px"
         },
-        "$description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style."
+        "$description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style; now sourced from primitive.xs (hds#283)."
       },
       "eyebrow": {
         "$value": {
@@ -1695,15 +1750,15 @@
           "fontSize": "{primitive.typography.size.xs}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.caps}",
-          "lineHeight": "20px",
+          "lineHeight": "16px",
           "textTransform": "uppercase"
         },
-        "$description": "Eyebrow / kicker label. Satoshi medium, 13px, caps tracking, uppercase."
+        "$description": "Eyebrow / kicker label. Satoshi medium, 12px, caps tracking, uppercase (hds#283: was 13px/20px)."
       },
       "mono": {
         "$value": {
           "fontFamily": "{primitive.typography.family.mono}",
-          "fontSize": "{primitive.typography.size.xs}",
+          "fontSize": "{primitive.typography.size.sm}",
           "fontWeight": "{primitive.typography.weight.regular}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
           "lineHeight": "20px",
@@ -1712,7 +1767,7 @@
             "unit": "ch"
           }
         },
-        "$description": "Monospace for code, token names, shortcuts. Geist Mono regular, 13px."
+        "$description": "Monospace for code, token names, shortcuts. Geist Mono regular, 14px (hds#283: repointed xs→sm; xs alone would give 12px)."
       },
       "lineHeight": {
         "none": {
@@ -1844,6 +1899,11 @@
         "$type": "dimension",
         "$value": "{primitive.radius.8}",
         "$description": "Corner radius for action elements (buttons, inputs, badges); Tailwind rounded-md resolves here. Override role.radius to reshape the system."
+      },
+      "control": {
+        "$type": "dimension",
+        "$value": "{primitive.radius.4}",
+        "$description": "Corner radius for small interactive control glyphs (e.g. checkbox glyph box) that are not fully round and not the standard action radius. Real design-scale value, distinct from semantic.radius.action (hds#242)."
       }
     },
     "borderWidth": {
@@ -1907,6 +1967,67 @@
         },
         "$description": "Modal, dialog, and drawer elevation."
       }
+    },
+    "size": {
+      "$type": "dimension",
+      "$description": "Semantic sizing roles for control glyphs, avatars, and table rows. Distinct roles may share a primitive value today by coincidence; keep them separate so one can change without dragging the other (hds#242).",
+      "control": {
+        "$description": "Interactive control glyph/element sizing (checkbox glyph box, radio dot, slider track/fill, code-block copy-button-matched footprint).",
+        "sm": {
+          "$value": "{primitive.size.8}",
+          "$description": "Small control element — radio dot, slider fill bar height."
+        },
+        "md": {
+          "$value": "{primitive.size.20}",
+          "$description": "Medium control element — checkbox glyph box, slider track wrapper height."
+        },
+        "lg": {
+          "$value": "{primitive.size.32}",
+          "$description": "Large control footprint — code-block inline-wrapper min-height / copy-button-matched pre padding."
+        }
+      },
+      "icon": {
+        "$description": "Reserved icon-size role, parallel to the existing --hds-icon-* bridge (src/styles/theme.css), for future direct semantic.size.icon consumers.",
+        "sm": {
+          "$value": "{primitive.size.16}",
+          "$description": "Small icon box — matches --hds-icon-small."
+        },
+        "md": {
+          "$value": "{primitive.size.20}",
+          "$description": "Medium icon box — matches --hds-icon-medium."
+        },
+        "lg": {
+          "$value": "{primitive.size.24}",
+          "$description": "Large icon box — matches --hds-icon-large."
+        }
+      },
+      "avatar": {
+        "$value": "{primitive.size.40}",
+        "$description": "Avatar diagonal (width/height) for activity-feed and similar identity glyphs. Coincides in pixels with row.compact today; kept as a separate role per hds#242 so either can change independently."
+      },
+      "row": {
+        "$description": "Table row minimum height by density.",
+        "compact": {
+          "$value": "{primitive.size.40}",
+          "$description": "Compact-density row minimum height."
+        },
+        "comfortable": {
+          "$value": "{primitive.size.48}",
+          "$description": "Comfortable-density row minimum height."
+        }
+      }
+    },
+    "zIndex": {
+      "$type": "number",
+      "$description": "Named stacking layers, aliasing the numeric primitive.zIndex scale (hds#242).",
+      "control": {
+        "$value": "{primitive.zIndex.10}",
+        "$description": "Raises an interactive control (e.g. a native range input) above its visual decoration for hit-testing."
+      },
+      "sticky": {
+        "$value": "{primitive.zIndex.100}",
+        "$description": "Sticky-positioned elements, such as a table header row."
+      }
     }
   },
   "component": {
@@ -2130,7 +2251,7 @@
           "fontSize": {
             "$type": "dimension",
             "$value": "{primitive.typography.size.xs}",
-            "$description": "Small button label size (13px)."
+            "$description": "Small button label size (12px, hds#283: was 13px)."
           },
           "iconSize": {
             "$type": "dimension",
@@ -2162,7 +2283,7 @@
           "fontSize": {
             "$type": "dimension",
             "$value": "{primitive.typography.size.sm}",
-            "$description": "Medium button label size (15px)."
+            "$description": "Medium button label size (14px, hds#283: was 15px)."
           },
           "iconSize": {
             "$type": "dimension",
@@ -2194,7 +2315,7 @@
           "fontSize": {
             "$type": "dimension",
             "$value": "{primitive.typography.size.base}",
-            "$description": "Large button label size (17px)."
+            "$description": "Large button label size (16px, hds#283: was 17px)."
           },
           "iconSize": {
             "$type": "dimension",