Variable & Utility Class Naming Convention
During development of Elentra JS 2.0, one of our primary goals was to streamline and consolidate all of the most commonly used tools that developers work with when developing within Elentra, in order to make development a more fluid process. Aside from the components in the Component Library, for most developers these tools are the utility classes and variables that work as building blocks to new components, views, and modules.
In Elentra JS 2.0 we have developed a consistent naming convention for all variables and utility classes, designed with IDE auto-complete in mind. Learning the pattern once means that it quickly becomes second nature for developers to drill down to the variable category and value they need, or apply a quick class that saves them from needing a custom rule. This saves time, increases productivity, and reduces redundant code bloat.
The Convention
Firstly, we prefix each class and variable with ejs- to avoid any conflicts with other libraries. Another major benefit from doing this is that all IDE auto-complete options available in the design system will be visible as soon as a developer begins typing the variable prefix. With this format, it becomes easy to begin searching for what you need.
It's important to follow a logical and consistent syntax following the prefix as well. Let’s take a typography variable as an example.
The prefix is followed by the main category for the variable, in our case, type. In the event of the category needing more than a single word, separate the words with a single dash/hyphen as with kebab-case. After the category keyword(s) come the modifiers, which are also separated word by word with single hyphens, and these are typically used to narrow down the more precise “target” of the rule. Our variable is going to be used to set the size of text copy, so we add the modifier size.
At this point, our variable or class name would look like the following:
We have the prefix, the category, and a modifier, so now what value do we want this variable to set the type size to? We have two ways of representing this in our system.
A very common standard in style libraries is to use a single hyphen to separate each word, while two hyphens in a row also has it’s own meaning - indicating that whatever comes after the double hyphens is the actual value to be applied to the target. For example, in Elentra JS 2.0, the utility class and variable names that are used to apply the "small" value for type size are:
By that same logic, if we want large text instead, we simply change the value part of the naming convention's pattern: $ejs-type-size--lg.
Now, what if you, as a developer, don’t know what type size is most appropriate for a given element? Should you guess, and pick a potentially incorrect size? Should you ask around and wait for a response?
What Elentra JS 2.0 does is (quite literally) extend that double hyphen convention. In the EJS, while two dashes indicates a value, three dashes in a row followed by a single “d” character (---d) indicates the default value for what you have set as your category and modifier.
For example, if you were designing a component and needed to add border radius to an element within it but weren't sure how many pixels it should be rounded by, you can simply type out $ejs-border-radius- then view your auto-complete suggestions. Because the results are sorted alphabetically in ascending order, and symbols preempt alphanumeric characters, the very first item at the top of the list will be the default value for border radius:
This methodology helps guide developers to the right style choices and in turn will make modules look more visually consistent across the application.
Last updated