UI Package

Best practices for creating a Flutter UI package — a reusable widget library that builds on top of package:flutter/material.dart, extending it with app-specific components, custom design tokens via ThemeExtension, and a consistent API surface.

Theming foundation: This skill focuses on UI package structure, widget APIs, and testing. For foundational Material 3 theming (ColorScheme, TextTheme, component themes, spacing constants, light/dark mode), see the Material Theming skill (/vgv-material-theming). The two skills are complementary — Material Theming covers how to set up and use ThemeData; this skill covers how to extend it with ThemeExtension tokens and package reusable widgets around it.

Core Standards

Apply these standards to ALL UI package work:

• Build on Material — depend on flutter/material.dart and compose Material widgets; do not rebuild primitives that Material already provides
• One widget per file — each public widget lives in its own file named after the widget in snake_case (e.g., app_button.dart)
• Barrel file for public API — expose all public widgets and theme classes through a single barrel file (e.g., lib/my_ui.dart) that also re-exports material.dart
• Extend theming with ThemeExtension — use Material's ThemeData, ColorScheme, and TextTheme as the base (see Material Theming skill); add app-specific tokens (spacing, custom colors) via ThemeExtension<T>
• Every widget has a corresponding widget test — behavioral tests verify interactions, callbacks, and state changes
• Prefix all public classes — use a consistent prefix (e.g., App, Vg) to avoid naming collisions with Material widgets
• Use const constructors everywhere possible — all widget constructors must be const when feasible
• Document every public member — every public class, constructor parameter, and method has a dartdoc comment