@hirobius/design-system 0.15.0 → 0.17.0

package/hirobius.tokens.json

@@ -495,89 +495,85 @@
       },
       "size": {
         "$type": "dimension",
-        "2xs": {
-          "$value": {
-            "value": 10,
-            "unit": "px"
-          }
-        },
         "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": {
         "$type": "fontWeight",
-        "light": {
-          "$value": 300,
-          "$description": "Swiss-canon heading weight. Display and h1/h2 composites only."
-        },
         "regular": {
           "$value": 400
         },
         "medium": {
           "$value": 500
         },
-        "semibold": {
-          "$value": 600
-        },
         "bold": {
           "$value": 700
         }
@@ -607,12 +603,6 @@
       },
       "letterSpacing": {
         "$type": "dimension",
-        "tighter": {
-          "$value": {
-            "value": -0.02,
-            "unit": "em"
-          }
-        },
         "tight": {
           "$value": {
             "value": -0.01,
@@ -625,18 +615,6 @@
             "unit": "em"
           }
         },
-        "wide": {
-          "$value": {
-            "value": 0.01,
-            "unit": "em"
-          }
-        },
-        "wider": {
-          "$value": {
-            "value": 0.02,
-            "unit": "em"
-          }
-        },
         "caps": {
           "$value": {
             "value": 0.06,
@@ -862,6 +840,14 @@
             "unit": "px"
           },
           "$description": "Minimum interactive hit target size."
+        },
+        "minCompact": {
+          "$type": "dimension",
+          "$value": {
+            "value": 24,
+            "unit": "px"
+          },
+          "$description": "WCAG 2.2 AA (2.5.8) minimum target size for a compact inline control, such as a tokenizer chip's remove button, where the 44px AAA floor (2.5.5) does not apply."
         }
       },
       "width": {
@@ -893,6 +879,14 @@
             "value": 50,
             "unit": "ch"
           }
+        },
+        "280": {
+          "$type": "dimension",
+          "$value": {
+            "value": 280,
+            "unit": "px"
+          },
+          "$description": "Docs-shell rail width (hds#280). Our own number, not HeroUI's 268px — wide enough for the longest top-level nav label at the default type ramp with room to spare."
         }
       }
     },
@@ -983,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": {
@@ -1449,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}",
@@ -1467,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": {
@@ -1530,6 +1573,11 @@
         "railPadding": {
           "$value": "{primitive.space.5}",
           "$description": "20px outer padding for sidebar and TOC rails."
+        },
+        "railWidth": {
+          "$type": "dimension",
+          "$value": "{primitive.size.width.280}",
+          "$description": "Docs-shell left nav rail and right TOC rail width (hds#280). Both rails share one width token; default 0 below their breakpoint (see HdsDocsShell)."
         }
       }
     },
@@ -1597,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)",
@@ -1629,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)",
@@ -1645,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)",
@@ -1664,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": {
@@ -1678,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": {
@@ -1705,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",
@@ -1722,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": {
@@ -1854,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": {
@@ -1917,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": {
@@ -2140,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",
@@ -2172,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",
@@ -2204,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",