Flutter UI Kit

A feature-rich Flutter UI kit built to speed up app development with Material 3 theming, reusable widgets, shimmer loaders, SVG icons, unified image handling, navigation helpers, responsive layout utilities, glass surfaces, product tours, and full light/dark theme support. All public APIs are exported through package:vvk_ui_kit/vvk_ui_kit.dart.

See doc/IMPLEMENTATION_GUIDE.md for integration patterns, composition conventions, and migration notes.

Preview

Theming (light & dark)	Components	Glass surfaces

Features

Theming — UIAppTheme with semantic color tokens (UIThemePalette, UIThemeExtension, UIMetrics) and built-in light/dark presets (teal, zinc, slate, stone). Includes easy-to-use typography and shadow presets.
Animation — UITapGuard for debouncing taps, UIAvatarGlow, AnimatedGestureDetector, and staggered entrance animations for lists and grids.
Buttons — UIStyledButton with variants, plus primary/elevated/icon/image buttons, UIGradientButton, UISliderButton, UISplitButton, UIGlassButton, and UISocialAuthButton.
Accordion, cards & clips — expansion accordions, UICard, UIAnimatedFlipCard, UIHexagon, UISharpCorners, UITicketClip, UICouponClip, UICouponCard.
Carousel — UICarouselWithIndicator, UISectionCarousel, UICarouselControls, nav buttons, and page indicators.
Decoration & glass — gradient widgets, dotted borders, corner ribbons, and frosted UIGlassSurface / UIGlassCard / UIGlassScaffold family.
Display & rating — stat cards, banners, progress bars, UICommandBar, UIAnimatedCounter, UITextAvatar, UIStackBadge, UITimerBuilder, UIBatteryIndicator, and UIRatingBar.
Dialogs — shell dialogs, adaptive alert/action sheets, Cupertino sheets, image picker, and bottom sheets.
Feedback — snackbars, badges, empty states, tooltips, UIPopover, and guided UITourController with spotlight overlay.
Forms & inputs — form fields, UIForm, dropdowns, searchable hierarchy dropdowns, UISearchBar, UITagInput, UINumberField, UIColorPicker, OTP, sliders, calendar/date/time pickers, and settings tiles.
Layout & responsive — dividers, separated rows/columns, UIPageScaffold, UIExpandableFloatingPanel, UIDynamicOverflow, keyboard dismiss area, UIPortal for overlays, and Responsive helpers.
Lists — UISwipeActionTile with custom drag actions.
Loading — shimmer containers, overlays, page loading, and load-more helpers.
Media — UIImage for assets, network, SVG, and base64 via UIImageScope. Includes image preview frames.
Navigation — app bars, side menu, bottom bars (UIBottomNavyBar, UIFloatingBottomBar, UIGlassBottomNavBar), UIMenuBar, UITreeView, settings scaffolds, breadcrumbs, and double-back-to-exit.
Selection & states — list tile select, pill switch, rounded checkbox, radio groups, error states.
Tabs — UITabBar, UISegmentedTabBar, UIButtonsTab.
Text & icons — UIText, rich/read-more/marquee text, SVG rendering, social auth icons, and text row helpers.
Utilities — NavigationUtil, DialogUtil, DateTimeUtil, JsonUtils, JsonHelper, Mapper, Translations, TranslationCache, and Dart extensions.

Getting started

Example app

Browse every widget and utility in the interactive catalog:

cd example
flutter run

Showcase sections: Core utilities, Buttons, Animation, Accordion/cards/clips, Carousel, Decoration, Display, Rating, Dialogs, Feedback, Inputs, Layout & responsive, Loading, Media, Navigation, Selection & states, Tabs, and Text & icons.

Installation

dependencies:
  vvk_ui_kit: ^1.1.0

Theme setup

import 'package:vvk_ui_kit/vvk_ui_kit.dart';

MaterialApp(
  theme: UIAppTheme.light,
  darkTheme: UIAppTheme.dark,
  themeMode: ThemeMode.system,
  home: const HomeScreen(),
)

Use UIAppTheme.custom when you need a custom UIThemeColors palette while keeping kit component styling.

Seed a theme from one color

Generate a full Material 3 palette from a single brand color:

MaterialApp(
  theme: UIAppTheme.fromSeed(const Color(0xFF6750A4)),
  darkTheme: UIAppTheme.fromSeed(
    const Color(0xFF6750A4),
    brightness: Brightness.dark,
  ),
)

High-contrast accessibility themes

Honor the OS "increase contrast" setting with the built-in high-contrast presets:

final highContrast = MediaQuery.of(context).highContrast;
MaterialApp(
  theme: highContrast ? UIAppTheme.highContrast(Brightness.light) : UIAppTheme.light,
  darkTheme: highContrast ? UIAppTheme.highContrast(Brightness.dark) : UIAppTheme.dark,
)

Image scope (optional)

Wrap your app with UIImageScope for custom network/SVG builders (cached_network_image, flutter_svg, etc.). Without it, UIImage uses Flutter's built-in network loader and the kit's lightweight UISvgImage renderer.

Usage examples

Buttons

