@usefragments/ui 1.6.0 → 2.0.0

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",
@@ -23,7 +18,6 @@
     "size: sm|md|lg (default: md)",
     "disabled: boolean (default: false)",
     "error: boolean (default: false)",
-    "success: boolean (default: false)",
     "showCharCount: boolean (default: false)",
     "label: string",
     "helperText: string",
@@ -78,23 +72,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",
@@ -108,12 +93,6 @@
       "default": "false",
       "required": false
     },
-    "success": {
-      "type": "boolean",
-      "description": "Whether to show success/validated styling",
-      "default": "false",
-      "required": false
-    },
     "showCharCount": {
       "type": "boolean",
       "description": "Show character counter when maxLength is set",
@@ -209,61 +188,56 @@
       "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": "Success State",
-      "description": "Textarea showing validated/success styling",
-      "code": "<Textarea\n  label=\"Bio\"\n  value=\"A short bio about myself.\"\n  success\n  helperText=\"Looks great!\"\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": "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/>"
     }
   ],
@@ -281,7 +255,6 @@
       "label: string - label text",
       "size: sm|md|lg (default: md)",
       "error: boolean - error state",
-      "success: boolean - shows success/validated styling",
       "showCharCount: boolean - show character counter (requires maxLength)",
       "disabled: boolean - disabled state",
       "resize: none|vertical|horizontal|both",
@@ -289,15 +262,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

@@ -5,6 +5,11 @@
 @use "../../recipes/layout";
 @use "../../recipes/typography";
 
