@usefragments/ui 1.7.0 → 2.0.0

package/src/components/Tabs/Tabs.contract.json

@@ -13,7 +13,7 @@
     "value: string",
     "onValueChange: function",
     "orientation: horizontal|vertical (default: horizontal)",
-    "variant: underline|pills (default: underline)"
+    "variant: ghost|soft (default: ghost)"
   ],
   "props": {
     "children": {
@@ -45,10 +45,10 @@
     },
     "variant": {
       "type": "enum",
-      "description": "Default visual style for Tabs.List (can be overridden on Tabs.List)",
-      "default": "underline",
+      "description": "Default chrome for Tabs.List (can be overridden on Tabs.List): ghost draws a rule under the active tab, soft is a filled rail with a selected segment",
+      "default": "ghost",
       "required": false,
-      "values": ["underline", "pills"]
+      "values": ["ghost", "soft"]
     }
   },
   "usage": {
@@ -69,7 +69,7 @@
       "Order by how often each panel is used",
       "Past five or six tabs, split the page instead",
       "Keep panels comparable in depth",
-      "Pills inside cards, underline at page level"
+      "Soft rails inside cards, ghost at page level"
     ],
     "accessibility": [
       "Keyboard navigation with arrow keys",
@@ -79,24 +79,24 @@
   },
   "examples": [
     {
-      "name": "Underline",
+      "name": "Ghost",
       "description": "A rule tracks the active panel.",
-      "code": "<Tabs defaultValue=\"overview\" variant=\"underline\">\n  <Tabs.List>\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"analytics\">Analytics</Tabs.Tab>\n    <Tabs.Tab value=\"settings\">Settings</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Overview content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"analytics\">\n    <p>Analytics content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"settings\">\n    <p>Settings content goes here.</p>\n  </Tabs.Panel>\n</Tabs>"
+      "code": "<Tabs defaultValue=\"overview\" variant=\"ghost\">\n  <Tabs.List>\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"analytics\">Analytics</Tabs.Tab>\n    <Tabs.Tab value=\"settings\">Settings</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Overview content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"analytics\">\n    <p>Analytics content goes here.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"settings\">\n    <p>Settings content goes here.</p>\n  </Tabs.Panel>\n</Tabs>"
     },
     {
-      "name": "Pills",
-      "description": "A filled track suits panels inside a card.",
-      "code": "<Tabs defaultValue=\"all\" variant=\"pills\">\n  <Tabs.List>\n    <Tabs.Tab value=\"all\">All</Tabs.Tab>\n    <Tabs.Tab value=\"active\">Active</Tabs.Tab>\n    <Tabs.Tab value=\"archived\">Archived</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"all\">\n    <p>Showing all items.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"active\">\n    <p>Showing active items only.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"archived\">\n    <p>Showing archived items.</p>\n  </Tabs.Panel>\n</Tabs>"
+      "name": "Soft",
+      "description": "A filled rail suits panels inside a card.",
+      "code": "<Tabs defaultValue=\"all\" variant=\"soft\">\n  <Tabs.List>\n    <Tabs.Tab value=\"all\">All</Tabs.Tab>\n    <Tabs.Tab value=\"active\">Active</Tabs.Tab>\n    <Tabs.Tab value=\"archived\">Archived</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"all\">\n    <p>Showing all items.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"active\">\n    <p>Showing active items only.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"archived\">\n    <p>Showing archived items.</p>\n  </Tabs.Panel>\n</Tabs>"
     },
     {
       "name": "With Disabled",
       "description": "An unavailable panel stays visible but unreachable.",
-      "code": "<Tabs defaultValue=\"general\" variant=\"underline\">\n  <Tabs.List>\n    <Tabs.Tab value=\"general\">General</Tabs.Tab>\n    <Tabs.Tab value=\"security\">Security</Tabs.Tab>\n    <Tabs.Tab value=\"billing\" disabled>Billing</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"general\">\n    <p>General settings panel.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"security\">\n    <p>Security settings panel.</p>\n  </Tabs.Panel>\n</Tabs>"
+      "code": "<Tabs defaultValue=\"general\" variant=\"ghost\">\n  <Tabs.List>\n    <Tabs.Tab value=\"general\">General</Tabs.Tab>\n    <Tabs.Tab value=\"security\">Security</Tabs.Tab>\n    <Tabs.Tab value=\"billing\" disabled>Billing</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"general\">\n    <p>General settings panel.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"security\">\n    <p>Security settings panel.</p>\n  </Tabs.Panel>\n</Tabs>"
     },
     {
       "name": "List Variant Override",
       "description": "One list can opt out of the root's style.",
-      "code": "<Tabs defaultValue=\"overview\" variant=\"pills\">\n  <Tabs.List variant=\"underline\">\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"activity\">Activity</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Root sets pills, but this list overrides to underline.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"activity\">\n    <p>Per-list variant override example.</p>\n  </Tabs.Panel>\n</Tabs>"
+      "code": "<Tabs defaultValue=\"overview\" variant=\"soft\">\n  <Tabs.List variant=\"ghost\">\n    <Tabs.Tab value=\"overview\">Overview</Tabs.Tab>\n    <Tabs.Tab value=\"activity\">Activity</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel value=\"overview\">\n    <p>Root sets soft, but this list overrides to ghost.</p>\n  </Tabs.Panel>\n  <Tabs.Panel value=\"activity\">\n    <p>Per-list variant override example.</p>\n  </Tabs.Panel>\n</Tabs>"
     }
   ],
   "relations": [
@@ -116,8 +116,8 @@
       "value: string - controlled active tab",
       "defaultValue: string - initial active tab",
       "onValueChange: (value) => void - tab change handler",
-      "variant: underline|pills - default style for Tabs.List",
-      "Tabs.List variant?: underline|pills - optional per-list override"
+      "variant: ghost|soft - default chrome for Tabs.List",
+      "Tabs.List variant?: ghost|soft - optional per-list override"
     ],
     "a11yRules": ["A11Y_TABS_KEYBOARD", "A11Y_TABS_LABELS"]
   },

