mega_ui_kit 0.0.13

Flutter UI kit with themeable semantic colors (MegaColorScheme), design tokens, and Mega-aligned widgets. Brand colors are provided by your app — see example.

MegaUIKit

A Flutter UI kit with design tokens, themeable semantic colors, and base widgets aligned with the Mega Figma UI kit.

MegaUIKit does not ship a fixed brand palette. You provide a MegaColorScheme for light and dark; the example app includes the official Mega brand as a reference.

Preview

Screenshots from the example app (dark theme).

Buttons & inputs	List tiles

Dropdown	Dividers & progress

Features

• Semantic theming — MegaColorScheme + MegaTheme.light(colors:) / dark(colors:)
• No light/dark suffixes in widgets — use context.megaColors.secondary; the active theme picks the value
• Design tokens — typography, spacing, radii, shadows, blurs
• Widgets — buttons, list tiles, dropdowns, snack bars, app bars, and more (see Widgets)

Installation

Add to pubspec.yaml:

dependencies:
  mega_ui_kit: ^0.0.13

flutter pub get

Requirements: Dart >=3.0.0, Flutter >=3.10.0.

Quick start

1. Define semantic colors

Each MegaColorScheme describes one brightness (light or dark). Copy the reference implementation from the example:

• example/lib/theme/mega_brand_colors.dart — ready-made MegaBrandColors.light / .dark
• example/lib/theme/mega_palette.dart — optional raw hex palette used to build the schemes

Minimal shape (all fields are required):

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

const myLightColors = MegaColorScheme(
  primary: Color(0xFF33CC67),
  onPrimary: Color(0xFFFCFCFD),
  secondary: Color(0xFF242F47),
  onSecondary: Color(0xFFFCFCFD),
  // …primary, secondary, disabled, surface, success, error, system, component tokens
);

const myDarkColors = MegaColorScheme(
  primary: Color(0xFF33CC67),
  secondary: Color(0xFFE3E8EF),
  // …same token names, different hex values where needed
);

2. Apply MegaTheme

MaterialApp(
  theme: MegaTheme.light(colors: myLightColors),
  darkTheme: MegaTheme.dark(colors: myDarkColors),
  themeMode: ThemeMode.system,
  home: const HomePage(),
);

MegaTheme registers MegaColorScheme as a ThemeExtension and maps core roles into Flutter’s ColorScheme (primary, secondary, surface, error, …).

3. Read colors in widgets

Widget build(BuildContext context) {
  final colors = context.megaColors;

  return Container(
    color: colors.surface,
    child: Text(
      'Hello',
      style: MegaTypography.bodyMdRegular.copyWith(color: colors.onSurface),
    ),
  );
}

Use package widgets (MegaButton, MegaListTile, …) — they already resolve tokens from context.megaColors.

Example app

The example/ project has two entry points:

Command	Entry	Description
flutter run	example/lib/main.dart	pub.dev example — theme wiring, color previews, buttons, snack bar
flutter run -t lib/kitchen_sink_main.dart	example/lib/kitchen_sink_main.dart	Full gallery (colors, typography, every widget tab)

git clone <repo>
cd mega_ui_kit/example
flutter pub get
flutter run

See example/README.md for integration notes.

Theming model

Why two schemes?

Light and dark surfaces need different contrast. Instead of secondaryLight / secondaryDark in code, you pass two flat schemes:

MegaTheme.light(colors: MegaBrandColors.light),  // secondary = #242F47
MegaTheme.dark(colors: MegaBrandColors.dark),    // secondary = #E3E8EF

Widgets call context.megaColors.secondary — no Brightness branches.

Token groups in MegaColorScheme

Group	Examples	Usage
Primary	primary, hoveredPrimary, primaryContainer, onPrimary, …	CTAs, brand actions
Secondary	secondary, hoveredSecondary, secondaryContainer, onSecondary, …	Secondary buttons, strokes
Disabled	disabled, onDisabled, hoveredDisabled, …	Inactive controls
Surface	surfaceLow, surface, surfaceHigh, onSurface, divider, …	Backgrounds, text, borders
Success / Error	success, error, *Container, on*, …	Status, destructive actions
System	systemOrange, systemIndigo, …	Badges, accents
Component	listTileHighlight, switchInactiveTrack, snackSuccessFill, …	Widget-specific fills

Aliases on the scheme: surfaceVariant → surfaceHigh, onBackground → onSurface, disabledBackground → disabled.

Raw palette (optional)

Keep brand hex values in your app (see example/lib/theme/mega_palette.dart). Map them once into MegaColorScheme; widgets only see semantic names.

Widgets

