@usefragments/ui 1.5.4 → 1.7.0

package/src/components/EmptyState/EmptyState.contract.json

@@ -1,21 +1,16 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "EmptyState",
-  "description": "Placeholder for empty content areas. Provides context, guidance, and actions when no data is available.",
+  "description": "Explains why an area is blank and offers the next step.",
   "category": "feedback",
-  "tags": [
-    "empty",
-    "placeholder",
-    "no-data",
-    "zero-state",
-    "blank-slate"
-  ],
+  "tags": ["empty", "placeholder", "no-data", "zero-state", "blank-slate"],
   "status": "stable",
   "sourcePath": "src/components/EmptyState/index.tsx",
   "exportName": "EmptyState",
   "propsSummary": [
     "children: node (required)",
-    "size: sm|md|lg (default: md)"
+    "size: sm|md|lg (default: md)",
+    "variant: plain|outlined (default: plain)"
   ],
   "props": {
     "children": {
@@ -28,31 +23,33 @@
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Frame style. `outlined` draws a dashed hairline around the reserved region; `plain` leaves framing to the surrounding surface.",
+      "default": "plain",
+      "required": false,
+      "values": ["plain", "outlined"]
     }
   },
   "usage": {
     "when": [
-      "Empty lists, tables, or search results",
-      "New user onboarding (no content yet)",
-      "Filtered views with no matches",
-      "Error states where content failed to load"
+      "Lists, tables, or search results with nothing to show",
+      "First-run screens before any content exists",
+      "Filtered views that matched nothing"
     ],
     "whenNot": [
-      "Loading states (use skeleton or spinner)",
-      "Error messages with retry (use Alert)",
-      "Temporary messages (use Toast)"
+      "Content still loading (use Skeleton)",
+      "Failures that need a retry (use Alert)",
+      "Transient confirmations (use Toast)"
     ],
     "guidelines": [
-      "Always explain why the area is empty",
-      "Provide a clear action to resolve the empty state",
-      "Use appropriate icons to reinforce the message",
-      "Keep messaging positive and actionable",
-      "EmptyState compound sub-components forward DOM props for ids, aria attributes, and handlers"
+      "Say why the area is empty, not just that it is",
+      "Give one clear action out of the state",
+      "Keep to two actions at most, primary first",
+      "Match the icon to the cause \u2014 search, inbox, folder",
+      "Use size=\"sm\" inline and size=\"lg\" for full-page states"
     ],
     "accessibility": [
       "Empty state content is accessible to screen readers",
@@ -62,27 +59,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic empty state with action",
+      "description": "First-run state: nothing exists yet, so offer the create action.",
       "code": "<EmptyState>\n  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>\n  <EmptyState.Title>No projects yet</EmptyState.Title>\n  <EmptyState.Description>Get started by creating your first project.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Create Project</Button>\n  </EmptyState.Actions>\n</EmptyState>"
     },
     {
       "name": "No Results",
-      "description": "Empty search results",
+      "description": "A filter or query matched nothing \u2014 offer a way back.",
       "code": "<EmptyState>\n  <EmptyState.Icon><SearchIcon /></EmptyState.Icon>\n  <EmptyState.Title>No results found</EmptyState.Title>\n  <EmptyState.Description>Try adjusting your search terms or filters.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button variant=\"secondary\">Clear Filters</Button>\n  </EmptyState.Actions>\n</EmptyState>"
     },
     {
       "name": "With Secondary Action",
-      "description": "Empty state with two actions",
+      "description": "One primary action plus a quieter alternative.",
       "code": "<EmptyState>\n  <EmptyState.Icon><InboxIcon /></EmptyState.Icon>\n  <EmptyState.Title>Inbox is empty</EmptyState.Title>\n  <EmptyState.Description>You have no new messages.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Compose Message</Button>\n    <Button variant=\"secondary\">View Archive</Button>\n  </EmptyState.Actions>\n</EmptyState>"
     },
     {
       "name": "Small",
-      "description": "Compact empty state for inline use",
+      "description": "Compact size for inline panels; no icon, no action.",
       "code": "<EmptyState size=\"sm\">\n  <EmptyState.Title>No items</EmptyState.Title>\n  <EmptyState.Description>Add items to see them here.</EmptyState.Description>\n</EmptyState>"
     },
     {
       "name": "Large",
-      "description": "Prominent empty state for full-page use",
+      "description": "Full-page size for a workspace or onboarding screen.",
       "code": "<EmptyState size=\"lg\">\n  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>\n  <EmptyState.Title>Welcome to your workspace</EmptyState.Title>\n  <EmptyState.Description>\n    This is where your projects will appear. Create your first project to get started.\n  </EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Create Your First Project</Button>\n  </EmptyState.Actions>\n</EmptyState>"
     }
   ],
