Skip to main content
skill CX Codex

layout-grid · daveebbelaar — Claude Code skill: SwiftUI grid and layout validation

layout-grid is a Claude Code skill that enforces grid and alignment rules in macOS SwiftUI apps. It runs when building custom UI components or after layout changes.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill layout-grid -a claude-code
Open on GitHub

What layout-grid does

The skill replaces guessed spacing with a strict scale and three checks that fail when UI elements drift. A linter catches off-grid raw numbers in code, a layout probe measures real frames from snapshot files, and a runtime grid overlay renders boundaries directly over the app window when launched with environment variables like APP_GRID=1.

Rules define spacing tokens from four to thirty-two points, shared leading edges, and container alignment patterns using .gridArea and .gridProbe modifiers. The workflow expects a macOS SwiftUI project structured with the template's helper scripts in tools/.

What it helps with

  • catch raw off-grid padding and spacing in code
  • measure real UI frames from snapshot JSON files
  • validate leading edge alignment across containers
  • render a visual grid overlay on top of the app window

Example prompts for the agent

  • Check the layout code for off-grid numbers using tools/grid-lint.sh.
  • Run layout checks on snapshot files using swift tools/check-layout.swift.
  • Launch the app with APP_GRID=1 to inspect the visual grid overlay.

How to install layout-grid

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill layout-grid -a claude-code

2Manually: put the files in place

~/.claude/skills/layout-grid/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/layout-grid/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about layout-grid

How to install layout-grid in Claude Code?

Run npx skills add daveebbelaar/bama --skill layout-grid -a claude-code followed by ~/.claude/skills/layout-grid/SKILL.md.

What does layout-grid do?

It checks alignment and grid consistency in macOS SwiftUI apps using a code linter, snapshot layout probes, and a visual grid overlay.

What is needed to run layout-grid?

You need macOS, a SwiftUI project, and the companion utility scripts located in the tools directory.

Source text

SKILL.md · MIT
---
name: layout-grid
description: Grid and alignment rules for a macOS SwiftUI app, with three checks that catch misalignment (a lint for off-grid numbers, a layout probe that measures real frames in snapshot mode, and a grid overlay). Use when building or reviewing a custom page, card, row, form, or sheet, after every build that touched layout, or when the user says something looks misaligned, crooked, cramped, or unevenly spaced.
---

# Layout grid

Agents guess numbers. A guessed `.padding(13)` looks almost right and
makes the whole app feel slightly off. This skill replaces guessing with
one scale and three checks that fail when something is off.

The template has everything in place: `Sources/<App>/UI/Grid.swift` and
`tools/`. For an app made before this skill, copy `UI/Grid.swift`,
`tools/grid-lint.sh`, and `tools/check-layout.swift` from the `new-mac-app`
skill's template, and the layout file line from its `Snapshot.swift`.

## The rules

1. Every padding, spacing, and size comes from `Space`: `xs 4`, `sm 8`,
   `md 12`, `lg 16`, `xl 20`, `xxl 24`, `section 32`. Raw numbers are
   0, 1, 2, or a multiple of 4.
2. Pages and windows have a 20 pt margin (`Space.margin`). Cards pad 16
   (`Space.lg`). Related controls sit 8 apart, groups 20 to 24, sections 32.
3. Each column has one leading edge. Titles, text, cards, and buttons in a
   column start on the same x. Indent on purpose, by a step of the scale.
4. Let containers do the aligning:
   - Labels with controls: `Form` with `.formStyle(.grouped)`, or
     `.columns` for the Mac layout of right-aligned labels.
   - Rows and columns of values: `Grid` and `GridRow`.
   - A label with a value: `LabeledContent`.
   - Text of different sizes in one row: `HStack(alignment: .firstTextBaseline)`.
   - Numbers in a column: `.monospacedDigit()`, trailing aligned.
   - An icon with text: `Label`.
5. Sheets are 360, 480, or 640 wide. Controls take their height from
   `.controlSize`, never from a fixed height.
6. Nested corners are concentric: inner radius = outer radius - padding.
7. `.offset` and `.position` move a view after layout, so nothing lines up
   with it. Use them only for motion and drag previews, with
   `// grid: ok <why>` on the line.
8. Long text truncates with its full value in a tooltip. Nothing clips.

## Check 1: lint the code

Run it after every build that touched views:

```bash
tools/grid-lint.sh
# Sources/Tasks/TaskRow.swift:14: off grid (10): .padding(.horizontal, 10)
# FAIL grid-lint: 1 lines off the grid
```

Fix each line with a `Space` token.

## Check 2: probe the real layout

Mark what you lay out yourself: the page, its sections, cards, rows in a
card, sheet content. System lists, forms, sidebars, and toolbars align
themselves and need no probes. Your own rows beside them do.

A check only sees what has probes. A screen with two probes passes while
everything else is off, so read the count in the PASS line.

```swift
VStack(alignment: .leading, spacing: Space.xxl) {
    Text("Today").gridProbe("title", area: "page")
    StatsRow().gridProbe("stats", area: "page")
    TaskCard()
        .gridArea("card", inset: Space.lg)
        .gridProbe("card", area: "page")
}
.padding(Space.margin)
.gridArea("page")
```

`.gridArea` marks a container and its inset. `.gridProbe` marks a view in
it. Probes with the same `edge` (default `"lead"`) must share one leading
edge. Pass `edge: nil` for views that sit side by side.

Snapshot mode writes a `<page>-<mode>-layout.json` next to every PNG.
Check them:

