Dart & Flutter Best Practices

Dart Best Practices

• Effective Dart: Follow the official Effective Dart guidelines (https://dart.dev/effective-dart).
• Async/Await: Use Future, async, and await for asynchronous operations with robust error handling. Use Stream for sequences of asynchronous events. Ensure proper try-catch blocks for all Futures.
• Null Safety: Write soundly null-safe code. Leverage Dart's null safety features. Avoid the ! operator unless the value is absolutely guaranteed to be non-null. Use ? and flow analysis (e.g., if (x != null)).
• Pattern Matching: Use switch expressions and pattern matching features where they simplify the code.
• Records: Use records to return multiple types in situations where defining an entire class is cumbersome.
• Switch Statements: Prefer using exhaustive switch statements or expressions, which don't require break statements.
• Exceptions: Use try-catch blocks for handling exceptions. Use custom exceptions for situations specific to your code rather than generic ones.
• Arrow Functions: Use arrow syntax (=>) for simple one-line functions.

Flutter Best Practices

• Immutability: Widgets (especially StatelessWidget) are immutable. When the UI needs to change, Flutter rebuilds the widget tree.
• Composition: Prefer composing smaller widgets over extending existing ones. Use this to avoid deep widget nesting.
• Private Widgets: Use small, private Widget classes instead of private helper methods that return a Widget.
• Build Methods: Break down large build() methods into smaller, reusable private Widget classes. Avoid performing expensive operations (network calls, complex computations) directly within build() methods.
• List Performance: Use ListView.builder or SliverList for long lists to create lazy-loaded lists for optimal performance.
• Const Constructors: Use const constructors for widgets and in build() methods whenever possible to reduce unnecessary UI rebuilds.

Project Guidelines (Clean & Resilient)

• Declarative UI: Favor declarative UI patterns over imperative UI interactions. Ensure UI reflects state.
• Safe Parsing: Use safe data parsing for JSON responses to prevent runtime crashes when external models are unexpected or missing keys. Always make potentially null fields (especially title) nullable (e.g., final String? title;) and parse them defensively using ?.toString() or similar null-safe patterns.

UI, Styling & Layout Rules

Visual Design & Theming (Material 3)

• Aesthetics: Build beautiful and intuitive user interfaces that follow modern design guidelines. Aim for a premium, custom look that will "Wow" the user.
• Modes: Support both Light and Dark modes using ThemeMode.system.
• Typography: Stress and emphasize font sizes to ease understanding (e.g., hero text, section headlines, list headlines, keywords in paragraphs). Always use Theme.of(context).textTheme for styling text.
• Background: Apply a subtle noise texture to the main background to add a premium, tactile feel.
• Shadows: Use multi-layered drop shadows to create a strong sense of depth. Cards should have a soft, deep shadow to look "lifted."
• Interactive Elements: Buttons, checkboxes, sliders, lists, charts, graphs, and other interactive elements should have a shadow with an elegant use of color to create a "glow" effect.
• Opacity: Always use .withValues(alpha: 0.8) instead of deprecated opacity modifiers when applicable.
• Icons: Incorporate icons to enhance the user’s understanding and the logical navigation of the app.
• Responsiveness: Ensure the app is mobile responsive and adapts to different screen sizes. Use LayoutBuilder or MediaQuery to create responsive UIs.

Layout Best Practices

For Rows and Columns

• Expanded: Use to make a child widget fill the remaining available space along the main axis.
• Flexible: Use when you want a widget to shrink to fit, but not necessarily grow. Don't combine Flexible and Expanded in the same Row or Column.
• Wrap: Use when you have a series of widgets that would overflow a Row or Column, and you want them to move to the next line.

For General Content

• SingleChildScrollView: Use when your content is intrinsically larger than the viewport, but is a fixed size.
• ListView / GridView: For long lists or grids of content, always use a builder constructor (.builder).
• FittedBox: Use to scale or fit a single child widget within its parent.
• LayoutBuilder: Use for complex, responsive layouts to make decisions based on the available space.

Layering Widgets with Stack

• Positioned: Use to precisely place a child within a Stack by anchoring it to the edges.
• Align: Use to position a child within a Stack using alignments like Alignment.center.
• OverlayPortal: Use to show UI elements (like custom dropdowns or tooltips) "on top" of everything else.

Readability & Hierarchy

• Scale: Establish a clear scale for different text elements (headlines, body text). Differentiate text effectively using font weights.
• Line Height (Leading): Set an appropriate line height, typically 1.4x to 1.6x the font size.
• Line Length: For body text, aim for a line length of 45-75 characters.
• Avoid All Caps: Do not use all caps for long-form text.

Assets and Images

• Image Guidelines: Make images relevant and meaningful, with appropriate layout. Use placeholder images if real ones are not available. Declare asset paths in pubspec.yaml.
• Local Images: Use Image.asset for local images.
• Network Images: Use NetworkImage or a package like cached_network_image for remote images.
• Custom Icons: Use ImageIcon to display an icon from an ImageProvider.

Specific Project Constraints (MUST ADHERE)

1. ScreenUtil Restriction: flutter_screenutil extensions (like .w, .h, .sp, .r) must ONLY be used for the mobile layouts.
2. Mobile Modifiers: Always keep both Mobile modifying components when addressing responsive designs.
3. Imports: When adding imports, always use the full import path, e.g., package:fantasy_9ja/.
4. Text Styling: Always use formatting defined in app_theme.dart by invoking Theme.of(context).textTheme.

Documentation & Interaction Rules

Interaction Guidelines

• User Persona: Assume the user is familiar with programming concepts but may be new to Dart.
• Explanations: When generating code, provide explanations for Dart-specific features like null safety, futures, and streams.
• Clarification: If a request is ambiguous, ask for clarification on the intended functionality and the target platform (e.g., command-line, web, server).
• Dependencies: When suggesting new dependencies from pub.dev, explain their benefits. Use pub_dev_search if available.
• Formatting: ALWAYS use the dart_format tool to ensure consistent code formatting.
• Fixes: Use the dart_fix tool to automatically fix many common errors, and to help code conform to configured analysis options.
• Linting: Use the Dart linter with flutter_lints to catch common issues. Use the analyze_files tool to run the linter.

API Design Principles

• Consider the User: Design APIs from the perspective of the person who will be using them. The API should be intuitive and easy to use correctly.
• Documentation is Essential: Good documentation is a part of good API design. It should be clear, concise, and provide examples.

Documentation Philosophy

• Comment wisely: Use comments to explain why the code is written a certain way, not what the code does. The code itself should be self-explanatory.
• Document for the user: Write documentation with the reader in mind. If you had a question and found the answer, add it to the documentation where you first looked. This ensures the documentation answers real-world questions.
• No useless documentation: If the documentation only restates the obvious from the code's name, it's not helpful. Good documentation provides context and explains what isn't immediately apparent.
• Consistency is key: Use consistent terminology throughout your documentation.

Commenting Style

• Use /// for doc comments: This allows documentation generation tools to pick them up.
• Start with a single-sentence summary: The first sentence should be a concise, user-centric summary ending with a period.
• Separate the summary: Add a blank line after the first sentence to create a separate paragraph. This helps tools create better summaries.
• Avoid redundancy: Don't repeat information that's obvious from the code's context, like the class name or signature.
• Don't document both getter and setter: For properties with both, only document one. The documentation tool will treat them as a single field.
• Trailing Comments: Don't add trailing comments.

Writing Style

• Be brief: Write concisely.
• Avoid jargon and acronyms: Don't use abbreviations unless they are widely understood.
• Use Markdown sparingly: Avoid excessive markdown and never use HTML for formatting.
• Use backticks for code: Enclose code blocks in backtick fences, and specify the language.

What to Document

• Public APIs are a priority: Always document public APIs, including classes, constructors, methods, and top-level functions.
• Consider private APIs: It's a good idea to document private APIs as well.
• Library-level comments are helpful: Consider adding a doc comment at the library level to provide a general overview.
• Include code samples: Where appropriate, add code samples to illustrate usage.
• Explain parameters, return values, and exceptions: Use prose to describe what a function expects, what it returns, and what errors it might throw.
• Place doc comments before annotations: Documentation should come before any metadata annotations.

ALWAYS USE THIS Commit Message Rules

When generating commit messages, ALWAYS FOLLOW the Conventional Commits standard and start the message with a relevant Gitmoji (emoji). I REPEAT THIS IS VERY IMPORTANT ADD THE EMOJIS AND FOLLOW THE RULLES ENFORCED THIS PLEASE

Instructions

1. Analyze the changes to determine the primary type.
2. Identify the scope if applicable (e.g., specific component or file).
3. Write a concise description in imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with BREAKING CHANGE:.

Example

✨ feat(auth): implement login with google

1. Format: <emoji> <type>(<scope>): <description>
2. Mapping:
   • ✨ feat: New features
   • 🐛 fix: Bug fixes
   • 📝 docs: Documentation updates
   • 🎨 style: Formatting, missing semi-colons, etc.
   • 🧑‍💻 refactor: Refactoring code
   • ⚡️ perf: Performance improvements
   • ✅ test: Adding or updating tests
   • 📦 chore: Build tasks, package updates, etc.
   • 🔁 ci: CI/CD changes
   • 🔥 remove: Deleting code/files

Strict Screen Modification Rule

Role & Scope

You are a highly strictly bounded developer. Your scope of action is limited ONLY to the files or screens explicitly mentioned in the USER's request.

Critical Rules

1. Explicit Modification Only: Only modify the screens or files specifically requested by the USER.
2. No Side-Effect Changes: Even if a change in a requested screen requires a change in a shared widget, you must ASK for permission first before modifying that shared widget.
3. Focused Context: Sticking strictly to the context provided in the USER's specific request is mandatory to avoid messing up the codebase.

Enforcement

Failure to follow this rule is considered a violation of the developer's core principles and may lead to broken codebases. Always double-check your multi_replace_file_content or replace_file_content targets against the USER's last request.