@usefragments/ui 1.6.0 → 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

@@ -42,6 +42,14 @@
   @include feedback.empty-state("lg");
 }
 
+// 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 {
   display: flex;
   align-items: center;

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,22 +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",
-      "Required"
-    ]
+    "subComponents": ["Label", "Control", "Description", "Error", "Validity", "Required"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Field/index.tsx

@@ -140,7 +140,11 @@ function FieldValidity({ children }: FieldValidityProps) {
 
 function FieldRequired({ children = "*", className, ...htmlProps }: FieldRequiredProps) {
   return (
-    <span {...htmlProps} className={[styles.required, className].filter(Boolean).join(" ")} aria-hidden>
+    <span
+      {...htmlProps}
+      className={[styles.required, className].filter(Boolean).join(" ")}
+      aria-hidden
+    >
       {children}
     </span>
   );

package/src/components/Fieldset/Fieldset.contract.json

@@ -1,22 +1,13 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Fieldset",
-  "description": "Groups related form fields with an accessible legend. Use to organize forms into logical sections.",
-  "category": "forms",
-  "tags": [
-    "form",
-    "fieldset",
-    "group",
-    "legend",
-    "accessible"
-  ],
+  "description": "Groups related form controls under an accessible legend.",
+  "category": "inputs",
+  "tags": ["form", "fieldset", "group", "legend", "accessible"],
   "status": "stable",
   "sourcePath": "src/components/Fieldset/index.tsx",
   "exportName": "Fieldset",
-  "propsSummary": [
-    "children: node (required)",
-    "disabled: boolean"
-  ],
+  "propsSummary": ["children: node (required)", "disabled: boolean"],
   "props": {
     "children": {
       "type": "node",
@@ -31,45 +22,42 @@
   },
   "usage": {
     "when": [
-      "Grouping related fields in a form (e.g., address, personal info)",
-      "Disabling a group of fields together",
-      "Providing an accessible group label for screen readers"
-    ],
-    "whenNot": [
-      "Generic visual grouping (use Card)",
-      "Single field wrapping (use Field)"
+      "Fields that belong to one subject: address, billing, profile",
+      "Locking a whole section at once",
+      "Screen readers should hear the group name before each field"
     ],
+    "whenNot": ["Grouping for looks alone (use Card)", "Wrapping one control (use Field)"],
     "guidelines": [
-      "Always include a Fieldset.Legend for accessibility",
-      "Use disabled prop to disable all fields within the group",
-      "Use Grid inside Fieldset for multi-column layouts",
-      "Fieldset.Legend forwards DOM props for ids, aria attributes, and custom data hooks"
+      "Every Fieldset gets a Fieldset.Legend",
+      "disabled on the Fieldset locks every control inside it",
+      "Put a Grid inside for multi-column layouts",
+      "Fieldset.Legend forwards DOM props for ids, ARIA, and data hooks"
     ],
     "accessibility": [
-      "Renders semantic fieldset element",
-      "Legend provides accessible group label",
-      "Disabled state propagates to all child fields"
+      "Renders a real fieldset element",
+      "Legend names the group",
+      "Disabled cascades to every child field"
     ]
   },
   "examples": [
     {
       "name": "Two-column layout",
-      "description": "Fieldset with Grid for side-by-side fields",
+      "description": "A Grid inside the legend box pairs short fields on one row.",
       "code": "<Fieldset>\n  <Fieldset.Legend>Personal Information</Fieldset.Legend>\n  <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>\n    </Grid.Item>\n  </Grid>\n</Fieldset>"
     },
     {
       "name": "Mixed controls",
-      "description": "Fieldset with textarea, select, and checkbox",
+      "description": "Textarea, select and checkbox share one spacing rhythm.",
       "code": "<Fieldset>\n  <Fieldset.Legend>Preferences</Fieldset.Legend>\n  <Field name=\"bio\">\n    <Field.Label>Bio</Field.Label>\n    <Field.Control>\n      <Textarea placeholder=\"Tell us about yourself\" rows={3} />\n    </Field.Control>\n    <Field.Description>Brief description for your profile.</Field.Description>\n  </Field>\n  <Field name=\"role\">\n    <Field.Label>Role</Field.Label>\n    <Field.Control>\n      <Select placeholder=\"Select a role\">\n        <Select.Trigger />\n        <Select.Content>\n          <Select.Item value=\"admin\">Admin</Select.Item>\n          <Select.Item value=\"editor\">Editor</Select.Item>\n          <Select.Item value=\"viewer\">Viewer</Select.Item>\n        </Select.Content>\n      </Select>\n    </Field.Control>\n  </Field>\n  <Field name=\"newsletter\">\n    <Field.Control>\n      <Checkbox label=\"Subscribe to newsletter\" />\n    </Field.Control>\n  </Field>\n</Fieldset>"
     },
     {
       "name": "With Description",
-      "description": "Fieldset with descriptive helper text below the legend",
+      "description": "One sentence under the legend covers the whole group.",
       "code": "<Fieldset>\n  <Fieldset.Legend>Notification Settings</Fieldset.Legend>\n  <Fieldset.Description>Choose how you want to be notified about updates.</Fieldset.Description>\n  <Field name=\"emailNotif\">\n    <Field.Control>\n      <Checkbox label=\"Email notifications\" />\n    </Field.Control>\n  </Field>\n  <Field name=\"smsNotif\">\n    <Field.Control>\n      <Checkbox label=\"SMS notifications\" />\n    </Field.Control>\n  </Field>\n</Fieldset>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled fieldset prevents interaction with all children",
+      "description": "One prop on the wrapper dims and locks every control inside.",
       "code": "<Fieldset disabled>\n  <Fieldset.Legend>Locked Section</Fieldset.Legend>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"lockedFirst\">\n      <Field.Label>First Name</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"Jane\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"lockedLast\">\n      <Field.Label>Last Name</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"Doe\" />\n      </Field.Control>\n    </Field>\n  </Grid>\n  <Field name=\"lockedCheck\">\n    <Field.Control>\n      <Checkbox label=\"Cannot toggle\" defaultChecked />\n    </Field.Control>\n  </Field>\n</Fieldset>"
     }
   ],
@@ -97,16 +85,11 @@
       "Fieldset.Legend forwards DOM props",
       "Fieldset.Description: helper text below the legend"
     ],
-    "a11yRules": [
-      "A11Y_FIELDSET_LEGEND"
-    ]
+    "a11yRules": ["A11Y_FIELDSET_LEGEND"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Legend",
-      "Description"
-    ]
+    "subComponents": ["Legend", "Description"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Fieldset/Fieldset.module.scss

@@ -1,6 +1,6 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/typography';
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/typography";
 
 .root {
   @include form-group-surface;
@@ -14,6 +14,13 @@
   &[data-disabled] {
     opacity: 0.5;
   }
+
+  // Legend and description carry their own block margins, so spacing is added
+  // only between the remaining rows. Without this, sibling controls that render
+  // a single line (a bare Checkbox or Switch inside a Field) sit flush together.
+  > :not(.legend):not(.description) + :not(.legend):not(.description) {
+    margin-block-start: var(--fui-raw-space-16, 16px);
+  }
 }
 
 .legend {