@putdotio/design 4.0.0 → 5.0.0

package/DESIGN.md

@@ -24,12 +24,12 @@ typography:
   ui:
     family: '"GT America", sans-serif'
     weight: 400
-    size: "1rem"
+    size: "0.875rem"
     lineHeight: 1.45
   display:
     family: '"GT America", sans-serif'
     weight: 900
-    size: "96px"
+    size: "6rem"
     lineHeight: 1.1
   mono:
     family: '"Berkeley Mono", monospace'
@@ -89,7 +89,8 @@ Tier 1, 3, and 4 cards are Components (put.io owns the recipe); tier 2 cards are
 - Berkeley Mono is the one mono face: numerics, timestamps, sizes, ETAs, counts, code, logs, identifiers, hashes, magnet URIs, filenames. Columns of numbers add `font-variant-numeric: tabular-nums`.
 - TV product UI has no mono face (a debug overlay may use the platform's system monospace): 10-foot numerics use GT America `tnum`. Platforms without OpenType feature selection (Roku: `Font` takes only `uri` and `size`) get proportional figures, so budget timecodes for reflow (`1` is 399/1000 em, `0` is 636).
 - GT America is Latin only (523 codepoints, Western and Central European plus Turkish, no dingbats such as `✓` `▶` `★`). Symbols are icons. Text that can hold a filename keeps a fallback family; web falls back per glyph, while one-font-per-label platforms must ship a fallback or render `.notdef` boxes.
-- Root font-size is 14px, 15px from `--bp-lg`. Body, labels, inputs: `--fs-base`. Captions, button labels: `--fs-sm`. Screen titles and one-time-code digits: `--fs-title`, the fixed-pixel sibling of H2's `--fs-lg`, which scales with the root. Titles sit on a 30px line with `--tracking-snug`; the code separator is 18px. `--fs-title`, `--fs-2xl`, `--fs-3xl`, `--fs-display` are fixed pixels.
+- The root is the browser default, `100%` (16px), so text follows the reader's setting. Components choose a text role, not a size step: `--fs-ui` (14px) for UI chrome (labels, buttons, nav, links, errors), `--fs-body` (16px) for body and long text, `--fs-caption` (12px) for captions, and `--fs-field` (16px) for typed text, which keeps iOS Safari from zooming on focus.
+- The steps are rem on Tailwind's 16px scale: `--fs-xs` 12px, `--fs-sm` 14, `--fs-base` 16, `--fs-md` 18, `--fs-lg` 24, `--fs-xl` 32, `--fs-2xl` 48, `--fs-3xl` 64, `--fs-display` 96. Screen titles and one-time-code digits take `--fs-title` (22px) on a 30px line with `--tracking-snug`; the code separator is `--fs-md`.
 
 ## Layout & Spacing
 
@@ -133,16 +134,17 @@ Default radius `6px`; `4px` for tight controls, `8px` or `10px` for panels, pill
 
 ### Auth
 
-- Sign in, sign up, password reset, and two-factor pages have no card or panel: the form sits on `--bg`. Recipe: `.auth-page`, `.auth-header`, `.auth-main`, `.auth-column`, `.auth-title`, `.auth-links`, `.auth-footer`.
+- Sign in, sign up, password reset, and two-factor pages have no card or panel: the form sits on `--bg`. Recipe: `.auth-page`, `.auth-header`, `.auth-main`, `.auth-column`, `.auth-title`, `.auth-note`, `.auth-links`, `.auth-footer`.
 - The logo sits top-left in the header, in a `30.33px` box (26px ink × 7/6). The top right stays empty by default.
 - One left-aligned column, up to `340px`, is centred horizontally and optically centred vertically: the form's middle sits near 45% of the viewport height, never below the true middle.
-- A quiet centred footer links Terms of Service, Privacy Policy, and Help in muted `--fs-sm`.
+- A quiet centred footer links Terms of Service, Privacy Policy, and Help in muted `--fs-ui`.
+- Text is one size: everything except the title and fields is `--fs-ui`. That covers labels, hints, `.auth-note` lines, errors, the link row, and the footer. Fields take `--fs-field`.
 - One title per screen: `--fs-title` (`22px`), medium, `--tracking-snug` (`-0.01em`). No subtitles, taglines, or marketing lines; copy stays short.
 - Fields and buttons keep the standard 36px box: the filled field and a full-width default-size primary.
 - Labels are small, muted, and above the field.
 - The primary button is full-width yellow. Secondary actions sit under the form as muted text links: “Forgot password?”, “New to put.io? Sign up”, “Wrong account? Sign out”.
 - Tab order runs fields, submit, then secondary links; DOM order follows visual order, with no positive `tabindex`. Two-factor runs the code, Verify, then its links. The reveal-password toggle takes `tabindex="-1"` and keeps its accessible name: keyboard-only users can't toggle visibility, screen-reader users still can in browse mode. No link leaves the tab order.
-- Form errors: one message in a `.form-reveal` row right above the submit button, in red `--fs-base` text. Invalid fields turn red. Auth forms never use the boxed `.form-callout`.
+- Form errors: one message in a `.form-reveal` row right above the submit button, in red `--fs-ui` text, 8px under the fields. Invalid fields turn red. Auth forms never use the boxed `.form-callout`.
 - Copy: “Sign in”, “Sign up”, and “That username or password doesn't look right.”
 - auth.put.io still ships the older card layout: drift.
 - References: `web-s06-auth`, `web-p00c-auth-signin`, `web-p00d-auth-signup`, `web-p00e-auth-2fa`. Outside references: the TIDAL, Stripe Link, Cursor, Linear, and Vercel sign-in pages.

package/dist/css/tailwind.css

@@ -250,6 +250,14 @@
   --text-4xl--line-height: initial;
   --text-display: var(--fs-display);
   --text-display--line-height: initial;
+  --text-ui: var(--fs-ui);
+  --text-ui--line-height: initial;
+  --text-body: var(--fs-body);
+  --text-body--line-height: initial;
+  --text-caption: var(--fs-caption);
+  --text-caption--line-height: initial;
+  --text-field: var(--fs-field);
+  --text-field--line-height: initial;
 
   --leading-tight: var(--lh-tight);
   --leading-snug: var(--lh-snug);

package/dist/css/tokens.css

@@ -265,12 +265,12 @@
   --fs-base: 1rem;
   --fs-md: 1.125rem;
   --fs-lg: 1.5rem;
-  --fs-title: 22px;
+  --fs-title: 1.375rem;
   --fs-xl: 2rem;
-  --fs-2xl: 48px;
-  --fs-3xl: 64px;
-  --fs-4xl: 64px;
-  --fs-display: 96px;
+  --fs-2xl: 3rem;
+  --fs-3xl: 4rem;
+  --fs-4xl: 4rem;
+  --fs-display: 6rem;
   --lh-tight: 1.1;
   --lh-snug: 1.25;
   --lh-normal: 1.45;
@@ -284,6 +284,10 @@
   --tracking-normal: 0;
   --tracking-wide: 0.02em;
   --tracking-uppercase: 0.08em;
+  --fs-ui: 0.875rem;
+  --fs-body: 1rem;
+  --fs-caption: 0.75rem;
+  --fs-field: 1rem;
   --space-0: 0;
   --space-1: 4px;
   --space-2: 8px;
@@ -521,7 +525,8 @@ html {
   background: var(--html-bg);
   color: var(--text);
   font-family: var(--font-sans);
-  font-size: 14px;  /* app.put.io root: fontSize ["14px","14px","15px"] — 15px at ≥ --bp-lg (media query below) */
+  /* The browser default (16px), so text follows the reader's setting. */
+  font-size: 100%;
   line-height: var(--lh-normal);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
@@ -530,16 +535,10 @@ html {
 body {
   background: var(--app-bg);
   color: var(--text);
+  font-size: var(--fs-body);
   margin: 0;
 }
 
-/* Root steps up on desktop, matching app.put.io's responsive base.
-   14px/15px literals must stay in sync with --bp-lg (media queries
-   can't read custom properties). */
-@media (min-width: 1280px) {
-  html { font-size: 15px; }
-}
-
 /* -- Semantic type ------------------------------------------------- */
 
 .h-display, h1.display {
@@ -600,7 +599,7 @@ h4, .h4 {
 
 p, .body {
   font-family: var(--font-sans);
-  font-size: var(--fs-base);
+  font-size: var(--fs-body);
   font-weight: var(--fw-regular);
   line-height: var(--lh-normal);
   margin: 0 0 var(--space-4);
@@ -614,19 +613,19 @@ p, .body {
 }
 
 small, .caption {
-  font-size: var(--fs-sm);  /* production caption = fontSize 0 */
+  font-size: var(--fs-caption);
   color: var(--text-secondary);
 }
 
 .label {
-  font-size: var(--fs-base);  /* production label = fontSize 1, medium */
+  font-size: var(--fs-ui);
   font-weight: var(--fw-medium);
   color: var(--text);
 }
 
 .button-text {
   font-weight: var(--fw-medium);
-  font-size: var(--fs-sm);  /* production button = fontSize 0 */
+  font-size: var(--fs-ui);
   letter-spacing: 0;
 }
 

package/dist/figma/putio.tokens.json

@@ -890,57 +890,58 @@
     "fontSize": {
       "xs": {
         "$type": "dimension",
-        "$value": "0.75rem"
+        "$value": "0.75rem",
+        "$description": "12px. Captions: read it through --fs-caption."
       },
       "sm": {
         "$type": "dimension",
         "$value": "0.875rem",
-        "$description": "Caption and button labels — production fontSize 0."
+        "$description": "14px. UI chrome (labels, buttons, links, errors): read it through --fs-ui."
       },
       "base": {
         "$type": "dimension",
         "$value": "1rem",
-        "$description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg)."
+        "$description": "16px, the root. Body text and inputs: read it through --fs-body or --fs-field."
       },
       "md": {
         "$type": "dimension",
         "$value": "1.125rem",
-        "$description": "Subheading."
+        "$description": "18px. Subheading."
       },
       "lg": {
         "$type": "dimension",
         "$value": "1.5rem",
-        "$description": "Heading."
+        "$description": "24px. Heading."
       },
       "title": {
         "$type": "dimension",
-        "$value": "22px",
-        "$description": "Screen titles and one-time-code digits. The fixed-pixel sibling of fontSize.lg (H2), which scales with the root."
+        "$value": "1.375rem",
+        "$description": "22px. Screen titles and one-time-code digits, beside fontSize.lg (H2)."
       },
       "xl": {
         "$type": "dimension",
         "$value": "2rem",
-        "$description": "Page title."
+        "$description": "32px. Page title."
       },
       "2xl": {
         "$type": "dimension",
-        "$value": "48px",
-        "$description": "Fixed display tier — does not scale with the responsive root."
+        "$value": "3rem",
+        "$description": "48px. Display tier."
       },
       "3xl": {
         "$type": "dimension",
-        "$value": "64px",
-        "$description": "Fixed display tier — does not scale with the responsive root."
+        "$value": "4rem",
+        "$description": "64px. Display tier."
       },
       "4xl": {
         "$type": "dimension",
-        "$value": "64px",
+        "$value": "4rem",
         "$description": "Compatibility alias for the former 4xl tier; new surfaces should use fontSize.3xl or fontSize.display."
       },
       "display": {
         "$type": "dimension",
-        "$value": "96px",
-        "$description": "Fixed display tier for brand display moments."
+        "$value": "6rem",
+        "$description": "96px. Display tier for brand display moments."
       }
     },
     "lineHeight": {
@@ -1001,6 +1002,28 @@
         "$type": "dimension",
         "$value": "0.08em"
       }
+    },
+    "role": {
+      "ui": {
+        "$type": "dimension",
+        "$value": "0.875rem",
+        "$description": "UI chrome: labels, buttons, nav, links, errors, footers."
+      },
+      "body": {
+        "$type": "dimension",
+        "$value": "1rem",
+        "$description": "Body and long text."
+      },
+      "caption": {
+        "$type": "dimension",
+        "$value": "0.75rem",
+        "$description": "Captions and metadata."
+      },
+      "field": {
+        "$type": "dimension",
+        "$value": "1rem",
+        "$description": "Text a person types into a field. 16px keeps iOS Safari from zooming on focus."
+      }
     }
   },
   "spacing": {

package/dist/tokens.d.ts

@@ -1,6 +1,6 @@
 // Do not edit directly. Generated from tokens/**/*.tokens.json.
 
-export type PutioTokenName = "component.button.primary.background" | "component.button.primary.backgroundHover" | "component.button.primary.backgroundHoverDark" | "component.button.primary.foreground" | "component.button.primary.radius" | "component.button.secondary.background" | "component.button.secondary.backgroundDark" | "component.button.secondary.foreground" | "component.button.secondary.foregroundDark" | "component.button.secondary.backgroundHover" | "component.button.secondary.backgroundHoverDark" | "component.button.success.background" | "component.button.success.backgroundDark" | "component.button.success.backgroundHover" | "component.button.success.backgroundHoverDark" | "component.button.success.foreground" | "component.button.danger.background" | "component.button.danger.backgroundDark" | "component.button.danger.backgroundHover" | "component.button.danger.backgroundHoverDark" | "component.button.danger.foreground" | "component.button.info.background" | "component.button.info.backgroundDark" | "component.button.info.backgroundHover" | "component.button.info.backgroundHoverDark" | "component.button.info.foreground" | "component.button.info.foregroundDark" | "component.button.default.background" | "component.button.default.backgroundDark" | "component.button.default.backgroundHover" | "component.button.default.backgroundHoverDark" | "component.button.default.foreground" | "component.button.default.foregroundDark" | "component.button.ghost.background" | "component.button.ghost.foreground" | "component.button.ghost.foregroundDark" | "component.button.ghost.foregroundHover" | "component.button.ghost.foregroundHoverDark" | "component.button.ghost.backgroundHover" | "component.button.ghost.backgroundHoverDark" | "component.button.height" | "component.button.heightMd" | "component.button.heightSm" | "component.button.heightXs" | "component.button.paddingX" | "component.button.paddingXXs" | "component.button.labelSize" | "component.button.labelSizeXs" | "component.button.tracking" | "component.button.trackingMd" | "component.button.trackingSm" | "component.button.trackingXs" | "component.button.iconSize" | "component.button.gap" | "component.nav.height" | "component.nav.heightCompact" | "component.nav.ctaHeight" | "component.input.background" | "component.input.backgroundDark" | "component.input.border" | "component.input.borderDark" | "component.input.radius" | "component.input.borderHover" | "component.input.borderHoverDark" | "component.input.borderFocus" | "component.input.borderFocusDark" | "component.input.ring" | "component.input.ringDark" | "component.input.text" | "component.input.textDark" | "component.input.placeholder" | "component.input.placeholderDark" | "component.field.background" | "component.field.backgroundDark" | "component.field.backgroundDisabled" | "component.field.backgroundDisabledDark" | "component.field.border" | "component.field.borderDark" | "component.field.borderHover" | "component.field.borderHoverDark" | "component.field.borderFocus" | "component.field.borderFocusDark" | "component.field.text" | "component.field.textDark" | "component.field.placeholder" | "component.field.placeholderDark" | "component.field.radius" | "component.field.ring" | "component.field.ringDark" | "component.panel.background" | "component.panel.backgroundDark" | "component.panel.border" | "component.panel.borderDark" | "component.panel.radius" | "component.panel.shadow" | "component.panel.shadowDark" | "component.alias.background" | "component.alias.backgroundDark" | "component.alias.foreground" | "component.alias.foregroundDark" | "component.alias.foregroundMuted" | "component.alias.foregroundMutedDark" | "component.alias.primary" | "component.alias.primaryForeground" | "component.alias.success" | "component.alias.successDark" | "component.alias.successForeground" | "component.alias.destructive" | "component.alias.destructiveDark" | "component.alias.destructiveForeground" | "component.alias.invertForeground" | "component.alias.invertForegroundDark" | "component.alias.solidForeground" | "component.alias.solidForegroundDark" | "component.alias.muted" | "component.alias.mutedDark" | "component.alias.mutedForeground" | "component.alias.mutedForegroundDark" | "component.alias.accent" | "component.alias.accentDark" | "component.alias.accentForeground" | "component.alias.accentForegroundDark" | "component.alias.card" | "component.alias.cardDark" | "component.alias.cardForeground" | "component.alias.cardForegroundDark" | "component.alias.popover" | "component.alias.popoverDark" | "component.alias.popoverForeground" | "component.alias.popoverForegroundDark" | "component.alias.input" | "component.alias.inputDark" | "component.alias.ring" | "component.fileRow.background" | "component.fileRow.backgroundDark" | "component.fileRow.hoverBackground" | "component.fileRow.hoverBackgroundDark" | "component.fileRow.activeBackground" | "component.fileRow.activeBackgroundDark" | "component.fileRow.border" | "component.fileRow.borderDark" | "component.fileRow.icon" | "component.notification.infoBackground" | "component.notification.infoBackgroundDark" | "component.notification.dangerBackground" | "component.notification.dangerBackgroundDark" | "component.notification.background" | "component.notification.backgroundDark" | "component.notification.border" | "component.notification.borderDark" | "component.notification.foreground" | "component.notification.foregroundDark" | "component.notification.icon" | "component.notification.iconDark" | "component.notification.successBackground" | "component.notification.successBackgroundDark" | "component.notification.successBorder" | "component.notification.successBorderDark" | "component.notification.successForeground" | "component.notification.successForegroundDark" | "component.notification.dangerBorder" | "component.notification.dangerBorderDark" | "component.notification.dangerForeground" | "component.notification.dangerForegroundDark" | "component.notification.badgeBackground" | "component.notification.badgeForeground" | "component.menu.background" | "component.menu.backgroundDark" | "component.menu.border" | "component.menu.borderDark" | "component.menu.radius" | "component.menu.shadow" | "component.menu.shadowDark" | "component.menu.itemBackgroundHover" | "component.menu.itemBackgroundHoverDark" | "component.menu.itemText" | "component.menu.itemTextDark" | "component.menu.itemIcon" | "component.menu.itemIconDark" | "component.menu.itemShortcut" | "component.menu.itemShortcutDark" | "component.menu.itemDangerText" | "component.menu.itemDangerTextDark" | "component.menu.itemDangerBackgroundHover" | "component.menu.itemDangerBackgroundHoverDark" | "component.menu.itemHeight" | "component.menu.separator" | "component.menu.separatorDark" | "component.menu.label" | "component.menu.labelDark" | "component.palette.background" | "component.palette.backgroundDark" | "component.palette.border" | "component.palette.borderDark" | "component.palette.shadow" | "component.palette.shadowDark" | "component.palette.scrim" | "component.palette.scrimDark" | "component.palette.width" | "component.palette.inputHeight" | "component.palette.itemHeight" | "component.palette.itemBackgroundActive" | "component.palette.itemBackgroundActiveDark" | "component.palette.groupLabel" | "component.palette.groupLabelDark" | "component.palette.itemMeta" | "component.palette.itemMetaDark" | "component.sheet.background" | "component.sheet.backgroundDark" | "component.sheet.border" | "component.sheet.borderDark" | "component.sheet.shadow" | "component.sheet.shadowDark" | "component.sheet.scrim" | "component.sheet.scrimDark" | "component.sheet.width" | "component.avatar.yellow" | "component.avatar.green" | "component.avatar.red" | "component.avatar.blue" | "component.avatar.purple" | "component.avatar.teal" | "component.avatar.orange" | "component.avatar.foreground" | "component.avatar.foregroundWarm" | "component.alert.radius" | "component.alert.infoBackground" | "component.alert.infoBackgroundDark" | "component.alert.infoBorder" | "component.alert.infoBorderDark" | "component.alert.infoText" | "component.alert.infoTextDark" | "component.alert.infoBody" | "component.alert.infoBodyDark" | "component.alert.infoIcon" | "component.alert.infoIconDark" | "component.alert.brandBackground" | "component.alert.brandBackgroundDark" | "component.alert.brandBorder" | "component.alert.brandBorderDark" | "component.alert.brandText" | "component.alert.brandTextDark" | "component.alert.brandBody" | "component.alert.brandBodyDark" | "component.alert.brandIcon" | "component.alert.brandIconDark" | "component.alert.successBackground" | "component.alert.successBackgroundDark" | "component.alert.successBorder" | "component.alert.successBorderDark" | "component.alert.successText" | "component.alert.successTextDark" | "component.alert.successBody" | "component.alert.successBodyDark" | "component.alert.successIcon" | "component.alert.successIconDark" | "component.alert.dangerBackground" | "component.alert.dangerBackgroundDark" | "component.alert.dangerBorder" | "component.alert.dangerBorderDark" | "component.alert.dangerText" | "component.alert.dangerTextDark" | "component.alert.dangerBody" | "component.alert.dangerBodyDark" | "component.alert.dangerIcon" | "component.alert.dangerIconDark" | "component.slider.track" | "component.slider.trackDark" | "component.slider.buffer" | "component.slider.bufferDark" | "component.slider.fill" | "component.slider.knob" | "component.slider.fillDisabled" | "component.slider.fillDisabledDark" | "component.slider.trackHeight" | "component.slider.knobSize" | "component.slider.hitHeight" | "component.pagination.itemSize" | "component.pagination.itemText" | "component.pagination.itemTextDark" | "component.pagination.itemTextActive" | "component.pagination.itemTextActiveDark" | "component.pagination.itemBackgroundHover" | "component.pagination.itemBackgroundHoverDark" | "component.pagination.itemBackgroundActive" | "component.pagination.itemBackgroundActiveDark" | "component.pagination.itemBorderActive" | "component.pagination.itemBorderActiveDark" | "context.tv.text.primary" | "context.tv.text.secondary" | "context.tv.text.tertiary" | "context.tv.channelArt.production.posterBackground" | "context.tv.channelArt.production.splashBackground" | "context.tv.channelArt.development.background" | "context.tv.channelArt.development.accent" | "context.tv.channelArt.development.grid" | "context.tv.channelArt.nightly.background" | "context.tv.channelArt.nightly.accent" | "context.tv.channelArt.nightly.star" | "context.tv.channelArt.nightly.moon" | "context.tv.channelArt.nightly.moonCrater" | "context.tv.channelArt.lab.background" | "context.tv.channelArt.lab.foreground" | "context.tv.channelArt.lab.accent" | "tv.video.background" | "tv.video.heroScrimTop" | "tv.video.heroScrimBottom" | "tv.video.textOnVideo" | "tv.text.heading" | "tv.text.label" | "tv.text.body" | "tv.text.caption" | "tv.text.smol" | "tv.fontWeight.regular" | "tv.fontWeight.medium" | "tv.space.xxs" | "tv.space.xs" | "tv.space.sm" | "tv.space.md" | "tv.space.lg" | "tv.space.xl" | "tv.space.xxl" | "tv.overscan.x" | "tv.overscan.y" | "tv.radius" | "tv.focus.borderWidth" | "tv.focus.row.background" | "tv.focus.row.backgroundFocused" | "tv.focus.control.background" | "tv.focus.control.backgroundFocused" | "tv.focus.control.border" | "tv.focus.control.borderFocused" | "tv.z.modal" | "tv.z.toast" | "tv.z.overlay" | "color.brand.yellow" | "color.neutral.light.bg" | "color.neutral.light.bgSecondary" | "color.neutral.light.componentBg" | "color.neutral.light.componentBgHover" | "color.neutral.light.componentBgActive" | "color.neutral.light.line" | "color.neutral.light.border" | "color.neutral.light.borderHover" | "color.neutral.light.solid" | "color.neutral.light.solidHover" | "color.neutral.light.textSecondary" | "color.neutral.light.text" | "color.neutral.dark.bg" | "color.neutral.dark.bgSecondary" | "color.neutral.dark.componentBg" | "color.neutral.dark.componentBgHover" | "color.neutral.dark.componentBgActive" | "color.neutral.dark.line" | "color.neutral.dark.border" | "color.neutral.dark.borderHover" | "color.neutral.dark.solid" | "color.neutral.dark.solidHover" | "color.neutral.dark.textSecondary" | "color.neutral.dark.text" | "color.green.light.bg" | "color.green.light.bgSecondary" | "color.green.light.componentBg" | "color.green.light.componentBgHover" | "color.green.light.componentBgActive" | "color.green.light.line" | "color.green.light.border" | "color.green.light.borderHover" | "color.green.light.solid" | "color.green.light.solidHover" | "color.green.light.textSecondary" | "color.green.light.text" | "color.green.dark.bg" | "color.green.dark.bgSecondary" | "color.green.dark.componentBg" | "color.green.dark.componentBgHover" | "color.green.dark.componentBgActive" | "color.green.dark.line" | "color.green.dark.border" | "color.green.dark.borderHover" | "color.green.dark.solid" | "color.green.dark.solidHover" | "color.green.dark.textSecondary" | "color.green.dark.text" | "color.red.light.bg" | "color.red.light.bgSecondary" | "color.red.light.componentBg" | "color.red.light.componentBgHover" | "color.red.light.componentBgActive" | "color.red.light.line" | "color.red.light.border" | "color.red.light.borderHover" | "color.red.light.solid" | "color.red.light.solidHover" | "color.red.light.textSecondary" | "color.red.light.text" | "color.red.dark.bg" | "color.red.dark.bgSecondary" | "color.red.dark.componentBg" | "color.red.dark.componentBgHover" | "color.red.dark.componentBgActive" | "color.red.dark.line" | "color.red.dark.border" | "color.red.dark.borderHover" | "color.red.dark.solid" | "color.red.dark.solidHover" | "color.red.dark.textSecondary" | "color.red.dark.text" | "color.yellow.light.bg" | "color.yellow.light.bgSecondary" | "color.yellow.light.componentBg" | "color.yellow.light.componentBgHover" | "color.yellow.light.componentBgActive" | "color.yellow.light.line" | "color.yellow.light.border" | "color.yellow.light.borderHover" | "color.yellow.light.solidHover" | "color.yellow.light.textSecondary" | "color.yellow.light.text" | "color.yellow.dark.bg" | "color.yellow.dark.bgSecondary" | "color.yellow.dark.componentBg" | "color.yellow.dark.componentBgHover" | "color.yellow.dark.componentBgActive" | "color.yellow.dark.line" | "color.yellow.dark.border" | "color.yellow.dark.borderHover" | "color.yellow.dark.solidHover" | "color.yellow.dark.textSecondary" | "color.yellow.dark.text" | "color.transfer.light.lime3" | "color.transfer.dark.lime3" | "elevation.shadowColor" | "elevation.color" | "elevation.sm" | "elevation.md" | "elevation.lg" | "elevation.focusColor" | "elevation.focus" | "elevation.focusDark" | "typography.fontFamily.sans" | "typography.fontFamily.display" | "typography.fontFamily.mono" | "typography.fontSize.xs" | "typography.fontSize.sm" | "typography.fontSize.base" | "typography.fontSize.md" | "typography.fontSize.lg" | "typography.fontSize.title" | "typography.fontSize.xl" | "typography.fontSize.2xl" | "typography.fontSize.3xl" | "typography.fontSize.4xl" | "typography.fontSize.display" | "typography.lineHeight.tight" | "typography.lineHeight.snug" | "typography.lineHeight.normal" | "typography.lineHeight.loose" | "typography.fontWeight.regular" | "typography.fontWeight.medium" | "typography.fontWeight.bold" | "typography.fontWeight.black" | "typography.letterSpacing.tight" | "typography.letterSpacing.snug" | "typography.letterSpacing.normal" | "typography.letterSpacing.wide" | "typography.letterSpacing.uppercase" | "spacing.0" | "spacing.1" | "spacing.2" | "spacing.3" | "spacing.4" | "spacing.5" | "spacing.6" | "spacing.7" | "spacing.8" | "spacing.10" | "spacing.12" | "spacing.16" | "spacing.32" | "spacing.64" | "spacing.128" | "radius.sm" | "radius.default" | "radius.md" | "radius.lg" | "radius.pill" | "radius.tv" | "border.width" | "motion.easing.out" | "motion.easing.inOut" | "motion.duration.fast" | "motion.duration.reveal" | "motion.duration.base" | "motion.duration.slow" | "z.dropdown" | "z.sticky" | "z.modal" | "z.notification" | "z.tooltip" | "breakpoint.sm" | "breakpoint.md" | "breakpoint.lg" | "surface.light.htmlBg" | "surface.light.appBg" | "surface.light.navBg" | "surface.light.navItemBg" | "surface.light.navItemBgHover" | "surface.light.navItemBgActive" | "surface.light.listItemBg" | "surface.light.listItemBgHover" | "surface.light.listItemBgActive" | "surface.light.listItemBorder" | "surface.light.segmentedControlBg" | "surface.light.segmentedControlBgActive" | "surface.light.transferListItemCompletingBg" | "surface.light.transferListItemDownloadingBg" | "surface.light.transferListItemFinishedBg" | "surface.light.transferListItemPassiveBg" | "surface.light.hiContrast" | "surface.light.loContrast" | "surface.light.transparent" | "surface.light.overlayInline" | "surface.light.overlayFull" | "surface.dark.htmlBg" | "surface.dark.appBg" | "surface.dark.navBg" | "surface.dark.navItemBg" | "surface.dark.navItemBgHover" | "surface.dark.navItemBgActive" | "surface.dark.listItemBg" | "surface.dark.listItemBgHover" | "surface.dark.listItemBgActive" | "surface.dark.listItemBorder" | "surface.dark.segmentedControlBg" | "surface.dark.segmentedControlBgActive" | "surface.dark.transferListItemCompletingBg" | "surface.dark.transferListItemDownloadingBg" | "surface.dark.transferListItemFinishedBg" | "surface.dark.transferListItemPassiveBg" | "surface.dark.hiContrast" | "surface.dark.loContrast" | "surface.dark.overlayInline" | "surface.dark.overlayFull" | "surface.dark.shadowColor" | "surface.dark.shadow" | "surface.dark.shadowSm" | "surface.dark.shadowMd" | "surface.dark.shadowLg";
+export type PutioTokenName = "component.button.primary.background" | "component.button.primary.backgroundHover" | "component.button.primary.backgroundHoverDark" | "component.button.primary.foreground" | "component.button.primary.radius" | "component.button.secondary.background" | "component.button.secondary.backgroundDark" | "component.button.secondary.foreground" | "component.button.secondary.foregroundDark" | "component.button.secondary.backgroundHover" | "component.button.secondary.backgroundHoverDark" | "component.button.success.background" | "component.button.success.backgroundDark" | "component.button.success.backgroundHover" | "component.button.success.backgroundHoverDark" | "component.button.success.foreground" | "component.button.danger.background" | "component.button.danger.backgroundDark" | "component.button.danger.backgroundHover" | "component.button.danger.backgroundHoverDark" | "component.button.danger.foreground" | "component.button.info.background" | "component.button.info.backgroundDark" | "component.button.info.backgroundHover" | "component.button.info.backgroundHoverDark" | "component.button.info.foreground" | "component.button.info.foregroundDark" | "component.button.default.background" | "component.button.default.backgroundDark" | "component.button.default.backgroundHover" | "component.button.default.backgroundHoverDark" | "component.button.default.foreground" | "component.button.default.foregroundDark" | "component.button.ghost.background" | "component.button.ghost.foreground" | "component.button.ghost.foregroundDark" | "component.button.ghost.foregroundHover" | "component.button.ghost.foregroundHoverDark" | "component.button.ghost.backgroundHover" | "component.button.ghost.backgroundHoverDark" | "component.button.height" | "component.button.heightMd" | "component.button.heightSm" | "component.button.heightXs" | "component.button.paddingX" | "component.button.paddingXXs" | "component.button.labelSize" | "component.button.labelSizeXs" | "component.button.tracking" | "component.button.trackingMd" | "component.button.trackingSm" | "component.button.trackingXs" | "component.button.iconSize" | "component.button.gap" | "component.nav.height" | "component.nav.heightCompact" | "component.nav.ctaHeight" | "component.input.background" | "component.input.backgroundDark" | "component.input.border" | "component.input.borderDark" | "component.input.radius" | "component.input.borderHover" | "component.input.borderHoverDark" | "component.input.borderFocus" | "component.input.borderFocusDark" | "component.input.ring" | "component.input.ringDark" | "component.input.text" | "component.input.textDark" | "component.input.placeholder" | "component.input.placeholderDark" | "component.field.background" | "component.field.backgroundDark" | "component.field.backgroundDisabled" | "component.field.backgroundDisabledDark" | "component.field.border" | "component.field.borderDark" | "component.field.borderHover" | "component.field.borderHoverDark" | "component.field.borderFocus" | "component.field.borderFocusDark" | "component.field.text" | "component.field.textDark" | "component.field.placeholder" | "component.field.placeholderDark" | "component.field.radius" | "component.field.ring" | "component.field.ringDark" | "component.panel.background" | "component.panel.backgroundDark" | "component.panel.border" | "component.panel.borderDark" | "component.panel.radius" | "component.panel.shadow" | "component.panel.shadowDark" | "component.alias.background" | "component.alias.backgroundDark" | "component.alias.foreground" | "component.alias.foregroundDark" | "component.alias.foregroundMuted" | "component.alias.foregroundMutedDark" | "component.alias.primary" | "component.alias.primaryForeground" | "component.alias.success" | "component.alias.successDark" | "component.alias.successForeground" | "component.alias.destructive" | "component.alias.destructiveDark" | "component.alias.destructiveForeground" | "component.alias.invertForeground" | "component.alias.invertForegroundDark" | "component.alias.solidForeground" | "component.alias.solidForegroundDark" | "component.alias.muted" | "component.alias.mutedDark" | "component.alias.mutedForeground" | "component.alias.mutedForegroundDark" | "component.alias.accent" | "component.alias.accentDark" | "component.alias.accentForeground" | "component.alias.accentForegroundDark" | "component.alias.card" | "component.alias.cardDark" | "component.alias.cardForeground" | "component.alias.cardForegroundDark" | "component.alias.popover" | "component.alias.popoverDark" | "component.alias.popoverForeground" | "component.alias.popoverForegroundDark" | "component.alias.input" | "component.alias.inputDark" | "component.alias.ring" | "component.fileRow.background" | "component.fileRow.backgroundDark" | "component.fileRow.hoverBackground" | "component.fileRow.hoverBackgroundDark" | "component.fileRow.activeBackground" | "component.fileRow.activeBackgroundDark" | "component.fileRow.border" | "component.fileRow.borderDark" | "component.fileRow.icon" | "component.notification.infoBackground" | "component.notification.infoBackgroundDark" | "component.notification.dangerBackground" | "component.notification.dangerBackgroundDark" | "component.notification.background" | "component.notification.backgroundDark" | "component.notification.border" | "component.notification.borderDark" | "component.notification.foreground" | "component.notification.foregroundDark" | "component.notification.icon" | "component.notification.iconDark" | "component.notification.successBackground" | "component.notification.successBackgroundDark" | "component.notification.successBorder" | "component.notification.successBorderDark" | "component.notification.successForeground" | "component.notification.successForegroundDark" | "component.notification.dangerBorder" | "component.notification.dangerBorderDark" | "component.notification.dangerForeground" | "component.notification.dangerForegroundDark" | "component.notification.badgeBackground" | "component.notification.badgeForeground" | "component.menu.background" | "component.menu.backgroundDark" | "component.menu.border" | "component.menu.borderDark" | "component.menu.radius" | "component.menu.shadow" | "component.menu.shadowDark" | "component.menu.itemBackgroundHover" | "component.menu.itemBackgroundHoverDark" | "component.menu.itemText" | "component.menu.itemTextDark" | "component.menu.itemIcon" | "component.menu.itemIconDark" | "component.menu.itemShortcut" | "component.menu.itemShortcutDark" | "component.menu.itemDangerText" | "component.menu.itemDangerTextDark" | "component.menu.itemDangerBackgroundHover" | "component.menu.itemDangerBackgroundHoverDark" | "component.menu.itemHeight" | "component.menu.separator" | "component.menu.separatorDark" | "component.menu.label" | "component.menu.labelDark" | "component.palette.background" | "component.palette.backgroundDark" | "component.palette.border" | "component.palette.borderDark" | "component.palette.shadow" | "component.palette.shadowDark" | "component.palette.scrim" | "component.palette.scrimDark" | "component.palette.width" | "component.palette.inputHeight" | "component.palette.itemHeight" | "component.palette.itemBackgroundActive" | "component.palette.itemBackgroundActiveDark" | "component.palette.groupLabel" | "component.palette.groupLabelDark" | "component.palette.itemMeta" | "component.palette.itemMetaDark" | "component.sheet.background" | "component.sheet.backgroundDark" | "component.sheet.border" | "component.sheet.borderDark" | "component.sheet.shadow" | "component.sheet.shadowDark" | "component.sheet.scrim" | "component.sheet.scrimDark" | "component.sheet.width" | "component.avatar.yellow" | "component.avatar.green" | "component.avatar.red" | "component.avatar.blue" | "component.avatar.purple" | "component.avatar.teal" | "component.avatar.orange" | "component.avatar.foreground" | "component.avatar.foregroundWarm" | "component.alert.radius" | "component.alert.infoBackground" | "component.alert.infoBackgroundDark" | "component.alert.infoBorder" | "component.alert.infoBorderDark" | "component.alert.infoText" | "component.alert.infoTextDark" | "component.alert.infoBody" | "component.alert.infoBodyDark" | "component.alert.infoIcon" | "component.alert.infoIconDark" | "component.alert.brandBackground" | "component.alert.brandBackgroundDark" | "component.alert.brandBorder" | "component.alert.brandBorderDark" | "component.alert.brandText" | "component.alert.brandTextDark" | "component.alert.brandBody" | "component.alert.brandBodyDark" | "component.alert.brandIcon" | "component.alert.brandIconDark" | "component.alert.successBackground" | "component.alert.successBackgroundDark" | "component.alert.successBorder" | "component.alert.successBorderDark" | "component.alert.successText" | "component.alert.successTextDark" | "component.alert.successBody" | "component.alert.successBodyDark" | "component.alert.successIcon" | "component.alert.successIconDark" | "component.alert.dangerBackground" | "component.alert.dangerBackgroundDark" | "component.alert.dangerBorder" | "component.alert.dangerBorderDark" | "component.alert.dangerText" | "component.alert.dangerTextDark" | "component.alert.dangerBody" | "component.alert.dangerBodyDark" | "component.alert.dangerIcon" | "component.alert.dangerIconDark" | "component.slider.track" | "component.slider.trackDark" | "component.slider.buffer" | "component.slider.bufferDark" | "component.slider.fill" | "component.slider.knob" | "component.slider.fillDisabled" | "component.slider.fillDisabledDark" | "component.slider.trackHeight" | "component.slider.knobSize" | "component.slider.hitHeight" | "component.pagination.itemSize" | "component.pagination.itemText" | "component.pagination.itemTextDark" | "component.pagination.itemTextActive" | "component.pagination.itemTextActiveDark" | "component.pagination.itemBackgroundHover" | "component.pagination.itemBackgroundHoverDark" | "component.pagination.itemBackgroundActive" | "component.pagination.itemBackgroundActiveDark" | "component.pagination.itemBorderActive" | "component.pagination.itemBorderActiveDark" | "context.tv.text.primary" | "context.tv.text.secondary" | "context.tv.text.tertiary" | "context.tv.channelArt.production.posterBackground" | "context.tv.channelArt.production.splashBackground" | "context.tv.channelArt.development.background" | "context.tv.channelArt.development.accent" | "context.tv.channelArt.development.grid" | "context.tv.channelArt.nightly.background" | "context.tv.channelArt.nightly.accent" | "context.tv.channelArt.nightly.star" | "context.tv.channelArt.nightly.moon" | "context.tv.channelArt.nightly.moonCrater" | "context.tv.channelArt.lab.background" | "context.tv.channelArt.lab.foreground" | "context.tv.channelArt.lab.accent" | "tv.video.background" | "tv.video.heroScrimTop" | "tv.video.heroScrimBottom" | "tv.video.textOnVideo" | "tv.text.heading" | "tv.text.label" | "tv.text.body" | "tv.text.caption" | "tv.text.smol" | "tv.fontWeight.regular" | "tv.fontWeight.medium" | "tv.space.xxs" | "tv.space.xs" | "tv.space.sm" | "tv.space.md" | "tv.space.lg" | "tv.space.xl" | "tv.space.xxl" | "tv.overscan.x" | "tv.overscan.y" | "tv.radius" | "tv.focus.borderWidth" | "tv.focus.row.background" | "tv.focus.row.backgroundFocused" | "tv.focus.control.background" | "tv.focus.control.backgroundFocused" | "tv.focus.control.border" | "tv.focus.control.borderFocused" | "tv.z.modal" | "tv.z.toast" | "tv.z.overlay" | "color.brand.yellow" | "color.neutral.light.bg" | "color.neutral.light.bgSecondary" | "color.neutral.light.componentBg" | "color.neutral.light.componentBgHover" | "color.neutral.light.componentBgActive" | "color.neutral.light.line" | "color.neutral.light.border" | "color.neutral.light.borderHover" | "color.neutral.light.solid" | "color.neutral.light.solidHover" | "color.neutral.light.textSecondary" | "color.neutral.light.text" | "color.neutral.dark.bg" | "color.neutral.dark.bgSecondary" | "color.neutral.dark.componentBg" | "color.neutral.dark.componentBgHover" | "color.neutral.dark.componentBgActive" | "color.neutral.dark.line" | "color.neutral.dark.border" | "color.neutral.dark.borderHover" | "color.neutral.dark.solid" | "color.neutral.dark.solidHover" | "color.neutral.dark.textSecondary" | "color.neutral.dark.text" | "color.green.light.bg" | "color.green.light.bgSecondary" | "color.green.light.componentBg" | "color.green.light.componentBgHover" | "color.green.light.componentBgActive" | "color.green.light.line" | "color.green.light.border" | "color.green.light.borderHover" | "color.green.light.solid" | "color.green.light.solidHover" | "color.green.light.textSecondary" | "color.green.light.text" | "color.green.dark.bg" | "color.green.dark.bgSecondary" | "color.green.dark.componentBg" | "color.green.dark.componentBgHover" | "color.green.dark.componentBgActive" | "color.green.dark.line" | "color.green.dark.border" | "color.green.dark.borderHover" | "color.green.dark.solid" | "color.green.dark.solidHover" | "color.green.dark.textSecondary" | "color.green.dark.text" | "color.red.light.bg" | "color.red.light.bgSecondary" | "color.red.light.componentBg" | "color.red.light.componentBgHover" | "color.red.light.componentBgActive" | "color.red.light.line" | "color.red.light.border" | "color.red.light.borderHover" | "color.red.light.solid" | "color.red.light.solidHover" | "color.red.light.textSecondary" | "color.red.light.text" | "color.red.dark.bg" | "color.red.dark.bgSecondary" | "color.red.dark.componentBg" | "color.red.dark.componentBgHover" | "color.red.dark.componentBgActive" | "color.red.dark.line" | "color.red.dark.border" | "color.red.dark.borderHover" | "color.red.dark.solid" | "color.red.dark.solidHover" | "color.red.dark.textSecondary" | "color.red.dark.text" | "color.yellow.light.bg" | "color.yellow.light.bgSecondary" | "color.yellow.light.componentBg" | "color.yellow.light.componentBgHover" | "color.yellow.light.componentBgActive" | "color.yellow.light.line" | "color.yellow.light.border" | "color.yellow.light.borderHover" | "color.yellow.light.solidHover" | "color.yellow.light.textSecondary" | "color.yellow.light.text" | "color.yellow.dark.bg" | "color.yellow.dark.bgSecondary" | "color.yellow.dark.componentBg" | "color.yellow.dark.componentBgHover" | "color.yellow.dark.componentBgActive" | "color.yellow.dark.line" | "color.yellow.dark.border" | "color.yellow.dark.borderHover" | "color.yellow.dark.solidHover" | "color.yellow.dark.textSecondary" | "color.yellow.dark.text" | "color.transfer.light.lime3" | "color.transfer.dark.lime3" | "elevation.shadowColor" | "elevation.color" | "elevation.sm" | "elevation.md" | "elevation.lg" | "elevation.focusColor" | "elevation.focus" | "elevation.focusDark" | "typography.fontFamily.sans" | "typography.fontFamily.display" | "typography.fontFamily.mono" | "typography.fontSize.xs" | "typography.fontSize.sm" | "typography.fontSize.base" | "typography.fontSize.md" | "typography.fontSize.lg" | "typography.fontSize.title" | "typography.fontSize.xl" | "typography.fontSize.2xl" | "typography.fontSize.3xl" | "typography.fontSize.4xl" | "typography.fontSize.display" | "typography.lineHeight.tight" | "typography.lineHeight.snug" | "typography.lineHeight.normal" | "typography.lineHeight.loose" | "typography.fontWeight.regular" | "typography.fontWeight.medium" | "typography.fontWeight.bold" | "typography.fontWeight.black" | "typography.letterSpacing.tight" | "typography.letterSpacing.snug" | "typography.letterSpacing.normal" | "typography.letterSpacing.wide" | "typography.letterSpacing.uppercase" | "typography.role.ui" | "typography.role.body" | "typography.role.caption" | "typography.role.field" | "spacing.0" | "spacing.1" | "spacing.2" | "spacing.3" | "spacing.4" | "spacing.5" | "spacing.6" | "spacing.7" | "spacing.8" | "spacing.10" | "spacing.12" | "spacing.16" | "spacing.32" | "spacing.64" | "spacing.128" | "radius.sm" | "radius.default" | "radius.md" | "radius.lg" | "radius.pill" | "radius.tv" | "border.width" | "motion.easing.out" | "motion.easing.inOut" | "motion.duration.fast" | "motion.duration.reveal" | "motion.duration.base" | "motion.duration.slow" | "z.dropdown" | "z.sticky" | "z.modal" | "z.notification" | "z.tooltip" | "breakpoint.sm" | "breakpoint.md" | "breakpoint.lg" | "surface.light.htmlBg" | "surface.light.appBg" | "surface.light.navBg" | "surface.light.navItemBg" | "surface.light.navItemBgHover" | "surface.light.navItemBgActive" | "surface.light.listItemBg" | "surface.light.listItemBgHover" | "surface.light.listItemBgActive" | "surface.light.listItemBorder" | "surface.light.segmentedControlBg" | "surface.light.segmentedControlBgActive" | "surface.light.transferListItemCompletingBg" | "surface.light.transferListItemDownloadingBg" | "surface.light.transferListItemFinishedBg" | "surface.light.transferListItemPassiveBg" | "surface.light.hiContrast" | "surface.light.loContrast" | "surface.light.transparent" | "surface.light.overlayInline" | "surface.light.overlayFull" | "surface.dark.htmlBg" | "surface.dark.appBg" | "surface.dark.navBg" | "surface.dark.navItemBg" | "surface.dark.navItemBgHover" | "surface.dark.navItemBgActive" | "surface.dark.listItemBg" | "surface.dark.listItemBgHover" | "surface.dark.listItemBgActive" | "surface.dark.listItemBorder" | "surface.dark.segmentedControlBg" | "surface.dark.segmentedControlBgActive" | "surface.dark.transferListItemCompletingBg" | "surface.dark.transferListItemDownloadingBg" | "surface.dark.transferListItemFinishedBg" | "surface.dark.transferListItemPassiveBg" | "surface.dark.hiContrast" | "surface.dark.loContrast" | "surface.dark.overlayInline" | "surface.dark.overlayFull" | "surface.dark.shadowColor" | "surface.dark.shadow" | "surface.dark.shadowSm" | "surface.dark.shadowMd" | "surface.dark.shadowLg";
 
 export type PutioToken = {
   readonly cssName: string;

package/dist/tokens.dtcg.json

@@ -519,7 +519,7 @@
       },
       "labelSize": {
         "$type": "dimension",
-        "$value": "{typography.fontSize.sm}",
+        "$value": "{typography.role.ui}",
         "$description": "Uppercase label size.",
         "$extensions": {
           "putio": {
@@ -4810,6 +4810,7 @@
       "xs": {
         "$type": "dimension",
         "$value": "0.75rem",
+        "$description": "12px. Captions: read it through --fs-caption.",
         "$extensions": {
           "putio": {
             "cssName": "fs-xs",
@@ -4821,7 +4822,7 @@
       "sm": {
         "$type": "dimension",
         "$value": "0.875rem",
-        "$description": "Caption and button labels — production fontSize 0.",
+        "$description": "14px. UI chrome (labels, buttons, links, errors): read it through --fs-ui.",
         "$extensions": {
           "putio": {
             "cssName": "fs-sm",
@@ -4833,7 +4834,7 @@
       "base": {
         "$type": "dimension",
         "$value": "1rem",
-        "$description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg).",
+        "$description": "16px, the root. Body text and inputs: read it through --fs-body or --fs-field.",
         "$extensions": {
           "putio": {
             "cssName": "fs-base",
@@ -4845,7 +4846,7 @@
       "md": {
         "$type": "dimension",
         "$value": "1.125rem",
-        "$description": "Subheading.",
+        "$description": "18px. Subheading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-md",
@@ -4857,7 +4858,7 @@
       "lg": {
         "$type": "dimension",
         "$value": "1.5rem",
-        "$description": "Heading.",
+        "$description": "24px. Heading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-lg",
@@ -4868,8 +4869,8 @@
       },
       "title": {
         "$type": "dimension",
-        "$value": "22px",
-        "$description": "Screen titles and one-time-code digits. The fixed-pixel sibling of fontSize.lg (H2), which scales with the root.",
+        "$value": "1.375rem",
+        "$description": "22px. Screen titles and one-time-code digits, beside fontSize.lg (H2).",
         "$extensions": {
           "putio": {
             "cssName": "fs-title",
@@ -4881,7 +4882,7 @@
       "xl": {
         "$type": "dimension",
         "$value": "2rem",
-        "$description": "Page title.",
+        "$description": "32px. Page title.",
         "$extensions": {
           "putio": {
             "cssName": "fs-xl",
@@ -4892,8 +4893,8 @@
       },
       "2xl": {
         "$type": "dimension",
-        "$value": "48px",
-        "$description": "Fixed display tier — does not scale with the responsive root.",
+        "$value": "3rem",
+        "$description": "48px. Display tier.",
         "$extensions": {
           "putio": {
             "cssName": "fs-2xl",
@@ -4904,8 +4905,8 @@
       },
       "3xl": {
         "$type": "dimension",
-        "$value": "64px",
-        "$description": "Fixed display tier — does not scale with the responsive root.",
+        "$value": "4rem",
+        "$description": "64px. Display tier.",
         "$extensions": {
           "putio": {
             "cssName": "fs-3xl",
@@ -4928,8 +4929,8 @@
       },
       "display": {
         "$type": "dimension",
-        "$value": "96px",
-        "$description": "Fixed display tier for brand display moments.",
+        "$value": "6rem",
+        "$description": "96px. Display tier for brand display moments.",
         "$extensions": {
           "putio": {
             "cssName": "fs-display",
@@ -5088,6 +5089,57 @@
           }
         }
       }
+    },
+    "$description": "Text roles. Components choose a role, not a size step.",
+    "role": {
+      "ui": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.sm}",
+        "$description": "UI chrome: labels, buttons, nav, links, errors, footers.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-ui",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "body": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.base}",
+        "$description": "Body and long text.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-body",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "caption": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.xs}",
+        "$description": "Captions and metadata.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-caption",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "field": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.base}",
+        "$description": "Text a person types into a field. 16px keeps iOS Safari from zooming on focus.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-field",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      }
     }
   },
   "spacing": {

package/dist/tokens.flat.json

@@ -367,7 +367,7 @@
     "type": "dimension",
     "mode": "global",
     "value": "0.875rem",
-    "originalValue": "{typography.fontSize.sm}",
+    "originalValue": "{typography.role.ui}",
     "description": "Uppercase label size."
   },
   "component.button.labelSizeXs": {
@@ -3274,7 +3274,8 @@
     "type": "dimension",
     "mode": "global",
     "value": "0.75rem",
-    "originalValue": "0.75rem"
+    "originalValue": "0.75rem",
+    "description": "12px. Captions: read it through --fs-caption."
   },
   "typography.fontSize.sm": {
     "cssName": "--fs-sm",
@@ -3282,7 +3283,7 @@
     "mode": "global",
     "value": "0.875rem",
     "originalValue": "0.875rem",
-    "description": "Caption and button labels — production fontSize 0."
+    "description": "14px. UI chrome (labels, buttons, links, errors): read it through --fs-ui."
   },
   "typography.fontSize.base": {
     "cssName": "--fs-base",
@@ -3290,7 +3291,7 @@
     "mode": "global",
     "value": "1rem",
     "originalValue": "1rem",
-    "description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg)."
+    "description": "16px, the root. Body text and inputs: read it through --fs-body or --fs-field."
   },
   "typography.fontSize.md": {
     "cssName": "--fs-md",
@@ -3298,7 +3299,7 @@
     "mode": "global",
     "value": "1.125rem",
     "originalValue": "1.125rem",
-    "description": "Subheading."
+    "description": "18px. Subheading."
   },
   "typography.fontSize.lg": {
     "cssName": "--fs-lg",
@@ -3306,15 +3307,15 @@
     "mode": "global",
     "value": "1.5rem",
     "originalValue": "1.5rem",
-    "description": "Heading."
+    "description": "24px. Heading."
   },
   "typography.fontSize.title": {
     "cssName": "--fs-title",
     "type": "dimension",
     "mode": "global",
-    "value": "22px",
-    "originalValue": "22px",
-    "description": "Screen titles and one-time-code digits. The fixed-pixel sibling of fontSize.lg (H2), which scales with the root."
+    "value": "1.375rem",
+    "originalValue": "1.375rem",
+    "description": "22px. Screen titles and one-time-code digits, beside fontSize.lg (H2)."
   },
   "typography.fontSize.xl": {
     "cssName": "--fs-xl",
@@ -3322,29 +3323,29 @@
     "mode": "global",
     "value": "2rem",
     "originalValue": "2rem",
-    "description": "Page title."
+    "description": "32px. Page title."
   },
   "typography.fontSize.2xl": {
     "cssName": "--fs-2xl",
     "type": "dimension",
     "mode": "global",
-    "value": "48px",
-    "originalValue": "48px",
-    "description": "Fixed display tier — does not scale with the responsive root."
+    "value": "3rem",
+    "originalValue": "3rem",
+    "description": "48px. Display tier."
   },
   "typography.fontSize.3xl": {
     "cssName": "--fs-3xl",
     "type": "dimension",
     "mode": "global",
-    "value": "64px",
-    "originalValue": "64px",
-    "description": "Fixed display tier — does not scale with the responsive root."
+    "value": "4rem",
+    "originalValue": "4rem",
+    "description": "64px. Display tier."
   },
   "typography.fontSize.4xl": {
     "cssName": "--fs-4xl",
     "type": "dimension",
     "mode": "global",
-    "value": "64px",
+    "value": "4rem",
     "originalValue": "{typography.fontSize.3xl}",
     "description": "Compatibility alias for the former 4xl tier; new surfaces should use fontSize.3xl or fontSize.display."
   },
@@ -3352,9 +3353,9 @@
     "cssName": "--fs-display",
     "type": "dimension",
     "mode": "global",
-    "value": "96px",
-    "originalValue": "96px",
-    "description": "Fixed display tier for brand display moments."
+    "value": "6rem",
+    "originalValue": "6rem",
+    "description": "96px. Display tier for brand display moments."
   },
   "typography.lineHeight.tight": {
     "cssName": "--lh-tight",
@@ -3448,6 +3449,38 @@
     "value": "0.08em",
     "originalValue": "0.08em"
   },
+  "typography.role.ui": {
+    "cssName": "--fs-ui",
+    "type": "dimension",
+    "mode": "global",
+    "value": "0.875rem",
+    "originalValue": "{typography.fontSize.sm}",
+    "description": "UI chrome: labels, buttons, nav, links, errors, footers."
+  },
+  "typography.role.body": {
+    "cssName": "--fs-body",
+    "type": "dimension",
+    "mode": "global",
+    "value": "1rem",
+    "originalValue": "{typography.fontSize.base}",
+    "description": "Body and long text."
+  },
+  "typography.role.caption": {
+    "cssName": "--fs-caption",
+    "type": "dimension",
+    "mode": "global",
+    "value": "0.75rem",
+    "originalValue": "{typography.fontSize.xs}",
+    "description": "Captions and metadata."
+  },
+  "typography.role.field": {
+    "cssName": "--fs-field",
+    "type": "dimension",
+    "mode": "global",
+    "value": "1rem",
+    "originalValue": "{typography.fontSize.base}",
+    "description": "Text a person types into a field. 16px keeps iOS Safari from zooming on focus."
+  },
   "spacing.0": {
     "cssName": "--space-0",
     "type": "dimension",

package/dist/tokens.js

@@ -369,7 +369,7 @@ export const tokens = {
     "type": "dimension",
     "mode": "global",
     "value": "0.875rem",
-    "originalValue": "{typography.fontSize.sm}",
+    "originalValue": "{typography.role.ui}",
     "description": "Uppercase label size."
   },
   "component.button.labelSizeXs": {
@@ -3276,7 +3276,8 @@ export const tokens = {
     "type": "dimension",
     "mode": "global",
     "value": "0.75rem",
-    "originalValue": "0.75rem"
+    "originalValue": "0.75rem",
+    "description": "12px. Captions: read it through --fs-caption."
   },
   "typography.fontSize.sm": {
     "cssName": "--fs-sm",
@@ -3284,7 +3285,7 @@ export const tokens = {
     "mode": "global",
     "value": "0.875rem",
     "originalValue": "0.875rem",
-    "description": "Caption and button labels — production fontSize 0."
+    "description": "14px. UI chrome (labels, buttons, links, errors): read it through --fs-ui."
   },
   "typography.fontSize.base": {
     "cssName": "--fs-base",
@@ -3292,7 +3293,7 @@ export const tokens = {
     "mode": "global",
     "value": "1rem",
     "originalValue": "1rem",
-    "description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg)."
+    "description": "16px, the root. Body text and inputs: read it through --fs-body or --fs-field."
   },
   "typography.fontSize.md": {
     "cssName": "--fs-md",
@@ -3300,7 +3301,7 @@ export const tokens = {
     "mode": "global",
     "value": "1.125rem",
     "originalValue": "1.125rem",
-    "description": "Subheading."
+    "description": "18px. Subheading."
   },
   "typography.fontSize.lg": {
     "cssName": "--fs-lg",
@@ -3308,15 +3309,15 @@ export const tokens = {
     "mode": "global",
     "value": "1.5rem",
     "originalValue": "1.5rem",
-    "description": "Heading."
+    "description": "24px. Heading."
   },
   "typography.fontSize.title": {
     "cssName": "--fs-title",
     "type": "dimension",
     "mode": "global",
-    "value": "22px",
-    "originalValue": "22px",
-    "description": "Screen titles and one-time-code digits. The fixed-pixel sibling of fontSize.lg (H2), which scales with the root."
+    "value": "1.375rem",
+    "originalValue": "1.375rem",
+    "description": "22px. Screen titles and one-time-code digits, beside fontSize.lg (H2)."
   },
   "typography.fontSize.xl": {
     "cssName": "--fs-xl",
@@ -3324,29 +3325,29 @@ export const tokens = {
     "mode": "global",
     "value": "2rem",
     "originalValue": "2rem",
-    "description": "Page title."
+    "description": "32px. Page title."
   },
   "typography.fontSize.2xl": {
     "cssName": "--fs-2xl",
     "type": "dimension",
     "mode": "global",
-    "value": "48px",
-    "originalValue": "48px",
-    "description": "Fixed display tier — does not scale with the responsive root."
+    "value": "3rem",
+    "originalValue": "3rem",
+    "description": "48px. Display tier."
   },
   "typography.fontSize.3xl": {
     "cssName": "--fs-3xl",
     "type": "dimension",
     "mode": "global",
-    "value": "64px",
-    "originalValue": "64px",
-    "description": "Fixed display tier — does not scale with the responsive root."
+    "value": "4rem",
+    "originalValue": "4rem",
+    "description": "64px. Display tier."
   },
   "typography.fontSize.4xl": {
     "cssName": "--fs-4xl",
     "type": "dimension",
     "mode": "global",
-    "value": "64px",
+    "value": "4rem",
     "originalValue": "{typography.fontSize.3xl}",
     "description": "Compatibility alias for the former 4xl tier; new surfaces should use fontSize.3xl or fontSize.display."
   },
@@ -3354,9 +3355,9 @@ export const tokens = {
     "cssName": "--fs-display",
     "type": "dimension",
     "mode": "global",
-    "value": "96px",
-    "originalValue": "96px",
-    "description": "Fixed display tier for brand display moments."
+    "value": "6rem",
+    "originalValue": "6rem",
+    "description": "96px. Display tier for brand display moments."
   },
   "typography.lineHeight.tight": {
     "cssName": "--lh-tight",
@@ -3450,6 +3451,38 @@ export const tokens = {
     "value": "0.08em",
     "originalValue": "0.08em"
   },
+  "typography.role.ui": {
+    "cssName": "--fs-ui",
+    "type": "dimension",
+    "mode": "global",
+    "value": "0.875rem",
+    "originalValue": "{typography.fontSize.sm}",
+    "description": "UI chrome: labels, buttons, nav, links, errors, footers."
+  },
+  "typography.role.body": {
+    "cssName": "--fs-body",
+    "type": "dimension",
+    "mode": "global",
+    "value": "1rem",
+    "originalValue": "{typography.fontSize.base}",
+    "description": "Body and long text."
+  },
+  "typography.role.caption": {
+    "cssName": "--fs-caption",
+    "type": "dimension",
+    "mode": "global",
+    "value": "0.75rem",
+    "originalValue": "{typography.fontSize.xs}",
+    "description": "Captions and metadata."
+  },
+  "typography.role.field": {
+    "cssName": "--fs-field",
+    "type": "dimension",
+    "mode": "global",
+    "value": "1rem",
+    "originalValue": "{typography.fontSize.base}",
+    "description": "Text a person types into a field. 16px keeps iOS Safari from zooming on focus."
+  },
   "spacing.0": {
     "cssName": "--space-0",
     "type": "dimension",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/design",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Public put.io design tokens, brand assets, and design-system guidance.",
   "license": "MIT",
   "type": "module",

package/system/components.css

@@ -41,7 +41,7 @@
 button {
   font-family: var(--font-sans);
   font-weight: var(--fw-medium);
-  font-size: calc(var(--button-label-size) * var(--tw-fs, 1));  /* production button = fontSize 0 (0.875rem) */
+  font-size: calc(var(--button-label-size) * var(--tw-fs, 1));  /* --button-label-size reads the UI role */
   /* Real starting bg so transition has something to interpolate
      from — otherwise UA `buttonface` paints silver until hover. */
   background-color: transparent;
@@ -209,13 +209,13 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   border-bottom: 1px solid var(--line);
 }
 .head .ix {
-  font-family: var(--font-mono); font-size: 11px;
+  font-family: var(--font-mono); font-size: var(--fs-caption);
   color: var(--yellow-text-secondary); letter-spacing: 0.04em;
 }
-.head .t { font-size: 15px; font-weight: 500; color: var(--text); }
+.head .t { font-size: var(--fs-ui); font-weight: 500; color: var(--text); }
 .head .n {
   margin-left: auto;
-  font-size: 12px; color: var(--text-secondary);
+  font-size: var(--fs-caption); color: var(--text-secondary);
 }
 
 
@@ -291,7 +291,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   background: var(--field-bg);
   color: var(--field-text);
   font-family: var(--font-sans);
-  font-size: var(--fs-base);
+  font-size: var(--fs-field);
   transition:
     border-color var(--dur-fast) var(--ease-out),
     box-shadow   var(--dur-fast) var(--ease-out),
@@ -334,7 +334,9 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 .field[data-state="loading"]:focus-visible {
   box-shadow: none;
 }
-.field.mono { font-family: var(--font-mono); font-size: 13px; }
+/* Mono fields keep the field role, not the 0.92em .mono step: under 16px,
+   iOS Safari zooms on focus. */
+.field.mono { font-family: var(--font-mono); font-size: var(--fs-field); }
 
 /* ===========================================================
    Form layout recipes — the rhythm comes from gap, not from
@@ -368,7 +370,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 }
 .form-group .label-row .label { margin-bottom: 0; }
 .form-group .label-row a {
-  font-size: 12px;
+  font-size: var(--fs-ui);
   color: var(--text-secondary);
   text-decoration: none;
   white-space: nowrap;
@@ -395,14 +397,14 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   border-radius: var(--alert-radius);
   background: var(--alert-info-bg);
   color: var(--alert-info-body);
-  font-size: var(--fs-sm);
+  font-size: var(--fs-ui);
   line-height: var(--lh-normal);
 }
 .form-callout[hidden] { display: none; }
 .form-callout > :is(i, svg) {
   flex-shrink: 0;
   color: var(--alert-info-icon);
-  font-size: 14px;
+  font-size: var(--fs-ui);
   line-height: var(--lh-normal);
 }
 .form-callout[data-state="success"] {
@@ -422,7 +424,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   border: 0;
   border-radius: 0;
   background: transparent;
-  font-size: var(--fs-sm);
+  font-size: var(--fs-ui);
 }
 
 /* ===========================================================
@@ -453,7 +455,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 .form-reveal .form-callout { margin: 0; }
 .form-reveal[data-state="open"] { grid-template-rows: 1fr; opacity: 1; }
 /* Inside a .form-group the row absorbs the group gap, so a closed row
-   adds no space and an open one sits the usual 6px under its field. */
+   adds no space and an open one sits the usual 8px under its field. */
 .form-group > .form-reveal { margin-top: -8px; }
 .form-group > .form-reveal .form-callout { padding-top: 8px; }
 
@@ -526,7 +528,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   flex: 0 0 auto;
   padding: 0;
   color: var(--text-secondary);
-  font-size: 18px;
+  font-size: var(--fs-md);
   line-height: 1;
   pointer-events: none;
 }
@@ -569,9 +571,10 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
    Card-less: the form sits on the page background. Logo top-left
    in .auth-header, one left-aligned 340px column centred in
    .auth-main, a quiet link row in .auth-footer. Controls keep the
-   standard 36px box;
-   the title is the only heading. Under 640px the gutters drop to 24px so the logo lines
-   up with the column.
+   standard 36px box; the title is the only heading. All other text
+   (labels, hints, notes, errors, links, footer) is the UI role, --fs-ui;
+   fields take --fs-field. Under
+   640px the gutters drop to 24px so the logo lines up with the column.
    =========================================================== */
 .auth-page {
   box-sizing: border-box;
@@ -614,11 +617,20 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 }
 .auth-column .form-stack { gap: 16px; }
 .auth-column .label {
-  font-size: var(--fs-sm);
+  font-size: var(--fs-ui);
   font-weight: var(--fw-regular);
   color: var(--text-secondary);
 }
-.auth-column form > .form-reveal .form-callout { padding-top: 12px; font-size: var(--fs-base); }
+/* A field hint, a legal line, or a sent-to note. */
+.auth-column .hint,
+.auth-note {
+  margin: 0;
+  font-size: var(--fs-ui);
+  line-height: var(--lh-normal);
+  color: var(--text-secondary);
+}
+.auth-note a { color: var(--text); text-underline-offset: 3px; }
+.auth-column form > .form-reveal .form-callout { padding-top: 8px; }
 .auth-column form > .form-reveal + .btn-block { margin-top: 16px; }
 .auth-links {
   margin: 24px 0 0;
@@ -628,11 +640,12 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   justify-content: space-between;
   gap: 8px 16px;
   color: var(--text-secondary);
-  font-size: var(--fs-base);
+  font-size: var(--fs-ui);
 }
 /* A prompt's link reads as text ("New to put.io? Sign up"); a bare
-   action link ("Use a recovery code") stays muted. */
-.auth-links p { margin: 0; }
+   action link ("Use a recovery code") stays muted. The token base sizes
+   every p at --fs-body, so a prompt inherits the row's size. */
+.auth-links p { margin: 0; font-size: inherit; }
 .auth-links a { color: var(--text); text-underline-offset: 3px; }
 .auth-links > a { color: var(--text-secondary); text-decoration: none; }
 .auth-links > a:hover { color: var(--text); }
@@ -642,7 +655,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
   justify-content: center;
   gap: 8px 16px;
   padding: 24px 32px 28px;
-  font-size: var(--fs-sm);
+  font-size: var(--fs-ui);
 }
 .auth-footer a { color: var(--text-secondary); text-decoration: none; }
 .auth-footer a:hover { color: var(--text); }
@@ -670,7 +683,7 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 }
 .menu-pop .menu-label {
   padding: 8px 8px 4px;
-  font-family: var(--font-mono); font-size: 10.5px;
+  font-family: var(--font-mono); font-size: var(--fs-caption);
   letter-spacing: 0.06em; text-transform: uppercase;
   /* --menu-label, not the generic --text-secondary. Same value in both modes
      today, so this is a retheming fix rather than a visual one: the family owns

package/tokens/components.tokens.json

@@ -519,7 +519,7 @@
       },
       "labelSize": {
         "$type": "dimension",
-        "$value": "{typography.fontSize.sm}",
+        "$value": "{typography.role.ui}",
         "$description": "Uppercase label size.",
         "$extensions": {
           "putio": {

package/tokens/foundation.css

@@ -3,7 +3,8 @@ html {
   background: var(--html-bg);
   color: var(--text);
   font-family: var(--font-sans);
-  font-size: 14px;  /* app.put.io root: fontSize ["14px","14px","15px"] — 15px at ≥ --bp-lg (media query below) */
+  /* The browser default (16px), so text follows the reader's setting. */
+  font-size: 100%;
   line-height: var(--lh-normal);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
@@ -12,16 +13,10 @@ html {
 body {
   background: var(--app-bg);
   color: var(--text);
+  font-size: var(--fs-body);
   margin: 0;
 }
 
-/* Root steps up on desktop, matching app.put.io's responsive base.
-   14px/15px literals must stay in sync with --bp-lg (media queries
-   can't read custom properties). */
-@media (min-width: 1280px) {
-  html { font-size: 15px; }
-}
-
 /* -- Semantic type ------------------------------------------------- */
 
 .h-display, h1.display {
@@ -82,7 +77,7 @@ h4, .h4 {
 
 p, .body {
   font-family: var(--font-sans);
-  font-size: var(--fs-base);
+  font-size: var(--fs-body);
   font-weight: var(--fw-regular);
   line-height: var(--lh-normal);
   margin: 0 0 var(--space-4);
@@ -96,19 +91,19 @@ p, .body {
 }
 
 small, .caption {
-  font-size: var(--fs-sm);  /* production caption = fontSize 0 */
+  font-size: var(--fs-caption);
   color: var(--text-secondary);
 }
 
 .label {
-  font-size: var(--fs-base);  /* production label = fontSize 1, medium */
+  font-size: var(--fs-ui);
   font-weight: var(--fw-medium);
   color: var(--text);
 }
 
 .button-text {
   font-weight: var(--fw-medium);
-  font-size: var(--fs-sm);  /* production button = fontSize 0 */
+  font-size: var(--fs-ui);
   letter-spacing: 0;
 }
 

package/tokens/primitives.tokens.json

@@ -150,6 +150,7 @@
       "xs": {
         "$type": "dimension",
         "$value": "0.75rem",
+        "$description": "12px. Captions: read it through --fs-caption.",
         "$extensions": {
           "putio": {
             "cssName": "fs-xs",
@@ -161,7 +162,7 @@
       "sm": {
         "$type": "dimension",
         "$value": "0.875rem",
-        "$description": "Caption and button labels — production fontSize 0.",
+        "$description": "14px. UI chrome (labels, buttons, links, errors): read it through --fs-ui.",
         "$extensions": {
           "putio": {
             "cssName": "fs-sm",
@@ -173,7 +174,7 @@
       "base": {
         "$type": "dimension",
         "$value": "1rem",
-        "$description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg).",
+        "$description": "16px, the root. Body text and inputs: read it through --fs-body or --fs-field.",
         "$extensions": {
           "putio": {
             "cssName": "fs-base",
@@ -185,7 +186,7 @@
       "md": {
         "$type": "dimension",
         "$value": "1.125rem",
-        "$description": "Subheading.",
+        "$description": "18px. Subheading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-md",
@@ -197,7 +198,7 @@
       "lg": {
         "$type": "dimension",
         "$value": "1.5rem",
-        "$description": "Heading.",
+        "$description": "24px. Heading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-lg",
@@ -208,8 +209,8 @@
       },
       "title": {
         "$type": "dimension",
-        "$value": "22px",
-        "$description": "Screen titles and one-time-code digits. The fixed-pixel sibling of fontSize.lg (H2), which scales with the root.",
+        "$value": "1.375rem",
+        "$description": "22px. Screen titles and one-time-code digits, beside fontSize.lg (H2).",
         "$extensions": {
           "putio": {
             "cssName": "fs-title",
@@ -221,7 +222,7 @@
       "xl": {
         "$type": "dimension",
         "$value": "2rem",
-        "$description": "Page title.",
+        "$description": "32px. Page title.",
         "$extensions": {
           "putio": {
             "cssName": "fs-xl",
@@ -232,8 +233,8 @@
       },
       "2xl": {
         "$type": "dimension",
-        "$value": "48px",
-        "$description": "Fixed display tier — does not scale with the responsive root.",
+        "$value": "3rem",
+        "$description": "48px. Display tier.",
         "$extensions": {
           "putio": {
             "cssName": "fs-2xl",
@@ -244,8 +245,8 @@
       },
       "3xl": {
         "$type": "dimension",
-        "$value": "64px",
-        "$description": "Fixed display tier — does not scale with the responsive root.",
+        "$value": "4rem",
+        "$description": "64px. Display tier.",
         "$extensions": {
           "putio": {
             "cssName": "fs-3xl",
@@ -268,8 +269,8 @@
       },
       "display": {
         "$type": "dimension",
-        "$value": "96px",
-        "$description": "Fixed display tier for brand display moments.",
+        "$value": "6rem",
+        "$description": "96px. Display tier for brand display moments.",
         "$extensions": {
           "putio": {
             "cssName": "fs-display",

package/tokens/semantic.tokens.json

@@ -1460,5 +1460,58 @@
         }
       }
     }
+  },
+  "typography": {
+    "$description": "Text roles. Components choose a role, not a size step.",
+    "role": {
+      "ui": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.sm}",
+        "$description": "UI chrome: labels, buttons, nav, links, errors, footers.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-ui",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "body": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.base}",
+        "$description": "Body and long text.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-body",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "caption": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.xs}",
+        "$description": "Captions and metadata.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-caption",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      },
+      "field": {
+        "$type": "dimension",
+        "$value": "{typography.fontSize.base}",
+        "$description": "Text a person types into a field. 16px keeps iOS Safari from zooming on focus.",
+        "$extensions": {
+          "putio": {
+            "cssName": "fs-field",
+            "mode": "global",
+            "figma": true
+          }
+        }
+      }
+    }
   }
 }