apple-native-ui

Name: apple-native-ui
Author: kemiljk

github.com/kemiljk设计与 UI6171 次安装1 周前更新

代码仓库

关于 apple-native-ui

这项技能指导 Apple 平台界面的构建与审查，遵循各平台的交互、无障碍和适配规范。内容涵盖平台选择、Apple 最新指南、状态管理以及基于证据的验证。

主要功能

01按目标平台调整设计建议
02优先采用原生控件与 API
03规范状态管理与身份标识
04检查无障碍交互行为
05采用平台专属验证方式

适用场景

01设计 SwiftUI 界面
02审查无障碍与交互体验
03规划 macOS 界面
04验证不同外形设备上的行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/kemiljk/skills --skill apple-native-ui

安装后在 Claude Code 中输入/apple-native-ui确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

apple-verification.md

macos-native-workflows.md

macos-source-license.txt

详细介绍

Apple 原生 UI

构建和评审真正具有原生感的界面，应使用平台的交互、无障碍功能和适配规范，而不是模仿截图。

从目标平台开始

确定目标平台、最低操作系统版本、SwiftUI 与 UIKit/AppKit 的边界、支持的输入方式（触控、指针、键盘、VoiceOver、Digital Crown、遥控器、眼动/手势）以及主要设备形态。没有证据表明适用时，不要将 iPhone 惯例套用到 macOS、iPad 多任务处理、watchOS、tvOS 或 visionOS。

优先使用系统控件、语义颜色、文本样式、安全区域 API、导航容器和呈现 API，而不是自行仿制。自定义 UI 必须保留与原生界面等效的无障碍功能、焦点、状态和取消行为。

macOS 工作流

如果目标平台包含 macOS，在规划、构建、移植或评审非简单界面之前，请阅读 references/macos-native-workflows.md。其中补充了 Mac 专属工作流，涵盖命令、窗口与文稿、选择与焦点、粘贴板与拖放、撤销、状态恢复、配置、与 Finder 的互操作，以及以行为为导向的验证。

即使与 iPadOS 共用模型或视图，也应将 Mac 版本视为独立的工作流。仅仅支持调整大小的 iPad 布局，并不等于完整的 Mac 应用。

状态与标识

在最小且稳定的边界上持有状态。仅显示数据的子视图接收值；编辑父视图状态的子视图接收绑定。不要在 body 中执行副作用，并为列表使用稳定标识。

@Observable final class ProfileModel {
    var name = ""
    var isSaving = false
}

struct ProfileScreen: View {
    @State private var model = ProfileModel()

    var body: some View {
        Form {
            TextField("Name", text: $model.name)
            Button("Save") { save() }
                .disabled(model.name.isEmpty || model.isSaving)
        }
    }
}

不要将注入的值转换成 @State，不要使用位置索引作为可变列表标识，也不要在 Button、NavigationLink、Toggle 或其他原生控件能表达任务时使用 onTapGesture。

平台规范

根据目标平台使用 NavigationStack/NavigationSplitView、工作表、警告框、确认对话框和工具栏。验证返回、关闭、取消和焦点恢复路径。
使用语义颜色和支持 Dynamic Type 的排版。添加截断、裁剪或固定框架前，先测试超大文本。
将安全区域、分屏视图、窗口大小调整、旋转、外接键盘、指针和布局方向视为布局的输入，而非特殊断点。
在部署目标允许时，优先使用 @Observable、@State、@Binding 和 @Bindable；对特定版本的 API 设置版本条件，并提供真正可用的替代方案。
让动画由值驱动，并在“减少动态效果”设置下保留任务行为。测试或报告结果前，等待可观察到的最终状态。

无障碍功能

无障碍功能通过原生无障碍树表达，而非 ARIA。检查 VoiceOver 标签、值、提示、特征、分组、阅读顺序、可调节操作、焦点移动和禁用控件。隐藏装饰性图像；为有意义的图像和含义不明确的图标添加标签。

Button(action: play) {
    Image(systemName: "play.fill")
}
.accessibilityLabel("Play preview")

Image(systemName: "sparkles")
    .accessibilityHidden(true)

有关模拟器、设备、XCUITest、无障碍功能和设备形态的证据，请阅读 references/apple-verification.md。在提出原生验证相关的结论之前，请先阅读该文档。

评审结果

将发现关联到源文件路径或观察到的目标平台/设备。说明证据仅来自源代码还是来自渲染结果。指出受影响的平台和输入方式；针对 iOS 的发现不一定适用于 macOS。

优先 / 避免

优先	避免
使用系统控件并进行有意的样式设计	用可点击的堆叠视图或图片代替控件
使用语义化字体、颜色和自适应布局	使用在更大字体或更小窗口下会导致布局错乱的固定尺寸
使用稳定的 ID，并明确状态的所有权	使用索引作为标识，以及将副作用隐藏在 `body` 中
按平台进行验证	将模拟器截图视为适用于所有目标平台的证明
设置版本门槛并提供实用的回退方案	无条件使用新 API，导致受支持的用户被悄然排除

支持 Markdown

登录后评论