bama-swift-swiftui
Swift 6 and SwiftUI code rules for macOS apps, including concurrency, state, SwiftData, AppKit bridges, and fixes for common compiler errors. Use when writing, reviewing, or debugging Swift code in a Mac app, or on concurrency, Sendable, or "not in scope" errors.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- bama-swift-swiftui
- description
- Swift 6 and SwiftUI code rules for macOS apps, including concurrency, state, SwiftData, AppKit bridges, and fixes for common compiler errors. Use when writing, reviewing, or debugging Swift code in a Mac app, or on concurrency, Sendable, or "not in scope" errors.
02 资源文件 1
- 参考文档agents/openai.yaml101 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.
Swift and SwiftUI
The code is right when it compiles with zero warnings in Swift 6 language
mode and the app does what the story says. For how it should look, call the
Skill tool with bama-mac-design. For copyable view code, read
../../design/bama-mac-design/patterns.md.
Concurrency
The template sets main-actor default isolation: every type and function runs on the main actor unless you say otherwise. UI code needs no annotations.
| Work | Put it in |
|---|---|
| UI state, views, view models | Default (main actor) |
| CPU-heavy pure work (parsing, image work, diffing) | A nonisolated function marked @concurrent |
| Shared mutable state used off the main thread | An actor |
| A C callback (event tap, Carbon hotkey, CoreAudio listener) | A nonisolated static func that hops back with Task { @MainActor in ... } |
- Data that crosses actors is
Sendable: structs and enums ofSendablevalues, orfinal classwith onlyletproperties. MainActor.assumeIsolated { }inside a callback you know runs on the main thread (a main run loopTimer, a main queue notification).Task { }inherits the actor.Task.detachedonly when it must not.- Fix a concurrency error at its type, not with
@unchecked Sendableornonisolated(unsafe). Those two are a last resort, with a comment why. - Runtime trap the compiler misses. A closure created inside a
@MainActortype and passed to an API without a@Sendableclosure parameter (DispatchSource.setEventHandler,DispatchWorkItem,addPeriodicTimeObserver, CoreAudio listener blocks) inherits the main actor. When it runs on a background queue, Swift 6 crashes the app. Write it as{ @Sendable in ... }, and run every background path once after any concurrency change.
State
@Observableclasses for models.@Statein the view that owns one,@Bindableto bind to its properties,.environment(model)to share it.@ObservationIgnoredon caches, timers, and handles, so they never trigger a redraw.@Statefor view-local values.@AppStoragefor small preferences. Keychain for secrets.ForEach(items)over values, neverForEach($items)for data the user can delete: a row can read an index that no longer exists and crash. Get a binding by looking the item up by id.
SwiftData
@Modelclasses,.modelContaineron the scene,@Queryin views,@Environment(\.modelContext)to insert and delete.- Every new property has a default value, so existing stores still open.
- Store at
~/Library/Application Support/<AppName>/. Allow an override (APP_STORE) so tests never touch the real data. - Give every model its own
uid: UUID.persistentModelIDchanges on the first save, so it breaks selection and lookups. - Undo: register the reverse of each action on the window's undo manager. SwiftData's automatic undo is not reliable. Code in ../../design/bama-mac-design/patterns.md (Undo with SwiftData).
- Need SQL, a CLI, or several processes on one file? Use SQLite with WAL through a small library target instead.
Menu commands
SwiftUI Commands do not observe @Observable models, so a title or a
.disabled(...) that reads the model goes stale. In testing, neither
@FocusedValue (from .focusedSceneValue) nor an @ObservedObject inside
the commands updated reliably: the menu stayed disabled with a row
selected. What works: mirror the selection into a small ObservableObject,
observe it in the App, and pass the values into the commands. The App's
body then rebuilds the menus when they change.
@MainActor final class MenuState: ObservableObject {
static let shared = MenuState()
@Published private(set) var selection: Set<UUID> = []
func update(_ s: Set<UUID>) { if selection != s { selection = s } }
}
// AppModel: var selection: Set<UUID> = [] { didSet { MenuState.shared.update(selection) } }
struct MyApp: App {
@ObservedObject private var menu = MenuState.shared
var body: some Scene {
Window("App", id: "main") { ContentView() }
.commands { AppCommands(model: model, selectedIDs: menu.selection) }
}
}
Disable items with .disabled(selectedIDs.isEmpty) and resolve the target
again when the item fires. Never ship items that stay enabled and do
nothing. Check the menu from outside the app (bama-test-mac-app skill, "Menu
check").
A menu shortcut also fires while a text field has focus. Never use Delete,
Command-Delete, arrows, or Return as menu shortcuts. Handle them on the
list with .onDeleteCommand and .onKeyPress.
Names Swift already uses
Never name a type Task, View, Color, Image, Text, Section,
Label, Menu, Group, or Settings. Task breaks every Task { }.
Use Todo, TaskItem, NoteSection.
AppKit bridges
SwiftUI covers windows, lists, and forms. AppKit is still the answer for:
- Floating panels that do not steal focus:
NSPanelwith.nonactivatingPanelhosting a SwiftUI view (NSHostingView, withsizingOptions = []for a fixed frame). - Text views with custom behavior:
NSViewRepresentablearoundNSTextView. - Status items with custom click handling:
NSStatusItem. - Key and mouse monitors:
NSEvent.addLocalMonitorForEvents. Remove the monitor when the view goes away.
For system hooks (hotkeys, Accessibility, screen capture), call the Skill
tool with bama-os-integrations.
Compiler errors
| Error | Fix |
|---|---|
cannot find 'X' in scope right after adding a file |
swift package clean --scratch-path ~/Library/Developer/<AppName>/build |
Main actor-isolated ... from a nonisolated context |
Make the caller main-actor, or await the call |
Sending 'x' risks causing data races |
Make the type Sendable, or keep it on one actor |
The compiler is unable to type-check this expression |
Split the view into smaller subviews or let constants |
ambiguous use of 'Task' |
A type in your code is named Task; rename it |
Fix the first error first. Later errors often come from it.
Swift 6 errors
Moving an existing Swift 5 app? Read ../../ship/bama-build-and-verify/existing-app.md first: expect several build rounds, then hunt the runtime trap above.
| Error | Fix |
|---|---|
Static let of a non-Sendable type (formatter, NSFont, CFString) |
@MainActor on the enclosing type, a computed var, or a commented nonisolated(unsafe) |
sending 'note' risks causing data races in a main-queue observer |
Copy the Sendable parts (an id, a pid) out of the notification before MainActor.assumeIsolated |
| Observer token captured before it is assigned | Keep the token in a small @MainActor class |
| "pattern that the region-based isolation checker does not understand" in a task group | Use an array of Task { @MainActor in ... } and await each one |
Vars changed from OperationQueue blocks under NSLock |
OSAllocatedUnfairLock(initialState:) |
@objc action on an NSMenuItem subclass |
@MainActor @objc func |
Done when the app builds with zero warnings in Swift 6 language mode and the story's acceptance checks pass.
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.