UIStyledButton(
  style: UIStyledButtonStyle.primary(context),
  onPressed: () {},
  child: const Text('Get Started'),
)

UISplitButton.fromTheme(
  context,
  label: 'Save',
  onPressed: save,
  menuItems: [UISplitButtonMenuItem(label: 'Discard', onTap: discard)],
)

Glass surfaces

UIGlassCard.fromTheme(
  context,
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('Frosted card'),
  ),
)

UIGlassScaffold(
  appBar: UIGlassAppBar(title: const Text('Glassy App')),
  body: Center(child: UIImage('...')),
)

Animation & Feedback

UITapGuard(
  onTap: () => print('Throttled tap'),
  child: UIStyledButton(
    style: UIStyledButtonStyle.primary(context),
    onPressed: () {},
    child: const Text('Click Me'),
  ),
)

UIAvatarGlow(
  child: const CircleAvatar(child: Icon(Icons.person)),
)

Product tour

final tour = UITourController(
  steps: [
    UITourStep(
      targetKey: _fabKey,
      title: 'Quick actions',
      description: 'Tap here to create a new item.',
    ),
  ],
);

Forms

UIForm(
  child: Column(
    children: [
      UIFormTextField(name: 'email', label: 'Email'),
      UISearchBar.fromTheme(context, hintText: 'Search…', onChanged: filter),
      UIFormCheckboxField(name: 'terms', label: 'Accept terms'),
    ],
  ),
)

NavigationUtil.pushPage(context, const ProfileScreen());

Testing

The package includes a comprehensive widget test suite. Run all tests from the package root:

flutter test

Tests are organized under test/ by category — buttons, inputs, dialogs, feedback, glass, navigation, loading, media, and more — mirroring the public widget groups in lib/vvk_ui_kit.dart. As of 1.1.0, the suite covers 326 tests across 32 test files.

Component overview

Category	Key components
Theming	`UIAppTheme`, `UIThemePalette`, `UIThemeExtension`, `UIMetrics`, `UITypography`
Animation	`UITapGuard`, `UIAvatarGlow`, `AnimatedGestureDetector`, `UIEntranceAnimation`
Buttons	`UIStyledButton`, `UISplitButton`, `UIGlassButton`, `UISocialAuthButton`, `UISliderButton`
Cards & clips	`UICard`, `UIAnimatedFlipCard`, `UICouponCard`, `UITicketClip`, `UIHexagon`
Glass	`UIGlassSurface`, `UIGlassCard`, `UIGlassScaffold`, `UIGlassAppBar`, `UIGlassBottomNavBar`
Display & rating	`UICommandBar`, `UIAnimatedCounter`, `UIRatingBar`, `UITextAvatar`, `UIBatteryIndicator`
Feedback	`UITourController`, `UIPopover`, `UIBadge`, `UISkeletonPlaceholder`, `UISnackbar`
Dialogs	`showUIAdaptiveAlertDialog`, `showUIAdaptiveActionSheet`, `showUISheet`, `UIShellDialog`
Inputs	`UISearchBar`, `UITagInput`, `UINumberField`, `UIColorPicker`, `UIForm`, `UIInputOTP`
Layout	`UIPageScaffold`, `UISeparatedRow`, `UIExpandableFloatingPanel`, `UIPortal`, `UIDynamicOverflow`
Navigation	`UIBottomNavyBar`, `UIMenuBar`, `UITreeView`, `UIDoubleBackToExit`, `UIFloatingBottomBar`
Media	`UIImage`, `UIImageScope`, `UIImagePreviewFrame`, `UISvgImage`
Lists	`UISwipeActionTile`
Utilities	`NavigationUtil`, `JsonUtils`, `JsonHelper`, `Mapper`, `Translations`, `DateTimeUtil`

Public API

All public symbols are exported from package:vvk_ui_kit/vvk_ui_kit.dart. Internal helpers under lib/src/ are not part of the stable API.

Modular imports

Import only what you need:

Entry point	Contents
`package:vvk_ui_kit/vvk_ui_kit.dart`	Full barrel (default)
`package:vvk_ui_kit/theme.dart`	`UIAppTheme`, palettes, typography, shadows
`package:vvk_ui_kit/buttons.dart`	Button family + `UIGlassButton`
`package:vvk_ui_kit/inputs.dart`	Forms, fields, pickers, selection inputs
`package:vvk_ui_kit/layout.dart`	Scaffolds, dividers, responsive, spacing
`package:vvk_ui_kit/dialogs.dart`	Dialogs, sheets, adaptive alerts
`package:vvk_ui_kit/feedback.dart`	Snackbars, badges, tours, loading/shimmer
`package:vvk_ui_kit/navigation.dart`	App bars, bottom bars, tabs, menus
`package:vvk_ui_kit/media.dart`	`UIImage`, SVG icons, image scope
`package:vvk_ui_kit/widgets.dart`	Cards, carousel, display, glass, text, rating
`package:vvk_ui_kit/core.dart`	Extensions, JSON/navigation/translation utils

See doc/IMPLEMENTATION_GUIDE.md for detailed integration guidance and doc/MIGRATION.md for upgrade notes.

License

This project is licensed under the MIT License — see the LICENSE file for details.