Shape, spacing and elevation

Three small scales sit under every theme. Shape is the size of rounded corners. Spacing is a set of gaps for your own widgets. Elevation is how high a surface floats. You name a step in one place and components and widgets refer to it by name.

spring:
  flutter:
    theme:
      shape:
        medium: 16
        large: 24
        full: infinity
      elevation:
        level1: 2
      spacing:
        m: 16
        gutter: 20
      components:
        card:
          shape: large
          elevation: level1

Shape: the corner scale

shape.<token> sets a corner radius in logical pixels. Names are Material 3's and are written in kebab case.

Property Type Values Default What it does
shape.none number radius 0 Square corners
shape.extra-small number radius 4 Very small rounding: text fields, tooltips, snack bars
shape.small number radius 8 Chips
shape.medium number radius 12 Cards
shape.large number radius 16 Floating action buttons
shape.large-increased number radius 20 A step between large and extra large
shape.extra-large number radius 28 Dialogs and bottom sheets
shape.extra-large-increased number radius 32 A step above extra large
shape.extra-extra-large number radius 48 The largest rounding
shape.full number radius or infinity infinity A stadium: fully round ends. Buttons use it

Any other token name stops the start and lists these ten.

Where shape tokens are used

Your own widgets read a token with theme.shape('medium') or a $shape.medium reference. In a Material app, several components follow a token without being written (cards medium, dialogs extra-large, buttons full, ...), so changing the token changes them: the list is in component themes.

How a component refers to a shape

In a component, shape takes a token name, a radius, stadium, circle, or a map:

spring:
  flutter:
    theme:
      components:
        card:
          shape: large                      # a token
        chip:
          shape: 6                          # a radius
        filled-button:
          shape: stadium
        dialog:
          shape:
            type: continuous                # rounded, continuous, beveled, stadium, circle
            radius: extra-large
            side: { color: $colors.outline, width: 1 }

The corner types: rounded (the default), continuous (the smooth iOS curve), beveled (cut corners), stadium and circle. A radius of infinity (the full token) with the rounded type gives a stadium. A radius or border-radius property takes a token name or a number too.

Anywhere in a theme a reference can read a token, even one you did not write: $shape.extra-small is 4 unless your theme changes it. That makes a corner in a styles entry follow the theme:

spring:
  flutter:
    theme:
      styles:
        tag:
          radius: $shape.small

Elevation levels

elevation.<level> sets the height of one of the six Material 3 levels.

Property Type Values Default What it does
elevation.level0 number any number 0 Flat on the surface
elevation.level1 number any number 1 Cards, resting buttons
elevation.level2 number any number 3 Raised or scrolled app bars
elevation.level3 number any number 6 Menus and floating buttons at rest
elevation.level4 number any number 8 Higher menus, hovered floating buttons
elevation.level5 number any number 12 Dragged surfaces

Any other name stops the start and lists level0 ... level5.

Where a component property takes an elevation, you can write the level name or a number:

spring:
  flutter:
    theme:
      elevation:
        level1: 2          # every component that says level1 now uses 2
      components:
        card:
          elevation: level1
        app-bar:
          elevation: 0
          scrolled-under-elevation: level2
        filled-button:
          elevation: { default: level1, hovered: level2, pressed: level0 }

Changing a level changes only the components that name it. A component that you do not give an elevation keeps Flutter's value.

Spacing

spacing.<name> is a set of gaps for your own widgets. Material components do not read it. Any name is allowed, and the values are numbers in logical pixels.

Name Default What it is for
xs 4 The smallest gap
s 8 A small gap between related items
m 16 The normal page padding
l 24 A gap between sections
xl 32 A large gap
any other name none Your own, such as gutter: 20
spring:
  flutter:
    theme:
      spacing:
        m: 12             # change a default
        gutter: 20        # add your own
      themes:
        compact:
          spacing: { s: 4, m: 8 }

Read it in Dart

final theme = SpringTheme.of(context);
EdgeInsets.all(theme.space('m'));        // 16, or what the theme says
theme.space('gutter');                   // 20
theme.shape('large');                    // the corner radius, 16 by default
theme.elevation('level2');               // 3 by default

EdgeInsets.all(context.theme.spacing.gutter);   // typed

space, shape and elevation accept names in any spelling (extra-large, extraLarge). An unknown name throws an ArgumentError. With the generator, context.theme.spacing has a getter for each name you declare; the defaults you did not write have none, so declare s and m if you want context.theme.spacing.m. Shapes and elevations are not generated; read them with theme.shape(...) and theme.elevation(...).

See also