@@ -104,21 +101,12 @@
       "Sub-components: EmptyState.Icon, EmptyState.Title, EmptyState.Description, EmptyState.Actions",
       "Compound sub-components forward DOM props to their rendered elements"
     ],
-    "a11yRules": [
-      "A11Y_EMPTY_STATE_CONTENT"
-    ]
+    "a11yRules": ["A11Y_EMPTY_STATE_CONTENT"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Icon",
-      "Title",
-      "Description",
-      "Actions"
-    ],
-    "requiredChildren": [
-      "Title"
-    ],
+    "subComponents": ["Icon", "Title", "Description", "Actions"],
+    "requiredChildren": ["Title"],
     "commonPatterns": [
       "<EmptyState><EmptyState.Title>{title}</EmptyState.Title><EmptyState.Description>{description}</EmptyState.Description></EmptyState>",
       "<EmptyState><EmptyState.Icon>{icon}</EmptyState.Icon><EmptyState.Title>{title}</EmptyState.Title><EmptyState.Description>{description}</EmptyState.Description><EmptyState.Actions><Button>{action}</Button></EmptyState.Actions></EmptyState>"

package/src/components/EmptyState/EmptyState.module.scss

@@ -1,88 +1,53 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
-// Local component tokens
-$fui-emptystate-width-sm: 240px !default;
-$fui-emptystate-width-md: 320px !default;
-$fui-emptystate-width-lg: 400px !default;
-$fui-emptystate-icon-sm: $fui-icon-xl !default; // 24px (--fui-icon-xl)
-$fui-emptystate-icon-md: $fui-icon-2xl !default; // 32px (--fui-icon-2xl)
-// 40px has no icon-ladder step; kept as a documented local between
-// icon-2xl (32) and space-6 (42) so the lg display glyph stays distinct.
-$fui-emptystate-icon-lg: 2.857rem !default; // 40px
+@use "../../tokens/variables" as *;
+@use "../../recipes/feedback" as feedback;
 
 .emptyState {
   display: flex;
   flex-direction: column;
   align-items: center;
+  gap: var(--fui-feedback-text-gap, var(--fui-raw-space-4, 4px));
   text-align: center;
   font-family: var(--fui-font-sans, $fui-font-sans);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
-}
 
-// Size variants
-.sm {
-  padding: var(--fui-space-6) var(--fui-space-4);
-
-  .title {
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  > .icon {
+    margin-block-end: calc(
+      var(--fui-feedback-section-gap, var(--fui-raw-space-16, 16px)) - var(
+          --fui-feedback-text-gap,
+          var(--fui-raw-space-4, 4px)
+        )
+    );
   }
 
-  .description {
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-    max-width: $fui-emptystate-width-sm;
-  }
-
-  .icon {
-    margin-bottom: var(--fui-space-2, $fui-space-2);
+  > .actions {
+    margin-block-start: calc(
+      var(--fui-feedback-section-gap, var(--fui-raw-space-16, 16px)) - var(
+          --fui-feedback-text-gap,
+          var(--fui-raw-space-4, 4px)
+        )
+    );
   }
+}
 
-  .actions {
-    margin-top: var(--fui-space-3, $fui-space-3);
-  }
+.sm {
+  @include feedback.empty-state("sm");
 }
 
 .md {
-  padding: var(--fui-space-10, $fui-space-10) var(--fui-space-6);
-
-  .title {
-    font-size: var(--fui-font-size-base, $fui-font-size-base);
-  }
-
-  .description {
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-    max-width: $fui-emptystate-width-md;
-  }
-
-  .icon {
-    margin-bottom: var(--fui-space-3, $fui-space-3);
-  }
-
-  .actions {
-    margin-top: var(--fui-space-4, $fui-space-4);
-  }
+  @include feedback.empty-state("md");
 }
 
 .lg {
-  padding: var(--fui-space-12, $fui-space-12) var(--fui-space-8);
-
-  .title {
-    font-size: var(--fui-font-size-lg, $fui-font-size-lg);
-  }
-
-  .description {
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-    max-width: $fui-emptystate-width-lg;
-  }
-
-  .icon {
-    margin-bottom: var(--fui-space-4, $fui-space-4);
-  }
+  @include feedback.empty-state("lg");
+}
 
-  .actions {
-    margin-top: var(--fui-space-6, $fui-space-6);
-  }
+// Reserved-but-empty region: a dashed hairline says the space belongs to
+// content that has not arrived, without claiming the weight of a real card.
+.outlined {
+  justify-content: center;
+  border: var(--fui-stroke-hairline, 1px) dashed var(--fui-border-default, $fui-border-default);
+  border-radius: var(--fui-card-radius, var(--fui-radius-lg, $fui-radius-lg));
 }
 
 .icon {
@@ -91,41 +56,37 @@ $fui-emptystate-icon-lg: 2.857rem !default; // 40px
   justify-content: center;
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 
-  // Icon sizing based on parent size variant
   svg {
-    width: var(--fui-icon-2xl, #{$fui-emptystate-icon-md}); // 32px
-    height: var(--fui-icon-2xl, #{$fui-emptystate-icon-md});
-  }
-
-  .lg & svg {
-    // 40px has no icon-ladder step — see local token note above.
-    width: $fui-emptystate-icon-lg;
-    height: $fui-emptystate-icon-lg;
-  }
-
-  .sm & svg {
-    width: var(--fui-icon-xl, #{$fui-emptystate-icon-sm}); // 24px
-    height: var(--fui-icon-xl, #{$fui-emptystate-icon-sm});
+    inline-size: var(--_fui-feedback-empty-icon-size);
+    block-size: var(--_fui-feedback-empty-icon-size);
   }
 }
 
 .title {
   margin: 0;
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
   color: var(--fui-text-primary, $fui-text-primary);
-  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--_fui-feedback-empty-title-size);
+  font-weight: var(--_fui-feedback-empty-title-weight);
+  line-height: var(--_fui-feedback-empty-title-line);
+  letter-spacing: var(--_fui-feedback-empty-title-tracking);
 }
 
 .description {
-  margin: var(--fui-space-2, $fui-space-2) 0 0;
+  max-inline-size: var(--_fui-feedback-empty-max-inline);
+  margin: 0;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--_fui-feedback-empty-copy-size);
+  font-weight: var(--_fui-feedback-empty-copy-weight);
+  line-height: var(--_fui-feedback-empty-copy-line);
+  letter-spacing: var(--_fui-feedback-empty-copy-tracking);
 }
 
 .actions {
   display: flex;
-  align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
   flex-wrap: wrap;
+  align-items: center;
   justify-content: center;
+  gap: var(--fui-feedback-transient-gap, var(--fui-raw-space-8, 8px));
 }

package/src/components/EmptyState/index.tsx

@@ -1,7 +1,7 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './EmptyState.module.scss';
+import * as React from "react";
+import styles from "./EmptyState.module.scss";
 
 // ============================================
 // Types
@@ -9,7 +9,12 @@ import styles from './EmptyState.module.scss';
 
 export interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  size?: 'sm' | 'md' | 'lg';
+  size?: "sm" | "md" | "lg";
+  /** `outlined` draws the dashed hairline that marks a reserved-but-empty
+   * region. Default `plain` keeps the state inside whatever already frames it
+   * (a Card, a table body) so the frame is never doubled.
+   * @default "plain" */
+  variant?: "plain" | "outlined";
 }
 
 export interface EmptyStateIconProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -33,7 +38,7 @@ export interface EmptyStateActionsProps extends React.HTMLAttributes<HTMLDivElem
 // ============================================
 
 interface EmptyStateContextValue {
-  size: 'sm' | 'md' | 'lg';
+  size: "sm" | "md" | "lg";
 }
 
 const EmptyStateContext = React.createContext<EmptyStateContextValue | null>(null);
@@ -41,7 +46,7 @@ const EmptyStateContext = React.createContext<EmptyStateContextValue | null>(nul
 function useEmptyStateContext() {
   const context = React.useContext(EmptyStateContext);
   if (!context) {
-    throw new Error('EmptyState compound components must be used within an EmptyState');
+    throw new Error("EmptyState compound components must be used within an EmptyState");
   }
   return context;
 }
@@ -52,45 +57,65 @@ function useEmptyStateContext() {
 
 function EmptyStateRoot({
   children,
-  size = 'md',
+  size = "md",
+  variant = "plain",
   className,
   ...htmlProps
 }: EmptyStateProps) {
-  const classes = [styles.emptyState, styles[size], className]
+  const classes = [
+    styles.emptyState,
+    styles[size],
+    variant === "outlined" ? styles.outlined : null,
+    className,
+  ]
     .filter(Boolean)
-    .join(' ');
+    .join(" ");
 
   const contextValue: EmptyStateContextValue = { size };
 
   return (
     <EmptyStateContext.Provider value={contextValue}>
-      <div {...htmlProps} className={classes}>{children}</div>
+      <div {...htmlProps} className={classes}>
+        {children}
+      </div>
     </EmptyStateContext.Provider>
   );
 }
 
 function EmptyStateIcon({ children, className, ...htmlProps }: EmptyStateIconProps) {
-  const classes = [styles.icon, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.icon, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function EmptyStateTitle({ children, className, ...htmlProps }: EmptyStateTitleProps) {
-  const classes = [styles.title, className].filter(Boolean).join(' ');
-  return <h3 {...htmlProps} className={classes}>{children}</h3>;
+  const classes = [styles.title, className].filter(Boolean).join(" ");
+  return (
+    <h3 {...htmlProps} className={classes}>
+      {children}
+    </h3>
+  );
 }
 
-function EmptyStateDescription({
-  children,
-  className,
-  ...htmlProps
-}: EmptyStateDescriptionProps) {
-  const classes = [styles.description, className].filter(Boolean).join(' ');
-  return <p {...htmlProps} className={classes}>{children}</p>;
+function EmptyStateDescription({ children, className, ...htmlProps }: EmptyStateDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(" ");
+  return (
+    <p {...htmlProps} className={classes}>
+      {children}
+    </p>
+  );
 }
 
 function EmptyStateActions({ children, className, ...htmlProps }: EmptyStateActionsProps) {
-  const classes = [styles.actions, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  const classes = [styles.actions, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 // ============================================

package/src/components/Field/Field.contract.json

@@ -1,17 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Field",
-  "description": "Compositional form field wrapper providing validation, labels, descriptions, and error messages. Use for advanced form needs beyond baked-in Input/Textarea props.",
-  "category": "forms",
-  "tags": [
-    "form",
-    "field",
-    "validation",
-    "label",
-    "error",
-    "input",
-    "accessible"
-  ],
+  "description": "Composes labels, descriptions, validation, and errors around a form control.",
+  "category": "inputs",
+  "tags": ["form", "field", "validation", "label", "error", "input", "accessible"],
   "status": "stable",
   "sourcePath": "src/components/Field/index.tsx",
   "exportName": "Field",
@@ -54,11 +46,7 @@
       "type": "enum",
       "description": "When to trigger validation",
       "required": false,
-      "values": [
-        "onSubmit",
-        "onBlur",
-        "onChange"
-      ]
+      "values": ["onSubmit", "onBlur", "onChange"]
     },
     "validationDebounceTime": {
       "type": "number",
@@ -68,42 +56,47 @@
   },
   "usage": {
     "when": [
-      "You need granular validation with match-based error messages",
-      "Custom form controls need accessible labels and descriptions",
-      "Server-side errors need to be distributed to specific fields",
-      "You need dirty/touched tracking or custom validation logic"
+      "One error message per failure reason, not one catch-all",
+      "A custom control needs a real label and description",
+      "Server errors must land on the field that caused them",
+      "You need dirty and touched tracking"
     ],
     "whenNot": [
-      "Simple inputs with basic label and helper text (use Input with label prop)",
-      "Standalone selects or textareas with built-in error display"
+      "A plain input with a label and helper text (use Input's own props)",
+      "A Select or Textarea whose built-in error display is enough"
     ],
     "guidelines": [
-      "Always provide a Field.Label for accessibility",
-      "Wrap any form control in Field.Control to connect it to the field context",
-      "Use match prop on Field.Error for granular native validation messages",
-      "Wrap in Form to enable server-side error distribution by field name"
+      "Every Field gets a Field.Label",
+      "Wrap the control in Field.Control so it joins the field context",
+      "Give each Field.Error a match so the message fits the failure",
+      "Nest inside Form to route server errors by field name"
     ],
     "accessibility": [
-      "Label automatically linked to control via aria-labelledby",
-      "Description linked via aria-describedby",
-      "Error messages announced to screen readers",
-      "Supports data-disabled and data-invalid attributes for styling"
+      "Label links to the control via aria-labelledby",
+      "Description links via aria-describedby",
+      "Errors are announced when they appear",
+      "data-disabled and data-invalid are available for styling"
     ]
   },
   "examples": [
     {
       "name": "Single field",
-      "description": "A single field with label, control, and description",
+      "description": "Label, control and description wired together automatically.",
       "code": "<Field name=\"email\">\n  <Field.Label>Email address</Field.Label>\n  <Field.Control>\n    <Input type=\"email\" placeholder=\"jane@example.com\" />\n  </Field.Control>\n  <Field.Description>We will never share your email.</Field.Description>\n</Field>"
     },
     {
       "name": "Two-column layout",
-      "description": "Fields arranged in a two-column grid",
+      "description": "Grid places two short fields side by side and one full-width.",
       "code": "<Grid columns={2} gap=\"md\">\n  <Field name=\"firstName\">\n    <Field.Label>First Name</Field.Label>\n    <Field.Control>\n      <Input placeholder=\"Jane\" />\n    </Field.Control>\n  </Field>\n  <Field name=\"lastName\">\n    <Field.Label>Last Name</Field.Label>\n    <Field.Control>\n      <Input placeholder=\"Doe\" />\n    </Field.Control>\n  </Field>\n  <Grid.Item colSpan=\"full\">\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n    </Field>\n  </Grid.Item>\n</Grid>"
     },
+    {
+      "name": "Invalid",
+      "description": "invalid marks the field failed and reveals Field.Error.",
+      "code": "<Field name=\"username\" invalid>\n  <Field.Label>Username</Field.Label>\n  <Field.Control>\n    <Input value=\"ada lovelace\" error />\n  </Field.Control>\n  <Field.Error match>Usernames cannot contain spaces</Field.Error>\n</Field>"
+    },
     {
       "name": "Custom validation",
-      "description": "Field with custom validate function",
+      "description": "validate runs on change and feeds Field.Error.",
       "code": "<Field\n  name=\"age\"\n  validate={(value) => {\n    const num = Number(value);\n    if (isNaN(num) || num < 18) return 'Must be 18 or older';\n    return null;\n  }}\n  validationMode=\"onChange\"\n  validationDebounceTime={500}\n>\n  <Field.Label>Age</Field.Label>\n  <Field.Control>\n    <Input type=\"number\" placeholder=\"18\" />\n  </Field.Control>\n  <Field.Description>You must be at least 18 years old.</Field.Description>\n  <Field.Error match=\"customError\" />\n</Field>"
     }
   ],
@@ -132,21 +125,11 @@
       "Field.Control: wraps any form component (Input, Textarea, etc.)",
       "Field.Error match: valueMissing|typeMismatch|customError|... - granular errors"
     ],
-    "a11yRules": [
-      "A11Y_FIELD_LABEL",
-      "A11Y_FIELD_ERROR",
-      "A11Y_FIELD_DESCRIPTION"
-    ]
+    "a11yRules": ["A11Y_FIELD_LABEL", "A11Y_FIELD_ERROR", "A11Y_FIELD_DESCRIPTION"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Label",
-      "Control",
-      "Description",
-      "Error",
-      "Validity"
-    ]
+    "subComponents": ["Label", "Control", "Description", "Error", "Validity", "Required"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Field/Field.module.scss

@@ -1,14 +1,11 @@
-@use "../../tokens/variables" as *;
-@use "../../tokens/mixins" as *;
+@use "../../recipes/field";
 
 .root {
-  display: flex;
-  flex-direction: column;
+  @include field.wrapper;
 }
 
 .label {
-  @include label-text;
-  margin-bottom: var(--fui-space-1, $fui-space-1);
+  @include field.label;
 
   &[data-disabled] {
     opacity: 0.5;
@@ -20,12 +17,13 @@
 }
 
 .description {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
+  @include field.helper;
 }
 
 .error {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
-  color: var(--fui-color-danger-text, $fui-color-danger-text);
+  @include field.error;
+}
+
+.required {
+  margin-inline-start: var(--fui-raw-space-2, 2px);
 }