braid-design-system
Themeable design system for the SEEK Group
MIT License
Bot releases are visible (Hide)
Published by seek-oss-ci almost 5 years ago
Published by seek-oss-ci about 5 years ago
14.0.0 (2019-10-09)
Features
BREAKING CHANGES
- Removes all leading and trailing white space around Text, Heading, Card, BulletList, Bullet, FieldLabel, FieldMessage.
- Columns 'gutter' prop has been renamed to 'space' and no longer provides default space.
- Paragraph has been removed.
See the release for more information: https://github.com/seek-oss/braid-design-system/releases/tag/v14.0.0
Rationale
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:
- Components should not own their surrounding white space.
- White space should be managed exclusively by layout components, e.g.
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.
Additional API
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.
Breaking Changes
Components with leading/trailing white space removed:
TextHeadingCard-
BulletList/Bullet FieldLabelFieldMessage
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.
Components with API Changes:
ColumnsParagraph
For details read below.
Details of changes
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>
