print_widget_flutter 0.5.3

Capture Flutter widgets and pages as PNG screenshots for visual verification. Designed for LLMs to generate, compare, and iterate on UI.

print_widget

Beta — This package is under active development. The API may change drastically between versions. That said, AI agents (Claude, Cursor, Codex) handle API changes gracefully by reading the --llm-guide output, so breaking changes won't break your workflow — just run print_widget --llm-guide and the AI adapts.

Capture Flutter widgets as PNG screenshots. Built for LLMs to see what they build.

Screenshots

What it does

You define widgets. It generates PNGs. LLMs read the PNGs and iterate on the UI.

You write code → print_widget generates screenshots → LLM sees the result → fixes UI → repeat

Two things in one

What	Purpose	Install
CLI	Run generate, list, config	dart pub global activate print_widget_flutter
Dev dependency	Use PrintSession, PrintEntry, Printable in code	Added by print_widget init

The CLI runs commands. The dev dependency gives you the Dart classes. print_widget init sets up both.

Quick start

1. Install CLI (once)

dart pub global activate print_widget_flutter

Not yet on pub.dev? Install directly from GitHub:

dart pub global activate --source git https://github.com/ulisseshen/print_widget.git

2. Set up your project

cd my_flutter_app
print_widget init

Web projects (web/ directory or platforms: web: in pubspec) automatically get web_1440 as the default device.

3. Edit the config

Open test/prints/print_config.dart:

final printSession = PrintSession(
  appWrapper: (child) => MaterialApp(
    theme: MyAppTheme.light,
    home: child,
  ),
  defaultDevice: DeviceFrame.iPhone15Pro,
);

final printList = <PrintEntry>[
  page('login_page', const LoginPage()),
  widget('product_card', ProductCard(title: 'Demo'), size: Size(350, 420)),

  // Multiple states of the same screen
  pages('sign_in', states: [
    state('empty', SignInScreen()),
    state('error', SignInScreen(initialError: 'Invalid email')),
  ]),
];

4. Generate

print_widget generate

Done. PNGs + manifest.json in your output directory.

Set up with your AI tool

print_widget works with Claude Code, Cursor, Codex, and Antigravity. After the quick start above, install the AI skills for your tool:

Claude Code

print_widget skills --tool=claude --install

Skills installed to .claude/skills/ (project) or ~/.claude/skills/ (user). Use with /print-widget-figma, /print-widget-stitch, /print-widget-update.

Cursor

print_widget skills --tool=cursor --install

Skills installed to .cursor/rules/ as .mdc rule files. Cursor auto-loads them when editing matching files.

Codex

print_widget skills --tool=codex --install

Skills installed to .agents/skills/ (project) or ~/.agents/skills/ (user) as SKILL.md files.

Antigravity

print_widget skills --tool=antigravity --install

Skills installed to .agent/skills/ (project) or ~/.gemini/antigravity/skills/ (user) as SKILL.md files. Antigravity auto-detects skills via semantic triggering.

Auto-detect

If you skip --tool, print_widget auto-detects which tools are installed and installs for all of them:

print_widget skills --install    # auto-detect + install all

AI Assistant Onboarding

If you are an AI assistant (Claude Code, Cursor, Codex) setting up print_widget in a Flutter project, follow this complete onboarding flow:

Step 1: Install the CLI globally

dart pub global activate --source git https://github.com/ulisseshen/print_widget.git

Do NOT add print_widget to the project's pubspec.yaml. It is a CLI tool, not a library dependency.

Step 2: Run init and follow the onboarding output

cd <flutter_project>
print_widget init

The init command creates all needed files and prints onboarding instructions specifically for you. Read and follow them — they guide you through:

• Editing the config file with the project's theme and widgets
• Running print_widget generate
• Installing AI skills (auto-installed during init; or manually with print_widget skills --install)
• Detecting VS Code/Cursor and offering to install the preview extension

Step 3: Read the compact reference

print_widget --llm-guide

This prints a condensed guide with project-specific paths, all CLI commands, entry types, device list, and the VS Code extension install instructions.

Step 4: Add widgets to capture

Edit the config file (path shown in init output) and add the project's widgets:

final printList = <PrintEntry>[
  page('login_page', const LoginPage()),
  widget('product_card', ProductCard(data: mock), size: Size(350, 420)),
];

Step 5: Generate and verify

print_widget generate

Read manifest.json in the output directory to find generated PNG paths. Read the PNGs to visually verify your UI work. Iterate until the screenshots match the design.

