Design libraries
spring_boot_starter_flutter knows no design library. It imports Flutter's widgets library only, and an app of spring.flutter.app.type: widgets, the type of an app without a design starter, has neither Material nor Cupertino in its build. Material and Cupertino come with two starters of their own, spring_boot_starter_flutter_material and spring_boot_starter_flutter_cupertino.
Why
Flutter 3.50 moved Material and Cupertino out of the SDK: package:flutter/material.dart and package:flutter/cupertino.dart are deprecated, and the libraries are the Flutter team's packages material_ui and cupertino_ui. A starter that imported them would put both into every app, whatever it shows. So the Flutter starter keeps what every app needs (the application, beans in widgets, themes from properties, the splash, messages, the debug panel), and what is a design's goes into the design starters.
An app that draws its own widgets gains a smaller build. A design system of your own plugs in the same way the two starters do.
The three app types
spring.flutter.app.type |
App widget | Starter it needs | UI library the app lists |
|---|---|---|---|
widgets (without a design starter) |
WidgetsApp |
none: spring_boot_starter_flutter |
none |
material |
MaterialApp |
spring_boot_starter_flutter_material |
material_ui |
cupertino |
CupertinoApp |
spring_boot_starter_flutter_cupertino |
cupertino_ui |
The type is a text. It names a SpringAppFactory bean: the Flutter starter has the one of widgets, each design starter adds its own, and a design of your own is one more bean. A type without its starter fails the start and names the starter to add; an unknown type fails it with the types the application has.
# pubspec.yaml of a Material app
dependencies:
material_ui: ^1.11.0
spring_boot_starter_flutter_material: ^0.9.0
A design starter brings and re-exports the Flutter starter, so an app lists the design starter instead.
The type is deduced
spring.flutter.app.type need not be set: the application's starters decide, as Spring Boot deduces spring.main.web-application-type from the class path. The Material app above, with one design starter, is of type material without a line of configuration.
- One design starter, or one
SpringAppFactorybean of the app's own type: the app is of that type. - None:
widgets. - App factories of several types, both design starters for instance: the start fails, naming the property and the types, and asks to choose one.
An app that is Material on Android and Cupertino on iOS lists both and so sets the type, for every platform and again per platform in a profile:
# lib/resources/application.yml
spring.flutter.app.type: material
# lib/resources/application-ios.yml
spring.flutter.app.type: cupertino
Set, the property always wins: widgets keeps a WidgetsApp although a design starter came in through another package, and a design of your own is chosen by its type when a design starter is in the application too.
What works without a design
An app of type widgets has the whole theme of spring.flutter.theme.* that is not a design's:
- The palette. Flutter's baseline palette (the Material 3 baseline, as
SpringColorScheme.baseline), with the roles you set undercolors.*over it.SpringTheme.of(context).colorSchemehas all 46 roles, under Material 3's names. - The type scale. The 15 text styles (
display-large...label-small) have the sizes of the Material 3 type scale and the platform's default fonts (SpringTypeScale), so they are what aMaterialAppgives, without Material.localizedTextStyle(style, script)gives the sizes of a script (dense for Chinese, Japanese and Korean, tall for Arabic, Hindi and Thai). - The rest of the theme. Spacing, shapes, elevations, tokens, state styles, backgrounds, images, loaders, the splash, and the page transitions
fade,fade-upwards,contentandnone. The Material 3 easings are numbers of the starter (ThemeValues.standardEasing). MarkdownView, with the theme's text styles and the starter's own selection handles (SpringTextSelectionControls): none where a mouse selects, two round handles in the theme's primary color on a touch screen.- The login form of the security starter, as plain widgets drawn from the
SpringTheme.
What needs a design
These fail the start without a design starter, and the message names one:
| Property | Why | Starter |
|---|---|---|
seed-color, scheme-variant, contrast |
The palette from a seed is Material 3's algorithm | either design starter: both make the same palette |
motion.page-transition: zoom |
Material's transition | spring_boot_starter_flutter_material |
motion.page-transition: cupertino |
The iOS slide with its swipe back | spring_boot_starter_flutter_cupertino |
Without a design, a theme writes its roles under colors.* instead of a seed; what it does not set is the baseline. The neon theme of the repository's examples does this: it names every role it uses and has no seed-color. A screen's own zoom or cupertino transition in the navigation starter is not a start failure: it is reported in the log, and the page shows without a transition. platform shows no transition without a design, as before.
What is accepted unchecked
The theme properties of a design are accepted in an app without its starter. A theme library has them for the apps of that design, and an app of another design simply does not show them, as Flutter shows no ThemeData outside a MaterialApp:
| Property | Read by |
|---|---|
components.* |
spring_boot_starter_flutter_material |
visual-density |
spring_boot_starter_flutter_material |
tap-target-size |
spring_boot_starter_flutter_material |
splash as one value (ripple, sparkle, none: the ink splash) |
spring_boot_starter_flutter_material |
cupertino.* |
spring_boot_starter_flutter_cupertino |
Without the starter they are not shown and not checked. One INFO line on spring_boot_starter_flutter.SpringThemes names each, once:
The theme property components is not shown and not checked: spring_boot_starter_flutter_material, which reads it, is not in the application.
The key is still checked: componets fails the start. A splash map is not a design's: it is the splash screen of the start, read in every app. SpringThemeData.unreadDesignProperties lists the unread properties of a theme with the starter that reads each.
A design of your own
A design system (the company's own widgets, say "Ocean") plugs in through the same four points as Material and Cupertino. All of them are in spring_boot_starter_flutter; the theme part is in the library package:spring_boot_starter_flutter/theme_design.dart.
The theme: ThemeDesign
A ThemeDesign tells the themes what the design adds: its app type, the theme properties only its widgets read, the palette it makes from a seed, its page transitions, and the check of its properties at the start.
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter/theme_design.dart';
final class OceanDesign implements ThemeDesign {
const OceanDesign();
@override
String get appType => 'ocean';
@override
List<String> get themeProperties => const ['ocean']; // spring.flutter.theme.ocean.*
@override
List<String> get schemeVariants => const []; // one way to make a palette
@override
SpringColorScheme colorScheme(ColorSchemeSpec spec) =>
OceanPalette.of(spec.seedColor ?? OceanPalette.seed, spec.brightness);
@override
PageTransitionsBuilder? pageTransition(PageTransitionType type) => null;
@override
void check(SpringThemeData theme) {
// Read the theme's `ocean` properties now: a wrong value throws a
// ThemePropertyException naming the property, and the start fails.
}
}
The themes are read before any bean exists (the splash of the start is in them), so a design is not a bean. Its starter lists it among the factories of its module:
// lib/spring_auto_configuration.dart of the design's package
@AutoConfigurationModule(factories: [OceanDesign()])
final BeanModule oceanAutoConfiguration = $oceanBeans;
The generator copies the factories of every starter into the generated application, and SpringThemes finds the designs with SpringApplication.factories.load<ThemeDesign>(). See Auto-configuration for factories.
The app widget: SpringAppFactory
A bean that implements SpringAppFactory builds the app widget of its type. SpringAppRequest has the settings of spring.flutter.app.*, the themes, the theme shown, the starter's builder (pass it on), and home or the application's router:
@Component()
class OceanAppFactory implements SpringAppFactory {
@override
String get type => 'ocean';
@override
List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
const [GlobalWidgetsLocalizations.delegate];
@override
Widget build(BuildContext context, SpringAppRequest app) => OceanApp(
title: app.settings.title,
theme: OceanTheme.of(app.shown),
builder: (context, child) => DesignScope(
textStyle: (context, style) => OceanTheme.of(app.shown).text[style],
selectable: (context, child) => OceanSelectionArea(child: child),
controls: const OceanControls(),
child: app.builder(context, child),
),
home: app.home,
);
}
Page routes: DesignPageRoutes
The router of the navigation starter asks the DesignPageRoutes beans, in @Order, for the route of a page whose transition is platform or cupertino, and shows the first route it gets. A design's bean answers for its own app type and returns null for the others; heroController(appType) gives the hero flights of its navigators.
@Component()
class OceanPageRoutes implements DesignPageRoutes {
@override
PageRoute<Object?>? pageRoute(
PageTransitionType transition,
String appType,
SpringPageRequest page,
) => transition == PageTransitionType.platform && appType == 'ocean'
? OceanPageRoute(settings: page.settings, builder: page.childOf)
: null;
@override
HeroController? heroController(String appType) => null;
}
The starters' own widgets: DesignScope and DesignControls
MarkdownView and the login form of the security starter know no design. A DesignScope above the app's pages (in the factory's builder, as above) gives them the design's text styles (textStyle, by the canonical name of a style: titlelarge; null for the SpringTheme's), its way of selecting text (selectable), and its form controls (controls): a DesignControls draws a text field (DesignTextField), a filled button (DesignButton), the color of an error, and what the controls need above them (surface). A DesignControls bean is also found below an app widget written by hand, when its isAppAbove(context) says the design's app is there.
The size of a build
This site is a Flutter web app of type widgets. Built with Flutter 3.50, its bundle went from 4.39 MB with the 0.7 starter, which carried Material and Cupertino, to 3.53 MB without a design library (gzip: 1.31 MB to 1.09 MB), and its pages are pixel-identical.
In Spring (Java)
Spring has no design libraries. What is similar is the mechanism: the app type chooses a bean by name, as a Spring Boot property chooses among auto-configured implementations; not set, it is deduced from the starters, as Spring Boot deduces the web application type from the class path (with two candidates the start fails instead of preferring one, as Spring Boot prefers servlet over reactive); and a design that must exist before any bean is a factory of the starter, as Spring Boot finds the entries of META-INF/spring.factories with SpringFactoriesLoader.