daveebbelaar/bama

layout-grid

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).

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/daveebbelaar/bama --skill layout-grid

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

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.

  1. 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.

  1. 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.

  1. 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.
  1. Sheets are 360, 480, or 640 wide. Controls take their height from

.controlSize, never from a fixed height.

  1. Nested corners are concentric: inner radius = outer radius - padding.
  2. .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.

  1. 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")
EdgeMust match
=nameleft 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

MessageUsual causeFix
starts 23 pt into pagea raw padding on one childremove it, use the stack's Space padding
2 leading edgesa centered stack, or one child with extra paddingalignment: .leading on the stack
gap 10 ptspacing: 10, or a Spacer(minLength:)a Space token
inside its 20 pt inseta missing margin, or a fixed width wider than the parent.padding(Space.margin), maxWidth instead of width
overlap.offset, .position, or a fixed heightremove it, let the stack size the view
x between pixelsa fractional numbera whole number from Space
=name has different left edgesa scroll bar that takes width, or a panel's gap on the content's sidemac-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.

del mismo repositorio

Más Skills

Todos los Skills
daveebbelaar
Comunidad

mac-design

Design rules that make a SwiftUI app look and feel like a native Mac app on macOS 26 and later, from Apple's eight design principles to Liquid Glass, layout, toolbars, menus, search, keyboard, type, color, and dark mode. Use when building or reviewing any window, sidebar, toolbar, menu, panel, or settings screen, or when the user asks for a more native, Apple-like, or better designed app.

Instalaciones / 1h
1
GitHub Stars
1,9 mil
Actualizado
5 nov
daveebbelaar
Comunidad

os-integrations

Deep macOS integrations for a native app, such as global hotkeys, menu bar items, floating panels, window control with Accessibility, screen capture and recording, clipboard, Shortcuts and Spotlight, URL schemes, login items, a CLI, and the permissions each one needs. Use when an app must reach outside its own window or control other apps.

Instalaciones / 1h
1
GitHub Stars
1,9 mil
Actualizado
5 nov
daveebbelaar
Comunidad

agent-cli

Optional command line and MCP server for a macOS app, so Claude Code, Codex, and scripts can drive it (list, add, change, search, act) through the running app. Use when the user wants agents to work with their app or its data, asks for a CLI, an MCP server, or automation for the app, or says "Claude should be able to use my app".

Instalaciones / 1h
4
GitHub Stars
1,9 mil
Actualizado
5 nov
daveebbelaar
Comunidad

app-brief

One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.

Instalaciones / 1h
4
GitHub Stars
1,9 mil
Actualizado
5 nov