@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Tabs/index.tsx

@@ -65,7 +65,7 @@ export interface TabsPanelProps extends React.HTMLAttributes<HTMLDivElement> {
 // ============================================
 
 const TabsVariantContext = React.createContext<"underline" | "pills">("underline");
-const TabsSizeContext = React.createContext<ControlSize>("sm");
+const TabsSizeContext = React.createContext<ControlSize>("md");
 
 // ============================================
 // Components
@@ -82,7 +82,7 @@ function TabsRoot({
   className,
   ...htmlProps
 }: TabsProps) {
-  const size = useResolvedControlSize(sizeProp, "sm");
+  const size = useResolvedControlSize(sizeProp);
   const classes = [styles.root, className].filter(Boolean).join(" ");
 
   return (
@@ -95,6 +95,7 @@ function TabsRoot({
           onValueChange={onValueChange}
           orientation={orientation}
           className={classes}
+          data-slot="tabs"
         >
           {children}
         </BaseTabs.Root>
@@ -114,7 +115,12 @@ function TabsList({ children, variant, size: sizeProp, className, ...htmlProps }
   return (
     <TabsVariantContext.Provider value={resolvedVariant}>
       <TabsSizeContext.Provider value={size}>
-        <BaseTabs.List {...htmlProps} className={classes}>
+        <BaseTabs.List
+          {...htmlProps}
+          className={classes}
+          data-slot="tabs-list"
+          data-variant={resolvedVariant}
+        >
           {children}
           {resolvedVariant === "underline" && <BaseTabs.Indicator className={styles.indicator} />}
         </BaseTabs.List>
@@ -131,7 +137,7 @@ function Tab({ children, value, disabled, className }: TabProps) {
   const classes = [styles.tab, sizeClass, variantClass, className].filter(Boolean).join(" ");
 
   return (
-    <BaseTabs.Tab value={value} disabled={disabled} className={classes}>
+    <BaseTabs.Tab value={value} disabled={disabled} className={classes} data-slot="tabs-tab">
       {children}
     </BaseTabs.Tab>
   );
@@ -148,7 +154,13 @@ function TabsPanel({
   const classes = [styles.panel, flush && styles.panelFlush, className].filter(Boolean).join(" ");
 
   return (
-    <BaseTabs.Panel {...htmlProps} value={value} keepMounted={keepMounted} className={classes}>
+    <BaseTabs.Panel
+      {...htmlProps}
+      value={value}
+      keepMounted={keepMounted}
+      className={classes}
+      data-slot="tabs-panel"
+    >
       {children}
     </BaseTabs.Panel>
   );

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

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Text",
-  "description": "Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements.",
+  "description": "Applies the type scale to any text element, without hand-rolling font rules.",
   "category": "display",
-  "tags": [
-    "text",
-    "typography",
-    "heading",
-    "paragraph",
-    "font"
-  ],
+  "tags": ["text", "typography", "heading", "paragraph", "font"],
   "status": "stable",
   "sourcePath": "src/components/Text/index.tsx",
   "exportName": "Text",
@@ -19,7 +13,7 @@
     "variant: section-label",
     "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl",
     "weight: normal|medium|semibold|bold (default: \"normal\")",
-    "color: primary|secondary|tertiary|muted|success|warning|danger (default: \"primary\")",
+    "color: primary|secondary|tertiary|muted|accent|success|warning|danger (default: \"primary\")",
     "font: sans|mono (default: sans)",
     "truncate: boolean",
     "lineClamp: number",
@@ -67,63 +61,34 @@
       "type": "enum",
       "description": "Preset text variant",
       "required": false,
-      "values": [
-        "section-label"
-      ]
+      "values": ["section-label", "eyebrow"]
     },
     "size": {
       "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).",
       "required": false,
-      "values": [
-        "2xs",
-        "xs",
-        "sm",
-        "base",
-        "md",
-        "lg",
-        "xl",
-        "2xl",
-        "3xl",
-        "4xl"
-      ]
+      "values": ["2xs", "xs", "sm", "base", "md", "lg", "xl", "2xl", "3xl", "4xl"]
     },
     "weight": {
       "type": "enum",
       "description": "Font weight",
       "default": "\"normal\"",
       "required": false,
-      "values": [
-        "normal",
-        "medium",
-        "semibold",
-        "bold"
-      ]
+      "values": ["normal", "medium", "semibold", "bold"]
     },
     "color": {
       "type": "enum",
-      "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 \u2014 prefer Badge or Alert when the state deserves a container)",
+      "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",
-        "success",
-        "warning",
-        "danger"
-      ]
+      "values": ["primary", "secondary", "tertiary", "muted", "accent", "success", "warning", "danger"]
     },
     "font": {
       "type": "enum",
       "description": "Font family",
       "default": "sans",
       "required": false,
-      "values": [
-        "sans",
-        "mono"
-      ]
+      "values": ["sans", "mono"]
     },
     "truncate": {
       "type": "boolean",
@@ -143,57 +108,55 @@
   },
   "usage": {
     "when": [
-      "Displaying text with specific typography styles",
-      "Creating headings, paragraphs, or labels",
-      "Text that needs truncation or line clamping",
-      "Consistent typography across the application"
+      "Any text that should sit on the type scale",
+      "Headings and paragraphs that need real tags",
+      "Text that must truncate or clamp"
     ],
     "whenNot": [
-      "Complex rich text (use a rich text editor)",
-      "Code display (use CodeBlock)",
-      "Interactive text (use Link or Button)"
+      "Rich or authored content (use Markdown)",
+      "Code (use CodeBlock)",
+      "Anything clickable (use Link or Button)"
     ],
     "guidelines": [
-      "Use semantic elements (h1-h6, p) via the \"as\" prop",
-      "Maintain heading hierarchy for accessibility",
-      "Use color variants sparingly for visual hierarchy",
-      "Consider truncation for user-generated content"
+      "Pick the tag with as, the look with size — 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"
     ],
     "accessibility": [
-      "Use proper heading levels (h1-h6) for document structure",
-      "Semantic elements convey meaning to screen readers",
-      "Truncated text should have full content in title/tooltip"
+      "as keeps the document outline intact for screen readers",
+      "Clamped text still exposes its full content to assistive tech"
     ]
   },
   "examples": [
     {
       "name": "Sizes",
-      "description": "Different text sizes",
+      "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>"
     },
     {
       "name": "Weights",
-      "description": "Different font weights",
+      "description": "Four weights — reach past semibold only for real emphasis.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text weight=\"normal\">Normal weight</Text>\n  <Text weight=\"medium\">Medium weight</Text>\n  <Text weight=\"semibold\">Semibold weight</Text>\n  <Text weight=\"bold\">Bold weight</Text>\n</div>"
     },
     {
       "name": "Colors",
-      "description": "Different text colors",
+      "description": "Dimmer tones push text back; success and danger carry state.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text color=\"primary\">Primary color (default)</Text>\n  <Text color=\"secondary\">Secondary color</Text>\n  <Text color=\"tertiary\">Tertiary color</Text>\n  <Text color=\"muted\">Muted color (alias for tertiary)</Text>\n</div>"
     },
     {
       "name": "Semantic Elements",
-      "description": "Using appropriate HTML 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>"
     },
     {
       "name": "Monospace",
-      "description": "Monospace font for code-like text",
+      "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>"
     },
     {
       "name": "Truncation",
-      "description": "Text truncation with ellipsis",
+      "description": "One line with an ellipsis, or clamp to a set number of lines.",
       "code": "<div style={{ width: '200px', display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text truncate>\n    This is a very long text that will be truncated with an ellipsis when it overflows.\n  </Text>\n  <Text truncate lineClamp={2}>\n    This text will be clamped to two lines. Any content beyond two lines\n    will be hidden and replaced with an ellipsis at the end.\n  </Text>\n</div>"
     }
   ],
@@ -219,21 +182,16 @@
       "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)",
       "weight: normal|medium|semibold|bold - font weight",
-      "color: primary|secondary|tertiary|muted|success|warning|danger - text color (muted = tertiary; semantic colours for inline state)",
+      "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",
       "truncate: boolean - enable truncation",
       "lineClamp: number - max lines"
     ],
-    "a11yRules": [
-      "A11Y_HEADING_HIERARCHY",
-      "A11Y_SEMANTIC_ELEMENTS"
-    ]
+    "a11yRules": ["A11Y_HEADING_HIERARCHY", "A11Y_SEMANTIC_ELEMENTS"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -1,5 +1,6 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/typography" as typography;
 
 .text {
   font-family: var(--fui-font-sans, $fui-font-sans);
@@ -9,7 +10,37 @@
 
 // Variants
 .variant-section-label {
-  @include section-label-text;
+  @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 {
+  @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);
+}
+
+@each $role
+  in (
+    "caption",
+    "ui-compact",
+    "ui-standard",
+    "body-compact",
+    "body-relaxed",
+    "title-sm",
+    "title-md",
+    "title-lg",
+    "display",
+    "code"
+  )
+{
+  .role-#{$role} {
+    @include typography.role($role);
+  }
 }
 
 // Font sizes
@@ -88,22 +119,27 @@
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
+.color-accent {
+  color: var(--fui-color-accent, $fui-color-accent);
+}
+
 // Semantic colours, for a run of text that carries a state on its own — a
 // count going over budget, an inline "expired", a figure in the red. Where
 // there is a component for the job (Badge, Alert, Callout) use that instead:
 // this is for the cases where the state is one word inside a line, and
 // wrapping it in a box would be more chrome than the fact is worth. Colour is
-// never the only carrier — the words still have to say it.
+// never the only carrier — the words still have to say it. Text uses the
+// same *-text stop as Badge so inline ink and chips stay one family.
 .color-success {
-  color: var(--fui-color-success, $fui-color-success);
+  color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
 .color-warning {
-  color: var(--fui-color-warning, $fui-color-warning);
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
 .color-danger {
-  color: var(--fui-color-danger, $fui-color-danger);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
 // Font family

package/src/components/Text/index.tsx

@@ -1,32 +1,71 @@
-import * as React from 'react';
-import styles from './Text.module.scss';
+import * as React from "react";
+import styles from "./Text.module.scss";
+import { isProductionBuild } from "../../utils/env";
 
 /**
  * Typography component for rendering text with consistent styling.
  * @see https://usefragments.com/components/text
  */
-export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+export type TextRole =
+  | "caption"
+  | "ui-compact"
+  | "ui-standard"
+  | "body-compact"
+  | "body-relaxed"
+  | "title-sm"
+  | "title-md"
+  | "title-lg"
+  | "display"
+  | "code";
+
+export type TextSize = "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";
+
+type TextSharedProps = Omit<React.HTMLAttributes<HTMLElement>, "color" | "role"> & {
   children: React.ReactNode;
   /** HTML element to render.
    * @default "span" */
-  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';
-  /** Preset text variant */
-  variant?: 'section-label';
-  /** Font size. Steps up the scale: 2xs (10), xs (12), sm/base (14), md (15 prose body),
-   * lg (20), xl (24), 2xl (30), 3xl (36 page title), 4xl (48 hero).
-   * @see https://usefragments.com/components/text#sizes */
-  size?: '2xs' | 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
-  /** Font weight.
-   * @default "normal" */
-  weight?: 'normal' | 'medium' | 'semibold' | 'bold';
-  /** Text color. `"muted"` is an alias for `"tertiary"`. `"success" | "warning" | "danger"`
+  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";
+  /** Text color. `"muted"` is an alias for `"tertiary"`. `"accent"` is the brand
+   * spend for one word inside a line (a repo name). `"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" */
-  color?: 'primary' | 'secondary' | 'tertiary' | 'muted' | 'success' | 'warning' | 'danger';
-  /** Font family.
-   * @default "sans" */
-  font?: 'sans' | 'mono';
+  color?:
+    | "primary"
+    | "secondary"
+    | "tertiary"
+    | "muted"
+    | "accent"
+    | "success"
+    | "warning"
+    | "danger";
   /** Truncate text with ellipsis when it overflows */
   truncate?: boolean;
   /** Number of lines before truncating (requires truncate=true) */
@@ -34,59 +73,93 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'colo
   /** 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?: 'normal' | 'tight' | 'tighter' | 'tightest';
   /** Use tabular (fixed-width) numerals so digits align in columns. Ideal for
    * stat values, tables, timestamps, and any updating number. */
   tabularNums?: boolean;
-}
+};
+
+type TextRoleProps = {
+  role: TextRole;
+  size?: never;
+  variant?: never;
+  weight?: never;
+  font?: never;
+  letterSpacing?: never;
+};
+
+type TextLegacyScaleProps = {
+  role?: never;
+  size?: TextSize;
+  variant?: "section-label" | "eyebrow";
+  weight?: TextWeight;
+  font?: TextFont;
+  letterSpacing?: TextTracking;
+};
 
-const TextRoot = React.forwardRef<HTMLElement, TextProps>(
-  function Text(
-    {
-      children,
-      as: Component = 'span',
-      variant,
-      size,
-      weight,
-      color,
-      font = 'sans',
-      truncate,
-      lineClamp,
-      letterSpacing,
-      tabularNums,
-      className,
-      style,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const classes = [
-      styles.text,
-      variant && styles[`variant-${variant}`],
-      size && styles[`size-${size}`],
-      weight && styles[`weight-${weight}`],
-      color && styles[`color-${color}`],
-      font === 'mono' && styles.mono,
-      truncate && styles.truncate,
-      lineClamp && styles.lineClamp,
-      letterSpacing && styles[`tracking-${letterSpacing}`],
-      tabularNums && styles.tabularNums,
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
+export type TextProps = TextSharedProps & (TextRoleProps | TextLegacyScaleProps);
 
-    const lineClampStyle = lineClamp
-      ? { '--fui-line-clamp': lineClamp, ...style } as React.CSSProperties
-      : style;
+const TextRoot = React.forwardRef<HTMLElement, TextProps>(function Text(
+  {
+    children,
+    as: Component = "span",
+    role,
+    variant,
+    size,
+    weight,
+    color,
+    font,
+    truncate,
+    lineClamp,
+    letterSpacing,
+    tabularNums,
+    className,
+    style,
+    ...htmlProps
+  },
+  ref
+) {
+  const ignoredLegacyProps = role
+    ? [size, variant, weight, font, letterSpacing].some((value) => value !== undefined)
+    : false;
 
-    return (
-      <Component ref={ref as React.Ref<never>} className={classes} style={lineClampStyle} {...htmlProps}>
-        {children}
-      </Component>
+  if (!isProductionBuild() && ignoredLegacyProps) {
+    console.warn(
+      "[Text] Semantic role takes precedence over size, variant, weight, font, and letterSpacing."
     );
   }
-);
+
+  const classes = [
+    styles.text,
+    role && styles[`role-${role}`],
+    !role && variant && styles[`variant-${variant}`],
+    !role && size && styles[`size-${size}`],
+    !role && weight && styles[`weight-${weight}`],
+    color && styles[`color-${color}`],
+    !role && font === "mono" && styles.mono,
+    truncate && styles.truncate,
+    lineClamp && styles.lineClamp,
+    !role && letterSpacing && styles[`tracking-${letterSpacing}`],
+    tabularNums && styles.tabularNums,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const lineClampStyle = lineClamp
+    ? ({ "--fui-line-clamp": lineClamp, ...style } as React.CSSProperties)
+    : style;
+
+  return (
+    <Component
+      ref={ref as React.Ref<never>}
+      className={classes}
+      style={lineClampStyle}
+      {...htmlProps}
+    >
+      {children}
+    </Component>
+  );
+});
 
 export const Text = Object.assign(TextRoot, {
   Root: TextRoot,