@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Text/index.tsx

@@ -1,36 +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 type TextRole =
-  | 'caption'
-  | 'ui-compact'
-  | 'ui-standard'
-  | 'body-compact'
-  | 'body-relaxed'
-  | 'title-sm'
-  | 'title-md'
-  | 'title-lg'
-  | 'code';
+  | "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';
+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'> & {
+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';
-  /** 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';
+  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) */
@@ -55,7 +90,7 @@ type TextRoleProps = {
 type TextLegacyScaleProps = {
   role?: never;
   size?: TextSize;
-  variant?: 'section-label';
+  variant?: "section-label" | "eyebrow";
   weight?: TextWeight;
   font?: TextFont;
   letterSpacing?: TextTracking;
@@ -63,65 +98,68 @@ type TextLegacyScaleProps = {
 
 export type TextProps = TextSharedProps & (TextRoleProps | TextLegacyScaleProps);
 
-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;
+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;
 
-    if (process.env.NODE_ENV !== 'production' && ignoredLegacyProps) {
-      console.warn(
-        '[Text] Semantic role takes precedence over size, variant, weight, font, and letterSpacing.'
-      );
-    }
+  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 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;
+  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>
-    );
-  }
-);
+  return (
+    <Component
+      ref={ref as React.Ref<never>}
+      className={classes}
+      style={lineClampStyle}
+      {...htmlProps}
+    >
+      {children}
+    </Component>
+  );
+});
 
 export const Text = Object.assign(TextRoot, {
   Root: TextRoot,

package/src/components/Textarea/Textarea.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Textarea",
-  "description": "Multi-line text input for longer form content",
-  "category": "forms",
-  "tags": [
-    "input",
-    "text",
-    "form",
-    "multiline"
-  ],
+  "description": "Collects multi-line text for longer form content.",
+  "category": "inputs",
+  "tags": ["input", "text", "form", "multiline"],
   "status": "stable",
   "sourcePath": "src/components/Textarea/index.tsx",
   "exportName": "Textarea",
@@ -78,23 +73,14 @@
       "description": "Resize behavior",
       "default": "vertical",
       "required": false,
-      "values": [
-        "none",
-        "vertical",
-        "horizontal",
-        "both"
-      ]
+      "values": ["none", "vertical", "horizontal", "both"]
     },
     "size": {
       "type": "enum",
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "disabled": {
       "type": "boolean",
@@ -209,61 +195,61 @@
       "Selecting from predefined options (use Select)"
     ],
     "guidelines": [
-      "Set appropriate rows for expected content length",
-      "Use placeholder to show example format",
-      "Show character count when maxLength is set",
-      "Consider auto-resize for better UX"
+      "Set rows to match the expected answer length",
+      "Placeholder shows an example, not the label",
+      "Pair maxLength with showCharCount so the limit is visible",
+      "Use resize=\"none\" only when the layout truly cannot flex"
     ],
     "accessibility": [
-      "Always provide a visible label",
-      "Use helperText for format hints",
-      "Error messages should be descriptive"
+      "Give every textarea a visible label",
+      "Put format hints in helperText, not the placeholder",
+      "Error text says what to fix, not just that it failed"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic textarea with label",
+      "description": "Three rows, draggable from the bottom-right corner.",
       "code": "<Textarea\n  label=\"Description\"\n  placeholder=\"Enter a description...\"\n/>"
     },
     {
       "name": "With Helper Text",
-      "description": "Textarea with additional guidance",
+      "description": "Supporting text sits under the box.",
       "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  helperText=\"Max 500 characters\"\n  maxLength={500}\n/>"
     },
     {
       "name": "Error State",
-      "description": "Textarea showing validation error",
+      "description": "Red border, and helperText becomes the reason.",
       "code": "<Textarea\n  label=\"Comments\"\n  placeholder=\"Add your comments...\"\n  error\n  helperText=\"This field is required\"\n/>"
     },
     {
       "name": "Disabled",
-      "description": "Non-interactive textarea",
+      "description": "Dimmed and unfocusable.",
       "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Cannot edit...\"\n  disabled\n/>"
     },
     {
       "name": "Custom Rows",
-      "description": "Textarea with more visible rows",
+      "description": "rows={6} doubles the visible height before scrolling.",
       "code": "<Textarea\n  label=\"Long Description\"\n  placeholder=\"Enter detailed information...\"\n  rows={6}\n/>"
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
+      "description": "Three heights: sm, md, lg.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '400px' }}>\n  <Textarea label=\"Small\" size=\"sm\" placeholder=\"Small textarea\" />\n  <Textarea label=\"Medium\" size=\"md\" placeholder=\"Medium textarea\" />\n  <Textarea label=\"Large\" size=\"lg\" placeholder=\"Large textarea\" />\n</div>"
     },
     {
-      "name": "With Root Props",
-      "description": "Pass wrapper attributes/styling via rootProps",
-      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Add notes...\"\n  rootProps={{ 'data-demo': 'textarea-wrapper' }}\n/>"
+      "name": "Fixed Height",
+      "description": "resize=\"none\" removes the drag handle so the box stays put.",
+      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Add notes...\"\n  resize=\"none\"\n/>"
     },
     {
       "name": "Success State",
-      "description": "Textarea showing validated/success styling",
+      "description": "Green border confirms the value passed validation.",
       "code": "<Textarea\n  label=\"Bio\"\n  value=\"A short bio about myself.\"\n  success\n  helperText=\"Looks great!\"\n/>"
     },
     {
       "name": "With Character Counter",
-      "description": "Textarea with character count and maxLength",
+      "description": "Live count against maxLength sits below the box.",
       "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  maxLength={200}\n  showCharCount\n/>"
     }
   ],
@@ -289,15 +275,11 @@
       "rootProps: HTMLAttributes<HTMLDivElement> - wrapper element props",
       "...native textarea attributes are supported (readOnly, autoComplete, maxLength, onKeyDown, etc.)"
     ],
