@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-forms-form-field.json

@@ -0,0 +1,848 @@
+{
+  "meta": {
+    "id": "Components-FormField",
+    "title": "Form field",
+    "exportName": "FormField",
+    "description": "Form fields are the building blocks of user interaction, collecting essential data, facilitating actions, and enabling customization within digital interfaces.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/form-field/form-field.mdx",
+    "menu": [
+      "Components",
+      "Forms",
+      "Form field"
+    ],
+    "route": "components/forms/form-field",
+    "tags": [
+      "component",
+      "form",
+      "field",
+      "label",
+      "input wrapper"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Label options",
+        "href": "#label-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Simple",
+        "href": "#simple",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "With help text",
+        "href": "#with-help-text",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "With error message",
+        "href": "#with-error-message",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Required with info icon and help text",
+        "href": "#required-with-info-icon-and-help-text",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Label on the left with info icon and help text",
+        "href": "#label-on-the-left-with-info-icon-and-help-text",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Small",
+        "href": "#small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=349-2635&m=dev",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nComposed of several elements, a label, optional helper icon, a text input. There\nis also an optional helper text feature that presents at the bottom of the\nfield.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=349-2635&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Label options\n\n#### Simple\n\nLabel is used to describe the form.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n    </FormField.Root>\n  )\n}\n```\n\n#### With help text\n\nLabel paired with form and description to give users extra clarification.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>Help Text</FormField.Description>\n    </FormField.Root>\n  )\n}\n```\n\n#### With error message\n\nExplain errors to the user in an eye catching way.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isInvalid>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Error>\n        Error message\n      </FormField.Error>\n    </FormField.Root>\n  )\n}\n```\n\n#### Required with info icon and help text\n\nThis is the default placement of labels. Info button should always open an info\ndialog, not just a tooltip on hover.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n#### Label on the left with info icon and help text\n\nThese can be used to make the page a little more condensed for the user.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root direction=\"row\" isRequired>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n### Size\n\n#### Medium\n\nThis is the default size for form fields.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired size=\"md\">\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n#### Small\n\nUse to condense forms.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired size=\"sm\">\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" size=\"sm\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nComposed of several elements, a label, optional helper icon, a text input. There\nis also an optional helper text feature that presents at the bottom of the\nfield.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=349-2635&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Label options\n\n#### Simple\n\nLabel is used to describe the form.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n    </FormField.Root>\n  )\n}\n```\n\n#### With help text\n\nLabel paired with form and description to give users extra clarification.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>Help Text</FormField.Description>\n    </FormField.Root>\n  )\n}\n```\n\n#### With error message\n\nExplain errors to the user in an eye catching way.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isInvalid>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Error>\n        Error message\n      </FormField.Error>\n    </FormField.Root>\n  )\n}\n```\n\n#### Required with info icon and help text\n\nThis is the default placement of labels. Info button should always open an info\ndialog, not just a tooltip on hover.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n#### Label on the left with info icon and help text\n\nThese can be used to make the page a little more condensed for the user.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root direction=\"row\" isRequired>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n### Size\n\n#### Medium\n\nThis is the default size for form fields.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired size=\"md\">\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n#### Small\n\nUse to condense forms.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired size=\"sm\">\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" size=\"sm\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>\n        Help Text\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Label options",
+          "href": "#label-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Simple",
+          "href": "#simple",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With help text",
+          "href": "#with-help-text",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With error message",
+          "href": "#with-error-message",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required with info icon and help text",
+          "href": "#required-with-info-icon-and-help-text",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Label on the left with info icon and help text",
+          "href": "#label-on-the-left-with-info-icon-and-help-text",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small",
+          "href": "#small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => {\n  const [val, setVal] = useState('Input value');\n\n  return (\n    <FormField.Root isRequired>\n      <FormField.Label>Label</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"full\" value={val} onChange={(v)=>setVal(v)} placeholder=\"Enter something...\" />\n      </FormField.Input>\n      <FormField.Description>Help Text</FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  )\n}\n```\n\n### Accessibility standards\n\n- **Non-text content:** Provide text alternatives for any non-text content\n  within or associated with form fields (e.g., icons, images). Use alt text for\n  images and provide text equivalents for other non-text content.\n- **Info and relationships:** Use the `<label>` element to programmatically\n  associate labels with form fields. Ensure that assistive technologies can\n  determine the relationship between labels and their corresponding inputs.\n- **Group related fields:** Group related form fields using `<fieldset>` and\n  provide a `<legend>` to create logical sections.\n- **ARIA attributes:** Use ARIA attributes (e.g., `aria-describedby`,\n  `aria-labelledby`) to establish relationships between form fields and related\n  elements.\n- **Use of color:** Avoid relying solely on color to convey information or\n  indicate the state of form fields (e.g., required fields, error states).\n  Provide redundant visual cues, such as icons, text, or patterns, to supplement\n  color-based indicators.\n- **Color contrast:** Ensure sufficient color contrast between form field\n  labels, input fields, borders, and background colors. Use a contrast checking\n  tool to verify that the contrast ratio meets the minimum requirements.\n- **Keyboard accessibility:** Make all form field functionality operable using\n  the keyboard. Enable users to navigate between form fields using the Tab key.\n  Allow users to activate form field controls (e.g., buttons, checkboxes, radio\n  buttons) using the Spacebar or Enter key. Ensure that keyboard focus is not\n  trapped within form fields.\n- **Focus visible:** Provide a clear and visible focus indicator for form fields\n  when they receive keyboard focus. Visually distinguish the focus state from\n  the default state using outlines, highlights, or other visual cues. Avoid\n  relying solely on color changes to indicate focus.\n- **On focus:** Prevent form fields from unexpectedly changing the context of\n  the page when they receive focus. Ensure that any context changes are\n  initiated by user actions, such as submitting the form.\n- **Error identification:** Identify and describe input errors in text when they\n  are automatically detected. Display clear and concise error messages near the\n  corresponding form fields.\n- **Labels or instructions:** Provide clear, concise, and descriptive labels or\n  instructions for all form fields. Write labels that accurately reflect the\n  purpose of the form fields. Provide instructions about the expected input\n  format or requirements. Avoid using placeholder text as a replacement for\n  visible labels.\n- **Error suggestion:** If an input error is automatically detected and\n  suggestions for correction are known, provide the suggestions to the user,\n  unless it would jeopardize the security or purpose of the content.\n- **Name, role, value:** Use semantic HTML elements (e.g., `<input>`,\n  `<textarea>`, `<select>`) to define the role, name, and value of form fields.\n  Ensure that assistive technologies can correctly interpret form fields and\n  their attributes. Use ARIA attributes when necessary to provide additional\n  information to assistive technologies, especially for complex or custom form\n  fields.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { FormField, type FormFieldProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nFormField is a compound component that provides a structured container for form inputs with automatic accessibility via React Aria. It coordinates label, input, description, and error elements:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Username</FormField.Label>\n    <FormField.Input>\n      <TextInput placeholder=\"Enter your username\" />\n    </FormField.Input>\n    <FormField.Description>\n      Must be 3-20 characters, letters and numbers only\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n## Usage examples\n\n### Size options\n\nFormField supports two size variants that affect the typography scale:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <FormField.Root size=\"sm\">\n      <FormField.Label>Small Size</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"Small field\" />\n      </FormField.Input>\n      <FormField.Description>Smaller typography for compact layouts</FormField.Description>\n    </FormField.Root>\n\n    <FormField.Root size=\"md\">\n      <FormField.Label>Medium Size (default)</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"Medium field\" />\n      </FormField.Input>\n      <FormField.Description>Standard typography for most forms</FormField.Description>\n    </FormField.Root>\n  </Stack>\n);\n```\n\n### Layout direction\n\nControl the label and input positioning with the `direction` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <FormField.Root direction=\"column\">\n      <FormField.Label>Column Layout (default)</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"Label above input\" />\n      </FormField.Input>\n      <FormField.Description>Label and input stacked vertically</FormField.Description>\n    </FormField.Root>\n\n    <FormField.Root direction=\"row\">\n      <FormField.Label>Row Layout</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"Label beside input\" />\n      </FormField.Input>\n      <FormField.Description>Label and input side by side</FormField.Description>\n    </FormField.Root>\n  </Stack>\n);\n```\n\n### Required fields\n\nMark fields as required to display a visual indicator and set ARIA attributes:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root isRequired>\n    <FormField.Label>Email Address</FormField.Label>\n    <FormField.Input>\n      <TextInput type=\"email\" placeholder=\"your@email.com\" />\n    </FormField.Input>\n    <FormField.Description>\n      We'll never share your email with anyone else\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n### Validation errors\n\nDisplay error messages when validation fails using the `isInvalid` prop:\n\n```jsx live-dev\nconst App = () => {\n  const [email, setEmail] = React.useState('invalid-email');\n  const [touched, setTouched] = React.useState(false);\n\n  const isValid = email.includes('@') && email.includes('.');\n  const showError = touched && !isValid;\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <FormField.Root isInvalid={showError} isRequired>\n        <FormField.Label>Email Address</FormField.Label>\n        <FormField.Input>\n          <TextInput\n            type=\"email\"\n            value={email}\n            onChange={(e) => setEmail(e.target.value)}\n            onBlur={() => setTouched(true)}\n            placeholder=\"your@email.com\"\n          />\n        </FormField.Input>\n        <FormField.Description>Enter a valid email address</FormField.Description>\n        <FormField.Error>Please enter a valid email address</FormField.Error>\n      </FormField.Root>\n\n      <Text fontSize=\"300\" color=\"neutral.11\">\n        Current value: {email}\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Disabled state\n\nDisable user interaction with the field using `isDisabled`:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root isDisabled>\n    <FormField.Label>Account Type</FormField.Label>\n    <FormField.Input>\n      <TextInput value=\"Premium (locked)\" readOnly />\n    </FormField.Input>\n    <FormField.Description>\n      Contact support to change your account type\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n### Read-only state\n\nDisplay values without allowing edits using `isReadOnly`:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root isReadOnly>\n    <FormField.Label>User ID</FormField.Label>\n    <FormField.Input>\n      <TextInput value=\"user-12345-abcde\" readOnly />\n    </FormField.Input>\n    <FormField.Description>\n      Your unique user identifier (cannot be changed)\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n### Field descriptions\n\nProvide helpful context with description text that's automatically linked for screen readers:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <FormField.Root>\n      <FormField.Label>Password</FormField.Label>\n      <FormField.Input>\n        <PasswordInput placeholder=\"Enter password\" />\n      </FormField.Input>\n      <FormField.Description>\n        Must be at least 8 characters with uppercase, lowercase, and numbers\n      </FormField.Description>\n    </FormField.Root>\n\n    <FormField.Root>\n      <FormField.Label>Confirm Password</FormField.Label>\n      <FormField.Input>\n        <PasswordInput placeholder=\"Re-enter password\" />\n      </FormField.Input>\n      <FormField.Description>\n        Enter the same password for verification\n      </FormField.Description>\n    </FormField.Root>\n  </Stack>\n);\n```\n\n### InfoBox for contextual help\n\nAdd an info icon with a popover for additional field context:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>API Key</FormField.Label>\n    <FormField.InfoBox>\n      <Stack direction=\"column\" gap=\"300\" padding=\"400\">\n        <Text fontWeight=\"500\">About API Keys</Text>\n        <Text>\n          Your API key can be found in your account settings under \"Developer Tools\".\n          Keep it secure and never share it publicly or commit it to version control.\n        </Text>\n        <Text>\n          If you believe your key has been compromised, regenerate it immediately\n          from your account settings.\n        </Text>\n      </Stack>\n    </FormField.InfoBox>\n    <FormField.Input>\n      <TextInput placeholder=\"sk_live_...\" type=\"password\" />\n    </FormField.Input>\n    <FormField.Description>\n      Used for API authentication\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n### With different input types\n\nFormField works with any input component:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <FormField.Root>\n      <FormField.Label>Full Name</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"John Doe\" />\n      </FormField.Input>\n    </FormField.Root>\n\n    <FormField.Root>\n      <FormField.Label>Age</FormField.Label>\n      <FormField.Input>\n        <NumberInput placeholder=\"25\" min={0} max={120} />\n      </FormField.Input>\n    </FormField.Root>\n\n    <FormField.Root>\n      <FormField.Label>Country</FormField.Label>\n      <FormField.Input>\n        <Select.Root>\n          <Select.Options placeholder=\"Select your country\">\n            <Select.Option id=\"us\">United States</Select.Option>\n            <Select.Option id=\"uk\">United Kingdom</Select.Option>\n            <Select.Option id=\"ca\">Canada</Select.Option>\n            <Select.Option id=\"au\">Australia</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </FormField.Input>\n    </FormField.Root>\n\n    <FormField.Root>\n      <FormField.Label>Bio</FormField.Label>\n      <FormField.Input>\n        <MultilineTextInput placeholder=\"Tell us about yourself...\" />\n      </FormField.Input>\n    </FormField.Root>\n  </Stack>\n);\n```\n\n## Component requirements\n\n## Accessibility\n\nFormField implements comprehensive accessibility features through React Aria's `useField` hook, automatically managing ARIA attributes for all child components.\n\n#### Role\n\n- The root container uses appropriate semantic HTML structure\n- Input elements receive proper roles from their respective components\n- Label associations are automatic via React Aria\n\n#### Labeling\n\n- **Automatic label association**: `FormField.Label` automatically links to the input via `aria-labelledby`\n- **Required indicator**: Visual asterisk and `aria-required=\"true\"` when `isRequired={true}`\n- **Description linking**: `FormField.Description` automatically links via `aria-describedby`\n- **Error linking**: `FormField.Error` automatically links via `aria-errormessage` when `isInvalid={true}`\n- **InfoBox accessibility**: InfoBox trigger has appropriate `aria-label` and popover role\n\n#### Keyboard navigation\n\nFormField itself doesn't handle keyboard interaction - navigation is managed by the input components it contains. The InfoBox trigger supports standard button keyboard interaction:\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to/from InfoBox trigger |\n| `Enter` / `Space` | Open InfoBox popover |\n| `Escape` | Close InfoBox popover (when open) |\n\nStandard keyboard navigation for input elements applies based on the input type used within `FormField.Input`.\n\n#### Persistent ID\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** `id` to the component:\n\n```tsx\n<FormField.Root id=\"user-email-field\">\n  <FormField.Label>Email Address</FormField.Label>\n  <FormField.Input>\n    <TextInput />\n  </FormField.Input>\n</FormField.Root>\n```\n\nThe `id` is used by React Aria to generate consistent IDs for all child elements, ensuring proper accessibility attribute relationships.\n\n## API reference\n\n<PropsTable id=\"FormField\" />\n\n## Common patterns\n\n### Complete form with validation\n\nA realistic login form with validation and state management:\n\n```jsx live-dev\nconst App = () => {\n  const [formData, setFormData] = React.useState({\n    email: '',\n    password: ''\n  });\n  const [errors, setErrors] = React.useState({});\n  const [touched, setTouched] = React.useState({});\n\n  const validate = () => {\n    const newErrors = {};\n\n    if (!formData.email) {\n      newErrors.email = 'Email is required';\n    } else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}$/i.test(formData.email)) {\n      newErrors.email = 'Invalid email address';\n    }\n\n    if (!formData.password) {\n      newErrors.password = 'Password is required';\n    } else if (formData.password.length < 8) {\n      newErrors.password = 'Password must be at least 8 characters';\n    }\n\n    setErrors(newErrors);\n    return Object.keys(newErrors).length === 0;\n  };\n\n  const handleSubmit = () => {\n    setTouched({ email: true, password: true });\n    if (validate()) {\n      console.log('Form submitted:', formData);\n    }\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"500\">\n      <FormField.Root\n        isRequired\n        isInvalid={!!(errors.email && touched.email)}\n      >\n        <FormField.Label>Email Address</FormField.Label>\n        <FormField.Input>\n          <TextInput\n            type=\"email\"\n            value={formData.email}\n            onChange={(value) => setFormData({ ...formData, email: value })}\n            onBlur={() => setTouched({ ...touched, email: true })}\n            placeholder=\"your@email.com\"\n          />\n        </FormField.Input>\n        <FormField.Error>{errors.email}</FormField.Error>\n      </FormField.Root>\n\n      <FormField.Root\n        isRequired\n        isInvalid={!!(errors.password && touched.password)}\n      >\n        <FormField.Label>Password</FormField.Label>\n        <FormField.Input>\n          <PasswordInput\n            value={formData.password}\n            onChange={(value) => setFormData({ ...formData, password: value })}\n            onBlur={() => setTouched({ ...touched, password: true })}\n            placeholder=\"Enter password\"\n          />\n        </FormField.Input>\n        <FormField.Description>Minimum 8 characters</FormField.Description>\n        <FormField.Error>{errors.password}</FormField.Error>\n      </FormField.Root>\n\n      <Button onClick={handleSubmit}>Log In</Button>\n\n      <Text fontSize=\"300\" color=\"neutral.11\">\n        Email: {formData.email || '(empty)'} | Password length: {formData.password.length}\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Multi-step form with validation\n\nBuild multi-step forms with per-step validation:\n\n```jsx live-dev\nconst App = () => {\n  const [step, setStep] = React.useState('personal');\n  const [formData, setFormData] = React.useState({\n    firstName: '',\n    lastName: '',\n    email: '',\n    password: '',\n    notifications: true\n  });\n  const [errors, setErrors] = React.useState({});\n  const [touched, setTouched] = React.useState({});\n\n  const validateStep = (currentStep) => {\n    const newErrors = {};\n\n    if (currentStep === 'personal') {\n      if (!formData.firstName) newErrors.firstName = 'First name is required';\n      if (!formData.lastName) newErrors.lastName = 'Last name is required';\n    } else if (currentStep === 'account') {\n      if (!formData.email) newErrors.email = 'Email is required';\n      if (!formData.password) newErrors.password = 'Password is required';\n      else if (formData.password.length < 8) {\n        newErrors.password = 'Password must be at least 8 characters';\n      }\n    }\n\n    setErrors(newErrors);\n    return Object.keys(newErrors).length === 0;\n  };\n\n  const handleNext = () => {\n    if (validateStep(step)) {\n      if (step === 'personal') setStep('account');\n      else if (step === 'account') setStep('preferences');\n    }\n  };\n\n  const handleBack = () => {\n    if (step === 'account') setStep('personal');\n    else if (step === 'preferences') setStep('account');\n  };\n\n  const handleSubmit = () => {\n    if (validateStep(step)) {\n      console.log('Form submitted:', formData);\n    }\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"500\">\n      <Text fontWeight=\"500\" fontSize=\"400\">\n        Step {step === 'personal' ? '1' : step === 'account' ? '2' : '3'} of 3: {\n          step === 'personal' ? 'Personal Info' :\n          step === 'account' ? 'Account Details' :\n          'Preferences'\n        }\n      </Text>\n\n      {step === 'personal' && (\n        <>\n          <FormField.Root\n            isRequired\n            isInvalid={!!(errors.firstName && touched.firstName)}\n          >\n            <FormField.Label>First Name</FormField.Label>\n            <FormField.Input>\n              <TextInput\n                value={formData.firstName}\n                onChange={(value) => setFormData({ ...formData, firstName: value })}\n                onBlur={() => setTouched({ ...touched, firstName: true })}\n              />\n            </FormField.Input>\n            <FormField.Error>{errors.firstName}</FormField.Error>\n          </FormField.Root>\n\n          <FormField.Root\n            isRequired\n            isInvalid={!!(errors.lastName && touched.lastName)}\n          >\n            <FormField.Label>Last Name</FormField.Label>\n            <FormField.Input>\n              <TextInput\n                value={formData.lastName}\n                onChange={(value) => setFormData({ ...formData, lastName: value })}\n                onBlur={() => setTouched({ ...touched, lastName: true })}\n              />\n            </FormField.Input>\n            <FormField.Error>{errors.lastName}</FormField.Error>\n          </FormField.Root>\n        </>\n      )}\n\n      {step === 'account' && (\n        <>\n          <FormField.Root\n            isRequired\n            isInvalid={!!(errors.email && touched.email)}\n          >\n            <FormField.Label>Email</FormField.Label>\n            <FormField.Input>\n              <TextInput\n                type=\"email\"\n                value={formData.email}\n                onChange={(value) => setFormData({ ...formData, email: value })}\n                onBlur={() => setTouched({ ...touched, email: true })}\n              />\n            </FormField.Input>\n            <FormField.Error>{errors.email}</FormField.Error>\n          </FormField.Root>\n\n          <FormField.Root\n            isRequired\n            isInvalid={!!(errors.password && touched.password)}\n          >\n            <FormField.Label>Password</FormField.Label>\n            <FormField.Input>\n              <PasswordInput\n                value={formData.password}\n                onChange={(value) => setFormData({ ...formData, password: value })}\n                onBlur={() => setTouched({ ...touched, password: true })}\n              />\n            </FormField.Input>\n            <FormField.Description>Minimum 8 characters</FormField.Description>\n            <FormField.Error>{errors.password}</FormField.Error>\n          </FormField.Root>\n        </>\n      )}\n\n      {step === 'preferences' && (\n        <>\n          <FormField.Root>\n            <FormField.Label>Email Notifications</FormField.Label>\n            <FormField.Input>\n              <Checkbox\n                isSelected={formData.notifications}\n                onChange={(value) => setFormData({ ...formData, notifications: value })}\n              >\n                Send me product updates and newsletters\n              </Checkbox>\n            </FormField.Input>\n            <FormField.Description>\n              You can change this preference anytime in settings\n            </FormField.Description>\n          </FormField.Root>\n\n          <Text fontSize=\"300\" color=\"neutral.11\">\n            Review: {formData.firstName} {formData.lastName} ({formData.email})\n          </Text>\n        </>\n      )}\n\n      <Stack direction=\"row\" gap=\"300\">\n        {step !== 'personal' && (\n          <Button variant=\"outline\" onClick={handleBack}>\n            Back\n          </Button>\n        )}\n        {step !== 'preferences' ? (\n          <Button onClick={handleNext}>Next</Button>\n        ) : (\n          <Button onClick={handleSubmit}>Submit</Button>\n        )}\n      </Stack>\n    </Stack>\n  );\n};\n```\n\n### Conditional field visibility\n\nShow or hide fields based on form state:\n\n```jsx live-dev\nconst App = () => {\n  const [accountType, setAccountType] = React.useState('personal');\n  const [needsShipping, setNeedsShipping] = React.useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"500\">\n      <FormField.Root>\n        <FormField.Label>Account Type</FormField.Label>\n        <FormField.Input>\n          <Select.Root\n            selectedKey={accountType}\n            onSelectionChange={setAccountType}\n          >\n            <Select.Options placeholder=\"Select account type\">\n              <Select.Option id=\"personal\">Personal</Select.Option>\n              <Select.Option id=\"business\">Business</Select.Option>\n            </Select.Options>\n          </Select.Root>\n        </FormField.Input>\n      </FormField.Root>\n\n      {accountType === 'business' && (\n        <FormField.Root isRequired>\n          <FormField.Label>Company Name</FormField.Label>\n          <FormField.Input>\n            <TextInput placeholder=\"Acme Corporation\" />\n          </FormField.Input>\n          <FormField.Description>\n            Your registered business name\n          </FormField.Description>\n        </FormField.Root>\n      )}\n\n      <Checkbox\n        isSelected={needsShipping}\n        onChange={setNeedsShipping}\n      >\n        Ship to different address\n      </Checkbox>\n\n      {needsShipping && (\n        <FormField.Root isRequired>\n          <FormField.Label>Shipping Address</FormField.Label>\n          <FormField.Input>\n            <MultilineTextInput\n              placeholder=\"123 Main St, City, State ZIP\"\n            />\n          </FormField.Input>\n        </FormField.Root>\n      )}\n    </Stack>\n  );\n};\n```\n\n### React 19 form state integration\n\nFormField integrates seamlessly with React 19's built-in form state features, including `useActionState` for progressive enhancement and server-side validation. This example demonstrates the standard React 19 pattern where validation occurs on form submission:\n\n```jsx live-dev\nconst App = () => {\n  const [state, submitAction, isPending] = React.useActionState(\n    async (previousState, formData) => {\n      // Simulate async server-side validation\n      await new Promise(resolve => setTimeout(resolve, 1000));\n\n      const errors = {};\n      const email = formData.get('email');\n      const password = formData.get('password');\n\n      if (!email) {\n        errors.email = 'Email is required';\n      } else if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}$/i.test(email)) {\n        errors.email = 'Invalid email address';\n      }\n\n      if (!password) {\n        errors.password = 'Password is required';\n      } else if (password.length < 8) {\n        errors.password = 'Password must be at least 8 characters';\n      }\n\n      if (Object.keys(errors).length > 0) {\n        return { success: false, errors, data: null };\n      }\n\n      return {\n        success: true,\n        message: 'Login successful!',\n        data: { email, password: '••••••••' },\n        errors: {}\n      };\n    },\n    { success: false, errors: {}, data: null }\n  );\n\n  return (\n    <form action={submitAction} noValidate>\n      <Stack direction=\"column\" gap=\"500\">\n        <FormField.Root\n          isRequired\n          isInvalid={!!(state.errors && state.errors.email)}\n        >\n          <FormField.Label>Email Address</FormField.Label>\n          <FormField.Input>\n            <TextInput\n              type=\"email\"\n              name=\"email\"\n              placeholder=\"your@email.com\"\n              autoComplete=\"email\"\n            />\n          </FormField.Input>\n          <FormField.Error>{state.errors?.email}</FormField.Error>\n        </FormField.Root>\n\n        <FormField.Root\n          isRequired\n          isInvalid={!!(state.errors && state.errors.password)}\n        >\n          <FormField.Label>Password</FormField.Label>\n          <FormField.Input>\n            <PasswordInput\n              name=\"password\"\n              placeholder=\"Enter password\"\n              autoComplete=\"current-password\"\n            />\n          </FormField.Input>\n          <FormField.Description>Minimum 8 characters</FormField.Description>\n          <FormField.Error>{state.errors?.password}</FormField.Error>\n        </FormField.Root>\n\n        <Button type=\"submit\" isDisabled={isPending}>\n          {isPending ? 'Logging in...' : 'Log In'}\n        </Button>\n\n        {state.success && state.data && (\n          <Alert.Root colorPalette=\"positive\">\n            <Alert.Title>{state.message}</Alert.Title>\n            <Alert.Description>\n              Email: {state.data.email}\n            </Alert.Description>\n          </Alert.Root>\n        )}\n      </Stack>\n    </form>\n  );\n};\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using FormField within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify FormField renders with all parts correctly structured\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - Basic rendering\", () => {\n  it(\"renders with label and input\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Username</FormField.Label>\n          <FormField.Input>\n            <TextInput placeholder=\"Enter username\" />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Username\")).toBeInTheDocument();\n    expect(screen.getByPlaceholderText(\"Enter username\")).toBeInTheDocument();\n  });\n\n  it(\"renders with description\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Password</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"password\" />\n          </FormField.Input>\n          <FormField.Description>\n            Must be at least 8 characters\n          </FormField.Description>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"Must be at least 8 characters\")\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with all parts\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n          <FormField.Description>Your contact email</FormField.Description>\n          <FormField.Error>Invalid email format</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Email\")).toBeInTheDocument();\n    expect(screen.getByText(\"Your contact email\")).toBeInTheDocument();\n    expect(screen.getByText(\"Invalid email format\")).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify ARIA attributes and label associations\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - Accessibility\", () => {\n  it(\"associates label with input via aria-labelledby\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Username</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    const label = screen.getByText(\"Username\");\n\n    expect(input).toHaveAttribute(\"aria-labelledby\", label.id);\n  });\n\n  it(\"associates description with input via aria-describedby\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Username</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n          <FormField.Description>\n            Must be at least 8 characters\n          </FormField.Description>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    const description = screen.getByText(\"Must be at least 8 characters\");\n\n    expect(input.getAttribute(\"aria-describedby\")).toContain(description.id);\n  });\n\n  it(\"marks input as required when isRequired is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isRequired>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-required\", \"true\");\n  });\n\n  it(\"marks input as invalid when isInvalid is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n          <FormField.Error>Invalid email</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n});\n```\n\n### Size Variants\n\nTest different size variants\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - Size variants\", () => {\n  it(\"renders small size\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root size=\"sm\">\n          <FormField.Label>Small Field</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Small Field\")).toBeInTheDocument();\n  });\n\n  it(\"renders medium size (default)\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root size=\"md\">\n          <FormField.Label>Medium Field</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Medium Field\")).toBeInTheDocument();\n  });\n});\n```\n\n### Layout Direction\n\nTest column and row layout directions\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - Layout direction\", () => {\n  it(\"renders with column direction (default)\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root direction=\"column\">\n          <FormField.Label>Column Layout</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Column Layout\")).toBeInTheDocument();\n  });\n\n  it(\"renders with row direction\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root direction=\"row\">\n          <FormField.Label>Row Layout</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Row Layout\")).toBeInTheDocument();\n  });\n});\n```\n\n### Component States\n\nTest required, invalid, disabled, and read-only states\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - States\", () => {\n  it(\"displays required indicator\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isRequired>\n          <FormField.Label>Required Field</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-required\", \"true\");\n  });\n\n  it(\"displays error when invalid\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n          <FormField.Error>Please enter a valid email</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Please enter a valid email\")).toBeInTheDocument();\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"disables input when isDisabled is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isDisabled>\n          <FormField.Label>Disabled Field</FormField.Label>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toBeDisabled();\n  });\n\n  it(\"makes input read-only when isReadOnly is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isReadOnly>\n          <FormField.Label>Read-only Field</FormField.Label>\n          <FormField.Input>\n            <TextInput value=\"Cannot edit\" />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    expect(input).toHaveAttribute(\"readonly\");\n  });\n});\n```\n\n### Error Visibility\n\nTest that errors only show when isInvalid is true\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - Error visibility\", () => {\n  it(\"hides error when isInvalid is false\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid={false}>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n          <FormField.Error>This should be hidden</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByText(\"This should be hidden\")).not.toBeInTheDocument();\n  });\n\n  it(\"shows error when isInvalid is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root isInvalid={true}>\n          <FormField.Label>Email</FormField.Label>\n          <FormField.Input>\n            <TextInput type=\"email\" />\n          </FormField.Input>\n          <FormField.Error>This should be visible</FormField.Error>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"This should be visible\")).toBeInTheDocument();\n  });\n});\n```\n\n### User Interactions\n\nTest user input and validation flows\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - User interactions\", () => {\n  it(\"handles user input\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>Username</FormField.Label>\n          <FormField.Input>\n            <TextInput placeholder=\"Enter username\" />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    const input = screen.getByRole(\"textbox\");\n    await user.type(input, \"testuser\");\n\n    expect(input).toHaveValue(\"testuser\");\n  });\n\n  it(\"supports validation on blur\", async () => {\n    const user = userEvent.setup();\n\n    const TestComponent = () => {\n      const [invalid, setInvalid] = React.useState(false);\n      const [value, setValue] = React.useState(\"\");\n\n      const handleChange = (newValue: string) => {\n        setValue(newValue);\n      };\n\n      const handleBlur = () => {\n        setInvalid(value.length < 3);\n      };\n\n      return (\n        <NimbusProvider>\n          <FormField.Root isInvalid={invalid}>\n            <FormField.Label>Username</FormField.Label>\n            <FormField.Input>\n              <TextInput\n                value={value}\n                onChange={handleChange}\n                onBlur={handleBlur}\n              />\n            </FormField.Input>\n            <FormField.Error>Must be at least 3 characters</FormField.Error>\n          </FormField.Root>\n        </NimbusProvider>\n      );\n    };\n\n    render(<TestComponent />);\n\n    const input = screen.getByRole(\"textbox\");\n    await user.type(input, \"ab\");\n    await user.tab(); // Blur the input\n\n    expect(\n      screen.getByText(\"Must be at least 3 characters\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### InfoBox Functionality\n\nTest InfoBox popover interactions\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport React from \"react\";\nimport { FormField, TextInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FormField - InfoBox\", () => {\n  it(\"renders InfoBox trigger when InfoBox is provided\", () => {\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>API Key</FormField.Label>\n          <FormField.InfoBox>\n            Additional information about this field\n          </FormField.InfoBox>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    // InfoBox trigger button should be present (help icon)\n    const buttons = screen.getAllByRole(\"button\");\n    expect(buttons.length).toBeGreaterThan(0);\n  });\n\n  it(\"shows InfoBox content when trigger is clicked\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <FormField.Root>\n          <FormField.Label>API Key</FormField.Label>\n          <FormField.InfoBox>\n            Your API key is sensitive information\n          </FormField.InfoBox>\n          <FormField.Input>\n            <TextInput />\n          </FormField.Input>\n        </FormField.Root>\n      </NimbusProvider>\n    );\n\n    // Click the help icon button\n    const helpButton = screen.getAllByRole(\"button\")[0];\n    await user.click(helpButton);\n\n    // Wait for popover content\n    await screen.findByText(\"Your API key is sensitive information\");\n    expect(\n      screen.getByText(\"Your API key is sensitive information\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook - FormField](https://nimbus-storybook.vercel.app/?path=/docs/components-formfield--docs)\n- [React Aria - useField](https://react-spectrum.adobe.com/react-aria/useField.html) - Underlying accessibility implementation\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Layout direction",
+          "href": "#layout-direction",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required fields",
+          "href": "#required-fields",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Validation errors",
+          "href": "#validation-errors",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Field descriptions",
+          "href": "#field-descriptions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "InfoBox for contextual help",
+          "href": "#infobox-for-contextual-help",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With different input types",
+          "href": "#with-different-input-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Role",
+          "href": "#role",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling",
+          "href": "#labeling",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Persistent ID",
+          "href": "#persistent-id",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Complete form with validation",
+          "href": "#complete-form-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-step form with validation",
+          "href": "#multi-step-form-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional field visibility",
+          "href": "#conditional-field-visibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "React 19 form state integration",
+          "href": "#react-19-form-state-integration",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility Tests",
+          "href": "#accessibility-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size Variants",
+          "href": "#size-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Layout Direction",
+          "href": "#layout-direction-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component States",
+          "href": "#component-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error Visibility",
+          "href": "#error-visibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "User Interactions",
+          "href": "#user-interactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "InfoBox Functionality",
+          "href": "#infobox-functionality",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDesign guidelines offer a set of standardized rules and recommendations that\nensure consistency, usability, and accessibility across all design elements and\ninteractions.\n\nRelated guidelines [text-fields](#).\n\n### Best practices\n\n- **Clarity and simplicity:**\n  - Minimize the number of fields. Only ask for essential information.\n  - Use clear, concise labels that accurately describe the required input.\n  - Choose what position (top or left) the labels will be and make it consistent\n    in the area to help with scanning.\n- **Labels:**\n  - Place labels above or to the left of input fields.\n  - Keep labels short and descriptive.\n  - Avoid using placeholders as labels.\n- **Error handling:**\n  - Display error messages clearly and prominently.\n  - Use specific and helpful error messages and provide suggestions for\n    correcting errors.\n\n#### Labels\n\nFor label text, use a short, catch-all description (1-3 words) of the\ninformation that a user needs to provide. Label text that gets too long can be\noverwhelming and distracting, especially in complex interactions and long forms.\nSupplementary information or requirements about what to input can be shown in\nhelp text below the field, or in a tooltip.\n\n- **Use sentence case:** This follows our consistent style, unless statement\n  contains words that are branded proper nouns.\n- **Don’t add a colon (:) at the end of a field label:** The design of the\n  component already communicates the relationship between the label and the\n  input field.\n- **Use clear and concise language:** Try to keep labels to 1-3 words. Avoid\n  jargon or technical terms that the user might not understand.\n- **Be specific, brief, and descriptive:** Ensure labels are easily scannable\n  and reflect the function of the element. If you need instructional text, use a\n  helper label beneath.\n- **Avoid ambiguity:** Labels should leave no room for misinterpretation.\n- **Internalization friendly:** Be aware that translation lengthens by 20% on\n  average, but also avoid creating a sentence using the label combined with the\n  response from a user. (e.g., Label: My favorite color is... Response...Green.\n  Sentence structures between languages vary greatly.)\n\n### Helper text vs info icon\n\nUse the right informative tool to aid your user to understand what is needed.\nSee [info button](#) for more guidelines.\n\n- **Info Button:**\n  - **Complex or lengthy information:** When you need to provide more than a\n    short sentence or two of explanation. By default the info button will open a\n    dialog overlay. It can be used to show a tooltip on hover, but the amount of\n    information a popover and a help text can contain is similar. If there is a\n    want to simplify the UI, this can be used, but test to make sure that this\n    information needs to be shown without interaction from a user.\n  - **Progressive disclosure:** To avoid cluttering the form with too much text\n    upfront, revealing details only when the user actively seeks them.\n  - **Contextual help:** When the help information is very specific to a\n    particular field or a user's current state within the form.  \n- **Help Text:**\n  - **Short, concise explanations:** For simple clarifications or hints about\n    the expected input. Try to keep helper text below 150 characters.\n  - **Formatting guidance:** To provide examples of the required format (e.g.,\n    date formats, phone number patterns).\n  - **Input requirements:** To specify character limits, password rules, or\n    other constraints.\n  - **Immediate visibility:** When it's crucial for the user to see the guidance\n    without any extra action like a click or a hover to display.\n\n### Usage\n\nBe sure to give enough information to the user to understand the form without\nbeing overwhelmed. Prioritize clarity and function over personality and over\nexplanation. To increase understanding, test your forms with users to understand\nwhere confusion might occur.\n\n### Formatting\n\nBe consistent with your use of form fields label placements and size.\n\n> [!TIP]\\\n> **Do**\n>\n> - Have one placement for labels in the same form, and consistently choose one\n>   size for the entire form.\n> - Help text is used to show the user what the accepted formatting will be.\n>   Placeholder text can be used when needed but help text is preferred for\n>   accessibility.\n> - OK to capitalize proper nouns in labels instead of using sentence case.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <FormField.Root isRequired>\n      <FormField.Label>First name</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"9600\" />\n      </FormField.Input>\n    </FormField.Root>\n    <FormField.Root isRequired>\n      <FormField.Label>Social Security Number</FormField.Label>\n      <FormField.Input>\n        <TextInput width=\"9600\" />\n      </FormField.Input>\n      <FormField.Description>\n        Format: XXX-XX-XXXX\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Use sentence case for labels. Do not capitalize every word.\n> - Do not combine top and side labels within the form.\n> - Only use description text and helper icons when it is needed.\n> - Placeholder text should give hints to the user about what is expected, not\n>   be used for quirky brand copy.\n> - Do not mix form sizes.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <FormField.Root size=\"md\" isRequired>\n      <FormField.Label>First Name</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"What should we call you?\" width=\"9600\" />\n      </FormField.Input>\n    </FormField.Root>\n    <FormField.Root direction=\"row\" size=\"sm\" isRequired>\n      <FormField.Label>Last name</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"What's in a name?\" width=\"8000\" />\n      </FormField.Input>\n    </FormField.Root>\n  </Stack>\n)\n```\n\n### Validation\n\nCommunicate clearly with users about how to correct form validation issues.\n\n> [!TIP]\\\n> **Do**\n>\n> - Have succinct reasons why the error happened for the user to correct.\n> - Keep previously entered information so a user can check their work to spot\n>   mistakes easier.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <FormField.Root isRequired isInvalid>\n      <FormField.Label>Social Security Number (SSN)</FormField.Label>\n      <FormField.Input>\n        <TextInput value=\"555-55-5555\" width=\"9600\" />\n      </FormField.Input>\n      <FormField.Error>\n        This information does not match\n      </FormField.Error>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don’t forget to use error messaging. Convey clearly how a user can make\n>   corrections to move forward through the form.\n> - Don’t clear the previously input information if applicable, to help the user\n>   understand the mistake, and provide the best user experience.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <FormField.Root isRequired isInvalid>\n      <FormField.Label>Social Security Number (SSN)</FormField.Label>\n      <FormField.Input>\n        <TextInput placeholder=\"XXX-XX-XXXX\" width=\"9600\" />\n      </FormField.Input>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  </Stack>\n)\n```\n\n### Labels\n\nClear labels are essential for a smooth user experience. They reduce confusion,\nimprove accessibility for everyone, and build user confidence by making\ninterfaces intuitive and easy to navigate. Simply put, clear labels mean happy\nusers.\n\n> [!TIP]\\\n> **Do**\n>\n> - Label is concise and clear.\n\n```jsx live\nconst App = () => (\n  <FormField.Root isRequired>\n    <FormField.Label>First name</FormField.Label>\n    <FormField.Input>\n      <TextInput width=\"9600\" placeholder=\"John\" />\n    </FormField.Input>\n    <FormField.InfoBox>\n      Info box content.\n    </FormField.InfoBox>\n  </FormField.Root>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Navigation is higher hierarchy than icon button tools, this is not a common\n>   pattern.\n\n```jsx live\nconst App = () => (\n  <FormField.Root isRequired>\n    <FormField.Label>What do we call you?</FormField.Label>\n    <FormField.Input>\n      <TextInput width=\"9600\" placeholder=\"John or Johnny or Jon?\" />\n    </FormField.Input>\n    <FormField.InfoBox>\n      Info box content.\n    </FormField.InfoBox>\n  </FormField.Root>\n)\n```\n\n### Helper text and info button\n\nUse the right informative tool to aid your user to understand what is needed.\nHelp text should be short and is preferred when crucial information is needed.\nUse info button when supplemental information is too long for a help text,\ntooltips will by default open a dialog overlay, and can contain more detailed\ninformation, content types and formatting. See [dialog](#) for more guidelines\nconcerning the content inside the modal.\n\n> [!TIP]\\\n> **Do**\n>\n> - Maximum of 1-2 short sentences, around 20-30 words. Keep helper text below\n>   150 characters.\n> - If a long explanation is needed to explain anything related to this field,\n>   use the tooltip instead of the helper text.\n> - A good example of balanced information. Helper text is being used to inform\n>   all users without interaction. The info button contains supplementary\n>   information.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <FormField.Root isRequired>\n      <FormField.Label>Product discount rank</FormField.Label>\n      <FormField.Input>\n        <TextInput  width=\"9600\" />\n      </FormField.Input>\n      <FormField.Description>\n        Sort order values can only be a value between 1 and 2,147,483,647.\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not overload help text and do not use bullet points. Keep help text below\n>   150 characters.\n> - If information is important for users, use the help text to show to users\n>   without interaction.\n> - Do not duplicate information in the help text and inside the info button.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <FormField.Root isRequired>\n      <FormField.Label>Product discount rank</FormField.Label>\n      <FormField.Input>\n        <TextInput  width=\"9600\" />\n      </FormField.Input>\n      <FormField.Description>\n        Only one Product discount can be applied per product. The Sort order\n        determines which Product discount applies to your product. Discounts\n        with a Sort order value closer to 1 are considered first. Sort order\n        values can only be a value between 0 and 1.\n        <br/><br/>\n        <Text fontWeight=\"700\">For example:</Text>\n        <br/>\n        <Text>• Product discount 1 has a Sort order value: 0.05</Text>\n        <Text>• Product discount 2 has a Sort order value: 0.07</Text>\n        <Text>• Both Product discounts are active and apply to the same\n        product.</Text>\n        <Text>• Product discount 2 will apply and Product discount 1 will not\n        because 0.07 is closer to 1 than 0.05.</Text>\n\n      </FormField.Description>\n      <FormField.InfoBox>\n        Info box content.\n      </FormField.InfoBox>\n    </FormField.Root>\n  </Stack>\n)\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels",
+          "href": "#labels",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Helper text vs info icon",
+          "href": "#helper-text-vs-info-icon",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Formatting",
+          "href": "#formatting",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Validation",
+          "href": "#validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels",
+          "href": "#labels-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Helper text and info button",
+          "href": "#helper-text-and-info-button",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}