@usefragments/ui 1.6.0 → 2.0.0

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,18 +1,26 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/typography';
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../recipes/typography";
 
 .root {
   @include form-group-surface;
 
   display: flex;
   flex-direction: column;
-  gap: 0;
+  gap: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   padding: var(--fui-surface-inset-default, 16px);
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 
   &[data-disabled] {
-    opacity: 0.5;
+    opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
+  }
+
+  // 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);
   }
 }
 
@@ -20,7 +28,7 @@
   @include typography.role("ui-standard");
 
   color: var(--fui-text-secondary, $fui-text-secondary);
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   margin-block-end: var(--fui-raw-space-16, 16px);
 
   &:has(+ .description) {

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

@@ -1,8 +1,8 @@
 {
   "$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",
+  "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",
@@ -50,47 +50,47 @@
   },
   "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",
-      "Place form buttons inside Form.Actions so cancel and submit actions are consistently right-aligned"
+      "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>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Create Account</Button>\n  </Form.Actions>\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=\"solid\">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  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Save Changes</Button>\n  </Form.Actions>\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=\"solid\">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>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Send Message</Button>\n  </Form.Actions>\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=\"solid\">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>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Submit</Button>\n  </Form.Actions>\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=\"solid\">Submit</Button>\n  </Form.Actions>\n</Form>"
     }
   ],
   "relations": [

package/src/components/Grid/Grid.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Grid",
-  "description": "Responsive grid layout for arranging items in columns with consistent spacing",
+  "description": "Arranges items into responsive columns with one shared gap.",
   "category": "layout",
-  "tags": [
-    "grid",
-    "layout",
-    "columns",
-    "responsive"
-  ],
+  "tags": ["grid", "layout", "columns", "responsive"],
   "status": "stable",
   "sourcePath": "src/components/Grid/index.tsx",
   "exportName": "Grid",
@@ -43,57 +38,33 @@
       "type": "string",
       "description": "Minimum width for auto-fill columns (e.g., \"16rem\", \"250px\")",
       "required": false,
-      "constraints": [
-        "Only applies when columns=\"auto\""
-      ]
+      "constraints": ["Only applies when columns=\"auto\""]
     },
     "gap": {
       "type": "union",
       "description": "Gap between grid items. Accepts string tokens or numbers (1-8) mapped to the spacing scale",
       "default": "md",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "alignItems": {
       "type": "enum",
       "description": "Vertical alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "justifyItems": {
       "type": "enum",
       "description": "Horizontal alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "padding": {
       "type": "enum",
       "description": "Internal padding of the grid container",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "className": {
       "type": "string",
@@ -108,23 +79,21 @@
   },
   "usage": {
     "when": [
-      "Arranging cards, tiles, or media in a responsive grid",
-      "Building form layouts with multi-column fields",
-      "Creating dashboard layouts with widgets",
-      "Any content that should reflow across breakpoints"
+      "Cards, tiles, or media that reflow across breakpoints",
+      "Multi-column form layouts",
+      "Dashboard widget layouts"
     ],
     "whenNot": [
-      "Single-column stacked content (use a simple flex column or Stack)",
-      "Navigation bars or toolbars (use a dedicated nav component)",
-      "Content that must not wrap (use inline layout)"
+      "One-directional lists (use Stack)",
+      "Editorial mosaics with feature tiles (use BentoGrid)",
+      "Navigation bars (use Header)"
     ],
     "guidelines": [
-      "Use columns=\"auto\" with minChildWidth for grids that adapt without breakpoints",
-      "Use responsive object { base: 1, md: 2, lg: 3 } when you need explicit control per breakpoint",
-      "Use fixed column counts when exact column control is needed and responsiveness is not required",
-      "Use Grid.Item with colSpan to create asymmetric layouts within a fixed grid",
-      "Keep gap consistent within a context — md is the default and works for most cases",
-      "Pass DOM attributes (id, role, aria-*, data-*, event handlers) directly to Grid and Grid.Item roots when needed"
+      "columns=\"auto\" with minChildWidth adapts without breakpoints",
+      "Pass { base, md, lg } to columns for explicit per-breakpoint control",
+      "Numeric gaps (1-8) map to the same spacing scale as the tokens",
+      "Wrap a child in Grid.Item to span columns; colSpan=\"full\" spans the row",
+      "Keep source order equal to visual order — Grid does not reorder for screen readers"
     ],
     "accessibility": [
       "Grid is purely visual — it does not affect reading order or semantics",
@@ -134,33 +103,28 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic 3-column grid",
-      "code": "<Grid columns={3} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 3</div>\n</Grid>"
+      "description": "A fixed count of equal columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={3} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">One</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Two</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Three</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Responsive",
-      "description": "1 column on mobile, 2 on tablet, 3 on desktop",
-      "code": "<Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n</Grid>"
+      "description": "Column count changes per breakpoint.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Auto-fill",
-      "description": "Responsive grid that auto-fills based on minimum child width",
-      "code": "<Grid columns=\"auto\" minChildWidth=\"12rem\" gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 4</div>\n</Grid>"
-    },
-    {
-      "name": "Numeric Gap",
-      "description": "Using number values (1-8) mapped to the spacing scale",
-      "code": "<Grid columns={3} gap={4}>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n</Grid>"
+      "description": "Columns fit themselves to a minimum child width — no breakpoints needed.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns=\"auto\" minChildWidth=\"10rem\" gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 4</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "With Spanning",
-      "description": "Grid items spanning multiple columns",
-      "code": "<Grid columns={4} gap=\"md\">\n  <Grid.Item colSpan={2}>\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Spans 2 cols</div>\n  </Grid.Item>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Full width</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Grid.Item stretches a child across columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={4} gap=\"md\">\n    <Grid.Item colSpan={2}>\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Spans 2 columns</Box>\n    </Grid.Item>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Grid.Item colSpan=\"full\">\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Full width</Box>\n    </Grid.Item>\n  </Grid>\n</Box>"
     },
     {
       "name": "Form Layout",
-      "description": "Two-column form that collapses to single column on mobile",
-      "code": "<Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>First Name</div>\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Last Name</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Email Address</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Paired fields with one full-width row.",
+      "code": "import { Box } from '@/components/Box';\nimport { Field } from '@/components/Field';\nimport { Grid } from '@/components/Grid';\nimport { Input } from '@/components/Input';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n    <Field>\n      <Field.Label>First name</Field.Label>\n      <Input placeholder=\"Ada\" />\n    </Field>\n    <Field>\n      <Field.Label>Last name</Field.Label>\n      <Input placeholder=\"Lovelace\" />\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field>\n        <Field.Label>Email address</Field.Label>\n        <Input type=\"email\" placeholder=\"ada@example.com\" />\n      </Field>\n    </Grid.Item>\n  </Grid>\n</Box>"
     }
   ],
   "relations": [

package/src/components/Grid/Grid.module.scss

@@ -8,7 +8,7 @@
 .grid {
   display: grid;
   width: 100%;
-  gap: var(--_fui-grid-gap, #{layout.gap("md")});
+  gap: layout.gap("md");
 }
 
 // ============================================
@@ -75,7 +75,7 @@
 .columnsResponsive {
   --_cols: var(--fui-grid-cols, 1);
 
-  grid-template-columns: repeat(var(--_cols), 1fr);
+  grid-template-columns: repeat(var(--_cols, var(--fui-grid-cols, 1)), 1fr);
 
   @include breakpoint-sm {
     --_cols: var(--fui-grid-cols-sm, var(--fui-grid-cols, 1));

package/src/components/Grid/index.tsx

@@ -88,10 +88,10 @@ function isResponsiveColumns(columns: GridProps["columns"]): columns is Responsi
 }
 
 const paddingClasses: Record<NonNullable<GridProps["padding"]>, string> = {
-  none: styles.paddingNone,
-  sm: styles.paddingSm,
-  md: styles.paddingMd,
-  lg: styles.paddingLg,
+  none: styles.paddingNone ?? "",
+  sm: styles.paddingSm ?? "",
+  md: styles.paddingMd ?? "",
+  lg: styles.paddingLg ?? "",
 };
 
 // ============================================
@@ -118,12 +118,12 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
   let inlineStyle: React.CSSProperties | undefined;
 
   if (columns === "auto") {
-    columnsClass = styles.columnsAuto;
+    columnsClass = styles.columnsAuto ?? "";
     if (minChildWidth) {
       inlineStyle = { "--fui-grid-min-child-width": minChildWidth } as React.CSSProperties;
     }
   } else if (isResponsiveColumns(columns)) {
-    columnsClass = styles.columnsResponsive;
+    columnsClass = styles.columnsResponsive ?? "";
     const vars: Record<string, string> = {};
     if (columns.base) vars["--fui-grid-cols"] = String(columns.base);
     if (columns.sm) vars["--fui-grid-cols-sm"] = String(columns.sm);
@@ -132,7 +132,7 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
     if (columns.xl) vars["--fui-grid-cols-xl"] = String(columns.xl);
     inlineStyle = vars as unknown as React.CSSProperties;
   } else {
-    columnsClass = styles[`columns${columns}`];
+    columnsClass = styles[`columns${columns}`] ?? "";
   }
 
   inlineStyle = {
@@ -165,9 +165,9 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
 // ============================================
 
 const subgridClasses: Record<string, string> = {
-  rows: styles.subgridRows,
-  columns: styles.subgridColumns,
-  both: styles.subgridBoth,
+  rows: styles.subgridRows ?? "",
+  columns: styles.subgridColumns ?? "",
+  both: styles.subgridBoth ?? "",
 };
 
 const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(function GridItem(