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 config --compare-threshold=0.98  # Tune compare gate
print_widget compare                     # Diff generated vs reference (pixelmatch)
print_widget compare --name=login_page   # Diff one entry
print_widget compare --threshold=0.98    # Override per-region threshold
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 --only=extract       # Install the smart-extract-design 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 the AI assistant skill for Claude Code, Cursor, Codex, and Antigravity. One unified skill with subcommands:

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

print_widget skills --install          # Install the print-widget skill
print_widget skills --update           # Update installed skill to latest version

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, mandatory DS component discovery
`screen.md`	Screen patterns, provider tracing, DS customization, toggle state capture
`review.md`	Layer-by-layer verification checklist (30+ checkpoints)
`iterate.md`	Autonomous iteration loop — 3-tier stop conditions, revert-on-regression, escalation
`compare.md`	How to use `print_widget compare` and read pixelmatch heatmaps
`viewport.md`	Phase 0 viewport contract — critical for web references
`lovable.md`	Adapter for Lovable.dev URLs via smart-extract handoff

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

Skill workflow

Figma/Lovable design → Pin viewport → Extract tokens → Map to DS tokens → Build widget
    → print_widget generate → print_widget compare (pixelmatch per region)
    → Fix ALL differences → Regenerate → Re-compare
    → Revert on regression → Loop until converged or hard cap → Escalation report

The skill teaches the AI to:

Pin the viewport on both sides before writing any code (fails fast if mismatched)
Extract ALL colors and padding BEFORE writing code; map each to a DS token
Discover existing DS components before creating new ones (grep mandatory)
Run print_widget compare for an objective per-region stop condition
Back up files before editing; revert if any region's score drops
Never infer icons/colors/components from semantic names — always observe
Escalate with a residual-diff report on hard cap instead of silently accepting

`print_widget compare` — the objective stop condition

compare runs pixelmatch (via Node) on each generated crop against its reference crop, writes per-region heatmap PNGs, and returns exit 0 (converged) or exit 1 (regions below threshold). This is what lets the iteration loop decide "done" without guessing.

# one-time setup (in your Flutter project root)
npm install pixelmatch pngjs

# then, after generating:
print_widget compare --name=<entry>
# ✓ header: 99.12%
# ✗ cards:  82.41%  (below 95%)
#     heatmap: print_widget/output/<entry>/crops/cards_diff.png

Configure defaults in print_widget.yaml:

reference_dir: .reference
compare_threshold: 0.95

Crops — per-region comparison at native resolution

Add named regions to a PrintEntry so that generate produces matched crops and compare diffs them individually:

page('dashboard', DashboardPage(),
  crops: {
    'header': Rect.fromLTWH(0, 0, 1440, 80),
    'cards':  Rect.fromLTWH(60, 80, 1320, 350),
    'table':  Rect.fromLTWH(60, 440, 1320, 400),
  },
)

Or point at a JSON file produced by the smart-extract-design skill:

page('dashboard', DashboardPage(),
  cropsFrom: 'print_widget/output/dashboard/.reference/_index.json',
)

Reference crops live at print_widget/output/<entry>/.reference/crops/*.png (ignored by git by default; see the commented-out .gitignore line to opt into committing them for review).

Lovable.dev workflow

Install the extract skill alongside the main skill:

print_widget skills --only=extract

Then give the AI a Lovable URL and it runs:

smart-extract-design captures the live page via Playwright — full-page PNG, section crops (auto-detected via DOM bounding boxes), raw tokens mapped to your theme
Crops land in print_widget/output/<feature>/.reference/ automatically
The AI implements the Flutter widget with the Token Bundle
print_widget generate + print_widget compare drive the iteration loop
Loop exits on convergence or hits the 15-iteration cap with an escalation report

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: 'user@test.com')),
])

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:

Bundled Roboto + MaterialIcons -- always available, no setup needed
google_fonts variant auto-detection -- when the google_fonts package is detected, registers variant names automatically (Roboto_regular, Roboto_bold, etc.)
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)
Your project fonts -- auto-detected from pubspec.yaml font declarations
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)
Fallback directory scan -- checks assets/fonts/, assets/font/, fonts/ for font files not declared in pubspec
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).

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
.agents/skills		.agents/skills
.claude/skills		.claude/skills
.github/workflows		.github/workflows
.planning		.planning
bin		bin
doc		doc
example		example
extensions		extensions
lib		lib
test		test
.gitignore		.gitignore
.pubignore		.pubignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
package.json		package.json
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation

print_widget

Screenshots

What it does

Two things in one

Quick start

1. Install CLI (once)

2. Set up your project

3. Edit the config

4. Generate

Set up with your AI tool

Claude Code

Cursor

Codex

Antigravity

Auto-detect

AI Assistant Onboarding

Step 1: Install the CLI globally

Step 2: Run init and follow the onboarding output

Step 3: Read the compact reference

Step 4: Add widgets to capture

Step 5: Generate and verify

What happens after onboarding

CLI commands

Skills

Skill workflow

print_widget compare — the objective stop condition

Crops — per-region comparison at native resolution

Lovable.dev workflow

Entry types

Page vs Widget

Widget size vs device frame

Grouped states

Devices

Mobile & tablet presets

Web & desktop presets

Custom device sizes

Font loading

loadFonts callback

Custom fonts (manual)

Package fonts (manual)

Actionable error hints

Advanced features

Setup callback (interact before capture)

Scroll capture

Per-entry provider injection

Widget diagnostics

JSON output

Manifest

LLM workflow

Works great with MCP tools

Figma MCP

Stitch (Google AI UI)

VS Code Extension

Docs

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`print_widget compare` — the objective stop condition

Packages