ui_core 0.3.1
ui_core: ^0.3.1 copied to clipboard
Headless behaviours for Flutter design systems: the state, keyboard, focus and semantics of 40 controls, routes and overlays, with every pixel left to the design system.
ui_core #
Headless controls for Flutter design systems. The package handles input, keyboard navigation, focus and accessibility. Your widget builders draw each state using your design system's shapes, colours and typography.
The look packages built on it (comic_ui, fluent2_design_ui, frosted_ui, neumorphism_ui and the rest) re-export
it, so an app that uses a look rarely imports it directly. Import it to build a look of your own:
import 'package:ui_core/ui_core.dart';
A button of your own, for example: DesignPressable keeps the press, the keys, focus, hover and what a screen reader
hears, and its builder draws the button for each set of states.
import 'package:flutter/widgets.dart';
import 'package:ui_core/ui_core.dart';
class InkButton extends StatelessWidget {
const InkButton({super.key, required this.label, this.onPressed});
final String label;
final VoidCallback? onPressed;
@override
Widget build(BuildContext context) {
return DesignPressable(
onPressed: onPressed,
semanticLabel: label,
minimumSize: const Size(44, 44),
builder: (context, states, child) {
final pressed = states.contains(WidgetState.pressed);
final focused = states.contains(WidgetState.focused);
final disabled = states.contains(WidgetState.disabled);
return DecoratedBox(
decoration: BoxDecoration(
color: disabled
? const Color(0xFFCBD5E1)
: pressed
? const Color(0xFF1D4ED8)
: const Color(0xFF2563EB),
borderRadius: BorderRadius.circular(8),
border: focused
? Border.all(color: const Color(0xFF93C5FD), width: 2)
: null,
),
child: Padding(
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
child: Text(
label,
style: const TextStyle(color: Color(0xFFFFFFFF)),
),
),
);
},
);
}
}
The behaviours #
| Behaviour | Class | Flutter's nearest |
|---|---|---|
| Anchored overlay (popover, menu surface) | DesignAnchoredOverlay |
RawMenuAnchor |
| Calendar | DesignCalendar, DesignCalendarController |
CalendarDatePicker |
| Carousel | DesignCarousel |
CarouselView |
| Colour picker | DesignColorPicker, DesignColorArea, DesignColorSlider |
|
| Combobox | DesignCombobox |
RawAutocomplete |
| Command palette | DesignCommandPalette, showDesignCommandPalette |
|
| Data table | DesignDataTable, DesignTableController |
DataTable |
| Form field | DesignField, DesignForm, DesignFormField |
InputDecorator, Form |
| Input group | DesignInputGroup |
|
| Menu bar | DesignMenuBar |
MenuBar |
| One-time code | DesignOtpField |
|
| Password reveal | DesignPasswordReveal |
|
| Pull to refresh | DesignPullToRefresh |
RefreshIndicator |
| Range slider | DesignRangeSlider |
RangeSlider |
| Reorderable list | DesignReorderableList |
ReorderableListView |
| Scroll area | DesignScrollArea |
RawScrollbar |
| Side sheet | DesignSideSheetRoute |
|
| Split button | DesignSplitButton |
|
| Split view | DesignSplitView |
|
| Swipe actions | DesignSwipeActions |
Dismissible |
| Tag input | DesignTagInput |
InputChip |
| Toasts | DesignToaster |
ScaffoldMessenger |
| Toggle group | DesignToggleGroup |
SegmentedButton |
| Tree | DesignTree, DesignTreeController |
TreeSliver |
| Haptics | DesignHaptics, DesignHapticsScope |
HapticFeedback |
| Overlay padding (a look's chrome a surface keeps clear of) | DesignOverlayPadding |
MediaQuery.padding |
| Context menu | DesignContextMenu |
ContextMenuController |
| Tooltip | DesignTooltip |
RawTooltip |
| Shortcut label (a menu row's keys) | designShortcutLabel, designShortcutKeys |
MenuItemButton's |
| Bottom sheet | DesignBottomSheetRoute, DesignBottomSheetController, DesignBottomSheetDragHandle |
ModalBottomSheetRoute, DraggableScrollableSheet |
| Full-screen sheet | DesignSheetPageRoute |
PageRoute |
| Dialog and alert | DesignDialogRoute, DesignDialog |
DialogRoute, AlertDialog |
| Swipe actions, from outside | DesignSwipeActionsController |
|
| Tabs | DesignTabController, DesignTabBar, DesignTabView |
TabController, TabBar, TabBarView |
| Adaptive shell | DesignAdaptiveShell, DesignWindowSizeClass, DesignNavigationMode |
NavigationBar, NavigationRail, NavigationDrawer |
| List and detail | DesignListDetail |
|
| Wheel picker | DesignWheelPicker, DesignWheelColumn |
CupertinoPicker |
| Date and time fields | DesignDateField, DesignTimeField, DesignTimeOfDay |
InputDatePickerFormField, TimeOfDay |
| Number field | DesignNumberField |
TextField with keyboardType: number |
| Rating | DesignRating |
(none) |
| Charts | DesignChart, DesignPieChart, DesignChartTable; DesignLinearScale, DesignTimeScale, DesignBandScale |
(none) |
They are built from DesignPressable (a press, focus, hover and semantics on any widget) and DesignValueHandle
(a value dragged or stepped with the keys). Each class's documentation has an example.
Flutter's conventions #
The behaviours take what Flutter's own widgets take, under Flutter's names:
- A controller (
TextEditingController,ScrollController,MenuController, or one of this package'sChangeNotifiers) and aFocusNodeare optional where a behaviour can keep its own: without one it makes its own and disposes it, and it never disposes one it was given. A behaviour whose controller holds its model (a calendar's dates, a table's rows, a tree's nodes, a colour shared by an area and its sliders) or shares it with your scroll view takes it as required, asTabBarViewneeds one when noDefaultTabControlleris above it. - A single tab stop takes
focusNodeandautofocus. A behaviour of many stops (a toggle group, a menubar, a table, a tree) keeps one node per item, asSegmentedButtonandMenuBardo. - A value comes with
onChanged, and a nullonPressedoronChangeddisables, with no second switch. Two keep one, asListTileandTextFielddo:DesignPressable.enabled(a busy button keeps its focus and reads as enabled while it ignores presses) andDesignCommand.enabled(a palette givenonSelectedruns commands that carry noonPressedof their own). - What a builder paints (a split button's label and its actions, a menu entry, a command, a toast, a table's column,
a shell's tab) carries its words as a
Stringand its glyph asIconData: they are what type-ahead, search and a screen reader read, and your builder turns them into widgets.
Accessibility #
Controls expose their label, value, role and available actions to assistive technology. Keyboard navigation follows the reading direction. Use a builder’s WidgetState values to show focus, press, selection and disabled states. Motion follows the platform’s reduced-motion preference.
Motion #
Motion is springs only: a look's motion tokens are (damping ratio, stiffness) pairs, run through designSpring,
DesignMotionPolicy and springTo, and nothing takes a duration or an easing curve. Under Reduce Motion,
DesignMotionPolicy.of(context) critically damps every spatial spring (one that moves, resizes or reshapes
something) at its own stiffness, so nothing overshoots or bounces, and turns every effects spring (opacity, colour)
into a short fade: critically damped at a stiffness of at least 3800 (DesignMotionPolicy.reducedEffectsStiffness),
settled within 150 ms, so nothing lingers. Neither is cut to an instant change, which reads as a flash.
Whether the reader asked for reduced motion is one read, designReduceMotionOf(context), and every part of
ui_core reads it. The platforms ask differently:
| Platform | The setting | What Flutter sets |
|---|---|---|
| Android | Remove animations | MediaQuery.disableAnimationsOf |
| Web | prefers-reduced-motion |
both |
| iOS | Reduce Motion | only dart:ui's AccessibilityFeatures.reduceMotion, which MediaQuery does not carry |
So MediaQuery.disableAnimationsOf(context) alone misses an iPhone with Reduce Motion on; read
designReduceMotionOf(context) (or DesignMotionPolicy.of(context)) instead. A widget that read it builds again
when either setting changes. iOS's change comes as a build, not as didChangeDependencies, so read it in build
or as you act, not once in didChangeDependencies.
A look's page transitions #
An app's MaterialPageRoute plays the push its own Material theme names. A look's library stands on material_ui, so a
PageTransitionsTheme it installs in the Material theme it builds is material_ui's. An app on Flutter's own
MaterialApp, as most apps that take a look are, and every look's example, pushes Flutter's MaterialPageRoute,
which never reads it: on a Mac it plays the Cupertino slide. So a look exposes its push as a map of widgets-level
PageTransitionsBuilders, which fits both Materials' PageTransitionsTheme:
const Map<TargetPlatform, PageTransitionsBuilder> comicPageTransitions = {
TargetPlatform.android: ComicPageTransitionsBuilder(),
// iOS's swipe back from the screen's edge, round the look's push.
TargetPlatform.iOS: DesignSwipeBackPageTransitionsBuilder(ComicPageTransitionsBuilder()),
TargetPlatform.macOS: ComicPageTransitionsBuilder(),
// ...
};
On iOS a page pops with a swipe from the screen's leading edge, and the swipe lives in Cupertino's page transition,
which a look's own push replaces. DesignSwipeBackPageTransitionsBuilder keeps it round any builder: while a finger
drives the swipe, the page follows it and the page under it shows, as on every iOS screen; otherwise the look's push
and pop play. designSwipeBack(map) wraps a map's iOS entry the same way, for a map built at run time.
Its example and its README put it in the app's ThemeData, Flutter's or material_ui's, whichever the app is on:
MaterialApp(
theme: ThemeData(
pageTransitionsTheme: const PageTransitionsTheme(builders: comicPageTransitions),
),
home: const ComicHome(),
);
example/test/page_transitions_test.dart holds it: under that theme, Flutter's MaterialPageRoute plays the look's
push on every platform, and without it a Mac's plays the Cupertino slide; on iOS, a swipe from the left edge past half
way pops the page, and one let go short of it settles back. A look's example copies the test with its own map.
Haptics #
The moments a behaviour marks with a haptic are one table, DesignHaptics: selectionChanged (a wheel's row crossing
its centre, a slider's thumb crossing a division, a rating's step while dragged), longPress (a long press that opened
something) and thresholdCrossed (a drag passing the point where letting go acts). Each is a callback that defaults
to the platform's own feedback; null plays nothing. A DesignHapticsScope swaps the table for its subtree:
DesignHaptics.silent() for none, or your own callbacks. Under flutter_test nothing plays; a test that checks a
haptic gives a scope a table that records.
Styling a part #
A look's parts take a style: of one shape, DesignStyle, as Material's buttons take a ButtonStyle: ten slots
(fill, foreground, edge, overlay, side, shape, padding, minimumSize, textStyle, iconSize), each a
WidgetStateProperty that resolves for the part's states. A part reads each slot from its style:, then its
component theme, then the look's theme-wide knobs, then the look's default; DesignStyleOf reads the first two
for a part's states. Each look names it as its own (ComicStyle, FrostedStyle), so a style is written and read
the same way in every look.
Words #
The words a behaviour says on its own ("Close sheet", "Slide 2 of 5", a sorted column's hint) come from
DesignLocalizations, each also a parameter on its behaviour. So do the general words a look shows or says by
itself (Cancel, Close, Today, Next month, "2 of 5", "3 items selected"), under MaterialLocalizations' names where
Flutter has the word: a look reads them from DesignLocalizations.of(context) rather than writing English. English
is the default, with nothing to set up under MaterialApp, CupertinoApp or WidgetsApp.
ui_core speaks 30 languages (DesignLocalizations.supportedLocales): its dates, plurals and digits come from
Unicode CLDR, as Flutter's do, and its words are Material's own translations where Material has the word. Opt in
with its delegate beside Flutter's, from flutter_localizations (add flutter_localizations: sdk: flutter to your
pubspec, as a look's gallery does):
import 'package:flutter_localizations/flutter_localizations.dart';
MaterialApp(
localizationsDelegates: const [
DesignLocalizations.delegate,
...GlobalMaterialLocalizations.delegates,
],
supportedLocales: DesignLocalizations.supportedLocales,
// ...
)
GlobalMaterialLocalizations.delegates holds the Material, Cupertino and Widgets delegates for your app's own
Flutter widgets: without the Material one, a Material TextField under a language other than English asserts, and
the Widgets one gives Arabic, Hebrew, Persian and Urdu their direction. A look supplies its own Material and
Cupertino words in the app's language: it is drawn with material_ui and cupertino_ui, whose words are types of
their own, and loads them itself. A locale ui_core does not speak gets English. For a language of your own, or
words of your own, extend DefaultDesignLocalizations, override the words you translate, and add a delegate for
your subclass to localizationsDelegates; a word added in a later minor version then stays English until you
translate it. DesignLocalizations also says the day a week starts on (firstDayOfWeek), which a calendar follows unless told
otherwise.
For number and chart labels, use formatDecimal, parseDecimal and formatPercent. Date and time controls use the locale’s calendar order, digits, separators and first day of the week.
Tap targets, density and spacing #
A look declares the floors its controls stand at once, as a theme does: DesignTapTargetScope holds
DesignTapTargets (44 by 44 for a finger, 24 by 24 for a pointer, unless the look says otherwise), and
DesignTapTarget lays a control out at the floor, as Material's padded tap target size does: its face keeps its
size, aligned where you say (centred by default), and the room round it takes the taps and is what a screen reader
outlines and Flutter's tap-target guideline measures, so the hit area, the semantics and the layout agree. Whether a finger or a pointer
reaches the controls is DesignInput, by platform unless the look decides. DesignDensity tightens a control's
face in steps (-4 to 4), never its target: a compact face stands in the same target, with more room round it.
DesignSpacingScope declares the grid a look's spacing stands on (DesignSpacing, 4 pt by default; a look whose values
sit on 2 pt declares 2), read by DesignSpacing.of and by ui_core_test's spacing check.
Testing your design system #
Add ui_core_test to your test dependencies to check alignment, widths, tap targets and clipping on rendered screens. Use DesignKeylineRegion to identify a card or section, and DesignKeylineFace for a visible face that blends into its background. ui_core_test on pub.dev
Lining controls up #
Controls that share a line drift apart in ways no one control's test sees: two controls of "the same size" a few pixels apart, a label a pixel low, a field that shrinks on desktop. ui_core_test's checks find them from the drawn pixels (its README says how each reads a screen). What keeps a line straight:
- one control height per size and density, taken by every control that can share a line;
- content centred in a box of that height, rather than padding added to a line height;
- even leading (
TextLeadingDistribution.even) on control labels, so a label's line box is centred on its glyphs; - a row that centres its controls, never one aligned to the bottom or the top;
- a theme under the design system that pins its density: Material's
ThemeData.visualDensityis compact on desktop unless the theme says otherwise, and tests run as Android, so no test sees it; - a text entry that is a
TextField(validated by the design system's ownFormField, never aTextFormField, which builds a decoration even when given none) inside the design system's own box, its decoration null or collapsed withcontentPadding,constraints,isDenseandvisualDensityall set, its one line centred by alignment, and its icons, counter, help and error the design system's own widgets: a decoration field left unset is filled from the platform and the host theme.
DesignControlBox is that box for a control, its content centred and its text given even leading.
DesignTextEntryBox is the same for a text entry: one line centred, several starting where one stands, the hint on
the typed text's baseline. Both paint nothing.
A label centred by its line box still looks off: the box is the font's ascent and descent, not its capitals, and the
engine puts the baseline on a whole pixel, so the capitals land a pixel or two from the middle, by a different amount
in each typeface and size. DesignCapCenter wraps a one-line label, keeps its size, and draws it so that its
capitals' middle, where the engine will draw it, is its box's middle: whatever centres the box (a row, a button's
face, a tab, a title bar) then centres the capitals, within half a device pixel (an engine that hints the font, such
as FreeType, also snaps the capitals' top to the pixel grid, which can add up to half a pixel). It takes the
typeface's cap height as
a fraction of its font size (capHeightFactor, the font's OS/2 cap height over its units per em). An icon beside
the label is not moved. Around a one-line TextField (or DesignTextEntryBox) it does the same for the typed
text and the hint, and the caret, the selection and taps move with them.
What the eye compares in a row is the capitals: a 13 px button label and a 14 px field's text look level when their
capitals' middles are, whatever their baselines. A design system whose labels and entries are wrapped in
DesignCapCenter holds them on a row's centre line to half a device pixel.
A card's contents drift the same way across rows: a title at 16, rows' words at 26, a checkbox at 22, a chevron that
stops short of the switches above it. A keyline is the line what starts a row (or ends one) sits on. A design
system's card and section widgets put DesignKeylineRegion around their content (it lays out and paints nothing,
and names any nested level the card means, such as words after an avatar), so ui_core_test's keyline check can read
every card on a screen; a face its pixels cannot show (one the colour of the ground, a pane of glass), or a picture
with things placed on it, wears DesignKeylineFace. A gallery marks each section's column of examples with
startAligned: true.
Who disposes what #
A controller or focus node you pass in is yours to dispose: a behaviour never disposes what it is given. Each parameter's documentation says what the behaviour does given none (most make their own, and dispose it).
Libraries #
package:ui_core/ui_core.dart: the behaviours, motion, the words, a part's style (DesignStyle),DesignCapCenter, which centres a label by its capitals,DesignKeylineRegion, which marks a card for the keyline check, andDesignKeylineFace, which marks a face its pixels cannot show.package:ui_core/host.dart: the scaffold contract the look packages share. It is not meant for apps and leaves the package in a later minor version.package:ui_core/inventory.dart: the checklist of components an ordinary app expects from a design system, andDesignInventoryGallery, which lists a design system's answers to it. A design system's own tests and gallery use it; an app does not.- The checks (
package:ui_core/alignment.dartuntil 0.2) arepackage:ui_core_test/ui_core_test.dart, a package of their own.
Requirements and versions #
ui_core needs Flutter 3.47 or later (Dart 3.13), and depends on Flutter alone.
Consult the CHANGELOG for migration instructions between minor releases. The main library is the supported API for apps. host.dart and inventory.dart are intended for design-system authors and may change in a patch release.