使用说明
figma_mcp
此存储库包含一个Flutter应用程序脚手架，该脚手架使用“MCP”（模型组件模式/模型上下文协议）设计，使用Figma MCP生成的UI资产对工作流进行编码。项目结构、约定和辅助脚本是为从Figma生成UI的团队量身定制的，然后将生成的代码净化并集成到生产质量的Flutter架构中。
什么是MCP？
这里的MCP是指一种设计到代码的生产力模式，以及一组用于将Figma设计转换为Flutter小部件和应用程序屏幕的实践。它不是一个单一的包——它是一个工作流程和一组约定，可以帮助团队更快地发布UI，而不会失去可维护性。
主要观点：
- 使用自动化工具（Figma MCP或类似工具）从Figma设计中生成第一遍UI实现。
- 将生成的代码视为起点：清理、重构并与项目约定保持一致。
- 将业务逻辑保存在Cubits/Repositories中，并保持小部件纯粹的表示性。
- 使用类型安全资产（flutter_gen）、主题和集中颜色来防止设计漂移。
MCP的工作原理（高级）
- Figma中的设计。设计师创建艺术板、组件和令牌。
- 导出或使用MCP插件为布局和资源生成Flutter代码。
- 将生成的文件导入到项目的临时文件夹或“generated/”文件夹中。
- 对生成的代码进行消毒：
- 将文件重命名为snake_case，将小部件类重命名为UpperCamelCase。
- 在中用语义颜色标记替换硬编码颜色
lib/values/. - 将原始资产路径替换为flutter_gen
Assets.*助手。 - 从小部件中删除业务逻辑；将其移动到Cubits和存储库。
- 将可重复使用的部件提取到
lib/views/并将特定的小部件添加到lib/modules/[feature]/views/. - 在路线构建器中注册立方体/提供者(
lib/utilities/navigation/app_routes.dart)而不是在小部件内部。 - 为任何面向用户的文本添加本地化字符串，并运行intl生成器。
- 跑
dart analyze,dart format，以及dart run build_runner build -d必要时。
关于此仓库（Figma MCP用法）
此项目遵循项目GitHub说明中概述的约定(.github/copilot-instructions.md).它包括：
lib/generated/--用于生成模型和净化输出的地方。lib/modules/--第一个模块，每个模块都有屏幕、肘和视图。lib/repositories/--数据层remote_repository和local_repository（安全存储、共享首选项）。lib/values/--应用程序范围内的颜色、主题、常量和资源。lib/views/--从生成的设计中提取的可重用UI小部件。
如果您使用Figma MCP为此项目生成组件，请按照中的后处理检查表进行操作 .github/copilot-instructions.md （也在下面的“消毒检查表”部分进行了总结）。
参考文件
有关MCP工作流程和分步清理指南的完整项目级参考，请参阅 MCP.md.
消毒检查表（生成UI后要做什么）
- 将生成的文件重命名为snake_case，并确保类使用UpperCamelCase。
- 将硬编码的Colors.*和Color（0xFF…）标记替换为引用
lib/values/app_colors.dart和lib/values/app_theme/. - 将SizedBox垫片替换为
Gap()从gap在适当的情况下包装。 - 将原始资产路径转换为
Assets.images.../Assets.vectors...从flutter_gen. - 确保生成器中的任何API模型都位于
lib/generated/或lib/models/然后跑build_runner如果它们包括*.g.dart文件夹。 - 提取重复的UI
lib/views/作为具有const构造函数的单一责任小部件。 - 将业务逻辑（导航决策、网络调用、状态）移动到Cubits
lib/modules/[feature]/以及存储库。 - 在路线级别注册腕尺/供应商
lib/utilities/navigation/app_routes.dart. - 为中的任何可见文本添加本地化键
lib/l10n/*.arb然后跑flutter pub run intl_utils:generate.
使用Figma MCP（和MCP工作流程）的优点
- 速度：从高保真设计中快速获得可用的UI骨架。
- 迭代：设计师和开发人员可以更快地迭代；Figma中的微小视觉变化可以重新生成。
- 一致性：使用相同的事实来源（Figma）可以保持设计和实现的一致性。
- 入职培训：新开发人员获得了像素完美屏幕的明确起点。
权衡/警告
- 生成的代码很少是生产就绪的：它需要净化和重构。
- 如果生成的小部件包含逻辑或全局状态，则存在架构漂移的风险。
- 如果跳过净化（颜色、大小、资产），则硬编码值会激增。
- 需要额外的CI检查和代码审查规则，以确保生成的代码符合项目标准。
最佳实践（团队规则）
- 合并前始终检查生成的代码。PR应包括一个简短的说明，描述生成的内容和消毒的内容。
- 将生成的代码保存在
lib/generated/最初。将经过消毒的小部件移动到lib/views/或lib/modules/.../views/. - 切勿在生成的小部件中保留网络或状态逻辑。如果它存在，请将其移动到Cubits和存储库中。
- 集中颜色和主题。添加新的设计颜色
lib/values/app_colors.dart并将它们连接起来AppColorTheme. - 为任何面向用户的文本添加本地化，并运行intl生成器。
- 跑
dart format和dart analyze在承诺之前。
贡献者快速入门（如何使用此仓库）
先决条件：
- Flutter SDK（推荐稳定版本）
flutter pub get
典型开发流程：
- 获取依赖关系
flutter pub get
- 如果添加或更改了可序列化模型或生成的代码，请运行build_runner：
dart run build_runner build -d
- 运行应用程序（选择模拟器或设备）：
flutter run
- 棉绒和格式：
dart format .
dart analyze
- 添加Figma MCP生成的UI时：
- 将生成的文件导入
lib/generated/. - 遵循上述消毒检查表。
- 将生成的文件导入
项目惯例（简称）
- 文件名：snake_case
- 飞镖类：UpperCamelCase
- 格子：后缀为
_cubit.dart以及类名SomethingCubit - 国家：
_state.dart和SomethingState - 导航模型：
_nav_dm.dart - API请求/响应模型：
_req_dm.dart,_res_dm.dart
看 .github/instructions/*.md 了解在整个代码库中应用的更详细的规则（颜色使用、代码风格、状态管理、api集成等）。
从哪里开始阅读代码
lib/main.dart和lib/app.dart–应用程序入口和配置lib/utilities/navigation/app_routes.dart–路线定义和供应商接线lib/values/–主题、颜色、常量lib/modules/–功能模块及其views/和cubit文件
故障排除和提示
- 如果由于生成的序列化文件导致构建失败，请运行
dart run build_runner build -d并重新启动IDE。 - 如果资产无法解决，请运行
flutter pub run build_runner build并确保flutter_gen生成的文件是最新的。 - 对于本地化更改，请运行
flutter pub run intl_utils:generate.
快速常见问题
Q： 仓库中是否允许生成UI？
A： 是的，但在合并之前，一定要进行清理和重构。将生成的代码视为草稿，而不是最终版本。
Q： 我应该在哪里注册Cubits屏幕？
A： In lib/utilities/navigation/app_routes.dart 靠近路线建设者。这使得生命周期管理更加明确。
总结
该项目使用实用的MCP工作流来加快UI开发，同时保持架构质量。使用Figma MCP引导UI，但在考虑生成的文件生产就绪之前，应用项目的净化和代码风格规则。
如果你愿意，我也可以：
- 生成一个简短的PR检查表模板，用于清理生成的UI。
- 添加一个带有MCP特定步骤的小CONTRIBUTING.md。
如果你想要其中之一，告诉我哪一个，我会添加的。
