react-native-terra-ui 0.13.2 → 0.13.4

package/src/theme/tokens/primitives.ts

@@ -375,102 +375,108 @@ export const primitives = {
   // are not physical pixels. Pass them directly to Text without multiplying
   // by PixelRatio or fontScale (native Text handles accessibility scaling).
   // Each role pairs fontSize with an absolute lineHeight, not a ratio.
-  // Line heights use a 4-unit grid; font sizes need not follow that grid.
   //
-  // Font size / line height, listed from lg to sm:
-  // display:  40/48, 36/44, 32/40 — short, prominent hero text.
-  // headline: 28/36, 24/32, 22/28 — page and section headings.
-  // title:    20/28, 18/24, 16/24 — card, list, and navigation titles.
-  // body:     18/28, 16/24, 14/20 — reading text; body-md is Text's default.
-  // label:    16/20, 14/20, 12/16 — short control labels, not paragraphs.
-  // caption:  12/16              — brief supplementary text.
-  // Prefer body sizes for essential information; reserve 12 for compact text.
-  // These are Terra's custom roles, not native platform text-style presets.
+  // Sizes follow the iOS text styles at the Default (Large) Dynamic Type size,
+  // and the role names follow iOS too, so `headline` is the 17pt semibold a
+  // navigation bar or table cell title uses and `large-title` is the 34pt
+  // bold large title. Line heights are the iOS values rounded to an even
+  // number. Weights are what UIKit renders in practice (bold titles), not the
+  // "Regular" the HIG table lists. Tracking is left to the font: SF carries
+  // its own, and a configured custom family can set `letterSpacing` per role.
+  //
+  // Font size / line height:
+  // display:      40/48 — hero text, no iOS equivalent.
+  // large-title:  34/40 — iOS Large Title.
+  // title-1/2/3:  28/34, 22/28, 20/24 — iOS Title 1, Title 2, Title 3.
+  // headline:     17/22 semibold — iOS Headline; compact header bar title.
+  // body:         17/22 — iOS Body; Text's default.
+  // callout:      16/20 — iOS Callout.
+  // subheadline:  15/20 — iOS Subheadline.
+  // footnote:     13/18 — iOS Footnote.
+  // caption-1/2:  12/16, 11/14 — iOS Caption 1, Caption 2.
+  // label-lg/md/sm: 16/20, 15/20, 13/16 medium — control labels; no iOS role.
   //
   // maxFontSizeMultiplier limits accessibility enlargement when scaling is
-  // enabled. The caps below are layout tradeoffs, not accessibility targets.
+  // enabled. Reading roles cap at 2 so text still meets WCAG 1.4.4 at the OS's
+  // 200% setting. Titles cap at 1.5 (iOS itself scales Large Title to 1.76x at
+  // most) and labels at 1.6 because toolbars and chips have fixed heights.
   // RN uses 0 for no cap; Terra Text also accepts a per-instance override.
   // Validate wrapping and clipping at large OS text sizes and with custom fonts.
-  "typography.variants.display-lg.fontSize": 40,
-  "typography.variants.display-lg.lineHeight": 48,
-  "typography.variants.display-lg.fontWeight": "bold",
-  "typography.variants.display-lg.letterSpacing": -1,
-  "typography.variants.display-lg.maxFontSizeMultiplier": 1.2,
-  "typography.variants.display-md.fontSize": 36,
-  "typography.variants.display-md.lineHeight": 44,
-  "typography.variants.display-md.fontWeight": "bold",
-  "typography.variants.display-md.letterSpacing": -0.8,
-  "typography.variants.display-md.maxFontSizeMultiplier": 1.2,
-  "typography.variants.display-sm.fontSize": 32,
-  "typography.variants.display-sm.lineHeight": 40,
-  "typography.variants.display-sm.fontWeight": "bold",
-  "typography.variants.display-sm.letterSpacing": -0.5,
-  "typography.variants.display-sm.maxFontSizeMultiplier": 1.2,
-  "typography.variants.headline-lg.fontSize": 28,
-  "typography.variants.headline-lg.lineHeight": 36,
-  "typography.variants.headline-lg.fontWeight": "semibold",
-  "typography.variants.headline-lg.letterSpacing": -0.3,
-  "typography.variants.headline-lg.maxFontSizeMultiplier": 1.3,
-  "typography.variants.headline-md.fontSize": 24,
-  "typography.variants.headline-md.lineHeight": 32,
-  "typography.variants.headline-md.fontWeight": "semibold",
-  "typography.variants.headline-md.letterSpacing": -0.2,
-  "typography.variants.headline-md.maxFontSizeMultiplier": 1.3,
-  "typography.variants.headline-sm.fontSize": 22,
-  "typography.variants.headline-sm.lineHeight": 28,
-  "typography.variants.headline-sm.fontWeight": "semibold",
-  "typography.variants.headline-sm.letterSpacing": -0.1,
-  "typography.variants.headline-sm.maxFontSizeMultiplier": 1.3,
-  "typography.variants.title-lg.fontSize": 20,
-  "typography.variants.title-lg.lineHeight": 28,
-  "typography.variants.title-lg.fontWeight": "semibold",
-  "typography.variants.title-lg.letterSpacing": 0,
-  "typography.variants.title-lg.maxFontSizeMultiplier": 1.4,
-  "typography.variants.title-md.fontSize": 18,
-  "typography.variants.title-md.lineHeight": 24,
-  "typography.variants.title-md.fontWeight": "semibold",
-  "typography.variants.title-md.letterSpacing": 0,
-  "typography.variants.title-md.maxFontSizeMultiplier": 1.4,
-  "typography.variants.title-sm.fontSize": 16,
-  "typography.variants.title-sm.lineHeight": 24,
-  "typography.variants.title-sm.fontWeight": "semibold",
-  "typography.variants.title-sm.letterSpacing": 0,
-  "typography.variants.title-sm.maxFontSizeMultiplier": 1.4,
-  "typography.variants.body-lg.fontSize": 18,
-  "typography.variants.body-lg.lineHeight": 28,
-  "typography.variants.body-lg.fontWeight": "regular",
-  "typography.variants.body-lg.letterSpacing": 0,
-  "typography.variants.body-lg.maxFontSizeMultiplier": 1.8,
-  "typography.variants.body-md.fontSize": 16,
-  "typography.variants.body-md.lineHeight": 24,
-  "typography.variants.body-md.fontWeight": "regular",
-  "typography.variants.body-md.letterSpacing": 0,
-  "typography.variants.body-md.maxFontSizeMultiplier": 1.8,
-  "typography.variants.body-sm.fontSize": 14,
-  "typography.variants.body-sm.lineHeight": 20,
-  "typography.variants.body-sm.fontWeight": "regular",
-  "typography.variants.body-sm.letterSpacing": 0,
-  "typography.variants.body-sm.maxFontSizeMultiplier": 1.8,
+  "typography.variants.display.fontSize": 40,
+  "typography.variants.display.lineHeight": 48,
+  "typography.variants.display.fontWeight": "bold",
+  "typography.variants.display.letterSpacing": -0.3,
+  "typography.variants.display.maxFontSizeMultiplier": 1.3,
+  "typography.variants.large-title.fontSize": 34,
+  "typography.variants.large-title.lineHeight": 40,
+  "typography.variants.large-title.fontWeight": "bold",
+  "typography.variants.large-title.letterSpacing": -0.3,
+  "typography.variants.large-title.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-1.fontSize": 28,
+  "typography.variants.title-1.lineHeight": 34,
+  "typography.variants.title-1.fontWeight": "bold",
+  "typography.variants.title-1.letterSpacing": 0,
+  "typography.variants.title-1.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-2.fontSize": 22,
+  "typography.variants.title-2.lineHeight": 28,
+  "typography.variants.title-2.fontWeight": "bold",
+  "typography.variants.title-2.letterSpacing": 0,
+  "typography.variants.title-2.maxFontSizeMultiplier": 1.5,
+  "typography.variants.title-3.fontSize": 20,
+  "typography.variants.title-3.lineHeight": 24,
+  "typography.variants.title-3.fontWeight": "semibold",
+  "typography.variants.title-3.letterSpacing": 0,
+  "typography.variants.title-3.maxFontSizeMultiplier": 1.5,
+  "typography.variants.headline.fontSize": 17,
+  "typography.variants.headline.lineHeight": 22,
+  "typography.variants.headline.fontWeight": "semibold",
+  "typography.variants.headline.letterSpacing": 0,
+  "typography.variants.headline.maxFontSizeMultiplier": 2,
+  "typography.variants.body.fontSize": 17,
+  "typography.variants.body.lineHeight": 22,
+  "typography.variants.body.fontWeight": "regular",
+  "typography.variants.body.letterSpacing": 0,
+  "typography.variants.body.maxFontSizeMultiplier": 2,
+  "typography.variants.callout.fontSize": 16,
+  "typography.variants.callout.lineHeight": 20,
+  "typography.variants.callout.fontWeight": "regular",
+  "typography.variants.callout.letterSpacing": 0,
+  "typography.variants.callout.maxFontSizeMultiplier": 2,
+  "typography.variants.subheadline.fontSize": 15,
+  "typography.variants.subheadline.lineHeight": 20,
+  "typography.variants.subheadline.fontWeight": "regular",
+  "typography.variants.subheadline.letterSpacing": 0,
+  "typography.variants.subheadline.maxFontSizeMultiplier": 2,
+  "typography.variants.footnote.fontSize": 13,
+  "typography.variants.footnote.lineHeight": 18,
+  "typography.variants.footnote.fontWeight": "regular",
+  "typography.variants.footnote.letterSpacing": 0,
+  "typography.variants.footnote.maxFontSizeMultiplier": 2,
+  "typography.variants.caption-1.fontSize": 12,
+  "typography.variants.caption-1.lineHeight": 16,
+  "typography.variants.caption-1.fontWeight": "regular",
+  "typography.variants.caption-1.letterSpacing": 0,
+  "typography.variants.caption-1.maxFontSizeMultiplier": 2,
+  "typography.variants.caption-2.fontSize": 11,
+  "typography.variants.caption-2.lineHeight": 14,
+  "typography.variants.caption-2.fontWeight": "regular",
+  "typography.variants.caption-2.letterSpacing": 0,
+  "typography.variants.caption-2.maxFontSizeMultiplier": 2,
   "typography.variants.label-lg.fontSize": 16,
   "typography.variants.label-lg.lineHeight": 20,
   "typography.variants.label-lg.fontWeight": "medium",
-  "typography.variants.label-lg.letterSpacing": 0.1,
-  "typography.variants.label-lg.maxFontSizeMultiplier": 1.5,
-  "typography.variants.label-md.fontSize": 14,
+  "typography.variants.label-lg.letterSpacing": 0,
+  "typography.variants.label-lg.maxFontSizeMultiplier": 1.6,
+  "typography.variants.label-md.fontSize": 15,
   "typography.variants.label-md.lineHeight": 20,
   "typography.variants.label-md.fontWeight": "medium",
-  "typography.variants.label-md.letterSpacing": 0.1,
-  "typography.variants.label-md.maxFontSizeMultiplier": 1.5,
-  "typography.variants.label-sm.fontSize": 12,
+  "typography.variants.label-md.letterSpacing": 0,
+  "typography.variants.label-md.maxFontSizeMultiplier": 1.6,
+  "typography.variants.label-sm.fontSize": 13,
   "typography.variants.label-sm.lineHeight": 16,
   "typography.variants.label-sm.fontWeight": "medium",
-  "typography.variants.label-sm.letterSpacing": 0.2,
-  "typography.variants.label-sm.maxFontSizeMultiplier": 1.5,
-  "typography.variants.caption.fontSize": 12,
-  "typography.variants.caption.lineHeight": 16,
-  "typography.variants.caption.fontWeight": "regular",
-  "typography.variants.caption.letterSpacing": 0.2,
-  "typography.variants.caption.maxFontSizeMultiplier": 2,
+  "typography.variants.label-sm.letterSpacing": 0,
+  "typography.variants.label-sm.maxFontSizeMultiplier": 1.6,
 
   // ── component opacity multipliers ─────────────────────────────────────────────────
   "opacity.disabled": 0.45,

package/src/theme/types.ts

@@ -64,6 +64,30 @@ export type ElevationScale = Record<ElevationKey, ElevationStyle>;
 // ─── Typography ──────────────────────────────────────────────────────────────
 
 export type RoleTextVariant =
+  | "display"
+  | "large-title"
+  | "title-1"
+  | "title-2"
+  | "title-3"
+  | "headline"
+  | "body"
+  | "callout"
+  | "subheadline"
+  | "footnote"
+  | "caption-1"
+  | "caption-2"
+  | "label-lg"
+  | "label-md"
+  | "label-sm";
+
+export type HeadingTextVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+/**
+ * Pre-0.14 role names. Still accepted by `Text` and resolved onto the iOS-style
+ * scale; removed at 1.0. `label-*` kept its name and is not listed here.
+ * @deprecated Use the {@link RoleTextVariant} it maps to.
+ */
+export type LegacyTextVariant =
   | "display-lg"
   | "display-md"
   | "display-sm"
@@ -76,14 +100,9 @@ export type RoleTextVariant =
   | "body-lg"
   | "body-md"
   | "body-sm"
-  | "label-lg"
-  | "label-md"
-  | "label-sm"
   | "caption";
 
-export type HeadingTextVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
-
-export type TextVariant = RoleTextVariant | HeadingTextVariant;
+export type TextVariant = RoleTextVariant | HeadingTextVariant | LegacyTextVariant;
 
 export type FontWeightToken = "regular" | "medium" | "semibold" | "bold";