@usefragments/ui 1.0.0

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

@@ -0,0 +1,133 @@
+{
+  "$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.",
+  "category": "feedback",
+  "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)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "EmptyState content - use EmptyState.Icon, EmptyState.Title, EmptyState.Description, EmptyState.Actions sub-components",
+      "required": true
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    }
+  },
+  "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"
+    ],
+    "whenNot": [
+      "Loading states (use skeleton or spinner)",
+      "Error messages with retry (use Alert)",
+      "Temporary messages (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"
+    ],
+    "accessibility": [
+      "Empty state content is accessible to screen readers",
+      "Action buttons follow button accessibility guidelines"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic empty state with 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",
+      "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",
+      "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",
+      "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",
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for error states with retry"
+    },
+    {
+      "component": "Progress",
+      "relationship": "alternative",
+      "note": "Use Progress/Spinner for loading states"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "size: sm|md|lg (default: md)",
+      "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"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "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>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:56.922Z"
+  }
+}

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

@@ -0,0 +1,131 @@
+@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
+
+.emptyState {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  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);
+  }
+
+  .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-top: var(--fui-space-3, $fui-space-3);
+  }
+}
+
+.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);
+  }
+}
+
+.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);
+  }
+
+  .actions {
+    margin-top: var(--fui-space-6, $fui-space-6);
+  }
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  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});
+  }
+}
+
+.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);
+}
+
+.description {
+  margin: var(--fui-space-2, $fui-space-2) 0 0;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  flex-wrap: wrap;
+  justify-content: center;
+}

package/src/components/EmptyState/EmptyState.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { EmptyState } from '.';
+import { Button } from '../Button';
+
+/**
+ * EmptyState is a placeholder for empty content areas, providing context,
+ * guidance, and actions when no data is available. It is a compound component:
+ * compose EmptyState.Icon, EmptyState.Title, EmptyState.Description, and
+ * EmptyState.Actions inside the root.
+ */
+const meta = {
+  title: 'Feedback/EmptyState',
+  component: EmptyState,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Placeholder for empty content areas with context, guidance, and actions.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size variant',
+    },
+  },
+  args: {
+    size: 'md',
+    children: (
+      <>
+        <EmptyState.Title>No projects yet</EmptyState.Title>
+        <EmptyState.Description>
+          Get started by creating your first project.
+        </EmptyState.Description>
+      </>
+    ),
+  },
+} satisfies Meta<typeof EmptyState>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <EmptyState>
+      <EmptyState.Title>No projects yet</EmptyState.Title>
+      <EmptyState.Description>
+        Get started by creating your first project.
+      </EmptyState.Description>
+      <EmptyState.Actions>
+        <Button>Create Project</Button>
+      </EmptyState.Actions>
+    </EmptyState>
+  ),
+};
+
+export const NoResults: Story = {
+  render: () => (
+    <EmptyState>
+      <EmptyState.Title>No results found</EmptyState.Title>
+      <EmptyState.Description>
+        Try adjusting your search terms or filters.
+      </EmptyState.Description>
+      <EmptyState.Actions>
+        <Button variant="secondary">Clear Filters</Button>
+      </EmptyState.Actions>
+    </EmptyState>
+  ),
+};
+
+export const Small: Story = {
+  render: () => (
+    <EmptyState size="sm">
+      <EmptyState.Title>No items</EmptyState.Title>
+      <EmptyState.Description>Add items to see them here.</EmptyState.Description>
+    </EmptyState>
+  ),
+};
+
+export const Large: Story = {
+  render: () => (
+    <EmptyState size="lg">
+      <EmptyState.Title>Welcome to your workspace</EmptyState.Title>
+      <EmptyState.Description>
+        This is where your projects will appear. Create your first project to get
+        started.
+      </EmptyState.Description>
+      <EmptyState.Actions>
+        <Button>Create Your First Project</Button>
+      </EmptyState.Actions>
+    </EmptyState>
+  ),
+};

