Themeable design system for the SEEK Group
MIT License
Bot releases are hidden (Show)
Published by seek-oss-ci almost 5 years ago
Published by seek-oss-ci about 5 years ago
See the release for more information: https://github.com/seek-oss/braid-design-system/releases/tag/v14.0.0
We’ve known for a long time that layout and white space management is an area where our design system work has been seriously lacking. However, we’re excited to announce that we think we’ve finally landed on a strong foundation that should solve this problem across the board going forwards. This foundation is made of two principles:
Columns
.Up to this point we’ve been working this way with most of our components, but—in hindsight—what’s been holding us back is that our Text
and Heading
components have leading white space, i.e. between the top of the container and the top of the letterforms. Luckily, we’ve figured out a method for removing this white space so that the top of text containers now touches the top of the capital letters.
This effectively means that our typography now behaves like every other component in the system, which now unlocks our ability to provide better layout primitives. So in this release, we’re also providing a Stack
component which allows you to evenly distribute white space between components.
Stack
A Stack
is responsible for interleaving white space between its immediate children. It requires a space
prop which is responsive, along with an optional dividers
prop. See the documentation for usage examples.
Text
Heading
Card
BulletList
/Bullet
FieldLabel
FieldMessage
Even though this doesn't constitute an API change, it will result in visual changes that are potentially undesirable, so it is strongly advised that you review these visual changes. Ideally, you can remediate any visual regressions by using a Stack
component. However, given the prevalence of Text
and Heading
, you also have the option to temporarily apply the _LEGACY_SPACE_
prop in order to retain the old behaviour. This prop will be deprecated in the future, so it should only be a temporary workaround.
Columns
Paragraph
For details read below.
BulletList
/Bullet
You can now configure the space between Bullet
elements responsively, e.g.:
<BulletList space={[ 'small', 'large' ]}>
<Bullet>...</Bullet>
<Bullet>...</Bullet>
</BulletList>
Note that, due to the trimming of white space above text, you may need to increase the space
on BulletList
. In addition the white space above the BulletList
would have decreased, so consider nesting it in a Stack
to control its surrounding white space.
Columns
To simplify our design language, we are now using the space
prop to consistently describe the white space between child elements. That means renaming the gutter
prop to space
, e.g.:
-<Columns gutter="small">
+<Columns space="small">
<Column>...</Column>
<Column>...</Column>
</Columns>
In addition, the space
prop is now also responsive, e.g. <Columns space={['small', 'large']}>
.
Please note that there is no longer a default space
applied between columns, which means that the space
prop is now required.
If using the collapse
prop, it's worth noting the space between columns also applies when collapsed. Previously the gutter
would not be honoured on small devices. If needed you can control the space independently by providing a responsive space value, e.g.:
-<Columns space="small" collapse>
+<Columns space={['small', 'large']} collapse>
<Column>...</Column>
<Column>...</Column>
</Columns>
Paragraph
The Paragraph
component has been removed as its primary purpose was to control white space outside of its container. With our new layout philosophy, this component is completely redundant. This can now be achieved using a Stack
, e.g.:
+<Stack space="medium">
-<Paragraph>
<Text>...</Text>
-</Paragraph>
-<Paragraph>
<Text>...</Text>
-</Paragraph>
+</Stack>
Also note that, if you require the paragraph semantics that Paragraph
provided, you can specify the component
prop on the Text
element:
-<Text>...</Text>
+<Text component="p">...</Text>
Card
Card
elements no longer include bottom margins. Instead, this should be controlled by a parent Stack
, e.g.:
+<Stack space="medium">
<Card>
...
</Card>
<Card>
...
</Card>
+</Stack>
It's also worth noting that, due to the trimming of leading space on Text
and Heading
, the internal white space is now balanced across the top and bottom of the Card
.
FieldLabel
& FieldMessage
Due to text no longer including leading or trailing white space, all form field labels and message have also had their surrounding white space removed. As always, the likely solution is to wrap these elements in a Stack
, e.g.:
+<Stack space="small">
<TextField label="Username" />
<TextField label="Password" />
+</Stack>
Published by seek-oss-ci about 5 years ago
grid
, spacing
, and touchableRows
within treat
files. Also moving seekAnz
theme to 4px
grid, consumers of anz-only apps should review any manually spacing, eg. <Box paddingBottom="small" />
The shape of a theme has changed, flattening out the grid
and space
scale to be a single definition applying to both vertical and horizontal dimensions, e.g.
{
- grid: {
- row: number
- column: number
- }
- spacing: {
- touchableRows: number
- row: SpaceScale
- column: SpaceScale
- }
+ grid: number
+ touchableSize: number
+ space: SpaceScale
}
This work will better support how white space is handled and balanced within the system. We will be leveraging this heavily in upcoming components.
rows
theme utilityThe rows
utility that was provided on the theme
has been removed as since unifying to a single grid unit on the theme the function was considered to provide more indirection than value.
seekAnz
to 4px
gridPreviously seekAnz
has utilised a 6px
grid system. This has posed problems when trying to manage white space across themes as it lacks some granularity at the smaller end of the space scale.
Moving to a 4px
grid allows us to better handle describing a layout once and more optimally rendering across themes. In order to maintain the brands spacing we have adjusted the space scale to increase in larger steps from medium
to xxlarge
.
Any rules in treat
files that consume the theme will need to be updated.
theme.grid.row
👉 theme.grid
theme.grid.column
👉 theme.grid
theme.spacing.row.xsmall
👉 theme.space.xsmall
etctheme.spacing.column.xsmall
👉 theme.space.xsmall
etctheme.spacing.touchableRows
👉 theme.touchableSize
rows
theme utilityexport const minHeight = style(theme => ({
- minHeight: theme.utils.rows(12)
+ minHeight: theme.grid * 12
});
seekAnz
to 4px
gridseekAnz
consumers:It is likely that your usage of Braid components and the APIs on Box
are consistent enough cross brand that you should not notice a change. It is recommended you review all usages of Box
or CSS rules in your treat
files that are driven by the space scale, e.g. <Box marginTop="small" />
or theme.spacing.row.small
.
seekAnz
consumers:These apps are likely the most affected as usages of the space scale are subjective and are selected based on a single theme. Reviewing usages of Box
or CSS rules in your treat
files that are driven by the space scale is highly recommended as the computed spacing will have changed and you may need to increase the space scale selected, e.g. <Box marginTop="small" />
or theme.spacing.row.small
.