@usefragments/ui 1.0.0

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

@@ -0,0 +1,145 @@
+{
+  "$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"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Form/index.tsx",
+  "exportName": "Form",
+  "propsSummary": [
+    "children: node (required)",
+    "errors: object",
+    "onSubmit: function",
+    "onFormSubmit: function",
+    "onClearErrors: function",
+    "validationMode: onSubmit|onBlur|onChange"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Form content",
+      "required": true
+    },
+    "errors": {
+      "type": "object",
+      "description": "Server-side errors keyed by field name",
+      "required": false
+    },
+    "onSubmit": {
+      "type": "function",
+      "description": "Form submission handler (preferred)",
+      "required": false
+    },
+    "onFormSubmit": {
+      "type": "function",
+      "description": "Deprecated alias for onSubmit",
+      "required": false
+    },
+    "onClearErrors": {
+      "type": "function",
+      "description": "Called with field name when errors should be cleared",
+      "required": false
+    },
+    "validationMode": {
+      "type": "enum",
+      "description": "When field validation should run",
+      "required": false,
+      "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"
+    ],
+    "whenNot": [
+      "Simple forms with only client-side validation (use native form or Field alone)",
+      "Non-form layouts (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"
+    ],
+    "accessibility": [
+      "Renders semantic form element",
+      "Error messages linked to fields 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>"
+    },
+    {
+      "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>"
+    },
+    {
+      "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>"
+    },
+    {
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Field",
+      "relationship": "sibling",
+      "note": "Contains Field components for error distribution"
+    },
+    {
+      "component": "Fieldset",
+      "relationship": "sibling",
+      "note": "Use Fieldset to group fields within a Form"
+    },
+    {
+      "component": "Button",
+      "relationship": "sibling",
+      "note": "Use Button type=\"submit\" for form submission"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "errors: Record<string, string | string[]> - server errors by field name",
+      "onSubmit: (event) => void - submission handler (preferred)",
+      "onFormSubmit: (event) => void - deprecated alias for onSubmit",
+      "onClearErrors: (name) => void - clear errors callback"
+    ],
+    "a11yRules": [
+      "A11Y_FORM_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:57.100Z"
+  }
+}

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

@@ -0,0 +1,8 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-4, $fui-space-4);
+}

package/src/components/Form/Form.stories.tsx

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Form } from '.';
+import { Field } from '../Field';
+import { Input } from '../Input';
+import { Grid } from '../Grid';
+import { Button } from '../Button';
+
+/**
+ * Form is a wrapper that handles server-side error distribution to Field
+ * components by field name. It pairs with Field and Fieldset for complete form
+ * validation, and renders a semantic form element.
+ */
+const meta = {
+  title: 'Forms/Form',
+  component: Form,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Form wrapper that distributes server-side errors to Field components.',
+      },
+    },
+  },
+  argTypes: {
+    validationMode: {
+      control: 'select',
+      options: ['onSubmit', 'onBlur', 'onChange'],
+      description: 'When field validation should run',
+    },
+  },
+  args: {
+    children: (
+      <Grid columns={1} gap="md">
+        <Field name="email">
+          <Field.Label>Email</Field.Label>
+          <Field.Control>
+            <Input type="email" placeholder="jane@example.com" />
+          </Field.Control>
+        </Field>
+        <Button type="submit" variant="primary">
+          Submit
+        </Button>
+      </Grid>
+    ),
+  },
+} satisfies Meta<typeof Form>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const SignUp: Story = {
+  render: () => (
+    <Form onSubmit={(e) => e.preventDefault()}>
+      <Grid columns={2} gap="md">
+        <Field name="firstName">
+          <Field.Label>First Name</Field.Label>
+          <Field.Control>
+            <Input placeholder="Jane" />
+          </Field.Control>
+        </Field>
+        <Field name="lastName">
+          <Field.Label>Last Name</Field.Label>
+          <Field.Control>
+            <Input placeholder="Doe" />
+          </Field.Control>
+        </Field>
+        <Grid.Item colSpan="full">
+          <Field name="email">
+            <Field.Label>Email</Field.Label>
+            <Field.Control>
+              <Input type="email" placeholder="jane@example.com" />
+            </Field.Control>
+            <Field.Error match="typeMismatch">
+              Enter a valid email address
+            </Field.Error>
+          </Field>
+        </Grid.Item>
+        <Grid.Item colSpan="full">
+          <Button type="submit" variant="primary">
+            Create Account
+          </Button>
+        </Grid.Item>
+      </Grid>
+    </Form>
+  ),
+};
+
+export const WithServerErrors: Story = {
+  render: () => (
+    <Form
+      errors={{
+        username: 'Username is already taken',
+        email: 'Email is already registered',
+      }}
+    >
+      <Grid columns={2} gap="md">
+        <Field name="username">
+          <Field.Label>Username</Field.Label>
+          <Field.Control>
+            <Input defaultValue="janedoe" />
+          </Field.Control>
+          <Field.Error match="customError" />
+        </Field>
+        <Field name="email">
+          <Field.Label>Email</Field.Label>
+          <Field.Control>
+            <Input type="email" defaultValue="jane@example.com" />
+          </Field.Control>
+          <Field.Error match="customError" />
+        </Field>
+        <Grid.Item colSpan="full">
+          <Button type="submit" variant="primary">
+            Submit
+          </Button>
+        </Grid.Item>
+      </Grid>
+    </Form>
+  ),
+};
+
+export const ValidateOnBlur: Story = {
+  render: () => (
+    <Form validationMode="onBlur" onSubmit={(e) => e.preventDefault()}>
+      <Grid columns={1} gap="md">
+        <Field name="email">
+          <Field.Label>Email</Field.Label>
+          <Field.Control>
+            <Input type="email" placeholder="you@example.com" />
+          </Field.Control>
+          <Field.Error match="typeMismatch">
+            Enter a valid email address
+          </Field.Error>
+        </Field>
+        <Button type="submit" variant="primary">
+          Submit
+        </Button>
+      </Grid>
+    </Form>
+  ),
+};

