expo-ios-hig-verify

Expo iOS HIG 验证器

只读静态检查工具，可扫描 Expo（React Native）项目，查找违反 expo-ios-hig 规则的情况，并按严重性分组报告，同时提供 file:line 位置和解释修复方法的规则链接。它是 expo-ios-hig 参考技能的自动化配套工具：该技能讲解规则；此工具负责检查。

适用时机

在以下情况下运行此技能：

• 用户要求检查、lint、审计或评审 Expo 应用是否符合 HIG 或具有原生体验
• 合并或发布 Expo iOS UI 更改前，将其作为质量门禁
• 搭建新屏幕后，确认界面仍保持原生风格
• 调查 Expo 应用为何“像是套了网页壳”或“感觉像 Android”

此工具为只读工具，绝不会修改目标项目，因此可安全地无人值守运行。

工作流概览

verify-hig.sh [project-dir]
  1. Resolve search roots (app/ src/ components/ by default, or config.json)
  2. Run static checks — one per detectable expo-ios-hig rule (rg, or grep fallback)
  3. Aggregate findings: severity, rule, message, file:line
  4. Print grouped report (ERRORS then ADVISORIES) with a link to each rule
  5. Exit 0 if clean, 1 if any ERROR (with --strict, advisories fail too)

运行：

bash scripts/verify-hig.sh /path/to/expo-app          # text report
bash scripts/verify-hig.sh /path/to/expo-app --strict # advisories also fail
bash scripts/verify-hig.sh /path/to/expo-app --json   # machine-readable

检查项

错误为高精度检查（匹配导入和字面量标志，误报率低）。建议为启发式检查，值得查看，但除非使用 --strict，否则不会导致运行失败。

严重性	规则	检测内容
错误	native-avoid-material-ui	react-native-paper、@react-native-material/*、@rneui/*、react-native-elements 导入
错误	nav-native-stack	@react-navigation/stack / createStackNavigator
错误	touch-gesture-handler-thread	PanResponder
错误	touch-pressable-feedback	TouchableWithoutFeedback
错误	acc-dynamic-type	allowFontScaling={false}
错误	motion-ui-thread-animation	useNativeDriver: false
建议	nav-native-tabs	createBottomTabNavigator（JS 标签栏）
建议	visual-semantic-colors	color:/backgroundColor:/borderColor:/tintColor: 中的硬编码十六进制颜色值
建议	visual-system-font	自定义 fontFamily:
建议	system-status-bar	硬编码的 StatusBar style="dark"/"light"
建议	motion-virtualized-lists	同时使用 <ScrollView> 和 .map( 的文件

每条检查结果都会链接到 expo-ios-hig/references/{rule}.md（链接路径可在 config.json 中配置），查看说明和修复方法。

设置

config.json 为可选文件，未配置时将使用合理的默认值。如果项目目录不同，可在首次使用时覆盖：

• search_roots — 要扫描的源码目录，以空格分隔（默认值：app src components）
• skill_rules_dir — 报告中指向 expo-ios-hig 规则文件的路径（默认值：../expo-ios-hig/references）

如果已安装 jq，脚本会从 config.json 读取这些值；否则使用默认值。工具在可用时使用 rg（ripgrep），否则回退到 grep，没有硬性依赖。

使用方法

1. 在 Expo 项目根目录下运行 scripts/verify-hig.sh。
2. 阅读分组报告；对于任何检查结果，打开对应的规则文件查看修复方法。
3. 发布前必须修复错误；审查建议（其中包括有意为之的例外情况）。
4. 如需扩展：在 run_checks() 中添加一行 check ERROR|ADVISORY <rule> "<message>" "<regex>" — 参见 references/workflow.md。

相关技能

• expo-ios-hig — 此验证器检查的规则；每条检查结果都会链接回该技能。
• expo-ios-screen-scaffolder — 以确保通过这些检查的方式生成屏幕。