fl-widget-preview

name	fl-widget-preview
description	Creates and runs previews with Flutter's official Widget Previewer using `@Preview` from `package:flutter/widget_previews.dart`. Use when the user asks to preview, showcase, inspect, or smoke-test a Flutter widget in the Widget Previewer.
license	MIT
metadata	{"audience":"flutter-developers","framework":"flutter","pattern":"widget-preview"}

Flutter Widget Preview Skill

When to use

• Previewing a new or changed Flutter widget interactively.
• Adding @Preview coverage for reusable UI, theme, or core widgets.
• Smoke-testing visual states without launching the full app.

Tooling model

Flutter Widget Previewer renders widgets in Chrome, separate from the app. It requires Flutter 3.35+; IDE support requires Flutter 3.38+. The API is experimental, so verify https://docs.flutter.dev/tools/widget-previewer before broad preview infrastructure changes.

Do not introduce Widgetbook, Storybook, or custom preview apps unless the user explicitly asks.

Add a preview

Import the preview API in the package that owns the widget:

import 'package:flutter/material.dart';
import 'package:flutter/widget_previews.dart';

@Preview(name: 'Feature card')
Widget featureCardPreview() => const FeatureCard();

@Preview can annotate top-level functions, static methods, and public Widget constructors/factories with no required arguments. Functions and methods must return Widget or WidgetBuilder.

Use deterministic, non-secret preview data. Keep preview-only state outside production config and generated files.

Configure previews

Use @Preview parameters instead of new infrastructure:

• name and group for discoverability.
• size for realistic constraints, especially mobile widths and unconstrained widgets.
• textScaleFactor for accessibility checks.
• brightness for light/dark variants.
• wrapper for required ancestors such as MaterialApp, localization, providers, or inherited state.
• theme and localizations for Material/Cupertino theme and locale configuration.

Apply multiple @Preview annotations to one function for state variants. Use custom Preview or MultiPreview annotations only when repeated configuration is already noisy.

Project wrapper guidance

Match enough production context for the widget to render honestly:

• Add MaterialApp/Scaffold for Material widgets.
• Add app localization delegates and supported locales when the widget reads translations.
• Apply the project theme path when the widget uses context.themeColor, context.textTheme, or ScreenForm.
• Provide the same BLoC/provider shape the screen expects; prefer focused fake data over broad mocks.

All callback values passed to preview annotations must be public and constant so previewer code generation can read them.

Run the previewer

From the Flutter package root that contains the previews:

fvm flutter widget-preview start

Check .fvm_cache; if USING_FVM=1, use fvm flutter, otherwise use flutter. IDEs expose a "Flutter Widget Preview" tab when supported.

Run the previewer yourself when the local Flutter toolchain is available. Ask the user only for setup you cannot perform.

Limitations and verification

• Native plugins and dart:io / dart:ffi APIs are unsupported because the previewer uses Flutter Web.
• Asset loading through dart:ui fromAsset APIs must use package-based paths such as packages/my_package/assets/foo.png.
• Apply size when constraints matter; default unconstrained behavior is not stable.
• Preview default, loading, empty, error, disabled, long-text, overflow, light/dark, and text-scale states as applicable.
• Use the previewer controls for zoom, brightness, and hot restart.
• If E2E/spec verification is requested, use the fl-testing skill and flutter_skill guidance separately.
• If you cannot run the previewer, report the exact blocker.

Related

• fl-theme-usage
• fl-testing
• fl-behavioral-guardrails