```bash
swift tools/check-layout.swift /tmp/<App>-shots/*-layout.json
# PASS today-light-layout.json: 12 probes in 2 areas
# FAIL inbox-light-layout.json
#   - edge page/lead has 2 leading edges: title 320, list 324
```

It checks that every probe:

1. Starts on a whole or half point, so its edges stay sharp.
2. Starts a multiple of 4 pt from its area's edge.
3. Stays inside its area's inset on both sides.
4. Shares one leading edge with the others on its edge.
5. Sits a multiple of 4 pt below the probe above it.
6. Never overlaps another probe in its area.

### Line up across areas

Rules 2 to 6 stay inside one area. Views in different areas, like text in a scroll
view and a chat box outside it, need an edge that starts with `=`:

```swift
TextColumn().gridProbe("column", area: "", edge: "=reading")
Composer().gridProbe("composer", area: "", edge: "=reading")
```

| Edge | Must match |
| --- | --- |
| `=name` | left and right |
| `=name<` | left |
| `=name>` | right |
| `=name\|` | center |
| `=name_` | bottom |

These probes skip rules 2 to 6, so a view off the 4 pt grid can still match a
system edge. To check one view against two groups, add a second `.gridProbe` with
a different name, because a probe with the same name replaces the first.

Run the snapshots once with scroll bars on, because a scroll bar that takes width
moves centered content (`mac-design`, app-shell.md):

```bash
tools/snap.sh -AppleShowScrollBars Always
```

The probes keep one frame per name across all windows. When a second window shows
the same views, its layout file mixes both windows, so check that window by its PNG.

## Check 3: look at the grid

When a check fails and the cause is not clear, draw the grid over the
window:

```bash
APP_GRID=1 APP_STORE=/tmp/<App>-test.store APP_SNAPSHOT=/tmp/<App>-grid \
  ~/Applications/<App>.app/Contents/MacOS/<App>
```

The PNGs show an 8 pt grid, each area in blue with its inset dashed, and
each probe in pink with its name. Open them with the Read tool.

## Fix a failure

| Message | Usual cause | Fix |
| --- | --- | --- |
| starts 23 pt into page | a raw padding on one child | remove it, use the stack's `Space` padding |
| 2 leading edges | a centered stack, or one child with extra padding | `alignment: .leading` on the stack |
| gap 10 pt | `spacing: 10`, or a `Spacer(minLength:)` | a `Space` token |
| inside its 20 pt inset | a missing margin, or a fixed width wider than the parent | `.padding(Space.margin)`, `maxWidth` instead of `width` |
| overlap | `.offset`, `.position`, or a fixed height | remove it, let the stack size the view |
| x between pixels | a fractional number | a whole number from `Space` |
| `=name` has different left edges | a scroll bar that takes width, or a panel's gap on the content's side | `mac-design`, app-shell.md, "Line up the content" |

Done when `tools/grid-lint.sh` passes, `tools/check-layout.swift` passes
on the layout files of every page you touched, and every custom page and
card has a `.gridArea` with probes on its main parts.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Frontend and UI →

layout-grid by other authors comes first.

layout-grid Owl-Listener The layout-grid skill defines a responsive page grid: columns, gutters, margins and breakpoint behaviour. Handy when you are setting up page structure from scratch. CX Codex +1 2,900installs image-first-grid-layout MengTo image-first-grid-layout directs coding agents to build layout grids around full-bleed photography with subtle guide rails and low-contrast overlays. Great for cinematic landing pages. CX Codex +1 1,800installs framed-grid-layout MengTo framed-grid-layout — a skill that spells out how to build pages with thin visible section borders, L-shaped corner brackets and strict grid alignment. CX Codex +1 1,800installs framer-motion-layout C-Jeril framer-motion-layout provides layout animation patterns for Framer Motion, covering shared element transitions with layoutId, reorderable lists, and exit sequences via AnimatePresence. CX Codex +1 876installs iphone-duo-adaptive-layout mirzaaghazadeh iphone-duo-adaptive-layout is a Claude Code skill that teaches agents to build layouts around the iPhone Duo fold with reserved regions, displacement, split, and overlay containers for avoiding the hinge and camera. CX Codex +1 1,000installs hig-components-layout raintree-technology hig-components-layout guides app navigation and layout architecture across Apple platforms based on the Human Interface Guidelines. CX Codex +1 830installs makepad-2.0-layout ZhangHanDong The makepad-2.0-layout skill guides an agent through sizing widgets and arranging children in Makepad 2.0. Use it when building a screen or tracing an invisible container. CX Codex +1 ★ 754repo stars

From the same set21

The whole set →
improve-architecture The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area. CX Codex +1 1,000installs app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs user-stories Turns app briefs, research, or screen indexes into prioritized user stories with checkable acceptance criteria. It runs after app-brief or clone, or when asked to plan features and choose what to build first. CX Codex +1 1,000installs swift-swiftui The swift-swiftui Claude Code skill sets Swift 6 and SwiftUI practices for macOS apps. It activates while writing, reviewing, or debugging Swift code, including concurrency and Sendable errors. CX Codex +1 1,000installs design-kit design-kit — a skill for Claude Code and Cursor builds a custom macOS SwiftUI design system with tokens and components. Runs when you need a brand look or custom controls. CX Codex +1 1,000installs design-system The design-system Claude Code skill organizes a macOS app’s accent color and design tokens. It activates for requests about themes, shared screen styles, or a style guide. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open