todo-app/docs/DOCS-flutter-rules-design.md

Flutter AI rules — Colour, type, documentation and accessibility

Colour schemes, fonts, dartdoc conventions and accessibility.

Verbatim from flutter/flutter docs/rules/rules.md, split across four files only to keep each under the repo's 250-line cap. Re-fetch periodically to stay current; do not hand-edit.

Contrast Ratios

• WCAG Guidelines: Aim to meet the Web Content Accessibility Guidelines (WCAG) 2.1 standards.
• Minimum Contrast:
  • Normal Text: A contrast ratio of at least 4.5:1.
  • Large Text: (18pt or 14pt bold) A contrast ratio of at least 3:1.

Palette Selection

• Primary, Secondary, and Accent: Define a clear color hierarchy.
• The 60-30-10 Rule: A classic design rule for creating a balanced color scheme.
  • 60% Primary/Neutral Color (Dominant)
  • 30% Secondary Color
  • 10% Accent Color

Complementary Colors

• Use with Caution: They can be visually jarring if overused.
• Best Use Cases: They are excellent for accent colors to make specific elements pop, but generally poor for text and background pairings as they can cause eye strain.

Example Palette

• Primary: #0D47A1 (Dark Blue)
• Secondary: #1976D2 (Medium Blue)
• Accent: #FFC107 (Amber)
• Neutral/Text: #212121 (Almost Black)
• Background: #FEFEFE (Almost White)

Font Best Practices

Font Selection

• Limit Font Families: Stick to one or two font families for the entire application.
• Prioritize Legibility: Choose fonts that are easy to read on screens of all sizes. Sans-serif fonts are generally preferred for UI body text.
• System Fonts: Consider using platform-native system fonts.
• Google Fonts: For a wide selection of open-source fonts, use the google_fonts package.

Hierarchy and Scale

• Establish a Scale: Define a set of font sizes for different text elements (e.g., headlines, titles, body text, captions).
• Use Font Weight: Differentiate text effectively using font weights.
• Color and Opacity: Use color and opacity to de-emphasize less important text.

Readability

• 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.

Example Typographic Scale

// In your ThemeData
textTheme: const TextTheme(
  displayLarge: TextStyle(fontSize: 57.0, fontWeight: FontWeight.bold),
  titleLarge: TextStyle(fontSize: 22.0, fontWeight: FontWeight.bold),
  bodyLarge: TextStyle(fontSize: 16.0, height: 1.5),
  bodyMedium: TextStyle(fontSize: 14.0, height: 1.4),
  labelSmall: TextStyle(fontSize: 11.0, color: Colors.grey),
),

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.

Accessibility (A11Y)

Implement accessibility features to empower all users, assuming a wide variety of users with different physical abilities, mental abilities, age groups, education levels, and learning styles.

• Color Contrast: Ensure text has a contrast ratio of at least 4.5:1 against its background.
• Dynamic Text Scaling: Test your UI to ensure it remains usable when users increase the system font size.
• Semantic Labels: Use the Semantics widget to provide clear, descriptive labels for UI elements.
• Screen Reader Testing: Regularly test your app with TalkBack (Android) and VoiceOver (iOS).