package/src/components/EmptyState/index.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import * as React from 'react';
+import styles from './EmptyState.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export interface EmptyStateIconProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface EmptyStateTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  children: React.ReactNode;
+}
+
+export interface EmptyStateDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  children: React.ReactNode;
+}
+
+export interface EmptyStateActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface EmptyStateContextValue {
+  size: 'sm' | 'md' | 'lg';
+}
+
+const EmptyStateContext = React.createContext<EmptyStateContextValue | null>(null);
+
+function useEmptyStateContext() {
+  const context = React.useContext(EmptyStateContext);
+  if (!context) {
+    throw new Error('EmptyState compound components must be used within an EmptyState');
+  }
+  return context;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function EmptyStateRoot({
+  children,
+  size = 'md',
+  className,
+  ...htmlProps
+}: EmptyStateProps) {
+  const classes = [styles.emptyState, styles[size], className]
+    .filter(Boolean)
+    .join(' ');
+
+  const contextValue: EmptyStateContextValue = { size };
+
+  return (
+    <EmptyStateContext.Provider value={contextValue}>
+      <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>;
+}
+
+function EmptyStateTitle({ children, className, ...htmlProps }: EmptyStateTitleProps) {
+  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 EmptyStateActions({ children, className, ...htmlProps }: EmptyStateActionsProps) {
+  const classes = [styles.actions, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const EmptyState = Object.assign(EmptyStateRoot, {
+  Icon: EmptyStateIcon,
+  Title: EmptyStateTitle,
+  Description: EmptyStateDescription,
+  Actions: EmptyStateActions,
+});
+
+// Re-export individual components for tree-shaking
+export {
+  EmptyStateRoot,
+  EmptyStateIcon,
+  EmptyStateTitle,
+  EmptyStateDescription,
+  EmptyStateActions,
+  useEmptyStateContext,
+};

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

@@ -0,0 +1,157 @@
+{
+  "$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"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Field/index.tsx",
+  "exportName": "Field",
+  "propsSummary": [
+    "children: node (required)",
+    "name: string",
+    "disabled: boolean",
+    "invalid: boolean",
+    "validate: function",
+    "validationMode: onSubmit|onBlur|onChange",
+    "validationDebounceTime: number"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Field content (Label, Control, Description, Error)",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "description": "Field name, used for error distribution from Form",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disables the field and its control",
+      "required": false
+    },
+    "invalid": {
+      "type": "boolean",
+      "description": "Marks the field as invalid",
+      "required": false
+    },
+    "validate": {
+      "type": "function",
+      "description": "Custom validation function returning error string(s) or null",
+      "required": false
+    },
+    "validationMode": {
+      "type": "enum",
+      "description": "When to trigger validation",
+      "required": false,
+      "values": [
+        "onSubmit",
+        "onBlur",
+        "onChange"
+      ]
+    },
+    "validationDebounceTime": {
+      "type": "number",
+      "description": "Debounce time in ms for onChange validation",
+      "required": false
+    }
+  },
+  "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"
+    ],
+    "whenNot": [
+      "Simple inputs with basic label and helper text (use Input with label prop)",
+      "Standalone selects or textareas with built-in error display"
+    ],
+    "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"
+    ],
+    "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"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Single field",
+      "description": "A single field with label, control, and description",
+      "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",
+      "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": "Custom validation",
+      "description": "Field with custom validate function",
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for simple fields with built-in label/error"
+    },
+    {
+      "component": "Form",
+      "relationship": "parent",
+      "note": "Wrap in Form for server-side error distribution"
+    },
+    {
+      "component": "Fieldset",
+      "relationship": "sibling",
+      "note": "Use Fieldset to group related fields"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "name: string - field name for error distribution",
+      "validate: (value) => string | null - custom validation",
+      "validationMode: onSubmit|onBlur|onChange - validation trigger",
+      "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"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Label",
+      "Control",
+      "Description",
+      "Error",
+      "Validity"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.733Z"
+  }
+}

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

@@ -0,0 +1,31 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.label {
+  @include label-text;
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+
+  &[data-disabled] {
+    opacity: 0.5;
+  }
+}
+
+.control {
+  // Minimal styles — users bring styled controls via render prop
+}
+
+.description {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.error {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}