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

```yaml
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](../../spring-boot-starter-flutter-material/components/index.md#shapes-and-elevations).

### How a component refers to a shape

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

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

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

```yaml
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` |

```yaml
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

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

- [Properties](properties.md)
- [Component themes](../../spring-boot-starter-flutter-material/components/index.md): `shape`, `elevation` and `padding` per Material component
- [Tokens and references](tokens-and-references.md): `$spacing.m` and `$shape.large`
- [Styles and states](styles-and-states.md): numbers and insets for your own widgets