-    "a11yRules": [
-      "A11Y_LABEL_REQUIRED"
-    ]
+    "a11yRules": ["A11Y_LABEL_REQUIRED"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Textarea/Textarea.module.scss

@@ -58,9 +58,7 @@
   &[rows="1"] {
     block-size: var(--_fui-field-track);
     min-block-size: var(--_fui-field-track);
-    padding-block: calc(
-      (var(--_fui-field-track) - 1lh - 2 * var(--_fui-field-stroke)) / 2
-    );
+    padding-block: calc((var(--_fui-field-track) - 1lh - 2 * var(--_fui-field-stroke)) / 2);
     overflow-y: hidden;
   }
 }
@@ -166,7 +164,7 @@
 
 @media (prefers-contrast: more) {
   .textarea {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &:focus-visible {

package/src/components/Theme/Theme.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Theme",
-  "description": "Theme management system with provider, toggle, and hook pattern. Supports light, dark, and system modes with localStorage persistence.",
-  "category": "navigation",
-  "tags": [
-    "theme",
-    "dark-mode",
-    "light-mode",
-    "provider",
-    "toggle"
-  ],
+  "description": "Gives every component below it a light, dark, or system color mode, and remembers the choice.",
+  "category": "utilities",
+  "tags": ["theme", "dark-mode", "light-mode", "provider", "toggle"],
   "status": "stable",
   "sourcePath": "src/components/Theme/index.tsx",
   "exportName": "ThemeProvider",
@@ -20,7 +14,8 @@
     "mode: light|dark|system",
     "onModeChange: function",
     "storageKey: string (default: fui-theme)",
-    "attribute: data-theme|class (default: data-theme)"
+    "attribute: data-theme|class (default: data-theme)",
+    "ThemeToggle appearance: group|icon (default: group)"
   ],
   "props": {
     "children": {
@@ -33,31 +28,19 @@
       "description": "Default theme mode for uncontrolled usage",
       "default": "system",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "defaultTheme": {
       "type": "enum",
       "description": "",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "mode": {
       "type": "enum",
       "description": "Controlled theme mode",
       "required": false,
-      "values": [
-        "light",
-        "dark",
-        "system"
-      ]
+      "values": ["light", "dark", "system"]
     },
     "onModeChange": {
       "type": "function",
@@ -75,52 +58,51 @@
       "description": "How to apply theme to DOM",
       "default": "data-theme",
       "required": false,
-      "values": [
-        "data-theme",
-        "class"
-      ]
+      "values": ["data-theme", "class"]
     }
   },
   "usage": {
     "when": [
-      "Providing theme context to an application",
-      "Toggling between light and dark modes",
-      "Respecting system color scheme preference",
-      "Persisting theme preference across sessions"
+      "An app needs light and dark modes",
+      "The user's choice should survive a reload",
+      "You want to honour the OS setting by default"
     ],
     "whenNot": [
-      "Simple one-off color changes (use CSS variables)",
-      "Component-level theming (use component props)"
+      "Recoloring one component (use its props)",
+      "A single one-off color swap (use a CSS variable)"
     ],
     "guidelines": [
-      "Wrap your app with ThemeProvider at the root level",
-      "Use useTheme hook to access theme state in components",
-      "ThemeToggle cycles through light → dark → system",
-      "Use storageKey to customize localStorage key",
-      "Set attribute=\"class\" if your CSS uses .dark class instead of data-theme",
-      "ThemeToggle forwards DOM props (id, data-*, className, handlers) to the toggle group"
+      "ThemeProvider goes at the root, once",
+      "useTheme reads and sets the mode anywhere below it",
+      "storageKey renames the localStorage entry",
+      "attribute=\"class\" if your CSS keys off .dark instead of data-theme",
+      "appearance=\"icon\" for tight toolbars; the default group shows both modes"
     ],
     "accessibility": [
-      "ThemeToggle button has accessible label indicating current mode",
-      "Theme changes are applied via CSS custom properties for smooth transitions",
-      "System preference is detected via prefers-color-scheme media query"
+      "The toggle's label names the mode it is in",
+      "System mode follows prefers-color-scheme"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "ThemeProvider with system default",
-      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeDemo />\n</ThemeProvider>"
+      "description": "Wrap the app once; every token below resolves to the active mode.",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <div\n    style={{\n      padding: '16px',\n      borderRadius: '8px',\n      background: 'var(--fui-bg-elevated)',\n      color: 'var(--fui-text-primary)',\n    }}\n  >\n    Everything inside follows the system color scheme.\n  </div>\n</ThemeProvider>"
     },
     {
       "name": "With Toggle",
-      "description": "ThemeProvider with toggle button",
+      "description": "The toggle cycles light, dark, then back to system.",
       "code": "<ThemeProvider defaultMode=\"light\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>\n    <ThemeToggle />\n    <span>Click to cycle themes</span>\n  </div>\n</ThemeProvider>"
     },
     {
       "name": "Toggle Sizes",
-      "description": "ThemeToggle in different sizes",
+      "description": "Three sizes so the control fits whatever bar holds it.",
       "code": "<ThemeProvider defaultMode=\"light\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '16px' }}>\n    <ThemeToggle size=\"sm\" />\n    <ThemeToggle size=\"md\" />\n    <ThemeToggle size=\"lg\" />\n  </div>\n</ThemeProvider>"
+    },
+    {
+      "name": "Icon Toggle",
+      "description": "A single icon button for toolbars with no room to spare.",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeToggle appearance=\"icon\" aria-label=\"Switch color mode\" />\n</ThemeProvider>"
     }
   ],
   "relations": [
@@ -137,11 +119,10 @@
       "onModeChange: (mode) => void - change handler",
       "attribute: data-theme|class - DOM theme attribute",
       "ThemeToggle size: sm|md|lg - toggle button size",
+      "ThemeToggle appearance: group|icon - segmented or compact icon control (default: group)",
       "ThemeToggle forwards div DOM props to the button group root"
     ],
-    "a11yRules": [
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_TARGET_SIZE_MIN"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Theme/index.tsx

@@ -81,7 +81,7 @@ function ThemeProvider({
   const systemPreference = useSystemPreference();
 
   // Warn on deprecated prop usage (dev only)
-  if (process.env.NODE_ENV !== "production" && defaultTheme !== undefined) {
+  if (!isProductionBuild() && defaultTheme !== undefined) {
     console.warn(
       "[Fragments] ThemeProvider: `defaultTheme` is deprecated. Use `defaultMode` instead. " +
         "`defaultTheme` will be removed in v1.0."
@@ -194,6 +194,7 @@ export { ThemeProvider, ThemeToggle, useTheme };
 // Import + re-export seed derivation types — canonical definitions in utils/seed-derivation.ts
 import type { NeutralPalette, DensityPreset, RadiusStyle } from "../../utils/seed-derivation";
 import { applyMeasurementSelection } from "../../measurements";
+import { isProductionBuild } from "../../utils/env";
 export type { NeutralPalette, DensityPreset, RadiusStyle };
 
 export interface ConfigureThemeOptions {

package/src/components/ThemeToggle/ThemeToggle.module.scss

@@ -11,7 +11,7 @@
   align-items: stretch;
   gap: 0;
   padding: 0;
-  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  background-color: var(--fui-theme-toggle-bg, var(--fui-bg-tertiary, #{$fui-bg-tertiary}));
   border-radius: var(--fui-radius-md, $fui-radius-md);
 }
 
@@ -36,14 +36,28 @@
 }
 
 .toggleButtonActive {
-  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  background-color: var(
+    --fui-theme-toggle-active-bg,
+    var(--fui-control-selected-bg, #{$fui-bg-active})
+  );
   color: var(--fui-text-primary, $fui-text-primary);
-  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+  box-shadow: var(--fui-theme-toggle-active-shadow, none);
 }
 
-// Size variants
+.iconButton {
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+}
+
+// Size variants — nested for the group, same-element for appearance="icon"
 .sizeSm {
-  .toggleButton {
+  .toggleButton,
+  &.toggleButton {
     @include action.icon-only("sm");
 
     svg {
@@ -53,7 +67,8 @@
 }
 
 .sizeMd {
-  .toggleButton {
+  .toggleButton,
+  &.toggleButton {
     @include action.icon-only("md");
 
     svg {
@@ -63,7 +78,8 @@
 }
 
 .sizeLg {
-  .toggleButton {
+  .toggleButton,
+  &.toggleButton {
     @include action.icon-only("lg");
 
     svg {