Borders separate and define. There are three strengths, each with its own token. Choose by how much definition the element needs on the page.
Soft
Dividers, and the lines between sections such as sidebars and navigation.
--color-border-soft Default
Things that need a stronger presence on the page, such as cards and inputs.
--color-border-default Strong
When those same elements need to be even more prominent.
--color-border-strong Soft
--color-border-soft is the quietest border. Use it for structure, where the line only needs to be seen when you look for it.
- Dividers
- Borders between sections, such as a sidebar and the content next to it
- Borders in navigation
Default
--color-border-default is for things that need a stronger representation on the page.
- Cards
- Inputs
Strong
--color-border-strong is for when those elements need to be even more prominent than a default border gives them.
Choosing a strength
- Start with soft for structure: dividers and the edges between sections.
- Use default for elements people read as objects or interact with, such as cards and inputs.
- Step up to strong only when a default border is not enough for the element to stand out.
- Use the same strength for the same kind of element across a page, so cards or inputs do not change weight from one place to the next.
Android
On Android the border tokens arrive as Material 3 colour roles, from checkatradeLightColorScheme() and checkatradeDarkColorScheme() in com.checkatrade.designsystem:tokens. Read them through MaterialTheme.colorScheme.
| Strength | Token | Compose role | Use it for |
|---|---|---|---|
| Soft | --color-border-soft | outlineVariant | Dividers, and subtle boundaries such as the edge of a sidebar or navigation |
| Default | --color-border-default | outline | Important boundaries, such as a card or a text field outline |
| Strong | --color-border-strong | None | Not mapped to a Compose role in the Android tokens yet |
Use outlineVariant for HorizontalDivider and section edges, and outline for the borders on cards and inputs. There is no Android role for the strong border today, so an element that needs more prominence than outline has no token to use. Raise it with Design instead of picking a colour by hand.
HorizontalDivider(color = MaterialTheme.colorScheme.outlineVariant)
Card(border = BorderStroke(1.dp, MaterialTheme.colorScheme.outline)) { /* content */ }With elevated surfaces
An elevated surface always needs a border token, with a shadow as an optional extra. See Surface hierarchy for the full rule.
Related
- Surface hierarchy
- Colours: every border token with its light and dark value
- Divider and Card