Form-spacing skill for AI coding agents: an 8 / 20 / 24 / 48px spacing system for UI forms, based on Zander Whitehurst's "Stop guessing your UI form spacing".

Don't eyeball form spacing. Use a fixed set of gaps, where proximity carries meaning: small gaps tie things together (a label to its input, a helper to its input), and larger gaps separate one group from the next. When every gap comes from the table below, the form reads correctly at a glance and looks the same in every theme.

Source: Zander Whitehurst (@zander_supafast, Memorisely), "Stop guessing your UI form spacing".

Every value is on a 4px grid. In rem (16px base): 0.25 / 0.5 / 1.25 / 1.5 / 2.5 / 3. Use the same numbers as pt/dp in SwiftUI and Flutter. Gaps are measured between element boxes, the way CSS gap works, not between visible glyphs. Container padding sits inside any card border.

Dark mode uses identical spacing. Only color tokens change between themes. Never put spacing inside theme overrides.

Scope: the table governs the space between form elements and the container padding. The insides of components are not covered. That includes input/button inner padding and height, the icon → text gap inside a button, and the line → text gap inside a divider. Keep the project's existing component styles for those.

Divide the form into groups first, then apply the table:

┌─ card: 48px top/bottom, 40px left/right ─┐
│  [Header]   title ─8─ caption            │
│      24                                  │
│  [Fields]   label ─8─ input ─4─ helper   │
│             ──20── next field            │
│      24                                  │
│  [Primary]  submit button                │
│      24                                  │
│  [Divider]  ── Or continue with ──       │
│      24                                  │
│  [Alt]      button ─8─ button            │
└──────────────────────────────────────────┘

Set each gap once, on the parent container (flex/ grid + gap), rather than scattering mt-*/ mb-* on individual elements. Stray margins are how forms drift out of the system. Inside a field, the label and helper are the only places where margins make sense.

<style>
  :root {
    --form-pad-y: 48px; --form-pad-x: 40px;
    --space-group: 24px;  /* content groups, last field → button, around divider */
    --space-field: 20px;  /* field → field */
    --space-tight: 8px;   /* title → caption, label → input, button → button */
    --space-helper: 4px;  /* input → helper/error */
  }
  .card   { padding: var(--form-pad-y) var(--form-pad-x); }
  .form   { display: flex; flex-direction: column; gap: var(--space-group); }
  .header, .alt-actions { display: flex; flex-direction: column; gap: var(--space-tight); }
  .header > * { margin: 0; } /* kill default h1/p margins or they add to the gap (Tailwind's preflight already does) */
  .fields { display: flex; flex-direction: column; gap: var(--space-field); }
  .field  { display: flex; flex-direction: column; }
  .field label { margin-bottom: var(--space-tight); }
  .field .help { margin: var(--space-helper) 0 0; }
</style>

<div class="card">
  <form class="form">
    <div class="header">
      <h1>Create your account</h1>
      <p>Get started with your free account today</p>
    </div>
    <div class="fields">
      <div class="field">
        <label for="name">Your name</label>
        <input id="name" />
      </div>
      <div class="field">
        <label for="email">Work email</label>
        <input id="email" type="email" aria-describedby="email-help" />
        <p class="help" id="email-help">Use your work email to collaborate with colleagues</p>
      </div>
    </div>
    <button type="submit">Continue</button>
    <div class="divider">Or continue with</div>
    <div class="alt-actions">
      <button type="button">Continue with Google</button>
      <button type="button">Continue with Microsoft</button>
    </div>
  </form>
</div>

In Tailwind, the same structure is: card px-10 py-12, form flex flex-col gap-6, header flex flex-col gap-2, fields flex flex-col gap-5, field flex flex-col, label mb-2, helper mt-1, and alt actions flex flex-col gap-2.

The header doesn't have to be inside <form>. If it sits outside, wrap the header and the form in a flex flex-col gap-6 div. Nested gap containers don't add up, because gap only applies between siblings.

These are extensions consistent with the system. Don't invent new gap values for them.

• Side-by-side fields (city | postcode): use 20px between columns, the same as field → field. Top-align them (items-start ). The next field sits 20px below the taller column.
• Several sections (shipping, then payment): each section is a content group with its own header (title 8 caption, then 24 to its fields). Keep 24px between sections, and separate them with a divider that has 24px on each side. A page title above all the sections is just another header group, 24px above the first section.
• Checkbox and radio rows: the control → its label is 8px across, and a description under the label takes the helper slot (4px). If the rows have descriptions, they are fields, 20px apart. If they are bare options in one list, they are a cluster, 8px apart like stacked buttons.
• Secondary action under the primary button ("Back to cart", "Cancel"): it joins the primary's action group at 8px button → button. That whole group sits 24px below the last field.
• Validation errors take the helper slot at 4px under the input. They don't change any other gap.
• Narrow screens (under 640px): the internal gaps stay exactly the same. Horizontal container padding drops to 24px (px-6 sm:px-10 ) and vertical stays at 48px.
• Space around the card: keep the card off the screen edge with a page gutter of at least 16px on every side (p-4 ). On phones you can instead let the card fill the screen, with its container padding as the gutter.
• Card width: if 40px padding squeezes the inputs, widen the card (for examplemax-w-sm →max-w-md ) rather than cutting the padding.

List every relationship from the table and measure what the code actually produces. Remember that margin s, gap, and default h1/ p margins add up. Report each one as current → target, then fix them by restructuring into groups with gap, not by tweaking individual margins.

If you can render the page (DevTools, Playwright, or a browser tool), evaluate scripts/measure-gaps.js in it. It prints the container padding and every vertical gap in order, so you can check them against the table instead of estimating. Run it in dark mode too, and the numbers should be identical.