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). 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.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- bama-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.
02 资源文件 1
- 参考文档agents/openai.yaml124 B
03 SKILL.md 正文
<!-- Version-Timestamp: 2026-10-27 07:36:32 AST -->
Adapted execution contract
This is the pinned, MIT-attributed BAMA capability adapted for the owned design kit. Read ADAPTATION.md at the BAMA package root before executing helpers. Project instructions, approved DESIGN.md and canonical tokens take precedence. Use supported Codex or Claude Code tools. Resolve this skill's sibling files relative to its installed SKILL.md; skill_dir is a task-local shell variable that you set to that resolved directory before running the examples in either host. Invoke a named bama-* skill through the host's supported skill mechanism.
Stage local builds by default. Installation, signing identity selection, launch, CLI linking, MCP registration, system setting changes and capture access are separate explicit operations. Existing task authorization applies; ask only for an action not already authorized. Stage or commit only when the current task or repository workflow authorizes it. Stage explicit paths and include required attribution. The helpers do not commit. Preserve the feature, story and testing workflow below using the hardened helpers. Legacy installed-app paths in examples must be replaced by the staged binary returned by build.sh.
Before a new scaffold exists, keep planning evidence under the selected <AppName>-planning/docs/ sibling or an existing approved planning folder. Treat docs paths below as relative to that planning folder until the fresh app is scaffolded, then copy the planning docs explicitly without replacing existing files. For an existing app, keep its current project layout.
The upstream acceptance statements describe checks to perform, never completed results. Screenshots, runtime behavior, permissions and cross-host acceptance require actual evidence. Use synthetic data and owned temporary test roots. Do not run a hosted session over real app data without project authorization.
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 bama-new-mac-app
skill's template, and the layout file line from its Snapshot.swift.
The rules
- 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. - 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. - 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.
- Let containers do the aligning:
- Labels with controls:
Formwith.formStyle(.grouped), or.columnsfor the Mac layout of right-aligned labels. - Rows and columns of values:
GridandGridRow. - 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.
- Labels with controls:
- Sheets are 360, 480, or 640 wide. Controls take their height from
.controlSize, never from a fixed height. - Nested corners are concentric: inner radius = outer radius - padding.
.offsetand.positionmove 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.- 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:
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.
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:
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:
- Starts on a whole or half point, so its edges stay sharp.
- Starts a multiple of 4 pt from its area's edge.
- Stays inside its area's inset on both sides.
- Shares one leading edge with the others on its edge.
- Sits a multiple of 4 pt below the probe above it.
- Never overlaps another probe in its area.
Check 3: look at the grid
When a check fails and the cause is not clear, draw the grid over the window:
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 |
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.
04 同仓库更多 Skills
web-design
Load before planning, designing, auditing or launching any website, landing page, cinematic hero, microsite or above-the-fold layout, or a prompt for Lovable, Bolt or v0 to build one, including regulated (prescription drug, health, finance), multilingual or market-specific launches. Covers page types (home, product, pricing, about, blog), conversion and ethical persuasion, responsive and fluid layouts, Core Web Vitals, SEO and structured data, localization and language-law requirements, stack and CMS choice (Astro, Next.js, WordPress, Webflow, Framer) and launch QA.
ux-design
Load before designing or reviewing any flow, form, onboarding, navigation or content for real users, especially low-literacy, older, neurodivergent, child or other specific audiences. Covers research and usability tests, heuristic reviews, personas and jobs to be done, journeys and service blueprints, information architecture, UX laws, SUS, SEQ and HEART metrics, plain language and reading level, and microcopy and error messages.
ui-design
Load before designing or specifying any interface screen or component, even a quick one: forms, tables, navigation, dashboards, onboarding, auth and passkeys, pricing, checkout, search and filters, settings, empty, loading and error states, notifications, consent and age-appropriate flows, and AI chat and agent interfaces, all to WCAG 2.2 AA. Also picks React UI libraries (toasts, drawers, command menus). Gives component specs, state matrices, sizes, density and keyboard and accessibility behavior.
typography
Choose, pair, size and set type for brand, web, app, print, slides, signage and motion: modular scales, fluid clamp() type, measure, leading, tracking, OpenType features, font licensing and web font loading, and multiscript setting for CJK, Arabic, Hebrew, Devanagari and Thai. Use when selecting or pairing fonts, building a type scale or type tokens, fixing weak hierarchy or bad line breaks, setting long-form text or numbers, loading web fonts, or localizing type for another market.
reference-reconstruction
Reconstructs the observed interface and behavior of a supplied app, site or screenshot set using a screen index, measurements, state and command maps, reusable components and matched-condition comparisons. Use when asked to reverse engineer, clone, reproduce or match a reference product, then adapt it if requested.
print-packaging-social
Load before any print, packaging, label, barcode, social, out-of-home, slide-deck or email design question, even a quick one, and before making finished collateral files. Specs: bleed, safe zones, 300ppi, CMYK, PDF/X preflight, dielines, barcodes, social formats with 9:16 safe areas, billboard letter heights, 16:9 decks, bulletproof email. Renders token-driven brand books, sell sheets, cards, carousels and decks to PDF and PNG with a Canva editable twin.