package/src/components/Form/index.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+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'> {
+  children: React.ReactNode;
+  errors?: Record<string, string | string[]>;
+  /** Standard form submit handler */
+  onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+  /** @deprecated Use onSubmit */
+  onFormSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+  onClearErrors?: (name: string) => void;
+  validationMode?: 'onSubmit' | 'onBlur' | 'onChange';
+}
+
+// ============================================
+// Component
+// ============================================
+
+function FormRoot({
+  children,
+  errors,
+  onSubmit,
+  onFormSubmit,
+  onClearErrors: _onClearErrors,
+  validationMode,
+  className,
+  ...htmlProps
+}: FormProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+  const submitHandler = onSubmit ?? onFormSubmit;
+
+  return (
+    <BaseForm
+      {...htmlProps}
+      errors={errors}
+      validationMode={validationMode}
+      onSubmit={submitHandler}
+      className={classes}
+    >
+      {children}
+    </BaseForm>
+  );
+}
+
+export const Form = Object.assign(FormRoot, {
+  Root: FormRoot,
+});

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

@@ -0,0 +1,195 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Grid",
+  "description": "Responsive grid layout for arranging items in columns with consistent spacing",
+  "category": "layout",
+  "tags": [
+    "grid",
+    "layout",
+    "columns",
+    "responsive"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Grid/index.tsx",
+  "exportName": "Grid",
+  "propsSummary": [
+    "children: node",
+    "columns: union (default: 1)",
+    "minChildWidth: string",
+    "gap: union (default: md)",
+    "alignItems: start|center|end|stretch",
+    "justifyItems: start|center|end|stretch",
+    "padding: none|sm|md|lg (default: none)",
+    "className: string",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Grid items and content",
+      "required": false
+    },
+    "columns": {
+      "type": "union",
+      "description": "Number of columns: a number (1-12), a responsive object { base, sm, md, lg, xl }, or \"auto\" for auto-fill",
+      "default": "1",
+      "required": false,
+      "constraints": [
+        "Use \"auto\" with minChildWidth for fully fluid layouts",
+        "Use responsive object for explicit breakpoint control: { base: 1, md: 2, lg: 3 }"
+      ]
+    },
+    "minChildWidth": {
+      "type": "string",
+      "description": "Minimum width for auto-fill columns (e.g., \"16rem\", \"250px\")",
+      "required": false,
+      "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"
+      ]
+    },
+    "alignItems": {
+      "type": "enum",
+      "description": "Vertical alignment of items within their cells",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end",
+        "stretch"
+      ]
+    },
+    "justifyItems": {
+      "type": "enum",
+      "description": "Horizontal alignment of items within their cells",
+      "required": false,
+      "values": [
+        "start",
+        "center",
+        "end",
+        "stretch"
+      ]
+    },
+    "padding": {
+      "type": "enum",
+      "description": "Internal padding of the grid container",
+      "default": "none",
+      "required": false,
+      "values": [
+        "none",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Inline styles",
+      "required": false
+    }
+  },
+  "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"
+    ],
+    "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)"
+    ],
+    "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"
+    ],
+    "accessibility": [
+      "Grid is purely visual — it does not affect reading order or semantics",
+      "Ensure logical source order matches visual order for screen readers"
+    ]
+  },
+  "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>"
+    },
+    {
+      "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>"
+    },
+    {
+      "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>"
+    },
+    {
+      "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>"
+    },
+    {
+      "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>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Card",
+      "relationship": "child",
+      "note": "Grid commonly contains Card components for dashboard and tile layouts"
+    },
+    {
+      "component": "Separator",
+      "relationship": "sibling",
+      "note": "Use Separator between grid sections"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "columns: 1-12 | { base, sm, md, lg, xl } | \"auto\" (default: 1)",
+      "minChildWidth: string — min width for auto-fill (only with columns=\"auto\")",
+      "gap: none|xs|sm|md|lg|xl|number (default: md, number maps to space scale)",
+      "alignItems: start|center|end|stretch — vertical alignment",
+      "justifyItems: start|center|end|stretch — horizontal alignment",
+      "padding: none|sm|md|lg (default: none)",
+      "Pass-through DOM props supported on Grid and Grid.Item roots (id, role, aria-*, data-*, handlers)"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:57.444Z"
+  }
+}