@aircall/ds 0.14.0 → 0.15.0

package/skills/aircall-ds/migrate-tractor/dropzone/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: aircall-ds/migrate-tractor/dropzone
+description: >
+  Migrate react-dropzone (useDropzone, DragAndDrop, ConversationDragAndDrop)
+  and project wrappers (Dropzone, DropzoneV2) to @aircall/ds Dropzone. Load
+  when a file imports from react-dropzone or uses DragAndDrop from @aircall/tractor.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/dropzone.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor.
+
+## 1. Component mapping
+
+| Tractor / react-dropzone | @aircall/ds |
+| --- | --- |
+| `useDropzone()` hook | `<Dropzone>` (no hook needed) |
+| `<DragAndDrop>` / `<ConversationDragAndDrop>` | `<Dropzone>` |
+| Project wrapper `<Dropzone dropzoneOptions={…}>` | `<Dropzone>` (flatten options to direct props) |
+| `onDrop` / `onDropAccepted` / `onAddFiles` | `onFiles: (files: File[]) => void` |
+| `onDropRejected` | `onError: (rejections: FileRejection[]) => void` |
+| `acceptMessage` | `hoverMessage` |
+| `rejectMessage` | `dragRejectMessage` |
+| `accept: Record<string, string[]>` / `acceptedMimeTypes` | `accept: string` (comma-separated HTML `<input accept>` form) |
+| `multiple`, `disabled`, `maxFiles`, `maxSize`, `minSize` | same props, same semantics |
+| `noClick` / `noKeyboard` / `noDrag` | omit `<DropzoneContent>` (headless mode = no click/keyboard) |
+| `getRootProps()` / `getInputProps()` / `open()` | `<DropzoneTrigger>` |
+| `text` / `subtext` (project wrapper) | `<DropzoneTitle>` / `<DropzoneDescription>` |
+| `errorText` / `customError` (project wrapper) | consumer state + `<FieldError>` inside `<Field data-invalid>` |
+| `variant="primary" \| "secondary"` (project wrapper) | removed — apply via `className` if needed |
+| `validator` | inline guard in `onFiles` + `dragRejectMessage` |
+
+### accept map helper
+
+When old code passes `accept` as a `Record<string, string[]>`, convert to a string:
+
+```ts
+function flattenAcceptMap(map: Record<string, string[]>): string {
+  return [...Object.keys(map), ...Object.values(map).flat()].join(',');
+}
+```
+
+### FileRejection shape (unchanged from react-dropzone)
+
+```ts
+import { type FileRejection, type FileError, type DropzoneErrorCode } from '@aircall/ds';
+
+// FileRejection: { file: File; errors: FileError[] }
+// FileError:     { code: DropzoneErrorCode; message: string }
+// DropzoneErrorCode: 'too-many-files' | 'file-too-large' | 'file-too-small' | 'file-invalid-type'
+```
+
+## 2. Imports
+
+```tsx
+import {
+  Dropzone,
+  DropzoneContent,
+  DropzoneIcon,
+  DropzoneTitle,
+  DropzoneDescription,
+  DropzoneActions,
+  DropzoneTrigger,
+  Field,
+  FieldError,
+  Button,
+  type FileRejection,
+  type FileError,
+  type DropzoneErrorCode,
+} from '@aircall/ds';
+```
+
+## 3. Pattern picker
+
+| Pattern | Use `<DropzoneContent>`? | Use when |
+| --- | --- | --- |
+| **Headless** | No | Drop area wraps existing UI; overlay appears on drag only. Old code used `noClick`, `noDrag`, or wrapped arbitrary children. |
+| **Headless with trigger** | No | Headless drop area + an explicit button to open the picker (`useDropzone({ noClick: true })` + separate `open()` call). |
+| **Card** | Yes | Standard dashed-border file-picker box with icon, title, description, and click-anywhere-to-open. |
+
+## 4. Before / After
+
+### Pattern 1 — Headless wrapping app content
+
+Replaces `<DragAndDrop>` / `<ConversationDragAndDrop>` with child content.
+
+```tsx
+// Before
+import { DragAndDrop } from '@aircall/tractor';
+
+const validator = useCallback(
+  () => [{ message: rejectMessage, code: ErrorCode.FileInvalidType }],
+  [rejectMessage]
+);
+
+<DragAndDrop
+  validator={cannotAttach ? validator : undefined}
+  multiple
+  acceptedMimeTypes={acceptedMimeTypes}
+  acceptMessage={t('FilePicker.DragAndDrop.AcceptMessage')}
+  rejectMessage={rejectMessage}
+  onAddFiles={handleOnAddFiles}
+>
+  {children}
+</DragAndDrop>
+
+// After
+import { Dropzone } from '@aircall/ds';
+
+<Dropzone
+  multiple
+  accept={flattenAcceptMap(acceptedMimeTypes)}
+  onFiles={cannotAttach ? undefined : handleOnAddFiles}
+  onError={rejections => showErrorToast(rejections[0]?.errors[0]?.message ?? '')}
+  hoverMessage={t('FilePicker.DragAndDrop.AcceptMessage')}
+  dragRejectMessage={cannotAttach ? rejectMessage : t('FilePicker.DragAndDrop.UnsupportedType')}
+>
+  {children}
+</Dropzone>
+```
+
+The `validator` collapses: gate acceptance in `onFiles` (pass `undefined` when disabled) and surface the rejection message via `dragRejectMessage`.
+
+### Pattern 2 — Headless with explicit trigger button
+
+Replaces a parallel `useDropzone({ noClick: true })` + `<DragAndDrop>` combo.
+
+```tsx
+// Before
+import { useDropzone } from 'react-dropzone';
+import { DragAndDrop } from '@aircall/tractor';
+import { Button } from '@aircall/ds';
+import { ImportOutlined } from '@aircall/react-icons';
+
+const { open, getInputProps } = useDropzone({
+  accept: POWERDIALER_ACCEPTED_MIME_TYPES,
+  multiple: false,
+  noClick: true,
+  noKeyboard: true,
+  onDropRejected,
+  onDropAccepted,
+});
+
+<DragAndDrop
+  maxFiles={1}
+  acceptMessage={t('DragAndDropAcceptMessage')}
+  rejectMessage={t('DragAndDropRejectMessage')}
+  onAddFiles={files => files.length && onAddFile(files[0])}
+  acceptedMimeTypes={POWERDIALER_ACCEPTED_MIME_TYPES}
+  onDropRejected={onDropRejected}
+>
+  <Button onClick={open}><ImportOutlined />{t('UploadAFile')}</Button>
+  <input {...getInputProps()} hidden />
+</DragAndDrop>
+
+// After
+import { Dropzone, DropzoneTrigger, Button } from '@aircall/ds';
+import { Import } from '@aircall/react-icons';
+
+<Dropzone
+  accept="text/csv,application/vnd.ms-excel,.csv"
+  multiple={false}
+  maxFiles={1}
+  onFiles={([file]) => file && onAddFile(file)}
+  onError={rejections => {
+    if (rejections[0]?.errors[0]?.code === 'file-invalid-type') {
+      showErrorToast(t('Notifications.FailedFormatError'));
+    }
+  }}
+  hoverMessage={t('DragAndDropAcceptMessage')}
+  dragRejectMessage={t('DragAndDropRejectMessage')}
+>
+  <DropzoneTrigger render={<Button />}>
+    <Import />{t('UploadAFile')}
+  </DropzoneTrigger>
+</Dropzone>
+```
+
+The hidden `<input>` and `getInputProps()` spread are gone — `<Dropzone>` manages the file input internally. `<DropzoneTrigger>` calls `open()` on click via context.
+
+### Pattern 3 — Card with click-to-open
+
+Replaces a project wrapper `<Dropzone dropzoneOptions={…}>` with typography children.
+
+```tsx
+// Before
+import { Dropzone } from '@aircall/tractor';
+
+<Dropzone
+  dropzoneOptions={{
+    onDrop: handleDrop,
+    onDropRejected: handleError,
+    maxFiles: 1,
+    accept: { 'audio/mpeg': ['.mp3'] },
+    maxSize: MAX_AUDIO_SIZE,
+  }}
+  errorText={capitalize(t('dropzone.secondary_text'))}
+  variant="primary"
+>
+  <Typography variant="bodySemiboldM">{t('primary_text')}</Typography>
+  <Typography variant="bodyMediumS">{t('secondary_text')}</Typography>
+</Dropzone>
+
+// After
+import { useState } from 'react';
+import {
+  Dropzone,
+  DropzoneContent,
+  DropzoneTitle,
+  DropzoneDescription,
+  DropzoneActions,
+  DropzoneTrigger,
+  Field,
+  FieldError,
+  Button,
+} from '@aircall/ds';
+
+const [error, setError] = useState<string | null>(null);
+
+<Field data-invalid={!!error}>
+  <Dropzone
+    accept="audio/mpeg,.mp3"
+    maxFiles={1}
+    maxSize={MAX_AUDIO_SIZE}
+    onFiles={([file]) => { setError(null); handleDrop([file]); }}
+    onError={() => setError(capitalize(t('dropzone.secondary_text')))}
+  >
+    <DropzoneContent error={!!error}>
+      <DropzoneTitle>{t('primary_text')}</DropzoneTitle>
+      <DropzoneDescription>{t('secondary_text')}</DropzoneDescription>
+      <DropzoneActions>
+        <DropzoneTrigger render={<Button size="sm" />}>Upload file</DropzoneTrigger>
+      </DropzoneActions>
+    </DropzoneContent>
+  </Dropzone>
+  {error && <FieldError>{error}</FieldError>}
+</Field>
+```
+
+`errorText` / `customError` collapse into consumer state + `<FieldError>`. Pass `error={!!error}` to `<DropzoneContent>` for the destructive red border. `variant` is dropped — use `className` if a custom border color is needed.
+
+## 5. Common mistakes
+
+### Mistake 1 — Using `onDrop` / `onDropAccepted` instead of `onFiles`
+
+```tsx
+// ❌ Wrong — react-dropzone callback names; DS ignores them silently
+<Dropzone onDrop={handleDrop} onDropAccepted={handleAccepted}>…</Dropzone>
+
+// ✅ Correct — DS fires accepted files via onFiles
+<Dropzone onFiles={handleDrop}>…</Dropzone>
+```
+
+`<Dropzone>` does not forward unknown props to react-dropzone — it is a standalone implementation. `onDrop` / `onDropAccepted` are silently swallowed as generic DOM props and never called.
+
+Source: `packages/ds/src/components/dropzone.tsx`
+
+### Mistake 2 — Passing `accept` as an object instead of a string
+
+```tsx
+// ❌ Wrong — react-dropzone Record shape; DS <input accept> expects a string
+<Dropzone accept={{ 'audio/mpeg': ['.mp3'], 'audio/wav': ['.wav'] }}>…</Dropzone>
+
+// ✅ Correct — comma-separated MIME types and/or extensions
+<Dropzone accept="audio/mpeg,.mp3,audio/wav,.wav">…</Dropzone>
+```
+
+DS passes `accept` directly to the hidden `<input type="file" accept={…}>`. A plain object is coerced to `"[object Object]"` and the file picker accepts nothing.
+
+Source: `packages/ds/src/components/dropzone.tsx`
+
+### Mistake 3 — Adding `<DropzoneContent>` when headless behavior is wanted
+
+```tsx
+// ❌ Wrong — DropzoneContent makes the entire area clickable and keyboard-focusable
+<Dropzone onFiles={handleFiles}>
+  <DropzoneContent>
+    {children}
+  </DropzoneContent>
+</Dropzone>
+
+// ✅ Correct — omit DropzoneContent; Dropzone alone is headless (drag-only)
+<Dropzone onFiles={handleFiles}>
+  {children}
+</Dropzone>
+```
+
+`<DropzoneContent>` renders a `role="button"` div that opens the picker on click and Space/Enter. Old code that ran with `noClick: true` should not include it — the drag overlay still appears via the parent `<Dropzone>`.
+
+Source: `packages/ds/src/components/dropzone.tsx`
+
+### Mistake 4 — Using `asChild` on `<DropzoneTrigger>` instead of the `render` prop
+
+```tsx
+// ❌ Wrong — asChild is a Radix convention; DS uses Base UI's render prop
+<DropzoneTrigger asChild>
+  <Button>Upload</Button>
+</DropzoneTrigger>
+
+// ✅ Correct — pass the element to render via the render prop
+<DropzoneTrigger render={<Button />}>Upload</DropzoneTrigger>
+```
+
+`<DropzoneTrigger>` follows the Base UI `render` prop convention, not Radix `asChild`. The label goes as children of `<DropzoneTrigger>`, not inside the `render` element. Passing `asChild` is ignored and the trigger falls back to a plain `<button>`.
+
+Source: `packages/ds/src/components/dropzone.tsx`
+
+### Mistake 5 — Placing error UI inside `<DropzoneContent>` instead of `<FieldError>`
+
+```tsx
+// ❌ Wrong — DS has no built-in error banner inside DropzoneContent
+<Dropzone onError={e => setError(e[0]?.errors[0]?.message)}>
+  <DropzoneContent>
+    <DropzoneTitle>Upload audio</DropzoneTitle>
+    {error && <p className="text-destructive">{error}</p>}
+  </DropzoneContent>
+</Dropzone>
+
+// ✅ Correct — wrap in Field + FieldError; pass error prop to DropzoneContent
+<Field data-invalid={!!error}>
+  <Dropzone onError={() => setError(t('upload.error'))}>
+    <DropzoneContent error={!!error}>
+      <DropzoneTitle>Upload audio</DropzoneTitle>
+    </DropzoneContent>
+  </Dropzone>
+  {error && <FieldError>{error}</FieldError>}
+</Field>
+```
+
+`<DropzoneContent error>` only toggles the destructive border — it does not render an error message. The accessible error text belongs in `<FieldError>` outside the dropzone, associated via `<Field data-invalid>`.
+
+Source: `packages/ds/src/components/dropzone.tsx`

