figma_mcp

This repository contains a Flutter app scaffold that uses the "MCP" (Model-Component-Pattern / Model Context Protocol) design-to-code workflow with Figma MCP-generated UI assets. The project structure, conventions, and helper scripts are tailored for teams that generate UI from Figma and then sanitize and integrate the generated code into a production-quality Flutter architecture.

What is MCP?

MCP here refers to a design-to-code productivity pattern and a set of practices used to convert Figma designs into Flutter widgets and app screens. It isn't a single package — it's a workflow and a set of conventions that help teams ship UI faster without losing maintainability.

Key ideas:

• Use automated tools (Figma MCP or similar) to generate a first-pass UI implementation from Figma designs.
• Treat generated code as a starting point: sanitize, refactor, and align with project conventions.
• Keep business logic in Cubits/Repositories and keep widgets purely presentational.
• Use type-safe assets (flutter_gen), themes, and centralized colors to prevent design drift.

How MCP works (high-level)

1. Design in Figma. Designers create artboards, components, and tokens.
2. Export or use an MCP plugin to generate Flutter code for layouts and assets.
3. Import generated files into the project under a temporary or "generated/" folder.
4. Sanitize generated code:
   • Rename files to snake_case and widget classes to UpperCamelCase.
   • Replace hard-coded colors with semantic color tokens in lib/values/.
   • Replace raw asset paths with flutter_gen Assets.* helpers.
   • Remove business logic from widgets; move it to Cubits and repositories.
5. Extract reusable pieces into lib/views/ and feature-specific widgets into lib/modules/[feature]/views/.
6. Register Cubits/providers in route builders (lib/utilities/navigation/app_routes.dart) rather than inside widgets.
7. Add localization strings for any user-facing text and run the intl generator.
8. Run dart analyze, dart format, and dart run build_runner build -d when needed.

About this repo (Figma MCP usage)

This project follows the conventions outlined in the project's GitHub instructions (.github/copilot-instructions.md). It includes:

• lib/generated/ — place for generated models and sanitized outputs.
• lib/modules/ — feature-first modules, each with screens, cubits, and views.
• lib/repositories/ — data layer with remote_repository and local_repository (secure storage, shared prefs).
• lib/values/ — app-wide colors, themes, constants and resources.
• lib/views/ — reusable UI widgets extracted from generated designs.

If you used Figma MCP to generate components for this project, follow the post-processing checklist in .github/copilot-instructions.md (also summarized in the "Sanitization checklist" section below).

Reference docs

For a full, project-level reference of the MCP workflow and step-by-step sanitization guidance, see MCP.md.

Sanitization checklist (what to do after generating UI)

• Rename generated files to snake_case and ensure classes use UpperCamelCase.
• Replace hard-coded Colors.* and Color(0xFF...) tokens with references from lib/values/app_colors.dart and lib/values/app_theme/.
• Replace SizedBox spacers with Gap() from the gap package where appropriate.
• Convert raw asset paths to Assets.images... / Assets.vectors... from flutter_gen.
• Ensure any API models from the generator are placed under lib/generated/ or lib/models/ and run build_runner if they include *.g.dart files.
• Extract repeated UI to lib/views/ as single-responsibility widgets with const constructors.
• Move business logic (navigation decisions, network calls, state) to Cubits in lib/modules/[feature]/ and repositories.
• Register cubits/providers at the route level in lib/utilities/navigation/app_routes.dart.
• Add localization keys for any visible text in lib/l10n/*.arb and run flutter pub run intl_utils:generate.

Pros of using Figma MCP (and MCP workflows)

• Speed: Quickly get a working UI skeleton from high-fidelity designs.
• Iteration: Designers and devs can iterate faster; small visual changes in Figma can be re-generated.
• Consistency: Using the same source of truth (Figma) keeps design and implementation aligned.
• Onboarding: New developers get a clear starting point for pixel-perfect screens.

Tradeoffs / Caveats

• Generated code is rarely production-ready: it needs sanitization and refactoring.
• Risk of architecture drift if generated widgets include logic or global state.
• Proliferation of hard-coded values if sanitization is skipped (colors, sizes, assets).
• Extra CI checks and code-review rules are required to ensure generated code is adapted to project standards.

Best practices (team rules)

1. Always review generated code before merging. PRs should include a short note describing what was generated and what was sanitized.
2. Keep generated code in lib/generated/ initially. Move sanitized widgets to lib/views/ or lib/modules/.../views/.
3. Never keep network or state logic inside generated widgets. If it exists, move it into Cubits and repositories.
4. Centralize colors and theming. Add new design colors to lib/values/app_colors.dart and wire them in AppColorTheme.
5. Add localization for any user-facing text and run the intl generator.
6. Run dart format and dart analyze before committing.

Quick-start for contributors (how to use this repo)

Prerequisites:

• Flutter SDK (stable version recommended)
• flutter pub get

Typical development flow:

1. Get dependencies

flutter pub get

2. If you added or changed serializable models or generated code, run build_runner:

dart run build_runner build -d

3. Run the app (choose an emulator or device):

flutter run

4. Lint and format:

dart format .
dart analyze

5. When adding generated UI from Figma MCP:
   • Import generated files into lib/generated/.
   • Follow the sanitization checklist above.

Project conventions (short)

• File names: snake_case
• Dart classes: UpperCamelCase
• Cubits: suffixed with _cubit.dart and class name SomethingCubit
• States: _state.dart and SomethingState
• Navigation models: _nav_dm.dart
• API request/response models: _req_dm.dart, _res_dm.dart

See .github/instructions/*.md for more detailed rules that are applied across the codebase (color usage, code style, state management, api integration, and more).

Where to start reading the code

• lib/main.dart and lib/app.dart – app entry and configuration
• lib/utilities/navigation/app_routes.dart – route definitions and provider wiring
• lib/values/ – themes, colors, constants
• lib/modules/ – feature modules and their views/ and cubit files

Troubleshooting & tips

• If build fails due to generated serialization files, run dart run build_runner build -d and restart the IDE.
• If assets don't resolve, run flutter pub run build_runner build and ensure flutter_gen generated files are up to date.
• For localization changes, run flutter pub run intl_utils:generate.

Quick FAQ

Q: Is generated UI allowed in the repo?

A: Yes — but always sanitize and refactor before merging. Treat generated code as a draft, not final.

Q: Where should I register Cubits for a screen?

A: In lib/utilities/navigation/app_routes.dart close to the route builder. That keeps lifecycle management explicit.

Summary

This project uses a pragmatic MCP workflow to speed up UI development while preserving architectural quality. Use Figma MCP to bootstrap UIs but apply the project's sanitization and code-style rules before considering generated files production-ready.

---

If you want, I can also:

• Generate a short PR checklist template for sanitizing generated UI.
• Add a small CONTRIBUTING.md with MCP-specific steps.

If you'd like one of those, tell me which and I'll add it.