What happens after onboarding

Once set up, you can:

• /print-widget-figma <figma-url> — convert a Figma design to Flutter with screenshot comparison loop
• /print-widget-stitch <description> — generate a UI design with Stitch, then implement and compare
• print_widget generate --name=<entry> — regenerate a single screenshot after code changes
• print_widget generate --all-devices — test responsive layouts across iPhone, Pixel, iPad
• Compare screenshots with design references in the VS Code extension sidebar

CLI commands

print_widget init                        # Set up project (auto-installs skills)
print_widget generate                    # Generate all screenshots
print_widget generate --name=login_page  # Generate one entry only
print_widget generate --device=pixel_7   # Override device (preset name)
print_widget generate --device=1440x900  # Override device (custom size)
print_widget generate --device=web:1440x900@2  # Custom name, size, pixel ratio
print_widget generate --all-devices      # All popular devices
print_widget generate --delete-old       # Clean regenerate
print_widget generate --json             # Structured JSON output
print_widget list                        # Show configured entries
print_widget config                      # View settings
print_widget config --device=pixel_7     # Change default device
print_widget diagnose                    # Analyze widget constructors for mock data
print_widget diagnose --name=login_page  # Diagnose a specific widget
print_widget skills --install            # Install all AI skills (figma + stitch)
print_widget skills --only=figma         # Install a specific skill
print_widget skills --only=stitch        # Install a specific skill
print_widget skills --update             # Update installed skills to latest version
print_widget skills --list               # List available skills
print_widget --llm-guide                 # Print LLM reference

The --name flag is useful when iterating on a single widget. Instead of regenerating all screenshots, target just the one you changed:

print_widget generate --name=product_card

Skills

The skills command installs AI assistant skill files for Claude Code, Cursor, and Codex. Two skills are available:

Skill	What it does
figma	Convert Figma designs to Flutter with screenshot comparison loop (/print-widget-figma)
stitch	Generate UI with Google Stitch, implement in Flutter, compare (/print-widget-stitch)
update	Update print_widget CLI and skill files to the latest version (/print-widget-update)

print_widget skills --install          # Install all skills (figma + stitch + update)
print_widget skills --only=figma       # Install only figma
print_widget skills --only=update      # Install only update
print_widget skills --update           # Update all installed skills to latest

Skills are auto-installed during print_widget init. In monorepos, skills are installed at the git root so they are visible to AI tools across the repository.

Each skill bundles internal reference files that the AI reads automatically:

Reference	What it teaches
conventions.md	Widget structure, behavioral rules (IntrinsicHeight, scoped fixes, no guessing)
screen.md	Screen patterns, provider tracing, DS customization, toggle state capture
review.md	Layer-by-layer verification checklist (30+ checkpoints)
iterate.md	Systematic checklist-driven iteration loop

After installation, you can edit these files to add project-specific tokens, component libraries, and team conventions.

Skill workflow

Figma design → Extract colors/padding → Map to DS tokens → Build widget
    → Generate screenshot → Verify layer-by-layer (review checklist)
    → Fix ALL differences → Regenerate → Repeat until 100% match

The skill teaches the AI to:

1. Extract ALL colors and padding BEFORE writing code
2. Map every Figma token to a project DS token (never hardcoded Color())
3. Verify screenshots section-by-section (backgrounds → text → padding → borders → icons → typography)
4. Fix all differences in one batch, then regenerate once
5. Save novel patterns to CLAUDE.md for future sessions

Entry types

There are 4 entry functions for adding items to printList:

Function	What it does	Use for
page('name', Widget())	Renders as full-screen home: of the app wrapper	Screens, routes, full pages
widget('name', Widget(), size: Size(w, h))	Centers widget in Scaffold > Center > SizedBox	Components, cards, buttons
pages('name', states: [...])	Multiple full-screen states of the same page	Login empty/error/filled
widgets('name', states: [...], size: Size(w, h))	Multiple states of the same component	Button active/disabled/loading

Page vs Widget

	page()	widget()
Layout	Full screen (fills device frame)	Centered in Scaffold
Use for	Screens, routes, full pages	Components, cards, buttons
Custom size	Uses device frame size	Optional size: constrains widget
Scroll capture	scrollExtent: 3000 for tall pages	scrollExtent: works too
Tab/state control	setup: callback to tap tabs	setup: callback works too
Provider injection	appWrapper: per entry	appWrapper: per entry

Widget size vs device frame