package/src/components/Tabs/Tabs.module.scss

@@ -1,5 +1,6 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/layout";
 @use "../../recipes/segmented";
 
@@ -14,37 +15,39 @@
   }
 }
 
-// Tab list container
+// Tab list container (ghost: a rule under the row, the indicator tracks the active tab)
 .list {
   position: relative;
   display: flex;
   align-items: center;
   gap: layout.gap("xs");
-  border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--fui-border, $fui-border);
   padding-inline: layout.gap("xs");
 
   &[data-orientation="vertical"] {
     flex-direction: column;
     align-items: stretch;
     border-bottom: none;
-    border-right: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+    border-right: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+      var(--fui-border, $fui-border);
     padding-block: layout.gap("xs");
-    padding-inline: 0;
+    padding-inline: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   }
 }
 
-// Variant: pills (shadcn-style with background container)
-.listPills {
+// Variant: soft (filled rail with a selected segment)
+.listSoft {
   border-bottom: none;
   border: 0;
   background-color: var(
     --fui-tabs-pills-bg,
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent)
   );
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  padding: 0;
-  gap: 0;
-  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+  border-radius: var(--fui-radius-l1, $fui-radius-l1);
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  gap: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline})
     var(
       --fui-tabs-pills-border,
       color-mix(in srgb, var(--fui-border, #{$fui-border}) 72%, transparent)
@@ -52,11 +55,6 @@
   width: fit-content;
 }
 
-// Variant: underline (default, with indicator line)
-.listUnderline {
-  // Default styles already applied to .list
-}
-
 // Individual tab button
 .tab {
   @include button-reset;
@@ -65,7 +63,7 @@
   position: relative;
   color: var(--fui-text-secondary, $fui-text-secondary);
   white-space: nowrap;
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  border-radius: var(--fui-radius-l3, $fui-radius-l3);
 
   &:hover:not([data-disabled]) {
     color: var(--fui-text-primary, $fui-text-primary);
@@ -105,18 +103,18 @@
   }
 }
 
-// Tab in underline variant
-.tabUnderline {
-  border-radius: 0;
+// Tab in the ghost variant: the indicator carries the selection, the tab stays flat
+.tabGhost {
+  border-radius: var(--fui-radius-none, #{$fui-radius-none});
 
   &:hover:not([data-disabled]) {
     background-color: transparent;
   }
 }
 
-// Tab in pills variant (shadcn-style)
-.tabPills {
-  border-radius: var(--fui-radius-md, $fui-radius-md);
+// Tab in the soft variant: a segment on the rail
+.tabSoft {
+  border-radius: var(--fui-radius-l2, $fui-radius-l2);
   transition:
     background-color var(--fui-transition-fast, $fui-transition-fast),
     color var(--fui-transition-fast, $fui-transition-fast),
@@ -128,18 +126,16 @@
   }
 
   &[data-active] {
-    background-color: var(--fui-tabs-pill-active-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-    color: var(--fui-text-primary, $fui-text-primary);
-    box-shadow: var(--fui-tabs-pill-active-shadow, none);
+    @include segmented-selection;
   }
 }
 
-// Animated indicator (underline variant)
+// Animated indicator (ghost variant)
 .indicator {
   position: absolute;
   bottom: 0;
   left: 0;
-  height: var(--fui-stroke-default, 2px);
+  height: var(--fui-stroke-default, #{$fui-stroke-default});
   background-color: var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
 
@@ -155,7 +151,7 @@
     left: auto;
     right: 0;
     top: 0;
-    width: var(--fui-stroke-default, 2px);
+    width: var(--fui-stroke-default, #{$fui-stroke-default});
     height: var(--active-tab-height);
     transform: translateY(var(--active-tab-top));
   }
@@ -164,7 +160,7 @@
 // Tab panel content
 .panel {
   padding-block: layout.gap("sm");
-  padding-inline: 0;
+  padding-inline: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   outline: none;
 
   &[data-hidden] {
@@ -174,11 +170,11 @@
   // Focus visible for keyboard navigation
   &:focus-visible {
     @include focus-ring;
-    border-radius: var(--fui-radius-md, $fui-radius-md);
+    border-radius: var(--fui-radius-l2, $fui-radius-l2);
   }
 }
 
 // Panel with no padding (for custom layouts)
 .panelFlush {
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }

package/src/components/Tabs/index.tsx

@@ -10,6 +10,7 @@ import styles from "./Tabs.module.scss";
 // ============================================
 
 export type TabValue = string;
+export type TabsVariant = "ghost" | "soft";
 export type TabsChangeEventDetails = Parameters<
   NonNullable<React.ComponentProps<typeof BaseTabs.Root>["onValueChange"]>
 >[1];
@@ -29,19 +30,20 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "d
   /** Tab layout direction.
    * @default "horizontal" */
   orientation?: "horizontal" | "vertical";
-  /** Tab list visual style (default for Tabs.List).
-   * @default "underline" */
-  variant?: "underline" | "pills";
+  /** Tab list chrome (default for Tabs.List): `ghost` draws a rule under the
+   * active tab, `soft` is a filled rail with a selected segment.
+   * @default "ghost" */
+  variant?: TabsVariant;
   /** Tab control size. Defaults to the component-default control size. */
   size?: ControlSize;
 }
 
 export interface TabsListProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  /** Tab list visual style.
-   * @default "underline"
+  /** Tab list chrome.
+   * @default "ghost"
    * @see https://usefragments.com/components/tabs#variants */
-  variant?: "underline" | "pills";
+  variant?: TabsVariant;
   /** Tab control size. Defaults to the nearest Tabs root or provider default. */
   size?: ControlSize;
 }
@@ -64,7 +66,7 @@ export interface TabsPanelProps extends React.HTMLAttributes<HTMLDivElement> {
 // Context for variant
 // ============================================
 
-const TabsVariantContext = React.createContext<"underline" | "pills">("underline");
+const TabsVariantContext = React.createContext<TabsVariant>("ghost");
 const TabsSizeContext = React.createContext<ControlSize>("md");
 
 // ============================================
@@ -77,7 +79,7 @@ function TabsRoot({
   value,
   onValueChange,
   orientation = "horizontal",
-  variant = "underline",
+  variant = "ghost",
   size: sizeProp,
   className,
   ...htmlProps
@@ -109,8 +111,9 @@ function TabsList({ children, variant, size: sizeProp, className, ...htmlProps }
   const rootSize = React.useContext(TabsSizeContext);
   const size = sizeProp ?? rootSize;
   const resolvedVariant = variant ?? rootVariant;
-  const variantClass = resolvedVariant === "pills" ? styles.listPills : styles.listUnderline;
-  const classes = [styles.list, variantClass, className].filter(Boolean).join(" ");
+  const classes = [styles.list, resolvedVariant === "soft" && styles.listSoft, className]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <TabsVariantContext.Provider value={resolvedVariant}>
@@ -122,7 +125,7 @@ function TabsList({ children, variant, size: sizeProp, className, ...htmlProps }
           data-variant={resolvedVariant}
         >
           {children}
-          {resolvedVariant === "underline" && <BaseTabs.Indicator className={styles.indicator} />}
+          {resolvedVariant === "ghost" && <BaseTabs.Indicator className={styles.indicator} />}
         </BaseTabs.List>
       </TabsSizeContext.Provider>
     </TabsVariantContext.Provider>
@@ -132,7 +135,7 @@ function TabsList({ children, variant, size: sizeProp, className, ...htmlProps }
 function Tab({ children, value, disabled, className }: TabProps) {
   const variant = React.useContext(TabsVariantContext);
   const size = React.useContext(TabsSizeContext);
-  const variantClass = variant === "pills" ? styles.tabPills : styles.tabUnderline;
+  const variantClass = variant === "soft" ? styles.tabSoft : styles.tabGhost;
   const sizeClass = size === "sm" ? styles.tabSm : size === "lg" ? styles.tabLg : styles.tabMd;
   const classes = [styles.tab, sizeClass, variantClass, className].filter(Boolean).join(" ");
 

package/src/components/Text/Text.contract.json

@@ -10,8 +10,8 @@
   "propsSummary": [
     "children: node (required)",
     "as: h1|h2|h3|h4|h5|h6|p|span|label|div|strong|em|small|mark|del|ins|sub|sup|time|address|blockquote|cite|code|abbr (default: span)",
-    "variant: section-label",
-    "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl",
+    "role: caption|ui-compact|ui-standard|body-compact|body-relaxed|title-sm|title-md|title-lg|code|section-label|eyebrow",
+    "scale: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl",
     "weight: normal|medium|semibold|bold (default: \"normal\")",
     "color: primary|secondary|tertiary|muted|accent|success|warning|danger (default: \"primary\")",
     "font: sans|mono (default: sans)",
@@ -57,15 +57,27 @@
         "abbr"
       ]
     },
-    "variant": {
+    "role": {
       "type": "enum",
-      "description": "Preset text variant",
+      "description": "Typography role: one named setting of size, weight, line height and tracking. section-label is the small list heading; eyebrow is the small semibold label above a statement. A role owns the whole setting, so scale, weight, font and letterSpacing are unavailable beside it.",
       "required": false,
-      "values": ["section-label", "eyebrow"]
+      "values": [
+        "caption",
+        "ui-compact",
+        "ui-standard",
+        "body-compact",
+        "body-relaxed",
+        "title-sm",
+        "title-md",
+        "title-lg",
+        "code",
+        "section-label",
+        "eyebrow"
+      ]
     },
-    "size": {
+    "scale": {
       "type": "enum",
-      "description": "Font size. 2xs (10), xs (12), sm/base (14), md (15 prose body), lg (20), xl (24), 2xl (30), 3xl (36 page title), 4xl (48 hero).",
+      "description": "Type-scale step for text with no role. 2xs (10), xs (12), sm/base (14), md (15 prose body), lg (20), xl (24), 2xl (30), 3xl (36 page title), 4xl (48 hero).",
       "required": false,
       "values": ["2xs", "xs", "sm", "base", "md", "lg", "xl", "2xl", "3xl", "4xl"]
     },
@@ -81,7 +93,16 @@
       "description": "Text color (muted is an alias for tertiary; success/warning/danger are for a run of text that carries a state on its own — prefer Badge or Alert when the state deserves a container)",
       "default": "\"primary\"",
       "required": false,
-      "values": ["primary", "secondary", "tertiary", "muted", "accent", "success", "warning", "danger"]
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "muted",
+        "accent",
+        "success",
+        "warning",
+        "danger"
+      ]
     },
     "font": {
       "type": "enum",
@@ -118,7 +139,7 @@
       "Anything clickable (use Link or Button)"
     ],
     "guidelines": [
-      "Pick the tag with as, the look with size — they are separate decisions",
+      "Pick the tag with as, the look with role (or scale) — they are separate decisions",
       "Never skip heading levels to get a smaller heading",
       "Color is for hierarchy and state, not decoration",
       "Truncated text needs the full string in title or a tooltip"
@@ -130,9 +151,9 @@
   },
   "examples": [
     {
-      "name": "Sizes",
+      "name": "Scale",
       "description": "Ten steps from caption to hero, all on the same scale.",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text size=\"2xs\">Extra extra small (2xs — 10px)</Text>\n  <Text size=\"xs\">Extra small (xs — 12px)</Text>\n  <Text size=\"sm\">Small (sm — 14px)</Text>\n  <Text size=\"base\">Base size (14px)</Text>\n  <Text size=\"md\">Medium prose body (md — 15px)</Text>\n  <Text size=\"lg\">Large (lg — 20px)</Text>\n  <Text size=\"xl\">Extra large (xl — 24px)</Text>\n  <Text size=\"2xl\">Extra extra large (2xl — 30px)</Text>\n  <Text size=\"3xl\">Page title (3xl — 36px)</Text>\n  <Text size=\"4xl\">Hero display (4xl — 48px)</Text>\n</div>"
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text scale=\"2xs\">Extra extra small (2xs — 10px)</Text>\n  <Text scale=\"xs\">Extra small (xs — 12px)</Text>\n  <Text scale=\"sm\">Small (sm — 14px)</Text>\n  <Text scale=\"base\">Base size (14px)</Text>\n  <Text scale=\"md\">Medium prose body (md — 15px)</Text>\n  <Text scale=\"lg\">Large (lg — 20px)</Text>\n  <Text scale=\"xl\">Extra large (xl — 24px)</Text>\n  <Text scale=\"2xl\">Extra extra large (2xl — 30px)</Text>\n  <Text scale=\"3xl\">Page title (3xl — 36px)</Text>\n  <Text scale=\"4xl\">Hero display (4xl — 48px)</Text>\n</div>"
     },
     {
       "name": "Weights",
@@ -147,12 +168,12 @@
     {
       "name": "Semantic Elements",
       "description": "The as prop picks the tag, so the outline stays correct.",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text as=\"h1\" size=\"3xl\" weight=\"semibold\">Heading 1</Text>\n  <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Heading 2</Text>\n  <Text as=\"h3\" size=\"lg\" weight=\"semibold\">Heading 3</Text>\n  <Text as=\"p\" size=\"md\" color=\"secondary\">\n    This is a paragraph of text that demonstrates the Text component\n    with semantic paragraph element.\n  </Text>\n</div>"
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text as=\"h1\" scale=\"3xl\" weight=\"semibold\">Heading 1</Text>\n  <Text as=\"h2\" scale=\"xl\" weight=\"semibold\">Heading 2</Text>\n  <Text as=\"h3\" scale=\"lg\" weight=\"semibold\">Heading 3</Text>\n  <Text as=\"p\" scale=\"md\" color=\"secondary\">\n    This is a paragraph of text that demonstrates the Text component\n    with semantic paragraph element.\n  </Text>\n</div>"
     },
     {
       "name": "Monospace",
       "description": "Fixed width for IDs, keys, and anything meant to be compared.",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text font=\"mono\" size=\"sm\">const greeting = \"Hello, World!\";</Text>\n  <Text font=\"mono\" size=\"sm\" color=\"secondary\">npm install @usefragments/ui</Text>\n</div>"
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text font=\"mono\" scale=\"sm\">const greeting = \"Hello, World!\";</Text>\n  <Text font=\"mono\" scale=\"sm\" color=\"secondary\">npm install @usefragments/ui</Text>\n</div>"
     },
     {
       "name": "Truncation",
@@ -180,7 +201,8 @@
   "contract": {
     "propsSummary": [
       "as: string - HTML element",
-      "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl - font size (px: 10/12/14/14/15/20/24/30/36/48)",
+      "role: caption|ui-compact|ui-standard|body-compact|body-relaxed|title-sm|title-md|title-lg|code|section-label|eyebrow - typography role (owns size, weight, line height, tracking)",
+      "scale: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl - type-scale step for text with no role (px: 10/12/14/14/15/20/24/30/36/48)",
       "weight: normal|medium|semibold|bold - font weight",
       "color: primary|secondary|tertiary|muted|accent|success|warning|danger - text color (muted = tertiary; accent = brand spend; semantic colours for inline state)",
       "font: sans|mono - font family",

package/src/components/Text/Text.module.scss

@@ -1,26 +1,25 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/typography" as typography;
 
 .text {
   font-family: var(--fui-font-sans, $fui-font-sans);
   color: var(--fui-text-primary, $fui-text-primary);
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
-// Variants
-.variant-section-label {
+// Label roles: the small list heading and the eyebrow.
+.role-section-label {
   @include typography.role("ui-compact");
 }
 
-// Eyebrow: the small-caps label that names a surface above its statement
-// (page label, card section head). Always tertiary ink — it is never the
-// thing the reader is meant to look at.
-.variant-eyebrow {
+// Eyebrow: the small label that names a surface above its statement (page
+// label, card section head). Caption size, semibold, natural case, always
+// tertiary ink — it is never the thing the reader is meant to look at.
+.role-eyebrow {
   @include typography.role("caption");
   font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
-  letter-spacing: var(--fui-letter-spacing-wide, $fui-letter-spacing-wide);
-  text-transform: uppercase;
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
@@ -43,46 +42,46 @@
   }
 }
 
-// Font sizes
-.size-2xs {
+// Scale steps, for text with no role
+.scale-2xs {
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
 }
 
-.size-xs {
+.scale-xs {
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
 }
 
-.size-sm {
+.scale-sm {
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
 }
 
-.size-base {
+.scale-base {
   font-size: var(--fui-font-size-base, $fui-font-size-base);
 }
 
-.size-md {
+.scale-md {
   font-size: var(--fui-font-size-md, $fui-font-size-md);
 }
 
-.size-lg {
+.scale-lg {
   font-size: var(--fui-font-size-lg, $fui-font-size-lg);
 }
 
-.size-xl {
+.scale-xl {
   font-size: var(--fui-font-size-xl, $fui-font-size-xl);
 }
 
-.size-2xl {
+.scale-2xl {
   font-size: var(--fui-font-size-2xl, $fui-font-size-2xl);
 }
 
-.size-3xl {
+.scale-3xl {
   font-size: var(--fui-font-size-3xl, $fui-font-size-3xl);
   line-height: var(--fui-line-height-display, $fui-line-height-display);
   letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);
 }
 
-.size-4xl {
+.scale-4xl {
   font-size: var(--fui-font-size-4xl, $fui-font-size-4xl);
   line-height: var(--fui-line-height-display, $fui-line-height-display);
   letter-spacing: var(--fui-letter-spacing-display, $fui-letter-spacing-display);

package/src/components/Text/index.tsx

@@ -16,9 +16,11 @@ export type TextRole =
   | "title-md"
   | "title-lg"
   | "display"
-  | "code";
+  | "code"
+  | "section-label"
+  | "eyebrow";
 
-export type TextSize = "2xs" | "xs" | "sm" | "base" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
+export type TextScale = "2xs" | "xs" | "sm" | "base" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
 export type TextWeight = "normal" | "medium" | "semibold" | "bold";
 export type TextFont = "sans" | "mono";
 export type TextTracking = "normal" | "tight" | "tighter" | "tightest";
@@ -70,41 +72,44 @@ type TextSharedProps = Omit<React.HTMLAttributes<HTMLElement>, "color" | "role">
   truncate?: boolean;
   /** Number of lines before truncating (requires truncate=true) */
   lineClamp?: number;
-  /** Letter-spacing preset. `"tight"` suits dense UI chrome labels (-0.01em);
-   * `"tighter"` suits headings and stat values (-0.02em); `"tightest"` suits
-   * display numerics (-0.025em). Omit for the font's default tracking. */
   /** Use tabular (fixed-width) numerals so digits align in columns. Ideal for
    * stat values, tables, timestamps, and any updating number. */
   tabularNums?: boolean;
 };
 
 type TextRoleProps = {
+  /** Typography role: one named setting of size, weight, line height and
+   * tracking. `section-label` is the small list heading; `eyebrow` is the
+   * small semibold label that names a surface above its statement. A role owns the
+   * whole setting, so `scale`, `weight`, `font` and `letterSpacing` are
+   * unavailable beside it. */
   role: TextRole;
-  size?: never;
-  variant?: never;
+  scale?: never;
   weight?: never;
   font?: never;
   letterSpacing?: never;
 };
 
-type TextLegacyScaleProps = {
+type TextScaleProps = {
   role?: never;
-  size?: TextSize;
-  variant?: "section-label" | "eyebrow";
+  /** Step on the type scale, for text that has no role. */
+  scale?: TextScale;
   weight?: TextWeight;
   font?: TextFont;
+  /** Letter-spacing preset. `"tight"` suits dense UI chrome labels (-0.01em);
+   * `"tighter"` suits headings and stat values (-0.02em); `"tightest"` suits
+   * display numerics (-0.025em). Omit for the font's default tracking. */
   letterSpacing?: TextTracking;
 };
 
-export type TextProps = TextSharedProps & (TextRoleProps | TextLegacyScaleProps);
+export type TextProps = TextSharedProps & (TextRoleProps | TextScaleProps);
 
 const TextRoot = React.forwardRef<HTMLElement, TextProps>(function Text(
   {
     children,
     as: Component = "span",
     role,
-    variant,
-    size,
+    scale,
     weight,
     color,
     font,
@@ -118,21 +123,18 @@ const TextRoot = React.forwardRef<HTMLElement, TextProps>(function Text(
   },
   ref
 ) {
-  const ignoredLegacyProps = role
-    ? [size, variant, weight, font, letterSpacing].some((value) => value !== undefined)
+  const ignoredScaleProps = role
+    ? [scale, weight, font, letterSpacing].some((value) => value !== undefined)
     : false;
 
-  if (!isProductionBuild() && ignoredLegacyProps) {
-    console.warn(
-      "[Text] Semantic role takes precedence over size, variant, weight, font, and letterSpacing."
-    );
+  if (!isProductionBuild() && ignoredScaleProps) {
+    console.warn("[Text] A role takes precedence over scale, weight, font, and letterSpacing.");
   }
 
   const classes = [
     styles.text,
     role && styles[`role-${role}`],
-    !role && variant && styles[`variant-${variant}`],
-    !role && size && styles[`size-${size}`],
+    !role && scale && styles[`scale-${scale}`],
     !role && weight && styles[`weight-${weight}`],
     color && styles[`color-${color}`],
     !role && font === "mono" && styles.mono,