swift-apps

Swift 应用

使用以 SwiftUI 为先的模式、清晰的状态所有权、忠实还原平台特性、无障碍设计和严格的性能规范，打造原生体验出色的 Apple 平台软件。 默认采用直接、易读的代码，并使用 Apple 框架，而不是在 SwiftUI 上叠加 Web 风格的抽象。

选择方向

• 新功能或界面：编写代码前，先确定目标平台、应用类型、主要操作、核心状态、导航模型和数据所有权。然后加载 references/architecture-and-state.md 和 references/ui-patterns.md。
• 重构或清理：保留现有行为、简化结构、减少间接层，并明确状态所有权。然后加载 references/architecture-and-state.md。
• 修复 Bug：先复现问题；如果项目有可用的测试框架，则先编写会失败的测试。修改代码前，列出 2-3 个假设。然后加载 references/performance-and-debugging.md 和任何适用的领域参考文档。
• 性能问题或卡顿：先从代码入手；如果审查后仍无法确定，再开始性能分析。加载 references/performance-and-debugging.md。
• Liquid Glass 或新的设计系统 API：使用原生材质并进行可用性检查，不要仿制自定义模糊效果。加载 references/liquid-glass.md。
• macOS 专项工作：将菜单命令、键盘操作流程、窗口、侧边栏、工具栏和文本行为视为产品需求，而非润色工作。加载 references/macos-quality-bar.md。
• 与版本相关的 API 问题：如果需要确认当前的确切 API 形式，请先加载 references/official-docs-map.md，并以 Apple 文档为准，而非凭记忆判断。

应用核心规则

1. 优先使用系统结构，再考虑自定义结构。 优先使用 NavigationStack、NavigationSplitView、TabView、List、Form、Table、Commands 和内置材质，而不是自定义容器。

2. 围绕状态设计，而不是围绕截图设计。 每项功能都应考虑加载、空内容、错误、离线、部分内容和权限受限等状态。

3. 将状态放在拥有它的视图附近。 默认工具集使用 @State、@Binding、@Bindable、@Environment、@Observable、@Query 和 .task。仅当现有代码库已采用视图模型，或视图之外的编排确实需要引用类型时，才引入视图模型。

4. 保持 body 开销低，并确保标识稳定。 不要在 body 中排序、筛选、格式化、解码图像、创建 UUID 或执行 I/O。应预先计算或缓存开销较大的工作，并使用稳定 ID。

5. 使用明确的输入组合小型视图。 优先传递范围明确的数据和绑定，而不是到处传递大型模型。将大型 body 拆分为职责清晰的子视图，而不是在一个类型中堆积更多逻辑。

6. 将无障碍和动态效果视为首要约束。 检查 Dynamic Type、VoiceOver、减少动态效果、降低透明度、对比度、焦点顺序和触控目标大小。

7. 符合平台特性。 iPhone、iPad、Mac 和 Vision Pro 的交互规范各不相同。除非产品有充分依据需要偏离，否则应保留各平台的惯用模式。

加载正确的参考资料

需求	加载
状态所有权、Observation、异步流程、路由、依赖注入	references/architecture-and-state.md
容器选择、组件组合、工作表、导航、应用外壳接线	references/ui-patterns.md
卡顿、失效风暴、布局抖动、性能分析、Bug 分诊、验证	references/performance-and-debugging.md
菜单栏、快捷键、窗口、侧边栏、工具栏、Mac 精细打磨、AppKit 应急方案	references/macos-quality-bar.md
Liquid Glass 的放置位置、修饰符顺序、容器、可用性、过渡效果	references/liquid-glass.md
关于状态、导航、场景、Liquid Glass 和性能的 Apple 官方文档与 WWDC 讲座	references/official-docs-map.md

交付结果

• 首先说明目标平台、应用类型和主要交互模型。
• 如果架构不明显，说明所选的状态与数据流方案。
• 使用预览快速迭代；但涉及场景、窗口、焦点、动画或性能时，须在 Simulator 或设备上验证关键行为。
• 进行审查时，优先报告风险最高的问题：正确性、平台不匹配、无障碍缺陷、性能风险，然后是样式。
• 调试时，分享主要假设、用于证实或排除假设的证据，以及最终根本原因。
• 最后列出验证步骤：测试、构建或 lint 命令、性能分析流程，以及仍需进行的手动检查。