When you use widget() with a size: parameter, the size controls the SizedBox constraints around your widget inside the device frame. The widget is centered in a Scaffold. The screenshot is always the full device frame size.

// DeviceFrame is 1440x900. Widget gets 1100x280 constraints, centered in the 1440x900 viewport.
widget('hero_banner', HeroBanner(), size: Size(1100, 280),
  devices: [DeviceFrame.web1440]),

This means:

• The device frame sets the overall viewport and screenshot dimensions
• The size parameter constrains and centers the widget within that viewport
• If size is omitted, the widget fills the entire scaffold (useful for full-width components)
• The output PNG is always the full device frame size, with the widget centered inside

Grouped states

Capture multiple visual states of the same component:

pages('sign_in_screen', states: [
  state('empty', SignInScreen()),
  state('error', SignInScreen(initialError: 'Invalid email')),
  state('filled', SignInScreen(initialEmail: '[e-mail]')),
])

Output naming via StateOutputMode:

Mode	File path
prefix (default)	sign_in_screen/empty_iphone_15_pro.png
suffix	sign_in_screen/iphone_15_pro_empty.png
folder	sign_in_screen/empty/iphone_15_pro.png

Devices

Mobile & tablet presets

DeviceFrame.iPhone15Pro   // 393x852 @3x
DeviceFrame.pixel7        // 412x915 @2.625x
DeviceFrame.iPadPro11     // 834x1194 @2x
DeviceFrame.popular       // [iPhone15Pro, pixel7, iPadPro11]
DeviceFrame.allPhones     // 8 phone devices
DeviceFrame.allTablets    // 4 tablet devices

Web & desktop presets

DeviceFrame.web1366       // 1366x768 @1x  — most common laptop
DeviceFrame.web1440       // 1440x900 @1x  — common desktop
DeviceFrame.web1920       // 1920x1080 @1x — Full HD
DeviceFrame.desktop1440p  // 2560x1440 @2x — QHD / 1440p
DeviceFrame.allWeb        // [web1366, web1440, web1920, desktop1440p]

Use web presets for responsive layout testing:

page('dashboard', DashboardPage(), devices: DeviceFrame.allWeb),

Custom device sizes

Create any device size in Dart:

const myDevice = DeviceFrame(
  name: 'ultrawide',
  size: Size(3440, 1440),
  pixelRatio: 2.0,
);

page('dashboard', DashboardPage(), devices: [myDevice]),

Or use custom sizes directly from the CLI without touching Dart code:

# Just dimensions (name defaults to "custom", pixel ratio to 1x)
print_widget generate --device=1440x900

# With a custom name
print_widget generate --device=my_monitor:1440x900

# With name and pixel ratio
print_widget generate --device=retina:1440x900@2

Font loading

Fonts load automatically. When print_widget init sets up your project, it creates a flutter_test_config.dart that calls loadPrintWidgetFonts(). This single call handles everything:

1. Bundled Roboto + MaterialIcons -- always available, no setup needed
2. google_fonts variant auto-detection -- when the google_fonts package is detected, registers variant names automatically (Roboto_regular, Roboto_bold, etc.)
3. google_fonts/ directory auto-scan -- loads all .ttf/.otf files from the google_fonts/ directory at your project root (auto-created if declared in pubspec.yaml assets but missing on disk)
4. Your project fonts -- auto-detected from pubspec.yaml font declarations
5. Package font auto-detection -- scans ALL dependency packages for font declarations in their pubspec.yaml (catches design system packages that bundle custom fonts -- no manual loadPackageFonts() needed)
6. Fallback directory scan -- checks assets/fonts/, assets/font/, fonts/ for font files not declared in pubspec
7. CLI output summary -- prints a summary of all loaded font registrations and warnings for missing ones

You will see real text in screenshots, not Ahem black rectangles.

loadFonts callback

If auto-detection cannot find your fonts (e.g., non-standard paths or dynamic font loading), use the loadFonts callback on PrintSession:

final printSession = PrintSession(
  appWrapper: (child) => MaterialApp(home: child),
  loadFonts: () async {
    await loadCustomFonts({
      'BrandFont': ['assets/fonts/BrandFont-Regular.ttf'],
      'BrandFont': ['assets/fonts/BrandFont-Bold.ttf'],
    });
  },
);

Custom fonts (manual)

You can also load fonts directly in flutter_test_config.dart:

