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.

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:

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.

See also