用途:指导创建 Flutter UI 包,即在 package:flutter/material.dart 之上扩展可复用组件库。主题基础(ColorScheme、TextTheme、组件主题、明暗模式)由 Material Theming 技能覆盖,本技能专注包结构、组件 API 与测试,两者互补。
核心规范:依赖 flutter/material.dart 并组合 Material 组件,不重建其已有基础件;每个公开组件单独文件,文件名用 snake_case(如 app_button.dart);用单一 barrel 文件暴露全部公开组件与主题类,并再导出 material.dart;以 ThemeData、ColorScheme、TextTheme 为基座,用 ThemeExtension<T> 添加间距、自定义颜色等 App 级令牌;每个组件都有对应 widget 测试;公开类加统一前缀(如 App、Vg)避免与 Material 命名冲突;尽量使用 const 构造函数;所有公开成员写 dartdoc 注释。
包结构:lib/my_ui.dart 为 barrel 文件,lib/src/ 下分 theme/(app_theme.dart、app_colors.dart、app_spacing.dart、app_text_styles.dart)、widgets/、extensions/(context.appColors、context.appSpacing 快捷方式);test/src/ 与 test/helpers/pump_app.dart;widgetbook/ 为目录子模块;pubspec.yaml。
组件构建:组合 FilledButton、OutlinedButton、TextField、Card 等;仅接受最少必要参数;除 key 和 child/children 外使用具名参数;未传参时从主题取合理默认值;回调用 VoidCallback、ValueChanged<T>;可选插槽用 Widget?。
反模式与修正:不要用 GestureDetector 重建 Material 组件,应组合并设置样式;不要自建 InheritedWidget 主题系统,应用 ThemeData + ThemeExtension;不要在组件内硬编码 Color(0xFF...);不要复制 Material 的 ColorScheme 角色,只为 Material 未覆盖的值(success、warning、info)建令牌;回调不用 dynamic/Object;内部实现文件放入 src/ 并保持私有,通过 barrel 暴露。
创建包:使用 Very Good CLI MCP 工具脚手架生成 app_ui_package。
限制:资料未提供安装命令、具体版本要求、平台支持范围或收费信息。