+// Fallbacks for the field recipe's size hooks when no size class has set them.
+$_track: field.track("md");
+$_stroke: field.stroke();
+$_block-inset: var(--fui-raw-space-8, #{measurements.raw-space(8)});
+
 .wrapper {
   @include field.wrapper;
 }
@@ -34,17 +39,18 @@
   display: block;
   width: 100%;
   min-block-size: max(
-    var(--_fui-field-track),
+    var(--_fui-field-track, #{$_track}),
     calc(
-      var(--_fui-textarea-min-rows) * 1lh + 2 * var(--_fui-textarea-block-inset) + 2 *
-        var(--_fui-field-stroke)
+      var(--fui-textarea-min-rows, 1) * 1lh + 2 *
+        var(--_fui-textarea-block-inset, #{$_block-inset}) + 2 *
+        var(--_fui-field-stroke, #{$_stroke})
     )
   );
   max-block-size: calc(
-    var(--_fui-textarea-max-rows) * 1lh + 2 * var(--_fui-textarea-block-inset) + 2 *
-      var(--_fui-field-stroke)
+    var(--fui-textarea-max-rows, 9999) * 1lh + 2 *
+      var(--_fui-textarea-block-inset, #{$_block-inset}) + 2 * var(--_fui-field-stroke, #{$_stroke})
   );
-  padding-block: var(--_fui-textarea-block-inset);
+  padding-block: var(--_fui-textarea-block-inset, #{$_block-inset});
 
   &::placeholder {
     color: var(--fui-text-tertiary, $fui-text-tertiary);
@@ -54,12 +60,14 @@
     @include field.focus-state;
   }
 
+  @include high-contrast-outline;
+
   // Single-line: same track as Input — height lock, horizontal pad only.
   &[rows="1"] {
-    block-size: var(--_fui-field-track);
-    min-block-size: var(--_fui-field-track);
+    block-size: var(--_fui-field-track, #{$_track});
+    min-block-size: var(--_fui-field-track, #{$_track});
     padding-block: calc(
-      (var(--_fui-field-track) - 1lh - 2 * var(--_fui-field-stroke)) / 2
+      (var(--_fui-field-track, #{$_track}) - 1lh - 2 * var(--_fui-field-stroke, #{$_stroke})) / 2
     );
     overflow-y: hidden;
   }
@@ -107,18 +115,7 @@
   @include field.invalid-state;
 
   &:focus-visible {
-    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
-    @include focus-ring-error;
-  }
-}
-
-// Success state — green border for validated fields
-.success {
-  border-color: var(--fui-color-success-text, $fui-color-success-text);
-
-  &:focus-visible {
-    border-color: var(--fui-color-success-text, $fui-color-success-text);
-    @include focus-ring-success;
+    @include field.invalid-focus-state;
   }
 }
 
@@ -127,12 +124,6 @@
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
-// Auto-detect success state
-.wrapper[data-success] .helper,
-.helperSuccess {
-  color: var(--fui-color-success-text, $fui-color-success-text);
-}
-
 // Footer row — helper + character counter side by side
 .footer {
   display: flex;
@@ -150,7 +141,10 @@
 .charCount {
   @include typography.role("caption");
 
-  margin-block-start: var(--fui-field-message-gap);
+  margin-block-start: var(
+    --fui-field-message-gap,
+    var(--fui-raw-space-4, #{measurements.raw-space(4)})
+  );
   margin-inline-start: auto;
   font-family: var(--fui-font-mono, $fui-font-mono);
   white-space: nowrap;
@@ -160,30 +154,6 @@
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .textarea {
-    border-width: 2px;
-    border-color: var(--fui-text-primary, $fui-text-primary);
-
-    &:focus-visible {
-      border-color: var(--fui-color-accent, $fui-color-accent);
-    }
-  }
-
-  .error,
-  .textarea[aria-invalid] {
-    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
-  }
-
-  .success {
-    border-color: var(--fui-color-success-text, $fui-color-success-text);
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

package/src/components/Textarea/index.tsx

@@ -28,8 +28,6 @@ export interface TextareaProps extends Omit<
   disabled?: boolean;
   /** Error state */
   error?: boolean;
-  /** Success state */
-  success?: boolean;
   /** Show character count when maxLength is set */
   showCharCount?: boolean;
   /** Label text above the textarea */
@@ -76,7 +74,6 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(functi
     size: sizeProp,
     disabled = false,
     error = false,
-    success = false,
     showCharCount = false,
     label,
     helperText,
@@ -113,29 +110,21 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(functi
     styles.textarea,
     styles[size],
     error && styles.error,
-    success && styles.success,
     styles[`resize-${resize}`],
   ]
     .filter(Boolean)
     .join(" ");
 
-  const helperClasses = [
-    styles.helper,
-    error && styles.helperError,
-    success && styles.helperSuccess,
-  ]
-    .filter(Boolean)
-    .join(" ");
+  const helperClasses = [styles.helper, error && styles.helperError].filter(Boolean).join(" ");
 
   const textareaInlineStyle = {
-    "--_fui-textarea-min-rows": minRows ?? 1,
-    "--_fui-textarea-max-rows": maxRows ?? 9999,
+    "--fui-textarea-min-rows": minRows ?? 1,
+    "--fui-textarea-max-rows": maxRows ?? 9999,
   } as React.CSSProperties;
 
   return (
     <div
       {...rootProps}
-      data-success={success || undefined}
       className={[styles.wrapper, rootProps?.className, className].filter(Boolean).join(" ")}
       style={{ ...(rootProps?.style ?? {}), ...(wrapperStyle ?? {}) }}
     >

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": "Utility provider that gives everything below it a light, dark, or system color mode.",
+  "category": "utilities",
+  "tags": ["theme", "dark-mode", "light-mode", "provider", "toggle"],
   "status": "stable",
   "sourcePath": "src/components/Theme/index.tsx",
   "exportName": "ThemeProvider",
@@ -20,7 +14,9 @@
     "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)",
+    "Theme.Toggle size: sm|md|lg",
+    "Theme.Button size: sm|md|lg"
   ],
   "props": {
     "children": {
@@ -33,31 +29,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 +59,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",
+      "ThemeProvider renders no chrome of its own; Theme.Toggle is the segmented light/dark/system control and Theme.Button the single icon button for tight toolbars"
     ],
     "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": "Theme Button",
+      "description": "A single icon button for toolbars with no room to spare.",
+      "code": "<ThemeProvider defaultMode=\"system\">\n  <ThemeButton aria-label=\"Switch color mode\" />\n</ThemeProvider>"
     }
   ],
   "relations": [
@@ -136,12 +119,11 @@
       "mode: light|dark|system - controlled mode",
       "onModeChange: (mode) => void - change handler",
       "attribute: data-theme|class - DOM theme attribute",
-      "ThemeToggle size: sm|md|lg - toggle button size",
-      "ThemeToggle forwards div DOM props to the button group root"
+      "Theme.Toggle size: sm|md|lg - segmented light/dark/system control",
+      "Theme.Toggle forwards div DOM props to the button group root",
+      "Theme.Button size: sm|md|lg - single ghost icon button that flips light and dark, built on IconButton"
     ],
-    "a11yRules": [
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_TARGET_SIZE_MIN"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Theme/index.tsx

@@ -2,10 +2,10 @@
 
 import * as React from "react";
 import { ComponentDefaultsProvider, type ComponentDefaults } from "../ComponentDefaults";
-import { ThemeToggle } from "../ThemeToggle";
+import { ThemeButton, ThemeToggle } from "../ThemeToggle";
 import { ThemeContext, useTheme, type ThemeContextValue, type ThemeMode } from "./context";
 
-export type { ThemeToggleProps } from "../ThemeToggle";
+export type { ThemeButtonProps, ThemeToggleProps } from "../ThemeToggle";
 export type { ThemeMode, UseThemeReturn } from "./context";
 
 // ============================================
@@ -68,6 +68,22 @@ function useSystemPreference(): "light" | "dark" {
  * ThemeProvider - Provides theme context to children
  * SSR-safe: initializes from localStorage in useEffect
  */
+function suppressTransitions(): () => void {
+  const style = document.createElement("style");
+  style.textContent = "*,*::before,*::after{transition:none!important}";
+  document.head.append(style);
+  return () => {
+    // Read layout for its side effect: a synchronous style flush commits the
+    // new colors while the override still applies, so nothing starts moving.
+    void document.body.offsetHeight;
+    if (typeof requestAnimationFrame === "function") {
+      requestAnimationFrame(() => requestAnimationFrame(() => style.remove()));
+    } else {
+      style.remove();
+    }
+  };
+}
+
 function ThemeProvider({
   children,
   componentDefaults,
@@ -81,7 +97,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."
@@ -121,6 +137,20 @@ function ThemeProvider({
     if (typeof document === "undefined" || !mounted) return;
 
     const root = document.documentElement;
+    const current =
+      attribute === "data-theme"
+        ? root.getAttribute("data-theme")
+        : root.classList.contains("dark")
+          ? "dark"
+          : root.classList.contains("light")
+            ? "light"
+            : null;
+
+    // A flip changes color, background, border and shadow on nearly every
+    // element at once; every transition on those properties would fire
+    // together and the switch smears instead of snapping. Turn transitions
+    // off for the swap, flush, then restore on the next frame.
+    const restore = current !== resolvedMode ? suppressTransitions() : null;
 
     if (attribute === "data-theme") {
       root.setAttribute("data-theme", resolvedMode);
@@ -128,6 +158,8 @@ function ThemeProvider({
       root.classList.remove("light", "dark");
       root.classList.add(resolvedMode);
     }
+
+    restore?.();
   }, [resolvedMode, attribute, mounted]);
 
   // Persist to localStorage when mode changes
@@ -182,27 +214,27 @@ export const Theme = Object.assign(ThemeProvider, {
   Root: ThemeProvider,
   Provider: ThemeProvider,
   Toggle: ThemeToggle,
+  Button: ThemeButton,
   useTheme,
 });
 
-export { ThemeProvider, ThemeToggle, useTheme };
+export { ThemeProvider, ThemeToggle, ThemeButton, useTheme };
 
 // ============================================
 // configureTheme — JS-only seed configuration
 // ============================================
 
 // Import + re-export seed derivation types — canonical definitions in utils/seed-derivation.ts
-import type { NeutralPalette, DensityPreset, RadiusStyle } from "../../utils/seed-derivation";
+import type { NeutralPalette, RadiusStyle } from "../../utils/seed-derivation";
 import { applyMeasurementSelection } from "../../measurements";
-export type { NeutralPalette, DensityPreset, RadiusStyle };
+import { isProductionBuild } from "../../utils/env";
+export type { NeutralPalette, RadiusStyle };
 
 export interface ConfigureThemeOptions {
   /** Brand/accent color as hex */
   brand?: string;
   /** Neutral palette name */
   neutral?: NeutralPalette;
-  /** Spacing density preset */
-  density?: DensityPreset;
   /** Border radius style */
   radiusStyle?: RadiusStyle;
   /** Danger/error color as hex */
@@ -247,7 +279,6 @@ function setVar(el: HTMLElement, name: string, value: string) {
  * configureTheme({
  *   brand: '#6366f1',
  *   neutral: 'ice',
- *   density: 'compact',
  *   radiusStyle: 'rounded',
  * });
  * ```
@@ -277,8 +308,5 @@ export function configureTheme(options: ConfigureThemeOptions): void {
   // Named geometry is selected through the generated Measurement Module.
   // Partial calls leave the omitted selector untouched and never write numeric
   // CSS maps inline.
-  applyMeasurementSelection(root, {
-    density: options.density,
-    radiusStyle: options.radiusStyle,
-  });
+  applyMeasurementSelection(root, { radiusStyle: options.radiusStyle });
 }