Flutter WidgetsSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: flutter-widgets
description: Build maintainable Flutter UI components with composition and theming. Use when changing widget implementation; defer animation-only changes and widget-test authoring.
metadata:
  triggers:
    files:
    - '**_page.dart'
    - '**_screen.dart'
    - '**/widgets/**'
    keywords:
    - StatelessWidget
    - const
    - Theme
    - ListView
---
# UI & Widgets

## **Priority: P1 (HIGH)**


- **State**: Use `StatelessWidget` by default. `StatefulWidget` only for local state/controllers.
- **Composition**: Extract UI into small, atomic `const` widgets.
- **Theming**: Use `Theme.of(context)`. No hardcoded colors.
- **Layout**: Use `Flex` + `Gap/SizedBox`.
- **Widget Keys**: All interactive elements must use keys from `widget_keys.dart`.
- **File Size**: If UI file exceeds ~80 lines, extract sub-widgets into private classes.
- **Specialized**:
 - `SelectionArea`: For multi-widget text selection.
 - `InteractiveViewer`: For zoom/pan.
 - `ListWheelScrollView`: For pickers.
 - `IntrinsicWidth/Height`: Avoid unless strictly required.
- **Large Lists**: Always use `ListView.builder`.

```dart
class AppButton extends StatelessWidget {
  final String label;
  final VoidCallback onPressed;
  const AppButton({super.key, required this.label, required this.onPressed});

  @override
  Widget build(BuildContext context) => ElevatedButton(onPressed: onPressed, child: Text(label));
}
```

## Anti-Patterns

- **No setState for server state**: Server or shared state belongs in BLoC, not widget state.
- **No widget file over 80 lines without extraction**: Extract sub-widgets into private classes.
- **No inline Key strings**: All keys must constants defined in `widget_keys.dart`.
- **No \_buildXxx() helper methods**: Extract to `const StatelessWidget` private class.
- **No manual widget repetition**: When 3+ sibling widgets of the same type differ only in data (e.g., radio buttons, tabs), map over a list instead. Put display labels inside the value object or a companion map so adding an option requires no UI change.

## References

- performance | testing

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- Extract
- interactive elements
- into private

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.