May 12, 2020
In her post, Kat Allen shares with us some good practices about naming design system components. One of the first subjects I worked on at Accor Hotel was reflecting on and auditing all existing components, in order to implement a clear and transverse nomenclature for the different products.
Communication between the different members of a project is the key to long-term success, with the design-system being the central and common element to everyone. Design, development, management, marketing… 👨🎨👩💻👩💼👨💼 We can speak the same language, understand each other, and we can all focus on user experience, making sure to have a consistent design all around.
Ensuring that a common language is in place is therefore essential. A shared nomenclature between designers, product owners and developers is the starting point, so the same components, design tokens and features names can be used. This issue is all the more relevant when you have to maintain several products with different teams, such as web, Android, and iOS teams. Native component names are not always similar between the different platforms. Alignment work is therefore necessary to move forwards in the same direction.
These are precisely the challenges we had to face within the design-system team at Accor Hotel. Here are some good practices drawn from our reflections, research, and readings. They include some tips from the article by Kat Allen which I recommend you to read (additional resources are listed at the bottom of the page):
- Naming from a user's perspective, instead of from a technical or presentational view
- Apply names that make sense to team members
- Good names are precise and memorable
- Good names are intuitive and communicate the component’s purpose: the best names offer guidance or inspiration for where to use a specific pattern. Your team will be more likely to use them and contribute to the system
- Don’t hesitate to use metaphors: a metaphor from other industries can inspire a good name, make it more memorable for the team. It creates an association, something to imagine when you think of that module
- Share the same approach among the different teams (design/dev, etc.) to ensure consistency
- Collaborative naming: we can understand the purpose of a pattern better if the naming process in our team is collaborative. People from different disciplines will each view a module slightly differently. Involving people with different points of view can help make a more informed and objective decision about the purpose of a module. And once you know the purpose, coming up with a name is easier
We then started to audit our existing system, compare and clean all our different platforms’ components, as well as confront this with the developers and grow aware of existing disparities. Our discussions enabled us to identify major rules that define the basis of our nomenclature:
- Using lower-case letters only
- Use kebab-case notation for compound words (hyphen as separator)
- Using slashes for structure separation
- Never using numbers or symbols
- Never describing the colours or font types used
- Never focusing on business component role
These rules apply to our entire system. The only differences between design and development teams are the separators. We advocate following development conventions for each platform, which are not the same for the Web, Android or iOS. The important thing is to be assured to speak the same language. It doesn't really matter if compound words are separated by hyphens, periods, or a camelCase notation. As such, we opted for the use of hyphens on the design side, which corresponds to the classic CSS notation.
It’s important to understand how things work on the technical side and how components are developed, to find a common philosophy upon which our nomenclature can be built. We therefore came up wih this proposal:
element-name / variation / modifier(s) / state(s) / breakpointExamples:
button/primary/inverse/defaultbutton/secondary/large -- icon-right/hover/L
Brief explanation of this structure:
- element name: represents the name of the pattern to be named, button in our examples
- variation: represents the pattern’s main families. A component in a specific state can only belong to one variation, otherwise it is transverse and applies to all variations. In our examples we talk about primary and secondary button
- modifiers: represents whatever will slightly modify the component, such as size or one more small element for example. These modifiers can be linked by being separated by double hyphens, to adopt the convention used on the CSS side. In our second example we understand that the button is in its large state and has an icon to the right of the label
- states: represents the component’s interaction state. In CSS, this corresponds to our pseudo-class. On the design side we decided to always add default, to leave no doubt. In our second example, we understand that we are dealing with the button when hovering the mouse
- breakpoint: represents the component for a specific screen size. We use three main ones: S, M and L
We realise how important it is to work together from the design phase, in order to clear up certain technical aspects that our components will then follow. This greatly facilitates the organisation and breakdown of the different cases that we are required to design, in addition to ensuring consistency across all products.
Additional resources:
Kevin Bizien
UI Designer & Creative Developer
Want to tell me about your web project? Contact me at bonjour@kevinbizien.com and we can start talking soon!