braid-design-system
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
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>
Published by seek-oss-ci about 5 years ago
13.0.0 (2019-09-25)
Bug Fixes
BREAKING CHANGES
- Grid & space scale flattened to single dimension and touchable space moved to top level of theme. Consumers will need to update references of
grid,spacing, andtouchableRowswithintreatfiles. Also movingseekAnztheme to4pxgrid, consumers of anz-only apps should review any manually spacing, eg.<Box paddingBottom="small" />
Details of change
Theme structure
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.
Removed rows theme utility
The 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.
Moved seekAnz to 4px grid
Previously 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.
Migration Guide
Theme structure
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.xsmalletc -
theme.spacing.column.xsmall👉theme.space.xsmalletc -
theme.spacing.touchableRows👉theme.touchableSize
Removed rows theme utility
export const minHeight = style(theme => ({
- minHeight: theme.utils.rows(12)
+ minHeight: theme.grid * 12
});
Moved seekAnz to 4px grid
For cross-brand seekAnz 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.
For single brand 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.
