awesome-ai-setup widgets.instructions.md

Widget Conventions

These conventions apply to all Flutter widget code in lib/.

---

Base Class

Use HookConsumerWidget as the default base class.

// Standard widget - use this by default
class TaskCard extends HookConsumerWidget {
  const TaskCard({super.key, required this.task});

  final Task task;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return ...;
  }
}

// Pure display widget - use this when there is no state or provider usage
class StatusBadge extends StatelessWidget {
  const StatusBadge({super.key, required this.status});

  final TaskStatus status;

  @override
  Widget build(BuildContext context) {
    return ...;
  }
}

Do not use StatefulWidget, ConsumerWidget, ConsumerStatefulWidget, or HookWidget.

---

Local State

Local widget state uses useState and useAnimationController hooks - not setState.

// Correct
final isExpanded = useState(false);
final tabController = useTabController(initialLength: 3);
final textController = useTextEditingController();
final scrollController = useScrollController();

// Wrong - do not use
// setState(() { _isExpanded = true; });

Hooks are called at the top of build() before any conditional returns. Never call hooks inside conditionals or loops.

---

Spacing and Layout

Use spacing constants from AppSpacing - do not hardcode pixel values.

// Correct
Padding(
  padding: EdgeInsets.all(AppSpacing.md),
)
SizedBox(height: AppSpacing.sm)
SizedBox(width: AppSpacing.xs)

// Wrong
Padding(padding: EdgeInsets.all(16))
SizedBox(height: 8)

Spacing scale:

• AppSpacing.xs = 4
• AppSpacing.sm = 8
• AppSpacing.md = 16
• AppSpacing.lg = 24
• AppSpacing.xl = 32
• AppSpacing.xxl = 48

---

Theming

Access colors and text styles through Theme.of(context) or the AppColors / AppTextStyles constants. Do not hardcode colors.

// Correct
color: Theme.of(context).colorScheme.primary
color: AppColors.taskOverdue
style: AppTextStyles.bodyMedium

// Wrong
color: Color(0xFF2563EB)
style: TextStyle(fontSize: 14, fontWeight: FontWeight.w500)