package/skills/aircall-ds/migrate-tractor/form-and-field/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: aircall-ds/migrate-tractor/form-and-field
+description: >
+  Migrate Tractor Form and FormItem to native <form> + @aircall/ds Field compound.
+  Load when a file imports Form, FormItem, or FormRow from @aircall/tractor. Covers
+  label/control/error layout, validation state, fieldsets, and help text.
+type: sub-skill
+library: aircall-ds
+library_version: "0.13.0"
+requires:
+  - aircall-ds/setup
+  - aircall-ds/migrate-tractor
+sources:
+  - "aircall/hydra:docs/migration-guides/tractor-to-ds/recipes/form-and-field.md"
+---
+
+This skill builds on aircall-ds/migrate-tractor. Apply all cross-cutting rules from that skill (prop renames, `render` prop, data attributes) before the form-specific steps below.
+
+> **Principle — for a form that collects + submits data, drive it with `@aircall/blocks` `useForm` + the `Form*Field` wrappers, not local `useState`.** The ds `Field`/`FieldLabel`/`FieldError` primitives below are the field *shell* those wrappers render — reach for them bare only for non-form display. See `@aircall/blocks#aircall-blocks/migrate-dashboard/form-wizard`.
+
+## 1. Component mapping
+
+DS has no `Form` component. Use a native `<form>` element and wrap each field row in `<Field>`.
+
+| Tractor | @aircall/ds | Notes |
+| --- | --- | --- |
+| `<Form>` | `<form>` | Native HTML element — no DS wrapper |
+| `<FormItem label="…">` | `<Field>` + `<FieldLabel>` + control | Layout and label are now separate |
+| `<FormItem validationStatus="error">` | `aria-invalid` on the control | No Tractor-style prop; use standard ARIA |
+| `<FormItem hint="…">` | `<FieldDescription>` | Renders muted below the control |
+| `<FormItem error="…">` | `<FieldError>` | Renders in `text-destructive`; conditionally mount it |
+| — | `<FieldGroup>` | Stacks multiple `<Field>` rows with consistent spacing |
+| — | `<FieldSet>` + `<FieldLegend>` | Wraps a group of related fields in a semantic `<fieldset>` |
+| — | `<FieldContent>` | Groups the control + description + error in a column (used with `orientation="horizontal"`) |
+
+## 2. Imports
+
+```tsx
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  FieldLegend,
+  FieldSet,
+  Button,
+  Input
+} from '@aircall/ds';
+```
+
+## 3. Before / After examples
+
+### 3a. Single field with validation
+
+**Before (Tractor):**
+```tsx
+import { FormItem, Input } from '@aircall/tractor';
+
+<form onSubmit={onSubmit}>
+  <FormItem
+    label="Email"
+    validationStatus={emailError ? 'error' : undefined}
+    error={emailError}
+  >
+    <Input
+      type="email"
+      value={email}
+      onChange={e => setEmail(e.target.value)}
+    />
+  </FormItem>
+</form>
+```
+
+**After (DS):**
+```tsx
+import { Field, FieldLabel, FieldError, Input, Button } from '@aircall/ds';
+
+<form onSubmit={onSubmit}>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input
+      id="email"
+      type="email"
+      value={email}
+      onChange={e => setEmail(e.target.value)}
+      aria-invalid={!!emailError}
+    />
+    {emailError && <FieldError>{emailError}</FieldError>}
+  </Field>
+
+  <Button type="submit" size="lg">Submit</Button>
+</form>
+```
+
+Key changes:
+- `<FormItem label="…">` → explicit `<FieldLabel htmlFor>` paired with `id` on the control; you own the id/htmlFor pairing.
+- `validationStatus="error"` → removed; set `aria-invalid={true}` on the control instead.
+- `error={…}` → `<FieldError>` rendered conditionally as a child of `<Field>`.
+
+### 3b. Multiple rows with FieldGroup
+
+**Before (Tractor):**
+```tsx
+import { FormItem, Input } from '@aircall/tractor';
+
+<form>
+  <FormItem label="Name"><Input id="name" /></FormItem>
+  <FormItem label="Phone"><Input id="phone" type="tel" /></FormItem>
+</form>
+```
+
+**After (DS):**
+```tsx
+import { Field, FieldGroup, FieldLabel, Input } from '@aircall/ds';
+
+<form>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="name">Name</FieldLabel>
+      <Input id="name" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="phone">Phone</FieldLabel>
+      <Input id="phone" type="tel" />
+    </Field>
+  </FieldGroup>
+</form>
+```
+
+`FieldGroup` provides consistent vertical spacing between rows.
+
+### 3c. Horizontal layout (inline control + label)
+
+**After (DS):**
+```tsx
+import { Field, FieldLabel, Checkbox } from '@aircall/ds';
+
+<Field orientation="horizontal">
+  <Checkbox id="remember" checked={remember} onCheckedChange={setRemember} />
+  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
+</Field>
+```
+
+Use `orientation="horizontal"` for Checkbox + label and Switch + label pairs. The `Field` component also accepts `orientation="responsive"`, which stacks vertically at narrow widths and switches to horizontal at `@md` breakpoint inside a `FieldGroup`.
+
+### 3d. Grouped fields with fieldset / legend
+
+**After (DS):**
+```tsx
+import { FieldSet, FieldLegend, FieldGroup, Field, FieldLabel, Input } from '@aircall/ds';
+
+<FieldSet>
+  <FieldLegend>Contact preferences</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="sms">SMS number</FieldLabel>
+      <Input id="sms" type="tel" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="slack">Slack handle</FieldLabel>
+      <Input id="slack" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+`FieldLegend` renders a `<legend>` with `variant="legend"` (base text size) by default. Pass `variant="label"` for a smaller label-sized legend.
+
+### 3e. Field with help text (hint)
+
+**Before (Tractor):**
+```tsx
+import { FormItem, Input } from '@aircall/tractor';
+
+<FormItem label="Alias" hint="Shown to teammates in your call queue.">
+  <Input id="alias" />
+</FormItem>
+```
+
+**After (DS):**
+```tsx
+import { Field, FieldLabel, FieldDescription, Input } from '@aircall/ds';
+
+<Field>
+  <FieldLabel htmlFor="alias">Alias</FieldLabel>
+  <Input id="alias" />
+  <FieldDescription>Shown to teammates in your call queue.</FieldDescription>
+</Field>
+```
+
+### 3f. Multiple validation errors via FieldError `errors` prop
+
+`FieldError` accepts an `errors` array in addition to `children`. When multiple distinct messages are present it renders a `<ul>` automatically; duplicates are deduplicated.
+
+**After (DS):**
+```tsx
+import { Field, FieldLabel, FieldError, Input } from '@aircall/ds';
+
+<Field>
+  <FieldLabel htmlFor="pwd">Password</FieldLabel>
+  <Input id="pwd" type="password" aria-invalid={errors.length > 0} />
+  <FieldError errors={errors} />
+</Field>
+```
+
+Where `errors` is `Array<{ message?: string }>`. When the array is empty `FieldError` renders nothing.
+
+### 3g. Horizontal layout with FieldContent (label beside stacked controls)
+
+When the label sits beside a column of controls (e.g. control + description + error), wrap the right-hand column in `FieldContent`:
+
+**After (DS):**
+```tsx
+import { Field, FieldLabel, FieldContent, FieldDescription, FieldError, Input } from '@aircall/ds';
+
+<Field orientation="horizontal">
+  <FieldLabel htmlFor="alias">Alias</FieldLabel>
+  <FieldContent>
+    <Input id="alias" aria-invalid={!!aliasError} />
+    <FieldDescription>Shown to teammates in your call queue.</FieldDescription>
+    {aliasError && <FieldError>{aliasError}</FieldError>}
+  </FieldContent>
+</Field>
+```
+
+## 4. Common mistakes
+
+### Mistake 1 — Using `validationStatus` instead of `aria-invalid`
+
+```tsx
+// Wrong — Field and its children have no validationStatus prop; it is silently ignored
+<Field validationStatus="error">
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" />
+</Field>
+
+// Correct — set aria-invalid on the control; FieldError handles the error message
+<Field>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid={!!emailError} />
+  {emailError && <FieldError>{emailError}</FieldError>}
+</Field>
+```
+
+DS uses standard ARIA for validation state rather than a custom prop. `aria-invalid` on the control signals the error to assistive technology; `FieldError` renders with `role="alert"` and applies the destructive colour automatically.
+
+Source: `packages/ds/src/components/field.tsx` — `FieldError` sets `role="alert"` and `text-destructive`; `Field` has no `validationStatus` variant.
+
+---
+
+### Mistake 2 — Omitting `htmlFor` / `id` pairing
+
+```tsx
+// Wrong — FieldLabel without htmlFor is not associated with the control
+<Field>
+  <FieldLabel>Email</FieldLabel>
+  <Input type="email" />
+</Field>
+
+// Correct — always supply matching htmlFor on FieldLabel and id on the control
+<Field>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+</Field>
+```
+
+Tractor's `<FormItem label="…">` wired the label to its child input automatically. DS `FieldLabel` is a styled `<label>` — it does not auto-discover its sibling control. Without `htmlFor` + `id` the label click does not focus the input and screen readers cannot announce the association.
+
+Source: `packages/ds/src/components/field.tsx` — `FieldLabel` wraps `Label` (a plain `<label>`) with no auto-association logic.
+
+---
+
+### Mistake 3 — Wrapping multiple fields without FieldGroup
+
+```tsx
+// Wrong — adjacent Fields have no spacing contract between them
+<form>
+  <Field>
+    <FieldLabel htmlFor="first">First name</FieldLabel>
+    <Input id="first" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="last">Last name</FieldLabel>
+    <Input id="last" />
+  </Field>
+</form>
+
+// Correct — use FieldGroup to get consistent gap-6 spacing
+<form>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="first">First name</FieldLabel>
+      <Input id="first" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="last">Last name</FieldLabel>
+      <Input id="last" />
+    </Field>
+  </FieldGroup>
+</form>
+```
+
+`Field` applies no external margin. `FieldGroup` is the intentional spacing container — it uses `gap-6` between children and adjusts automatically for nested `FieldGroup` elements (`*:data-[slot=field-group]:gap-4`).
+
+Source: `packages/ds/src/components/field.tsx` — `FieldGroup` sets `flex flex-col gap-6`; `Field` sets no external gap.
+
+---
+
+### Mistake 4 — Conditionally rendering FieldError without checking the message
+
+```tsx
+// Wrong — FieldError always mounts, rendering an empty alert div
+<FieldError>{emailError}</FieldError>
+
+// Correct — either guard the mount or pass the errors array prop
+{emailError && <FieldError>{emailError}</FieldError>}
+// or
+<FieldError errors={[{ message: emailError }]} />
+```
+
+When `children` is falsy and `errors` is empty or undefined, `FieldError` returns `null` on its own when you use the `errors` prop. But when using `children`, you must guard the mount yourself — an undefined/empty string child still causes a `<div role="alert">` to be inserted into the DOM, which screen readers may announce unexpectedly.
+
+Source: `packages/ds/src/components/field.tsx` — `FieldError` only short-circuits to `null` via `useMemo` when `!children && !errors?.length`.