RFC: Design System V2

[joshuaellis]

Summary

The following document outlines a minimal release for a v2 of the design-system package as well as highlighting any potential risks our breaking changes could cause that would typically go “unnoticed”. Whilst there are many changes we could make e.g. changing components to use radix-ui we’ve since seen/proven that it’s possible to rework a backwards compatible API of the new component within a single major version therefore keeping the scope of this release very small.

Motivation

As with all libraries, they mature and reach a point where breaking changes are necessary to take the library to where it needs to go. We’ve seen with the first iteration of the Design-System that not making it framework agnostic from the start was a mistake and created technical debt within the project when we began to work on the cloud project. There’s also some minor DX obstacles we can improve e.g. rem sizing always requires someone to divide by 16 which could easily be avoided. Finally, with the migration of the DS to typescript internally, we will most likely find that publishing those types will break someones project, therefore it makes more sense to hold these off for a breaking change where people will be expecting this sort of thing – there also may be bugs, but that is to be expected.

Precursors

The ability to publish breaking changes in the DS is directly impacted by the removal of aliasing the design-system in the webpack config of the CMS. Without doing this we’ll force our breaking changes on user’s plugins. Therefore, when looking at the plugin system as a whole we should aim to address the fact some plugins do not declare @strapi/design-system in their dependencies.

Proposal

Removal of v1 components

Replace all v1 components with their v2 counterparts with a well written migration guide from v1 → v2. The list of components is as follows:

• Breadcrumbs
• Link
• LinkButton
• MainNav
• Pagination
• SimpleMenu
• SubNav

Removal of direct imports

Current you can technically import a component like import { Combobox } from '@strapi/design-system/Combobox. We support this by preserving modules in the package, the downside to this is all files are treated this way so there’s no definitive way to know if a seemingly arbitrary import such as a util in a component is being used by a plugin. We’ve recently pushed the “best practice” to be importing from the root of the package and those changes have been reflected (and enforced via eslint) in the CMS repo but it’s impossible to force this into 3rd party plugins. Therefore we’ll need to write a comprehensive documentation list of what’s exported from the package for the migration guide. The only way to import components will be:

import { Combobox } from '@strapi/design-system'

Publishing of Typescript types

Currently the design-system does not publish it’s types even though it is written in Typescript, this is largely because of the assumed negative impact on the cloud project, but also because it could more than likely break plugins or rather projects that are using typescript whether they have plugins or not because the TS compiler may complain about types.

Similar to other libraries like react-router-dom and styled-components we should use a major version to signify such a huge change in our type system.

Base font-size setting

Typically speaking, we use rem of px which is a common practice in web-development because it generally works better with assistive technology e.g. zooming a webpage. However, the default rem size is 16px therefore to convert 10px to rem you’d divide 10/16 – which isn’t too hard, but more complex numbers e.g 80/16 is a little harder.

The defacto workaround for this is to set font-size: 62.5% on html & body in the Global CSS settings, this makes 1rem equivalent to 10px which results in only dividing by 10.

Prefixing props to be consumed by the styled component

Take this example of a styled-component we’ve created:

import { styled } from 'styled-components'

const Component = () => (
	<StyledButton type="button" color="#fafafa" backgroundColor="#1a1a1a" hasBorder>
		Click me!
	</StyledButton>
)

const StyledButton = styled.button`
	background: ${props => props.backgroundColor};
	color: ${props => props.color};
	border-radius: ${props => props.hasBorder ? "4px" : undefined};
`

it takes some props and in the current version of styled-components you’ll find the DOM node renders as such <button type="button">Click me!</button> note the props we’ve passed don’t reach the DOM node – hasBorder for example.

In [email protected] they will be removing “automatic prop filtering”, which is a positive thing because it wasn’t that great. This means our DOM node would render like this: <button type="button" color="#fafafa" backgroundColor="#1a1a1a hasBorder>Click Me!</button>. So soon, you’ll see this error:

react-dom.development.js:86 Warning: React does not recognize the `isExternal` 
prop on a DOM element. If you intentionally want it to appear in the DOM as a 
custom attribute, spell it as lowercase `isexternal` instead. If you 
accidentally passed it from a parent component, remove it from the DOM element.

To avoid this, styled-components recommend that all props designed to be filtered should be prefixed with $. Making this change in anything but a major version of the design-system would be considered a breaking change and moving forward, we’d be unable to use [email protected] until we’ve made this change.

SVG icons

Currently the entire system is broken, lots of icons have colours hardcoded which make them impossible to overwrite without doing the css svg > path { fill: #1a1a1a; } which is verbose and is done in far too many places. The same goes for sizes of SVGs, we have hard coded this in numerous components to the point it breaks over components or makes them more verbose because we’ve tried to be “too clever” with our code. The design-system SVG usage is very brittle.

Dot notation exports

More recently with newer APIs we’ve been exploring a dot notation name spacing system similar to radix-ui, there are however, some components that were named before this e.g. ModalBody etc. Through this breaking change, it would be good to move to consistency across the library.

Review components that should not be in the DS

An non-exhaustive list, but a starting point of discussion as to what components potentially don’t belong in the design-system.

• EmptyStateLayout
• HeaderLayout
• SubNav
• MainNav
• TwoColsLayout

Since it’s conception at v1 it’s purpose has changed, originally it was built purely for the CMS, however we’ve seen that this can extend to new products like the Cloud. Therefore, before undergoing this work, we should hold a workshop to decipher the role of the design-system package and where these components would go – e.g. would we export them from @strapi/admin or the new @strapi/plugin-kit (name TBD).

Thorough review of documentation, component testing and accessibility

If we want to be a first class product, we need a first class design-system with a solid bed of unit testing and visual regression testing. There are multiple components that do test the accessibility which shows up in any detailed testing of the CMS. The documentation is continuously criticised as being unclear and not helpful. This idea also paves the way for visual regression testing.

Make more components more composable

We constantly run into issues where the design-system is simply not flexible enough or depends on too many layers of components because it’s trying to be too DRY, this leads to incredibly overloaded props e.g startIcon & endIcon which in reality, aren’t a requirement, we could very simply just include them in the component we’re rendering at the source. More composability, more freedom, less over-eager DRY practices.

Responsive API

#1686

Risks

There are a lot of breaking changes, I would like to explore creating a codemod that would hopefully help smooth the changes for our users.

REM sizes

Because most plugins / extensions don’t redeclare the Theme from the design-system they’re subject to our GlobalStyles which could mean a plugin may look “odd” if they’re using a division of 16 to calculate their rem size – we’d need to communicate the change as a “breaking change”.