# Dart Rules > Apply when writing or reviewing Flutter or Dart code. Use when this capability is needed. - Skill: `tomevault-io/dart-rules` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/dart-rules` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dart-rules/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/dart-rules --- # AI rules for Flutter You are an expert in Flutter and Dart development. Your goal is to build beautiful, performant, and maintainable applications following modern best practices. You have expert experience with application writing, testing, and running Flutter applications for various platforms, including desktop, web, and mobile platforms. ## 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. * **Formatting:** 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 a recommended set of rules to catch common issues. Use the `analyze_files` tool to run the linter. ## Flutter style guide * **SOLID Principles:** Apply SOLID principles throughout the codebase. * **Concise and Declarative:** Write concise, modern, technical Dart code. Prefer functional and declarative patterns. * **Composition over Inheritance:** Favor composition for building complex widgets and logic. * **Immutability:** Prefer immutable data structures. ## Package Management * **Pub Tool:** To manage packages, use the `pub` tool, if available. * **External Packages:** If a new feature requires an external package, use the `pub_dev_search` tool, if it is available. Otherwise, identify the most suitable and stable package from pub.dev. * **Adding Dependencies:** To add a regular dependency, use the `pub` tool, if it is available. Otherwise, run `flutter pub add `. * **Adding Dev Dependencies:** To add a development dependency, use the `pub` tool, if it is available, with `dev:`. Otherwise, run `flutter pub add dev:`. * **Dependency Overrides:** To add a dependency override, use the `pub` tool, if it is available, with `override::1.0.0`. Otherwise, run `flutter pub add override::1.0.0`. * **Removing Dependencies:** To remove a dependency, use the `pub` tool, if it is available. Otherwise, run `dart pub remove `. ## Code Quality * **Code structure:** Adhere to maintainable code structure and separation of concerns (e.g., UI logic separate from business logic). * **Naming conventions:** Avoid abbreviations and use meaningful, consistent, descriptive names for variables, functions, and classes. * **Conciseness:** Write code that is as short as it can be while remaining clear. * **Simplicity:** Write straightforward code. Code that is clever or obscure is difficult to maintain. * **Error Handling:** Anticipate and handle potential errors. Don't let your code fail silently. * **Styling:** * Line length: Lines should be 80 characters or fewer. * Use `PascalCase` for classes, `camelCase` for members/variables/functions/enums, and `snake_case` for files. * **Functions:** * Functions short and with a single purpose (strive for less than 20 lines). * **Testing:** Write code with testing in mind. Use the `file`, `process`, and `platform` packages, if appropriate, so you can inject in-memory and fake versions of the objects. * **Logging:** Use the `logging` package instead of `print`. ## Dart Best Practices * **Effective Dart:** Follow the official Effective Dart guidelines (https://dart.dev/effective-dart) * **Class Organization:** Define related classes within the same library file. For large libraries, export smaller, private libraries from a single top-level library. * **Library Organization:** Group related libraries in the same folder. * **API Documentation:** Add documentation comments to all public APIs, including classes, constructors, methods, and top-level functions. * **Comments:** Write clear comments for complex or non-obvious code. Avoid over-commenting. * **Trailing Comments:** Don't add trailing comments. * **Async/Await:** Ensure proper use of `async`/`await` for asynchronous operations with robust error handling. * Use `Future`s, `async`, and `await` for asynchronous operations. * Use `Stream`s for sequences of asynchronous events. * **Null Safety:** Write code that is soundly null-safe. Leverage Dart's null safety features. Avoid `!` unless the value is guaranteed to be non-null. * **Pattern Matching:** Use 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. * **Exception Handling:** Use `try-catch` blocks for handling exceptions, and use exceptions appropriate for the type of exception. Use custom exceptions for situations specific to your code. * **Arrow Functions:** Use arrow syntax for simple one-line functions. ## API Design Principles When building reusable APIs, such as a library, follow these 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. ### Data Flow * **Data Structures:** Define data structures (classes) to represent the data used in the application. * **Data Abstraction:** Abstract data sources (e.g., API calls, database operations) using Repositories/Services to promote testability. ## Testing * **Running Tests:** To run tests, use the `run_tests` tool if it is available, otherwise use `flutter test`. * **Unit Tests:** Use `package:test` for unit tests. * **Widget Tests:** Use `package:flutter_test` for widget tests. * **Integration Tests:** Use `package:integration_test` for integration tests. * **Assertions:** Prefer using `package:checks` for more expressive and readable assertions over the default `matchers`. ### Testing Best practices * **Convention:** Follow the Arrange-Act-Assert (or Given-When-Then) pattern. * **Unit Tests:** Write unit tests for domain logic, data layer, and state management. * **Widget Tests:** Write widget tests for UI components. * **Integration Tests:** For broader application validation, use integration tests to verify end-to-end user flows. * **integration_test package:** Use the `integration_test` package from the Flutter SDK for integration tests. Add it as a `dev_dependency` in `pubspec.yaml` by specifying `sdk: flutter`. * **Mocks:** Prefer fakes or stubs over mocks. If mocks are absolutely necessary, use `mockito` or `mocktail` to create mocks for dependencies. While code generation is common for state management (e.g., with `freezed`), try to avoid it for mocks. * **Coverage:** Aim for high test coverage. ## Documentation * **`dartdoc`:** Write `dartdoc`-style comments for all public APIs. ### 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. ### 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. * **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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jhosm) — claim your Tome and manage your conversions.