diff --git a/.claude/rules/fleet-frontend.md b/.claude/rules/fleet-frontend.md
index 19806e6e3e..4b85c25775 100644
--- a/.claude/rules/fleet-frontend.md
+++ b/.claude/rules/fleet-frontend.md
@@ -84,6 +84,7 @@ Use helpers from `frontend/utilities/strings/stringUtils.ts`:
 - Modifiers: `` className={`${baseClass}--modifier`} ``
 - Use `classnames()` for conditional classes
 - Style files use underscore prefix: `_styles.scss`
+- Prefer `gap` over `margin` for spacing between sibling elements when the parent is `display: flex`/`grid`. Use the layout mixins from `frontend/styles/var/mixins.scss`: `vertical-card-layout`, `vertical-form-layout`, `vertical-modal-layout`, `vertical-page-layout`, `vertical-page-tab-panel-layout`, `vertical-data-set-layout`
 
 ## Interfaces & Types
 - Interface files live in `frontend/interfaces/` with `I` prefix: `IHost`, `IUser`, `IPack`
diff --git a/frontend/docs/patterns.md b/frontend/docs/patterns.md
index c74dce88cc..fa0ef0c33c 100644
--- a/frontend/docs/patterns.md
+++ b/frontend/docs/patterns.md
@@ -512,6 +512,23 @@ const PageOrComponent = ({
 
 Below are a few need-to-knows about what's available in Fleet's CSS:
 
+### Spacing
+
+Prefer `gap` over `margin` for spacing between sibling elements when they share a flex or grid parent (otherwise `gap` has no effect). We have layout mixins in
+`frontend/styles/var/mixins.scss` for common flex column patterns:
+
+| Mixin | Gap | Use for |
+|---|---|---|
+| `vertical-page-layout` | 24px | Top-level page content |
+| `vertical-card-layout` | 24px | Settings cards, OS settings panels |
+| `vertical-form-layout` | 24px | Form field groups |
+| `vertical-modal-layout` | 24px | Modal body content |
+| `vertical-page-tab-panel-layout` | 24px | Tab panel content |
+| `vertical-data-set-layout` | 16px | Definition lists, key-value field sets |
+
+All use `flex-direction: column`; the 24px value is `$gap-page-component`. For arbitrary
+spacing without a semantic name, use `flex-column-16px-gap` or `flex-column-32px-gap`.
+
 ### Modals
 
 1) When creating a modal with a form inside, the action buttons (cancel, save, delete, etc.) should