Widget	Description
MegaButton	Primary / secondary / error variants, sizes, loading, icons
MegaAppBar	Title, back, trailing, bottom
MegaListTile	Leading, subtitle, badges, selection fill
MegaDropdown, MegaDropdownFormField	Overlay FAQ, bottom sheet, full-page selection with optional search and form validation
MegaBottomSheet	Modal sheet with header, footer actions
MegaSnackBar	Top overlay: success, info, error
MegaSwitch, MegaCheckbox	Toggles aligned with Figma
MegaTextField, MegaTextFormField	Floating label, ghost hint, input templates, form validation
MegaSearchField	Compact search input (40 dp, clear + optional cancel)
MegaTextScroll	Horizontally scrolling title text (app bar, long labels)
MegaCards	Card presets: icon, service, text, featured
MegaDivider	Solid / dashed, horizontal / vertical
MegaLinearProgressIndicator, MegaCircularProgressIndicator	Determinate progress
MegaStepBars	Multi-step flow
MegaBadge, MegaBadgeBase	Status and corner badges
MegaAvatar, MegaCard, MegaChip, MegaDialog	Display / layout (some WIP)

MegaButton

MegaButton.primary(
  label: 'Continue',
  size: MegaButtonSize.md,
  onPressed: () {},
);

MegaButton.secondaryBlack(label: 'Back', onPressed: () {});
MegaButton.primaryStroke(label: 'Learn more', onPressed: () {});

Variant	Role
primary	Conversion / CTA
primaryStroke, primaryContainer	Lighter primary emphasis
secondaryBlack	Main action on a task screen
secondaryStroke, secondaryContainer	Lighter secondary emphasis
error, errorStroke, errorContainer	Destructive actions

Sizes: sm, md, lg, xl, xxl. Use isLoading: true and onPressed: null for loading; semanticsLabel for icon-only buttons.

MegaTextField

MegaTextFormField(
  labelText: 'Phone',
  hintText: '[phone]',
  inputTemplate: '+996 (###) ### ###',
  keyboardType: TextInputType.phone,
  validator: (value) => MegaTextField.isTemplateComplete(value, '+996 (###) ### ###')
      ? null
      : 'Invalid phone number',
);

MegaTextField(
  labelText: 'Password',
  obscureText: true,
  showObscureToggle: true,
  showClearButton: true,
);

Template fields may auto-insert leading literals on focus — use MegaTextField.isTemplateComplete for validation, not isEmpty alone.

MegaSearchField

Compact search bar (40 dp, surfaceHigh background, 16 dp radius). Clear control appears inside the field when text is non-empty; [trailing] is a separate optional slot (e.g. filters). Pass [onCancel] to show an external cancel action that exits search mode (keyboard + collapsed UI — host handles logic).

MegaSearchField(
  hintText: 'Search',
  controller: searchController,
  focusNode: searchFocusNode,
  onChanged: (query) => filterResults(query),
  onCancel: () {
    searchController.clear();
    searchFocusNode.unfocus();
    setState(() => searchMode = false);
  },
  cancelText: 'Cancel',
  trailing: Icon(Icons.tune, size: MegaSpacing.iconSizeMd),
);

See example/lib/tabs/mega_text_field_tab.dart (_SearchModeFlowDemo) for an animated header ↔ search field flow.

Design tokens (non-color)

Spacing (4pt grid)

Token	px
MegaSpacing.xxs	2
MegaSpacing.xs	4
MegaSpacing.sm	8
MegaSpacing.md	16
MegaSpacing.lg	24
MegaSpacing.xl	32
MegaSpacing.xxl	48

Typography

MegaTypography — display, heading, title, body, label scales (regular / medium / bold). Used by MegaTheme TextTheme mapping.

Radii & shadows

• MegaRadii — xs … xxl, field, card, button, input, dialog, bottomSheet
• MegaShadows — card, dialog, snackBar, …

Migration from 0.0.x

Before (0.0.1–0.0.2)	After (0.0.3)
MegaTheme.light()	MegaTheme.light(colors: myLight)
MegaColors.primary	context.megaColors.primary
MegaColors.secondaryLight / secondaryDark	context.megaColors.secondary (per theme)
MegaPalette in package	Your app / example/lib/theme/ only

Before (0.0.6)	After (0.0.7)
MegaTextField(label: …, hint: …)	MegaTextField(labelText: …, hintText: …)
prefixIcon / suffixIcon	leading / trailing
@Deprecated text field stub	Full Figma-aligned MegaTextField + MegaTextFormField

Before (0.0.8)	After (0.0.9)
MegaSearchField wrapper over MegaTextField (labelText, …)	Standalone 40 dp search field; no labelText
—	onCancel + cancelText for search-mode exit; trailing for in-field actions

Contributing

1. Fork the repository
2. git checkout -b feat/my-widget
3. Commit with a clear message
4. Open a merge request

License

Apache-2.0 — see LICENSE.