@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Field/index.tsx

@@ -6,6 +6,7 @@ import {
   type FieldControlProps as BaseFieldControlProps,
   type FieldValidityState,
 } from "@base-ui/react/field";
+import { useResolvedControlSize, type ControlSize } from "../ComponentDefaults";
 import styles from "./Field.module.scss";
 
 // ============================================
@@ -20,6 +21,7 @@ export interface FieldProps extends React.HTMLAttributes<HTMLDivElement> {
   validate?: (value: unknown) => string | string[] | null | Promise<string | string[] | null>;
   validationMode?: "onSubmit" | "onBlur" | "onChange";
   validationDebounceTime?: number;
+  size?: ControlSize;
 }
 
 export interface FieldLabelProps {
@@ -57,6 +59,10 @@ export interface FieldValidityProps {
   children: (state: FieldValidityState) => React.ReactNode;
 }
 
+export interface FieldRequiredProps extends React.HTMLAttributes<HTMLSpanElement> {
+  children?: React.ReactNode;
+}
+
 export type { FieldValidityState };
 
 // ============================================
@@ -71,9 +77,11 @@ function FieldRoot({
   validate,
   validationMode,
   validationDebounceTime,
+  size: sizeProp,
   className,
   ...htmlProps
 }: FieldProps) {
+  const size = useResolvedControlSize(sizeProp);
   const classes = [styles.root, className].filter(Boolean).join(" ");
 
   return (
@@ -85,6 +93,7 @@ function FieldRoot({
       validate={validate}
       validationMode={validationMode}
       validationDebounceTime={validationDebounceTime}
+      data-size={size}
       className={classes}
     >
       {children}
@@ -129,6 +138,18 @@ function FieldValidity({ children }: FieldValidityProps) {
   return <BaseField.Validity>{children}</BaseField.Validity>;
 }
 
+function FieldRequired({ children = "*", className, ...htmlProps }: FieldRequiredProps) {
+  return (
+    <span
+      {...htmlProps}
+      className={[styles.required, className].filter(Boolean).join(" ")}
+      aria-hidden
+    >
+      {children}
+    </span>
+  );
+}
+
 // ============================================
 // Export compound component
 // ============================================
@@ -139,6 +160,15 @@ export const Field = Object.assign(FieldRoot, {
   Description: FieldDescription,
   Error: FieldError,
   Validity: FieldValidity,
+  Required: FieldRequired,
 });
 
-export { FieldRoot, FieldLabel, FieldControl, FieldDescription, FieldError, FieldValidity };
+export {
+  FieldRoot,
+  FieldLabel,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldValidity,
+  FieldRequired,
+};

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,28 +1,43 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/typography";
 
 .root {
   @include form-group-surface;
 
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-3, $fui-space-3);
-  padding: var(--fui-space-4, $fui-space-4);
+  gap: 0;
+  padding: var(--fui-surface-inset-default, 16px);
   margin: 0;
 
   &[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 {
-  @include label-text;
+  @include typography.role("ui-standard");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   padding: 0;
+  margin-block-end: var(--fui-raw-space-16, 16px);
+
+  &:has(+ .description) {
+    margin-block-end: var(--fui-raw-space-4, 4px);
+  }
 }
 
 .description {
-  @include helper-text;
-  margin: calc(-1 * var(--fui-space-2, $fui-space-2)) 0 0 0;
+  @include typography.role("caption");
+
+  margin: 0 0 var(--fui-raw-space-16, 16px);
+  color: var(--fui-text-secondary, $fui-text-secondary);
 }

package/src/components/Form/Form.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Form",
-  "description": "Form wrapper that handles server-side error distribution to Field components. Pairs with Field for complete form validation.",
-  "category": "forms",
-  "tags": [
-    "form",
-    "validation",
-    "errors",
-    "submit",
-    "server"
-  ],
+  "description": "Distributes server-side validation errors to its Field components.",
+  "category": "inputs",
+  "tags": ["form", "validation", "errors", "submit", "server"],
   "status": "stable",
   "sourcePath": "src/components/Form/index.tsx",
   "exportName": "Form",
@@ -51,55 +45,52 @@
       "type": "enum",
       "description": "When field validation should run",
       "required": false,
-      "values": [
-        "onSubmit",
-        "onBlur",
-        "onChange"
-      ]
+      "values": ["onSubmit", "onBlur", "onChange"]
     }
   },
   "usage": {
     "when": [
-      "Building forms that need server-side error handling",
-      "Distributing validation errors to specific fields by name",
-      "Combining client and server validation in one form"
+      "The server rejects a submission and each reason must reach its own field",
+      "Client and server validation live in the same form"
     ],
     "whenNot": [
-      "Simple forms with only client-side validation (use native form or Field alone)",
-      "Non-form layouts (use Grid or Card)"
+      "Client-side validation only (a native form plus Field is enough)",
+      "Layout without submission (use Grid or Card)"
     ],
     "guidelines": [
-      "Pass errors as Record<string, string | string[]> keyed by field name",
-      "Use onClearErrors to clear errors when fields are modified",
-      "Use onSubmit for form submission handling (onFormSubmit is deprecated alias)",
-      "Field components with matching name prop display errors automatically",
-      "Use Grid inside Form or Fieldset for multi-column layouts"
+      "errors is keyed by field name: Record<string, string | string[]>",
+      "Clear a field's error in onClearErrors when the user edits it",
+      "Use onSubmit; onFormSubmit is a deprecated alias",
+      "A Field picks up its error by matching name",
+      "Leave Field.Error unmatched so it shows whatever the server sent",
+      "Put a Grid inside Form or Fieldset for multi-column layouts",
+      "Buttons go in Form.Actions so they stay right-aligned"
     ],
     "accessibility": [
-      "Renders semantic form element",
-      "Error messages linked to fields via aria-describedby"
+      "Renders a real form element",
+      "Errors link back to their field via aria-describedby"
     ]
   },
   "examples": [
     {
       "name": "Sign up",
-      "description": "Registration form with two-column name fields",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\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.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"password\">\n        <Field.Label>Password</Field.Label>\n        <Field.Control>\n          <Input type=\"password\" placeholder=\"At least 8 characters\" />\n        </Field.Control>\n        <Field.Description>Must be at least 8 characters</Field.Description>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"terms\">\n        <Field.Control>\n          <Checkbox label=\"I agree to the terms and conditions\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Button type=\"submit\" variant=\"primary\">Create Account</Button>\n    </Grid.Item>\n  </Grid>\n</Form>"
+      "description": "Paired name fields, then full-width rows and a right-aligned submit.",
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\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.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"password\">\n        <Field.Label>Password</Field.Label>\n        <Field.Control>\n          <Input type=\"password\" placeholder=\"At least 8 characters\" />\n        </Field.Control>\n        <Field.Description>Must be at least 8 characters</Field.Description>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"terms\">\n        <Field.Control>\n          <Checkbox label=\"I agree to the terms and conditions\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Create Account</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "Profile settings",
-      "description": "Multi-section form with Fieldsets, switches, and radio group",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Fieldset>\n    <Fieldset.Legend>Profile</Fieldset.Legend>\n    <Grid columns={2} gap=\"md\">\n      <Field name=\"displayName\">\n        <Field.Label>Display Name</Field.Label>\n        <Field.Control>\n          <Input placeholder=\"How others see you\" />\n        </Field.Control>\n      </Field>\n      <Field name=\"timezone\">\n        <Field.Label>Timezone</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"Select timezone\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"utc\">UTC</Select.Item>\n              <Select.Item value=\"est\">Eastern (EST)</Select.Item>\n              <Select.Item value=\"pst\">Pacific (PST)</Select.Item>\n              <Select.Item value=\"gmt\">GMT</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n      <Grid.Item colSpan=\"full\">\n        <Field name=\"bio\">\n          <Field.Label>Bio</Field.Label>\n          <Field.Control>\n            <Textarea placeholder=\"Tell us about yourself\" rows={3} maxLength={280} />\n          </Field.Control>\n          <Field.Description>Max 280 characters</Field.Description>\n        </Field>\n      </Grid.Item>\n    </Grid>\n  </Fieldset>\n  <Fieldset>\n    <Fieldset.Legend>Notifications</Fieldset.Legend>\n    <Field name=\"emailNotifs\">\n      <Field.Control>\n        <Switch label=\"Email notifications\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"marketingEmails\">\n      <Field.Control>\n        <Switch label=\"Marketing emails\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"frequency\">\n      <Field.Label>Digest frequency</Field.Label>\n      <Field.Control>\n        <RadioGroup name=\"frequency\" orientation=\"vertical\">\n          <RadioGroup.Item value=\"daily\" label=\"Daily\" />\n          <RadioGroup.Item value=\"weekly\" label=\"Weekly\" />\n          <RadioGroup.Item value=\"monthly\" label=\"Monthly\" />\n        </RadioGroup>\n      </Field.Control>\n    </Field>\n  </Fieldset>\n  <Button type=\"submit\" variant=\"primary\">Save Changes</Button>\n</Form>"
+      "description": "Fieldsets split a long form into sections the user can scan.",
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Fieldset>\n    <Fieldset.Legend>Profile</Fieldset.Legend>\n    <Grid columns={2} gap=\"md\">\n      <Field name=\"displayName\">\n        <Field.Label>Display Name</Field.Label>\n        <Field.Control>\n          <Input placeholder=\"How others see you\" />\n        </Field.Control>\n      </Field>\n      <Field name=\"timezone\">\n        <Field.Label>Timezone</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"Select timezone\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"utc\">UTC</Select.Item>\n              <Select.Item value=\"est\">Eastern (EST)</Select.Item>\n              <Select.Item value=\"pst\">Pacific (PST)</Select.Item>\n              <Select.Item value=\"gmt\">GMT</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n      <Grid.Item colSpan=\"full\">\n        <Field name=\"bio\">\n          <Field.Label>Bio</Field.Label>\n          <Field.Control>\n            <Textarea placeholder=\"Tell us about yourself\" rows={3} maxLength={280} />\n          </Field.Control>\n          <Field.Description>Max 280 characters</Field.Description>\n        </Field>\n      </Grid.Item>\n    </Grid>\n  </Fieldset>\n  <Fieldset>\n    <Fieldset.Legend>Notifications</Fieldset.Legend>\n    <Field name=\"emailNotifs\">\n      <Field.Control>\n        <Switch label=\"Email notifications\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"marketingEmails\">\n      <Field.Control>\n        <Switch label=\"Marketing emails\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"frequency\">\n      <Field.Label>Digest frequency</Field.Label>\n      <Field.Control>\n        <RadioGroup name=\"frequency\" orientation=\"vertical\">\n          <RadioGroup.Item value=\"daily\" label=\"Daily\" />\n          <RadioGroup.Item value=\"weekly\" label=\"Weekly\" />\n          <RadioGroup.Item value=\"monthly\" label=\"Monthly\" />\n        </RadioGroup>\n      </Field.Control>\n    </Field>\n  </Fieldset>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Save Changes</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "Contact form",
-      "description": "Contact form with select, textarea, and checkbox",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"name\">\n      <Field.Label>Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Your name\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"you@example.com\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"subject\">\n        <Field.Label>Subject</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"What is this about?\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"general\">General Inquiry</Select.Item>\n              <Select.Item value=\"support\">Technical Support</Select.Item>\n              <Select.Item value=\"billing\">Billing</Select.Item>\n              <Select.Item value=\"feedback\">Feedback</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"message\">\n        <Field.Label>Message</Field.Label>\n        <Field.Control>\n          <Textarea placeholder=\"How can we help?\" rows={5} />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"copy\">\n        <Field.Control>\n          <Checkbox label=\"Send me a copy\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Button type=\"submit\" variant=\"primary\">Send Message</Button>\n    </Grid.Item>\n  </Grid>\n</Form>"
+      "description": "Mixed control types in one submission flow.",
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"name\">\n      <Field.Label>Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Your name\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"you@example.com\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"subject\">\n        <Field.Label>Subject</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"What is this about?\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"general\">General Inquiry</Select.Item>\n              <Select.Item value=\"support\">Technical Support</Select.Item>\n              <Select.Item value=\"billing\">Billing</Select.Item>\n              <Select.Item value=\"feedback\">Feedback</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"message\">\n        <Field.Label>Message</Field.Label>\n        <Field.Control>\n          <Textarea placeholder=\"How can we help?\" rows={5} />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"copy\">\n        <Field.Control>\n          <Checkbox label=\"Send me a copy\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Send Message</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "With server errors",
-      "description": "Form displaying server-side validation errors",
-      "code": "<Form errors={{ username: 'Username is already taken', email: 'Email is already registered' }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"username\">\n      <Field.Label>Username</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"janedoe\" />\n      </Field.Control>\n      <Field.Error match=\"customError\" />\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" defaultValue=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error match=\"customError\" />\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Button type=\"submit\" variant=\"primary\">Submit</Button>\n    </Grid.Item>\n  </Grid>\n</Form>"
+      "description": "Errors from the server land on the fields that caused them.",
+      "code": "<Form errors={{ username: 'Username is already taken', email: 'Email is already registered' }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"username\">\n      <Field.Label>Username</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"janedoe\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" defaultValue=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Submit</Button>\n  </Form.Actions>\n</Form>"
     }
   ],
   "relations": [
@@ -126,15 +117,11 @@
       "onFormSubmit: (event) => void - deprecated alias for onSubmit",
       "onClearErrors: (name) => void - clear errors callback"
     ],
-    "a11yRules": [
-      "A11Y_FORM_LABEL"
-    ]
+    "a11yRules": ["A11Y_FORM_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root", "Actions"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Form/Form.module.scss

@@ -1,8 +1,13 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-
 .root {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-4, $fui-space-4);
+  gap: var(--fui-raw-space-16, 16px);
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  flex-wrap: wrap;
+  gap: var(--fui-raw-space-8, 8px);
 }

package/src/components/Form/index.tsx

@@ -1,14 +1,14 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Form as BaseForm } from '@base-ui/react/form';
-import styles from './Form.module.scss';
+import * as React from "react";
+import { Form as BaseForm } from "@base-ui/react/form";
+import styles from "./Form.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> {
   children: React.ReactNode;
   errors?: Record<string, string | string[]>;
   /** Standard form submit handler */
@@ -16,7 +16,11 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
   /** @deprecated Use onSubmit */
   onFormSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
   onClearErrors?: (name: string) => void;
-  validationMode?: 'onSubmit' | 'onBlur' | 'onChange';
+  validationMode?: "onSubmit" | "onBlur" | "onChange";
+}
+
+export interface FormActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
 }
 
 // ============================================
@@ -33,7 +37,7 @@ function FormRoot({
   className,
   ...htmlProps
 }: FormProps) {
-  const classes = [styles.root, className].filter(Boolean).join(' ');
+  const classes = [styles.root, className].filter(Boolean).join(" ");
   const submitHandler = onSubmit ?? onFormSubmit;
 
   return (
@@ -49,6 +53,17 @@ function FormRoot({
   );
 }
 
+function FormActions({ children, className, ...htmlProps }: FormActionsProps) {
+  const classes = [styles.actions, className].filter(Boolean).join(" ");
+
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
 export const Form = Object.assign(FormRoot, {
   Root: FormRoot,
+  Actions: FormActions,
 });