ui-package

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 (/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:

• Scaffold from the app_ui_package template — create the package with the Very Good CLI MCP tool, subcommand: 'app_ui_package'. Never flutter_package, never dart_package, never flutter create --template=package; those produce a bare package with none of the theme, barrel, test-helper, or Widgetbook scaffolding below
• 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, so one import gives a consumer both Material's widgets and the package's own and no second Material import is needed
• lib/src/ is private — consumers import the barrel and nothing else; a per-file import such as package:my_ui/src/widgets/app_button.dart reaches into private implementation and breaks on any internal rename. Tree shaking already drops unused widgets, so the barrel costs nothing
• 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>, register every one of them on ThemeData.extensions, and read them through a BuildContext extension (context.appColors, context.appSpacing)
• Every widget has a corresponding widget test — behavioral tests verify interactions, callbacks, and state changes, pumped through the package's pumpApp helper rather than an inline MaterialApp
• Decline anti-patterns with working code — when a request asks for something in the Anti-Patterns table, say why it is wrong and deliver the corrected implementation in the same response. Do not stop at the objection, and do not ask permission to do it the documented way
• 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