
# 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](../spring-boot-starter-flutter-material/index.md) and [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md).

## 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.

```yaml
# 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 `SpringAppFactory` bean 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:

```yaml
# lib/resources/application.yml
spring.flutter.app.type: material
```

```yaml
# 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 under `colors.*` over it. `SpringTheme.of(context).colorScheme` has 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 a `MaterialApp` gives, 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`, `content` and `none`. 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:

```text
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.

```dart
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:

```dart
// 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](../spring-boot-dart/auto-configuration.md) 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:

```dart
@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.

```dart
@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

- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [Moving to 0.8](moving-to-0-8.md)
- [Themes](themes/index.md)
- [The app widget](app-widget.md)
