lumen_kit
A Flutter widget kit with independently configurable colors and visual styles. Choose a palette and pair it with neon, flat, glass, soft, or brutal styling.
What's inside
| Category | Components |
|---|---|
| Theme | AppColors, LumenPalette, LumenPreset, LumenStyle, LumenThemeExt, LumenScope, AppTheme |
| Background | LumenAnimatedGridBackground, LumenGlowOrbSpec |
| Structure | LumenAppBar, LumenCard |
| Action | LumenCta, LumenButton, LumenIconButton, LumenFab, LumenMenuButton, LumenContextMenu |
| Input | LumenTextField, LumenSwitch, LumenCheckbox, LumenRadio, LumenSlider, LumenRangeSlider, LumenDropdown, LumenSearchBar, LumenDatePicker, LumenTimePicker, LumenChip (+ LumenChoiceChips, LumenFilterChips), LumenQuantityStepper, LumenRating, LumenPinField |
| Feedback | LumenStatusChip, LumenBanner, LumenDialog, showLumenSnackBar, showLumenToast, LumenLinearProgress, LumenCircularProgress, LumenSkeleton, LumenTooltip, LumenLoadingPanel, LumenLoadingOverlay (+ showLumenLoading) |
| Navigation | LumenNavigationCard, LumenTabs, LumenSegmentedControl, LumenBottomNavBar, LumenNavRail, showLumenBottomSheet, LumenDrawer, LumenStepper, LumenPageIndicator, LumenCarousel |
| Display | LumenBadge, LumenTag, LumenAvatar, LumenAvatarGroup, LumenListTile, LumenList, LumenEmptyState, LumenDivider, LumenExpansionTile, LumenDataTable, LumenTableRow |
The widgets take data, callbacks, and theme tokens so the app owns its business rules.
Requirements
- Dart
^3.14.0and Flutter>=3.50.0. - Use
package:material_ui/material_ui.dartfor the Material app and its widgets.flutter/material.dartandmaterial_uihave distinctThemeDataandMaterialtypes. See the integration guide when adding Lumen to an existing Flutter app.
Installation
Published package
Use the pub.dev release for the published
version. This example uses the 1.3.0 release constraints.
dependencies:
lumen_kit: ^1.3.0
material_ui: ^1.11.0
Git checkout
To try unreleased code from main, pin a commit on the repository instead.
dependencies:
lumen_kit:
git:
url: https://github.com/saulogatti/lumen-kit.git
ref: <commit-sha>
material_ui: ^1.11.0
Run flutter pub get from your app after choosing an installation method.
Minimum usage
Use the Lumen theme for the whole app
Use the full import to get AppTheme, which configures Material theme defaults
and registers the Lumen palette and style.
import 'package:lumen_kit/lumen_kit.dart';
import 'package:material_ui/material_ui.dart';
void main() => runApp(
MaterialApp(
theme: AppTheme.light,
darkTheme: AppTheme.dark,
home: const Scaffold(
appBar: LumenAppBar(title: 'Dashboard'),
body: Center(child: LumenCard(child: Text('Online service'))),
),
),
);
Only the components (without the theme)
Use components.dart to keep your Material theme and avoid name collisions
with your own AppTheme or AppColors. Register a LumenThemeExt on each
theme that should supply a specific palette and style. The extension preserves
the app's typography and Material settings.
import 'package:lumen_kit/components.dart';
import 'package:material_ui/material_ui.dart';
ThemeData withLumen(ThemeData base) => base.copyWith(
extensions: <ThemeExtension<dynamic>>[
...base.extensions.values.where((extension) => extension is! LumenThemeExt),
LumenThemeExt(
palette: LumenPalette.fromSeed(
primary: base.colorScheme.primary,
brightness: base.brightness,
),
style: LumenStyle.flat,
),
],
);
Without a Lumen extension, the widgets use the kit's light or dark palette according to the app's theme brightness, with the neon style.
Style one part of a screen
LumenScope applies a palette and style to its subtree. Widgets read the
nearest scope first, then the theme extension, then the default palette and style.
Routes and overlays can sit above a scope that wraps only the caller.
showLumenDialog resolves its appearance from the dialog route, while
showLumenBottomSheet carries the caller's accent to the sheet.
showLumenLoading carries both the caller's palette and style.
Widget saveAction(BuildContext context, VoidCallback onSave) => LumenScope(
palette: LumenPalette.fromSeed(
primary: Colors.teal,
brightness: Theme.of(context).brightness,
),
style: LumenStyle.flat,
child: LumenButton(label: 'Save', onPressed: onSave),
);
Changing colors
Widgets that use Lumen color tokens resolve the active palette. Explicit color overrides and typography supplied by the Material theme keep their own values.
// 1. Preset ready: neon (default), matrix, synthwave, ultraviolet, ember.
MaterialApp(theme: AppTheme.fromPreset(LumenPreset.matrix), home: ...);
// 2. One or two colors: backgrounds, surfaces, texts, glows and gradients
// are derived automatically.
MaterialApp(
theme: AppTheme.fromSeed(
primary: Colors.greenAccent,
secondary: Colors.orangeAccent, // optional
brightness: Brightness.dark, // or Brightness.light
),
home: ...,
);
// 3. Fine-tuning specific tokens (gradients are recalculated automatically).
final palette = LumenPalette.defaultDark().copyWith(primary: Colors.greenAccent);
MaterialApp(theme: AppTheme.fromPalette(palette), home: ...);
Semantic colors
success and warning use the AppColors defaults. danger uses
AppColors.danger in dark palettes and the darker AppColors.dangerLight in
light ones, which keeps AA contrast (4.5:1) on light surfaces. Pass your own
colors to AppTheme.fromSeed or LumenPalette.fromSeed, for example the
Material error color, which already follows brightness:
MaterialApp(
theme: AppTheme.fromSeed(
primary: Colors.red,
brightness: Brightness.light,
danger: scheme.error,
),
home: ...,
);
A custom danger whose hue is within 30 degrees of primary and whose
saturation is below 50% becomes 20% more saturated, so it does not read as an
off-tone primary. Other colors are kept as given. Any palette also accepts
semantic colors through copyWith.
LumenThemeExt.lerp interpolates palette changes during theme transitions.
accentCyan,accentMagentaandaccentBluebecameprimary,secondaryandtertiary. The old names continue to function as@Deprecated.
Inside any widget, access via extension:
final p = LumenThemeExt.of(context).palette;
return Container(color: p.surface);
Changing the style (in addition to color)
"Neon" (glow, gradients, grid) is just one of the styles. LumenStyle controls
shadow, fill, surface, border and background, and matches any palette:
| Style | Visual |
|---|---|
neon |
Colorful glow, gradients, grid + orbs (default) |
flat |
Neutral shadows and solid fills where the style is applied. The decorative background keeps its gradient and omits the grid and default orbs. |
glass |
Translucent surfaces with blur, soft glow |
soft |
Very round corners, diffuse shadows, and a dotted background. Removes borders drawn through LumenStyle.borderAll. |
brutal |
Straight corners, thick edge, offset hard shadow |
MaterialApp(
theme: AppTheme.fromPreset(LumenPreset.matrix, style: LumenStyle.flat),
home: ...,
);
// Fine-tuning starting from a preset.
final style = LumenStyle.soft.copyWith(
background: LumenBackgroundKind.grid,
radiusScale: 1.2,
);
Assembling own components
The parts that kit widgets wear inside are also public
(package:lumen_kit/components.dart), then a widget of yours earns the same
behavior and follows palette and style without copying code:
final LumenPalette p = LumenThemeExt.of(context).palette;
final LumenStyle s = LumenStyle.of(context);
LumenPressable( // ripple, focus, disabled 0.55, semantics
onTap: save,
borderRadius: s.radius(14),
child: Container(
padding: const EdgeInsets.all(16),
decoration: LumenDecorations.panel(p, s, accent: p.secondary),
child: LumenActionContent(color: p.textPrimary, icon: Icons.save, label: 'Save', busy: saving),
),
);
| Ask | For what |
|---|---|
LumenPressable |
Touchable area with ripple, keyboard, selected/checked/toggled for screen readers and opacity disabled |
LumenDecorations |
panel (dialog/toast/tooltip), selectable (navigation item), iconBox, input (InputDecoration), accent/diagonal (gradients) |
LumenActionContent |
Spinner or icon + text, as in buttons |
LumenLabeled |
Control + label (checkbox, radio, switch) |
LumenMotion / kLumen* |
Durations, disabled opacity and respect to "reduce animations" |
Skeleton and Lumen indeterminate progress animations hold a static state
when the system requests reduced motion. Transitions using
LumenMotion.duration become instantaneous.
Configurable background
LumenAnimatedGridBackground(
gridSpacing: 80,
gridOpacity: 0.08,
orbs: const <LumenGlowOrbSpec>[
LumenGlowOrbSpec(color: Colors.cyanAccent, size: 380, top: -120, left: -120),
LumenGlowOrbSpec(
color: Colors.purpleAccent,
size: 320,
bottom: -100,
right: -80,
),
],
child: child,
);
Large list and code
LumenList builds rows on demand. Supply a separatorBuilder to add
separators and an empty widget for zero items. Give the list a bounded
viewport for large data sets. Scroll options such as shrinkWrap, physics,
scrollDirection, and reverse work as in ListView.
LumenList(
itemCount: events.length,
empty: const LumenEmptyState(
icon: Icons.inbox_outlined,
title: 'No events',
),
itemBuilder: (context, i) => LumenListTile(
title: events[i].title,
onTap: () => open(events[i]),
),
)
LumenPinField is controlled by value and onChanged. Set
onChanged to null to disable input. onCompleted fires when typing
or pasting takes the code from incomplete to complete. Assigning a complete
value programmatically only updates the displayed code.
LumenPinField(
value: _code,
onChanged: (String v) => setState(() => _code = v),
onCompleted: submit,
)
LumenBanner stays visible until its parent removes it. To add a close
button, pass an onDismiss callback that updates the parent's state.
Button variants
Row(
children: <Widget>[
LumenButton(label: 'CONFIRM', icon: Icons.check, onPressed: () {}),
const SizedBox(width: 12),
LumenButton.outline(label: 'EDIT', icon: Icons.edit, onPressed: () {}),
const SizedBox(width: 12),
LumenButton.ghost(label: 'CANCEL', onPressed: () {}),
],
);
soliduses the accent gradient in gradient styles and a solid fill in flat and brutal, as doesLumenCta.outline— glow edge + translucent background. Secondary action.ghost— only text/icon in accent color. Tertiary action.
Pass a LumenStatusTone as tone to give any variant a semantic color from
the palette. A solid button with a tone fills with that color instead of the
accent gradient, and LumenButton.danger is the shortcut for destructive
actions:
showLumenDialog<void>(
context: context,
title: 'Delete category?',
accent: LumenThemeExt.of(context).palette.danger,
content: const Text('This cannot be undone.'),
actions: <Widget>[
LumenButton.ghost(label: 'Cancel', onPressed: () => Navigator.pop(context)),
LumenButton.danger(label: 'Delete', icon: Icons.delete_outline, onPressed: onDelete),
],
);
accentColor still overrides the shadow of a solid button and the color of
outline and ghost buttons, but never the solid fill.
Labels stay on one line. In a narrow space, the label is truncated with an ellipsis instead of overflowing.
Selection inputs
LumenSwitch(value: on, onChanged: (v) => setState(() => on = v));
LumenCheckbox(value: checked, tristate: true, onChanged: (v) => …);
LumenRadio<String>(
value: 'a',
groupValue: selected,
label: 'Option A',
onChanged: (v) => setState(() => selected = v ?? selected),
);
LumenDropdown<String>(
label: 'Accent',
value: current,
items: const [
LumenDropdownItem(value: 'cyan', label: 'Cyan'),
LumenDropdownItem(value: 'magenta', label: 'Magenta'),
],
onChanged: (v) => setState(() => current = v ?? current),
);
LumenDatePicker(
label: 'Start',
value: date,
firstDate: DateTime(2020),
lastDate: DateTime(2030),
onChanged: (d) => setState(() => date = d),
);
LumenTimePicker(
label: 'Time',
value: time,
onChanged: (t) => setState(() => time = t),
);
LumenRangeSlider(
values: price,
max: 500,
divisions: 50,
onChanged: (v) => setState(() => price = v),
onChangeEnd: (v) => search(v), // search only when released
);
Chips, quantity and evaluation
// Single selection.
LumenChoiceChips<String>(
value: size,
onChanged: (v) => setState(() => size = v),
items: const [
LumenChipItem(value: 's', label: 'S'),
LumenChipItem(value: 'm', label: 'M'),
],
);
// Filters (multiple selections). Accepts and returns a new Set.
LumenFilterChips<String>(
values: filters,
onChanged: (v) => setState(() => filters = v),
items: const [
LumenChipItem(value: 'promo', label: 'Promotion'),
LumenChipItem(value: 'shipping', label: 'Free shipping'),
],
);
LumenQuantityStepper(value: quantity, min: 1, max: 10, onChanged: (v) => setState(() => quantity = v));
LumenRating(value: rating, allowHalf: true, onChanged: (v) => setState(() => rating = v));
LumenRating(value: 4.3, size: 16); // read-only, with fraction
Menu, loading and carousel
// The card / app bar overflow menu.
LumenMenuButton<String>(
items: const [
LumenMenuItem(value: 'edit', label: 'Edit', icon: Icons.edit),
LumenMenuDivider(),
LumenMenuItem(value: 'del', label: 'Delete', destructive: true),
],
onSelected: (v) => …,
);
// Right-click (desktop/web) or long press (mobile).
LumenContextMenu<String>(items: items, onSelected: …, child: row);
// Locks the screen during submit and returns the result of the task.
final ok = await showLumenLoading(
context: context,
message: 'Submitting…',
task: () => api.submit(form),
);
// Or just an area, controlled by state.
LumenLoadingOverlay(loading: saving, message: 'Saving…', child: form);
// Gallery / onboarding with page dots.
LumenCarousel(
itemCount: photos.length,
itemBuilder: (context, i) => Image.network(photos[i], fit: BoxFit.cover),
);
// Or just the dots, linked to your PageView.
LumenPageIndicator(count: 4, controller: pageController);
// Stacked avatars with "+N".
LumenAvatarGroup(
avatars: [for (final u in members) LumenAvatar(initials: u.initials)],
maxVisible: 3,
total: totalMembers,
);
Navigation
// Compact pill — great for switching views within a screen.
LumenSegmentedControl(
selectedIndex: i,
onChanged: (v) => setState(() => i = v),
items: const [
LumenTabItem(label: 'Day'),
LumenTabItem(label: 'Week'),
LumenTabItem(label: 'Month'),
],
);
// Bottom nav with badge.
Scaffold(
bottomNavigationBar: LumenBottomNavBar(
selectedIndex: tab,
onChanged: (v) => setState(() => tab = v),
items: const [
LumenNavItem(icon: Icons.home_outlined, label: 'Home'),
LumenNavItem(icon: Icons.bolt_outlined, label: 'Events', badge: '3'),
LumenNavItem(icon: Icons.person_outline, label: 'Account'),
],
),
);
// Themed modal bottom sheet.
showLumenBottomSheet<void>(
context: context,
builder: (_) => const Padding(
padding: EdgeInsets.all(20),
child: Text('Quick actions'),
),
);
Styled dialog
await showLumenDialog<void>(
context: context,
title: 'Confirm action',
icon: Icons.warning_amber_rounded,
content: const Text('This operation cannot be undone.'),
actions: <Widget>[
TextButton(onPressed: () => Navigator.pop(context), child: const Text('Cancel')),
LumenCta(label: 'CONFIRM', onPressed: () => Navigator.pop(context)),
],
);
Example app
The example gallery lets you toggle Lumen colors and component styles independently. Choose Default Material to compare with equivalent Material widgets using their default colors and shapes.
The gallery also demonstrates foundation building blocks, enabled and disabled controls, loading and validation states, and horizontal and vertical steppers.
cd example
flutter pub get
flutter run -d windows
Libraries
- components
- Only the kit components, without
AppThemeorAppColors. - lumen_kit
- Complete kit: components + theme (
AppTheme,AppColors). To use just the widgets, without any themes, importpackage:lumen_kit/components.dart.