Flutter Design Grid 🚀

A powerful, Figma-like design grid and image overlay for Flutter applications. Perfect for aligning widgets, checking margins, and ensuring pixel-perfect implementation by comparing your app directly with design mocks.

What's New in v2.0.1 ✨

• 🖼️ Image Overlay: Overlay your Figma design screenshots directly on your app.
• 🖐️ Interactive Viewer: Pan, zoom, and nudge your design image for perfect alignment.
• ✂️ Image Sectioning: Support for long designs by selecting specific sections to display.
• 🔘 Enhanced Toggle Button: A polished sliding UI to switch between Grid, Image, and Off.
• 🛡️ Conditional Overlay: Safety first! Automatically disables the grid in production builds.
• ⌨️ Keyboard Shortcuts: Press 'G' to cycle through overlay modes instantly.

Features

• 🎯 Pixel-Perfect Alignment: Traditional grid overlay with customizable sizing.
• 🎨 Fully Customizable: Adjust grid size, colors, stroke widths, and opacity.
• 🔧 Multiple Presets: Quick-start with baseline8, micro4, layout24, and more.
• 📱 Multi-Platform: Works seamlessly on iOS, Android, Web, and Desktop.
• 🎮 Developer Friendly: Zero dependencies beyond Flutter and easy extension methods.

Installation

Add flutter_design_grid to your pubspec.yaml:

dependencies:
  flutter_design_grid: ^2.0.1

Quick Start (The "Safe" Way)

The recommended way is to use withConditionalDesignGrid. This ensures the overlay only appears in debug mode and is completely removed from your production app.

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

void main() {
  runApp(
    const MyApp().withConditionalDesignGrid(
      config: GridConfig(
        imageAssetPath: 'assets/designs/home_screen.png', // Optional Figma design
        gridSize: 8.0,
      ),
    ),
  );
}

Core Concepts

1. Grid Overlay

A traditional layout grid to check for spacing, margins, and alignment.

• Keyboard Shortcut: Press G once to enable the grid.

2. Image Overlay

Overlay a design image (e.g., a .png export from Figma) with adjustable opacity.

• Keyboard Shortcut: Press G again to switch to Image mode.
• Interactive: You can pan the image if it doesn't align perfectly out of the box.

Advanced Usage

Working with Long Designs

If your Figma design is very long (e.g., a scrolling page), use imageSection to focus on a specific area:

GridConfig.forImageSection(
  'assets/long_design.png',
  startY: 800,   // Skip the header
  height: 812,   // Show one screen's worth of content
  opacity: 0.6,
)

Manual Fine-Tuning

Sometimes you need to nudge the design image by a few pixels:

GridConfig(
  imageAssetPath: 'assets/design.png',
  imageOffset: Offset(0, 10), // Move down 10px
  imageScale: 1.1,            // Scale up slightly
  imageFitMode: ImageFitMode.fitWidth,
)

Extension Methods

The package provides clean extensions to wrap any widget:

// Wrap just a specific page
return MySettingsPage().withDesignGridControls(
  config: GridConfig.baseline8,
);

// Wrap the whole app
return MaterialApp(...).withConditionalDesignGrid();

Configuration Options (GridConfig)

Property	Description	Default
gridSize	Size of each grid cell	20.0
gridColor	Color of the grid lines	Color(0x40FF0000)
imageAssetPath	Path to your design image	null
imageOpacity	Opacity of the image overlay	0.5
imageScale	Scaling factor for the image	1.0
imageFitMode	How the image fits the screen	ImageFitMode.cover
showMajorLines	Whether to highlight every Nth line	true

Keyboard Shortcuts

While the app is running in debug mode:

• G: Cycles through Off ➡️ Grid ➡️ Image Overlay ➡️ Off.

---

Contributing & Feedback

Issues and Pull Requests are welcome on the GitLab repository.

Built with ❤️ for the Flutter community.