The main notion of this study is, that there are two layers underlying both the developer-centric vocabulary — when you are learning it — and to-be-established naming convention — when structuring and setting it up for your project.
Introduction
Throughout my design-travels, I came into conclusion, that there are two layers underlying both the developer-centric vocabulary — when you are learning it — and to-be-established naming convention — when structuring and setting it up for your project.
First layer constitutes a semantic representation of every object used in the user interface. In other words, how to name each thing rendered by the browser.
Second layer is a system or a methodology that determines how to combine singular names and other attributes into compound names in order to make their position, use, function and purpose — all in a meaningful sequence — clear to all participants of a design-development process.
It’s important to underline the fact, that vocabulary, and as a byproduct, the naming conventions are flexible as well as fluid, both in time and space, like all languages are.
Thus one could never state that a particular naming convention is final or the best one. Choosing the right words and definitions, like in any conversation, is inherently circumstantial. Meaning that, both the needs and objectives of a project determines naming convention. Yet, it doesn’t necessarily mean that there are no standards nor best practices.
Purpose of this section is to present both above-mentioned standards and best practices, but also to make them digestible for non-coders — designers.
Naming Convention’s Principles
Before we dive into layers, I’ve highlighted above, let’s first go through important traits of any naming convention should have, and the rules that naming convention should obey, in order to be A-OK.
So firstly, naming convention should enhance following areas of design-development process:
- Collaboration and Communication,
- Management and Scalability,
- Understanding and Review,
- On-boarding and Delivery Time.
The list seems to be a bit synthetic without context, so let me provide it.
Software development is not a single person’s job, there is always a team effort involved. Thus things have to be named clearly so everyone understands what they mean (Collaboration and Communication).
Design-development process is a lengthy and complex process, the easier it is to be managed, the better. Same thing goes for projects growth. Moreover, there is nothing worse, than inheriting a project after someone who did not think through, how it will work in bigger scale (Management and Scalability).
If all words have equal purposeful meaning, figuring out what author wanted to convey with his/her code/design is tremendously simplified. The same goes for any review process (Understanding and Review).
For onboarding anyone, naming conventions allow to grasp the inners of code/design by simply looking at the names of elements, components or tokens. The same way, if you only didn’t have to lose valuable resources on grasping the inners of the code/design, you’d deliver what is expected of you much faster (On-boarding and Delivery Time).
Secondly, each naming convention should obey these set of rules:
- Being self-explanatory. Each name should contain in itself the exact explanation of its contents, in other words, it should be self-documentable;
- Being searchable. Each name should be search-friendly. So based in some kind of standard poll of words/names — Like this one: UI Elements. Moreover, the best standard is to stick to one popular language, like English. You just never know when your project will be ‘moved’ to other side of the globe, and you’ll have to collaborate with completely new people from different cultures with different languages native to them;
- Being as short as possible. It doesn’t mean that there is a limit on lengthiness of a name, but having a CSS class with 50 characters might be overwhelming, and simply hinder performance;
- Being consistent. It means both consistent on use of the same name for the same thing, but also being consistent on how each compound name is being created, so a sequence of names and attributes happens in one meaningful order.
Once we cleared the theoretical premises of the traits and rules each naming convention should have and obey, now we can start diving into more practical matters.
Defining the names
The semantic representation of the objects rendered by the browser has been listed separetly. You’ll find it in UI Crux—under UI Elements. There is no point in copying everything here.
You’ll find there a finite list of UI Elements (UI Components) alongside their names. I’ve put extra effort in presenting the ‘most standard’ names through an extensive research.
List has been drafted with Single Purpose Principle in mind — UI Element should do one thing, and one thing only.
Yet, it has to be pointed out that in few less popular frameworks some names may differ from what I’ve listed out. At the same time, when two or more names were equally popular, I placed all of them in my list highlighting the alternatives.
Categorization of UI Elements and Patterns
Traditionally, web application UIs are built using templates or HTML directives. These templates dictate the full set of abstractions that you are allowed to use building UI.
The new approach adopted by many popular Desing System and Frameworks, like for example ReactJS or Bootstrap, addresses building user interfaces differently. Simply by breaking UIs into components.
Main reason for this change is based in the fact, that components by their nature are:
- Highly composable,
- Extendible and
- Testable.
This makes a lot of sense for highly agile and collaborative environments. Where each component can be developed in separation.
Beyond Components
Modern frontend applications are composed of more elements then only components. There are:
- Layouts,
- Color,
- Typography,
- Spacing,
- And much more UI Patterns and Elements.
Defining the structure
Once your application will start to grow, and alonside with it your UI, you’ll come to point where without proper structure you might get lost, both in code as well as you design artboards.
That’s why it makes sense to consider dividing UI elements and patterns into categories or sections.
The three major approaches:
- One list, no categories (in alphabetical order)
- Division based on function (eg. content, forms, inputs, navigations, layouts etc.)
- Division based on complexity (eg. elements, components, modules, etc.)
All of them have particular pros and cons. And I know, that I’m only scratching the surface here, but I do not find, describing said pros and cons, practical.
Instead, let me show you what is my curated approach, that takes plentiful from most popular Design Systems and Frameworks out there.
Creating Sections and Categories
First division happens on the highest level, and the sections are as follows:
- Foundations (color, typography, spacing, layouts, icons, etc.)
- Tokens (color, border, background, interaction, elevation, etc.)
- Components (will be analyzed separately below)
- Patterns (loading, messages, common actions, search, truncation, login, etc.)
Now, let me provide context and an explanation based on what, why I’ve crafted such division.
- Foundations are grouped together based on their fundamentality for the UI. Color, typography, spacing, layouts, icons, and alike are like glue that holds entire UI together.
- Tokens are placed as a separate group on equal terms and other sections, because they are way of providing single source of truth to name and store design decisions.
- Components are the reusable building blocks of UI.
- Patterns are reusable combinations of components that solve common user problems. They should help users in achieving their goals and ensure consistency across experiences.
OK, now let’s dive into crème de la crème — the components. It might seem controversial, but hear me out.
I do not create any categories for components, but I do group ones, that are inherently interlaced together. So it’s a mixture of (1) one big list with pinch of (2) division based on function.
Let me present it on an example. I’ll use CSS syntax for visual purposes, and because of the monospaced typography:
.accordion .avatar > .avatar-item > .avatar-status > .avatar-group .badge .blackquote .breadcrumbs .button > .button-group .caption .card .carousel ...
Arguments against too detailed or too specific divisions
Let me give reasoning why overdoing categories and sections, might get in your way, while crafting or using a Design System, Component Library or simply creating a structure for UI.
Arguments against division based on function:
- If you divide your components into couple of categories, you’ll come to a point where you’ll have full-blown debates on whether you should put a component into this or other category. You can debate it internally or with your teammates. I guarantee, that there are good arguments for each placement of any component. Belive me, I’ve been there.
- There are components that serve 2 or more function at the same time. Once you place a component in one of functional categories, someone else might get confused and not find it at all. Simply becasue he/she figures that another function of this particualr component is dominant, and forgot completly about this particular function.
Arguments against division based on complexity:
- Dividing all UI Components into singular-purpose elements, components, grouped components, modules, will trigger discussion, which degree of complexity a particular component has.
- Problems with vocabulary. The best example for it is, the atomic design nomenclature. In the end, no one knows for sure which component, module is an atom, a molecule or an organism. Why would you overcomplicate purposefully your design-development process with unecessary misunderstandings.
Having one alpabetically ordered list, with a very very limited grouping, as showcased above, solves all of these issues.
CSS Methodologies
There are many methodologies how to name objects in HTML/CSS, yet there are couple that are most commonly used within the devs community.
I’ll be showcasing the following triad:
- BEM: Block Element Modifier
- RSCSS: Reasonable System for CSS
- SMACSS: Scalable and Modular Architecture for CSS
All of the above methodologies are trying to structurize the code in order to fulfill all of the traits and rules I’ve described hereinabove.
Yet, If you’d ask me, which methodology I use the most? I’d have to say, that RSCSS is hands down biggest contributor to my daily deliveries.
And there is two arguments for that:
- Almost all frameworks, React, Polymer, Angular, Vue, etc. or even Bootstrap, center software development on components, and RSCSS main premise is to consider each piece of UI as an individual component.
- BEM makes the CSS code super clean, but with scale the HTML markup becomes unbearable. RSCSS is trying to balance out both things — CSS clarity and HTML markup simplicity.
Important sidenote:
Before we go deeper, I’d like to point out, that this study is directed to non-coders — designers. Hence it is not a complete breakdown of all knowledge necessary to implement any CSS methodology in engineer’s daily work.
Though, if you’re interested in learning more underneath each section, you’ll find links to solid resources, that should give you 360 degree view on each methodology.
Explore the CSS Methodologies
For designers?
So why should a designer bother with CSS, BEM, self-documenting names, methodologies, shared vocabulary and other concepts I’ve just mentioned?
A simple explanation is that, by knowing how all these structures and concepts, designers can adjust their UI Kits, mockups, designs accordingly and reduce the amount of issues that might arise between design and its implementation. And as mentioned in the introduction part, way at the top, to enhance functioning of these areas:
- Collaboration and Communication,
- Management and Scalability,
- Understanding and Review,
- On-boarding and Delivery Speed.
In other words, if a design follows guidelines on naming conventions, it will be an invaluable advantage for communication, management, scalability, review and on-boarding new people to develop and deliver fast and error-free, for the benefit of us all.
No one is always right
I use feedback to improve UI Crux Platform. If you noticed a mistake, please report it.