import 'package:print_widget_flutter/print_widget.dart';

Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  await loadPrintWidgetFonts();       // bundled + all auto-detected fonts
  await loadCustomFonts({             // additional custom fonts
    'BrandFont': ['assets/fonts/BrandFont-Regular.ttf'],
    'BrandFont': ['assets/fonts/BrandFont-Bold.ttf'],
  });
  return testMain();
}

Package fonts (manual)

Load fonts from a specific dependency package (usually not needed -- auto-detection handles this):

await loadPackageFonts('my_design_system');

Actionable error hints

When print_widget generate encounters common issues, it prints actionable hints instead of raw stacktraces:

• Overflow -- suggests increasing widget size or using larger device frame
• Missing fonts -- lists auto-detection sources and loadFonts callback example
• Network images -- suggests local assets, errorWidget, or image provider mocks
• AnimatedDefaultTextStyle -- suggests DefaultTextStyle or TweenAnimationBuilder
• Missing MediaQuery -- suggests wrapping with MaterialApp in appWrapper
• Multiple missing fonts -- "Fix ALL at once" workflow instead of one-by-one

Advanced features

Setup callback (interact before capture)

Tap tabs, enter text, open dialogs, or trigger any UI state before the screenshot:

page('orders_tab', OrdersScreen(),
  setup: (tester) async {
    await tester.tap(find.text('Orders'));
    await tester.pumpAndSettle();
  },
)

Works on both entries and individual states:

pages('settings', states: [
  state('general', SettingsScreen()),
  state('notifications', SettingsScreen(),
    setup: (tester) async {
      await tester.tap(find.text('Notifications'));
      await tester.pumpAndSettle();
    },
  ),
])

Scroll capture

Capture pages taller than one viewport:

// Capture the full scrollable extent (output PNG will be 1440x3000)
page('long_page', LongPage(), scrollExtent: 3000, devices: [DeviceFrame.web1440])

// Scroll to a specific offset before capturing
page('page_bottom', LongPage(), scrollTo: 1500)

Per-entry provider injection

Override the session-level appWrapper for entries that need different providers:

page('admin_dashboard', AdminDashboard(),
  appWrapper: (child) => MultiProvider(
    providers: [
      ChangeNotifierProvider.value(value: mockAdminProvider),
      ChangeNotifierProvider.value(value: mockOrdersProvider),
    ],
    child: MaterialApp(home: child),
  ),
  devices: [DeviceFrame.web1440],
)

Widget diagnostics

Analyze widget constructors to find what mock data you need:

print_widget diagnose
print_widget diagnose --name=smart_summary

JSON output

Get structured output for programmatic consumption:

print_widget generate --json

Manifest

Generated manifest.json for LLM consumption:

{
  "generatedAt": "2026-02-13T15:00:00Z",
  "screenshots": [
    {
      "name": "login_page",
      "type": "page",
      "file": "test/prints/output/login_page/iphone_15_pro.png",
      "device": "iphone_15_pro",
      "width": 393.0,
      "height": 852.0
    }
  ]
}

LLM workflow

1. LLM implements LoginPage
2. LLM adds to printList: page('login_page', LoginPage())
3. LLM runs: print_widget generate --name=login_page
4. LLM reads manifest.json → finds PNG → views screenshot
5. LLM compares with design → iterates until it matches

Works great with MCP tools

print_widget is designed to work with AI design tools via MCP (Model Context Protocol):

Figma MCP

Autonomous design-match loop — fetch a Figma frame, implement the Flutter widget, generate a screenshot, compare pixels, fix differences, repeat until it matches.

AI fetches Figma design → builds widget → print_widget generate → compare → iterate

Reference images from Figma are saved to .reference/ for automatic comparison in the VS Code extension.

• Figma MCP Server

Stitch (Google AI UI)

Generate UI screens with Stitch, then verify the Flutter implementation matches with print_widget screenshots. Stitch creates design screens from text prompts or code, and print_widget captures what the Flutter code actually renders — compare both to ensure pixel-perfect implementation.

Stitch generates design → AI implements in Flutter → print_widget generate → compare

• Stitch MCP Setup

VS Code Extension

Preview and compare screenshots directly in VS Code.

• Sidebar tree view grouped by feature, state, and device
• Multi-device comparison grid
• Before/after diff with slider overlay
• Design reference comparison with similarity percentage (auto-detects .reference/ images)

Requires Node.js 18+ to build from source:

cd extensions/vscode && npm install && npm run build && npx @vscode/vsce package
code --install-extension print-widget-preview-*.vsix

See extensions/vscode/README.md for full installation instructions (macOS, Linux, Windows).

Docs

• Architecture
• Standalone test API